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>
2444 lines
124 KiB
Rust
2444 lines
124 KiB
Rust
//! Eureka pipeline documents: the typed shape of a Eureka campaign's state.
|
||
//!
|
||
//! This is a leaf type library, and deliberately nothing else. It owns document
|
||
//! shape, field bounds, formats, key derivation and the JSON schemas published
|
||
//! under `schemas/cultnet`; it owns no storage, no admission, no process and no
|
||
//! network. That is the whole reason it is a package: the organ that will admit
|
||
//! these documents depends on these types without depending on the harness
|
||
//! that used to hold them.
|
||
//!
|
||
//! Every kind is a plain `serde` + `JsonSchema` value inside a one-slot
|
||
//! `DatabaseEntry` wrapper, always prepared with `prepare_entry_named`, so the
|
||
//! stored payload is `[value]` and the value is the named map the published
|
||
//! schema describes. Keys are semantic: `pipeline_key` derives them from the
|
||
//! value, and the write validator refuses any envelope whose key differs.
|
||
//!
|
||
//! Every key is `<root>:<kind>:<local>`, three segments for every kind with
|
||
//! none excused: the root is a `Slug`, the kind is the literal kind name, and
|
||
//! the local is `Label`s joined by `.`, so no local part carries a dot and a
|
||
//! reader recovers the parts by splitting. A root's local is the constant
|
||
//! `self`; a resolution's local is its subject's kind and local. A
|
||
//! resolution's local ends in its per-subject sequence, `n<N>`, and a
|
||
//! stewardship's in its per-repo sequence, so a subject's resolutions and a
|
||
//! repo's assignments each share a prefix.
|
||
//!
|
||
//! **Validation follows the type.** `value_types!` is the single field list: it
|
||
//! emits the struct and its `Bounded` impl from the same tokens, so a field
|
||
//! cannot be declared without being validated. Format rules live in the field's
|
||
//! type (`Label`, `Slug`, `OrgRepo`, `Sha`, `Sha256Hex`, `Date`), never in a
|
||
//! hand-written impl that a later field can slip past. A `Vec` field must carry
|
||
//! a maximum, because `Vec<T>` has no `Bounded` impl of its own.
|
||
//!
|
||
//! The wrappers are crate-private: outside code registers, prepares and
|
||
//! decodes them through `register_pipeline_document_types`,
|
||
//! `PipelineDocument::prepare` and `PipelineDocument::decode`, and validates a
|
||
//! write through `validate_pipeline_write_envelope`.
|
||
|
||
// `anyhow` is the cache's own error type, which `prepare` and the registrar
|
||
// pass through; every refusal this crate decides is a `PipelineRefusal`.
|
||
use anyhow::Result;
|
||
use cultcache_rs::{CultCache, CultCacheEnvelope, DatabaseEntry};
|
||
use schemars::JsonSchema;
|
||
use serde::{Deserialize, Serialize};
|
||
|
||
/// Typed refusals of the pipeline documents: bounds, formats and key identity
|
||
/// (D2's document half), and `ForeignStore`, raised by `decode` for an
|
||
/// envelope of any other type. This is every refusal the leaf decides; a
|
||
/// store's identity and its schema epoch are not decided here, since this
|
||
/// crate owns no store, and belong to the organ that will admit these
|
||
/// documents.
|
||
///
|
||
/// Serialised externally tagged, serde's default for an enum: each variant is
|
||
/// a one-key map from the variant's name to its named fields, so `field` and
|
||
/// `value` are on the wire under their own names and a reader of a refusal
|
||
/// carried over a wire reads the same parts a local caller matches on. No
|
||
/// attribute buys that, which is why there is none: an internal or adjacent
|
||
/// tag would move the fields under a content key without making any of them
|
||
/// more visible.
|
||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||
pub enum PipelineRefusal {
|
||
FieldBound { field: String, limit: u32, actual: u32 },
|
||
InvalidFormat { field: String, value: String },
|
||
InvalidIdentity { kind: PipelineKind, key: String, expected: String },
|
||
ForeignStore { r#type: String },
|
||
}
|
||
|
||
impl std::fmt::Display for PipelineRefusal {
|
||
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||
write!(formatter, "pipeline refusal: {self:?}")
|
||
}
|
||
}
|
||
|
||
impl std::error::Error for PipelineRefusal {}
|
||
|
||
pub(crate) trait Bounded {
|
||
fn validate(&self, field: &str) -> Result<(), PipelineRefusal>;
|
||
}
|
||
|
||
impl<T: Bounded> Bounded for Option<T> {
|
||
fn validate(&self, field: &str) -> Result<(), PipelineRefusal> {
|
||
self.as_ref().map_or(Ok(()), |value| value.validate(field))
|
||
}
|
||
}
|
||
|
||
macro_rules! unbounded_scalars {
|
||
($($ty:ty),* $(,)?) => {$(
|
||
impl Bounded for $ty {
|
||
fn validate(&self, _field: &str) -> Result<(), PipelineRefusal> {
|
||
Ok(())
|
||
}
|
||
}
|
||
)*};
|
||
}
|
||
|
||
unbounded_scalars!(u32, u64, bool);
|
||
|
||
fn bound(field: &str, limit: usize, actual: usize) -> Result<(), PipelineRefusal> {
|
||
if actual > limit {
|
||
return Err(PipelineRefusal::FieldBound {
|
||
field: field.into(),
|
||
limit: limit as u32,
|
||
actual: actual as u32,
|
||
});
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
/// List maximums only. Minimum counts are admission rules with their own
|
||
/// refusals (Cut 3b), so a bounds pass never pre-empts them.
|
||
fn list<T: Bounded>(field: &str, items: &[T], max: usize) -> Result<(), PipelineRefusal> {
|
||
bound(field, max, items.len())?;
|
||
for (index, item) in items.iter().enumerate() {
|
||
item.validate(&format!("{field}[{index}]"))?;
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
fn format_error(field: &str, value: &str) -> PipelineRefusal {
|
||
PipelineRefusal::InvalidFormat {
|
||
field: field.into(),
|
||
value: value.into(),
|
||
}
|
||
}
|
||
|
||
fn hex(field: &str, value: &str, lengths: std::ops::RangeInclusive<usize>) -> Result<(), PipelineRefusal> {
|
||
let lower_hex = value.bytes().all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'));
|
||
if !lengths.contains(&value.len()) || !lower_hex {
|
||
return Err(format_error(field, value));
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
/// A key label: `[A-Za-z0-9_-]{1,64}`. Dots are excluded so that a composed key
|
||
/// segments unambiguously; see `local`.
|
||
fn label_text(field: &str, value: &str) -> Result<(), PipelineRefusal> {
|
||
let valid = value
|
||
.bytes()
|
||
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'));
|
||
if !valid || value.is_empty() || value.len() > 64 {
|
||
return Err(format_error(field, value));
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
/// A dotted key segment: label parts joined by `.`, at most 64 bytes. Every
|
||
/// part must be a label, so `..`, a leading or trailing dot, and an empty part
|
||
/// are all refused.
|
||
fn dotted_text(field: &str, value: &str) -> Result<(), PipelineRefusal> {
|
||
if value.is_empty() || value.len() > 64 {
|
||
return Err(format_error(field, value));
|
||
}
|
||
for part in value.split('.') {
|
||
label_text(field, part)?;
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
fn org_repo_text(field: &str, value: &str) -> Result<(), PipelineRefusal> {
|
||
match value.split_once('/') {
|
||
Some((org, repo))
|
||
if !org.is_empty() && !repo.is_empty() && !repo.contains('/') && value.len() <= 200 =>
|
||
{
|
||
Ok(())
|
||
}
|
||
_ => Err(format_error(field, value)),
|
||
}
|
||
}
|
||
|
||
macro_rules! bounded_text {
|
||
($($(#[$doc:meta])* $name:ident = $limit:literal, $check:expr;)*) => {$(
|
||
$(#[$doc])*
|
||
#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema)]
|
||
#[serde(transparent)]
|
||
#[schemars(extend("maxLength" = $limit))]
|
||
pub struct $name(pub String);
|
||
impl Bounded for $name {
|
||
fn validate(&self, field: &str) -> Result<(), PipelineRefusal> {
|
||
let check: fn(&str, &str) -> Result<(), PipelineRefusal> = $check;
|
||
check(field, &self.0)
|
||
}
|
||
}
|
||
impl From<&str> for $name {
|
||
fn from(value: &str) -> Self {
|
||
Self(value.into())
|
||
}
|
||
}
|
||
)*};
|
||
}
|
||
|
||
fn within(limit: usize) -> impl Fn(&str, &str) -> Result<(), PipelineRefusal> {
|
||
move |field: &str, value: &str| bound(field, limit, value.len())
|
||
}
|
||
|
||
bounded_text! {
|
||
/// Text of at most 200 UTF-8 bytes.
|
||
Short = 200, |field, value| within(200)(field, value);
|
||
/// Text of at most 1,000 UTF-8 bytes.
|
||
Line = 1000, |field, value| within(1000)(field, value);
|
||
/// Text of at most 4,000 UTF-8 bytes; longer narrative is cited by `DocRef`.
|
||
Para = 4000, |field, value| within(4000)(field, value);
|
||
/// A key label: `[A-Za-z0-9_-]{1,64}`.
|
||
Label = 64, label_text;
|
||
/// A campaign slug or key segment: label parts joined by `.`.
|
||
Slug = 64, dotted_text;
|
||
/// A GitHub repository as `Org/Repo`.
|
||
OrgRepo = 200, org_repo_text;
|
||
/// A git commit id: 7-40 lowercase hex characters.
|
||
Sha = 40, |field, value| hex(field, value, 7..=40);
|
||
/// A full git commit id: exactly 40 lowercase hex characters.
|
||
FullSha = 40, |field, value| hex(field, value, 40..=40);
|
||
/// A SHA-256 digest: exactly 64 lowercase hex characters.
|
||
Sha256Hex = 64, |field, value| hex(field, value, 64..=64);
|
||
}
|
||
|
||
/// A calendar date, `YYYY-MM-DD`.
|
||
#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema)]
|
||
#[serde(transparent)]
|
||
#[schemars(extend("maxLength" = 10))]
|
||
pub struct Date(pub String);
|
||
|
||
impl Bounded for Date {
|
||
fn validate(&self, field: &str) -> Result<(), PipelineRefusal> {
|
||
match chrono::NaiveDate::parse_from_str(&self.0, "%Y-%m-%d") {
|
||
Ok(_) if self.0.len() == 10 => Ok(()),
|
||
_ => Err(format_error(field, &self.0)),
|
||
}
|
||
}
|
||
}
|
||
|
||
macro_rules! bounded_field {
|
||
($value:expr, $field:expr) => {
|
||
Bounded::validate(&$value, $field)?
|
||
};
|
||
($value:expr, $field:expr, $max:literal) => {
|
||
list($field, &$value, $max)?
|
||
};
|
||
}
|
||
|
||
/// The single field list: one invocation emits the value struct and its
|
||
/// `Bounded` impl, so a field can never be left out of validation.
|
||
macro_rules! value_types {
|
||
($($(#[$attr:meta])* pub struct $name:ident { $($field:ident: $ty:ty $([$max:literal])?),* $(,)? })*) => {$(
|
||
$(#[$attr])*
|
||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||
pub struct $name {
|
||
$(
|
||
$(#[schemars(extend("maxItems" = $max))])?
|
||
pub $field: $ty
|
||
),*
|
||
}
|
||
|
||
impl Bounded for $name {
|
||
fn validate(&self, at: &str) -> Result<(), PipelineRefusal> {
|
||
$(bounded_field!(self.$field, &format!("{at}.{}", stringify!($field)) $(, $max)?);)*
|
||
Ok(())
|
||
}
|
||
}
|
||
)*};
|
||
}
|
||
|
||
macro_rules! unit_enums {
|
||
($($name:ident { $($variant:ident),* $(,)? })*) => {$(
|
||
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema)]
|
||
pub enum $name { $($variant),* }
|
||
impl Bounded for $name {
|
||
fn validate(&self, _field: &str) -> Result<(), PipelineRefusal> {
|
||
Ok(())
|
||
}
|
||
}
|
||
)*};
|
||
}
|
||
|
||
unit_enums! {
|
||
EvidenceKind { Command, Test, Mutation, Probe, SourceRead, Capture }
|
||
ClaimOutcome { Holds, Falsified, Unproven }
|
||
FindingConfidence { Confirmed, Plausible }
|
||
FindingSeverity { Blocker, High, Medium, Low }
|
||
RulingAuthority { Operator, Standing, Defaulted }
|
||
FindingOrigin { Introduced, PreExisting }
|
||
}
|
||
|
||
value_types! {
|
||
pub struct CodeLocation { path: Short, line: u32, end_line: Option<u32> }
|
||
pub struct CommitRange { base: Sha, head: Sha }
|
||
pub struct Evidence { kind: EvidenceKind, locator: Line, result: Line }
|
||
/// A citation of a document in another repo's pipeline store (D6).
|
||
pub struct ForeignRef { repo: OrgRepo, commit: FullSha, kind: PipelineKind, id: Short, payload_sha256: Sha256Hex }
|
||
pub struct DocRef { path: Short, start_line: u32, end_line: u32, commit: Sha }
|
||
pub struct TargetInvariant { label: Label, statement: Line }
|
||
pub struct QuestionOption { label: Label, text: Line }
|
||
pub struct CutDelete { path: Short, lines: u32, note: Line }
|
||
pub struct FileChange { location: CodeLocation, change: Line }
|
||
pub struct AuthorityMap {
|
||
owner: Line, inputs: Vec<Line>[16], outputs: Vec<Line>[16], derived_state: Vec<Line>[16],
|
||
forbidden_writers: Vec<Line>[16], shared_paths: Vec<Line>[16], deletion_line: Line,
|
||
}
|
||
pub struct VerificationTest { name: Short, pins: Line }
|
||
pub struct NegativeCheck { pattern: Short, scope: Line }
|
||
pub struct CutVerification {
|
||
builds: Vec<Line>[64], tests: Vec<VerificationTest>[64],
|
||
negative: Vec<NegativeCheck>[64], operator: Vec<Line>[64],
|
||
}
|
||
pub struct ReportCommit { sha: Sha, subject: Line, builds: bool }
|
||
/// One mutation a report ran: a key-safe label a verdict claim can name,
|
||
/// the exact edit, and the tree it was applied to.
|
||
pub struct MutationRecord { label: Label, rule: Line, location: CodeLocation, before: Line, after: Line, commit: Sha, failed_as_expected: bool }
|
||
pub struct Deviation { what: Line, why: Line }
|
||
// D1 tables no maximum for these lists, so they take the shared list
|
||
// default of 64 rather than a number invented for this field alone.
|
||
pub struct StructuralDelta {
|
||
lines_added: u32, lines_removed: u32,
|
||
dependencies_added: Vec<Short>[64], dependencies_removed: Vec<Short>[64],
|
||
formats_added: Vec<Short>[64], formats_removed: Vec<Short>[64],
|
||
targets_added: Vec<Short>[64], targets_removed: Vec<Short>[64],
|
||
}
|
||
/// A name the cut landed, and where it lives.
|
||
pub struct LandedName { name: Short, path: Short }
|
||
/// A promise a report makes about what it landed. Not a document and not
|
||
/// resolvable: it is identified by its report's id and its label, as a
|
||
/// `TargetInvariant` is by its target's. Soul measures every one (ruling
|
||
/// A), and the rule that every one is measured is admission's.
|
||
pub struct Promise { label: Label, text: Line }
|
||
/// The promise this claim measured, and the report's mutations it ran. An
|
||
/// `Unproven` claim with a promise is one Soul could not reach.
|
||
pub struct VerdictClaim {
|
||
claim: Line, outcome: ClaimOutcome, evidence: Vec<Evidence>[8], findings: Vec<Short>[16],
|
||
promise: Option<Label>, mutations: Vec<Label>[8],
|
||
}
|
||
|
||
pub struct PipelineCampaign { slug: Slug, title: Short, repos: Vec<OrgRepo>[8], working_branch: Short, target_doc: DocRef }
|
||
pub struct PipelineTarget {
|
||
campaign: Slug, revision: u32, invariants: Vec<TargetInvariant>[32], not_in_scope: Vec<Line>[32],
|
||
canonical_implementations: Vec<Line>[16], doc: DocRef,
|
||
}
|
||
pub struct PipelineQuestion {
|
||
campaign: Slug, label: Label, question: Para, options: Vec<QuestionOption>[8], recommended: Label,
|
||
depends: Vec<Line>[8], raised_in: Option<PipelineRef>, asked_on: Date,
|
||
}
|
||
pub struct PipelineRuling {
|
||
campaign: Slug, label: Label, answers: Option<Short>, choice: Option<Label>, ruling: Para,
|
||
operator_quote: Option<Para>, ruled_on: Date, precedents: Vec<ForeignRef>[8], authority: RulingAuthority,
|
||
}
|
||
pub struct PipelineCutSpec {
|
||
campaign: Slug, cut: Label, revision: u32, title: Short, repo: OrgRepo, branch: Short, base: Sha,
|
||
depends_on: Vec<Short>[8], first: Vec<Line>[16], deletes: Vec<CutDelete>[64], keeps_moves: Vec<Line>[64],
|
||
adds: Vec<Line>[64], file_changes: Vec<FileChange>[256], authority_map: Option<AuthorityMap>,
|
||
verification: CutVerification, estimate: StructuralDelta,
|
||
rulings: Vec<Short>[32], questions: Vec<Short>[16],
|
||
}
|
||
pub struct PipelineCutReport {
|
||
campaign: Slug, cut_spec: Short, attempt: u32, repo: OrgRepo, branch: Short,
|
||
commits: Vec<ReportCommit>[128], range: CommitRange, verification: Vec<Evidence>[64],
|
||
mutations: Vec<MutationRecord>[64], deviations: Vec<Deviation>[32], forks: Vec<Short>[8],
|
||
structural_delta: StructuralDelta, landed_names: Vec<LandedName>[128], undone: Vec<Line>[32],
|
||
promises: Vec<Promise>[64],
|
||
}
|
||
pub struct PipelineVerdict { campaign: Slug, cut_report: Short, pass: u32, range: CommitRange, claims: Vec<VerdictClaim>[64] }
|
||
pub struct PipelineFinding {
|
||
campaign: Slug, verdict: Short, label: Label, range: CommitRange, confidence: FindingConfidence,
|
||
severity: FindingSeverity, claim: Line, invariants: Vec<Label>[8], locations: Vec<CodeLocation>[16],
|
||
failure_scenario: Para, evidence: Vec<Evidence>[16], precedents: Vec<ForeignRef>[8], origin: FindingOrigin,
|
||
}
|
||
pub struct PipelineFollowUp {
|
||
campaign: Slug, label: Label, source: PipelineRef, repo: OrgRepo, locations: Vec<CodeLocation>[16],
|
||
item: Line, why_it_can_wait: Line, owner: Short,
|
||
}
|
||
/// The record of how a subject was closed and by what. `sequence` is per
|
||
/// subject and set by the writer, `1` for the first, and it is the last
|
||
/// part of the key, so a subject's resolutions share a prefix and a
|
||
/// withdrawn one is kept under its subject rather than overwritten.
|
||
/// Whether a sequence is the previous plus one, and whether an earlier
|
||
/// resolution still stands, are admission's rules: this crate refuses
|
||
/// neither `0` nor a gap, exactly as it refuses neither `revision: 0` nor
|
||
/// a `revision` with no predecessor.
|
||
pub struct PipelineResolution { subject: PipelineRef, sequence: u32, outcome: ResolutionOutcome, rationale: Para, resolved_on: Date }
|
||
|
||
/// A mind's identity document. A store is canonical to exactly one
|
||
/// instance, and this says which; identity lives in the state, not in a
|
||
/// path.
|
||
pub struct PipelineInstance { instance: Slug, display_name: Short, created_at: Date, host: Short }
|
||
/// Stewardship over a repo, as an assignment recorded in a mind. One
|
||
/// instance may steward several repos, so the repo is part of the key.
|
||
/// `sequence` is per `(instance, repo)`, set by the writer, `1` for the
|
||
/// first, so a repo transferred away and back is two records under one
|
||
/// prefix rather than one document overwriting the other. `assigned_on`
|
||
/// is a field, not a key part. As on a resolution, whether the sequence
|
||
/// is the previous plus one, and which assignment is in force, are
|
||
/// admission's rules and not this crate's.
|
||
pub struct PipelineStewardship { instance: Slug, repo: OrgRepo, sequence: u32, assigned_on: Date, note: Line }
|
||
/// A reassignment of stewardship, recorded in both minds. `documents` names
|
||
/// what travels with it.
|
||
pub struct PipelineHandOff {
|
||
from_instance: Slug, to_instance: Slug, repo: OrgRepo, documents: Vec<Short>[256],
|
||
reason: Para, handed_on: Date,
|
||
}
|
||
}
|
||
|
||
/// A reference to another document. The id is parsed as a full pipeline id of
|
||
/// the declared `kind`, so the kind and the id's kind segment cannot disagree.
|
||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||
pub struct PipelineRef {
|
||
pub kind: PipelineKind,
|
||
pub id: Short,
|
||
}
|
||
|
||
impl Bounded for PipelineRef {
|
||
fn validate(&self, at: &str) -> Result<(), PipelineRefusal> {
|
||
self.id.validate(&format!("{at}.id"))?;
|
||
pipeline_id(&format!("{at}.id"), &self.id.0, self.kind).map(|_| ())
|
||
}
|
||
}
|
||
|
||
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
|
||
/// is outside the document set (ruling B). Whether a named document exists,
|
||
/// and how many may supersede one subject, are admission's rules.
|
||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||
pub enum ResolutionOutcome {
|
||
/// Overturned, in whole or in part, by later records. The list is bounded
|
||
/// here because the enum is outside `value_types!`, the only place a list
|
||
/// maximum is emitted automatically.
|
||
Superseded {
|
||
#[schemars(extend("maxItems" = 8))]
|
||
by: Vec<PipelineRef>,
|
||
},
|
||
Answered { by: PipelineRef },
|
||
Fixed { commit: Sha, by: Option<PipelineRef> },
|
||
Deferred { to: PipelineRef },
|
||
Recorded { reason: Line },
|
||
Withdrawn { reason: Line },
|
||
}
|
||
|
||
impl Bounded for ResolutionOutcome {
|
||
fn validate(&self, field: &str) -> Result<(), PipelineRefusal> {
|
||
match self {
|
||
Self::Superseded { by } => list(&format!("{field}.by"), by, 8),
|
||
Self::Answered { by } => by.validate(&format!("{field}.by")),
|
||
Self::Fixed { commit, by } => {
|
||
commit.validate(&format!("{field}.commit"))?;
|
||
by.validate(&format!("{field}.by"))
|
||
}
|
||
Self::Deferred { to } => to.validate(&format!("{field}.to")),
|
||
Self::Recorded { reason } | Self::Withdrawn { reason } => reason.validate(&format!("{field}.reason")),
|
||
}
|
||
}
|
||
}
|
||
|
||
macro_rules! pipeline_kinds {
|
||
($($variant:ident($value:ident) => $document:ident, $name:literal, $type_id:tt, $schema:tt;)*) => {
|
||
$(
|
||
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
|
||
#[cultcache(type = $type_id, schema = $schema)]
|
||
pub(crate) struct $document {
|
||
#[cultcache(key = 0)]
|
||
pub(crate) value: $value,
|
||
}
|
||
)*
|
||
|
||
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema)]
|
||
pub enum PipelineKind { $($variant),* }
|
||
|
||
impl Bounded for PipelineKind {
|
||
fn validate(&self, _field: &str) -> Result<(), PipelineRefusal> {
|
||
Ok(())
|
||
}
|
||
}
|
||
|
||
/// The envelope enum, adjacently tagged on the kind name: a document
|
||
/// on a wire is `{ kind, value }`, and `kind` is exactly what
|
||
/// `PipelineKind::name()` returns, so a reader dispatches on the kind
|
||
/// segment it already knows from the key and needs no second registry
|
||
/// mapping variant spellings to kinds. Adjacent rather than internal
|
||
/// because a value is a named map of its own and an internal tag would
|
||
/// have to be merged into it; the tag stays beside the value instead.
|
||
/// This is not a published schema: `schemas/cultnet` publishes the
|
||
/// thirteen per-kind value documents, and the envelope is the wire's
|
||
/// shape, not a document's.
|
||
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
|
||
#[serde(tag = "kind", content = "value", rename_all = "snake_case")]
|
||
pub enum PipelineDocument { $($variant($value)),* }
|
||
|
||
impl PipelineKind {
|
||
pub const ALL: &'static [PipelineKind] = &[$(Self::$variant),*];
|
||
|
||
/// The kind segment of a document key.
|
||
pub fn name(self) -> &'static str {
|
||
match self { $(Self::$variant => $name),* }
|
||
}
|
||
|
||
pub fn type_id(self) -> &'static str {
|
||
match self { $(Self::$variant => <$document as DatabaseEntry>::TYPE),* }
|
||
}
|
||
|
||
#[cfg(test)]
|
||
pub(crate) fn derived_schema(self) -> schemars::Schema {
|
||
match self { $(Self::$variant => schemars::schema_for!($value)),* }
|
||
}
|
||
}
|
||
|
||
impl PipelineDocument {
|
||
pub fn kind(&self) -> PipelineKind {
|
||
match self { $(Self::$variant(_) => PipelineKind::$variant),* }
|
||
}
|
||
|
||
/// Field bounds and formats (D1), in UTF-8 bytes and list maximums.
|
||
pub fn validate(&self) -> Result<(), PipelineRefusal> {
|
||
match self { $(Self::$variant(value) => value.validate($name)),* }
|
||
}
|
||
|
||
/// Prepares the envelope to be stored: keyed by `pipeline_key`,
|
||
/// payload `[value]` through `prepare_entry_named`.
|
||
pub fn prepare(&self, cache: &CultCache) -> Result<CultCacheEnvelope> {
|
||
let key = pipeline_key(self)?;
|
||
Ok(match self {
|
||
$(Self::$variant(value) => {
|
||
cache.prepare_entry_named(key, &$document { value: value.clone() })?.0
|
||
})*
|
||
})
|
||
}
|
||
|
||
/// Decodes a stored envelope, type-matched both ways: an envelope of
|
||
/// any other type is `ForeignStore`, never the kind that happens to
|
||
/// parse its payload. It validates neither bounds nor the key: a
|
||
/// decoded document is a typed read, and
|
||
/// `validate_pipeline_write_envelope` is the check before a write.
|
||
pub fn decode(envelope: &CultCacheEnvelope) -> Result<Self, PipelineRefusal> {
|
||
let invalid = |error: rmp_serde::decode::Error| format_error("payload", &error.to_string());
|
||
$(if envelope.r#type == <$document as DatabaseEntry>::TYPE {
|
||
let document: $document = rmp_serde::from_slice(&envelope.payload).map_err(invalid)?;
|
||
return Ok(Self::$variant(document.value));
|
||
})*
|
||
Err(PipelineRefusal::ForeignStore { r#type: envelope.r#type.clone() })
|
||
}
|
||
}
|
||
|
||
/// Registers every pipeline kind in a cache, and nothing else: the one
|
||
/// door to the crate-private wrappers, so a caller registers exactly
|
||
/// what this crate publishes.
|
||
pub fn register_pipeline_document_types(cache: &mut CultCache) -> Result<()> {
|
||
$(cache.register_entry_type::<$document>()?;)*
|
||
Ok(())
|
||
}
|
||
};
|
||
}
|
||
|
||
/// A document that is not a pipeline document, for the decode refusal and the
|
||
/// registrar's count to be pinned against something real. It stands in for
|
||
/// any other document a store may hold beside pipeline documents, a commit
|
||
/// receipt say, which is still not a document this library may decode. The
|
||
/// stand-in carries a receipt-shaped type id and is registered only by the
|
||
/// tests' own cache, never by the live registrar.
|
||
#[cfg(test)]
|
||
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
|
||
#[cultcache(type = "epiphany.mind_commit_receipt.v1", schema = "ForeignDocument")]
|
||
pub(crate) struct ForeignDocument {
|
||
#[cultcache(key = 0)]
|
||
pub(crate) marker: Short,
|
||
}
|
||
|
||
pipeline_kinds! {
|
||
Campaign(PipelineCampaign) => EpiphanyPipelineCampaignDocument, "campaign",
|
||
"epiphany.pipeline.campaign.v1", "EpiphanyPipelineCampaignDocument";
|
||
Target(PipelineTarget) => EpiphanyPipelineTargetDocument, "target",
|
||
"epiphany.pipeline.target.v1", "EpiphanyPipelineTargetDocument";
|
||
Question(PipelineQuestion) => EpiphanyPipelineQuestionDocument, "question",
|
||
"epiphany.pipeline.question.v1", "EpiphanyPipelineQuestionDocument";
|
||
Ruling(PipelineRuling) => EpiphanyPipelineRulingDocument, "ruling",
|
||
"epiphany.pipeline.ruling.v1", "EpiphanyPipelineRulingDocument";
|
||
CutSpec(PipelineCutSpec) => EpiphanyPipelineCutSpecDocument, "cut_spec",
|
||
"epiphany.pipeline.cut_spec.v1", "EpiphanyPipelineCutSpecDocument";
|
||
CutReport(PipelineCutReport) => EpiphanyPipelineCutReportDocument, "cut_report",
|
||
"epiphany.pipeline.cut_report.v1", "EpiphanyPipelineCutReportDocument";
|
||
Verdict(PipelineVerdict) => EpiphanyPipelineVerdictDocument, "verdict",
|
||
"epiphany.pipeline.verdict.v1", "EpiphanyPipelineVerdictDocument";
|
||
Finding(PipelineFinding) => EpiphanyPipelineFindingDocument, "finding",
|
||
"epiphany.pipeline.finding.v1", "EpiphanyPipelineFindingDocument";
|
||
FollowUp(PipelineFollowUp) => EpiphanyPipelineFollowUpDocument, "follow_up",
|
||
"epiphany.pipeline.follow_up.v1", "EpiphanyPipelineFollowUpDocument";
|
||
Resolution(PipelineResolution) => EpiphanyPipelineResolutionDocument, "resolution",
|
||
"epiphany.pipeline.resolution.v1", "EpiphanyPipelineResolutionDocument";
|
||
Instance(PipelineInstance) => EpiphanyPipelineInstanceDocument, "instance",
|
||
"epiphany.pipeline.instance.v1", "EpiphanyPipelineInstanceDocument";
|
||
Stewardship(PipelineStewardship) => EpiphanyPipelineStewardshipDocument, "stewardship",
|
||
"epiphany.pipeline.stewardship.v1", "EpiphanyPipelineStewardshipDocument";
|
||
HandOff(PipelineHandOff) => EpiphanyPipelineHandOffDocument, "hand_off",
|
||
"epiphany.pipeline.hand_off.v1", "EpiphanyPipelineHandOffDocument";
|
||
}
|
||
|
||
/// Parses a full document id: the grammar read backwards. A key and an id are
|
||
/// the same string, so this accepts exactly what `pipeline_key` derives:
|
||
/// `<root>:<kind>:<local>`, three segments for every kind. The kind segment
|
||
/// must equal `kind`'s name, the root is a `Slug`, and the local is `Label`s
|
||
/// joined by `.` and bounded whole, so `..`, an empty part, spaces and trailing
|
||
/// junk are all refused. Returns the root and the local; nothing is inferred
|
||
/// from either, and no kind is read any other way.
|
||
fn pipeline_id<'a>(
|
||
field: &str,
|
||
id: &'a str,
|
||
kind: PipelineKind,
|
||
) -> Result<(&'a str, &'a str), PipelineRefusal> {
|
||
let mut segments = id.split(':');
|
||
let (Some(root), Some(name), Some(local), None) = (
|
||
segments.next(),
|
||
segments.next(),
|
||
segments.next(),
|
||
segments.next(),
|
||
) else {
|
||
return Err(format_error(field, id));
|
||
};
|
||
if name != kind.name() {
|
||
return Err(format_error(field, id));
|
||
}
|
||
dotted_text(field, root)?;
|
||
dotted_text(field, local)?;
|
||
Ok((root, local))
|
||
}
|
||
|
||
/// The local segment of a parent id in `campaign`, of the expected kind.
|
||
fn parent_local<'a>(
|
||
field: &str,
|
||
id: &'a str,
|
||
campaign: &str,
|
||
kind: PipelineKind,
|
||
) -> Result<&'a str, PipelineRefusal> {
|
||
let (owner, local) = pipeline_id(field, id, kind)?;
|
||
if owner != campaign {
|
||
return Err(format_error(field, id));
|
||
}
|
||
Ok(local)
|
||
}
|
||
|
||
/// The cut label inside a parent local `cut-<label>.<marker><N>`: exactly two
|
||
/// parts, the label a `Label` and `<N>` a non-empty run of digits.
|
||
fn parent_cut<'a>(field: &str, local: &'a str, marker: char) -> Result<&'a str, PipelineRefusal> {
|
||
let invalid = || format_error(field, local);
|
||
let mut parts = local.split('.');
|
||
let (Some(head), Some(suffix), None) = (parts.next(), parts.next(), parts.next()) else {
|
||
return Err(invalid());
|
||
};
|
||
let cut = head.strip_prefix("cut-").ok_or_else(invalid)?;
|
||
label_text(field, cut)?;
|
||
let digits = suffix.strip_prefix(marker).ok_or_else(invalid)?;
|
||
if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_digit()) {
|
||
return Err(invalid());
|
||
}
|
||
Ok(cut)
|
||
}
|
||
|
||
/// A `Slug` or an `OrgRepo` entering a local, escaped to one label. `/` is not
|
||
/// a `Label` byte, so it cannot survive into a key, and neither may `.`: no
|
||
/// local part carries the separator, or the boundary before it would have two
|
||
/// readings. A dotted slug and a dotted repo name are both ordinary, so both
|
||
/// bytes are escaped rather than refused. The escape has to be injective or two
|
||
/// values claim one key: replacing `/` with `_` alone is not, since
|
||
/// `GameCult_Epiphany/thing` and `GameCult/Epiphany_thing` both give
|
||
/// `GameCult_Epiphany_thing`. So `_` is escaped as well, and every code is two
|
||
/// bytes starting with `_`: `_` becomes `__`, `/` becomes `_-`, and `.` becomes
|
||
/// `_d`. Every other byte is passed through and is never `_`, so a reader going
|
||
/// left to right takes each `_` together with the byte after it and never has a
|
||
/// choice to make; the encoding is therefore reversible, and distinct values
|
||
/// give distinct segments. The caller validates the value as its own type first
|
||
/// and checks the result against the local's rules, which is where an over-long
|
||
/// or otherwise unlabelled value is refused.
|
||
fn key_segment(value: &str) -> String {
|
||
value.replace('_', "__").replace('/', "_-").replace('.', "_d")
|
||
}
|
||
|
||
/// The local of a root. A campaign's or an instance's identity is entirely its
|
||
/// root segment, so its local carries none; a reader never consults it.
|
||
const ROOT_LOCAL: &str = "self";
|
||
|
||
/// The bound on a composed local, whole, in UTF-8 bytes. It is the only depth
|
||
/// limit on a chain of resolutions, and the depth test derives its expectation
|
||
/// from this name rather than restating the number.
|
||
const LOCAL_MAX: usize = 64;
|
||
|
||
/// The schema epoch every pipeline store is written at, owned here with the
|
||
/// schemas it names. Evolution is additive and keeps it: a new named field
|
||
/// with a serde default, or a widened `PipelineKind`, since each reader ships
|
||
/// with the variants it knows and refuses an unknown kind on the kind, not on
|
||
/// the epoch. A breaking change bumps it, so that a store written at the old
|
||
/// one can be refused by whoever opens it; this crate owns no store and
|
||
/// refuses none.
|
||
pub const PIPELINE_SCHEMA_EPOCH: &str = "epiphany.pipeline.epoch.v1";
|
||
|
||
/// Composes and validates a local: every part is a `Label`, and the join is
|
||
/// bounded whole. Both rules live here because this is the only way a local is
|
||
/// built; `pipeline_key` has no other path to a key string. Parts are a slice,
|
||
/// not a builder, so an arm's arity is written at its call site.
|
||
fn local(field: &str, parts: &[&str]) -> Result<String, PipelineRefusal> {
|
||
for part in parts {
|
||
label_text(field, part)?;
|
||
}
|
||
let joined = parts.join(".");
|
||
if joined.len() > LOCAL_MAX {
|
||
return Err(format_error(field, &joined));
|
||
}
|
||
Ok(joined)
|
||
}
|
||
|
||
/// Derives a document's identity key (D1, "Keys: identity, not convenience").
|
||
/// Thirteen arms, one exit: every arm names its root and composes its local
|
||
/// through `local`, and the key is formatted here and nowhere else.
|
||
pub fn pipeline_key(document: &PipelineDocument) -> Result<String, PipelineRefusal> {
|
||
use PipelineDocument as D;
|
||
let kind = document.kind().name();
|
||
let key_field = format!("{kind}.key");
|
||
let campaign_field = format!("{kind}.campaign");
|
||
let (root_field, root, composed) = match document {
|
||
D::Campaign(value) => ("campaign.slug", value.slug.0.as_str(), local(&key_field, &[ROOT_LOCAL])?),
|
||
D::Instance(value) => ("instance.instance", value.instance.0.as_str(), local(&key_field, &[ROOT_LOCAL])?),
|
||
// A resolution is keyed inside its subject's root, with the subject's
|
||
// kind and local as its own local and its per-subject sequence last, so
|
||
// the subject's resolutions and only they share the prefix
|
||
// `<root>:resolution:<kind>.<local>.n`. A resolution's own key is an
|
||
// ordinary id, so it composes as a subject like any other; each nesting
|
||
// prepends `resolution.` (11 bytes) and appends `.n<s>` (3 bytes for
|
||
// one digit), so a chain `n` deep over a depth-one local of `L` bytes
|
||
// composes `14 * (n - 1) + L` bytes against `LOCAL_MAX` in `local`,
|
||
// which is the only depth limit and needs no guard.
|
||
D::Resolution(value) => {
|
||
let field = "resolution.subject.id";
|
||
let (subject_root, subject_local) = pipeline_id(field, &value.subject.id.0, value.subject.kind)?;
|
||
let sequence = format!("n{}", value.sequence);
|
||
let parts = std::iter::once(value.subject.kind.name()).chain(subject_local.split('.')).chain(std::iter::once(sequence.as_str())).collect::<Vec<_>>();
|
||
(field, subject_root, local(&key_field, &parts)?)
|
||
}
|
||
// Stewardship and hand-off hang off an instance rather than a campaign.
|
||
// The root is the whole difference; the key shape is the same.
|
||
D::Stewardship(value) => {
|
||
org_repo_text("stewardship.repo", &value.repo.0)?;
|
||
let sequence = format!("n{}", value.sequence);
|
||
("stewardship.instance", value.instance.0.as_str(), local(&key_field, &[&key_segment(&value.repo.0), &sequence])?)
|
||
}
|
||
D::HandOff(value) => {
|
||
dotted_text("hand_off.to_instance", &value.to_instance.0)?;
|
||
org_repo_text("hand_off.repo", &value.repo.0)?;
|
||
value.handed_on.validate("hand_off.handed_on")?;
|
||
(
|
||
"hand_off.from_instance",
|
||
value.from_instance.0.as_str(),
|
||
local(&key_field, &[&key_segment(&value.to_instance.0), &key_segment(&value.repo.0), &value.handed_on.0])?,
|
||
)
|
||
}
|
||
D::Target(value) => (campaign_field.as_str(), value.campaign.0.as_str(), local(&key_field, &[&format!("r{}", value.revision)])?),
|
||
D::Question(value) => (campaign_field.as_str(), value.campaign.0.as_str(), local(&key_field, &[&value.label.0])?),
|
||
D::Ruling(value) => (campaign_field.as_str(), value.campaign.0.as_str(), local(&key_field, &[&value.label.0])?),
|
||
D::FollowUp(value) => (campaign_field.as_str(), value.campaign.0.as_str(), local(&key_field, &[&value.label.0])?),
|
||
D::CutSpec(value) => (
|
||
campaign_field.as_str(),
|
||
value.campaign.0.as_str(),
|
||
local(&key_field, &[&format!("cut-{}", value.cut.0), &format!("r{}", value.revision)])?,
|
||
),
|
||
D::CutReport(value) => {
|
||
let spec = parent_local("cut_report.cut_spec", &value.cut_spec.0, &value.campaign.0, PipelineKind::CutSpec)?;
|
||
let cut = parent_cut("cut_report.cut_spec", spec, 'r')?;
|
||
(
|
||
campaign_field.as_str(),
|
||
value.campaign.0.as_str(),
|
||
local(&key_field, &[&format!("cut-{cut}"), &format!("h{}", value.attempt)])?,
|
||
)
|
||
}
|
||
D::Verdict(value) => {
|
||
let report = parent_local("verdict.cut_report", &value.cut_report.0, &value.campaign.0, PipelineKind::CutReport)?;
|
||
let cut = parent_cut("verdict.cut_report", report, 'h')?;
|
||
(
|
||
campaign_field.as_str(),
|
||
value.campaign.0.as_str(),
|
||
local(&key_field, &[&format!("cut-{cut}"), &format!("s{}", value.pass)])?,
|
||
)
|
||
}
|
||
D::Finding(value) => {
|
||
let verdict = parent_local("finding.verdict", &value.verdict.0, &value.campaign.0, PipelineKind::Verdict)?;
|
||
parent_cut("finding.verdict", verdict, 's')?;
|
||
let parts = verdict.split('.').chain(std::iter::once(value.label.0.as_str())).collect::<Vec<_>>();
|
||
(campaign_field.as_str(), value.campaign.0.as_str(), local(&key_field, &parts)?)
|
||
}
|
||
};
|
||
dotted_text(root_field, root)?;
|
||
Ok(format!("{root}:{kind}:{composed}"))
|
||
}
|
||
|
||
/// Bounds, formats, then key recomputation, on the envelope that will be
|
||
/// stored, whoever prepared it. It is the whole of what this crate checks
|
||
/// before a write; per-kind and cross-document rules are not decided here and
|
||
/// belong to the admission path of the organ that will admit these documents,
|
||
/// which is expected to call this first rather than re-derive it.
|
||
pub fn validate_pipeline_write_envelope(envelope: &CultCacheEnvelope) -> Result<(), PipelineRefusal> {
|
||
let document = PipelineDocument::decode(envelope)?;
|
||
document.validate()?;
|
||
let expected = pipeline_key(&document)?;
|
||
if envelope.key != expected {
|
||
return Err(PipelineRefusal::InvalidIdentity {
|
||
kind: document.kind(),
|
||
key: envelope.key.clone(),
|
||
expected,
|
||
});
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use std::collections::BTreeSet;
|
||
use std::path::Path;
|
||
|
||
const CAMPAIGN: &str = "eureka-state";
|
||
const INSTANCE: &str = "yggdrasil";
|
||
|
||
fn s(value: &str) -> Short {
|
||
value.into()
|
||
}
|
||
|
||
fn l(value: &str) -> Label {
|
||
value.into()
|
||
}
|
||
|
||
fn slug(value: &str) -> Slug {
|
||
value.into()
|
||
}
|
||
|
||
fn id(kind: &str, local: &str) -> Short {
|
||
Short(format!("{CAMPAIGN}:{kind}:{local}"))
|
||
}
|
||
|
||
fn sha() -> Sha {
|
||
Sha("5f98228d".into())
|
||
}
|
||
|
||
fn date() -> Date {
|
||
Date("2026-09-15".into())
|
||
}
|
||
|
||
fn range() -> CommitRange {
|
||
CommitRange { base: sha(), head: sha() }
|
||
}
|
||
|
||
fn location() -> CodeLocation {
|
||
CodeLocation { path: s("epiphany-pipeline/src/lib.rs"), line: 1, end_line: Some(9) }
|
||
}
|
||
|
||
fn evidence() -> Evidence {
|
||
Evidence { kind: EvidenceKind::Test, locator: "cargo test".into(), result: "ok".into() }
|
||
}
|
||
|
||
fn doc_ref() -> DocRef {
|
||
DocRef { path: s("notes/eureka-pipeline-state-target.md"), start_line: 1, end_line: 9, commit: sha() }
|
||
}
|
||
|
||
/// One valid document of every kind, with its expected key.
|
||
fn samples() -> Vec<(PipelineDocument, String)> {
|
||
use PipelineDocument as D;
|
||
let repo = || OrgRepo("GameCult/Epiphany".into());
|
||
let branch = || s("codex/eureka-pipeline-state");
|
||
vec![
|
||
(D::Campaign(PipelineCampaign {
|
||
slug: slug(CAMPAIGN), title: s("Eureka pipeline state"), repos: vec![repo()],
|
||
working_branch: branch(), target_doc: doc_ref(),
|
||
}), format!("{CAMPAIGN}:campaign:self")),
|
||
(D::Target(PipelineTarget {
|
||
campaign: slug(CAMPAIGN), revision: 2,
|
||
invariants: vec![TargetInvariant { label: l("mind-admits"), statement: "Only admission writes.".into() }],
|
||
not_in_scope: vec!["Eve browsing".into()], canonical_implementations: vec!["CultLib".into()], doc: doc_ref(),
|
||
}), format!("{CAMPAIGN}:target:r2")),
|
||
(D::Question(PipelineQuestion {
|
||
campaign: slug(CAMPAIGN), label: l("Q1"), question: "Who owns the state?".into(),
|
||
options: vec![
|
||
QuestionOption { label: l("A"), text: "an instance".into() },
|
||
QuestionOption { label: l("B"), text: "a repo".into() },
|
||
],
|
||
recommended: l("A"), depends: vec!["Cut 3a".into()],
|
||
raised_in: Some(PipelineRef { kind: PipelineKind::CutSpec, id: id("cut_spec", "cut-3a.r1") }),
|
||
asked_on: date(),
|
||
}), format!("{CAMPAIGN}:question:Q1")),
|
||
(D::Ruling(PipelineRuling {
|
||
campaign: slug(CAMPAIGN), label: l("R8"), answers: Some(id("question", "Q1")), choice: Some(l("A")),
|
||
ruling: "An instance owns its mind.".into(), operator_quote: Some("all recommendations, go ahead".into()),
|
||
ruled_on: date(),
|
||
precedents: vec![ForeignRef {
|
||
repo: OrgRepo("GameCult/Aetheria".into()), commit: FullSha("a".repeat(40)), kind: PipelineKind::Ruling,
|
||
id: s("cultcache:ruling:R1"), payload_sha256: Sha256Hex("b".repeat(64)),
|
||
}],
|
||
authority: RulingAuthority::Operator,
|
||
}), format!("{CAMPAIGN}:ruling:R8")),
|
||
(D::CutSpec(PipelineCutSpec {
|
||
campaign: slug(CAMPAIGN), cut: l("3a"), revision: 1, title: s("Pipeline documents"), repo: repo(),
|
||
branch: branch(), base: sha(), depends_on: vec![s("2")], first: vec!["Read the spec.".into()],
|
||
deletes: vec![CutDelete { path: s("old.rs"), lines: 3, note: "dead".into() }],
|
||
keeps_moves: vec!["commit owner".into()], adds: vec!["pipeline_documents.rs".into()],
|
||
file_changes: vec![FileChange { location: location(), change: "add".into() }],
|
||
authority_map: Some(AuthorityMap {
|
||
owner: "core".into(), inputs: vec!["typed documents".into()], outputs: vec!["envelopes".into()],
|
||
derived_state: vec!["derived keys".into()], forbidden_writers: vec!["MCP".into()],
|
||
shared_paths: vec!["admission".into()], deletion_line: "n/a".into(),
|
||
}),
|
||
verification: CutVerification {
|
||
builds: vec!["cargo check".into()],
|
||
tests: vec![VerificationTest { name: s("keys"), pins: "one derived key".into() }],
|
||
negative: vec![NegativeCheck { pattern: s("Vec<u8>"), scope: "documents".into() }],
|
||
operator: vec!["none".into()],
|
||
},
|
||
// Cut 3a's real numbers, and in this order: the tripwire test
|
||
// reads them back, so a transposition is a failure, not a typo.
|
||
estimate: StructuralDelta {
|
||
lines_added: 900, lines_removed: 0,
|
||
dependencies_added: vec![s("schemars")], dependencies_removed: vec![],
|
||
formats_added: vec![s("epiphany.pipeline.*.v1")], formats_removed: vec![],
|
||
targets_added: vec![], targets_removed: vec![],
|
||
},
|
||
rulings: vec![id("ruling", "R8")], questions: vec![id("question", "Q1")],
|
||
}), format!("{CAMPAIGN}:cut_spec:cut-3a.r1")),
|
||
(D::CutReport(PipelineCutReport {
|
||
campaign: slug(CAMPAIGN), cut_spec: id("cut_spec", "cut-3a.r1"), attempt: 1, repo: repo(), branch: branch(),
|
||
commits: vec![ReportCommit { sha: sha(), subject: "Add the pipeline documents".into(), builds: true }],
|
||
range: range(), verification: vec![evidence()],
|
||
mutations: vec![MutationRecord {
|
||
// `.into()` on both, not `l()` and `sha()`: the type-level
|
||
// mutations (M19, M20) widen these fields to `Short`, and
|
||
// a sample spelled with the narrow constructors would stop
|
||
// compiling instead of letting the forgery through.
|
||
label: "M1".into(), rule: "key derivation".into(), location: location(),
|
||
before: "parent_cut(field, spec, 'r')?".into(), after: "spec".into(), commit: "5f98228d".into(),
|
||
failed_as_expected: true,
|
||
}],
|
||
deviations: vec![Deviation { what: "names".into(), why: "glob exports".into() }],
|
||
forks: vec![id("question", "Q1")],
|
||
structural_delta: StructuralDelta {
|
||
lines_added: 900, lines_removed: 0, dependencies_added: vec![s("schemars")],
|
||
dependencies_removed: vec![], formats_added: vec![s("epiphany.pipeline.*.v1")],
|
||
formats_removed: vec![], targets_added: vec![], targets_removed: vec![],
|
||
},
|
||
landed_names: vec![LandedName { name: s("PipelineDocument"), path: s("epiphany-pipeline/src/lib.rs") }],
|
||
undone: vec!["admission".into()],
|
||
promises: vec![Promise { label: l("P1"), text: "One derived key per document.".into() }],
|
||
}), format!("{CAMPAIGN}:cut_report:cut-3a.h1")),
|
||
(D::Verdict(PipelineVerdict {
|
||
campaign: slug(CAMPAIGN), cut_report: id("cut_report", "cut-3a.h1"), pass: 2, range: range(),
|
||
claims: vec![VerdictClaim {
|
||
claim: "A composed key has one source.".into(), outcome: ClaimOutcome::Falsified,
|
||
evidence: vec![evidence()], findings: vec![id("finding", "cut-3a.s2.F4")],
|
||
promise: Some(l("P1")), mutations: vec![l("M1")],
|
||
}],
|
||
}), format!("{CAMPAIGN}:verdict:cut-3a.s2")),
|
||
(D::Finding(PipelineFinding {
|
||
campaign: slug(CAMPAIGN), verdict: id("verdict", "cut-3a.s2"), label: l("F4"), range: range(),
|
||
confidence: FindingConfidence::Confirmed, severity: FindingSeverity::High,
|
||
claim: "A dotted label composes two keys.".into(), invariants: vec![l("mind-admits")],
|
||
locations: vec![location()], failure_scenario: "Two documents claim one key.".into(),
|
||
evidence: vec![evidence()], precedents: vec![], origin: FindingOrigin::Introduced,
|
||
}), format!("{CAMPAIGN}:finding:cut-3a.s2.F4")),
|
||
(D::FollowUp(PipelineFollowUp {
|
||
campaign: slug(CAMPAIGN), label: l("FU-4"),
|
||
source: PipelineRef { kind: PipelineKind::Finding, id: id("finding", "cut-3a.s2.F4") },
|
||
repo: repo(), locations: vec![location()], item: "Per-kind admission rules.".into(),
|
||
why_it_can_wait: "The organ owns admission.".into(), owner: s("Hands"),
|
||
}), format!("{CAMPAIGN}:follow_up:FU-4")),
|
||
(D::Resolution(PipelineResolution {
|
||
subject: PipelineRef { kind: PipelineKind::Question, id: id("question", "Q1") }, sequence: 1,
|
||
outcome: ResolutionOutcome::Answered { by: PipelineRef { kind: PipelineKind::Ruling, id: id("ruling", "R8") } },
|
||
rationale: "Ruled A.".into(), resolved_on: date(),
|
||
}), format!("{CAMPAIGN}:resolution:question.Q1.n1")),
|
||
// The mind's own three kinds. They are appended rather than
|
||
// inserted because the helpers below index this list by position.
|
||
(D::Instance(PipelineInstance {
|
||
instance: slug(INSTANCE), display_name: s("Yggdrasil mind"), created_at: date(),
|
||
host: s("yggdrasil"),
|
||
}), format!("{INSTANCE}:instance:self")),
|
||
(D::Stewardship(PipelineStewardship {
|
||
instance: slug(INSTANCE), repo: repo(), sequence: 1, assigned_on: date(),
|
||
note: "The Eureka campaign repo.".into(),
|
||
}), format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n1")),
|
||
(D::HandOff(PipelineHandOff {
|
||
from_instance: slug(INSTANCE), to_instance: slug("thought-cage"), repo: repo(),
|
||
documents: vec![s(CAMPAIGN), id("ruling", "R8")],
|
||
reason: "The workstation mind takes the campaign.".into(), handed_on: date(),
|
||
}), format!("{INSTANCE}:hand_off:thought-cage.GameCult_-Epiphany.{}", date().0)),
|
||
]
|
||
}
|
||
|
||
fn instance_sample() -> PipelineInstance {
|
||
let PipelineDocument::Instance(instance) = samples().remove(10).0 else { unreachable!() };
|
||
instance
|
||
}
|
||
|
||
fn stewardship_sample() -> PipelineStewardship {
|
||
let PipelineDocument::Stewardship(stewardship) = samples().remove(11).0 else { unreachable!() };
|
||
stewardship
|
||
}
|
||
|
||
fn hand_off_sample() -> PipelineHandOff {
|
||
let PipelineDocument::HandOff(hand_off) = samples().remove(12).0 else { unreachable!() };
|
||
hand_off
|
||
}
|
||
|
||
fn campaign_sample() -> PipelineDocument {
|
||
samples().remove(0).0
|
||
}
|
||
|
||
fn report_sample() -> PipelineCutReport {
|
||
let PipelineDocument::CutReport(report) = samples().remove(5).0 else { unreachable!() };
|
||
report
|
||
}
|
||
|
||
fn verdict_sample() -> PipelineVerdict {
|
||
let PipelineDocument::Verdict(verdict) = samples().remove(6).0 else { unreachable!() };
|
||
verdict
|
||
}
|
||
|
||
fn finding_sample() -> PipelineFinding {
|
||
let PipelineDocument::Finding(finding) = samples().remove(7).0 else { unreachable!() };
|
||
finding
|
||
}
|
||
|
||
fn resolution_sample() -> PipelineResolution {
|
||
let PipelineDocument::Resolution(resolution) = samples().remove(9).0 else { unreachable!() };
|
||
resolution
|
||
}
|
||
|
||
/// The live registrar plus the foreign stand-in, which only the tests
|
||
/// register.
|
||
fn schema_cache() -> Result<CultCache> {
|
||
let mut cache = CultCache::new();
|
||
register_pipeline_document_types(&mut cache)?;
|
||
cache.register_entry_type::<ForeignDocument>()?;
|
||
Ok(cache)
|
||
}
|
||
|
||
#[test]
|
||
fn every_pipeline_kind_round_trips_through_named_slot_zero() -> Result<()> {
|
||
let cache = schema_cache()?;
|
||
let samples = samples();
|
||
let kinds = samples.iter().map(|(document, _)| document.kind()).collect::<BTreeSet<_>>();
|
||
assert_eq!(kinds.len(), PipelineKind::ALL.len(), "every kind has a sample");
|
||
for (document, _) in samples {
|
||
document.validate()?;
|
||
let envelope = document.prepare(&cache)?;
|
||
assert_eq!(envelope.r#type, document.kind().type_id());
|
||
assert_eq!(envelope.payload[0], 0x91, "{:?} payload is a one-element array", document.kind());
|
||
assert!(
|
||
matches!(envelope.payload[1], 0x80..=0x8f | 0xde | 0xdf),
|
||
"{:?} slot 0 is a named map",
|
||
document.kind()
|
||
);
|
||
assert_eq!(PipelineDocument::decode(&envelope)?, document);
|
||
Ok::<_, anyhow::Error>(())?;
|
||
}
|
||
Ok(())
|
||
}
|
||
|
||
/// Soul F2: a decode is type-matched in both directions. The round-trip
|
||
/// test above pins the positive match; this pins the refusal, so an
|
||
/// envelope belonging to another kind can never be decoded as whichever
|
||
/// pipeline kind happens to parse its payload. The commit receipt is the
|
||
/// sharp case: a mind's store may legitimately hold one, and it is still
|
||
/// not a document; `ForeignDocument` stands in for it here.
|
||
#[test]
|
||
fn decode_refuses_an_envelope_of_a_foreign_type() -> Result<()> {
|
||
let cache = schema_cache()?;
|
||
let foreign = <ForeignDocument as DatabaseEntry>::TYPE;
|
||
assert!(!foreign.starts_with("epiphany.pipeline."), "{foreign} is a foreign type id");
|
||
let mut envelope = campaign_sample().prepare(&cache)?;
|
||
envelope.r#type = foreign.into();
|
||
assert_eq!(
|
||
PipelineDocument::decode(&envelope),
|
||
Err(PipelineRefusal::ForeignStore { r#type: foreign.into() })
|
||
);
|
||
Ok(())
|
||
}
|
||
|
||
#[test]
|
||
fn bounds_refuse_in_utf8_bytes() {
|
||
let PipelineDocument::Campaign(mut campaign) = campaign_sample() else { unreachable!() };
|
||
campaign.title = Short("é".repeat(100));
|
||
assert_eq!(PipelineDocument::Campaign(campaign.clone()).validate(), Ok(()));
|
||
campaign.title = Short(format!("{}a", "é".repeat(100)));
|
||
assert_eq!(
|
||
PipelineDocument::Campaign(campaign.clone()).validate(),
|
||
Err(PipelineRefusal::FieldBound { field: "campaign.title".into(), limit: 200, actual: 201 })
|
||
);
|
||
campaign.title = s("ok");
|
||
campaign.repos = vec![OrgRepo("GameCult/Epiphany".into()); 9];
|
||
assert_eq!(
|
||
PipelineDocument::Campaign(campaign).validate(),
|
||
Err(PipelineRefusal::FieldBound { field: "campaign.repos".into(), limit: 8, actual: 9 })
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn repo_fields_must_be_org_slash_repo() {
|
||
let mut report = report_sample();
|
||
report.repo = OrgRepo("Epiphany".into());
|
||
assert_eq!(
|
||
PipelineDocument::CutReport(report).validate(),
|
||
Err(PipelineRefusal::InvalidFormat { field: "cut_report.repo".into(), value: "Epiphany".into() })
|
||
);
|
||
let PipelineDocument::CutSpec(mut spec) = samples().remove(4).0 else { unreachable!() };
|
||
spec.repo = OrgRepo("GameCult/Epiphany/extra".into());
|
||
assert!(matches!(
|
||
PipelineDocument::CutSpec(spec).validate(),
|
||
Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "cut_spec.repo"
|
||
));
|
||
let PipelineDocument::FollowUp(mut follow_up) = samples().remove(8).0 else { unreachable!() };
|
||
follow_up.repo = OrgRepo("/Epiphany".into());
|
||
assert!(matches!(
|
||
PipelineDocument::FollowUp(follow_up).validate(),
|
||
Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "follow_up.repo"
|
||
));
|
||
}
|
||
|
||
#[test]
|
||
fn keys_are_derived_and_mismatch_refuses() -> Result<()> {
|
||
let cache = schema_cache()?;
|
||
for (document, key) in samples() {
|
||
assert_eq!(pipeline_key(&document), Ok(key.clone()));
|
||
let mut envelope = document.prepare(&cache)?;
|
||
envelope.key = format!("{key}-forged");
|
||
assert_eq!(
|
||
validate_pipeline_write_envelope(&envelope),
|
||
Err(PipelineRefusal::InvalidIdentity { kind: document.kind(), key: envelope.key, expected: key })
|
||
);
|
||
}
|
||
let mut resolution = resolution_sample();
|
||
let answered = pipeline_key(&PipelineDocument::Resolution(resolution.clone()));
|
||
resolution.outcome = ResolutionOutcome::Withdrawn { reason: "moot".into() };
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Resolution(resolution)),
|
||
answered,
|
||
"a subject has one resolution key whatever the outcome"
|
||
);
|
||
Ok(())
|
||
}
|
||
|
||
/// F2, and Soul's second pass: a composed local segments one way only. The
|
||
/// rule -- no local part carries the separator -- is pinned on the composer
|
||
/// in `no_local_part_carries_the_separator`; the pairs below are the ones
|
||
/// Soul measured through the documents, and each is a pair only because the
|
||
/// rule holds.
|
||
#[test]
|
||
fn composed_keys_cannot_collide() {
|
||
let key = |document: PipelineDocument| pipeline_key(&document);
|
||
|
||
// Soul's hand-off pair. A dotted slug is ordinary on the receiver side
|
||
// and a dotted repo name on the repo side, so both are escaped: left
|
||
// unescaped these two both key to
|
||
// `yggdrasil:hand_off:thought-cage.GameCult.Epiphany_-thing.2026-09-15`.
|
||
let handed = |to: &str, repo: &str| {
|
||
let mut hand_off = hand_off_sample();
|
||
hand_off.to_instance = slug(to);
|
||
hand_off.repo = OrgRepo(repo.into());
|
||
key(PipelineDocument::HandOff(hand_off))
|
||
};
|
||
let dotted_receiver = handed("thought-cage.GameCult", "Epiphany/thing");
|
||
let dotted_repo = handed("thought-cage", "GameCult.Epiphany/thing");
|
||
assert_eq!(
|
||
dotted_receiver,
|
||
Ok(format!("{INSTANCE}:hand_off:thought-cage_dGameCult.Epiphany_-thing.2026-09-15"))
|
||
);
|
||
assert_eq!(
|
||
dotted_repo,
|
||
Ok(format!("{INSTANCE}:hand_off:thought-cage.GameCult_dEpiphany_-thing.2026-09-15"))
|
||
);
|
||
assert_ne!(dotted_receiver, dotted_repo, "a dotted repo and a dotted receiver cannot claim one key");
|
||
|
||
let mut wide_label = finding_sample();
|
||
wide_label.label = l("F1.G");
|
||
assert!(
|
||
matches!(key(PipelineDocument::Finding(wide_label)), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"a finding label carrying a dot is refused, not silently composed"
|
||
);
|
||
let mut deep_verdict = finding_sample();
|
||
deep_verdict.verdict = id("verdict", "cut-3a.s1.F1");
|
||
deep_verdict.label = l("G");
|
||
assert!(
|
||
matches!(key(PipelineDocument::Finding(deep_verdict)), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"a verdict local that is not cut-<label>.s<N> is refused"
|
||
);
|
||
let mut plain = finding_sample();
|
||
plain.verdict = id("verdict", "cut-3a.s1");
|
||
plain.label = l("F1");
|
||
assert_eq!(key(PipelineDocument::Finding(plain)), Ok(format!("{CAMPAIGN}:finding:cut-3a.s1.F1")));
|
||
|
||
let mut deep_spec = report_sample();
|
||
deep_spec.cut_spec = id("cut_spec", "cut-3a.h1.r1");
|
||
deep_spec.attempt = 2;
|
||
assert!(
|
||
matches!(key(PipelineDocument::CutReport(deep_spec)), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"a cut label carrying a dot is refused, so cut-3a.h1.h2 has one source"
|
||
);
|
||
let mut attempt_two = report_sample();
|
||
attempt_two.attempt = 2;
|
||
assert_eq!(key(PipelineDocument::CutReport(attempt_two)), Ok(format!("{CAMPAIGN}:cut_report:cut-3a.h2")));
|
||
}
|
||
|
||
/// F3: every parent id is parsed strictly. These are the bad parents Soul
|
||
/// found accepted, plus the wrong-kind and marker rules that mutations S1
|
||
/// and S3 remove.
|
||
#[test]
|
||
fn parent_ids_are_parsed_strictly() {
|
||
let refused = |parent: &str| {
|
||
let mut report = report_sample();
|
||
report.cut_spec = Short(parent.into());
|
||
let key = pipeline_key(&PipelineDocument::CutReport(report));
|
||
assert!(
|
||
matches!(&key, Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "cut_report.cut_spec"),
|
||
"parent {parent:?} must be refused, got {key:?}"
|
||
);
|
||
};
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.r1:junk"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.rX"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-..r1"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-.r1"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.r1 "));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.r"));
|
||
refused(&format!("{CAMPAIGN}:cut_report:cut-3a.h1"));
|
||
// Right kind and a well-formed number, but the marker belongs to
|
||
// another kind: the marker rule is pinned on its own.
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.h1"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.s1"));
|
||
// A well-formed number with no marker at all. Only the marker rule
|
||
// refuses this one: the digits rule is satisfied either way.
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.1"));
|
||
refused(&format!("{CAMPAIGN}:CUT_SPEC:cut-3a.r1"));
|
||
refused(&format!("EUREKA-STATE:cut_spec:cut-3a.r1"));
|
||
refused(&format!("{CAMPAIGN}:cut_spec:cut-3a.r1:"));
|
||
refused(&format!("{CAMPAIGN}::cut-3a.r1"));
|
||
refused("cut-3a.r1");
|
||
let mut other_campaign = report_sample();
|
||
other_campaign.campaign = slug("other-campaign");
|
||
assert!(
|
||
matches!(
|
||
pipeline_key(&PipelineDocument::CutReport(other_campaign)),
|
||
Err(PipelineRefusal::InvalidFormat { .. })
|
||
),
|
||
"a parent in another campaign is refused"
|
||
);
|
||
let mut verdict = verdict_sample();
|
||
verdict.cut_report = id("cut_report", "cut-3a.r1");
|
||
assert!(
|
||
matches!(pipeline_key(&PipelineDocument::Verdict(verdict)), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"a verdict's parent must carry the report marker, not the spec marker"
|
||
);
|
||
}
|
||
|
||
/// F4: a resolution's subject id is a full id of the declared kind.
|
||
#[test]
|
||
fn resolution_subject_is_a_full_id_of_its_kind() {
|
||
let refused = |kind: PipelineKind, subject: &str| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = PipelineRef { kind, id: Short(subject.into()) };
|
||
let document = PipelineDocument::Resolution(resolution);
|
||
assert!(
|
||
matches!(document.validate(), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"subject {subject:?} must fail validation"
|
||
);
|
||
assert!(
|
||
matches!(pipeline_key(&document), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"subject {subject:?} must not compose a key"
|
||
);
|
||
};
|
||
refused(PipelineKind::Question, "");
|
||
refused(PipelineKind::Question, "not an id: spaces and : colons");
|
||
refused(PipelineKind::Question, "eureka-state:question:11");
|
||
refused(PipelineKind::Question, &format!("{CAMPAIGN}:ruling:R8"));
|
||
refused(PipelineKind::Ruling, &format!("{CAMPAIGN}:question:Q1"));
|
||
refused(PipelineKind::Question, &format!("{CAMPAIGN}:question:.."));
|
||
|
||
let mut valid = resolution_sample();
|
||
valid.subject = PipelineRef { kind: PipelineKind::Ruling, id: id("ruling", "R8") };
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Resolution(valid)),
|
||
Ok(format!("{CAMPAIGN}:resolution:ruling.R8.n1"))
|
||
);
|
||
}
|
||
|
||
/// Soul G2: a resolution is named by the key it has, and a `PipelineRef`
|
||
/// of kind `Resolution` accepts exactly that id. `PipelineRef` takes any
|
||
/// kind, so this is reachable; a follow-up sourced from a resolution is the
|
||
/// live path. The grammar admits `<campaign>:resolution:R8` too: it is
|
||
/// well-formed, and no resolution derives it, but whether a document with an
|
||
/// id exists is admission's rule, not the grammar's, so the reader does not
|
||
/// refuse it and this test does not ask it to.
|
||
#[test]
|
||
fn a_resolution_is_named_by_the_key_it_has() {
|
||
let sourced = |id: &str| {
|
||
let PipelineDocument::FollowUp(mut follow_up) = samples().remove(8).0 else { unreachable!() };
|
||
follow_up.source = PipelineRef { kind: PipelineKind::Resolution, id: Short(id.into()) };
|
||
PipelineDocument::FollowUp(follow_up).validate()
|
||
};
|
||
let key = pipeline_key(&PipelineDocument::Resolution(resolution_sample())).expect("the sample keys");
|
||
assert_eq!(key, format!("{CAMPAIGN}:resolution:question.Q1.n1"));
|
||
assert_eq!(sourced(&key), Ok(()), "a resolution is named by the key it has");
|
||
assert_eq!(sourced(&format!("{CAMPAIGN}:resolution:R8")), Ok(()), "well-formed grammar is not the reader's to refuse");
|
||
|
||
for refused in [
|
||
// The prefix shape the writer used to emit. No resolution carries it.
|
||
format!("resolution:{CAMPAIGN}:question:Q1"),
|
||
format!("{CAMPAIGN}:resolution:{CAMPAIGN}:question:Q1"),
|
||
// No local, a subject local with an empty part, trailing junk, and a
|
||
// kind segment that is not `resolution`.
|
||
format!("{CAMPAIGN}:resolution:"),
|
||
format!("{CAMPAIGN}:resolution:question..Q1"),
|
||
format!("{CAMPAIGN}:resolution:question.Q1:junk"),
|
||
format!("{CAMPAIGN}:question:Q1"),
|
||
] {
|
||
assert!(
|
||
matches!(sourced(&refused), Err(PipelineRefusal::InvalidFormat { .. })),
|
||
"{refused:?} is not an id any resolution has"
|
||
);
|
||
}
|
||
|
||
// A root subject reads back too: a resolution of a campaign carries the
|
||
// campaign's kind and its `self` local.
|
||
let mut of_campaign = resolution_sample();
|
||
of_campaign.subject = PipelineRef { kind: PipelineKind::Campaign, id: Short(format!("{CAMPAIGN}:campaign:self")) };
|
||
let root_key = pipeline_key(&PipelineDocument::Resolution(of_campaign)).expect("a root subject keys");
|
||
assert_eq!(root_key, format!("{CAMPAIGN}:resolution:campaign.self.n1"));
|
||
assert_eq!(sourced(&root_key), Ok(()));
|
||
}
|
||
|
||
/// The three kinds a mind is keyed by. The samples above already round-trip
|
||
/// every kind; this pins the shapes D2 gives these three specifically: an
|
||
/// instance is a root keyed by its own slug, and the other two hang off an
|
||
/// instance rather than a campaign, so neither borrows the campaign tail.
|
||
#[test]
|
||
fn instance_stewardship_and_hand_off_round_trip() -> Result<()> {
|
||
let cache = schema_cache()?;
|
||
let instance = PipelineDocument::Instance(instance_sample());
|
||
assert_eq!(pipeline_key(&instance), Ok(format!("{INSTANCE}:instance:self")));
|
||
for document in [
|
||
instance,
|
||
PipelineDocument::Stewardship(stewardship_sample()),
|
||
PipelineDocument::HandOff(hand_off_sample()),
|
||
] {
|
||
document.validate()?;
|
||
let envelope = document.prepare(&cache)?;
|
||
assert_eq!(PipelineDocument::decode(&envelope)?, document);
|
||
let key = pipeline_key(&document)?;
|
||
assert!(
|
||
!key.starts_with(&format!("{CAMPAIGN}:")),
|
||
"{:?} is keyed by its instance, not by a campaign: {key}",
|
||
document.kind()
|
||
);
|
||
validate_pipeline_write_envelope(&envelope)?;
|
||
}
|
||
// A bounded list is still bounded: `documents` carries a maximum, as
|
||
// every `Vec` field must.
|
||
let mut wide = hand_off_sample();
|
||
wide.documents = vec![s("x"); 257];
|
||
assert_eq!(
|
||
PipelineDocument::HandOff(wide).validate(),
|
||
Err(PipelineRefusal::FieldBound { field: "hand_off.documents".into(), limit: 256, actual: 257 })
|
||
);
|
||
Ok(())
|
||
}
|
||
|
||
/// Soul F3: a key and an id are the same string, so every kind's key reads
|
||
/// back as an id of that kind. The kinds a mind is keyed by were added to
|
||
/// the key writer and left out of the id reader, and nothing noticed,
|
||
/// because the key tests assert strings and never read one back: an
|
||
/// instance keys to its slug and then fails to parse as an instance id, so
|
||
/// no `PipelineRef` and no resolution could ever name one. Every kind now
|
||
/// reads back with no kind excused, a resolution included, and a root kind
|
||
/// read as the other root kind is refused: the reader checks the kind
|
||
/// segment for the roots exactly as for every other kind.
|
||
#[test]
|
||
fn keys_read_back_as_ids_of_their_kind() -> Result<()> {
|
||
for (document, expected) in samples() {
|
||
let kind = document.kind();
|
||
let key = pipeline_key(&document)?;
|
||
assert_eq!(key, expected, "{kind:?} keys to its sample's key");
|
||
assert_eq!(
|
||
pipeline_id("read_back", &key, kind).map(|_| ()),
|
||
Ok(()),
|
||
"{kind:?} key {key} does not read back as an id of its kind"
|
||
);
|
||
}
|
||
|
||
let campaign_key = pipeline_key(&campaign_sample())?;
|
||
let instance_key = pipeline_key(&PipelineDocument::Instance(instance_sample()))?;
|
||
assert_eq!(
|
||
pipeline_id("read_back", &instance_key, PipelineKind::Instance),
|
||
Ok((INSTANCE, ROOT_LOCAL)),
|
||
"an instance key reads back as an instance"
|
||
);
|
||
assert_eq!(
|
||
pipeline_id("read_back", &instance_key, PipelineKind::Campaign),
|
||
Err(format_error("read_back", &instance_key)),
|
||
"an instance key is not a campaign id"
|
||
);
|
||
assert_eq!(
|
||
pipeline_id("read_back", &campaign_key, PipelineKind::Instance),
|
||
Err(format_error("read_back", &campaign_key)),
|
||
"a campaign key is not an instance id"
|
||
);
|
||
|
||
// Soul X1 and X11: the reader's root and local are each `dotted_text`
|
||
// whole, so a trailing dot on either is refused by the reader itself,
|
||
// not only by the writer that never composes one. A leading dot and
|
||
// an empty part are the same rule on the local.
|
||
for malformed in ["c.:target:x", "c:target:x.", "c:target:.x", "c:target:a..b"] {
|
||
let read = pipeline_id("read_back", malformed, PipelineKind::Target);
|
||
assert!(
|
||
matches!(&read, Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "read_back"),
|
||
"{malformed:?} is not an id of any kind, got {read:?}"
|
||
);
|
||
}
|
||
|
||
// The instance root's own key segment is validated, not merely bounded.
|
||
// Nothing else stands between a `Slug` and a key: a space would compose
|
||
// a store key carrying a byte no `Label` may hold.
|
||
let mut spaced = instance_sample();
|
||
spaced.instance = Slug("thought cage".into());
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Instance(spaced)),
|
||
Err(PipelineRefusal::InvalidFormat {
|
||
field: "instance.instance".into(),
|
||
value: "thought cage".into(),
|
||
}),
|
||
"an instance slug is validated where the key is composed"
|
||
);
|
||
Ok(())
|
||
}
|
||
|
||
/// The repo is one key segment, so its slash is escaped. Left unescaped it
|
||
/// would both add a segment the reader cannot tell from a real one and put a
|
||
/// byte in the key that no `Label` may carry; escaped to a bare `_` it would
|
||
/// let two repos claim one key, which the colliding pair below pins.
|
||
#[test]
|
||
fn stewardship_key_escapes_the_repo_slash() {
|
||
let stewardship = stewardship_sample();
|
||
assert_eq!(stewardship.repo, OrgRepo("GameCult/Epiphany".into()));
|
||
let key = pipeline_key(&PipelineDocument::Stewardship(stewardship.clone()));
|
||
assert_eq!(key, Ok(format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n1")));
|
||
assert!(!key.unwrap().contains('/'), "no key segment carries a slash");
|
||
|
||
// The escape is not a cosmetic substitution, and the pair that proves it
|
||
// is a pair: under `/` -> `_` alone both of these key to
|
||
// `GameCult_Epiphany_thing`, and one of the two documents is lost.
|
||
let keyed = |repo: &str| {
|
||
let mut value = stewardship.clone();
|
||
value.repo = OrgRepo(repo.into());
|
||
pipeline_key(&PipelineDocument::Stewardship(value))
|
||
};
|
||
let underscored_org = keyed("GameCult_Epiphany/thing");
|
||
let underscored_repo = keyed("GameCult/Epiphany_thing");
|
||
assert_eq!(
|
||
underscored_org,
|
||
Ok(format!("{INSTANCE}:stewardship:GameCult__Epiphany_-thing.n1"))
|
||
);
|
||
assert_eq!(
|
||
underscored_repo,
|
||
Ok(format!("{INSTANCE}:stewardship:GameCult_-Epiphany__thing.n1"))
|
||
);
|
||
assert_ne!(underscored_org, underscored_repo, "two repos cannot claim one key");
|
||
|
||
let mut no_org = stewardship.clone();
|
||
no_org.repo = OrgRepo("Epiphany".into());
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Stewardship(no_org)),
|
||
Err(PipelineRefusal::InvalidFormat { field: "stewardship.repo".into(), value: "Epiphany".into() })
|
||
);
|
||
|
||
// An escaped repo is still bound by the key's segment rules.
|
||
let mut long = stewardship;
|
||
long.repo = OrgRepo(format!("GameCult/{}", "a".repeat(60)));
|
||
assert!(
|
||
matches!(
|
||
pipeline_key(&PipelineDocument::Stewardship(long)),
|
||
Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "stewardship.key"
|
||
),
|
||
"a repo segment longer than a key segment is refused"
|
||
);
|
||
}
|
||
|
||
/// A hand-off is recorded in both minds, so both instances are in the key:
|
||
/// the sender owns the first segment and the receiver the local. Changing
|
||
/// either one moves the document.
|
||
#[test]
|
||
fn hand_off_names_both_instances() {
|
||
let key = |hand_off: PipelineHandOff| pipeline_key(&PipelineDocument::HandOff(hand_off));
|
||
let base = key(hand_off_sample()).expect("the sample keys");
|
||
assert_eq!(base, format!("{INSTANCE}:hand_off:thought-cage.GameCult_-Epiphany.2026-09-15"));
|
||
|
||
let mut other_sender = hand_off_sample();
|
||
other_sender.from_instance = slug("thought-cage");
|
||
assert_ne!(key(other_sender), Ok(base.clone()), "the sender is in the key");
|
||
|
||
let mut other_receiver = hand_off_sample();
|
||
other_receiver.to_instance = slug("mimir");
|
||
assert_ne!(key(other_receiver), Ok(base.clone()), "the receiver is in the key");
|
||
|
||
// Two hand-offs of the same repo between the same pair on different
|
||
// days are different documents.
|
||
let mut later = hand_off_sample();
|
||
later.handed_on = Date("2026-09-16".into());
|
||
assert_ne!(key(later), Ok(base), "the date is in the key");
|
||
|
||
// A dotted receiver is a `Slug` entering a local, so it is escaped to
|
||
// one label rather than widening the local by a part.
|
||
let mut dotted_receiver = hand_off_sample();
|
||
dotted_receiver.to_instance = slug("thought-cage.GameCult");
|
||
assert_eq!(
|
||
key(dotted_receiver),
|
||
Ok(format!("{INSTANCE}:hand_off:thought-cage_dGameCult.GameCult_-Epiphany.2026-09-15"))
|
||
);
|
||
|
||
// The escape's `_` half is not only for repos: a receiver `a_db` and a
|
||
// receiver `a.b` would both key to `a_db` if the slug's own `_` passed
|
||
// through raw, so the slug is escaped as `a__db` and the two differ.
|
||
let mut underscored_receiver = hand_off_sample();
|
||
underscored_receiver.to_instance = slug("a_db");
|
||
let mut dotted_twin = hand_off_sample();
|
||
dotted_twin.to_instance = slug("a.b");
|
||
let underscored_receiver = key(underscored_receiver).expect("an underscored receiver keys");
|
||
assert!(underscored_receiver.contains("a__db"), "{underscored_receiver}: the slug's underscore is escaped");
|
||
assert_ne!(key(dotted_twin), Ok(underscored_receiver), "`a_db` and `a.b` are two receivers");
|
||
|
||
// Both instance slugs are validated as key segments, not merely bounded.
|
||
let mut bad_receiver = hand_off_sample();
|
||
bad_receiver.to_instance = Slug("thought cage".into());
|
||
assert_eq!(
|
||
key(bad_receiver),
|
||
Err(PipelineRefusal::InvalidFormat {
|
||
field: "hand_off.to_instance".into(),
|
||
value: "thought cage".into(),
|
||
})
|
||
);
|
||
let mut bad_date = hand_off_sample();
|
||
bad_date.handed_on = Date("2026-9-15".into());
|
||
assert!(
|
||
matches!(key(bad_date), Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "hand_off.handed_on"),
|
||
"a malformed date does not compose a key"
|
||
);
|
||
}
|
||
|
||
/// A resolution whose subject is the given document, keyed.
|
||
fn resolution_of(kind: PipelineKind, id: &str) -> Result<String, PipelineRefusal> {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = PipelineRef { kind, id: Short(id.into()) };
|
||
pipeline_key(&PipelineDocument::Resolution(resolution))
|
||
}
|
||
|
||
/// R1, the grammar's own test: every key is `<root>:<kind>:<local>`, three
|
||
/// segments with no kind excused, the root a `Slug`, the kind the literal
|
||
/// name, and every local part a `Label`. A root that would add a segment is
|
||
/// refused where the key is composed: `pipeline_key` is `pub` and does not
|
||
/// validate the document first, so this is reachable without one.
|
||
#[test]
|
||
fn every_key_has_exactly_three_segments() {
|
||
let nested = resolution_of(PipelineKind::Resolution, &format!("{CAMPAIGN}:resolution:question.Q1.n1"))
|
||
.expect("a resolution of a resolution keys");
|
||
let keys = samples()
|
||
.into_iter()
|
||
.map(|(document, _)| (document.kind(), pipeline_key(&document).expect("every sample keys")))
|
||
.chain([(PipelineKind::Resolution, nested)]);
|
||
for (kind, key) in keys {
|
||
let segments = key.split(':').collect::<Vec<_>>();
|
||
assert_eq!(segments.len(), 3, "{kind:?} key {key} has three segments");
|
||
assert_eq!(dotted_text("root", segments[0]), Ok(()), "{key}: the root is a slug");
|
||
assert_eq!(segments[1], kind.name(), "{key}: the kind segment is the literal kind");
|
||
assert!(PipelineKind::ALL.iter().any(|known| known.name() == segments[1]));
|
||
for part in segments[2].split('.') {
|
||
assert_eq!(label_text("local", part), Ok(()), "{key}: local part {part:?} is a label");
|
||
}
|
||
}
|
||
|
||
// A root that would add a segment, one that would empty a part, and one
|
||
// wider than a segment are all refused before a key is formatted. The
|
||
// refusal names the part that failed, so an empty part reports `""`.
|
||
let trailing_dot = format!("{CAMPAIGN}.");
|
||
let leading_dot = format!(".{CAMPAIGN}");
|
||
let over = "a".repeat(65);
|
||
for root in ["a:b", trailing_dot.as_str(), leading_dot.as_str(), "a..b", over.as_str()] {
|
||
let PipelineDocument::Target(mut target) = samples().remove(1).0 else { unreachable!() };
|
||
target.campaign = Slug(root.into());
|
||
let key = pipeline_key(&PipelineDocument::Target(target));
|
||
assert!(
|
||
matches!(&key, Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "target.campaign"),
|
||
"root {root:?} does not compose a key, got {key:?}"
|
||
);
|
||
}
|
||
}
|
||
|
||
/// Defect 1: the two roots are in distinct namespaces because the kind
|
||
/// segment distinguishes them, the same mechanism that separates every
|
||
/// other pair of kinds. Both key; only the pair sees a shared namespace.
|
||
#[test]
|
||
fn roots_of_different_kinds_do_not_share_a_key() {
|
||
let PipelineDocument::Campaign(mut campaign) = campaign_sample() else { unreachable!() };
|
||
campaign.slug = slug(INSTANCE);
|
||
let campaign = pipeline_key(&PipelineDocument::Campaign(campaign));
|
||
let instance = pipeline_key(&PipelineDocument::Instance(instance_sample()));
|
||
assert_eq!(campaign, Ok(format!("{INSTANCE}:campaign:self")));
|
||
assert_eq!(instance, Ok(format!("{INSTANCE}:instance:self")));
|
||
assert_ne!(campaign, instance, "a campaign and an instance of one slug are two documents");
|
||
}
|
||
|
||
/// The root is a `Slug`, so a dotted root keys and reads back whole on
|
||
/// both sides: the writer's root check and the reader's root check are
|
||
/// each `dotted_text`, not `label_text`. A campaign `game.cult` and an
|
||
/// instance `ygg.drasil` key, a document under the dotted campaign keys,
|
||
/// and each reads back through `pipeline_id` recovering the root exactly.
|
||
#[test]
|
||
fn dotted_roots_key_and_read_back() {
|
||
let PipelineDocument::Campaign(mut campaign) = campaign_sample() else { unreachable!() };
|
||
campaign.slug = slug("game.cult");
|
||
let campaign_key = pipeline_key(&PipelineDocument::Campaign(campaign)).expect("a dotted campaign keys");
|
||
assert_eq!(campaign_key, "game.cult:campaign:self");
|
||
assert_eq!(
|
||
pipeline_id("read_back", &campaign_key, PipelineKind::Campaign),
|
||
Ok(("game.cult", ROOT_LOCAL)),
|
||
"the dotted campaign root reads back whole"
|
||
);
|
||
|
||
let mut instance = instance_sample();
|
||
instance.instance = slug("ygg.drasil");
|
||
let instance_key = pipeline_key(&PipelineDocument::Instance(instance)).expect("a dotted instance keys");
|
||
assert_eq!(instance_key, "ygg.drasil:instance:self");
|
||
assert_eq!(
|
||
pipeline_id("read_back", &instance_key, PipelineKind::Instance),
|
||
Ok(("ygg.drasil", ROOT_LOCAL)),
|
||
"the dotted instance root reads back whole"
|
||
);
|
||
|
||
let PipelineDocument::Target(mut target) = samples().remove(1).0 else { unreachable!() };
|
||
target.campaign = slug("game.cult");
|
||
let target_key = pipeline_key(&PipelineDocument::Target(target)).expect("a target under a dotted campaign keys");
|
||
assert_eq!(target_key, "game.cult:target:r2");
|
||
assert_eq!(
|
||
pipeline_id("read_back", &target_key, PipelineKind::Target),
|
||
Ok(("game.cult", "r2")),
|
||
"the dotted root and the local both read back"
|
||
);
|
||
|
||
let resolution = resolution_of(PipelineKind::Campaign, &campaign_key).expect("a resolution of a dotted campaign keys");
|
||
assert_eq!(resolution, "game.cult:resolution:campaign.self.n1");
|
||
assert_eq!(
|
||
pipeline_id("read_back", &resolution, PipelineKind::Resolution),
|
||
Ok(("game.cult", "campaign.self.n1")),
|
||
"a resolution under a dotted root reads back"
|
||
);
|
||
}
|
||
|
||
/// Cut 6c: a resolution's referent is a full id of the kind it declares,
|
||
/// validated through `PipelineRef` like every other referent, so a
|
||
/// well-formed id of the wrong kind is refused and the refusal names the
|
||
/// entry. The positive case is Ghostlight's own: a ruling partly
|
||
/// overturned by two later records, one of them a resolution named by the
|
||
/// key it has, which only the 6b grammar made nameable. An id no
|
||
/// resolution derives, `eureka-state:resolution:R8`, still validates:
|
||
/// whether a document with an id exists is admission's rule.
|
||
#[test]
|
||
fn resolution_outcome_referents_are_parsed_ids_of_their_kind() {
|
||
let resolved = |subject: PipelineRef, outcome: ResolutionOutcome| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = subject;
|
||
resolution.outcome = outcome;
|
||
PipelineDocument::Resolution(resolution).validate()
|
||
};
|
||
let refused = |field: &str, result: Result<(), PipelineRefusal>| {
|
||
assert!(
|
||
matches!(&result, Err(PipelineRefusal::InvalidFormat { field: at, .. }) if at == field),
|
||
"expected InvalidFormat at {field}, got {result:?}"
|
||
);
|
||
};
|
||
let ruling = |label: &str| PipelineRef { kind: PipelineKind::Ruling, id: id("ruling", label) };
|
||
let question = |label: &str| PipelineRef { kind: PipelineKind::Question, id: id("question", label) };
|
||
let inner = pipeline_key(&PipelineDocument::Resolution(resolution_sample())).expect("the sample keys");
|
||
let resolution = PipelineRef { kind: PipelineKind::Resolution, id: Short(inner.clone()) };
|
||
|
||
let superseded = |second: PipelineRef| ResolutionOutcome::Superseded { by: vec![ruling("R9"), second] };
|
||
assert_eq!(resolved(ruling("R8"), superseded(resolution)), Ok(()));
|
||
let forged = PipelineRef { kind: PipelineKind::Ruling, id: Short(inner) };
|
||
refused("resolution.outcome.by[1].id", resolved(ruling("R8"), superseded(forged)));
|
||
let underived = PipelineRef { kind: PipelineKind::Resolution, id: Short(format!("{CAMPAIGN}:resolution:R8")) };
|
||
assert_eq!(resolved(ruling("R8"), superseded(underived)), Ok(()), "well-formed grammar is not the shape's to refuse");
|
||
|
||
assert_eq!(resolved(question("Q1"), ResolutionOutcome::Answered { by: ruling("R8") }), Ok(()));
|
||
let forged = PipelineRef { kind: PipelineKind::Question, id: id("ruling", "R8") };
|
||
refused("resolution.outcome.by.id", resolved(question("Q1"), ResolutionOutcome::Answered { by: forged }));
|
||
|
||
assert_eq!(resolved(question("Q1"), ResolutionOutcome::Deferred { to: question("Q2") }), Ok(()));
|
||
let forged = PipelineRef { kind: PipelineKind::Ruling, id: id("question", "Q2") };
|
||
refused("resolution.outcome.to.id", resolved(question("Q1"), ResolutionOutcome::Deferred { to: forged }));
|
||
|
||
let finding = PipelineRef { kind: PipelineKind::Finding, id: id("finding", "cut-3a.s2.F4") };
|
||
let fixed = |by: Option<PipelineRef>| ResolutionOutcome::Fixed { commit: sha(), by };
|
||
assert_eq!(resolved(finding.clone(), fixed(None)), Ok(()));
|
||
assert_eq!(resolved(finding.clone(), fixed(Some(ruling("R8")))), Ok(()));
|
||
let forged = PipelineRef { kind: PipelineKind::Finding, id: id("ruling", "R8") };
|
||
refused("resolution.outcome.by.id", resolved(finding, fixed(Some(forged))));
|
||
|
||
// Soul F2: the validator's bound on a supersession is its own, not
|
||
// only the schema's. Eight referents are the most a subject names;
|
||
// nine are refused as a count before any item is read.
|
||
let rulings = |count: usize| (1..=count).map(|n| ruling(&format!("R{n}"))).collect::<Vec<_>>();
|
||
assert_eq!(resolved(ruling("R8"), ResolutionOutcome::Superseded { by: rulings(8) }), Ok(()));
|
||
assert_eq!(
|
||
resolved(ruling("R8"), ResolutionOutcome::Superseded { by: rulings(9) }),
|
||
Err(PipelineRefusal::FieldBound { field: "resolution.outcome.by".into(), limit: 8, actual: 9 })
|
||
);
|
||
|
||
// Soul F3: the two reason-carrying outcomes are bounded like every
|
||
// `Line`; the shared arm is pinned on both so neither can drop out.
|
||
let wide = Line("a".repeat(1001));
|
||
for outcome in [
|
||
ResolutionOutcome::Recorded { reason: wide.clone() },
|
||
ResolutionOutcome::Withdrawn { reason: wide },
|
||
] {
|
||
let finding = PipelineRef { kind: PipelineKind::Finding, id: id("finding", "cut-3a.s2.F4") };
|
||
assert_eq!(
|
||
resolved(finding, outcome),
|
||
Err(PipelineRefusal::FieldBound { field: "resolution.outcome.reason".into(), limit: 1000, actual: 1001 })
|
||
);
|
||
}
|
||
}
|
||
|
||
/// Ruling B: a fix names the tree where the finding stopped being true,
|
||
/// as a `Sha`. Uppercase hex of a legal length is the forgery a length
|
||
/// check passes and `hex` refuses.
|
||
#[test]
|
||
fn fixed_resolution_requires_a_commit_sha() {
|
||
let fixed = |commit: &str, by: Option<PipelineRef>| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = PipelineRef { kind: PipelineKind::Finding, id: id("finding", "cut-3a.s2.F4") };
|
||
resolution.outcome = ResolutionOutcome::Fixed { commit: Sha(commit.into()), by };
|
||
PipelineDocument::Resolution(resolution).validate()
|
||
};
|
||
assert_eq!(fixed("5f98228d9c", None), Ok(()));
|
||
for forged in ["5F98228D9C", "5f9822", "dirty-worktree", ""] {
|
||
assert_eq!(
|
||
fixed(forged, None),
|
||
Err(PipelineRefusal::InvalidFormat { field: "resolution.outcome.commit".into(), value: forged.into() }),
|
||
"{forged:?} is not a commit"
|
||
);
|
||
}
|
||
// Soul F1: naming the record that fixed it does not excuse the commit.
|
||
let ruling = PipelineRef { kind: PipelineKind::Ruling, id: id("ruling", "R8") };
|
||
assert_eq!(
|
||
fixed("dirty-worktree", Some(ruling)),
|
||
Err(PipelineRefusal::InvalidFormat { field: "resolution.outcome.commit".into(), value: "dirty-worktree".into() }),
|
||
"a fix with a named record still names a commit"
|
||
);
|
||
}
|
||
|
||
/// A mutation record has a key-safe identity a verdict claim can name,
|
||
/// and is pinned to a tree: its label is a `Label` and its commit a
|
||
/// `Sha`, so a dotted label and free text where a sha belongs are refused.
|
||
#[test]
|
||
fn mutation_records_carry_a_dot_free_label_and_a_commit() {
|
||
let recorded = |label: &str, commit: &str| {
|
||
let mut report = report_sample();
|
||
// Through `From<&str>`, which every text type has, so the
|
||
// widened types under M19 and M20 still compile and the
|
||
// forgeries reach validation.
|
||
report.mutations[0].label = label.into();
|
||
report.mutations[0].commit = commit.into();
|
||
PipelineDocument::CutReport(report).validate()
|
||
};
|
||
assert_eq!(recorded("M1", "5f98228d"), Ok(()));
|
||
assert_eq!(
|
||
recorded("M1.a", "5f98228d"),
|
||
Err(PipelineRefusal::InvalidFormat { field: "cut_report.mutations[0].label".into(), value: "M1.a".into() })
|
||
);
|
||
assert_eq!(
|
||
recorded("M1", "dirty-worktree"),
|
||
Err(PipelineRefusal::InvalidFormat {
|
||
field: "cut_report.mutations[0].commit".into(),
|
||
value: "dirty-worktree".into(),
|
||
})
|
||
);
|
||
}
|
||
|
||
/// Ruling A's shape half: a claim names the promise it measured and the
|
||
/// mutations it ran, both as `Label`s, and names at most eight mutations.
|
||
#[test]
|
||
fn a_verdict_claim_names_the_promise_and_the_mutation_it_measured() {
|
||
let sample = verdict_sample();
|
||
assert_eq!(sample.claims[0].promise, Some(l("P1")));
|
||
assert_eq!(sample.claims[0].mutations, vec![l("M1")]);
|
||
assert_eq!(PipelineDocument::Verdict(sample).validate(), Ok(()));
|
||
|
||
let claimed = |promise: Option<Label>, mutations: Vec<Label>| {
|
||
let mut verdict = verdict_sample();
|
||
verdict.claims[0].promise = promise;
|
||
verdict.claims[0].mutations = mutations;
|
||
PipelineDocument::Verdict(verdict).validate()
|
||
};
|
||
assert_eq!(claimed(None, vec![]), Ok(()), "a claim need not measure a promise");
|
||
assert_eq!(
|
||
claimed(Some(l("P1.a")), vec![]),
|
||
Err(PipelineRefusal::InvalidFormat { field: "verdict.claims[0].promise".into(), value: "P1.a".into() })
|
||
);
|
||
assert_eq!(
|
||
claimed(None, vec![l("M1.a")]),
|
||
Err(PipelineRefusal::InvalidFormat { field: "verdict.claims[0].mutations[0]".into(), value: "M1.a".into() })
|
||
);
|
||
let labels = |count: usize| (1..=count).map(|n| l(&format!("M{n}"))).collect::<Vec<_>>();
|
||
assert_eq!(claimed(None, labels(8)), Ok(()));
|
||
assert_eq!(
|
||
claimed(None, labels(9)),
|
||
Err(PipelineRefusal::FieldBound { field: "verdict.claims[0].mutations".into(), limit: 8, actual: 9 })
|
||
);
|
||
}
|
||
|
||
/// A tripwire on the one hazard of retyping the estimate: the delta's two
|
||
/// `u32` fields are not interchangeable. The sample spec is Cut 3a's, a
|
||
/// net addition of 900 lines, and the order is asserted.
|
||
#[test]
|
||
fn the_sample_cut_spec_estimates_a_net_addition() {
|
||
let PipelineDocument::CutSpec(spec) = samples().remove(4).0 else { unreachable!() };
|
||
assert_eq!(spec.estimate.lines_added, 900);
|
||
assert_eq!(spec.estimate.lines_removed, 0);
|
||
assert_eq!(spec.estimate, report_sample().structural_delta, "the estimate and the actual are one shape");
|
||
}
|
||
|
||
/// Defect 2: a resolution's key carries its subject's kind as a literal
|
||
/// part of the local, so nothing infers it and two subjects of one local
|
||
/// and different kinds resolve to two keys. Each reads back through the
|
||
/// reader with the subject kind it was built from.
|
||
#[test]
|
||
fn a_resolution_names_its_subjects_kind() {
|
||
let pairs = [
|
||
(PipelineKind::Question, id("question", "Q1").0, PipelineKind::Ruling, id("ruling", "Q1").0),
|
||
(
|
||
PipelineKind::Campaign,
|
||
format!("{CAMPAIGN}:campaign:self"),
|
||
PipelineKind::Instance,
|
||
format!("{CAMPAIGN}:instance:self"),
|
||
),
|
||
];
|
||
for (left_kind, left_id, right_kind, right_id) in pairs {
|
||
let left = resolution_of(left_kind, &left_id).expect("the left subject keys");
|
||
let right = resolution_of(right_kind, &right_id).expect("the right subject keys");
|
||
assert_ne!(left, right, "resolutions of {left_id} and {right_id} are two documents");
|
||
for (kind, key) in [(left_kind, &left), (right_kind, &right)] {
|
||
let (root, local) = pipeline_id("read_back", key, PipelineKind::Resolution).expect("reads back");
|
||
assert_eq!(root, CAMPAIGN);
|
||
assert_eq!(local.split('.').next(), Some(kind.name()), "{key} names its subject's kind");
|
||
}
|
||
}
|
||
}
|
||
|
||
/// Defect 3: a resolution's own key is an ordinary id, so it composes as a
|
||
/// subject like any other, and the key reads back to the inner key -- the
|
||
/// whole inner key, sequence included, since the subject is recovered by
|
||
/// stripping this resolution's own sequence from the end and the kind from
|
||
/// the front. Depth is bounded by the local alone: each nesting prepends
|
||
/// `resolution.` (11 bytes) and appends `.n<s>` (3 for one digit), so a
|
||
/// chain `n` deep over a depth-one local of `L` bytes composes
|
||
/// `14 * (n - 1) + L` bytes against `LOCAL_MAX`. The deepest chain that
|
||
/// keys is therefore `(LOCAL_MAX - L) / 14 + 1`, and it depends on the
|
||
/// subject: at 64, `ruling.A.n1` (11 bytes) and `question.Q1.n1` (14
|
||
/// bytes) both key four deep.
|
||
#[test]
|
||
fn a_resolution_of_a_resolution_reads_back() {
|
||
let inner = resolution_of(PipelineKind::Question, &id("question", "Q1").0).expect("the inner keys");
|
||
let mut outer = resolution_sample();
|
||
outer.subject = PipelineRef { kind: PipelineKind::Resolution, id: Short(inner.clone()) };
|
||
let outer = PipelineDocument::Resolution(outer);
|
||
assert_eq!(outer.validate(), Ok(()));
|
||
let key = pipeline_key(&outer).expect("a resolution of a resolution keys");
|
||
assert_eq!(key, format!("{CAMPAIGN}:resolution:resolution.question.Q1.n1.n1"));
|
||
let (root, local) = pipeline_id("read_back", &key, PipelineKind::Resolution).expect("reads back");
|
||
let (subject_kind, rest) = local.split_once('.').expect("the local names a subject");
|
||
let (subject_local, _sequence) = rest.rsplit_once('.').expect("the local ends in this resolution's sequence");
|
||
assert_eq!(format!("{root}:{subject_kind}:{subject_local}"), inner, "the recovered subject is the inner key");
|
||
|
||
let prefix = format!("{CAMPAIGN}:resolution:").len();
|
||
let nesting = "resolution.".len() + ".n1".len();
|
||
for (subject_kind, subject_id) in [(PipelineKind::Ruling, id("ruling", "A")), (PipelineKind::Question, id("question", "Q1"))] {
|
||
let mut key = resolution_of(subject_kind, &subject_id.0).expect("the depth-one resolution keys");
|
||
let depth_one = key.len() - prefix;
|
||
let deepest = (LOCAL_MAX - depth_one) / nesting + 1;
|
||
for depth in 2..=deepest {
|
||
key = resolution_of(PipelineKind::Resolution, &key)
|
||
.unwrap_or_else(|error| panic!("{subject_id:?} depth {depth}: {error}"));
|
||
assert_eq!(key.len() - prefix, nesting * (depth - 1) + depth_one, "{key}: depth {depth} local length");
|
||
}
|
||
assert!(key.len() - prefix <= LOCAL_MAX, "{key}: the deepest chain fits the local");
|
||
assert!(
|
||
matches!(
|
||
resolution_of(PipelineKind::Resolution, &key),
|
||
Err(PipelineRefusal::InvalidFormat { field, .. }) if field == "resolution.key"
|
||
),
|
||
"{key}: nesting {} is refused on the local bound",
|
||
deepest + 1
|
||
);
|
||
}
|
||
}
|
||
|
||
/// Each level of a nesting carries its own sequence, and only its own: the
|
||
/// part appended is this resolution's `sequence` field, never a copy of the
|
||
/// sequence the subject already ends in. The fixtures elsewhere all sit at
|
||
/// `1` at every level, where the two are indistinguishable, so the chain
|
||
/// here differs at every level and reads back level by level.
|
||
///
|
||
/// On spelling, so silence is not read as coverage: the leaf emits `n<N>`
|
||
/// with `N` as `u32::to_string` writes it, so `n0` and `n12` are emitted
|
||
/// and `n01` is not. A hand-built id ending `n01`, `n1x`, or no `n<N>` at
|
||
/// all is still a well-formed reference -- those are legal labels, and a
|
||
/// grammar that reads keys may not refuse them on spelling. Nothing in the
|
||
/// leaf canonicalises them either: such an id simply names a document the
|
||
/// leaf would never key, which admission's A7 sees as a missing referent.
|
||
#[test]
|
||
fn every_level_of_a_nesting_keeps_its_own_sequence() {
|
||
let resolved = |kind: PipelineKind, subject: &str, sequence: u32| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = PipelineRef { kind, id: Short(subject.into()) };
|
||
resolution.sequence = sequence;
|
||
pipeline_key(&PipelineDocument::Resolution(resolution)).expect("a sequenced resolution keys")
|
||
};
|
||
let first = resolved(PipelineKind::Question, &id("question", "Q1").0, 9);
|
||
let second = resolved(PipelineKind::Resolution, &first, 10);
|
||
let third = resolved(PipelineKind::Resolution, &second, 0);
|
||
let fourth = resolved(PipelineKind::Resolution, &third, 12);
|
||
assert_eq!(first, format!("{CAMPAIGN}:resolution:question.Q1.n9"));
|
||
assert_eq!(second, format!("{CAMPAIGN}:resolution:resolution.question.Q1.n9.n10"));
|
||
assert_eq!(third, format!("{CAMPAIGN}:resolution:resolution.resolution.question.Q1.n9.n10.n0"));
|
||
assert_eq!(
|
||
fourth,
|
||
format!("{CAMPAIGN}:resolution:resolution.resolution.resolution.question.Q1.n9.n10.n0.n12")
|
||
);
|
||
for (outer, inner, sequence) in [(&fourth, &third, 12), (&third, &second, 0), (&second, &first, 10)] {
|
||
let (root, local) = pipeline_id("read_back", outer, PipelineKind::Resolution).expect("reads back");
|
||
let (subject_kind, rest) = local.split_once('.').expect("the local names a subject");
|
||
let (subject_local, last) = rest.rsplit_once('.').expect("the local ends in this resolution's sequence");
|
||
assert_eq!(subject_kind, "resolution", "{outer}: the subject of a nesting is a resolution");
|
||
assert_eq!(format!("{root}:{subject_kind}:{subject_local}"), *inner, "{outer}: the subject is the inner key");
|
||
assert_eq!(last, format!("n{sequence}"), "{outer}: this level's own sequence, not the subject's");
|
||
}
|
||
}
|
||
|
||
/// A stewardship is the other sequenced kind, and it composes as a subject
|
||
/// like any other: the subject's whole local, escaped repo and sequence
|
||
/// both, is the resolution's local, with the resolution's own sequence
|
||
/// last. So the two assignments of one repo have two resolutions, and a
|
||
/// resolution of either is itself resolvable.
|
||
#[test]
|
||
fn a_resolution_of_a_stewardship_reads_back() {
|
||
let stewarded = |sequence: u32| {
|
||
let mut stewardship = stewardship_sample();
|
||
stewardship.sequence = sequence;
|
||
pipeline_key(&PipelineDocument::Stewardship(stewardship)).expect("a sequenced stewardship keys")
|
||
};
|
||
let first = stewarded(1);
|
||
let second = stewarded(2);
|
||
assert_eq!(first, format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n1"));
|
||
assert_eq!(second, format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n2"));
|
||
|
||
let resolved = resolution_of(PipelineKind::Stewardship, &first).expect("a resolution of a stewardship keys");
|
||
let resolved_second = resolution_of(PipelineKind::Stewardship, &second).expect("the second assignment resolves");
|
||
assert_eq!(resolved, format!("{INSTANCE}:resolution:stewardship.GameCult_-Epiphany.n1.n1"));
|
||
assert_eq!(resolved_second, format!("{INSTANCE}:resolution:stewardship.GameCult_-Epiphany.n2.n1"));
|
||
assert_ne!(resolved, resolved_second, "each assignment keeps its own resolution");
|
||
|
||
for (key, subject) in [(&resolved, &first), (&resolved_second, &second)] {
|
||
let (root, local) = pipeline_id("read_back", key, PipelineKind::Resolution).expect("reads back");
|
||
assert_eq!(root, INSTANCE, "{key}: a stewardship's resolution lives in the mind's root");
|
||
let (subject_kind, rest) = local.split_once('.').expect("the local names a subject");
|
||
let (subject_local, last) = rest.rsplit_once('.').expect("the local ends in this resolution's sequence");
|
||
assert_eq!(subject_kind, PipelineKind::Stewardship.name(), "{key} names its subject's kind");
|
||
assert_eq!(
|
||
format!("{root}:{subject_kind}:{subject_local}"),
|
||
*subject,
|
||
"{key}: the subject's own sequence is part of the recovered key"
|
||
);
|
||
assert_eq!(last, "n1", "{key}: this resolution's own sequence");
|
||
|
||
// A withdrawal of that resolution nests one out, as it does under
|
||
// any other subject, and reads back to the resolution it withdraws.
|
||
let withdrawal = resolution_of(PipelineKind::Resolution, key).expect("a withdrawal keys");
|
||
let subject_local = key.split(':').nth(2).expect("three segments");
|
||
assert_eq!(withdrawal, format!("{INSTANCE}:resolution:resolution.{subject_local}.n1"));
|
||
let (root, local) = pipeline_id("read_back", &withdrawal, PipelineKind::Resolution).expect("reads back");
|
||
let (subject_kind, rest) = local.split_once('.').expect("the local names a subject");
|
||
let (subject_local, _) = rest.rsplit_once('.').expect("the local ends in its own sequence");
|
||
assert_eq!(format!("{root}:{subject_kind}:{subject_local}"), **key, "{withdrawal}: the withdrawn resolution");
|
||
}
|
||
}
|
||
|
||
/// The total bound, in the one place it lives: parts that are each a legal
|
||
/// label compose a local wider than 64 bytes and are refused as a whole.
|
||
#[test]
|
||
fn a_composed_local_is_bounded_whole() {
|
||
let mut wide = hand_off_sample();
|
||
wide.to_instance = Slug("a".repeat(60));
|
||
assert_eq!(wide.to_instance.validate("hand_off.to_instance"), Ok(()), "the receiver alone is legal");
|
||
assert_eq!(
|
||
label_text("part", &key_segment(&wide.repo.0)),
|
||
Ok(()),
|
||
"the repo alone is legal"
|
||
);
|
||
let key = pipeline_key(&PipelineDocument::HandOff(wide));
|
||
assert!(
|
||
matches!(&key, Err(PipelineRefusal::InvalidFormat { field, value }) if field == "hand_off.key" && value.len() > 64),
|
||
"a local of legal parts is still bounded whole, got {key:?}"
|
||
);
|
||
|
||
// The bound is 64 exactly, on both sides, whether the part that fills
|
||
// it is a plain label or an escaped repo. A hand-off local is
|
||
// `<receiver>.<repo>.<date>`, the repo `GameCult_-Epiphany` and the
|
||
// date ten bytes, so the receiver fills the rest; a stewardship local is
|
||
// `<repo escaped>.n<N>`, so `GameCult_-` and `.n1` bound the name.
|
||
let hand_off_rest = "GameCult_-Epiphany".len() + ".".len() + date().0.len() + ".".len();
|
||
let stewardship_rest = "GameCult_-".len() + ".n1".len();
|
||
let received = |receiver: usize| {
|
||
let mut hand_off = hand_off_sample();
|
||
hand_off.to_instance = Slug("a".repeat(receiver));
|
||
pipeline_key(&PipelineDocument::HandOff(hand_off))
|
||
};
|
||
let stewarded = |name: usize| {
|
||
let mut stewardship = stewardship_sample();
|
||
stewardship.repo = OrgRepo(format!("GameCult/{}", "a".repeat(name)));
|
||
pipeline_key(&PipelineDocument::Stewardship(stewardship))
|
||
};
|
||
for (label, at_64, at_65) in [
|
||
("plain label", received(64 - hand_off_rest), received(65 - hand_off_rest)),
|
||
("escaped repo", stewarded(64 - stewardship_rest), stewarded(65 - stewardship_rest)),
|
||
] {
|
||
let keyed = at_64.unwrap_or_else(|error| panic!("{label}: a 64-byte local keys: {error}"));
|
||
assert_eq!(keyed.split(':').nth(2).map(str::len), Some(64), "{label}: {keyed} fills the local exactly");
|
||
assert!(
|
||
matches!(&at_65, Err(PipelineRefusal::InvalidFormat { value, .. }) if value.len() == 65),
|
||
"{label}: a 65-byte local is refused, got {at_65:?}"
|
||
);
|
||
}
|
||
}
|
||
|
||
/// R2, on the composer every kind goes through: no local part carries the
|
||
/// separator, the head included. The live case is a hand-off with a dotted
|
||
/// receiver, which keys to an escaped label rather than a wider local.
|
||
#[test]
|
||
fn no_local_part_carries_the_separator() {
|
||
assert_eq!(
|
||
local("probe", &["a.b"]),
|
||
Err(PipelineRefusal::InvalidFormat { field: "probe".into(), value: "a.b".into() }),
|
||
"the head may not carry the separator"
|
||
);
|
||
assert_eq!(
|
||
local("probe", &["a", "b.c"]),
|
||
Err(PipelineRefusal::InvalidFormat { field: "probe".into(), value: "b.c".into() }),
|
||
"a tail part may not carry the separator"
|
||
);
|
||
assert_eq!(local("probe", &["a", "b", "c"]), Ok("a.b.c".into()));
|
||
|
||
let mut dotted = hand_off_sample();
|
||
dotted.to_instance = slug("thought-cage.GameCult");
|
||
let key = pipeline_key(&PipelineDocument::HandOff(dotted)).expect("a dotted receiver keys");
|
||
let local = key.split(':').nth(2).expect("three segments");
|
||
assert_eq!(local.split('.').count(), 3, "{key}: the receiver is one part, not two");
|
||
assert_eq!(local.split('.').next(), Some("thought-cage_dGameCult"));
|
||
}
|
||
|
||
/// Q17 B: a subject's resolutions are distinct records, ordered by a
|
||
/// per-subject sequence the key carries as its last part, so a withdrawn
|
||
/// resolution stays under its subject and the next closure is nameable.
|
||
/// The sequence is a field the writer sets and this crate only composes:
|
||
/// it bounds nothing beyond `u32` and the local's own width, so `0` and a
|
||
/// gap both key. Which sequence a document may claim, and whether an
|
||
/// earlier resolution still stands, are admission's rules, exactly as
|
||
/// `revision: 0` is.
|
||
#[test]
|
||
fn a_subject_keeps_every_resolution_it_had() {
|
||
let resolved = |sequence: u32| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.sequence = sequence;
|
||
pipeline_key(&PipelineDocument::Resolution(resolution)).expect("a sequenced resolution keys")
|
||
};
|
||
let first = resolved(1);
|
||
let second = resolved(2);
|
||
assert_eq!(first, format!("{CAMPAIGN}:resolution:question.Q1.n1"));
|
||
assert_eq!(second, format!("{CAMPAIGN}:resolution:question.Q1.n2"));
|
||
assert_ne!(first, second, "two resolutions of one subject are two documents");
|
||
for (sequence, key) in [(1, &first), (2, &second)] {
|
||
let (root, local) = pipeline_id("read_back", key, PipelineKind::Resolution).expect("reads back");
|
||
assert_eq!(root, CAMPAIGN, "{key}: the subject's root");
|
||
let last = format!("n{sequence}");
|
||
assert_eq!(local.rsplit('.').next(), Some(last.as_str()), "{key} ends in its sequence");
|
||
assert_eq!(local.split('.').count(), 3, "{key}: subject kind, subject local, sequence");
|
||
}
|
||
|
||
// Outcome-invariance now holds per sequence: one record under two
|
||
// outcomes is still one key, which is exactly why a second closure of
|
||
// a subject needs a second sequence and not a second outcome.
|
||
let mut withdrawn = resolution_sample();
|
||
withdrawn.outcome = ResolutionOutcome::Withdrawn { reason: "moot".into() };
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Resolution(withdrawn)),
|
||
Ok(first.clone()),
|
||
"one sequence is one key whatever the outcome"
|
||
);
|
||
|
||
// Stated limits. Both are admission's to refuse and neither is the
|
||
// leaf's, so both compose here.
|
||
assert_eq!(resolved(0), format!("{CAMPAIGN}:resolution:question.Q1.n0"), "the leaf refuses no sequence value");
|
||
let mut widest = resolution_sample();
|
||
widest.subject = PipelineRef { kind: PipelineKind::Ruling, id: id("ruling", "A") };
|
||
widest.sequence = u32::MAX;
|
||
assert_eq!(
|
||
pipeline_key(&PipelineDocument::Resolution(widest)),
|
||
Ok(format!("{CAMPAIGN}:resolution:ruling.A.n4294967295")),
|
||
"the widest sequence is an eleven-byte label, not a refusal"
|
||
);
|
||
}
|
||
|
||
/// D2: the sequence is the *last* part, so a subject's resolutions and
|
||
/// only they share the prefix `<root>:resolution:<kind>.<local>.n`. R2 is
|
||
/// what makes the prefix exact: no local part carries a dot, so
|
||
/// `question.Q1.n` cannot match `question.Q10.n1`, and the withdrawal of
|
||
/// `Q1`'s first resolution is a record of that resolution, one nesting
|
||
/// out and outside `Q1`'s prefix. Pinned as a string property, which is
|
||
/// what a prefix query is.
|
||
#[test]
|
||
fn a_subjects_resolutions_share_a_prefix_no_other_key_has() {
|
||
let resolved = |kind: PipelineKind, subject: &str, sequence: u32| {
|
||
let mut resolution = resolution_sample();
|
||
resolution.subject = PipelineRef { kind, id: Short(subject.into()) };
|
||
resolution.sequence = sequence;
|
||
pipeline_key(&PipelineDocument::Resolution(resolution)).expect("the subject keys")
|
||
};
|
||
let history = [1, 2, 3].map(|sequence| resolved(PipelineKind::Question, &id("question", "Q1").0, sequence));
|
||
let others = [
|
||
resolved(PipelineKind::Question, &id("question", "Q10").0, 1),
|
||
resolved(PipelineKind::Ruling, &id("ruling", "Q1").0, 1),
|
||
resolved(PipelineKind::Campaign, &format!("{CAMPAIGN}:campaign:self"), 1),
|
||
resolved(PipelineKind::Resolution, &history[0], 1),
|
||
];
|
||
assert_eq!(
|
||
others[3],
|
||
format!("{CAMPAIGN}:resolution:resolution.question.Q1.n1.n1"),
|
||
"a withdrawal keys under the resolution it withdraws, not under the subject"
|
||
);
|
||
let prefix = format!("{CAMPAIGN}:resolution:question.Q1.n");
|
||
let selected = history
|
||
.iter()
|
||
.chain(others.iter())
|
||
.filter(|key| key.starts_with(&prefix))
|
||
.collect::<Vec<_>>();
|
||
assert_eq!(
|
||
selected,
|
||
history.iter().collect::<Vec<_>>(),
|
||
"the prefix selects the subject's resolutions and nothing else"
|
||
);
|
||
}
|
||
|
||
/// Q18 A and Q20 A: a repo's stewardships on a mind are distinct records,
|
||
/// ordered by a per-`(instance, repo)` sequence the key carries last, so a
|
||
/// repo transferred away and later transferred back is two records under
|
||
/// one prefix rather than one document overwriting the other. The date is
|
||
/// not in the key: `assigned_on` is validated where every field is, by the
|
||
/// derived `Bounded` impl, and two assignments differing only in it are
|
||
/// one document.
|
||
#[test]
|
||
fn a_repo_keeps_every_stewardship_it_had() {
|
||
let stewarded = |repo: &str, sequence: u32, assigned_on: &str| {
|
||
let mut stewardship = stewardship_sample();
|
||
stewardship.repo = OrgRepo(repo.into());
|
||
stewardship.sequence = sequence;
|
||
stewardship.assigned_on = Date(assigned_on.into());
|
||
pipeline_key(&PipelineDocument::Stewardship(stewardship)).expect("a sequenced stewardship keys")
|
||
};
|
||
let first = stewarded("GameCult/Epiphany", 1, "2026-09-15");
|
||
let second = stewarded("GameCult/Epiphany", 2, "2026-09-16");
|
||
assert_eq!(first, format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n1"));
|
||
assert_eq!(second, format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n2"));
|
||
assert_ne!(first, second, "two assignments of one repo are two documents");
|
||
for (sequence, key) in [(1, &first), (2, &second)] {
|
||
let (root, local) = pipeline_id("read_back", key, PipelineKind::Stewardship).expect("reads back");
|
||
assert_eq!(root, INSTANCE, "{key}: the mind's root");
|
||
let last = format!("n{sequence}");
|
||
assert_eq!(local.rsplit('.').next(), Some(last.as_str()), "{key} ends in its sequence");
|
||
assert_eq!(local.split('.').count(), 2, "{key}: the escaped repo and the sequence, nothing else");
|
||
}
|
||
|
||
assert_eq!(
|
||
stewarded("GameCult/Epiphany", 1, "2026-09-16"),
|
||
first,
|
||
"assigned_on is a field, not a key part: one sequence is one key whatever the date"
|
||
);
|
||
|
||
let others = [
|
||
stewarded("GameCult/Epiphany_thing", 1, "2026-09-15"),
|
||
stewarded("GameCult/Huginn", 1, "2026-09-15"),
|
||
];
|
||
let prefix = format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n");
|
||
let history = [first, second];
|
||
let selected = history
|
||
.iter()
|
||
.chain(others.iter())
|
||
.filter(|key| key.starts_with(&prefix))
|
||
.collect::<Vec<_>>();
|
||
assert_eq!(
|
||
selected,
|
||
history.iter().collect::<Vec<_>>(),
|
||
"the prefix selects the repo's assignments on this mind and nothing else"
|
||
);
|
||
|
||
assert_eq!(
|
||
stewarded("GameCult/Epiphany", 0, "2026-09-15"),
|
||
format!("{INSTANCE}:stewardship:GameCult_-Epiphany.n0"),
|
||
"the leaf refuses no sequence value"
|
||
);
|
||
}
|
||
|
||
/// Cut 8: the leaf owns the serialisation of the shapes it owns, so a wire
|
||
/// carrying a document or a refusal reads back the same value rather than
|
||
/// a mirror definition kept in step by hand in the reader's repo. Both
|
||
/// encodings are pinned: JSON is what a schema describes, MessagePack is
|
||
/// what a CultCache payload is written in, and an adjacent tag has to
|
||
/// survive both. The tag is asserted against `name()` rather than against
|
||
/// a literal, because the point of the tag is that a reader dispatching on
|
||
/// a key's kind segment finds the same string here.
|
||
#[test]
|
||
fn every_document_and_refusal_serialises_and_reads_back() -> Result<()> {
|
||
for (document, _) in samples() {
|
||
let json = serde_json::to_value(&document)?;
|
||
assert_eq!(json["kind"].as_str(), Some(document.kind().name()), "{json} is tagged with its kind name");
|
||
assert_eq!(serde_json::from_value::<PipelineDocument>(json.clone())?, document, "{json} reads back");
|
||
let packed = rmp_serde::to_vec_named(&document)?;
|
||
assert_eq!(
|
||
rmp_serde::from_slice::<PipelineDocument>(&packed)?,
|
||
document,
|
||
"{:?} reads back through MessagePack",
|
||
document.kind()
|
||
);
|
||
}
|
||
|
||
// Every variant, and every one of them carrying its named parts: a
|
||
// refusal read off a wire names the field it refused, as a local one
|
||
// does.
|
||
let refusals = [
|
||
PipelineRefusal::FieldBound { field: "campaign.title".into(), limit: 200, actual: 201 },
|
||
PipelineRefusal::InvalidFormat { field: "campaign.slug".into(), value: "a b".into() },
|
||
PipelineRefusal::InvalidIdentity {
|
||
kind: PipelineKind::Campaign,
|
||
key: format!("{CAMPAIGN}:campaign:forged"),
|
||
expected: format!("{CAMPAIGN}:campaign:self"),
|
||
},
|
||
PipelineRefusal::ForeignStore { r#type: <ForeignDocument as DatabaseEntry>::TYPE.into() },
|
||
];
|
||
for refusal in &refusals {
|
||
let json = serde_json::to_value(refusal)?;
|
||
assert_eq!(&serde_json::from_value::<PipelineRefusal>(json.clone())?, refusal, "{json} reads back");
|
||
let packed = rmp_serde::to_vec_named(refusal)?;
|
||
assert_eq!(
|
||
&rmp_serde::from_slice::<PipelineRefusal>(&packed)?,
|
||
refusal,
|
||
"{refusal:?} reads back through MessagePack"
|
||
);
|
||
}
|
||
|
||
// The derived schemas list the same two sets. A `const` in the tag
|
||
// position is what a schema reader dispatches on, so it is read as the
|
||
// schema writes it and compared to `name()`, not to a literal list.
|
||
let tag = |variant: &serde_json::Value| {
|
||
variant["properties"]["kind"]["const"]
|
||
.as_str()
|
||
.unwrap_or_else(|| panic!("a document variant schema carries a kind const: {variant}"))
|
||
.to_owned()
|
||
};
|
||
let document_schema = serde_json::to_value(schemars::schema_for!(PipelineDocument))?;
|
||
let variants = document_schema["oneOf"].as_array().expect("the document schema is a oneOf");
|
||
assert_eq!(PipelineKind::ALL.len(), 13, "thirteen kinds");
|
||
assert_eq!(
|
||
variants.iter().map(tag).collect::<Vec<_>>(),
|
||
PipelineKind::ALL.iter().map(|kind| kind.name().to_owned()).collect::<Vec<_>>(),
|
||
"the document schema lists exactly the thirteen kinds, by name"
|
||
);
|
||
|
||
let refusal_schema = serde_json::to_value(schemars::schema_for!(PipelineRefusal))?;
|
||
let refusal_variants = refusal_schema["oneOf"].as_array().expect("the refusal schema is a oneOf");
|
||
let named = refusal_variants
|
||
.iter()
|
||
.map(|variant| {
|
||
let properties = variant["properties"].as_object().expect("a refusal variant is an object");
|
||
assert_eq!(properties.len(), 1, "{variant} is externally tagged");
|
||
properties.keys().next().expect("one key").to_owned()
|
||
})
|
||
.collect::<Vec<_>>();
|
||
assert_eq!(named, vec!["FieldBound", "InvalidFormat", "InvalidIdentity", "ForeignStore"]);
|
||
assert_eq!(named.len(), refusals.len(), "every refusal variant is in the schema and in the round trip");
|
||
Ok(())
|
||
}
|
||
|
||
#[test]
|
||
fn pipeline_published_schemas_match_derivation() -> Result<()> {
|
||
let published = Path::new(env!("CARGO_MANIFEST_DIR")).join("../schemas/cultnet");
|
||
let index: serde_json::Value = serde_json::from_slice(&std::fs::read(published.join("index.json"))?)?;
|
||
// A directory this run alone writes, so everything in it is what this
|
||
// run derived. A previous run's leftovers -- a mutation run's
|
||
// especially, since those deliberately derive schemas no committed type
|
||
// produces -- are not this derivation, and copying one of those into
|
||
// `schemas/cultnet` publishes a schema no Rust type produces. A shared
|
||
// directory cleared first would have to defend that clear against a
|
||
// held handle; an unshared one has nothing to defend. The cost is that
|
||
// nothing ever removes one. The directory is only created when
|
||
// something is stale, so a passing run leaves none -- but a failing run
|
||
// leaves its copies behind for good, one directory per failing run
|
||
// where the shared design left one however often it failed. That is the
|
||
// trade: the copies are the evidence the failure message names, and
|
||
// they outlive the run that wrote them. Whoever reads the failure is
|
||
// the one who deletes them.
|
||
let derived_dir = std::env::temp_dir().join(format!(
|
||
"epiphany-pipeline-schemas-{}-{}",
|
||
std::process::id(),
|
||
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH)?.as_nanos()
|
||
));
|
||
let mut stale = Vec::new();
|
||
for kind in PipelineKind::ALL {
|
||
let file = format!("{}.schema.json", kind.type_id());
|
||
let mut schema = serde_json::to_value(kind.derived_schema())?;
|
||
schema["$id"] = format!("https://gamecult.dev/epiphany/cultnet/{file}").into();
|
||
let derived = format!("{}\n", serde_json::to_string_pretty(&schema)?);
|
||
if std::fs::read(published.join(&file)).ok().as_deref() != Some(derived.as_bytes()) {
|
||
std::fs::create_dir_all(&derived_dir)?;
|
||
std::fs::write(derived_dir.join(&file), &derived)?;
|
||
stale.push(derived_dir.join(&file));
|
||
}
|
||
let entry = serde_json::json!({
|
||
"schemaId": format!("https://gamecult.dev/epiphany/cultnet/{file}"),
|
||
"kind": "document_payload",
|
||
"wireContracts": ["cultnet.schema.v0"],
|
||
"schemaVersion": kind.type_id(),
|
||
"documentType": kind.type_id(),
|
||
"title": format!("Epiphany Pipeline {kind:?} v1"),
|
||
"path": file,
|
||
});
|
||
assert!(
|
||
index["schemas"].as_array().is_some_and(|schemas| schemas.contains(&entry)),
|
||
"index.json lacks {entry}"
|
||
);
|
||
}
|
||
assert!(stale.is_empty(), "published pipeline schemas differ from the Rust derivation; derived copies: {stale:?}");
|
||
Ok(())
|
||
}
|
||
|
||
/// The epoch is the version every kind is published at: its version
|
||
/// segment is read from the constant, not restated, and every type id
|
||
/// carries the same one, so a bumped epoch fails here until the kinds
|
||
/// move with it. The live registrar registers the kinds and nothing else,
|
||
/// so the foreign stand-in is not among them.
|
||
#[test]
|
||
fn every_kind_is_at_the_epochs_version() -> Result<()> {
|
||
let (name, version) = PIPELINE_SCHEMA_EPOCH.rsplit_once('.').expect("the epoch carries a version");
|
||
assert_eq!(name, "epiphany.pipeline.epoch");
|
||
assert!(
|
||
version.len() > 1 && version.starts_with('v') && version[1..].bytes().all(|byte| byte.is_ascii_digit()),
|
||
"{version:?} is not a version segment"
|
||
);
|
||
for kind in PipelineKind::ALL {
|
||
let type_id = kind.type_id();
|
||
assert!(type_id.ends_with(&format!(".{version}")), "{type_id} is not at the epoch's version {version}");
|
||
}
|
||
|
||
let mut cache = CultCache::new();
|
||
register_pipeline_document_types(&mut cache)?;
|
||
let registered = cache.registered_entry_types();
|
||
assert_eq!(registered.len(), PipelineKind::ALL.len(), "the live registrar registers exactly the kinds: {registered:?}");
|
||
for kind in PipelineKind::ALL {
|
||
assert!(registered.iter().any(|name| name == kind.type_id()), "{kind:?} is registered");
|
||
}
|
||
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(())
|
||
}
|
||
}
|