Skip to content

Commit 6839a6b

Browse files
committed
feat(ownir): add WellFormedness, the seventh error category
Veto on filing two protocol rules under `shape`, and the reasoning behind the veto is the part worth keeping. `protocol can never fire` (no barriers with `exit_barriers: false`) and `barrier == opens` were reported as `Shape` while the code comment directly above them said "both are well-formedness, not shape". Every value in such a record has the right type and a legal vocabulary; what is broken is that the record cannot MEAN anything. The justification given was that the taxonomy was already frozen at six. That is backwards. The taxonomy was frozen by the FIRST census; this mechanism was found by the SECOND — the same census that just proved a category set settled early is a claim about the settling, not about the contract. Filing a newly discovered mechanism under the nearest existing name is the exact substitution this enum was built to stop, and it was the substitution being made. So: `OwnIrErrorKind::WellFormedness`, wire name `well_formedness`. Both rules move to it. The enum's doc now states the set is closed by measurement in BOTH directions — it cannot outgrow its evidence (no `Reference` variant, nothing reaches it) and it is not frozen against new evidence. Ledger: 191 -> 193 controls. The two new ones are the acceptance twins the category needs — `exit_barriers: false` WITH a barrier, and a barrier that differs from `opens` — so the rejections are about meaning rather than about the fields being present at all. Four mutations, all caught, including the two that matter most here: each rule reported as `Shape` while still rejecting. Category-only mutations are the only thing that can tell a real taxonomy from a decorative one. Also, per review: 128 is now the ONLY normative depth number. The measured abort points (~831/~846 for serialization, ~804/~851 for `Drop`) are properties of one stack size, build profile and platform. They are good forensics and they were creeping into doc comments as if they were specification; they are out of the normative wording and the PR keeps them as evidence. And the guard's promise is stated precisely instead of absolutely. It was "nothing this crate does can prevent that". Correctly: `to_value()` and `validate()` refuse a too-deep value and RETURN rather than aborting inside the serializer. They do not promise that any `Value` a caller built is safe to hold — `serde_json::Value` has a recursive `Drop`. Guaranteeing that would mean not representing facts as `serde_json::Value`, a representation change and outside cp1. Status, per the same review: cp1 is NOT complete and P-022 + the index now say so. 0/0/0 currently means "over a set from which two known Python-accept/Rust-reject families were removed" — coordinates beyond Rust's integer range, and deep nesting. That is not the parity #259 asks for. Both close Python-first, before this checkpoint may be called complete. #250 is corrected in the same logical change, via the API. Refs #250, #259. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJF7MBi1ijU5m9cJVWgQsM
1 parent bb94cbd commit 6839a6b

8 files changed

Lines changed: 195 additions & 55 deletions

File tree

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

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ was #258 alone, which is satisfied. Per the checkpoints #259 itself defines:
5353

5454
| #259 checkpoint | Status | Evidence / what remains |
5555
|---|---|---|
56-
| 1 — typed OwnIR validation | **complete** | Two censuses, and the second is the point. The first froze 77 controls, closed twelve permissive documents and read 0/0/0 — then independent review found seven divergences the ledger could not express, because the same author wrote the ledger and the port and one gap in reading BR-D1 produced a matching gap in each (`_svc()` always supplied `lifetime`, so no control could omit it). The re-census is derived from `load()` and `obligations.py` line by line: **191 controls**, which opened a further **58** permissive documents and **9** category mismatches. Closing them was architectural, not incremental — the strict door is now a sequential validator over the raw document (`own-ir/src/strict.rs`) that reproduces BR-D1's interleaving of shape and semantics *per section, in declaration order*. `serde` is the typed constructor, no longer the arbiter, and a document it rejects after validation is reported as a hole in the validator and asserted against. The obligation **acceptance grammar** (`parse_protocol`/`parse_matcher`/`parse_events`/`parse_method`) is ported in `own-ir/src/protocol.rs`; protocol *analysis* is not, and is not part of what the door accepts. Final matrix 29/162 agreed, 0/0/0 across the three failure rows; 27 mutations each caught, five of them only by the validator-hole guard. **One measured divergence stays open and is deliberately not closed here:** Python integers are unbounded and every `line`/`column` field accepts values past 64 bits, so Rust is over-strict above `i64::MAX` across seven field families. The ledger pins the boundary where both agree; the range above it is a Python-first defensive limit on source coordinates (#259's own limits/defensive-parsing requirement), not a case for arbitrary-precision integers through the Rust core. #294 OD-2 remains a separate tolerant-door concern |
56+
| 1 — typed OwnIR validation | **acceptance surface closed except two named families — not yet complete** | Two censuses. The first froze 77 controls, closed twelve permissive documents and read 0/0/0 — then review found seven divergences the ledger could not express, because the same author wrote the ledger and the port and one gap in reading BR-D1 produced a matching gap in each (`_svc()` always supplied `lifetime`, so no control could omit it). The re-census is derived from `load()` and `obligations.py` line by line: **193 controls**, which opened a further **58** permissive documents and **9** category mismatches. Closing them was architectural — the strict door is now a sequential validator over the raw document (`own-ir/src/strict.rs`) reproducing BR-D1's interleaving of shape and semantics *per section, in declaration order*; `serde` is the typed constructor, and a document it rejects after validation is reported as a hole in the validator and asserted against. The obligation **acceptance grammar** is ported (`own-ir/src/protocol.rs`); protocol *analysis* is not, and is not part of what the door accepts. Taxonomy is now **seven** categories: `WellFormedness` was added for the two protocol rules whose values are all correctly typed and whose records still cannot mean anything — a category set frozen by the first census is a claim about that census, not about the contract. Matrix 31/162, 0/0/0; 31 mutations each caught, five only by the validator-hole guard and two changing nothing but a category. **Why this is not yet complete:** two Python-accept/Rust-reject families are measured and deliberately excluded from the ledger — source coordinates beyond Rust's integer range, and sufficiently deep protocol/flow nesting. 0/0/0 therefore means "over a set from which two known divergence families were removed", which is not the parity #259 asks for. Both close in one **Python-first** defensive-limit change (signed-64 coordinates; one measured domain nesting limit, at-limit accept and limit+1 reject, written into the OwnIR contract). That lands first; this checkpoint is then rebased, gains boundary controls for both families, and is re-measured before it may be called complete. #294 OD-2 remains a separate tolerant-door concern |
5757
| 2 — fact lowering | **complete** | `lower()` → `own_lowered`; **27/27** `rust_replay` cases in `tests/fixtures/lowered/manifest.json` byte-exact |
5858
| 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 |
5959
| 4 — analysis wiring | **not started** | the crate states its own boundary: "no diagnostics, no analysis" |
@@ -72,11 +72,13 @@ was #258 alone, which is satisfied. Per the checkpoints #259 itself defines:
7272
| 7b | Rust `own-cli`: command/output/exit-code parity | #261 | blocked — needs the production bridge and the output surfaces |
7373
| 8 | Rust-default **cutover**, rollback gate, Python distribution removal | #262 | blocked by #260/#261 and final parity |
7474

75-
**Preferred queue:** #259 remaining (cp4 → cp5) → #260/#269. One Python-first
76-
side change is queued ahead of nothing and blocks nothing: a documented
77-
defensive limit on source-coordinate integers, which closes the last measured
78-
cp1 divergence (Python accepts coordinates past 64 bits; Rust does not) without
79-
pushing arbitrary-precision integers through the Rust core.
75+
**Preferred queue:** Python-first defensive limits → finish cp1 → cp4 → cp5 →
76+
#260/#269. The limits change is **not** a side quest: it closes the two measured
77+
Python-accept/Rust-reject families (source-coordinate integers beyond signed 64
78+
bits, and nesting depth), and until it lands cp1's 0/0/0 is a result over a set
79+
with two known divergence families removed from it. Closing them by widening
80+
Rust — arbitrary-precision integers, `unbounded_depth` — is refused: the limit
81+
belongs in the contract, not in the representation.
8082

8183
### What #256 asked for that the tree does not have
8284

‎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 (#214/#249); step 5a done (full diagnostic contract, #255 via #319/#320/#321); step 5b SARIF done (#256; `.ownreport.json` struck — a buffer report needing the AST, not a diagnostics surface); step 6a done (`spec/Bridge.md`, #258); step 6b underway (`own-lowered`/`own-bridge`, #259: strict-door validation, lowering and MOS parity landed — validation re-censused at 191 controls after a first 0/0/0 proved to be the ledger agreeing with its own author; analysis wiring open); 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 5b SARIF done (#256; `.ownreport.json` struck — a buffer report needing the AST, not a diagnostics surface); step 6a done (`spec/Bridge.md`, #258); step 6b underway (`own-lowered`/`own-bridge`, #259: lowering and MOS parity landed; strict-door validation re-censused at 193 controls after a first 0/0/0 proved to be the ledger agreeing with its own author, and awaiting a Python-first defensive-limit change before it can be called complete; analysis wiring open); 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) |

‎rust/crates/own-ir/src/lib.rs‎

Lines changed: 33 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -62,12 +62,18 @@ pub const OWNIR_VERSION: i64 = 0;
6262
/// two languages' English would freeze a debug surface as a contract.
6363
///
6464
/// One variant per **mechanism** a loader can reject on, not one per message.
65-
/// The set is closed by measurement — `tests/fixtures/ownir_validation.json`
66-
/// fails if a declared category has no control exercising it, so the taxonomy
67-
/// cannot outgrow its evidence. There is deliberately no `Reference` variant:
68-
/// the strict-door sweep found no load-time referential constraint, and adding
69-
/// one on the strength of an issue's prose would invent a category nothing can
70-
/// reach.
65+
/// The set is closed by measurement, in both directions:
66+
///
67+
/// * it cannot outgrow its evidence — `tests/fixtures/ownir_validation.json`
68+
/// fails if a declared category has no control exercising it. There is
69+
/// deliberately no `Reference` variant, because the strict-door sweep found
70+
/// no load-time referential constraint and adding one on the strength of an
71+
/// issue's prose would invent a category nothing can reach;
72+
/// * and it is not frozen against new evidence. [`Self::WellFormedness`] was
73+
/// added when the second census found a mechanism the first had not reached.
74+
/// A taxonomy settled by one census is a claim about that census, not about
75+
/// the contract, and reporting the new mechanism under the nearest existing
76+
/// variant would be exactly the substitution this enum exists to prevent.
7177
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
7278
pub enum OwnIrErrorKind {
7379
/// The document is not JSON at all.
@@ -83,6 +89,16 @@ pub enum OwnIrErrorKind {
8389
Identity,
8490
/// A source coordinate violating the 1-based contract (#317).
8591
Location,
92+
/// Every value has the right type and the right vocabulary, and the record
93+
/// still cannot mean anything — a rule that structurally never fires, a
94+
/// barrier the walk can never reach.
95+
///
96+
/// This variant exists because the second census found the mechanism, and
97+
/// a taxonomy frozen by the *first* census is not evidence about the
98+
/// second. Reporting these as `Shape` was the exact failure the taxonomy
99+
/// was built to prevent: letting the nearest available category stand in
100+
/// for the real one.
101+
WellFormedness,
86102
}
87103

88104
impl OwnIrErrorKind {
@@ -96,6 +112,7 @@ impl OwnIrErrorKind {
96112
Self::Vocabulary => "vocabulary",
97113
Self::Identity => "identity",
98114
Self::Location => "location",
115+
Self::WellFormedness => "well_formedness",
99116
}
100117
}
101118
}
@@ -606,13 +623,17 @@ impl OwnIr {
606623
/// round-trip the oracle's first parity check rides on.
607624
///
608625
/// Refuses a document whose raw values nest deeper than
609-
/// `strict::MAX_VALUE_DEPTH` — `serde_json::to_value` recurses over a
610-
/// `Value`, and on a deep enough one it does not fail, it **aborts the
626+
/// `strict::MAX_VALUE_DEPTH` (128). `serde_json::to_value` recurses over a
627+
/// `Value`, and on a deep enough one it does not fail — it **aborts the
611628
/// process**. A stack overflow cannot be caught, so the only place to stop
612-
/// it is before serialization starts. Measured: the abort begins somewhere
613-
/// between 831 and 846 levels; the limit here is 128, the same bound
614-
/// `serde_json`'s parser applies, so nothing [`OwnIr::from_json`] can
615-
/// accept is refused.
629+
/// it is before serialization starts.
630+
///
631+
/// **128 is the contract**, and the only depth number that is. It is
632+
/// `serde_json`'s own parser bound, so nothing [`OwnIr::from_json`] can
633+
/// accept is refused here. The depth at which an unguarded serialization
634+
/// would actually abort is a property of one stack size, build profile and
635+
/// platform; useful forensics, not a specification, so it is not written as
636+
/// one.
616637
///
617638
/// # Errors
618639
/// [`OwnIrError`] if a raw value is nested too deeply, or if serialization

‎rust/crates/own-ir/src/protocol.rs‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,16 @@
3030
//!
3131
//! `parse_protocol` refuses a protocol that can never fire (no barriers with
3232
//! `exit_barriers: false`) and one whose barrier equals its `opens` matcher (the
33-
//! walk checks opens first, so the barrier is dead). Both are well-formedness,
34-
//! not shape: every value in such a record has the right type. They are reported
35-
//! as [`OwnIrErrorKind::Shape`] because the six-category taxonomy has no better
36-
//! home, and that imprecision is written down in the ledger rather than
37-
//! smoothed over.
33+
//! walk checks opens first, so the barrier is dead). Every value in such a
34+
//! record has the right type and a legal vocabulary; what is wrong is that the
35+
//! record cannot *mean* anything.
36+
//!
37+
//! They are [`OwnIrErrorKind::WellFormedness`]. An earlier revision reported
38+
//! them as `Shape` on the grounds that the taxonomy was already frozen at six —
39+
//! which got the reasoning backwards. The taxonomy was frozen by the *first*
40+
//! census; this mechanism was found by the *second*. Freezing a category set
41+
//! against later evidence, and then filing new mechanisms under the nearest
42+
//! available name, is the precise substitution the enum was built to stop.
3843
3944
// `unreachable_pub` (denied workspace-wide) and `redundant_pub_crate`
4045
// disagree about a private module's cross-module helpers: the first
@@ -66,6 +71,11 @@ fn vocabulary(message: impl Into<String>) -> OwnIrError {
6671
OwnIrError::new(OwnIrErrorKind::Vocabulary, message)
6772
}
6873

74+
/// Right types, legal vocabulary, and still meaningless — see the module doc.
75+
fn well_formed(message: impl Into<String>) -> OwnIrError {
76+
OwnIrError::new(OwnIrErrorKind::WellFormedness, message)
77+
}
78+
6979
/// One event pattern, in the only form this checkpoint needs: something that can
7080
/// be compared. The `opens in barriers` rule is a value comparison in the
7181
/// reference (a frozen dataclass), so equality here has to mean the same thing —
@@ -118,13 +128,13 @@ pub(crate) fn validate_protocol(raw: &Value) -> Result<&str, OwnIrError> {
118128
}
119129
};
120130
if barriers.is_empty() && !exit_barriers {
121-
return Err(shape(format!(
131+
return Err(well_formed(format!(
122132
"{what}: no barriers and exit_barriers is false — the protocol can \
123133
never fire (a rule that structurally never fires is decoration)"
124134
)));
125135
}
126136
if barriers.contains(&opens) {
127-
return Err(shape(format!(
137+
return Err(well_formed(format!(
128138
"{what}: a barrier equals the 'opens' matcher — the open wins and \
129139
the barrier can never fire (re-entrancy checks are not supported yet)"
130140
)));

‎rust/crates/own-ir/src/strict.rs‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -500,12 +500,18 @@ fn protocol_functions(obj: &Map<String, Value>) -> Checked {
500500
Ok(())
501501
}
502502

503-
/// The nesting depth beyond which a raw [`Value`] is refused.
503+
/// The nesting depth beyond which a raw [`Value`] is refused — the one
504+
/// normative depth number in this crate.
504505
///
505506
/// Deliberately `serde_json`'s own parse limit: a document that could be
506507
/// *parsed* never exceeds it, so this bound rejects nothing
507508
/// [`crate::OwnIr::from_json`] would accept. It exists for values built **in
508509
/// memory**, which never passed a parser and therefore carry no bound at all.
510+
///
511+
/// It matches the parser rather than sitting just under some observed overflow
512+
/// point. Where an unguarded serialization happens to abort depends on stack
513+
/// size, build profile and platform — pinning a contract to that would be
514+
/// pinning it to one machine.
509515
pub(crate) const MAX_VALUE_DEPTH: usize = 128;
510516

511517
/// Depth of a raw value, measured with an explicit stack.

‎rust/crates/own-ir/tests/validation_replay.rs‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -241,14 +241,17 @@ fn every_declared_category_is_exercised_by_a_control() {
241241
"category {name:?} is declared but no control exercises it"
242242
);
243243
}
244-
// …and the port must be able to name every one of them.
244+
// …and the port must be able to name every one of them. This list is
245+
// exhaustive by hand rather than derived, so adding a variant without a
246+
// control — or a control without a variant — fails here.
245247
for kind in [
246248
OwnIrErrorKind::Json,
247249
OwnIrErrorKind::Version,
248250
OwnIrErrorKind::Shape,
249251
OwnIrErrorKind::Vocabulary,
250252
OwnIrErrorKind::Identity,
251253
OwnIrErrorKind::Location,
254+
OwnIrErrorKind::WellFormedness,
252255
] {
253256
assert!(
254257
declared.contains_key(kind.as_str()),
@@ -294,7 +297,7 @@ fn a_deep_in_memory_value_is_refused_rather_than_aborting() {
294297
// caller built in memory.
295298
//
296299
// Depth 200 is chosen deliberately: past the 128 guard, and well inside the
297-
// band where the value can still be built and dropped. See the honesty note
300+
// range where the value can still be built and dropped. See the scope note
298301
// below for why it is not larger.
299302
let mut node = serde_json::json!({"ev": "return", "line": 1});
300303
for _ in 0..200 {
@@ -318,11 +321,17 @@ fn a_deep_in_memory_value_is_refused_rather_than_aborting() {
318321
// through `events`/`flow_columns` would never be the check that fires.
319322
assert!(doc.to_value().is_err(), "to_value must refuse it too");
320323

321-
// HONESTY NOTE, measured rather than assumed: this guard covers depths 129
322-
// to roughly 800. Above ~804 merely DROPPING the value aborts, because
323-
// `serde_json::Value` has a recursive `Drop` — nothing this crate does can
324-
// prevent that, and a test asserting otherwise would abort before it could
325-
// report. The bound stops the serializer, not the type.
324+
// SCOPE NOTE. What the guard promises is exactly this: `to_value()` and
325+
// `validate()` refuse a too-deep value and RETURN, instead of aborting
326+
// inside the serializer. It does not promise that any `Value` a caller
327+
// managed to construct is safe to hold — `serde_json::Value` has a
328+
// recursive `Drop`, so a sufficiently deep one aborts on release before any
329+
// method of this crate is reached. Guaranteeing that would mean not
330+
// representing facts as `serde_json::Value` at all: a representation
331+
// change, and outside cp1.
332+
//
333+
// (Such a case cannot be asserted here anyway — it would abort while the
334+
// test tears down, so the test could never report. Hence 200, not more.)
326335
}
327336

328337
#[test]

0 commit comments

Comments
 (0)