Skip to content

Commit 4a0e11c

Browse files
committed
docs(ownir): retire five doc claims the rewrite left behind
Review raised one of these as a nitpick against `af6e782`. Checking it against the current tree found four more, all mine, all introduced by not re-reading doc comments after the architecture changed under them. * the crate doc still said the ledger was **191** controls; the seventh category took it to 193. Same number stale in the depth test. * `Subscription::column` said the check "lives in `OwnIr::validate`". It lived in `gate_components` when that was written, and both are gone: it is `strict::column`, reached from `from_json` and `validate` alike. * `OwnIr::protocols` was the bad one. It still read "Record-level validity beyond that is NOT yet mirrored" — the exact claim this PR retracted. The reference CALLS the obligation parser inside `load()` and wraps its errors, so it is part of the door, and the second census measured that supposed boundary as 47 of its 58 permissive documents. The comment was describing the bug as if it were the design. * `OwnIr::protocol_functions` repeated it by reference. Worth naming: the misleading one was not the one review found. It was found by grepping for every stale symbol at once — `gate_*`, `191`, `OwnIr::validate` — rather than fixing the line that was pointed at. A doc comment that survives the code it documents is the same failure class as a test that survives the behaviour it asserts; neither gets re-read just because something near it changed. Refs #250, #259. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CJF7MBi1ijU5m9cJVWgQsM
1 parent 6839a6b commit 4a0e11c

2 files changed

Lines changed: 19 additions & 11 deletions

File tree

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

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
//! `OwnTS`) and the core: a versioned JSON fact vocabulary. This crate is the
55
//! Rust side of that seam. Its acceptance rule mirrors the Python reference
66
//! (`ownlang/ownir.py::load`) — a claim that is **measured**, not asserted:
7-
//! `tests/validation_replay.rs` replays a 191-control Python-authored ledger
7+
//! `tests/validation_replay.rs` replays a 193-control Python-authored ledger
88
//! and requires zero Rust-only accepts, zero Rust-only rejects and zero
99
//! error-category mismatches.
1010
//!
@@ -294,7 +294,8 @@ pub struct Subscription {
294294
/// rejections, but every one of them reported as [`OwnIrErrorKind::Shape`],
295295
/// when the contract being violated is the 1-based coordinate rule. The
296296
/// implementation mechanism must not pick the semantic category, so the
297-
/// check lives in [`OwnIr::validate`] where it can answer `Location`.
297+
/// check lives in the `strict` module — reached from [`OwnIr::from_json`]
298+
/// and [`OwnIr::validate`] alike — where it can answer `Location`.
298299
#[serde(default, skip_serializing_if = "Option::is_none")]
299300
pub column: Option<Value>,
300301
#[serde(flatten)]
@@ -528,20 +529,27 @@ pub struct OwnIr {
528529
skip_serializing_if = "Option::is_none"
529530
)]
530531
pub functions: Option<Vec<Function>>,
531-
/// Obligation-protocol declarations. Held as raw values: the reference
532-
/// checks only that this is a LIST here and delegates each record to the
533-
/// shared obligation parser, which is a separate surface with its own
534-
/// vocabulary. What this crate owns from it is the identity invariant —
535-
/// see [`OwnIr::validate`]. Record-level validity beyond that is NOT yet
536-
/// mirrored; documented in the ledger rather than silently assumed.
532+
/// Obligation-protocol declarations. Held as raw values because nothing
533+
/// consumes a typed representation yet — not because the records go
534+
/// unchecked.
535+
///
536+
/// The reference checks only list-ness *here* and delegates each record to
537+
/// the shared obligation parser. That parser is called by `load()` and its
538+
/// errors are wrapped as `OwnIRError`, so it is part of the strict-door
539+
/// contract, and its **acceptance grammar** is ported in `protocol.rs`. An
540+
/// earlier revision of this comment called record validity a delegated
541+
/// boundary "not yet mirrored"; the second census measured that as a hole
542+
/// in the door worth 47 of its 58 permissive documents. Protocol
543+
/// *analysis* — the lattice, the walker, verdicts — is still absent, and
544+
/// that one is a real boundary.
537545
#[serde(
538546
default,
539547
deserialize_with = "reject_null",
540548
skip_serializing_if = "Option::is_none"
541549
)]
542550
pub protocols: Option<Vec<Value>>,
543-
/// Per-method protocol facts. Same delegation as `protocols`: list shape
544-
/// here, record parsing elsewhere.
551+
/// Per-method protocol facts. Same arrangement as `protocols`: list shape
552+
/// here, the event-tree grammar in `protocol.rs`, no analysis anywhere.
545553
#[serde(
546554
default,
547555
deserialize_with = "reject_null",

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,7 @@ fn the_depth_guard_never_fires_on_a_document_from_json_accepts() {
342342
// the reference.
343343
//
344344
// The ledger alone cannot check this: every control is a handful of levels
345-
// deep, so a guard set to 16 would pass against all 191 of them. Measured —
345+
// deep, so a guard set to 16 would pass against all 193 of them. Measured —
346346
// that mutation SURVIVED until this document was added. So the test builds
347347
// the deepest document `from_json` still accepts and pins the guard above
348348
// it.

0 commit comments

Comments
 (0)