Contracts

birth-cutover-ordering.md

Contract: Birth-Cutover Seed Ordering

Inputs

  • PRIMARY mission directory containing legacy WP artifacts and meta.json.
  • Canonical status directory containing transition and annotation events.
  • Deterministic mission/WP/field seed identity.

Invariants

1. For each WP with existing history, every newly-created migration transition seed key is strictly less than every existing transition key for that WP. 2. For each WP with existing history, every newly-created migration annotation seed key is strictly less than every existing annotation key for that WP. 3. A cutover never changes the WP's pre-cutover canonical lane. 4. A cutover never replaces a later legitimate runtime-slot value. 5. Each non-null legacy shell_pid, shell_pid_created_at, and agent value is present in the raw seed evidence. It equals the reduced snapshot when no later legitimate writer owns that slot; otherwise the later legitimate value wins. 6. New seed IDs remain deterministic. An old colliding seed is repaired by a distinct deterministic compatibility identity that restores the state reduced with migration seeds excluded. Neither path rewrites an event or appends a duplicate on a second invocation. 7. Verification failure prevents status_phase from flipping.

Caller Coverage

The same contract applies to:

  • accept commit mode;
  • merge birth cutover;
  • upgrade migration;
  • migrate backfill-runtime-state single mission;
  • migrate backfill-runtime-state corpus mode.

accept --no-commit and diagnose validate convergence only; they do not exercise the stamp.

Already-Seeded Compatibility

An event stream containing the pre-fix seed payload and its original terminal or runtime history is the mandatory compatibility fixture. Re-appending the seed ID is not a repair: reducer deduplication retains the first row. The implementation must append a separately namespaced deterministic repair event only when the old seed currently corrupts a lane or slot. Its payload restores the value obtained by reducing legitimate history with migration seeds excluded. A legitimate writer later than the old seed remains authoritative. Verification accepts the historical seed only together with the converged repair witness, and a byte-for-byte rerun appends nothing.

Failure Contract

Unreadable or lower-bound timestamps, corrupt event streams, an unprovable strict floor, or a missing claim-slot/repair witness fail closed through existing cutover result/error surfaces before any partial append or status_phase flip. No caller may bypass the guard.

dead-code-verdict.md

Contract: Dead-Code Review Verdict

Supported Analysis

The gate must:

1. obtain the baseline-to-HEAD change set without assuming a src/ root; 2. classify whether the changed source language/layout is supported; 3. extract added public Python def and class symbols when supported; 4. search Python files with a platform-neutral implementation; 5. preserve existing caller filtering and relative-path comparison semantics.

Verdicts

Clean

Allowed only after discovery and scanning complete successfully over a non-vacuous supported denominator. Output may state 0 unreferenced public symbols.

Findings

One finding per unreferenced public symbol, using the existing dead_code finding shape.

Undeterminable

Required when:

  • the diff command fails;
  • the source layout/language is unsupported;
  • the scanner cannot establish which files it examined;
  • filesystem decoding or traversal prevents a complete scan.

The finding must carry a stable diagnostic code, a reason, and remediation. Output must not contain the clean-zero message.

Portability Regression Contract

A fast test injects FileNotFoundError at the subprocess boundary and asserts a verdict rather than a traceback. It must not patch shutil.which. A separate non-Python/non-src fixture asserts an undeterminable result rather than a clean pass.

Compatibility Contract

On the current POSIX, src/-rooted Python repository, the pre/post reported symbol set is identical. The existing substring exclusion ("test" not in path) remains unchanged.