//! 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 `::`, 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`, 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` has no `Bounded` impl of its own. A field added //! at the epoch carries the `= absent` marker, which defaults it on read and //! omits it on write when empty. //! //! 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 }, DuplicateRepo { field: String, repo: 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 Bounded for Option { fn validate(&self, field: &str) -> Result<(), PipelineRefusal> { self.as_ref().map_or(Ok(()), |value| value.validate(field)) } } /// A value with an empty spelling. The `= absent` marker on a `value_types!` /// field requires it, and the field is then omitted on write when it is absent. pub(crate) trait Absent { fn absent(&self) -> bool; } impl Absent for Option { fn absent(&self) -> bool { self.is_none() } } impl Absent for bool { fn absent(&self) -> bool { !*self } } impl Absent for Vec { fn absent(&self) -> bool { self.is_empty() } } macro_rules! unbounded_scalars { ($($ty:ty),* $(,)?) => {$( impl Bounded for $ty { fn validate(&self, _field: &str) -> Result<(), PipelineRefusal> { Ok(()) } } )*}; } unbounded_scalars!(u8, u16, 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(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) -> 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> { dotted_within(field, value, 64) } /// `dotted_text`'s grammar with the bound as a parameter: the one place a /// dotted segment is parsed, whoever owns the bound. fn dotted_within(field: &str, value: &str, max: usize) -> Result<(), PipelineRefusal> { if value.is_empty() || value.len() > max { return Err(format_error(field, value)); } for part in value.split('.') { label_text(field, part)?; } Ok(()) } /// GitHub's own grammar for `owner/repo`, exactly one `/`: the owner is /// `[A-Za-z0-9-]`, 1 to 39 bytes, with no leading or trailing hyphen; the repo /// is `[A-Za-z0-9._-]`, 1 to 100 bytes, is never `.` or `..`, and does not end /// in `.git`, ASCII-case-insensitively (`a/b.GIT` is refused exactly as /// `a/b.git` is), so the suffix rule cannot be dodged by a case variant whose /// `identity()` is refused. The repo's own byte alphabet excludes `/`, so a /// second `/` inside it is already refused by the byte check; no separate /// `contains('/')` check is needed. fn org_repo_text(field: &str, value: &str) -> Result<(), PipelineRefusal> { let valid = value.split_once('/').is_some_and(|(owner, repo)| { (1..=39).contains(&owner.len()) && owner.bytes().all(|byte| byte.is_ascii_alphanumeric() || byte == b'-') && !owner.starts_with('-') && !owner.ends_with('-') && (1..=100).contains(&repo.len()) && repo.bytes().all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-')) && repo != "." && repo != ".." && !(repo.len() >= 4 && repo[repo.len() - 4..].eq_ignore_ascii_case(".git")) }); if valid { Ok(()) } else { Err(format_error(field, value)) } } macro_rules! bounded_text { ($($(#[$doc:meta])* $name:ident = $limit:literal, $check:expr;)*) => {$( #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema)] #[serde(transparent)] #[schemars(extend("maxLength" = $limit))] $(#[$doc])* 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()) } /// A title holds at least one `char::is_alphanumeric()` character, no /// `char::is_control()` character, no U+2028 LINE SEPARATOR or U+2029 /// PARAGRAPH SEPARATOR (both `Zl`/`Zp`, so `is_control()` does not reach /// them, and a one-line field should carry no hard line break), and no bidi /// control character: `U+061C`, `U+200E`, `U+200F`, `U+202A`-`U+202E`, /// `U+2066`-`U+2069`. No denylist of individual zero-width or format /// characters is maintained here; a character not covered by one of these /// tests is allowed, so ZWJ and ZWNJ still work. fn title_text(field: &str, value: &str) -> Result<(), PipelineRefusal> { let alphanumeric = value.chars().any(|character| character.is_alphanumeric()); let control = value .chars() .any(|character| character.is_control() || matches!(character, '\u{2028}' | '\u{2029}')); let bidi = value.chars().any(|character| { matches!( character, '\u{061C}' | '\u{200E}' | '\u{200F}' | '\u{202A}'..='\u{202E}' | '\u{2066}'..='\u{2069}' ) }); if !alphanumeric || control || bidi { return Err(format_error(field, value)); } within(200)(field, value) } /// A symbol is 1 to 128 bytes with no whitespace and no control character. fn symbol_text(field: &str, value: &str) -> Result<(), PipelineRefusal> { if value.is_empty() || value.chars().any(|character| character.is_whitespace() || character.is_control()) { return Err(format_error(field, value)); } within(128)(field, value) } /// A lowercase D-format UUID: 8-4-4-4-12 lowercase hex digits, any version. fn uuid_text(field: &str, value: &str) -> Result<(), PipelineRefusal> { let shaped = value.len() == 36 && value.bytes().enumerate().all(|(at, byte)| match at { 8 | 13 | 18 | 23 => byte == b'-', _ => matches!(byte, b'0'..=b'9' | b'a'..=b'f'), }); if !shaped { return Err(format_error(field, value)); } Ok(()) } /// A person's words: 1 to 4000 UTF-8 bytes and not blank (`str::trim` leaves something). fn words_text(field: &str, value: &str) -> Result<(), PipelineRefusal> { if value.trim().is_empty() { return Err(format_error(field, value)); } within(4000)(field, value) } bounded_text! { /// Text of at most 200 UTF-8 bytes. Short = 200, |field, value| within(200)(field, value); /// A title: 1 to 200 UTF-8 bytes, enforced by admission; JSON Schema /// length counts characters. Holds at least one alphanumeric character, /// no control character, and no bidi control character (`U+061C`, /// `U+200E`, `U+200F`, `U+202A`-`U+202E`, `U+2066`-`U+2069`). #[schemars(extend("minLength" = 1))] Title = 200, title_text; /// Text of at most 1,000 UTF-8 bytes. Line = 1000, |field, value| within(1000)(field, value); /// A name the location's lines must contain as written there (an /// identifier or a YAML `&fileID`); not an identity. 1 to 128 bytes, no /// whitespace and no control character. #[schemars(extend("minLength" = 1))] Symbol = 128, symbol_text; /// Text of at most 4,000 UTF-8 bytes; longer narrative is cited by `DocRef`. Para = 4000, |field, value| within(4000)(field, value); /// A person's words, verbatim: 1 to 4,000 UTF-8 bytes, not blank (CultLib PR #72, `answer.note`). #[schemars(extend("minLength" = 1))] Words = 4000, words_text; /// A client's retry token: a lowercase D-format UUID. RequestId = 36, uuid_text; /// 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 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); } impl Sha { /// The type's identity rule: two spellings name one commit when one is a /// prefix of the other, so a 7-character abbreviation and the full id of /// the same commit are equal here though not `==`. Both are already 7-40 /// lowercase hex. Two distinct commits that share a 7-character prefix are /// git's ambiguity, not the mind's. pub fn names_same_commit(&self, other: &Sha) -> bool { self.0.starts_with(&other.0) || other.0.starts_with(&self.0) } } impl Slug { /// The public door onto the slug grammar, for a caller outside this crate /// that holds a bare `Slug` and no way to reach `Bounded`, which is /// crate-private. On the pattern of `PipelineRef::validate_ref`: it /// delegates so the grammar keeps one owner, and it applies exactly the /// `dotted_text` check that every `Slug` field in this crate is held to, /// so a caller that validates a declared name this way and a document /// field of the same type refuse the same inputs. Named `validate_slug` /// rather than a bare `validate`, because an inherent `validate` would /// shadow `Bounded`'s for every in-crate caller holding a `Slug`. pub fn validate_slug(&self) -> Result<(), PipelineRefusal> { Bounded::validate(self, "slug") } } /// A GitHub repository as `Org/Repo`, at most 140 UTF-8 bytes (39 + 1 + /// 100). The owner is 1 to 39 `[A-Za-z0-9-]` bytes with no leading or /// trailing hyphen; the repo is 1 to 100 `[A-Za-z0-9._-]` bytes, is never /// `.` or `..`, and does not end in `.git`, ASCII-case-insensitively. /// Identity is case-insensitive: `GameCult/Epiphany` and `gamecult/epiphany` /// are the same repository. // // The raw string is display-only. `OrgRepo` is not generated by // `bounded_text!`: that macro derives `PartialEq`, `Eq`, `Hash`, `PartialOrd` // and `Ord` on the raw string, with no per-member override, so a type built // from it compares and keys on spelling. `OrgRepo` instead carries // hand-written impls of those five traits, every one of them over // `identity()` (the ASCII-lowercased value), so `==`, a `BTreeMap` key and a // `HashMap` key are all case-insensitive by construction: `GameCult/Epiphany` // and `gamecult/epiphany` compare equal, hash equal, order together and // collapse to one map entry, and a caller cannot reach the case-sensitive // behaviour by accident. `Hash` and `Eq` agree because both are defined over // the same `identity()` string. Every other bounded type keeps the macro's // derives untouched. This reasoning is a source comment, not a doc comment, // so it does not enter the published schema description (RS-L closing fix 2): // a consumer needs the grammar, the bound and the case-insensitivity, not the // Rust-macro justification for how that got built. #[derive(Clone, Debug, Default, Serialize, Deserialize, JsonSchema)] #[serde(transparent)] #[schemars(extend("maxLength" = 140))] pub struct OrgRepo(pub String); impl Bounded for OrgRepo { fn validate(&self, field: &str) -> Result<(), PipelineRefusal> { org_repo_text(field, &self.0) } } impl From<&str> for OrgRepo { fn from(value: &str) -> Self { Self(value.into()) } } impl PartialEq for OrgRepo { fn eq(&self, other: &Self) -> bool { self.identity() == other.identity() } } impl Eq for OrgRepo {} impl std::hash::Hash for OrgRepo { fn hash(&self, state: &mut H) { self.identity().hash(state); } } impl PartialOrd for OrgRepo { fn partial_cmp(&self, other: &Self) -> Option { Some(self.cmp(other)) } } impl Ord for OrgRepo { fn cmp(&self, other: &Self) -> std::cmp::Ordering { self.identity().cmp(&other.identity()) } } impl OrgRepo { /// The public door onto the `org_repo` grammar, for a caller outside this /// crate that holds a bare `OrgRepo` (the organ's `repo` alias, RS-3) and /// no way to reach `Bounded`. On the pattern of `Slug::validate_slug`: it /// delegates to `org_repo_text` through `Bounded::validate`, so the /// grammar keeps one owner and a declared name checked this way refuses /// exactly what a document's own `OrgRepo` field refuses. pub fn validate_org_repo(&self) -> Result<(), PipelineRefusal> { Bounded::validate(self, "org_repo") } /// The one canonical key for an `OrgRepo`: the value, ASCII-lowercased. /// Every comparison, hash, ordering and lookup keyed by repository /// identity goes through this — `PartialEq`, `Hash` and `Ord` above are /// all defined in terms of it — so `GameCult/Epiphany` and /// `gamecult/epiphany` are the same repository everywhere, not only where /// a caller remembers to ask. pub fn identity(&self) -> String { self.0.to_ascii_lowercase() } } impl Label { /// The public door onto the label grammar, for a caller outside this /// crate that holds a bare `Label` (the organ's `cut` alias, RS-3) and no /// way to reach `Bounded`. On the pattern of `Slug::validate_slug`: it /// delegates to `label_text` through `Bounded::validate`, so the grammar /// keeps one owner and a declared name checked this way refuses exactly /// what a document's own `Label` field refuses. pub fn validate_label(&self) -> Result<(), PipelineRefusal> { Bounded::validate(self, "label") } } /// 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])? $(= $marker:ident)?),* $(,)? } $(=> $extra:path)?)*) => {$( $(#[$attr])* #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)] pub struct $name { $( $(#[schemars(extend("maxItems" = $max))])? // `= absent`: defaulted on read, omitted on write when absent. // The `cfg_attr(any(), ..)` is a no-op that binds `$marker` to the group. $(#[serde(default, skip_serializing_if = "Absent::absent")] #[cfg_attr(any(), $marker)])? pub $field: $ty ),* } impl Bounded for $name { fn validate(&self, at: &str) -> Result<(), PipelineRefusal> { $( $(let _: fn(&$ty) -> bool = <$ty as Absent>::$marker;)? bounded_field!(self.$field, &format!("{at}.{}", stringify!($field)) $(, $max)?); )* $($extra(self, at)?;)? 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 $name { /// The variants' spellings, in declaration order: the names the wire and /// `Debug` use. pub const NAMES: &'static [&'static str] = &[$(stringify!($variant)),*]; } impl Bounded for $name { fn validate(&self, _field: &str) -> Result<(), PipelineRefusal> { Ok(()) } } )*}; } /// RS-L closing fix 4: a repo list refuses two entries naming the same /// repository by identity, not by raw spelling, so `GameCult/Epiphany` and /// `gamecult/epiphany` in one list refuse exactly as one entry twice would. /// This is a cross-element invariant on the lists alone, not a per-type format /// rule any other `value_types!` struct shares, so it is wired in as the /// `=> extra` hook of the two structs that carry a repo list /// (`PipelineCampaign.repos` and `PipelineTarget.repos`) rather than folded /// into `Bounded for OrgRepo` or the list bound in `bounded_field!`. fn repos_are_distinct(repos: &[OrgRepo], at: &str) -> Result<(), PipelineRefusal> { let mut seen = std::collections::HashSet::new(); for repo in repos { if !seen.insert(repo.identity()) { return Err(PipelineRefusal::DuplicateRepo { field: format!("{at}.repos"), repo: repo.0.clone(), }); } } Ok(()) } fn campaign_repos_are_distinct(campaign: &PipelineCampaign, at: &str) -> Result<(), PipelineRefusal> { repos_are_distinct(&campaign.repos, at) } fn target_repos_are_distinct(target: &PipelineTarget, at: &str) -> Result<(), PipelineRefusal> { repos_are_distinct(&target.repos, at) } /// The most lines one read anchor may span. const READ_WINDOW_MAX_LINES: u32 = 100; /// A location starts at line 1 or later, ends no earlier than it starts, and a /// read anchor spans at most `READ_WINDOW_MAX_LINES`. The bounds are on /// `ReadAnchor` alone: `CodeLocation` elsewhere keeps its stored shape. fn read_window_is_bounded(anchor: &ReadAnchor, at: &str) -> Result<(), PipelineRefusal> { let location = &anchor.location; if location.line < 1 { return Err(format_error(&format!("{at}.location.line"), &location.line.to_string())); } if let Some(end_line) = location.end_line { if end_line < location.line { return Err(format_error(&format!("{at}.location.end_line"), &end_line.to_string())); } let span = end_line - location.line + 1; if span > READ_WINDOW_MAX_LINES { return Err(PipelineRefusal::FieldBound { field: format!("{at}.location.end_line"), limit: READ_WINDOW_MAX_LINES, actual: span, }); } } Ok(()) } /// A run claims work, never runs, rulings or campaigns: its claims are cut /// specs, findings and follow-ups, the three kinds a Self takes on. And its /// budget is a canonical decimal (`0`, `12`, `7.5`: no sign, no leading or /// trailing zeros, no exponent), so one spend has one spelling. fn run_is_well_formed(run: &PipelineRun, at: &str) -> Result<(), PipelineRefusal> { for (index, claim) in run.claims.iter().enumerate() { if !matches!(claim.kind, PipelineKind::CutSpec | PipelineKind::Finding | PipelineKind::FollowUp) { return Err(format_error(&format!("{at}.claims[{index}].kind"), claim.kind.name())); } if run.claims[..index].contains(claim) { return Err(format_error(&format!("{at}.claims[{index}]"), &claim.id.0)); } } let (whole, fraction) = run.budget_usd.0.split_once('.').map_or((run.budget_usd.0.as_str(), None), |(whole, fraction)| (whole, Some(fraction))); let digits = |text: &str| !text.is_empty() && text.bytes().all(|byte| byte.is_ascii_digit()); let canonical = digits(whole) && (whole == "0" || !whole.starts_with('0')) && fraction.is_none_or(|fraction| digits(fraction) && !fraction.ends_with('0')); if canonical { Ok(()) } else { Err(format_error(&format!("{at}.budget_usd"), &run.budget_usd.0)) } } /// A chat name holds a letter or a digit and has no space at either end, so it can match a whole word. fn stewardship_is_well_formed(stewardship: &PipelineStewardship, at: &str) -> Result<(), PipelineRefusal> { for (index, name) in stewardship.names.iter().enumerate() { if name.0.trim() != name.0 || !name.0.chars().any(char::is_alphanumeric) { return Err(format_error(&format!("{at}.names[{index}]"), &name.0)); } } Ok(()) } /// The longest and shortest beat a Mind may vote for, in seconds. pub const TEMPO_VOTE_MIN_S: u32 = 60; pub const TEMPO_VOTE_MAX_S: u32 = 86_400; /// Urgency is in thousandths: 0 declares none, 1000 the most. pub const URGENCY_MAX_PERMILLE: u16 = 1000; /// A pulse votes a tempo or declares an urgency, in bounds, or says nothing it /// could be read for: an empty pulse is refused. fn pulse_is_well_formed(pulse: &PipelinePulse, at: &str) -> Result<(), PipelineRefusal> { if let Some(beat) = pulse.tempo_vote_beat_s && !(TEMPO_VOTE_MIN_S..=TEMPO_VOTE_MAX_S).contains(&beat) { return Err(format_error(&format!("{at}.tempo_vote_beat_s"), &beat.to_string())); } if let Some(urgency) = pulse.urgency_permille && urgency > URGENCY_MAX_PERMILLE { return Err(format_error(&format!("{at}.urgency_permille"), &urgency.to_string())); } if pulse.tempo_vote_withdrawn && pulse.tempo_vote_beat_s.is_some() { return Err(format_error(&format!("{at}.tempo_vote_withdrawn"), "a pulse that votes a beat and withdraws the vote")); } if pulse.tempo_vote_beat_s.is_none() && !pulse.tempo_vote_withdrawn && pulse.urgency_permille.is_none() { return Err(format_error(&format!("{at}.tempo_vote_beat_s"), "a pulse that votes and declares nothing")); } Ok(()) } /// A reply says something and answers only follow-ups, from a run. fn reply_is_well_formed(reply: &PipelineReply, at: &str) -> Result<(), PipelineRefusal> { if reply.text.0.trim().is_empty() { return Err(format_error(&format!("{at}.text"), "a reply with no words")); } if reply.run.kind != PipelineKind::Run { return Err(format_error(&format!("{at}.run.kind"), reply.run.kind.name())); } for (index, answer) in reply.answers.iter().enumerate() { if answer.kind != PipelineKind::FollowUp { return Err(format_error(&format!("{at}.answers[{index}].kind"), answer.kind.name())); } } Ok(()) } /// The most candidates a continuation may offer, and the nearness that means /// she had no earlier thought to be near. pub const THOUGHT_CANDIDATES_MAX: usize = 4; pub const THOUGHT_NEAREST_NONE_PERMILLE: u16 = 1000; /// A thought says something it was chosen to say: its text is not blank and is /// the chosen candidate, every candidate has its nearness, and no nearness is /// over 1000 thousandths. fn thought_is_well_formed(thought: &PipelineThought, at: &str) -> Result<(), PipelineRefusal> { if thought.text.0.trim().is_empty() { return Err(format_error(&format!("{at}.text"), "a thought with no words")); } if thought.prompt_version.0.trim().is_empty() { return Err(format_error(&format!("{at}.prompt_version"), "a thought with no prompt version")); } if thought.candidates.is_empty() || thought.candidates.len() > THOUGHT_CANDIDATES_MAX { return Err(format_error(&format!("{at}.candidates"), &format!("{} candidates", thought.candidates.len()))); } if thought.nearest_permille.len() != thought.candidates.len() { return Err(format_error(&format!("{at}.nearest_permille"), "a nearness list that is not one per candidate")); } if let Some(over) = thought.nearest_permille.iter().position(|near| *near > THOUGHT_NEAREST_NONE_PERMILLE) { return Err(format_error(&format!("{at}.nearest_permille[{over}]"), &thought.nearest_permille[over].to_string())); } match thought.candidates.get(usize::from(thought.chosen)) { None => Err(format_error(&format!("{at}.chosen"), &thought.chosen.to_string())), Some(chosen) if chosen.0 != thought.text.0 => Err(format_error(&format!("{at}.text"), "a thought that is not its chosen candidate")), Some(_) => Ok(()), } } /// The most thousandths a memory's salience may carry. pub const SALIENCE_MAX_PERMILLE: u16 = 1000; /// A memory says something (its text is not empty), its salience is in /// thousandths, and it consolidates only memories. fn memory_is_well_formed(memory: &PipelineMemory, at: &str) -> Result<(), PipelineRefusal> { if memory.text.0.trim().is_empty() { return Err(format_error(&format!("{at}.text"), "an empty memory")); } if let MemoryOrigin::Direct { with, .. } = &memory.origin && with.is_empty() { return Err(format_error(&format!("{at}.origin.with"), "a direct memory that names no one she heard it from")); } if memory.salience_permille > SALIENCE_MAX_PERMILLE { return Err(format_error(&format!("{at}.salience_permille"), &memory.salience_permille.to_string())); } for (index, entry) in memory.consolidates.iter().enumerate() { if entry.kind != PipelineKind::Memory { return Err(format_error(&format!("{at}.consolidates[{index}].kind"), entry.kind.name())); } } Ok(()) } /// A research note states a claim and stands on at least one source that /// names something: a Repo source a file and a range that does not end before /// it starts, a Web source its address and work, an Observed one its /// locator and result, a Document one a note other than this one. A claim /// with no source is not research. An inferred note names what it inferred /// from in those sources. Two notes citing each other cannot be seen from one /// document; that refusal would need the image, so it is not made here. fn research_is_well_formed(research: &PipelineResearch, at: &str) -> Result<(), PipelineRefusal> { if research.claim.0.trim().is_empty() { return Err(format_error(&format!("{at}.claim"), "an empty claim")); } if research.sources.is_empty() { return Err(format_error(&format!("{at}.sources"), "a research note that names no source")); } let own_key = format!("{}:research:{}.{}", research.campaign.0, research.pass.0, research.label.0); let blank = |text: &str| text.trim().is_empty(); for (index, source) in research.sources.iter().enumerate() { let (field, empty) = match source { ResearchSource::Repo { at, .. } if blank(&at.path.0) => ("at.path", "a repo source pinning no file"), ResearchSource::Repo { at, .. } if at.end_line < at.start_line => ("at.end_line", "a repo source whose range ends before it starts"), ResearchSource::Web { url, .. } if blank(&url.0) => ("url", "a web source with no address"), ResearchSource::Web { work, .. } if blank(&work.0) => ("work", "a web source naming no work"), ResearchSource::Observed { evidence } if blank(&evidence.locator.0) => ("evidence.locator", "an observation naming nothing observed"), ResearchSource::Observed { evidence } if blank(&evidence.result.0) => ("evidence.result", "an observation with no result"), ResearchSource::Document { reference } if reference.kind == PipelineKind::Research && reference.id.0 == own_key => ("reference", "a note that is its own source"), _ => continue, }; return Err(format_error(&format!("{at}.sources[{index}].{field}"), empty)); } Ok(()) } /// An idea says something. It may serve no fork and rest on nothing. fn idea_is_well_formed(idea: &PipelineIdea, at: &str) -> Result<(), PipelineRefusal> { if idea.idea.0.trim().is_empty() { return Err(format_error(&format!("{at}.idea"), "an empty idea")); } Ok(()) } unit_enums! { EvidenceKind { Command, Test, Mutation, Probe, SourceRead, Capture } ClaimOutcome { Holds, Falsified, Unproven } FindingConfidence { Confirmed, Plausible } FindingSeverity { Blocker, High, Medium, Low } FindingOrigin { Introduced, PreExisting } RunOperator { Operator, Mind } RunTurn { PersonaTurn, SelfRun, Sleep } MemorySort { Asked, Decided, Committed, Learned, Did, Idea, Rapport } // The role the verified account holds, an attribution copied from Bifrost's state (CultLib PR #72, // fork-card.md). It confers nothing: whether an answerer may decide is the decider list's, never this. DeskAuthority { Operator, Steward, Member } // Why a desk answer was refused and stored: binding spec 1.3 steps 4-7 and R1. DeskRefusal { StaleFork, NotADecider, ForkClosed, ChoiceInvalid, BadRetraction, AlreadyRetracted } } /// The slots of a Mind's runs: one live run of hers per instance and slot. A /// Persona session and her Sleep run share the Persona slot (unit /// `mind-persona@`); a Self run holds the other. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum RunSlot { Persona, SelfRun, } impl RunTurn { /// The slot this turn holds while live; admission and launch both read it here. pub fn slot(self) -> RunSlot { match self { Self::PersonaTurn | Self::Sleep => RunSlot::Persona, Self::SelfRun => RunSlot::SelfRun, } } } value_types! { pub struct CodeLocation { path: Short, line: u32, end_line: Option, symbol: Option = absent } 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 } /// Code Hands must see but not change, in the spec's repo at the spec's base. pub struct ReadAnchor { location: CodeLocation, why: Short } => read_window_is_bounded pub struct AuthorityMap { owner: Line, inputs: Vec[16], outputs: Vec[16], derived_state: Vec[16], forbidden_writers: Vec[16], shared_paths: Vec[16], deletion_line: Line, } pub struct VerificationTest { name: Short, pins: Line } pub struct NegativeCheck { pattern: Short, scope: Line } pub struct CutVerification { builds: Vec[64], tests: Vec[64], negative: Vec[64], operator: Vec[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[64], dependencies_removed: Vec[64], formats_added: Vec[64], formats_removed: Vec[64], targets_added: Vec[64], targets_removed: Vec[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[8], findings: Vec[16], promise: Option