Skip to content

Commit 2b4f971

Browse files
committed
docs(shadow-infra): record the owner decisions, and name the byte-level boundary
Closure for the step-7a slice. No code, no fixture, no recorded campaign result changes; the checkpoints stay as they landed. Three departures from the slice's brief are now decisions on the record instead of a brief quietly re-read to match the tree, in a new ledger at docs/notes/p022-shadow-infra-owner-decisions.md: - D-1: capture and the reproduction format stay ONE checkpoint, where the brief asked for a checkpoint each. Accepted — the format's central field is the hash, so the two halves have one indivisible piece of evidence — and recorded rather than renumbered. - D-2: the `-0` canonical-domain narrowing. An engine divergence was the brief's stop-and-report trigger; checkpoint 1 reported it AND decided it, in a paragraph that disclaims the standing to decide. The outcome is ratified as an owner decision (neither engine's semantics move, both refuse at the literal); the process correction is that discovering it was the trigger to stop. - D-3: `sha2` accepted for `own-shadow` only, bounded by the existing dag.rs test that no core crate depends on it. And one boundary the slice worded too strongly. #260's acceptance invariant is byte-level: hash the raw OwnIR bytes, feed THOSE bytes to both engines. What checkpoint 1 proves is shared CANONICAL document identity — and canonical-equivalent input is not byte-identical input, since ignoring whitespace, key order and duplicate-key resolution is exactly the canonical form's job. So the raw-byte invariant is now named as unmeasured in the generated census, in spec/Bridge.md §6 (a fifth point), and in P-022 row 7a plus the proposals index, before "same-input" and a green 80/80 can be read as #260's acceptance already closed. The ledger also records what CI does not attest: CodeRabbit's green line on the PR is "review skipped, manual review required for this OSS repository", not a review. Gates: ruff, mypy, python tests/run_tests.py, cargo fmt --check, cargo clippy --workspace --all-targets (zero warnings), cargo test --workspace --no-fail-fast, render_checkpoint_status.py --check. Campaigns not re-run: every mutation anchors into ownlang/repro.py or own-shadow/src/, neither of which this commit touches, and CI re-anchors each definition. Refs #260, #269, #250. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kh6wpfbBUNLbeCJZ263gYM
1 parent 5286689 commit 2b4f971

7 files changed

Lines changed: 196 additions & 7 deletions

File tree

‎docs/generated/p022-shadow-census.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@ here is a parity claim either.
1212

1313
This document is the **live view** of the slice as it stands; each checkpoint's
1414
recorded mutation campaign stays frozen at what it measured, under
15-
`docs/notes/p022-shadow-infra-checkpoint*-data/`.
15+
`docs/notes/p022-shadow-infra-checkpoint*-data/`. Where the slice departed from
16+
the brief it was given — the checkpoint grouping, the `-0` domain decision, the
17+
`sha2` dependency — the departures are decisions on the record in
18+
[the owner-decision ledger](../notes/p022-shadow-infra-owner-decisions.md),
19+
which also states the byte-level boundary repeated in the unmeasured set below.
1620

1721
## The measured set — same-input capture (checkpoint 1)
1822

@@ -28,7 +32,9 @@ recorded mutation campaign stays frozen at what it measured, under
2832
Every one of those documents is canonicalized and hashed by the reference
2933
(`ownlang/repro.py`) and re-hashed from the same file by the port
3034
(`own-shadow`), which is what makes "both engines saw the same input" a
31-
checked fact rather than an assumption.
35+
checked fact rather than an assumption — **at the level of canonical document
36+
identity**. That is a weaker statement than #260's acceptance invariant, and
37+
the difference is named in the unmeasured set below.
3238

3339
| surface | count |
3440
|---|---|
@@ -140,6 +146,17 @@ non-zero counter there is not representable as a passing build. The gates:
140146

141147
## The unmeasured set, named
142148

149+
- **#260's raw-byte same-input invariant.** #260 asks that the `OwnIR`
150+
document be produced or loaded exactly once, that the **raw bytes** be
151+
hashed, and that *those exact bytes* reach both engines. What this slice
152+
proves is shared **canonical document identity**: each engine parses the
153+
file and agrees on the canonical form's digest. Canonical-equivalent input
154+
is not byte-identical input — two files differing in whitespace, in object
155+
key order, or in duplicate-key resolution share one canonical identity,
156+
because ignoring exactly those differences is the canonical form's job.
157+
Acceptance must therefore prove the byte-level invariant separately; until
158+
it does, "same input" here means canonical identity and nothing stronger
159+
([owner decision B-1](../notes/p022-shadow-infra-owner-decisions.md)).
143160
- **End diagnostics compared as an acceptance surface** — #260's acceptance,
144161
blocked by #259 (cp5 and 4b). Not attempted, not approximated.
145162
- **The verdict layer.** Refused by the reducer, and recorded as refused in

‎docs/notes/p022-shadow-infra-checkpoint1.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@
77
> or should be quoted as it. Written from the tree at the commit that landed
88
> it; every number in it is generated — see
99
> [`docs/generated/p022-shadow-census.md`](../generated/p022-shadow-census.md).
10+
>
11+
> **Two owner decisions were taken about this checkpoint after it landed**, and
12+
> the note is left as written rather than edited to match them: it carries
13+
> *both* of the brief's first two items where the brief asked for a checkpoint
14+
> each (D-1), and the `-0` contract decision below was the checkpoint's to
15+
> *report*, not to take (D-2). Both are ratified, with reasons, in
16+
> [the owner-decision ledger](p022-shadow-infra-owner-decisions.md) — which
17+
> also states the boundary this note words too strongly: what is proved here is
18+
> **canonical document identity**, not #260's raw-byte same-input invariant
19+
> (B-1).
1020
1121
Two questions have to be settled **before** two engines can be compared at
1222
all, and neither of them is a comparison:
@@ -97,6 +107,12 @@ which is the exact lie this surface exists to prevent. Reconciling instead of
97107
refusing would have meant picking one parser's reading and calling the other
98108
wrong, which is a contract decision this checkpoint has no standing to take.
99109

110+
> Nor, as the owner's review pointed out, had it standing to take the
111+
> *narrowing* — an engine divergence was the brief's stop-and-report trigger,
112+
> and this paragraph declines the decision in the sentence before taking one.
113+
> The outcome stands, now as an owner decision:
114+
> [D-2](p022-shadow-infra-owner-decisions.md).
115+
100116
It costs the contract nothing: `spec/OwnIR.md` §4.2 already bounds every
101117
validated coordinate to signed 64 bits, and no `OwnIR` producer emits `-0`
102118
(measured: no document in any corpus contains one, a float, or an exponent).
Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# P-022 step 7a (#260/#269) — owner decisions on the shadow-mode infrastructure slice
2+
3+
> Status: **infrastructure for shadow mode**. This file changes no code, no
4+
> fixture and no measured number. It records three places where the slice
5+
> departed from the brief it was given, and one boundary the slice did not
6+
> state clearly enough — so that the departures are *decisions on the record*
7+
> rather than a brief quietly re-read to match what was built.
8+
9+
Ratified by the repository owner at the review of
10+
[#338](https://github.com/PhysShell/Own.NET/pull/338), 2026-09-06, on the tree
11+
at `5286689`. Checkpoints 1–4 stay as they landed; their notes, campaigns and
12+
recorded numbers are untouched.
13+
14+
## D-1 — capture and the reproduction format stay one checkpoint
15+
16+
**The brief said** five items, *each its own checkpoint with its own evidence,
17+
its own commit and its own row*: (1) same-input capture with a canonical hash,
18+
(2) the reproduction-artifact format, (3) the engine protocol, (4) the
19+
`AnalysisTrace` and stable-ID normalization, (5) first-divergence reduction.
20+
21+
**What landed** is four checkpoints over five commits: items 1 and 2 are both
22+
[checkpoint 1](p022-shadow-infra-checkpoint1.md).
23+
24+
**Decision: accepted, as an explicit deviation.** The two are one contract.
25+
An artifact format without a document identity is a container carrying a claim
26+
it cannot check — the format's central field *is* the hash, and the evidence
27+
for either half (a byte-exact round-trip whose embedded document re-hashes to
28+
the recorded digest) is a single indivisible check. Splitting them would have
29+
produced a checkpoint whose only evidence was "the file parses".
30+
31+
What is **not** accepted is leaving this unstated. The published history is not
32+
rewritten to renumber four checkpoints into five: the deviation is recorded
33+
here, and row 7a and the checkpoint-1 note both point at this file. A brief
34+
that says five and a tree that says four must disagree *in writing*.
35+
36+
## D-2 — the `-0` canonical-domain decision is the owner's, retrospectively
37+
38+
**The stop condition said**: if an engine divergence is discovered, stop and
39+
report it; describe the fork with its options, but do not take the decision.
40+
41+
**What happened**: checkpoint 1 discovered a real divergence — CPython's `json`
42+
reads the literal `-0` as the integer `0`, `serde_json` reads it as the float
43+
`-0.0` — recorded it as a finding with a reproduction, and then **took the
44+
contract decision itself**, narrowing the canonical domain to exclude `-0`.
45+
The checkpoint note is candid to the point of self-indictment: it says
46+
reconciling "is a contract decision this checkpoint has no standing to take",
47+
in the same paragraph in which a contract decision is taken.
48+
49+
**Decision: the outcome is ratified; the process is corrected.** As of this
50+
ledger the canonical domain's exclusion of `-0` is an **owner decision**, not a
51+
checkpoint's. It stands because:
52+
53+
- Neither engine's semantics change. Nothing teaches CPython to hold a float or
54+
`serde_json` to hold an integer; the document is refused by **both**, at the
55+
literal, under the executable `domain_refusals` ledger.
56+
- The alternative is worse than the refusal. A canonical form that hashed `-0`
57+
would assert *"both engines saw the same document"* while the two engines
58+
held different values — the precise lie the same-input surface exists to
59+
prevent.
60+
- It costs the contract nothing. `spec/OwnIR.md` §4.2 already bounds every
61+
validated coordinate to signed 64 bits, and no document in any corpus
62+
contains `-0`, a float or an exponent.
63+
64+
The correction that matters for future slices: **discovering the divergence was
65+
the trigger to stop.** The finding, the reproduction and the ledger were the
66+
deliverable; the domain decision should have been proposed here and waited.
67+
68+
## D-3 — `sha2` is accepted, for `own-shadow` only
69+
70+
`sha2` (RustCrypto) enters a deliberately spare workspace and is used by
71+
exactly one crate. **Accepted.** A hand-rolled SHA-256 inside a workspace that
72+
denies `arithmetic_side_effects` and `indexing_slicing` would trade an audited
73+
implementation for a page of justified suppressions and buy nothing.
74+
75+
The bound is the part to keep enforced, and it already is: `own-shadow` is
76+
outside the semantic core, and `own-diagnostics/tests/dag.rs` asserts by name
77+
that no core crate — `own-bridge` included — depends on it. If that test is
78+
ever relaxed, this decision lapses with it.
79+
80+
## B-1 — the boundary this slice did not state: #260 wants *raw bytes*
81+
82+
This is the one that would have cost someone a week of commit archaeology, and
83+
it is now stated in three places rather than none.
84+
85+
**#260's acceptance invariant is byte-level**: produce or load the `OwnIR`
86+
document exactly once, hash the **raw bytes**, and feed *those exact bytes* to
87+
both engines.
88+
89+
**What checkpoint 1 proves is one level up from that**: both engines derive the
90+
same **canonical identity over the parsed document** — sorted keys, compact
91+
separators, a closed value domain, SHA-256 over that form. Every one of the 80
92+
documents is canonicalized and hashed by the reference and re-hashed by the
93+
port, and the two agree.
94+
95+
That is the right thing to have built now, and the brief asked for exactly it.
96+
But the two claims are not the same claim:
97+
98+
> **canonical-equivalent input ≠ byte-identical input.**
99+
100+
Two files differing in whitespace, in object key order, or in how a duplicate
101+
key resolves can share one canonical identity. The canonical form is designed
102+
to ignore those differences — that is its job — so it cannot also be the
103+
evidence that they were absent.
104+
105+
**Consequence, and it is not optional at acceptance**: #260's same-input
106+
invariant is **not proved by this slice**, and shadow-mode acceptance must
107+
additionally prove that both engines consumed the identical captured byte
108+
sequence. Until then, "same input" in this slice's vocabulary means *canonical
109+
document identity*, and the phrase must not be read as the stronger invariant.
110+
111+
Now named in: the generated census's unmeasured set, `spec/Bridge.md` §6, and
112+
P-022 row 7a.
113+
114+
## What this commit deliberately does not do
115+
116+
- **No code changes.** `ownlang/repro.py` and `rust/crates/own-shadow/` are
117+
untouched; so is every fixture, golden and recorded campaign result.
118+
- **No campaign re-runs.** Every mutation anchors into `ownlang/repro.py` or
119+
`own-shadow/src/`, neither of which this commit edits, so the recorded
120+
results still describe the tree they measured — and CI re-anchors each
121+
definition on every build (`tests/test_generated_docs.py`). A campaign is
122+
evidence about a tree, not a rite to be repeated whenever prose moves.
123+
- **No history rewrite.** Four checkpoints, five commits, and D-1 above.
124+
125+
## One thing CI does not attest
126+
127+
`CodeRabbit` on #338 reports `success`, and its description says what that
128+
success is: *"Review skipped: manual review required for this OSS repository"*
129+
(the repository is under the star threshold for automatic review). There are no
130+
submitted reviews on the pull request. A green line named after a review tool
131+
is not a review, and this slice should never be quoted as having had one.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ was #258 alone, which is satisfied. Per the checkpoints #259 itself defines:
7272
| 5c | `own-codegen` (analysis-independent sibling) | #257 | **ready**, independent of the analysis path — parallelizable |
7373
| 6a | OwnIR **bridge semantics formalized** before the port | #258 | **complete** — see above |
7474
| 6b | Rust `own-bridge`, layered OwnIR parity | #259 | **in progress** — checkpoint table above |
75-
| 7a | dual-engine shadow mode + zero-diff reproduction artifacts | #260 (supported by #269) | **infrastructure COMPLETE — checkpoints 1–4 landed**; final acceptance **still blocked by #259**. Every item this row listed as *sliceable now* is built and replayed with zero of the other engine's runtime: cp1 same-input `OwnIR` capture + canonical hash and the reproduction-artifact format; cp2 the **engine protocol** (each engine declares what it could *produce*); cp3 the **`AnalysisTrace`** (#269 — stable-ID normalization, per-layer ordering semantics *declared* rather than normalized away); cp4 **first-divergence reduction** over the *lowered*/MOS layers, naming layer, step and the minimal difference. `ownlang/repro.py` is the reference emitter, `own-shadow` the port's half. **80 documents** digest-pinned and re-hashed **0/0/0**, **9** artifacts + **9** traces + **9** reductions reproduced byte-for-byte, **80** tamper controls, **6** executable domain refusals, **18** structural + **5** backstop controls per side, campaigns **30/30**, **11/11**, **11/11**, **11/11** caught. Divergence classification, now **computed** by the reducer rather than gate-implied: left-only 0 / right-only 0 / changed 0 / ordering-only 0 / unexplained 0, with 2 `status` observations, both boundaries the port declares ([cp1](../notes/p022-shadow-infra-checkpoint1.md), [cp2](../notes/p022-shadow-infra-checkpoint2.md), [cp3](../notes/p022-shadow-infra-checkpoint3.md), [cp4](../notes/p022-shadow-infra-checkpoint4.md), [generated census](../generated/p022-shadow-census.md)). Four **findings**, each recorded and resolved as a contract decision rather than by bending either engine: `-0` reads as an integer in CPython's `json` and a float in `serde_json`; the trace schema was ambiguous about where a duplicate address takes its `~n`; the capture carried the MOS document in a key order its own surface does not fix; and the two reducers disagreed about whether object key order is significant. **Still NOT shadow mode and not parity**: the reducer *refuses* the verdict layer and records the refusal, because acceptance compares end diagnostics and needs #259 cp5 + 4b. Crossing that line is a contract decision — the scope, engine and layer vocabularies are frozen constants with tests that fail when they move |
75+
| 7a | dual-engine shadow mode + zero-diff reproduction artifacts | #260 (supported by #269) | **infrastructure COMPLETE — checkpoints 1–4 landed**; final acceptance **still blocked by #259**. Every item this row listed as *sliceable now* is built and replayed with zero of the other engine's runtime: cp1 same-input `OwnIR` capture + canonical hash and the reproduction-artifact format; cp2 the **engine protocol** (each engine declares what it could *produce*); cp3 the **`AnalysisTrace`** (#269 — stable-ID normalization, per-layer ordering semantics *declared* rather than normalized away); cp4 **first-divergence reduction** over the *lowered*/MOS layers, naming layer, step and the minimal difference. `ownlang/repro.py` is the reference emitter, `own-shadow` the port's half. **80 documents** digest-pinned and re-hashed **0/0/0**, **9** artifacts + **9** traces + **9** reductions reproduced byte-for-byte, **80** tamper controls, **6** executable domain refusals, **18** structural + **5** backstop controls per side, campaigns **30/30**, **11/11**, **11/11**, **11/11** caught. Divergence classification, now **computed** by the reducer rather than gate-implied: left-only 0 / right-only 0 / changed 0 / ordering-only 0 / unexplained 0, with 2 `status` observations, both boundaries the port declares ([cp1](../notes/p022-shadow-infra-checkpoint1.md), [cp2](../notes/p022-shadow-infra-checkpoint2.md), [cp3](../notes/p022-shadow-infra-checkpoint3.md), [cp4](../notes/p022-shadow-infra-checkpoint4.md), [generated census](../generated/p022-shadow-census.md)). Four **findings**, each recorded and resolved as a contract decision rather than by bending either engine: `-0` reads as an integer in CPython's `json` and a float in `serde_json`; the trace schema was ambiguous about where a duplicate address takes its `~n`; the capture carried the MOS document in a key order its own surface does not fix; and the two reducers disagreed about whether object key order is significant. **Still NOT shadow mode and not parity**: the reducer *refuses* the verdict layer and records the refusal, because acceptance compares end diagnostics and needs #259 cp5 + 4b. Crossing that line is a contract decision — the scope, engine and layer vocabularies are frozen constants with tests that fail when they move. **Also not proved: #260's raw-byte same-input invariant.** What cp1 establishes is shared *canonical document identity*; canonical-equivalent input is not byte-identical input, so acceptance must additionally prove that both engines consumed the identical captured byte sequence. Three departures from the slice's brief — capture and the artifact format kept as one checkpoint, the `-0` domain narrowing (an engine divergence the brief said to report rather than decide), and `sha2` for `own-shadow` only — are ratified on the record in the [owner-decision ledger](../notes/p022-shadow-infra-owner-decisions.md) |
7676
| 7b | Rust `own-cli`: command/output/exit-code parity | #261 | blocked — needs the production bridge and the output surfaces |
7777
| 8 | Rust-default **cutover**, rollback gate, Python distribution removal | #262 | blocked by #260/#261 and final parity |
7878

0 commit comments

Comments
 (0)