Contracts

dead-code-dynamic-access.md

Contract — Dead-code gate: first-party dynamic-access awareness (IC-01 / FR-001, FR-002)

Behaviour

WHEN the dead-code scanner classifies it, THEN it MUST be classified live (a reference site exists), NOT dead.

WHEN classified, THEN it MUST be classified dead (the negative direction still holds).

  • GIVEN a first-party symbol referenced only via module.attr dynamic access (e.g. _runtime_bridge_module().get_or_start_run),
  • GIVEN a symbol with no static import and no first-party dynamic access,

Non-fakeable evidence

  • Focused AST tests exercise BOTH directions (dynamic-access→live, unreferenced→dead) against fixtures, not the live tree only.
  • At least the 4 known runtime.next.runtime_bridge façade symbols (get_or_start_run, query_current_state, answer_decision_via_runtime, QueryModeValidationError) are removed from the permanent allowlist and pass as recognised-live.

Anti-goals

  • Do NOT widen liveness to any attribute access (would mask real dead code); scope to first-party module resolution.
  • Do NOT special-case runtime_bridge by name — resolve the dynamic-accessor shape generally.

positional-anchor-ban-hole.md

Contract — Positional-anchor ban: seed-tuple laundering hole (IC-04 / FR-005, P1)

Behaviour

AND that int_line reaches the 2nd positional arg of composite_key(source, N) / composite_key_from_file(path, N) via an intermediate loop or local variable, WHEN the positional-anchor ban runs, THEN it MUST flag the seed as a banned int-to-line-sink (the laundering vector is closed).

WHEN the ban runs, THEN it MUST NOT flag it (no false positive on legitimate content-addressed keys).

  • GIVEN a module-level allowlist seed constant holding a raw (rel_path, int_line) tuple,
  • GIVEN a composite_key(source, N) where N is a genuine live line obtained from code_tokens_by_line(...) at runtime,

Non-fakeable evidence

  • A regression fixture that attempts the laundering fails the ban.
  • git grep -nE '\.py", *[0-9]{3}\)' tests/architectural/ returns zero (the residual raw seed tuples in test_no_write_side_rederivation.py / test_trio_seam_only.py are converted to content-addressed keys).
  • test_ratchet_positional_anchor_ban.py is green on the real (non-fixture) tree.

Notes

  • The predicate stays int-to-line-sink, not "positional anchor in general" — module::Name / path::qualname symbol-identity keys are explicitly allowed (they are the relocation-proof keys, and banning them would be circular with FR-014's permanent census deferral).

quality-gate-needs-containment.md

Contract — quality-gate.needs ⊇ pytest-jobs containment (IC-11 / FR-012, #2622)

Behaviour

LET pytest_jobs = { job : any step run-cmd matches \bpytest\b }, WHEN the guard runs, THEN it asserts pytest_jobs - NON_BLOCKING_ALLOWLIST ⊆ quality_gate.needs.

WHEN the guard runs, THEN it FAILS (the un-gated suite job is caught).

  • GIVEN the CI workflow model (_gate_coverage.WorkflowModel),
  • GIVEN a new pytest-invoking job is added without a quality-gate.needs edge and without an allowlist entry,
  • EACH NON_BLOCKING_ALLOWLIST entry MUST carry a why-non-blocking rationale string (mirroring the CI_INVISIBLE ledger pattern).

Non-fakeable evidence

  • A regression adds a fake pytest job to the parsed model and asserts the guard fails.
  • slow-tests and mutation-testing are resolved to an explicit state: either added to quality-gate.needs, or added to NON_BLOCKING_ALLOWLIST with a rationale — never left silently absent.

Anti-goals

  • Do NOT hard-code the current job list; derive pytest_jobs from the workflow model so a future job is covered automatically.
  • Do NOT match pytest inside comments/strings — anchor on the run-command token.

shard-registry-seam.md

Contract — Explicit shard-registry seam (IC-10 / FR-011, #2621)

Behaviour

WHEN a row owner registers a ShardGroup, THEN all_groups() returns it; register is idempotent and rejects a duplicate key.

WHEN the completeness guard runs, THEN it fails with a diagnosable "group <name> not registered" — NEVER a bare KeyError.

WHEN collection marks tests, THEN the guard fails loud (no test universe is silently left unmarked).

  • GIVEN the shard registry is assembled via explicit register(group) calls (not import side-effect),
  • GIVEN a group named in the expected-group manifest is NOT registered,
  • GIVEN the tests/next root has no registered group,

Non-fakeable evidence

  • A regression that removes the _next_shard_map registration asserts the guard emits the diagnosable message (assert on the message, not just "raises").
  • A regression that asserts an unmarked tests/next universe fails, not passes.

Anti-goals

  • Do NOT keep the # noqa: F401 import-for-side-effect line as the assembly mechanism.
  • Do NOT collapse arch and next ownership into one module — keep row-owners separate, registered through the seam.