Compatibility With Python

Compatibility With Python

The Python project is canonical.

• Canonical repository: https://github.com/kadubon/percolation-inversion-compiler
• Canonical wiki: https://github.com/kadubon/percolation-inversion-compiler/wiki
• Python package: percolation-inversion-compiler==0.9.0

The TypeScript package is the npm and Node.js compatibility port.

What Compatibility Means

PIC-TS aims to preserve the public behavior that matters to agents:

• JSON input and output meaning;
• schema files;
• conformance fixtures;
• CLI command families;
• status fields such as accepted, workflow_usable, operationally_usable, and settled;
• residual, blocker, and missing obligation fields;
• phase planner output;
• CCR task and residual JSONL handoff meaning;
• TRC operation-readiness meaning;
• Phase Ecology Lab public records;
• safety boundary;
• non-promotion rules.

What It Does Not Mean

The TypeScript package is not a line-by-line rewrite of the Python internals.

It should not invent new semantics on the TypeScript side. It should not claim stronger settlement than the canonical Python model.

Store Difference

Python uses a SQLite-backed Phase Ecology Lab store.

PIC-TS uses a local JSON/JSONL store so npm consumers can run the lab without Python. The store implementation is different, but the public JSON safety boundary remains the same: candidate-only data is not promoted, residual work stays visible, and execution paths are not executed.

Exact And Diagnostic Compatibility

• Snapshot commands have exact Python v0.5.0 fixture parity in fixtures/python_v050_snapshots.
• v0.5.0 Phase Lab and subsystem routes use public-shape and safety compatibility fixtures in fixtures/python_v050_cli.
• v0.9.0 CCR interop, token reports, TRC operation-gate routes, observation reports, performance reports, and cache reports track Python public behavior through pic-ts token, pic-ts phase --emit, pic-ts bit, pic-ts sqot, pic-ts trc, pic-ts performance, and pic-ts cache.
• Python-only heavy routes are exposed only as safe diagnostic compatibility routes when present.

Python-Only Heavy Routes

Some routes in the broader Python project depend on Python-only services, local stores, external verifier authority, or heavy runtime behavior.

In the npm package, these are handled as safe diagnostic compatibility routes when exposed. They fail closed and preserve:

• operationally_usable=false;
• settled=false;
• execution_authority_granted=false;
• missing obligations;
• residual ledgers;
• blockers.

CLI Name Difference

Python uses pic.

This npm package recommends pic-ts to avoid command ambiguity. The npm package also provides pic as a compatibility alias.