Skip to content

feat(interlock): harden Pitot interface + client readiness for external builders - #261

Merged
bigboateng merged 1 commit into
mainfrom
codex/interlock-hardening
Jul 31, 2026
Merged

feat(interlock): harden Pitot interface + client readiness for external builders#261
bigboateng merged 1 commit into
mainfrom
codex/interlock-hardening

Conversation

@bigboateng

Copy link
Copy Markdown
Contributor

What & why

Mirrors the Pitot readiness work (#260) for Interlock. A full Locus analysis
of the Interlock core and the Pitot↔Interlock interface certified there are no
correctness holes
— the frontier was engineering readiness, not enforcement bugs.
This PR is feature-preserving hardening: the engine still decides, the broker
still performs, every path still fails closed. What changes is that the two ways an
external builder got silently stuck are now loudly diagnosed.

Locus certification (model-scoped, fidelity-validated)

Two SystemModels, every evidence ref resolved against the worktree (claims are
supported / model-scoped, not theorem-only):

  • adapter-collapse (verification.safety-reachability, anchored to
    integrations/pitot/adapter/adapter.go): the engine 4-outcome → Pitot 2-outcome
    collapse. Verdict reachable: false — a non-allow outcome, an empty/undecodable
    payload, or any unknown/future outcome surfacing as wire-allow is unreachable; the
    default: branch fails unknowns closed. → interface soundness certified.
  • broker-authority (control.supervisory-rw): the "authority, not interception"
    guarantee. Verdict controllable: true, accepted: true — the forbidden
    uncontrollable events (agent_write_artifact, broker_promote_without_allow) have
    no declared transition. → core guarantee certified.
  • frontier --rank over both: no correctness action available → the honest headline
    is readiness, not correctness.

Advisory/model-scoped until obligations discharge against fresh tests; assumptions
(strict-mode isolation precondition; broker I/O fail-closed and engine
first-match/default-deny covered by their own tests) recorded as model unknowns.

Changes (all feature-preserving)

Interface

  • Unify the Pitot request kind on interlock.effect across the client constant,
    SPEC, integration README, and validate.sh. A kind/config mismatch made Pitot find
    no controller and deny every request silently; kind_consistency_test.go now
    fails the build if the constant, README, or validate.sh drift apart.
  • Schema-skew diagnostic: adapter.Evaluate distinguishes a newer client's
    unknown field from a corrupt payload and from a policy deny — same fail-closed
    behavior, message names the controller protocol. Covered by adapter_test.go.

Client readiness

  • Version-lockstep gate in check-clients.sh (always-on, no toolchain): the
    TypeScript and Python clients must share one release version, so a consumer can
    never pin mismatched clients against one controller.

Public README

  • New Build on Interlock section (language clients + run-a-decision-over-Pitot
    quickstart with the canonical kind and the drift-guard note) and a new
    CONTRIBUTING.md (six-point client bar + the no-foreign-enforcement guardrail).

Verification

  • Integration go test ./... (incl. new schema-skew + kind-consistency tests).
  • Integration real-pitot E2E round-trip: allow / deny / require→deny, Pitot tree
    asserted unmodified.
  • scripts/validate.sh full chain: tests, -race, purity boundary, IR determinism,
    CGO_ENABLED=0 build, CLI lifecycle, README proof-drift, and check-clients.sh
    incl. the new version gate — all green.
  • Release note added under interlock-distribution/release-notes/.

Separate stacked PR to follow on labs/15-pitot for the Pitot-SDK readiness items
(conformance CI, Rust CI, Java/C# not-yet-runnable labeling, version-gate, per-SDK
quickstarts).

…al builders

Feature-preserving hardening of the Interlock↔Pitot decision-transport interface
and the language clients, so outside builders can start testing. The enforcement
guarantee is unchanged: the engine decides, the broker performs, every path fails
closed. Two ways a newcomer got *silently* stuck are now *loudly* diagnosed, and
Locus certified there are no correctness holes to fix — the frontier was readiness.

Interface:
- Unify on one canonical Pitot request kind (interlock.effect) across the client
  constant, SPEC, integration README, and validate.sh. A kind/config mismatch made
  Pitot find no controller and deny every request silently; kind_consistency_test.go
  now fails the build if the constant, README, or validate.sh drift apart.
- adapter.Evaluate distinguishes schema skew (a newer client's unknown field) from a
  corrupt payload and from a policy deny — same fail-closed behavior, diagnosable
  message naming the controller protocol. Covered by adapter_test.go.

Client readiness:
- check-clients.sh gains an always-on version-lockstep gate: the TypeScript and
  Python clients must share one release version (static check, no toolchain), so a
  consumer can never pin mismatched clients against one controller.

Public README:
- New "Build on Interlock" section (language clients + run-a-decision-over-Pitot
  quickstart with the canonical kind and the drift-guard note) and a CONTRIBUTING.md
  (six-point client bar + the no-foreign-enforcement guardrail).

Verified: integration go test + real-pitot E2E round-trip (allow/deny/require→deny),
and scripts/validate.sh full chain (tests, -race, purity boundary, IR determinism,
CGO_ENABLED=0 build, CLI lifecycle, README proof-drift, check-clients incl. the new
version gate) — all green. Release note added under interlock-distribution.

Disclosure-Reviewed: reviewed — public-safe only, private facet kept out of this commit
@bigboateng
bigboateng merged commit dcf7cad into main Jul 31, 2026
5 checks passed
@bigboateng
bigboateng deleted the codex/interlock-hardening branch July 31, 2026 16:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant