Epic: contracts at every layer — stream, count, score (the rosetta roadmap; child of #2560)

[squid-protocol]

Child of #2560; supersedes #2669 as the handoff surface for cross-language consistency work. Strategy approved 2026-09-06. The document is docs/contract_roadmap.md (lands with #2811; formatted copy: https://claude.ai/code/artifact/debf7286-7958-48d6-91e5-48b1bbc4abc0). Read it before claiming anything here.

Why this epic exists (one paragraph)

The bias report's consistency badge paints every out-of-band cell the same red, whether the ledger validated it as "this language cannot express that" or as an open engine defect — so the scoreboard could not tell an extraction problem from a language fact, and the work kept looking like an extraction problem. Rolling the 267 gated red cells up by cause: 102 echo (derived), ~45 language inherency, ~50 extraction defects, 38 proximity-correlation effects, ~32 scoring choices. The largest engine-side finding is a layer leak, not a regex: core/spatial_correlation.py edits recorded signal counts in place (×3 cascading flux, silencer dampeners, ×5/×100 amplifiers; documented and pinned by #2631), so the count the corpus reads is never the raw count. The fix is a stated contract at each of the engine's three layers — what text a rule sees (stream), what one hit means (count), how counts combine (score) — and tooling that enforces them.

The goal restated: equal counts for equal constructs. Every remaining cross-language difference comes from one of three declared sources — a strictness stratum (design), an n/a (the language cannot express it), or a filed defect. After that a red dot is a defect by construction. The close criterion is open-defect share 0 and no draft row in the contract sheet, replacing "nothing unexplained".

Session start protocol (every session, every time)

1. gh issue view <this> --comments — the last comment per item is its true state. Claim by comment: claiming <item> — <model> — branch <name>; stop with status <item>: <done|blocked|partial> — <branch/PR> — <what remains>. Unfinished branches are pushed, never left local.
2. Read keyword-rosetta docs/bias_report.md from main (regenerated on every corpus push and nightly): the "What the red cells are" section and the open-defect share. Do not regenerate locally to triage; regenerate only to verify a change before a PR.
3. Read the signal's row in gitgalaxy/standards/signal_contracts.py and the ledger entries naming it before calling any rule a defect (two of the four issues filed from the args audit were already settled in the ledger).
4. One layer per engine PR (rule regex | slicer/DAG | correlation | scoring). One Closes #N per line. Label rosetta:rebless-owed when the corpus moves; corpus re-bless PR opens against engine main after the engine PR merges (no pins since Cross-repo choreography is circular, and every way it broke today failed green — drop the ENGINE_REF dance, machine-check the invariants #2682/ci: rosetta-audit without pins -- baseline-classified, refuses to no-op (#2682) #2699).
5. Claim a family (one signal, or one formula), never a language. The per-language issues rosetta[abap]: cross-language consistency — 3 red / 3 amber metrics, 2 ledgered shapes #2561–rosetta[zig]: cross-language consistency — 4 red / 2 amber metrics, 5 ledgered shapes #2607 are closed; per-language classification is the keyword-rosetta rosetta-language-sweep skill, called from a family audit, and live standing is python tools/language_deviations.py <lang>.

Decisions (approved 2026-09-06)

• D1 Recorded signal counts become raw counts; correlation weights move to the formulas that read them (score-neutral by construction; one golden-master bless + one corpus re-bless). → Phase 2.
• D2 Close rosetta[abap]: cross-language consistency — 3 red / 3 amber metrics, 2 ledgered shapes #2561–rosetta[zig]: cross-language consistency — 4 red / 2 amber metrics, 5 ledgered shapes #2607 and Epic: rosetta cross-language consistency — per-language deviation tracking (46 languages) #2560; this epic is the one handoff surface; Rosetta to green: cause-first batch plan + multi-session coordination (child of #2560) #2669 closed with a final status. Capstones (docs/language_status/<lang>.md §10) are written when a language reads clean by language_deviations.py, decoupled from any issue.
• D3 The contract sheet is gitgalaxy/standards/signal_contracts.py (machine-readable), rendered to docs/signal_contracts.md, checked by tests/signal_contract_audit.py --ci; how_to_add_a_language.md's comment lines are its prompt form.
• D4 Add the open-defect share now; switch the chart badge in a follow-up PR with the README copy.

Phases

• 0 · Scoreboard keyword-rosetta T2 — bias_report.py cause roll-up (categorize_out_of_band, open_defect_share, decayed_entries), "What the red cells are" section, bias_data.json["cell_categories"] / ["open_defect_share"], GATING.md category semantics, rosetta-language-sweep re-scoped, issue_status.py --post retired. → keyword-rosetta branch tools/cell-categories (PR number in the status comment). Closes keyword-rosetta#75 as a standing check.
• 1 · The sheet gitgalaxy T2 — signal_contracts.py (68 rows: 2 stated, 66 draft), signal_contract_audit.py + baseline + workflow, docs/signal_contracts.md, RULE 18 + pointer in how_to_add_a_language.md, rule-contract-audit skill, ecosystem.md. → docs(contracts): contract roadmap, signal contract sheet + baseline-gated audit, rule-contract-audit skill #2811.
• 2 · Raw counts are counts (D1) gitgalaxy T1 design done, T2 build, T1 bless review — the six proximity pairs write to mitigations only; a _weighted() helper in signal_processor.py; recorders carry the weighted figure under its own key; test_spatial_correlation.py pins move; core/README.md proximity table. Proof: every risk_* column in both golden masters byte-identical; corpus state_mutation lands on 2 where planted; state-flux-branch-weighting flips still_reproduces. Issue: see the comment below. Unblocks state_mutation has no stated contract: three incompatible definitions across 46 languages, and it governs the corpus's two worst metrics #2765.
• 3 · Count contracts, by family gitgalaxy + keyword-rosetta T1 sentence + audit, T2 build — order by consistency: state_mutation state_mutation has no stated contract: three incompatible definitions across 46 languages, and it governs the corpus's two worst metrics #2765 → encapsulation encapsulation has no stated contract: rust counts pub (the public modifier) and agc_assembly's rule matches every column-0 token #2766 → immutability_locks immutability_locks has no contract: rust's let is invisible while swift's let scores 11 — and it is subtracted from the corpus's worst gated metric #2772 (rule half) → cobol args/globals cobol args −92%: the overlap-cost rejection was priced before #2729 planted ENTRY on every paragraph — the api cost it avoids is already paid #2804 cobol globals counts WORKING-STORAGE SECTION: a region header stacked on top of the item-level GLOBAL/EXTERNAL clauses, unconditional on every COBOL program #2805 → the rest by the mechanical audit. Use the rule-contract-audit skill. The eight unplanted risk inputs get a plant or a contract-level absence. Structure rows (functions_found[markdown] −100%: func_start is n/a for markdown but functions_found scores it anyway — the structure-count rows have no n/a mechanism #2795 classes_found: five red cells on a 0 median are language morphology, not extraction — the row needs a declaration-requirement stratum #2796 classes_found[css] red on a 0 median: a CSS class is a selector, and #1295 already ruled it out of scope on the other two charts #2798) get the same inherency → n/a treatment. Done when every sheet row is stated.
• 4 · Score contracts + commensurability audit gitgalaxy T1 design, T2 build — tests/tools/audit_commensurability.py (walks _calc_* ASTs, reads units from the sheet, flags +/− between unlike units, ungated inputs, tally denominators), then one PR per formula. Closes control_flow_ratio is the corpus's worst metric (33%): it divides a pinned numerator by structural_boundaries, an ungoverned 0-45 vocabulary tally #2770, raw_arch_api bands a per-file declaration count against a per-function median — one granularity mismatch, three red columns #2771, immutability_locks has no contract: rust's let is invisible while swift's let scores 11 — and it is subtracted from the corpus's worst gated metric #2772 (formula half), length leaks: func_internal_density, avg_func_loc and control_flow_ratio read file length with content and tier held equal (rosetta F.1 design pass) #2705's residue.
• 5 · Closure — chart badge → open-defect share with README copy (D4 step 2); capstones as languages read clean; this epic closes on open-defect share 0 + no draft rows.

Housekeeping owed (not blocking)

• gitgalaxy/standards/fidelity_table.py is stale against corpus main (tests/tools/fidelity_table.py --check fails on main since keyword-rosetta#74) — regen owed by the next PR touching the fidelity layer.
• Untracked scratch files in the engine working tree (gitgalaxy/tests.py, gen_tests.py, parse_regex.py, regexes.txt, temp_search.txt) trip the local ruff/mypy audits; CLAUDE.md's scratch rule applies.

Issue disposition

issues	action
#2561–#2607 (40 open) + #2560	closed 2026-09-06 as superseded (D2)
#2669	closed with final status; F.4 → Phase 3 families, F.5 → the STRUCTURE COUNTS issues, F.6 retired
#2765 #2766 #2772 #2804 #2805	Phase 3
#2770 #2771	Phase 4
#2792 #2801 #2803 #2806	engine defects, unchanged
keyword-rosetta#75	closed via Phase 0

[squid-protocol]

Phase 2 (D1) engine issue: #2813. Phase 1: #2811. Phase 0: keyword-rosetta branch tools/cell-categories (PR number to follow).