From 5cda0886bd937b9df18309de7f505029d0e41f4d Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 16 Sep 2026 22:31:26 +0200 Subject: [PATCH] Open one door onto the reference grammar Ruling 1 leaves the schemas and the key grammar with the leaf, and the read side in Huginn must refuse a `PipelineRef` whose kind and id disagree rather than answer the nothing a lookup finds. `Bounded` is `pub(crate)`, so nothing outside could ask. `PipelineRef::validate_ref` delegates to that impl at the field name `ref`, so the grammar keeps one owner and the wrappers and `pipeline_id` stay where they are. A method, as `prepare` and `decode` are, because it concerns one public type; `validate_ref` rather than a bare `validate`, because an inherent `validate` would shadow `Bounded`'s for every in-crate holder of a `PipelineRef`. The test holds every sample document's own key to be a reference of its own kind, and refuses a kind that is not the id's and a trailing dot at `ref.id`. It also pins the boundary rather than assuming it: a resolution id missing the per-subject sequence its writer always composes is still well formed here. The leaf reads an id kind-deep, and the local's per-kind shape is admission's rule. Entries R1 and R2 in `tools/eureka-cut8-epiphany-mutations.psd1`: the door that answers `Ok(())` to everything, and the door that reads the kind segment alone. `cargo test -p epiphany-pipeline --lib` 34 passed, 0 warnings; `cargo check -p epiphany-core --lib --tests` clean; the four Epiphany suites green-and-killed through the harness. No schema and no lock moved. Co-Authored-By: Claude Fable 5.1 --- epiphany-pipeline/src/lib.rs | 78 +++++++++++++++++++++++ tools/eureka-cut8-epiphany-mutations.psd1 | 38 +++++++++++ 2 files changed, 116 insertions(+) diff --git a/epiphany-pipeline/src/lib.rs b/epiphany-pipeline/src/lib.rs index 85ab3445..d321bc9a 100644 --- a/epiphany-pipeline/src/lib.rs +++ b/epiphany-pipeline/src/lib.rs @@ -409,6 +409,27 @@ impl Bounded for PipelineRef { } } +impl PipelineRef { + /// The grammar's door for a reader holding a bare reference. A read side + /// outside this crate is handed a `kind` and an `id` that may disagree, and + /// `Bounded` is crate-private, so without this there is no way to ask; a + /// reader with no way to ask answers empty, which reads as "no such + /// document" rather than "that is not a reference". It delegates, so the + /// grammar keeps one owner: this is exactly what a document's own + /// `PipelineRef` field is held to, at the field name `ref`. It is kind-deep, + /// like every other read of an id: whether the named document exists, and + /// whether the local's shape suits the kind, are admission's rules. + /// + /// A method rather than a free function because it concerns one public + /// type, as `prepare` and `decode` do; the two free doors act on a cache or + /// an envelope this crate does not own. `validate_ref` rather than a bare + /// `validate`, because an inherent `validate` would shadow `Bounded`'s for + /// every in-crate caller holding a `PipelineRef`. + pub fn validate_ref(&self) -> Result<(), PipelineRefusal> { + self.validate("ref") + } +} + /// How a subject was resolved. Every referent is a parsed `PipelineRef`, so a /// resolution names its records by ids of the kinds they declare, validated /// where every other referent is; a `Fixed` commit is a `Sha` whose referent @@ -2363,4 +2384,61 @@ mod tests { } Ok(()) } + + /// The public door onto the reference grammar, for the read side that + /// holds a `kind` and an `id` and no way to reach `Bounded`. Every sample + /// document's own key is a reference of its own kind; a kind that is not + /// the id's, and a local no writer composes, are `InvalidFormat` at `ref.id`. + #[test] + fn a_ref_validates_as_an_id_of_the_kind_it_declares() -> Result<()> { + for (document, expected) in samples() { + let kind = document.kind(); + let key = pipeline_key(&document)?; + assert_eq!(key, expected); + assert_eq!( + PipelineRef { kind, id: s(&key) }.validate_ref(), + Ok(()), + "{kind:?}'s own key is not a reference of its kind" + ); + } + + let refused = |reference: PipelineRef, why: &str| { + let read = reference.validate_ref(); + assert!( + matches!(&read, Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "ref.id"), + "{why}: {reference:?} was not refused, got {read:?}" + ); + }; + + // The kind and the id's kind segment cannot disagree: the whole reason + // the door exists, since a reader that cannot ask would look this up + // and report the nothing it found. + refused( + PipelineRef { kind: PipelineKind::Campaign, id: id("question", "Q1") }, + "a question id is not a campaign reference", + ); + refused( + PipelineRef { kind: PipelineKind::Ruling, id: id("question", "Q1") }, + "a question id is not a ruling reference", + ); + // The local is `dotted_text` whole, so a trailing dot is refused by the + // reader and not only by the writer that never composes one. + refused( + PipelineRef { kind: PipelineKind::Question, id: s(&format!("{CAMPAIGN}:question:Q1.")) }, + "a trailing dot is no local", + ); + + // The boundary, pinned rather than assumed: a resolution id missing the + // per-subject sequence its writer always composes is still a + // well-formed id of its kind here. The leaf's grammar is kind-deep, and + // the local's per-kind shape belongs to admission; refusing this would + // be a new rule in `pipeline_id`, not a door onto the one that exists. + assert_eq!( + PipelineRef { kind: PipelineKind::Resolution, id: s(&format!("{CAMPAIGN}:resolution:question.Q1")) } + .validate_ref(), + Ok(()), + "the leaf reads a resolution id kind-deep" + ); + Ok(()) + } } diff --git a/tools/eureka-cut8-epiphany-mutations.psd1 b/tools/eureka-cut8-epiphany-mutations.psd1 index 2399ed1c..525a959b 100644 --- a/tools/eureka-cut8-epiphany-mutations.psd1 +++ b/tools/eureka-cut8-epiphany-mutations.psd1 @@ -17,6 +17,11 @@ # reader dispatches on is asserted against `PipelineKind::name()` for every # kind, and every refusal variant is round-tripped whole, so a field that # leaves the wire comes back empty and is not the refusal that went out. +# +# R1 and R2 are the public reference door, and both are killed by +# `a_ref_validates_as_an_id_of_the_kind_it_declares`: a kind that is not the +# id's kills the door that answers Ok to everything, and a trailing dot kills +# the door that reads the kind segment and nothing else. @{ Mutations = @( @{ @@ -61,6 +66,39 @@ Test = 'tests::every_document_and_refusal_serialises_and_reads_back' Old = ' FieldBound { field: String, limit: u32, actual: u32 },' New = ' FieldBound { #[serde(skip)] field: String, limit: u32, actual: u32 },' + }, + @{ + Id = 'R1' + Rule = 'The public door is the grammar, not a formality: a door that answers Ok to every reference leaves the read side unable to tell a malformed reference from a missing document.' + Test = 'tests::a_ref_validates_as_an_id_of_the_kind_it_declares' + Old = @' + pub fn validate_ref(&self) -> Result<(), PipelineRefusal> { + self.validate("ref") + } +'@ + New = @' + pub fn validate_ref(&self) -> Result<(), PipelineRefusal> { + Ok(()) + } +'@ + }, + @{ + Id = 'R2' + Rule = 'The door delegates to the one grammar: a door that checks the kind segment alone admits a local no writer composes, and the reference grammar has two owners.' + Test = 'tests::a_ref_validates_as_an_id_of_the_kind_it_declares' + Old = @' + pub fn validate_ref(&self) -> Result<(), PipelineRefusal> { + self.validate("ref") + } +'@ + New = @' + pub fn validate_ref(&self) -> Result<(), PipelineRefusal> { + if self.id.0.split(':').nth(1) != Some(self.kind.name()) { + return Err(format_error("ref.id", &self.id.0)); + } + Ok(()) + } +'@ } ) }