Skip to content

Commit 3736ec0

Browse files
authored
docs(P-022): parity-work discipline + status reconciliation at fdcb222 (#322)
Two halves of one change, deliberately together: the rules for not letting status drift happen again, and the reconciliation that removes the drift those rules were learned on. Parity-work discipline — four rules, each paid for by a real defect during step 5a (#255, PRs #319/#320/#321), worded wider than this port so they outlive P-022: oracle over reviewer prose; mutation over plausible tests; no fail-fast during mutation campaigns; insertion-stable generated goldens. Rule 4's law is the invariant (churn == 0, delta == 1), not the content hash that satisfies it today. Recorded only in P-022 — two copies of one law drift. Status reconciliation — written fresh against the tree at fdcb222, not carried over from an earlier stale block. Corrects #258 (closed completed, both spec documents on main), the missing own-lowered/own-bridge workspace members, step 5a (closed completed), and own-diagnostics (full normalized contract, not a data-only layer). Statuses are checkpoint-level, separating each open step's normative blocker from #250's preferred sequencing. The proposals index row is fixed in the same change — a third status surface of the same fact. Review round on 2cb3822: four findings, each checked against the tree first. Three fixed in 267e38c, including the one that matters — the rule-4 section declared both acceptance lines while the executable guard gates only churn, so the enforcement gap is now stated rather than implied. The fourth was rejected with evidence and withdrawn by the reviewer. Refs #250, #255, #256, #258, #259.
1 parent fdcb222 commit 3736ec0

2 files changed

Lines changed: 146 additions & 18 deletions

File tree

‎docs/proposals/P-022-rust-core-migration.md‎

Lines changed: 145 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,21 @@ rationale below is historical and unchanged; the live sequencing is the #250
66
child-issue DAG. Revised per the post-merge review in
77
[`docs/notes/p022-review-notes.md`](../notes/p022-review-notes.md).
88

9-
### Implementation status (reconciled after #214/#249 — see #250/#251)
10-
11-
**Implemented** (workspace members in `rust/Cargo.toml`, parity-gated by
9+
## Implementation status
10+
11+
> **Reconciled at `fdcb222`** against `rust/Cargo.toml`, the crate sources and
12+
> the child-issue states under #250. Written fresh from the tree, not carried
13+
> over from an earlier reconciliation — a stale status block patched with a
14+
> stale fix stays stale. Statuses are **checkpoint-level**, and each open step
15+
> separates its *normative* blocker (what its acceptance actually requires) from
16+
> #250's *preferred* sequencing (what order is cheapest); conflating those is
17+
> what let this table drift twice already.
18+
>
19+
> Keeping it true is a rule, not a habit: see
20+
> [Parity-work discipline](#parity-work-discipline) below, and the status-drift
21+
> rule in #250.
22+
23+
**Complete** (workspace members in `rust/Cargo.toml`, parity-gated by
1224
`scripts/oracle_exact.py` and the shared fixtures in `tests/fixtures/`):
1325

1426
- `own-ir` — OwnIR serde + schema round-trip (step 1);
@@ -17,24 +29,47 @@ child-issue DAG. Revised per the post-merge review in
1729
`tests/fixtures/cfg_parity.json` (steps 0/3; the seam the strategy below
1830
said "still needs building" **is built** — `python -m ownlang cfg --format
1931
json` + the `--write`-regenerated parity fixtures);
20-
- `own-diagnostics` — the data-only diagnostics layer;
2132
- `own-analysis` — the worklist solver + ownership/lifetime/buffer/effect/DI
2233
analyses (step 4; the **analysis-heart milestone**, completed in #214 /
2334
PR #249, replaying `diag_parity.json` and the DI/effect fact-parity
24-
fixtures).
25-
26-
**Next steps — each owned by exactly one child issue under #250:**
27-
28-
| Step | Deliverable | Issue |
35+
fixtures);
36+
- `own-diagnostics` — the verdict model **and** the full normalized diagnostic
37+
contract (step 5a, #255 **closed completed**, PRs #319/#320/#321): structural
38+
identity with a non-collapsing comparison key, canonical `render` /
39+
`render_pretty` text, the emission ordering contract, and a self-policing
40+
ledger covering all 47 `TITLES` codes;
41+
- `own-lowered` — the normalized Layer 2 document the bridge lowers into (the
42+
differential-testing representation named by #259 checkpoint 2);
43+
- `spec/Bridge.md` + `spec/BridgeBehaviorMatrix.md` — the normative bridge
44+
contract and its completeness ledger (step 6a, #258 **closed completed**;
45+
PR #297 merged, both documents on `main`).
46+
47+
**In progress — step 6b, `own-bridge` (#259).** It landed ahead of #250's
48+
*preferred* order ("preferably after #255/#256"); its *normative* blocker
49+
was #258 alone, which is satisfied. Per the checkpoints #259 itself defines:
50+
51+
| #259 checkpoint | Status | Evidence / what remains |
2952
|---|---|---|
30-
| 5a | diagnostic messages + ordered Evidence parity | #255 |
31-
| 5b | `.ownreport.json` + SARIF projection, canonical parity | #256 |
32-
| 5c | `own-codegen` (analysis-independent sibling) | #257 |
33-
| 6a | OwnIR **bridge semantics formalized** before the port | #258 (deliverable written — `spec/Bridge.md` + `spec/BridgeBehaviorMatrix.md` **land with PR #297**, in independent review; not on `main` yet) |
34-
| 6b | Rust `own-bridge`, layered OwnIR parity | #259 |
35-
| 7a | dual-engine shadow mode + zero-diff reproduction artifacts | #260 (supported by #269 — normalized `AnalysisTrace` + first-divergence minimizer) |
36-
| 7b | Rust `own-cli`: command/output/exit-code parity | #261 |
37-
| 8 | Rust-default **cutover**, rollback gate, Python distribution removal | #262 |
53+
| 1 — typed OwnIR validation | **partial** | `OwnIr::from_json` + the #294 OD-2 fail-loud unknown-kind rule. Full validation acceptance/rejection parity (fixture layer 1) is out of the current slice |
54+
| 2 — fact lowering | **complete** | `lower()` → `own_lowered`; **27/27** `rust_replay` cases in `tests/fixtures/lowered/manifest.json` byte-exact |
55+
| 3 — interprocedural MOS | **complete for the stage-1 domain** | `dump_summaries()` byte-identical to `python -m ownlang summaries` across **35** `*.summaries.json` goldens. Container-valued metadata is **outside** the declared scalar-metadata parity domain — a separate #294-class door decision, not a silent gap |
56+
| 4 — analysis wiring | **not started** | the crate states its own boundary: "no diagnostics, no analysis" |
57+
| 5 — full fact-to-verdict parity | **unblocked, not done** | its comparison set (message, severity, subject, resource kind, ordered Evidence) is now delivered by #255 — but the checkpoint still needs checkpoint 4's wiring to produce verdicts to compare |
58+
59+
**Open steps — each owned by exactly one child issue under #250:**
60+
61+
| Step | Deliverable | Issue | Status |
62+
|---|---|---|---|
63+
| 5a | diagnostic messages + ordered Evidence parity | #255 | **complete** — see above |
64+
| 5b | `.ownreport.json` + SARIF projection, canonical parity | #256 | **ready** — its normative blocker (#255) is satisfied. The **preferred next step**: it stays on the diagnostic/output seam #255 just finished, and completing it widens #259 checkpoint 5 to its full Layer-5 surface in one pass instead of two visits |
65+
| 5c | `own-codegen` (analysis-independent sibling) | #257 | **ready**, independent of the analysis path — parallelizable |
66+
| 6a | OwnIR **bridge semantics formalized** before the port | #258 | **complete** — see above |
67+
| 6b | Rust `own-bridge`, layered OwnIR parity | #259 | **in progress** — checkpoint table above |
68+
| 7a | dual-engine shadow mode + zero-diff reproduction artifacts | #260 (supported by #269) | **infrastructure sliceable now**, final acceptance **blocked by #259**. Buildable against the landed checkpoints: same-input OwnIR capture + hash, reproduction-artifact format, engine protocol, trace schema, stable-ID normalization, first-divergence reduction over the *lowered*/MOS layers. Not yet declarable as shadow mode: acceptance compares end diagnostics |
69+
| 7b | Rust `own-cli`: command/output/exit-code parity | #261 | blocked — needs the production bridge and the output surfaces |
70+
| 8 | Rust-default **cutover**, rollback gate, Python distribution removal | #262 | blocked by #260/#261 and final parity |
71+
72+
**Preferred queue:** #256 → #259 remaining (cp1 → cp4 → cp5) → #260/#269.
3873

3974
The Datalog/Ascent rule layer stays strictly **post-cutover** (strategy step 8
4075
below) and deliberately has no issue yet. Throughout: Python remains
@@ -561,6 +596,99 @@ hardening is what made the verdict seam cheap — and the CFG seam has since bee
561596

562597
Throughout, Python stays authoritative; the Rust crates light up behind the ratchet.
563598

599+
## Parity-work discipline
600+
601+
Four rules, each paid for by a real defect during step 5a
602+
(#255, PRs #319/#320/#321). They are written **wider than this port on
603+
purpose**: nothing below depends on Rust, on Python, or on the diagnostics
604+
layer, so they outlive P-022 and apply to the next migration that pins one
605+
implementation against another.
606+
607+
Scope: parity/migration work. This is the only home — the rules are not
608+
duplicated into `AGENTS.execution-surfaces.md`, because two copies of one law
609+
drift, which is the failure mode the status-drift rule already exists to stop.
610+
611+
### 1. Oracle over reviewer prose
612+
613+
**Rule.** A reviewer finding is a *hypothesis* until reproduced against the
614+
reference implementation. Preserve the observed oracle behaviour, not the
615+
reviewer's explanation of it.
616+
617+
**Why.** A reviewer — human or bot — can be right about *what* is wrong and
618+
wrong about *why*, and the explanation is what you would otherwise encode.
619+
620+
**Failure mode paid for.** A review argued the word-boundary rule from probes
621+
using single-ended patterns (`\b-foo`). The reference builds a **both-ended**
622+
pattern (`\b…\b`), which gives a different answer at the right edge. The
623+
conclusion was correct; the stated reason was not, and implementing the reason
624+
would have been wrong. Re-probing with the real pattern shape settled it.
625+
626+
### 2. Mutation over plausible tests
627+
628+
**Rule.** A test written to catch a specific regression is not evidence until
629+
the corresponding mutation makes it fail **through the production surface it
630+
claims to protect**.
631+
632+
**Why.** A test that has never failed has never been shown to test anything.
633+
"Through the production surface" is the load-bearing half: a test can exercise a
634+
private copy of the logic and pass while the public path rots.
635+
636+
**Failure mode paid for.** The ordering replay sorted a parallel vector with a
637+
*copy* of the sort key and then compared only `(line, code)` — which tied
638+
records share by construction. `ties_keep_emission_order` would have passed
639+
against `sort_unstable_by`, the exact defect it was written for. Driving the
640+
label order through the public helper made it real.
641+
642+
### 3. No fail-fast during mutation campaigns
643+
644+
**Rule.** Mutation validation must expose **all** independent catching layers,
645+
not merely the first failing test target.
646+
647+
**Why.** Stopping at the first failure tells you *a* test caught the mutation.
648+
It does not tell you which layers did and which silently would not have.
649+
650+
**Failure mode paid for.** `cargo test` halts after the first failing target. A
651+
mutation appeared to be caught by one unit test only; with `--no-fail-fast` the
652+
same mutation showed three catchers across unit and replay layers — and a second
653+
mutation, invisible in the first run, was caught only at the replay layer.
654+
655+
### 4. Insertion-stable generated goldens
656+
657+
**Rule.** When a fixture's shape is derived from a vocabulary, it must depend on
658+
**stable item identity**, never on ordinal position.
659+
660+
**Normative acceptance:**
661+
662+
```text
663+
insert one synthetic vocabulary member
664+
existing-record churn == 0
665+
new-record delta == 1
666+
```
667+
668+
The **invariant is the law**. A content hash is today's way of satisfying it in
669+
`tests/test_diag_ledger_fixtures.py`, not the requirement — any stable mapping
670+
that holds the two lines above conforms, and swapping the mapping is not a
671+
violation. (Whatever is chosen must be reproducible across processes: Python's
672+
`hash()` randomises string hashing per run and cannot be used.)
673+
674+
**Enforcement today is partial — the norm deliberately outruns the guard.**
675+
`_insertion_churn()` in `tests/test_diag_ledger_fixtures.py` computes and gates
676+
the **first** line only (`churn == 0`). Nothing yet asserts `delta == 1`, so a
677+
generator that dropped the new record entirely would still satisfy every
678+
executable check. The acceptance above is the norm regardless of how much of it
679+
is currently wired up; closing the gap is a queued test change, not a
680+
relaxation of the rule.
681+
682+
**Why.** A vocabulary-derived golden exists to make *adding a member* legible.
683+
If insertion rewrites unrelated records, the one diff a reviewer needs is buried
684+
in churn, and a genuine change to the generator hides inside it.
685+
686+
**Failure mode paid for.** The ledger rotated case shapes by sorted index.
687+
Inserting one code (`DI006`) rewrote **42 of 47** existing records — measured,
688+
not estimated. The docstring meanwhile claimed the shapes were "deterministic,
689+
so the golden stays stable", true only while the vocabulary never changed, which
690+
is the single event the ledger exists to expose.
691+
564692
## Open questions (to resolve as we go)
565693

566694
- **Parser**: hand-roll vs `chumsky`/`winnow`. Leaning hand-roll for golden-parity of

‎docs/proposals/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ proposal is marked `done` with a pointer.
4141
| [P-017](P-017-multi-stack-frontends.md) | Multi-stack frontends (OwnTS / OwnJVM: OwnJava + OwnKotlin) | draft |
4242
| [P-020](P-020-ownts-react-effects.md) | OwnTS React effects profile (`Own.React`) — the effect-storm angle | draft |
4343
| [P-021](P-021-async-audit-pack.md) | Async audit pack (`Own.Async`) | draft |
44-
| [P-022](P-022-rust-core-migration.md) | Rust core migration: crate DAG, patterns, prior art, differential oracle (Python = golden) | in execution — steps 0–4 built (`own-ir`/`own-syntax`/`own-cfg`/`own-diagnostics`/`own-analysis`, #214/#249); remaining steps = the #250 child-issue DAG (#255–#262); Python authoritative until cutover |
44+
| [P-022](P-022-rust-core-migration.md) | Rust core migration: crate DAG, patterns, prior art, differential oracle (Python = golden) | in execution — steps 0–4 built (#214/#249); step 5a done (full diagnostic contract, #255 via #319/#320/#321); step 6a done (`spec/Bridge.md`, #258); step 6b underway (`own-lowered`/`own-bridge`, #259: lowering + MOS parity landed, analysis wiring open); next ready step 5b (#256); Python authoritative until cutover |
4545
| [P-023](P-023-architecture-guard.md) | Architecture guard (`Own.Arch`): rules.yaml intent model + dependency-graph gate + baseline ratchet | draft |
4646
| [P-024](P-024-security-audit-profile.md) | Security audit profile (external tools + SARIF adapters; rejects own scanner engine) | draft |
4747
| [P-025](P-025-obligation-protocols.md) | Obligation protocols (`Own.Protocols`): barrier-sensitive project invariants (OBL001–005) | first slice built (core + bridge + fixtures; extractor pending) |

0 commit comments

Comments
 (0)