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 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-16 22:31:26 +02:00
commit 5cda0886bd
2 changed files with 116 additions and 0 deletions

View file

@ -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(())
}
}

View file

@ -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(())
}
'@
}
)
}