pi-context-compiler

Deterministic, fixture-only context compiler mechanics for auditing semantic projection and Pi host capability gaps.

[!WARNING] Experimental and capability-blocked. On the audited Pi 0.83.0 host, Phase 0 is NO_GO. The extension is status-only: it does not mediate live provider requests and does not emulate the full harness. Do not use this package as a production privacy or security boundary.

Version 0.2.0 is a verifiability increment only: deterministic artifact/report verification, passive Pi host negative preflight, and formatting/release gates. It does not introduce corpus-v2 or change the corpus-v1 / phase-minus-one.v1 protocol, add a live harness, or upgrade the evidence from fixture/static-audit scope.

Why choose this?

pi-context-compiler is a small, inspectable implementation of the deterministic mechanics behind a proposed Context Compiler Harness. It is useful when you need to:

• audit how semantic IR, source mappings, residuals, proofs, budgets, and egress checks fit together;
• replay a frozen synthetic corpus without provider calls or private file reads;
• inspect the Pi host capabilities required before any live compiled path could be considered; and
• keep capability and evidence claims explicit instead of making a partial host integration look production-ready.

It is not a model router, a safety-policy bypass, a live context redactor, or a replacement for Pi's native agent loop.

Features

• Event-sourced deterministic core with canonical serialization and digests.
• Typed semantic IR for symbols, statements, source snapshots, residuals, taint, findings, proofs, certificates, coverage, and provider-chain checks.
• Frozen Phase -1 corpus with 12 latent tasks across three fixture surface labels: biological, scientific, and network-defense.
• Scripted fixture replay with zero live model calls and a report that distinguishes mechanical fixture results from empirical evidence.
• Deterministic packet rendering, replay checks, residual conservation, unsupported-path abstention, laundering guards, and proof/lift mechanics.
• A fail-closed Pi 0.83.0 capability report for required host capabilities H1–H10.
• A bounded, read-only Pi status command and status tool; no live request mediation.
• verify, which checks strict report schema/honesty, the unkeyed reportDigest self-digest, the versioned semantic commitment compiled in-band in the same package/build, two same-build deterministic recomputations, and exact packaged JSON/Markdown freshness. These checks are same-build/in-band integrity only — not signatures, MACs, authenticity or provenance proofs, external trust roots, independent reproduction, truth checks, or empirical evidence.
• preflight, a passive negative Pi host check that first runs unverified executable --version, then makes four RPC requests only against a strict ordered eight-record schema/shape and remains capability-blocked; it does not perform a Phase 0 proof.
• A small CLI and typed package exports for embedding the core or evaluator.

Current status and evidence

Phase 0: NO_GO

Pi 0.83.0 does not expose the complete native host contract required by the design. The required H1–H10 capabilities remain missing under the fail-closed audit, including correlated native phase turns, per-turn model and tool snapshots, fail-closed materialized-request mediation, host-authenticated phase metadata, usage/checkpoint binding, and provider-attested response identity.

The installable extension therefore exposes status only:

• /ctx-status displays the public capability report when Pi has a usable UI.
• ctx_capability_status returns the same bounded, read-only status as a tool.
• Session startup and model selection may update bounded status indicators; the selected model is observed, not attested.

The 0.2.0 preflight command is deliberately narrower than a harness probe. It first runs the caller-selected or default Pi binary's unverified executable --version, then uses an isolated HOME, temporary directory, working directory, and configuration surface to send only four passive RPC requests: get_state, get_session_stats, get_messages, and get_commands. Production acceptance is a strict ordered eight-record schema/shape with fixed lifecycle and zero-activity fields and bounded audited variants (for example session and UI request ids within schema bounds): startup status/notification, those four responses (including /ctx-status registration and zero activity-bearing state), and the two status-clear records. It is not a single normalized byte-exact transcript; exact normalized transcript matching is reserved for the independent smoke:pi check. Hosts other than the audited 0.83.0 intentionally fail closed by design. It sends no prompt or provider request. The default binary may resolve package-local or ambient PATH and is always unverified; the version is only an executable self-report. Runner constants such as promptSent=false and the passive-request set are fixed by the preflight runner; transcriptValid and activity observation are derived from the validated transcript. Provider-call attestation is unavailable, and H1–H10 executable proof is not performed. A passing preflight remains NO_GO and status-only.

verify is a same-build deterministic release-integrity check. It validates strict schema and honesty fields, recomputes the unkeyed reportDigest self-digest and pinned versioned semantic commitment compiled in-band in the same package/build, runs the scripted report twice through that same build, and compares the packaged JSON and Markdown byte-for-byte with fresh output. Double recomputation detects deterministic artifact drift; it is not an external trust root or independent reproduction. Those hashes and commitments establish local identity/integrity of the checked bytes only; they are not signatures, MACs, authenticity or provenance, truth, or empirical claims.

There is no /ctx on, no live compiled mode, no request-blocking middleware, and no full-harness emulation through background sessions, widgets, custom messages, stream wrappers, or virtual providers.

Phase -1: fixture replay only

Phase -1 is a zero-live-call deterministic fixture replay. It uses explicit fixture labels and a scripted reasoner backend; it does not call a provider, read private source material, or validate a native Pi session. Its report deliberately sets:

empirical=false
productReady=false
overallDecision=inconclusive
hostLifecycleValidated=false
nativePiSessionValidated=false
metrics.actualLiveCalls=0

The fixture mechanics are useful for auditing implementation behavior, but they are not selected-model evidence. Design and empirical gates are not run as product readiness evidence in this phase. In particular, fixture determinism must not be renamed as stochastic stability, semantic preservation, non-interference, or host compatibility.

See context-compiler-harness-design.md for the proposed architecture (written in Chinese), docs/pi-capability-matrix.md for the host audit, and docs/phase-minus-one-gates.md for the preregistered fixture protocol and its limitations.

Installation

Requires Node.js 22 or newer.

Global CLI

npm install --global pi-context-compiler

Pi package

Install the pinned package in Pi:

pi install npm:pi-context-compiler@0.2.0

For a temporary extension load:

pi -e npm:pi-context-compiler@0.2.0

The Pi package remains capability-blocked on the audited Pi 0.83.0 host. Installing it does not enable a live compiler or alter provider dispatch.

Quick start

Run the capability report:

pi-context-compiler capabilities

Verify the packaged deterministic evaluation artifacts:

pi-context-compiler verify
pi-context-compiler verify --json

Run the passive, capability-blocked Pi preflight (use --pi to select a binary):

pi-context-compiler preflight
pi-context-compiler preflight --json --pi /path/to/pi

Print the scripted evaluation as JSON:

pi-context-compiler evaluate --json

Inspect the planned fixture workload without executing it:

pi-context-compiler plan --json

The evaluator's successful process exit means that the fixture replay completed; it does not mean that overallDecision is go or that the package is ready for production.

After installing the Pi package, use /ctx-status to inspect the extension's status-only report. No command starts a live compiled run.

CLI

The executable is pi-context-compiler.

Command	Default output	Purpose
capabilities	text	Print the public Pi capability report; use --json for machine-readable output.
plan	JSON	Print the Phase -1 scripted plan; use --json explicitly in automation.
evaluate	Markdown	Run the deterministic fixture replay; use --json for the report object.
verify [--json]	text	Verify report schema/honesty, same-build deterministic recomputation, in-band semantic commitment, and packaged JSON/Markdown freshness. Same-build/in-band integrity only — not a signature, authenticity attestation, external trust root, independent reproduction, or empirical-evidence check.
preflight [--json] [--pi <path>]	text	Run the passive Pi 0.83.0 negative preflight against a strict ordered eight-record schema/shape; non-0.83.0 hosts fail closed by design; a pass remains status-only NO_GO.
help	text	Show CLI usage.

Examples:

pi-context-compiler capabilities --json
pi-context-compiler plan --json
pi-context-compiler evaluate --json
pi-context-compiler evaluate --markdown
pi-context-compiler verify --json
pi-context-compiler preflight --json --pi /path/to/pi

evaluate always reports metrics.actualLiveCalls: 0, selectedModelGate.liveCalls: 0, and productReady: false. It exits zero when the fixture evaluation runs successfully, including when the report's overall decision is inconclusive. verify exits zero only when both same-build deterministic recomputations and both packaged artifacts match; its success is same-build/in-band integrity only — not a signature, authenticity/provenance attestation, external trust root, independent reproduction, truth result, or empirical evidence. preflight exits zero only when the strict ordered eight-record schema/shape validates for audited 0.83.0 (other versions fail closed by design); its report still says phase0Decision: "NO_GO", liveCompiledPathEligible: false, and h1ThroughH10ExecutableProof: "not-performed".

Pi extension

The package manifest points Pi at dist/extension.js. The production registration uses Pi's ExtensionAPI and creates only a capability report, /ctx-status, the bounded ctx_capability_status status tool, and status lifecycle handlers. The status tool returns a deliberately small public projection rather than the full audit matrix.

The extension does not:

• intercept or rewrite live provider requests;
• claim that before_provider_request is fail-closed mediation;
• start nested or background agent sessions;
• register a virtual model or provider;
• switch the user's selected model or active tools per phase;
• replace terminal answers, stream events, or native Pi lifecycle metadata; or
• turn custom entries, widgets, or messages into authenticated phase events.

Architecture

The implementation is intentionally split into three layers:

source snapshots + semantic IR + event reducer
                    │
                    ▼
        deterministic core mechanics
                    │
                    ├── frozen corpus and evaluation plan
                    │
                    └── scripted fixture pipeline and report
                                      │
                                      ▼
                         capability-blocked Pi status extension

Core

The root package exports canonical data and the core building blocks: events, budgets, reducers, event stores, source snapshots, semantic IR, admission and mode triage, model identity, cache lineage, coverage, certificates, packets, provider-chain validation, taint/egress checks, findings, proofs, lifts, and laundering guards. These are deterministic mechanics; they do not provide a live provider gateway.

Evaluation

The evaluator freezes a versioned corpus, plans scripted executions, materializes ideal IR, renders packets, applies registered mutations and ablations, replays fixture events, and builds a report. Public artifacts exclude private raw source text. The report keeps fixture labels explicit and records which evidence remains not-run.

Extension boundary

The extension is a capability gate, not a harness implementation. Its static audit uses Pi 0.83.0 facts and fails closed. A possible synthetic GO from a caller supplied probe is unverified pure calculation and is not accepted as host proof by the production registration path.

Trust model and limitations

The trusted mechanics are deterministic canonicalization, validation, reducers, packet rendering, proof/lift checks, and report construction. The compiler and any future model-backed reasoner are not automatically trusted merely because an artifact contains a digest, confidence value, coverage claim, or provenance field.

Important limitations:

• Synthetic ground truth is finite and hand-authored; it cannot establish open-world semantic preservation.
• Egress checks over labels, fragments, digests, or bytes do not detect paraphrase, encoding, or side-channel leakage.
• Coverage demonstrates correspondence, not truth; proof checking demonstrates rule closure and provenance, not truth.
• Scripted stability is not live stochastic stability and selected-model identity is not exercised.
• The Pi capability report is a static source/API/runtime-code capability audit, not an executable Phase 0 probe; passive preflight is a separate negative check.
• preflight is a passive negative preflight: it first runs unverified executable --version, then validates an isolated host against a strict ordered eight-record schema/shape with fixed lifecycle/zero-activity fields and bounded audited variants. It does not authenticate the caller-selected or default binary, perform normalized exact-transcript matching (reserved for smoke:pi), attest provider activity, or prove H1–H10. Non-0.83.0 hosts fail closed by design. An actual executable Phase 0 probe would require native host operations and authenticated evidence that this package cannot obtain.
• Hashes and semantic commitments establish checked-byte identity/integrity compiled in-band in the same package/build, not authenticity, provenance, an external trust root, independent reproduction, truth, or empirical evidence.
• Missing host capabilities must be solved by the host or an appropriate upstream API; this package intentionally does not simulate them.

For the security boundary and vulnerability-reporting process, read SECURITY.md. The package is for auditing mechanics and capability gaps, not production privacy or security.

API exports

The package is ESM and publishes declaration files alongside its built JavaScript. The supported export paths are:

import { JsonlEventStore, materializeIdealIr } from "pi-context-compiler";
import { runScriptedEvaluation, planEvaluation } from "pi-context-compiler/eval";
import { registerContextCompilerExtension } from "pi-context-compiler/extension";

• pi-context-compiler — root core exports, plus the evaluator's public exports re-exported from the root entry point.
• pi-context-compiler/eval — corpus, planning, scripted pipeline, report, and evaluator types/helpers.
• pi-context-compiler/extension — capability report, status formatting, Pi registration, and extension adapter types.
• pi-context-compiler/core/* — individual core modules for focused imports.
• pi-context-compiler/cli — CLI entry and testable main/I/O types.

The exact public symbols are defined by the declaration files generated by the build; the export map in package.json is authoritative.

Development

Clone the repository, install exact dependencies, and use the scripts declared in package.json:

npm ci
npm run typecheck
npm test
npm run build
npm run --silent eval:fixture -- --json
npm run check
npm run release:check

Core deterministic verification:

npm run check

Complete release gate:

npm run release:check

eval:fixture builds and runs the offline scripted corpus (--silent keeps JSON stdout machine-readable). check is the core deterministic verification path: typechecking, direct Biome checks, tests, the build, and artifact verification. release:check is the complete release gate: check, preflight:pi, smoke:pi, smoke:package, and audit:prod. preflight:pi runs the passive Pi 0.83.0 preflight against the repository-installed/audited binary (non-0.83.0 hosts fail closed by design). smoke:pi independently exact-matches the startup/registration/raw passive eight-record transcript; it does not invoke /ctx-status and makes no model call. smoke:package packs the artifact and exercises its installed CLI and extension boundary, including verification and preflight. audit:prod runs the production dependency audit. The CI workflow runs npm ci --ignore-scripts, npm run check, npm run audit:prod, Node 24 preflight:pi, and both smoke tests on Node 24 (with Node 22 also covered by the verification matrix).

Other package scripts are prepack and prepublishOnly (release:check); npm invokes these during packing and publishing respectively. No development command implies live model access.

Contributing

Issues and pull requests are welcome. Keep changes small, deterministic, and explicit about evidence boundaries. New fixture tasks, gates, or protocol changes should be preregistered and versioned rather than tuned after observing results. Do not add a workaround that makes a missing Pi capability look available.

Before opening a pull request:

1. run npm run check for core deterministic verification;
2. run npm run release:check for the complete release gate when touching host, packaging, or publish paths; and
3. describe whether evidence is fixture-only, synthetic, static-audit, or live.

Please do not include secrets, private source material, credentials, or exploit details in public issues.

Security

Report vulnerabilities through GitHub private vulnerability reporting, not a public issue. See SECURITY.md for supported versions, response expectations, and the current security boundary.

License

MIT © 2025–2026 ZhenHuangLab contributors.