subc_protocol/

manifest.rs

//! Capability manifest schema for subc modules.
//!
//! All v1 modules are supervised singletons: one long-lived process per
//! per-user machine. The manifest intentionally has **no `cardinality` field**.
//! subc routes by module kind plus channel, while any finer demultiplexing
//! (for example, AFT's per-project actor map) remains internal to the singleton
//! module.

use std::{collections::HashSet, fmt};

use serde::{de::Error as _, Deserialize, Deserializer, Serialize};
use serde_json::Value;

use crate::PROTOCOL_VERSION;

/// A module's full declared participation in the subc mesh.
///
/// Construct via [`ModuleManifest::builder()`], never a struct literal. Adding a
/// field to this struct would break every direct construction site; builder methods
/// are additive, so constructors written against an older revision continue
/// compiling when later fields land.
#[derive(Serialize, Debug, Clone, PartialEq)]
#[non_exhaustive]
pub struct ModuleManifest {
    pub module_id: String,
    pub module_version: String,
    pub protocol_ver: u8,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trust_tier: Option<TrustTier>,
    /// Whether this registered module is ready to receive new route binds.
    ///
    /// Absence means ready, preserving the behavior of manifests emitted before
    /// this field existed. This is a best-effort admission hint, not an invariant:
    /// the daemon reads readiness separately from reserving a relay, so modules
    /// must still tolerate an `on_bind` while not ready.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ready: Option<bool>,
    /// Existing role declarations; capability grammar claims deliberately live in
    /// the separate [`CapabilityDeclarations`] block below.
    pub provides: Vec<ProviderRole>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub consumes: Vec<ConsumerRole>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub bindings: Option<Bindings>,
    /// Optional capability-grammar declarations.
    ///
    /// Omitting this block preserves the manifest contract used before capability
    /// grammar was introduced. A present block is static discovery metadata that
    /// the daemon validates before accepting a HELLO.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub capabilities: Option<CapabilityDeclarations>,
    /// Events published as notices on `ck.{acct}.event.{module_id}.{event}.v{N}`.
    /// The publisher serves the body; declared headers are filter hints, never authority.
    ///
    /// `None` means the module has not declared events. `Some(vec![])` affirmatively
    /// declares that it publishes none. Absence remains absent on the wire.
    ///
    /// Declarations are validated at HELLO and retained in the daemon registry,
    /// but no client can read them yet: `catalog.list`, `server.describe` and
    /// `ck catalog` do not return them, because subc-control's `CatalogEntry`
    /// has no field for them and adding one is a breaking change. A daemon built
    /// before this field existed drops it silently. So a flow engine cannot yet
    /// discover a module's events from the catalog, and a module must not depend
    /// on that discovery until a daemon that serves declarations is running.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub events: Option<Vec<EventDeclaration>>,
    /// Periodic or event-driven behavior this module performs against an external
    /// surface, so later analysts can account for the resulting self-shaped time
    /// series.
    ///
    /// Declarations describe the EFFECTIVE values in force at HELLO time. In
    /// particular, a compile-time cadence constant belongs in
    /// [`SignalCadence::Literal`], while a cadence resolved from configuration
    /// belongs in [`SignalCadence::Derived`] with a pointer to that effective
    /// source. Both provenance stories are honest; copying a stale configured
    /// value into a literal is not.
    ///
    /// Ephemeral signals are out of scope for v1 because they are not durably
    /// declarable, not because they are harmless. A v2 reader must not interpret
    /// this field's absence in a v1 manifest as a judgement about ephemerals.
    ///
    /// `None` and `Some(vec![])` are deliberately distinct on the wire: an
    /// absent block means the module has not adopted this vocabulary (readers
    /// treat it as zero signals but must not treat it as a survey answer),
    /// while an empty list is an affirmative declaration that the module
    /// examined its effects and claims none are declarable. Modules that mean
    /// "no signals" should declare the empty list; `None` is what an
    /// un-adopted manifest looks like, not a statement.
    ///
    /// Convention for mutate-effect entries: where the mutation leaves a
    /// per-observation tell on the surface itself (insula publishes the
    /// relaxed `usedPercent` beside the raw figure, so any single reading
    /// self-reports whether it was touched), name that tell in the
    /// declaration's note. A standing registry row says the module sometimes
    /// mutates; the tell says whether THIS observation was mutated — a
    /// consumer holding one sample can act on the second, not the first.
    /// A named tell must exist on the wire independently of this registry:
    /// the declaration points at evidence, it is never the evidence. A tell
    /// that exists only because the manifest describes it is a claim
    /// vouching for itself.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub self_signals: Option<Vec<SelfSignalDeclaration>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub provenance: Option<ManifestProvenance>,
}

/// Incrementally constructs a [`ModuleManifest`] without fabricating absent facts.
#[derive(Debug, Clone)]
pub struct ModuleManifestBuilder {
    module_id: String,
    module_version: String,
    protocol_ver: u8,
    trust_tier: Option<TrustTier>,
    ready: Option<bool>,
    provides: Vec<ProviderRole>,
    consumes: Vec<ConsumerRole>,
    bindings: Option<Bindings>,
    capabilities: Option<CapabilityDeclarations>,
    events: Option<Vec<EventDeclaration>>,
    self_signals: Option<Vec<SelfSignalDeclaration>>,
    provenance: Option<ManifestProvenance>,
}

impl ModuleManifest {
    /// Starts a manifest builder with the minimal identification fields.
    ///
    /// `protocol_ver` defaults to the protocol version linked into this crate;
    /// `provides` and `consumes` default to empty declarations. `trust_tier`
    /// and `bindings` default to `None` because the daemon reads neither on any
    /// production path; a required unread field forces producers to invent
    /// fabricated values.
    pub fn builder(
        module_id: impl Into<String>,
        module_version: impl Into<String>,
    ) -> ModuleManifestBuilder {
        ModuleManifestBuilder {
            module_id: module_id.into(),
            module_version: module_version.into(),
            protocol_ver: PROTOCOL_VERSION,
            trust_tier: None,
            ready: None,
            provides: Vec::new(),
            consumes: Vec::new(),
            bindings: None,
            capabilities: None,
            events: None,
            self_signals: None,
            provenance: None,
        }
    }
}

impl ModuleManifestBuilder {
    /// Overrides the linked protocol version for compatibility fixtures.
    pub fn protocol_ver(mut self, protocol_ver: u8) -> Self {
        self.protocol_ver = protocol_ver;
        self
    }

    /// Declares the optional trust tier of this module.
    ///
    /// The daemon does not evaluate this field on any production path.
    pub fn trust_tier(mut self, trust_tier: Option<TrustTier>) -> Self {
        self.trust_tier = trust_tier;
        self
    }

    /// Declares whether the module is ready to receive new route binds.
    pub fn ready(mut self, ready: bool) -> Self {
        self.ready = Some(ready);
        self
    }

    /// Declares the provider roles this module exposes.
    pub fn provides(mut self, provides: Vec<ProviderRole>) -> Self {
        self.provides = provides;
        self
    }

    /// Declares the consumer roles this module requests.
    pub fn consumes(mut self, consumes: Vec<ConsumerRole>) -> Self {
        self.consumes = consumes;
        self
    }

    /// Declares the optional resource and subsystem bindings of this module.
    ///
    /// The daemon does not evaluate this field on any production path.
    pub fn bindings(mut self, bindings: Option<Bindings>) -> Self {
        self.bindings = bindings;
        self
    }

    /// Adds optional capability-grammar declarations.
    pub fn capabilities(mut self, capabilities: Option<CapabilityDeclarations>) -> Self {
        self.capabilities = capabilities;
        self
    }

    /// Adds optional bus event declarations; an empty list declares no events.
    pub fn events(mut self, events: Option<Vec<EventDeclaration>>) -> Self {
        self.events = events;
        self
    }

    /// Adds optional periodic or event-driven behavior declarations.
    pub fn self_signals(mut self, self_signals: Option<Vec<SelfSignalDeclaration>>) -> Self {
        self.self_signals = self_signals;
        self
    }

    /// Adds optional build provenance declared by the module.
    pub fn provenance(mut self, provenance: Option<ManifestProvenance>) -> Self {
        self.provenance = provenance;
        self
    }

    /// Finishes the manifest.
    pub fn build(self) -> ModuleManifest {
        ModuleManifest {
            module_id: self.module_id,
            module_version: self.module_version,
            protocol_ver: self.protocol_ver,
            trust_tier: self.trust_tier,
            ready: self.ready,
            provides: self.provides,
            consumes: self.consumes,
            bindings: self.bindings,
            capabilities: self.capabilities,
            events: self.events,
            self_signals: self.self_signals,
            provenance: self.provenance,
        }
    }
}

/// DELIBERATELY LENIENT: unknown top-level manifest keys are DROPPED at this
/// parse boundary, not rejected and not retained. This is forward
/// compatibility across version skew — a module built against a newer
/// subc-protocol must still HELLO into an older daemon, and strictness here
/// would turn every additive manifest field into a daemon-first flag day.
/// The costs, so nobody re-derives them the hard way (CEREB found both):
/// - A key you add module-side is INVISIBLE to the daemon until a typed field
///   lands here. Producing it is honest; assuming a daemon-side reader exists
///   is not. Say who the audience is next to any such producer.
/// - There is deliberately NO untyped extension bag on this struct: a
///   retained-verbatim Value map becomes an unversioned de-facto wire
///   contract nobody authored (the drift class module-owned payload crates
///   exist to prevent). When a daemon consumer materializes for a fact, the
///   fact gets a typed optional field with a CONSUMER-IMPACT commit instead.
///
/// `CapabilityDeclarations` below is strict by contrast because claims are
/// routed on: an unparseable claim must refuse loudly, never partially apply.
#[derive(Deserialize)]
struct ModuleManifestWire {
    module_id: String,
    module_version: String,
    protocol_ver: u8,
    #[serde(default)]
    trust_tier: Option<TrustTier>,
    #[serde(default)]
    ready: Option<bool>,
    provides: Vec<ProviderRole>,
    #[serde(default)]
    consumes: Vec<ConsumerRole>,
    #[serde(default)]
    bindings: Option<Bindings>,
    #[serde(default)]
    capabilities: Option<CapabilityDeclarations>,
    #[serde(default)]
    events: Option<Value>,
    #[serde(default)]
    self_signals: Option<Vec<SelfSignalDeclaration>>,
    #[serde(default)]
    provenance: Option<ManifestProvenance>,
    // `runtime_computed` belongs to --manifest output rather than the retained
    // manifest model. Deserialize it only long enough to enforce that capability
    // declarations cannot be omitted as runtime-varying data.
    #[serde(default)]
    runtime_computed: Option<Value>,
}

impl<'de> Deserialize<'de> for ModuleManifest {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let wire = ModuleManifestWire::deserialize(deserializer)?;
        validate_runtime_computed(wire.runtime_computed.as_ref(), "runtime_computed")
            .map_err(D::Error::custom)?;
        validate_events_value(wire.events.as_ref()).map_err(D::Error::custom)?;
        let events = wire
            .events
            .map(serde_json::from_value)
            .transpose()
            .map_err(D::Error::custom)?;
        let mut builder = Self::builder(wire.module_id, wire.module_version)
            .protocol_ver(wire.protocol_ver)
            .trust_tier(wire.trust_tier);
        if let Some(ready) = wire.ready {
            builder = builder.ready(ready);
        }
        let manifest = builder
            .provides(wire.provides)
            .consumes(wire.consumes)
            .bindings(wire.bindings)
            .capabilities(wire.capabilities)
            .events(events)
            .self_signals(wire.self_signals)
            .provenance(wire.provenance)
            .build();
        manifest
            .validate_capability_grammar()
            .map_err(D::Error::custom)?;
        Ok(manifest)
    }
}

/// The `server.describe` capability a daemon advertises when `catalog.list`
/// carries each module's declared `events`. Without it, an entry with no
/// `events` cannot tell "this module declares none" from "this daemon never
/// reports them", so a consumer that acts on declared events checks for this
/// first.
pub const CAP_CATALOG_EVENTS_V1: &str = "catalog-events/v1";

/// A daemon advertising this capability stores scope `bind_proof_sha256` hashes
/// and enforces `bind_proof` on scoped route opens. A scope owner should set the
/// hash only when the daemon it is connected to advertises this capability.
pub const CAP_SCOPE_BIND_PROOF_V1: &str = "scope-bind-proof/v1";

/// Atomic idle-only scope rotation and connection-held scope presence.
pub const CAP_SCOPE_REPLACE_IF_IDLE_V1: &str = "scope-replace-if-idle/v1";

/// A versioned bus event notice whose body is served by the publisher.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct EventDeclaration {
    /// One NATS subject token: `[a-z0-9][a-z0-9_]{0,62}`.
    ///
    /// This is the event token rule in `cortexkit-bus-naming` 0.2.0,
    /// [`token.rs`, lines 91–143](https://docs.rs/cortexkit-bus-naming/0.2.0/src/cortexkit_bus_naming/token.rs.html#91-143).
    pub name: String,
    /// Event schema version, at least 1.
    pub version: u32,
    /// Header names every notice carries, for filtering only, never authority.
    /// Names match `[a-z][a-z0-9_]{0,31}` and are unique within the declaration.
    pub headers: Vec<String>,
    /// Short human line for consent cards, at most 200 characters without controls.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub summary: Option<String>,
}

impl EventDeclaration {
    /// Starts an event declaration with no filter headers or summary.
    /// Validation happens when decoding a manifest or admitting its HELLO.
    pub fn new(name: impl Into<String>, version: u32) -> Self {
        Self {
            name: name.into(),
            version,
            headers: Vec::new(),
            summary: None,
        }
    }

    /// Sets the header names carried by every notice of this event.
    pub fn with_headers(mut self, headers: Vec<String>) -> Self {
        self.headers = headers;
        self
    }

    /// Sets or removes the short human summary.
    pub fn with_summary(mut self, summary: Option<String>) -> Self {
        self.summary = summary;
        self
    }
}

/// A safe-to-report event declaration failure, without echoing untrusted values.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct EventDeclarationError {
    field: String,
    reason: &'static str,
}

impl EventDeclarationError {
    fn new(field: impl Into<String>, reason: &'static str) -> Self {
        Self {
            field: field.into(),
            reason,
        }
    }

    /// The precise malformed field path, relative to the manifest.
    pub fn field(&self) -> &str {
        &self.field
    }
}

impl fmt::Display for EventDeclarationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid event declaration: field {} {}",
            self.field, self.reason
        )
    }
}

impl std::error::Error for EventDeclarationError {}

/// Validates event declarations before HELLO decoding can lose field context.
pub fn validate_hello_event_declarations(hello: &Value) -> Result<(), EventDeclarationError> {
    validate_events_value(
        hello
            .get("manifest")
            .and_then(|manifest| manifest.get("events")),
    )
}

fn is_valid_event_name(name: &str) -> bool {
    (1..=63).contains(&name.len())
        && name.as_bytes()[0].is_ascii_alphanumeric()
        && name
            .bytes()
            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_')
}

fn validate_events_value(value: Option<&Value>) -> Result<(), EventDeclarationError> {
    let Some(value) = value.filter(|value| !value.is_null()) else {
        return Ok(());
    };
    let entries = value
        .as_array()
        .ok_or_else(|| EventDeclarationError::new("events", "must be a list"))?;
    if entries.len() > 64 {
        return Err(EventDeclarationError::new(
            "events",
            "must contain at most 64 declarations",
        ));
    }
    let mut pairs = HashSet::new();
    for (index, entry) in entries.iter().enumerate() {
        let field = format!("events[{index}]");
        let entry = entry
            .as_object()
            .ok_or_else(|| EventDeclarationError::new(&field, "must be an object"))?;
        let name_field = format!("{field}.name");
        let name = entry
            .get("name")
            .and_then(Value::as_str)
            .ok_or_else(|| EventDeclarationError::new(&name_field, "must be a string"))?;
        if !is_valid_event_name(name) {
            return Err(EventDeclarationError::new(
                name_field,
                "must match [a-z0-9][a-z0-9_]{0,62}",
            ));
        }
        let version = entry
            .get("version")
            .and_then(Value::as_u64)
            .filter(|version| (1..=u32::MAX as u64).contains(version))
            .ok_or_else(|| {
                EventDeclarationError::new(
                    format!("{field}.version"),
                    "must be an integer between 1 and u32::MAX",
                )
            })?;
        if !pairs.insert((name, version)) {
            return Err(EventDeclarationError::new(
                &field,
                "duplicates an event (name, version) pair",
            ));
        }
        let headers_field = format!("{field}.headers");
        let headers = entry
            .get("headers")
            .and_then(Value::as_array)
            .ok_or_else(|| EventDeclarationError::new(&headers_field, "must be a list"))?;
        if headers.len() > 16 {
            return Err(EventDeclarationError::new(
                headers_field,
                "must contain at most 16 headers",
            ));
        }
        let mut names = HashSet::new();
        for (header_index, header) in headers.iter().enumerate() {
            let header_field = format!("{headers_field}[{header_index}]");
            let header = header
                .as_str()
                .ok_or_else(|| EventDeclarationError::new(&header_field, "must be a string"))?;
            if !(1..=32).contains(&header.len())
                || !header.as_bytes()[0].is_ascii_lowercase()
                || !header
                    .bytes()
                    .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_')
            {
                return Err(EventDeclarationError::new(
                    header_field,
                    "must match [a-z][a-z0-9_]{0,31}",
                ));
            }
            if !names.insert(header) {
                return Err(EventDeclarationError::new(
                    header_field,
                    "duplicates a header name",
                ));
            }
        }
        if let Some(summary) = entry.get("summary").filter(|value| !value.is_null()) {
            let summary_field = format!("{field}.summary");
            let summary = summary
                .as_str()
                .ok_or_else(|| EventDeclarationError::new(&summary_field, "must be a string"))?;
            if summary.chars().count() > 200 || summary.chars().any(char::is_control) {
                return Err(EventDeclarationError::new(
                    summary_field,
                    "must contain at most 200 characters and no control characters",
                ));
            }
        }
    }
    Ok(())
}

/// A raw HELLO declaration error that can be reported before serde drops context.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SelfSignalDeclarationError {
    module_id: String,
    entry_index: usize,
    field: &'static str,
}

impl fmt::Display for SelfSignalDeclarationError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "module_id '{}' self_signals[{}] is missing required field '{}'",
            self.module_id.escape_debug(),
            self.entry_index,
            self.field
        )
    }
}

/// Reject raw HELLO self-signal declarations that omit `effect` or `anchored_to`.
///
/// Serde correctly rejects these omissions while decoding [`ModuleManifest`], but
/// that decode does not retain the module id or list index needed for a useful
/// daemon refusal. This preflight adds only that reporting context; it does not
/// interpret a declaration's behavior.
pub fn validate_hello_self_signal_declarations(
    hello: &Value,
) -> Result<(), SelfSignalDeclarationError> {
    let Some(manifest) = hello.get("manifest").and_then(Value::as_object) else {
        return Ok(());
    };
    let module_id = manifest
        .get("module_id")
        .and_then(Value::as_str)
        .unwrap_or("<unknown>");
    let Some(entries) = manifest.get("self_signals").and_then(Value::as_array) else {
        return Ok(());
    };

    for (entry_index, entry) in entries.iter().enumerate() {
        let Some(entry) = entry.as_object() else {
            continue;
        };
        for field in ["effect", "anchored_to"] {
            if !entry.contains_key(field) {
                return Err(SelfSignalDeclarationError {
                    module_id: module_id.to_string(),
                    entry_index,
                    field,
                });
            }
        }
    }
    Ok(())
}

/// Static, versioned capabilities declared by a module.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct CapabilityDeclarations {
    #[serde(default)]
    pub provides: Vec<String>,
    #[serde(default)]
    pub requires: Vec<CapabilityRequirement>,
    #[serde(default)]
    pub must_never_reach: Vec<String>,
}

/// A declared periodic or event-driven behavior that shapes an external surface.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
pub struct SelfSignalDeclaration {
    /// Stable identifier for this declared behavior, such as `codex_keepalive`.
    pub name: String,
    /// Signal classification. `Busy` participates in drain quiescence; the
    /// remaining kinds are descriptive for operators and analysts.
    ///
    /// # A `Busy` GAUGE COUNTS WORK THE DRAIN CAN AFFECT, AND NOTHING ELSE
    ///
    /// The daemon waits for every declared `Busy` gauge to reach zero before
    /// tearing a module down, up to the drain ceiling. That wait is only worth
    /// anything for work whose RESULT WOULD BE DELIVERED if it finished during
    /// the drain.
    ///
    /// The test: **if this request completed one millisecond before the
    /// teardown, would anyone receive its answer?** If no, it does not belong
    /// in a `Busy` gauge, and counting it makes the daemon wait out its whole
    /// ceiling for something that cannot usefully complete.
    ///
    /// The case that names the rule (CEREB, 2026-09-19): cerebellum's
    /// management requests can park for up to 300 s awaiting a HUMAN's consent
    /// decision. Those were counted as in-flight, so a drain begun while a
    /// prompt was open waited on a person until the 30 s ceiling expired --
    /// and the pending answer dies with the process either way, so the wait
    /// bought nothing. The fix splits the accounting: `executing` counts toward
    /// `Busy`, `awaiting_consent` is reported as its own informational gauge.
    ///
    /// The same shape exists anywhere a request blocks on an external party the
    /// restart invalidates -- a human, a peer seat, a vendor call whose reply
    /// has nowhere to land. Those are legitimately IN FLIGHT and are not
    /// legitimately `Busy`.
    pub kind: SelfSignalKind,
    /// Whether the signal only observes the surface or changes it.
    pub effect: SelfSignalEffect,
    /// The cadence, event, or health gauges that anchor this signal.
    pub anchored_to: SignalAnchor,
    /// The effective cadence in force at HELLO time.
    ///
    /// Use [`SignalCadence::Literal`] when a compile-time constant is the
    /// effective value. Use [`SignalCadence::Derived`] when configuration or
    /// another runtime input resolves the effective value, naming the source so
    /// the declaration cannot silently drift from that resolution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cadence: Option<SignalCadence>,
    /// The external surface this behavior shapes, such as `provider-usage`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub domain: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub note: Option<String>,
}

/// Class of a self-signal, tolerant of newer wire values.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SelfSignalKind {
    Keepalive,
    /// Work that must settle before the daemon considers a module quiescent.
    Busy,
    Poller,
    Cron,
    Sweep,
    Watchdog,
    Heartbeat,
    Other(String),
}

impl SelfSignalKind {
    fn wire_name(&self) -> &str {
        match self {
            Self::Keepalive => "keepalive",
            Self::Busy => "busy",
            Self::Poller => "poller",
            Self::Cron => "cron",
            Self::Sweep => "sweep",
            Self::Watchdog => "watchdog",
            Self::Heartbeat => "heartbeat",
            Self::Other(value) => value,
        }
    }
}

impl Serialize for SelfSignalKind {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.wire_name())
    }
}

impl<'de> Deserialize<'de> for SelfSignalKind {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        Ok(match value.as_str() {
            "keepalive" => Self::Keepalive,
            "busy" => Self::Busy,
            "poller" => Self::Poller,
            "cron" => Self::Cron,
            "sweep" => Self::Sweep,
            "watchdog" => Self::Watchdog,
            "heartbeat" => Self::Heartbeat,
            _ => Self::Other(value),
        })
    }
}

/// The effect a self-signal has on the external surface it targets.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum SelfSignalEffect {
    Observe,
    Mutate,
}

/// What anchors a self-signal to an interval, event, or health state.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SignalAnchor {
    /// The behavior follows its own periodic signature, so analysts can find it
    /// without an external event grid.
    FixedInterval,
    /// The behavior follows an external event boundary, which can make its shape
    /// indistinguishable from the surface mechanism without this declaration.
    Event { event: String },
    /// Health metrics whose non-negative integer values are summed during drain.
    HealthGauges { gauges: Vec<String> },
}

/// How a self-signal's effective cadence is declared.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SignalCadence {
    Literal { interval_ms: u64 },
    Derived { source: String },
}

/// Build facts a module DECLARES about its own binary at HELLO. The daemon
/// overlays process-identity evidence it alone can attest; the two halves are
/// served together via `supervisor.provenance` and never merged.
///
/// The canonical constructor form is a full 40-character lowercase hexadecimal
/// `build_git_sha` and a full 64-character lowercase hexadecimal
/// `build_lock_digest`; abbreviations are not conforming. The daemon's HELLO
/// decoder intentionally remains lenient enough to relay older declarations,
/// so this construction contract is enforced by [`build_provenance`] rather
/// than by wire deserialization.
///
/// Honesty contract for constructors (ruled with the first adopters):
/// - Every field is a VERIFIED-AT-BUILD claim. No field is required: a module
///   may declare any subset, and omitting an inapplicable field is the honest
///   choice rather than inventing a value to fill it. Populate `build_git_sha`
///   only from a value injected by the build/release pipeline (`CK_BUILD_REV`
///   via `option_env!` guarded by the packaging path, or build.rs equivalent)
///   — never from ambient env at an arbitrary consumer compile, which mints a
///   provenance claim from an accident of whoever ran cargo. A builder that
///   can determine whether the tree was clean may declare the sha regardless
///   of whether a release pipeline exists.
/// - Dirty or unstamped builds declare `None` for the affected fields. A
///   populated field stops the reader asking; absent-and-honest beats
///   present-and-best-effort. Absence is reported at two levels with two
///   distinct words: a module that declared no provenance block at all reads
///   `unverifiable`, while an omitted field inside a declared block is
///   dropped from the wire and reads `unavailable`. So omitting a field never
///   costs a module its `Reported` status -- declaration is decided by
///   whether the manifest carried a block, not by which fields it filled.
/// - Dirty-tree stamps are not canonical `build_git_sha` values. A pipeline
///   that emits `-dirty` must omit the affected field rather than pass that
///   stamp to the canonical constructor. Stricter is better: cerebellum's
///   build.rs reports the commit ONLY when the tree was clean, on the argument
///   that dirty bytes match no commit and a precise-looking wrong answer beats
///   absence at being believed.
/// - Two silent-when-wrong checks for any build-rev embedder (CEREB): does
///   the builder know whether the tree was clean, and can its no-git sentinel
///   (source-tarball builds) escape into a field parsed as a sha? Sentinels
///   render as absence, never as a value.
/// - Fill fields FROM THE BUILD only: reading Cargo.lock or the wire crate
///   version inside the manifest constructor describes the source tree
///   sitting beside the running binary, not the binary — the exact claim
///   this struct exists to avoid.
/// - Declare what you KNOW, not blanket-None (WERNI): `store_schema_version`
///   needs no pipeline — any module with a migration list can state its
///   newest migration as fact, and a daemon comparing it against the store's
///   actual version sees a stale-binary mismatch directly. Blanket `None`
///   where a field is knowable wastes the field; blanket-fill where it is
///   not mints a lie. Absence also beats sentinel values (CKCRED): omit the
///   FIELD when BUILD_REV reads a builder sentinel ("unknown", "unavailable",
///   "none", any casing) — publishing the sentinel string as a fact is a
///   well-formed lie shape validation cannot catch. Field omission, not block
///   omission, is the target shape for SDK modules: `wire_crate_version` is a
///   compile-time constant of the linked crate, so a module using the SDK
///   always has at least one honest fact and `build_provenance` reflects that
///   by never returning an absent block. (Block absence remains meaningful on
///   the wire — it reads `unverifiable`, the module made no claim — but it is
///   the shape for non-adopters and proxied manifests, not a target for
///   declarers; see #78.) The hazard in one sentence, for every referent and
///   sentinel case alike: A PRESENT, WELL-FORMED FIELD STOPS THE READER
///   ASKING — a value from the wrong domain and a sentinel from the wrong
///   vocabulary are indistinguishable from a correct value to every check
///   that inspects shape rather than meaning.
/// - PROXIED MANIFESTS STAY None PERMANENTLY (CALLO): a process that
///   forwards another machine's manifest cannot observe that build, and a
///   forwarded provenance claim is indistinguishable on the wire from a
///   verified one — filling it launders an unverifiable assertion. Same
///   reasoning as pinning a re-exported module's trust_tier to Untrusted.
///   Record that at the construction site: injection-wiring sweeps grep for
///   `provenance:` and the obvious action at a re-export site is the wrong
///   one.
///
/// `#[non_exhaustive]`: a new provenance fact must not break the modules that
/// build this block, so construct it with [`ManifestProvenance::new`] and the
/// `with_*` setters (or the `build_provenance*` helpers), never a struct
/// literal.
#[derive(Serialize, Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub struct ManifestProvenance {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub build_git_sha: Option<String>,
    /// Why `build_git_sha` is unavailable. This is absent when the commit is
    /// declared, and remains open so future causes do not make readers reject
    /// the enclosing provenance declaration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub build_git_sha_absence_reason: Option<BuildGitShaAbsenceReason>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub build_lock_digest: Option<String>,
    /// REFERENT: the `subc-protocol` crate version linked into this binary
    /// (`subc_protocol::SUBC_PROTOCOL_CRATE_VERSION`) — the fleet's shared
    /// wire vocabulary, one numbering space for every module. Never a
    /// module's own envelope/payload crate version: that is real information
    /// in a different numbering space, and here it scores as a confident
    /// wrong answer at any census gate. (QTA's rule, learned live: a field
    /// whose entire content is a referent cannot be documented by its
    /// constraints — so the referent is stated here, where readers look.)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wire_crate_version: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub store_schema_version: Option<String>,
    /// Where the running module read its launch nonce from: `fd` (the pipe
    /// the daemon hands over as descriptor 3), `pipe` (the Windows named pipe),
    /// or `env` (the environment
    /// variable kept while modules move to the pipe). Absent means the module
    /// did not say. This is a fact about the running process, not the build.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub launch_nonce_source: Option<LaunchNonceSource>,
}

/// Where a module read its launch nonce from, as reported in
/// [`ManifestProvenance::launch_nonce_source`].
///
/// An open string enum, like [`BuildGitShaAbsenceReason`]: a value this crate
/// does not know decodes as `ForwardCompatibleUnknown` instead of making the
/// whole provenance block, and with it the module's HELLO, fail to decode.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum LaunchNonceSource {
    /// Read from the inherited descriptor the daemon passes.
    Fd,
    /// Read from the PID-authenticated Windows named pipe.
    Pipe,
    /// Read from the `SUBC_LAUNCH_NONCE` environment variable.
    Env,
    ForwardCompatibleUnknown(String),
}

impl LaunchNonceSource {
    /// The value as it appears on the wire.
    pub fn wire_name(&self) -> &str {
        match self {
            Self::Fd => "fd",
            Self::Pipe => "pipe",
            Self::Env => "env",
            Self::ForwardCompatibleUnknown(value) => value,
        }
    }

    /// The source a wire value names; unknown values are kept as they are.
    pub fn from_wire_name(value: &str) -> Self {
        match value {
            "fd" => Self::Fd,
            "pipe" => Self::Pipe,
            "env" => Self::Env,
            _ => Self::ForwardCompatibleUnknown(value.to_string()),
        }
    }
}

impl Serialize for LaunchNonceSource {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.wire_name())
    }
}

impl<'de> Deserialize<'de> for LaunchNonceSource {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        Ok(Self::from_wire_name(&value))
    }
}

/// A build pipeline's reason for omitting `build_git_sha`.
///
/// This is an open string enum: consumers preserve a future reason instead of
/// rejecting the enclosing provenance declaration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BuildGitShaAbsenceReason {
    DeclinedDirty,
    NeverDerived,
    NoGitDir,
    ForwardCompatibleUnknown(String),
}

impl BuildGitShaAbsenceReason {
    fn wire_name(&self) -> &str {
        match self {
            Self::DeclinedDirty => "declined_dirty",
            Self::NeverDerived => "never_derived",
            Self::NoGitDir => "no_git_dir",
            Self::ForwardCompatibleUnknown(value) => value,
        }
    }
}

impl Serialize for BuildGitShaAbsenceReason {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.wire_name())
    }
}

impl<'de> Deserialize<'de> for BuildGitShaAbsenceReason {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let value = String::deserialize(deserializer)?;
        Ok(match value.as_str() {
            "declined_dirty" => Self::DeclinedDirty,
            "never_derived" => Self::NeverDerived,
            "no_git_dir" => Self::NoGitDir,
            _ => Self::ForwardCompatibleUnknown(value),
        })
    }
}

/// The observable state of a git worktree when a build pipeline found a revision.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum GitTreeState {
    Clean,
    Dirty,
}

/// How the build pipeline obtained (or did not obtain) git revision data.
///
/// `NoGitDir` and `NeverDerived` carry no revision, so callers cannot attach
/// those absence causes to an otherwise attested commit through this API.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BuildGitShaSource<'a> {
    Git {
        revision: &'a str,
        tree_state: GitTreeState,
    },
    NeverDerived,
    NoGitDir,
}

/// Return a commit only when its source tree was clean at build time.
///
/// The rule is pure so stampers can exercise both branches without rebuilding.
pub fn attestable_commit(revision: &str, tree_state: GitTreeState) -> Option<&str> {
    match tree_state {
        GitTreeState::Clean => Some(revision),
        GitTreeState::Dirty => None,
    }
}

const MAX_PROVENANCE_VALUE_BYTES: usize = 128;
const BUILD_GIT_SHA_CANONICAL_FORM: &str = "exactly 40 lowercase hexadecimal characters";
const BUILD_LOCK_DIGEST_CANONICAL_FORM: &str = "exactly 64 lowercase hexadecimal characters";

#[derive(Deserialize)]
struct ManifestProvenanceWire {
    #[serde(default)]
    build_git_sha: Option<String>,
    #[serde(default)]
    build_git_sha_absence_reason: Option<BuildGitShaAbsenceReason>,
    #[serde(default)]
    build_lock_digest: Option<String>,
    #[serde(default)]
    wire_crate_version: Option<String>,
    #[serde(default)]
    store_schema_version: Option<String>,
    #[serde(default)]
    launch_nonce_source: Option<LaunchNonceSource>,
}

impl<'de> Deserialize<'de> for ManifestProvenance {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let wire = ManifestProvenanceWire::deserialize(deserializer)?;
        let provenance = Self {
            build_git_sha: wire.build_git_sha,
            build_git_sha_absence_reason: wire.build_git_sha_absence_reason,
            build_lock_digest: wire.build_lock_digest,
            wire_crate_version: wire.wire_crate_version,
            store_schema_version: wire.store_schema_version,
            launch_nonce_source: wire.launch_nonce_source,
        };
        provenance.validate().map_err(D::Error::custom)?;
        Ok(provenance)
    }
}

/// A declared build fact did not use its canonical form.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProvenanceFormError {
    field: &'static str,
    length: usize,
    canonical_form: &'static str,
}

impl ProvenanceFormError {
    fn new(field: &'static str, length: usize, canonical_form: &'static str) -> Self {
        Self {
            field,
            length,
            canonical_form,
        }
    }

    /// The provenance field whose value was not canonical.
    pub fn field(&self) -> &str {
        self.field
    }

    /// The offending value's length in bytes.
    pub fn length(&self) -> usize {
        self.length
    }

    /// The canonical form required for this field.
    pub fn canonical_form(&self) -> &str {
        self.canonical_form
    }
}

impl fmt::Display for ProvenanceFormError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid manifest provenance form: field {} has length {}; canonical form is {}",
            self.field, self.length, self.canonical_form
        )
    }
}

impl std::error::Error for ProvenanceFormError {}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ManifestProvenanceError {
    field: String,
    value: String,
    reason: &'static str,
}

impl ManifestProvenanceError {
    fn new(field: &str, value: &str, reason: &'static str) -> Self {
        Self {
            field: field.to_string(),
            value: safe_error_value(value),
            reason,
        }
    }

    pub fn field(&self) -> &str {
        &self.field
    }
}

impl fmt::Display for ManifestProvenanceError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid manifest provenance: field {} has {} (value {:?})",
            self.field, self.reason, self.value
        )
    }
}

impl std::error::Error for ManifestProvenanceError {}

impl ManifestProvenance {
    /// A block declaring nothing; add facts with the `with_*` setters.
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_build_git_sha(mut self, value: Option<String>) -> Self {
        self.build_git_sha = value;
        self
    }

    pub fn with_build_git_sha_absence_reason(
        mut self,
        value: Option<BuildGitShaAbsenceReason>,
    ) -> Self {
        self.build_git_sha_absence_reason = value;
        self
    }

    pub fn with_build_lock_digest(mut self, value: Option<String>) -> Self {
        self.build_lock_digest = value;
        self
    }

    pub fn with_wire_crate_version(mut self, value: Option<String>) -> Self {
        self.wire_crate_version = value;
        self
    }

    pub fn with_store_schema_version(mut self, value: Option<String>) -> Self {
        self.store_schema_version = value;
        self
    }

    /// Report where this process read its launch nonce from. A module takes
    /// it from its nonce accessor's cached source, so whoever reads the fleet's
    /// provenance (`ck provenance`) can tell a module reading the pipe from
    /// one still reading the environment variable.
    pub fn with_launch_nonce_source(mut self, value: Option<LaunchNonceSource>) -> Self {
        self.launch_nonce_source = value;
        self
    }

    pub fn validate(&self) -> Result<(), ManifestProvenanceError> {
        if let (Some(_), Some(reason)) = (
            self.build_git_sha.as_ref(),
            self.build_git_sha_absence_reason.as_ref(),
        ) {
            return Err(ManifestProvenanceError::new(
                "build_git_sha_absence_reason",
                reason.wire_name(),
                "must be omitted when build_git_sha is present",
            ));
        }
        for (field, value) in [
            ("build_git_sha", self.build_git_sha.as_deref()),
            (
                "build_git_sha_absence_reason",
                self.build_git_sha_absence_reason
                    .as_ref()
                    .map(|reason| reason.wire_name()),
            ),
            ("build_lock_digest", self.build_lock_digest.as_deref()),
            ("wire_crate_version", self.wire_crate_version.as_deref()),
            ("store_schema_version", self.store_schema_version.as_deref()),
            (
                "launch_nonce_source",
                self.launch_nonce_source
                    .as_ref()
                    .map(|source| source.wire_name()),
            ),
        ] {
            let Some(value) = value else { continue };
            if value.is_empty() {
                return Err(ManifestProvenanceError::new(
                    field,
                    value,
                    "must not be empty",
                ));
            }
            // HELLO decoding checks only wire safety here. Canonical build forms
            // belong to build_provenance; the daemon is a non-adjudicating relayer
            // and must continue accepting legacy declarations such as 12-hex
            // module revisions rather than breaking a fleet on daemon upgrade.
            if value.len() > MAX_PROVENANCE_VALUE_BYTES {
                return Err(ManifestProvenanceError::new(
                    field,
                    value,
                    "exceeds the 128-byte maximum",
                ));
            }
            if value.bytes().any(|byte| !(0x20..=0x7e).contains(&byte)) {
                return Err(ManifestProvenanceError::new(
                    field,
                    value,
                    "contains non-printable ASCII",
                ));
            }
        }
        Ok(())
    }
}

/// Build [`ManifestProvenance`] from legacy raw build facts.
///
/// Callers of this compatibility path did not supply the tree state that
/// explains an omitted SHA. It emits no absence reason not because the absence
/// has no cause, but because guessing one without that state would fabricate
/// the fact this API exists to report honestly.
///
/// ```
/// use subc_protocol::manifest::build_provenance;
///
/// let provenance = build_provenance(option_env!("CK_BUILD_REV"), None, None)
///     .expect("legacy build facts remain supported");
/// assert!(provenance.build_git_sha_absence_reason.is_none());
/// ```
///
/// Sentinel and empty values become field omission before canonical form
/// validation, preserving the established three-argument wire behavior.
pub fn build_provenance(
    build_git_sha: Option<&str>,
    build_lock_digest: Option<&str>,
    store_schema_version: Option<&str>,
) -> Result<ManifestProvenance, ProvenanceFormError> {
    let build_git_sha = normalize_and_validate_build_git_sha(build_git_sha)?;
    build_provenance_with_build_git_sha(
        build_git_sha,
        None,
        build_lock_digest,
        store_schema_version,
    )
}

/// Build a [`ManifestProvenance`] from source-state-aware build facts.
///
/// The source state makes the SHA absence cause attestable: `Dirty` declines
/// the commit, while `NeverDerived` and `NoGitDir` name distinct source paths.
/// A `build_git_sha` must be exactly 40 lowercase hexadecimal characters and a
/// `build_lock_digest` exactly 64 lowercase hexadecimal characters. Abbreviations
/// are not conforming; a real value in the wrong form returns a
/// [`ProvenanceFormError`] instead of being discarded as if it were absent.
/// Sentinel values are filtered before form validation, so they remain honest
/// omission rather than becoming form errors.
///
/// OWNERSHIP RULE: a helper that constructs a wire type lives in the crate
/// that owns the type. This helper constructs `ManifestProvenance`, so it
/// lives here in subc-protocol (not in subc-client-rs) — transport-direct
/// modules that never link the client SDK can still build honest provenance.
pub fn build_provenance_from_source(
    build_git_sha_source: BuildGitShaSource<'_>,
    build_lock_digest: Option<&str>,
    store_schema_version: Option<&str>,
) -> Result<ManifestProvenance, ProvenanceFormError> {
    let (raw_build_git_sha, mut build_git_sha_absence_reason) = match build_git_sha_source {
        BuildGitShaSource::Git {
            revision,
            tree_state,
        } => match attestable_commit(revision, tree_state) {
            Some(revision) => (Some(revision), None),
            None => (None, Some(BuildGitShaAbsenceReason::DeclinedDirty)),
        },
        BuildGitShaSource::NeverDerived => (None, Some(BuildGitShaAbsenceReason::NeverDerived)),
        BuildGitShaSource::NoGitDir => (None, Some(BuildGitShaAbsenceReason::NoGitDir)),
    };
    let build_git_sha = normalize_and_validate_build_git_sha(raw_build_git_sha)?;
    if build_git_sha.is_none() {
        build_git_sha_absence_reason.get_or_insert(BuildGitShaAbsenceReason::NeverDerived);
    }
    build_provenance_with_build_git_sha(
        build_git_sha,
        build_git_sha_absence_reason,
        build_lock_digest,
        store_schema_version,
    )
}

fn normalize_and_validate_build_git_sha(
    build_git_sha: Option<&str>,
) -> Result<Option<String>, ProvenanceFormError> {
    let build_git_sha = normalize_provenance_fact(build_git_sha);
    validate_provenance_form(
        "build_git_sha",
        build_git_sha.as_deref(),
        BUILD_GIT_SHA_CANONICAL_FORM,
        40,
    )?;
    Ok(build_git_sha)
}

fn build_provenance_with_build_git_sha(
    build_git_sha: Option<String>,
    build_git_sha_absence_reason: Option<BuildGitShaAbsenceReason>,
    build_lock_digest: Option<&str>,
    store_schema_version: Option<&str>,
) -> Result<ManifestProvenance, ProvenanceFormError> {
    let build_lock_digest = normalize_provenance_fact(build_lock_digest);
    validate_provenance_form(
        "build_lock_digest",
        build_lock_digest.as_deref(),
        BUILD_LOCK_DIGEST_CANONICAL_FORM,
        64,
    )?;

    Ok(ManifestProvenance {
        build_git_sha,
        build_git_sha_absence_reason,
        build_lock_digest,
        wire_crate_version: Some(crate::SUBC_PROTOCOL_CRATE_VERSION.to_string()),
        store_schema_version: normalize_provenance_fact(store_schema_version),
        launch_nonce_source: None,
    })
}

fn validate_provenance_form(
    field: &'static str,
    value: Option<&str>,
    canonical_form: &'static str,
    expected_length: usize,
) -> Result<(), ProvenanceFormError> {
    let Some(value) = value else { return Ok(()) };
    if value.len() != expected_length
        || !value
            .bytes()
            .all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'))
    {
        return Err(ProvenanceFormError::new(field, value.len(), canonical_form));
    }
    Ok(())
}

/// Sentinel strings that build tooling emits where it means "no value": shell
/// fallbacks and Makefile defaults produce `unknown`, wire vocabulary uses
/// `unavailable`, and `git describe` failures surface as `none`. Publishing
/// any of them as a fact is the well-formed-lie shape the provenance contract
/// warns against — a present, well-formed field stops the reader asking — so
/// the helper maps them all to field omission. Matched case-insensitively
/// because `UNKNOWN`/`Unknown` are equally common from shell fallbacks.
pub const PROVENANCE_SENTINELS: [&str; 3] = ["unknown", "unavailable", "none"];

fn normalize_provenance_fact(value: Option<&str>) -> Option<String> {
    let value = value?.trim();
    if value.is_empty() {
        return None;
    }
    let lowered = value.to_ascii_lowercase();
    if PROVENANCE_SENTINELS.contains(&lowered.as_str()) {
        return None;
    }
    Some(value.to_string())
}

/// One capability a module consumes and whether its absence is tolerated.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct CapabilityRequirement {
    pub capability: String,
    pub need: CapabilityNeed,
}

/// Closed capability requirement strength vocabulary.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CapabilityNeed {
    Required,
    Optional,
}

/// A safe-to-report capability-schema validation failure.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapabilityGrammarError {
    field: String,
    value: String,
}

impl CapabilityGrammarError {
    fn new(field: impl Into<String>, value: impl AsRef<str>) -> Self {
        Self {
            field: field.into(),
            value: safe_error_value(value.as_ref()),
        }
    }

    /// The precise malformed field path.
    pub fn field(&self) -> &str {
        &self.field
    }

    /// The offending value, redacted when it resembles a credential.
    pub fn value(&self) -> &str {
        &self.value
    }
}

impl fmt::Display for CapabilityGrammarError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "invalid capability grammar: field {} has offending value {:?}",
            self.field, self.value
        )
    }
}

impl std::error::Error for CapabilityGrammarError {}

impl ModuleManifest {
    /// Validate the typed capability block after serde has decoded it.
    pub fn validate_capability_grammar(&self) -> Result<(), CapabilityGrammarError> {
        let Some(capabilities) = &self.capabilities else {
            return Ok(());
        };

        validate_capability_list("capabilities.provides", &capabilities.provides)?;
        validate_requires(&capabilities.requires)?;
        validate_capability_list(
            "capabilities.must_never_reach",
            &capabilities.must_never_reach,
        )
    }
}

/// Validate capability grammar in a standalone manifest JSON value.
///
/// The raw-value form lets HELLO distinguish schema failures from malformed JSON,
/// including an unknown `need` that cannot be represented by [`CapabilityNeed`].
pub fn validate_manifest_capability_grammar(
    manifest: &Value,
) -> Result<(), CapabilityGrammarError> {
    let Some(object) = manifest.as_object() else {
        return Ok(());
    };

    validate_capabilities_value(object.get("capabilities"))?;
    validate_runtime_computed(object.get("runtime_computed"), "runtime_computed")
}

/// Validate capability grammar in a raw HELLO body.
///
/// `runtime_computed` is a top-level sibling in --manifest output. HELLO keeps
/// accepting that sibling only so an attempted dynamic capability declaration is
/// refused explicitly instead of being silently ignored by serde.
pub fn validate_hello_capability_grammar(hello: &Value) -> Result<(), CapabilityGrammarError> {
    let Some(object) = hello.as_object() else {
        return Ok(());
    };
    if let Some(manifest) = object.get("manifest") {
        validate_manifest_capability_grammar(manifest)?;
    }
    validate_runtime_computed(object.get("runtime_computed"), "runtime_computed")
}

/// Return whether `identifier` has the exact `<name>/v<N>` capability spelling.
pub fn is_valid_capability_identifier(identifier: &str) -> bool {
    if identifier.chars().any(char::is_whitespace) {
        return false;
    }
    let Some((name, version)) = identifier.split_once("/v") else {
        return false;
    };
    if name.is_empty() || name.len() > 64 || version.is_empty() {
        return false;
    }

    let name_bytes = name.as_bytes();
    if !name_bytes[0].is_ascii_lowercase()
        || (name.len() > 1
            && !name_bytes[name.len() - 1].is_ascii_lowercase()
            && !name_bytes[name.len() - 1].is_ascii_digit())
        || name_bytes.windows(2).any(|pair| pair == b"--")
    {
        return false;
    }
    if !name_bytes
        .iter()
        .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || *byte == b'-')
    {
        return false;
    }

    if version.len() > 1 && version.starts_with('0')
        || !version.bytes().all(|byte| byte.is_ascii_digit())
    {
        return false;
    }
    matches!(
        version.parse::<u64>(),
        Ok(value) if (1..=u64::from(u32::MAX)).contains(&value)
    )
}

fn validate_capabilities_value(value: Option<&Value>) -> Result<(), CapabilityGrammarError> {
    let Some(value) = value else {
        return Ok(());
    };
    let Some(object) = value.as_object() else {
        return Err(CapabilityGrammarError::new(
            "capabilities",
            value_description(value),
        ));
    };

    for (key, value) in object {
        if !matches!(key.as_str(), "provides" | "requires" | "must_never_reach") {
            return Err(CapabilityGrammarError::new(
                field_child("capabilities", key),
                value_description(value),
            ));
        }
    }

    validate_capability_list_value("capabilities.provides", object.get("provides"))?;
    validate_requires_value(object.get("requires"))?;
    validate_capability_list_value(
        "capabilities.must_never_reach",
        object.get("must_never_reach"),
    )
}

fn validate_capability_list_value(
    field: &str,
    value: Option<&Value>,
) -> Result<(), CapabilityGrammarError> {
    let Some(value) = value else {
        return Ok(());
    };
    let Some(values) = value.as_array() else {
        return Err(CapabilityGrammarError::new(field, value_description(value)));
    };

    let mut seen = HashSet::new();
    for (index, value) in values.iter().enumerate() {
        let field = format!("{field}[{index}]");
        let Some(identifier) = value.as_str() else {
            return Err(CapabilityGrammarError::new(field, value_description(value)));
        };
        validate_capability_identifier(&field, identifier)?;
        if !seen.insert(identifier) {
            return Err(CapabilityGrammarError::new(field, identifier));
        }
    }
    Ok(())
}

fn validate_requires_value(value: Option<&Value>) -> Result<(), CapabilityGrammarError> {
    let Some(value) = value else {
        return Ok(());
    };
    let Some(values) = value.as_array() else {
        return Err(CapabilityGrammarError::new(
            "capabilities.requires",
            value_description(value),
        ));
    };

    let mut seen = HashSet::new();
    for (index, value) in values.iter().enumerate() {
        let entry_field = format!("capabilities.requires[{index}]");
        let Some(object) = value.as_object() else {
            return Err(CapabilityGrammarError::new(
                entry_field,
                value_description(value),
            ));
        };
        for (key, value) in object {
            if !matches!(key.as_str(), "capability" | "need") {
                return Err(CapabilityGrammarError::new(
                    field_child(&entry_field, key),
                    value_description(value),
                ));
            }
        }
        let capability_field = format!("{entry_field}.capability");
        let Some(capability) = object.get("capability").and_then(Value::as_str) else {
            return Err(CapabilityGrammarError::new(
                capability_field,
                object
                    .get("capability")
                    .map_or("<missing>".to_string(), value_description),
            ));
        };
        validate_capability_identifier(&capability_field, capability)?;

        let need_field = format!("{entry_field}.need");
        let Some(need) = object.get("need").and_then(Value::as_str) else {
            return Err(CapabilityGrammarError::new(
                need_field,
                object
                    .get("need")
                    .map_or("<missing>".to_string(), value_description),
            ));
        };
        if !matches!(need, "required" | "optional") {
            return Err(CapabilityGrammarError::new(need_field, need));
        }
        if !seen.insert(capability) {
            return Err(CapabilityGrammarError::new(entry_field, capability));
        }
    }
    Ok(())
}

fn validate_capability_list(field: &str, values: &[String]) -> Result<(), CapabilityGrammarError> {
    let mut seen = HashSet::new();
    for (index, identifier) in values.iter().enumerate() {
        let field = format!("{field}[{index}]");
        validate_capability_identifier(&field, identifier)?;
        if !seen.insert(identifier) {
            return Err(CapabilityGrammarError::new(field, identifier));
        }
    }
    Ok(())
}

fn validate_requires(values: &[CapabilityRequirement]) -> Result<(), CapabilityGrammarError> {
    let mut seen = HashSet::new();
    for (index, requirement) in values.iter().enumerate() {
        let field = format!("capabilities.requires[{index}].capability");
        validate_capability_identifier(&field, &requirement.capability)?;
        if !seen.insert(&requirement.capability) {
            return Err(CapabilityGrammarError::new(
                format!("capabilities.requires[{index}]"),
                &requirement.capability,
            ));
        }
    }
    Ok(())
}

fn validate_capability_identifier(
    field: &str,
    identifier: &str,
) -> Result<(), CapabilityGrammarError> {
    if is_valid_capability_identifier(identifier) {
        Ok(())
    } else {
        Err(CapabilityGrammarError::new(field, identifier))
    }
}

fn validate_runtime_computed(
    value: Option<&Value>,
    field: &str,
) -> Result<(), CapabilityGrammarError> {
    let Some(value) = value else {
        return Ok(());
    };
    let Some(pointers) = value.as_array() else {
        return Err(CapabilityGrammarError::new(field, value_description(value)));
    };

    for (index, pointer) in pointers.iter().enumerate() {
        let field = format!("{field}[{index}]");
        let Some(pointer) = pointer.as_str() else {
            return Err(CapabilityGrammarError::new(
                field,
                value_description(pointer),
            ));
        };
        let Some(tokens) = parse_json_pointer(pointer) else {
            return Err(CapabilityGrammarError::new(field, pointer));
        };
        if tokens.first().is_some_and(|token| token == "capabilities") {
            return Err(CapabilityGrammarError::new(field, pointer));
        }
    }
    Ok(())
}

fn parse_json_pointer(pointer: &str) -> Option<Vec<String>> {
    if pointer.is_empty() {
        return Some(Vec::new());
    }
    let raw_tokens = pointer.strip_prefix('/')?;
    raw_tokens
        .split('/')
        .map(unescape_json_pointer_token)
        .collect()
}

fn unescape_json_pointer_token(token: &str) -> Option<String> {
    let mut output = String::with_capacity(token.len());
    let mut characters = token.chars();
    while let Some(character) = characters.next() {
        if character != '~' {
            output.push(character);
            continue;
        }
        match characters.next()? {
            '0' => output.push('~'),
            '1' => output.push('/'),
            _ => return None,
        }
    }
    Some(output)
}

fn field_child(parent: &str, child: &str) -> String {
    let child = safe_error_value(child);
    format!("{parent}.{child}")
}

fn value_description(value: &Value) -> String {
    match value {
        Value::String(value) => safe_error_value(value),
        Value::Null => "null".to_string(),
        Value::Bool(value) => value.to_string(),
        Value::Number(value) => value.to_string(),
        Value::Array(_) => "<array>".to_string(),
        Value::Object(_) => "<object>".to_string(),
    }
}

fn safe_error_value(value: &str) -> String {
    let lower = value.to_ascii_lowercase();
    if ["secret", "password", "api_key"]
        .iter()
        .any(|marker| lower.contains(marker))
        || lower.starts_with("sk-")
        || lower.starts_with("akia")
        || lower.starts_with("bearer ")
        || lower.starts_with("token=")
        || lower.starts_with("credential=")
    {
        "<redacted>".to_string()
    } else {
        value.to_string()
    }
}

/// How this module was sourced, as declared by the module itself.
///
/// Not read on any daemon routing or admission path; relayed verbatim. A
/// module declares it because it describes the module, not because the
/// daemon consumes it, and leaves it absent rather than inventing a value.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum TrustTier {
    FirstParty,
    Reviewed,
    Untrusted,
}

/// Provider capabilities exposed by a module.
///
/// The role set is closed for protocol v1; unknown role tags fail serde decode.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(tag = "role", rename_all = "snake_case")]
pub enum ProviderRole {
    ToolProvider {
        tools: Vec<Tool>,
        /// Which `BindIdentity` keys PARTITION this provider's state or
        /// answers: a module whose reply to a call depends on the caller's
        /// project declares `Project`; one that threads per session declares
        /// `Session`; one that answers identically to every caller declares
        /// `[]`. It states what the module does with the keys it is handed,
        /// not which keys it will accept — every bind carries all of them.
        /// Not read on any daemon path; relayed verbatim for consumers.
        identity_scope: Vec<IdentityScope>,
        concurrency: Concurrency,
        emits_push: bool,
        sub_supervises: bool,
    },
    PipelineStage {
        stage: PipelineStageKind,
        applies_to: PipelineAppliesTo,
        interface: String,
        declares_frozen_floor: bool,
        needs_signals: Vec<String>,
        conformance_class: String,
    },
    ManagementSurface {
        operations: Vec<ManagementOperation>,
        config_schema: Value,
        observability: Vec<ObservabilitySurface>,
        /// Same meaning as on `ToolProvider`: the keys that partition this
        /// surface's state or answers; `[]` for a surface that serves the
        /// same answer to every caller.
        identity_scope: Vec<IdentityScope>,
        #[serde(default)]
        concurrency: Concurrency,
    },
    InternalService {
        service_id: String,
        transport: InternalTransport,
        agent_facing: bool,
        operations: Vec<String>,
    },
}

/// How a tool's side effects are fenced for durable at-most-once handling.
///
/// Classified on a tool's externally-observable effects, never inferred from
/// the module's concurrency lane:
/// - `Pure`: no observable side effect (reads, searches, cache warming) — safe
///   to re-run after an indeterminate outcome.
/// - `Mutating`: a fenceable external side effect such as a file write — a
///   re-run risks a duplicate effect, so an indeterminate outcome must not
///   auto-retry.
/// - `Unfenceable`: a side effect that cannot be fenced or safely replayed,
///   such as running a shell command — never auto-re-run on an indeterminate
///   outcome.
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ExecutionMode {
    Pure,
    Mutating,
    Unfenceable,
}

/// Tool-plane capability exposed by a `tool_provider`.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Tool {
    pub name: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// How the tool's side effects are fenced for durable at-most-once handling.
    /// Observability + durability metadata only; subc's thin core never acts on
    /// this for routing, scheduling, or concurrency — the module's declared
    /// [`Concurrency`] contract governs delivery.
    pub execution_mode: ExecutionMode,
    pub schema: Value,
}

/// How subc may deliver concurrent in-flight calls to the provider.
///
/// subc records and forwards these semantics unchanged; the dispatcher that
/// enforces them lives in subc-core, kept separate from this frozen manifest
/// contract.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum Concurrency {
    /// One in-flight call at a time with strict submission and response order.
    Serial,
    /// Concurrent in-flight calls may span channels, while subc preserves FIFO
    /// submission within each channel; the module schedules internally.
    ModuleManaged,
    /// Fully parallel delivery with no ordering guarantee across or within
    /// channels.
    StatelessParallel,
}

#[allow(clippy::derivable_impls)]
// The default is PINNED BY HISTORY, not chosen as the best value. Before this
// field existed, every ManagementSurface received ModuleManaged delivery (32
// concurrent credits) unconditionally, so an absent-field manifest must resolve
// to exactly that behavior -- any other default (including the fail-closed
// Serial) would convert a daemon upgrade into a silent delivery-semantics
// change for every deployed module. A genuinely-Serial module was ALREADY
// receiving concurrent delivery under pre-field daemons; the field's addition
// is what makes declaring Serial possible at all, so the fix for such a module
// is an explicit declaration, and the daemon logs defaulted registrations so
// the fleet's exposure is readable rather than assumed.
impl Default for Concurrency {
    fn default() -> Self {
        Self::ModuleManaged
    }
}

/// A `BindIdentity` key a provider partitions its state or answers by.
///
/// Declared in a role's `identity_scope` to say which caller keys change
/// what the module does; the daemon hands every bind all of the keys
/// regardless, so an empty declaration means "answers do not depend on the
/// caller", never "keys are refused".
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum IdentityScope {
    Session,
    Project,
}

/// Proxy-plane stage kind.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum PipelineStageKind {
    Transform,
    Codec,
    Auth,
}

/// Provider/model selector for a pipeline stage. `"*"` denotes wildcard.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct PipelineAppliesTo {
    pub provider: String,
    pub model: String,
}

/// Operation exposed on the management plane.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct ManagementOperation {
    pub name: String,
    pub kind: ManagementOperationKind,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ManagementOperationKind {
    Query,
    Mutate,
}

/// Observable state exposed on the management plane.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct ObservabilitySurface {
    pub name: String,
    pub kind: ObservabilityKind,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ObservabilityKind {
    Snapshot,
    Stream,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum InternalTransport {
    Bulk,
}

/// Consumer capabilities requested by a module.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(tag = "role", rename_all = "snake_case")]
pub enum ConsumerRole {
    ToolClient { of: Vec<String> },
    LlmClient { via: String, auth: String },
    ServiceClient { of: Vec<String> },
}

/// External storage, vault, and identity bindings supplied through subc.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct Bindings {
    pub storage: StorageBinding,
    pub vault_grants: Vec<VaultGrant>,
    pub identity: IdentityBinding,
}

/// Storage backend supplied by subc; the module owns its schema.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct StorageBinding {
    pub kind: StorageKind,
    pub scope: StorageScope,
    pub owns_schema: bool,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum StorageKind {
    Sqlite,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum StorageScope {
    Project,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct VaultGrant {
    pub secret: String,
    pub reason: String,
}

#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct IdentityBinding {
    pub requires: Vec<IdentityScope>,
    pub optional: Vec<IdentityScope>,
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn aft_manifest_fixture() -> ModuleManifest {
        ModuleManifest::builder("aft", "0.39.2")
            .trust_tier(Some(TrustTier::FirstParty))
            .bindings(Some(Bindings {
                storage: StorageBinding {
                    kind: StorageKind::Sqlite,
                    scope: StorageScope::Project,
                    owns_schema: true,
                },
                vault_grants: vec![VaultGrant {
                    secret: "provider_api_key".to_string(),
                    reason: "cortexkit_native auth".to_string(),
                }],
                identity: IdentityBinding {
                    requires: vec![IdentityScope::Project],
                    optional: vec![IdentityScope::Session],
                },
            }))
            .protocol_ver(1)
            .provides(vec![ProviderRole::ToolProvider {
                tools: vec![
                    Tool {
                        name: "read".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Pure,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "grep".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Pure,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "outline".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Pure,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "semantic_search".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Pure,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "edit".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Mutating,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "write".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Mutating,
                        schema: json!({"type": "object"}),
                    },
                    Tool {
                        name: "bash".to_string(),
                        description: None,
                        execution_mode: ExecutionMode::Unfenceable,
                        schema: json!({"type": "object"}),
                    },
                ],
                identity_scope: vec![IdentityScope::Session, IdentityScope::Project],
                concurrency: Concurrency::ModuleManaged,
                emits_push: true,
                sub_supervises: true,
            }])
            .consumes(vec![ConsumerRole::ServiceClient {
                of: vec!["embedding.v2".to_string()],
            }])
            .build()
    }

    #[test]
    fn serde_round_trips_representative_manifest() {
        let manifest = aft_manifest_fixture();
        let serialized = serde_json::to_string_pretty(&manifest).unwrap();
        let decoded: ModuleManifest = serde_json::from_str(&serialized).unwrap();

        assert_eq!(manifest, decoded);
    }

    #[test]
    fn builder_defaults_additions_to_honest_absence_and_round_trips() {
        let manifest = ModuleManifest::builder("builder-defaults", "2.0.0").build();

        assert_eq!(manifest.module_id, "builder-defaults");
        assert_eq!(manifest.module_version, "2.0.0");
        assert_eq!(manifest.protocol_ver, PROTOCOL_VERSION);
        assert_eq!(manifest.trust_tier, None);
        assert!(manifest.provides.is_empty());
        assert!(manifest.consumes.is_empty());
        assert_eq!(manifest.bindings, None);
        assert_eq!(manifest.capabilities, None);
        assert_eq!(manifest.self_signals, None);
        assert_eq!(manifest.provenance, None);

        let encoded = serde_json::to_value(&manifest).expect("builder manifest serializes");
        for optional in [
            "trust_tier",
            "consumes",
            "bindings",
            "capabilities",
            "self_signals",
            "provenance",
        ] {
            assert!(
                encoded.get(optional).is_none(),
                "an absent {optional} declaration must stay absent on the wire"
            );
        }
        let decoded: ModuleManifest =
            serde_json::from_value(encoded).expect("builder manifest round-trips");
        assert_eq!(decoded, manifest);
    }

    #[test]
    fn fully_populated_builder_manifest_matches_the_literal_wire_golden() {
        let manifest = ModuleManifest::builder("full-builder", "2.0.0")
            .trust_tier(Some(TrustTier::Reviewed))
            .bindings(Some(Bindings {
                storage: StorageBinding {
                    kind: StorageKind::Sqlite,
                    scope: StorageScope::Project,
                    owns_schema: false,
                },
                vault_grants: Vec::new(),
                identity: IdentityBinding {
                    requires: vec![IdentityScope::Project],
                    optional: Vec::new(),
                },
            }))
            .provides(vec![ProviderRole::ToolProvider {
                tools: vec![Tool {
                    name: "read".to_string(),
                    description: None,
                    execution_mode: ExecutionMode::Pure,
                    schema: json!({"type": "object"}),
                }],
                identity_scope: vec![IdentityScope::Project],
                concurrency: Concurrency::Serial,
                emits_push: false,
                sub_supervises: false,
            }])
            .consumes(vec![ConsumerRole::ServiceClient {
                of: vec!["embedding.v2".to_string()],
            }])
            .capabilities(Some(CapabilityDeclarations {
                provides: vec!["embedding/v2".to_string()],
                requires: Vec::new(),
                must_never_reach: Vec::new(),
            }))
            .self_signals(Some(vec![SelfSignalDeclaration {
                name: "usage_poller".to_string(),
                kind: SelfSignalKind::Poller,
                effect: SelfSignalEffect::Observe,
                anchored_to: SignalAnchor::FixedInterval,
                cadence: Some(SignalCadence::Literal {
                    interval_ms: 60_000,
                }),
                domain: Some("provider-usage".to_string()),
                note: None,
            }]))
            .provenance(Some(ManifestProvenance {
                build_git_sha: Some("0123456789abcdef0123456789abcdef01234567".to_string()),
                build_git_sha_absence_reason: None,
                build_lock_digest: Some(
                    "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789".to_string(),
                ),
                wire_crate_version: Some("0.16.0".to_string()),
                store_schema_version: Some("42".to_string()),
                launch_nonce_source: None,
            }))
            .build();

        assert_eq!(
            serde_json::to_vec(&manifest).expect("builder manifest serializes"),
            include_bytes!("../tests/golden/module_manifest_builder_full.json"),
            "the builder must preserve the prior fully populated literal wire bytes"
        );
    }

    #[test]
    fn old_manifest_with_unread_fields_decodes_and_round_trips_verbatim() {
        let raw = include_bytes!("../tests/golden/module_manifest_builder_full.json");
        let decoded: ModuleManifest =
            serde_json::from_slice(raw).expect("old manifest with all unread fields decodes");

        assert_eq!(decoded.trust_tier, Some(TrustTier::Reviewed));
        assert!(!decoded.consumes.is_empty());
        assert!(decoded.bindings.is_some());

        let reencoded = serde_json::to_vec(&decoded).expect("re-encode succeeds");
        assert_eq!(
            reencoded, raw,
            "old manifest relay stays byte-for-byte verbatim"
        );
    }

    #[test]
    fn new_manifest_omits_unread_fields_on_wire_and_decodes_cleanly() {
        let raw = include_bytes!("../tests/golden/module_manifest_diet.json");
        let decoded: ModuleManifest =
            serde_json::from_slice(raw).expect("new manifest omitting unread fields decodes");

        assert_eq!(decoded.trust_tier, None);
        assert!(decoded.consumes.is_empty());
        assert_eq!(decoded.bindings, None);

        let pretty = format!("{}\n", serde_json::to_string_pretty(&decoded).unwrap());
        assert_eq!(
            pretty.as_bytes(),
            raw,
            "new manifest matches golden byte-for-byte without unread keys"
        );

        let as_val: serde_json::Value = serde_json::to_value(&decoded).unwrap();
        assert!(
            as_val.get("trust_tier").is_none(),
            "no trust_tier on wire for new manifest"
        );
        assert!(
            as_val.get("consumes").is_none(),
            "no consumes on wire for empty consumes"
        );
        assert!(
            as_val.get("bindings").is_none(),
            "no bindings on wire for new manifest"
        );
    }

    #[test]
    fn aft_manifest_fixture_matches_v1_contract() {
        let manifest = aft_manifest_fixture();

        assert_eq!(manifest.module_id, "aft");
        let ProviderRole::ToolProvider {
            tools,
            identity_scope,
            concurrency,
            emits_push,
            sub_supervises,
        } = &manifest.provides[0]
        else {
            panic!("AFT fixture must expose one tool_provider role");
        };

        assert_eq!(*concurrency, Concurrency::ModuleManaged);
        assert!(*emits_push);
        assert!(*sub_supervises);
        assert_eq!(
            identity_scope,
            &vec![IdentityScope::Session, IdentityScope::Project]
        );
        assert_eq!(
            tools
                .iter()
                .map(|tool| (tool.name.as_str(), tool.execution_mode))
                .collect::<Vec<_>>(),
            vec![
                ("read", ExecutionMode::Pure),
                ("grep", ExecutionMode::Pure),
                ("outline", ExecutionMode::Pure),
                ("semantic_search", ExecutionMode::Pure),
                ("edit", ExecutionMode::Mutating),
                ("write", ExecutionMode::Mutating),
                ("bash", ExecutionMode::Unfenceable),
            ]
        );
    }

    #[test]
    fn tool_provider_role_tag_serializes_as_snake_case() {
        let manifest = aft_manifest_fixture();
        let value = serde_json::to_value(&manifest).unwrap();

        assert_eq!(value["provides"][0]["role"], "tool_provider");
    }

    #[test]
    fn manifest_without_capabilities_preserves_the_existing_wire_shape() {
        let manifest = aft_manifest_fixture();
        let encoded = serde_json::to_value(&manifest).expect("manifest serializes");
        assert!(encoded.get("capabilities").is_none());

        let decoded: ModuleManifest =
            serde_json::from_value(encoded).expect("legacy manifest parses");
        assert_eq!(decoded.capabilities, None);
    }

    #[test]
    fn capability_identifier_lexical_grammar_accepts_only_pinned_forms() {
        for identifier in [
            "a/v1",
            "credentials-provider/v1",
            "a1-b2/v4294967295",
            "a123456789012345678901234567890123456789012345678901234567890123/v1",
        ] {
            assert!(
                is_valid_capability_identifier(identifier),
                "identifier must be accepted: {identifier}"
            );
        }

        for identifier in [
            "credentials-Provider/v1",
            "credentials-provider/v01",
            "credentials-provider-/v1",
            "credentials--provider/v1",
            "Credentials-provider/v1",
            "credentials-provider/1",
            "credentials provider/v1",
            "credentials-provider/v0",
            "credentials-provider/v4294967296",
            "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/v1",
        ] {
            assert!(
                !is_valid_capability_identifier(identifier),
                "identifier must be rejected: {identifier}"
            );
        }
    }

    #[test]
    fn capability_grammar_errors_redact_secret_shaped_values() {
        let error = validate_manifest_capability_grammar(&json!({
            "capabilities": { "provides": ["sk-secret-value/v0"] }
        }))
        .expect_err("secret-shaped capability identifier is malformed");
        assert_eq!(error.field(), "capabilities.provides[0]");
        assert_eq!(error.value(), "<redacted>");
        assert!(!error.to_string().contains("sk-secret-value"));
    }

    /// Builder sentinels are the strings tooling emits where it means "no
    /// value" (shell fallbacks say `unknown`, not `unavailable`); publishing
    /// one as a build fact is the well-formed lie the provenance contract
    /// names. The helper must map every sentinel, any casing, to field
    /// omission — and must keep a canonical real value intact (the control arm,
    /// so the filter cannot pass by refusing everything).
    #[test]
    fn provenance_builder_sentinels_become_field_omission() {
        for sentinel in [
            "unknown",
            "UNKNOWN",
            "Unknown",
            "unavailable",
            "none",
            "None",
            "  unknown  ",
            "",
        ] {
            let p = build_provenance_from_source(
                BuildGitShaSource::Git {
                    revision: sentinel,
                    tree_state: GitTreeState::Clean,
                },
                Some(sentinel),
                Some(sentinel),
            )
            .expect("sentinels are omitted before form validation");
            assert_eq!(
                (
                    p.build_git_sha,
                    p.build_git_sha_absence_reason,
                    p.build_lock_digest,
                    p.store_schema_version,
                ),
                (
                    None,
                    Some(BuildGitShaAbsenceReason::NeverDerived),
                    None,
                    None,
                ),
                "sentinel {sentinel:?} must be omitted, not published"
            );
        }
        let real = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: "0123456789abcdef0123456789abcdef01234567",
                tree_state: GitTreeState::Clean,
            },
            None,
            Some("9"),
        )
        .expect("canonical build revision is accepted");
        assert_eq!(
            real.build_git_sha.as_deref(),
            Some("0123456789abcdef0123456789abcdef01234567")
        );
        assert_eq!(real.store_schema_version.as_deref(), Some("9"));
        // The always-knowable fact: an SDK-built block always carries a crate
        // version, so it is never empty; that is why the contract omits a
        // field when it is absent rather than publishing a sentinel.
        assert_eq!(
            real.wire_crate_version.as_deref(),
            Some(crate::SUBC_PROTOCOL_CRATE_VERSION)
        );
    }

    #[test]
    fn build_provenance_accepts_canonical_sha_and_lock_digest() {
        let provenance = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: " 0123456789abcdef0123456789abcdef01234567 ",
                tree_state: GitTreeState::Clean,
            },
            Some(" abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789 "),
            Some(" schema-v3 "),
        )
        .expect("canonical build facts are accepted");

        assert_eq!(
            provenance,
            ManifestProvenance {
                build_git_sha: Some("0123456789abcdef0123456789abcdef01234567".to_string()),
                build_git_sha_absence_reason: None,
                build_lock_digest: Some(
                    "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789".to_string(),
                ),
                wire_crate_version: Some(crate::SUBC_PROTOCOL_CRATE_VERSION.to_string()),
                store_schema_version: Some("schema-v3".to_string()),
                launch_nonce_source: None,
            }
        );
    }

    #[test]
    fn build_provenance_refuses_an_abbreviated_git_sha() {
        let error = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: "0123456789ab",
                tree_state: GitTreeState::Clean,
            },
            None,
            None,
        )
        .expect_err("a 12-character abbreviation is not canonical");

        assert_eq!(error.field(), "build_git_sha");
        assert_eq!(error.length(), 12);
        assert_eq!(error.canonical_form(), BUILD_GIT_SHA_CANONICAL_FORM);
        assert_eq!(
            error.to_string(),
            "invalid manifest provenance form: field build_git_sha has length 12; canonical form is exactly 40 lowercase hexadecimal characters"
        );
    }

    #[test]
    fn build_provenance_refuses_an_abbreviated_lock_digest() {
        let error = build_provenance_from_source(
            BuildGitShaSource::NeverDerived,
            Some("0123456789abcdef"),
            None,
        )
        .expect_err("a 16-character digest is not canonical");

        assert_eq!(error.field(), "build_lock_digest");
        assert_eq!(error.length(), 16);
        assert_eq!(error.canonical_form(), BUILD_LOCK_DIGEST_CANONICAL_FORM);
    }

    #[test]
    fn build_provenance_refuses_uppercase_hex() {
        let uppercase_sha = "A".repeat(40);
        let error = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: &uppercase_sha,
                tree_state: GitTreeState::Clean,
            },
            None,
            None,
        )
        .expect_err("uppercase hexadecimal is not canonical");

        assert_eq!(error.field(), "build_git_sha");
        assert_eq!(error.length(), 40);
        assert_eq!(error.canonical_form(), BUILD_GIT_SHA_CANONICAL_FORM);
    }

    #[test]
    fn build_provenance_refuses_dirty_revision_stamp_claimed_clean() {
        let error = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: "0123456789abcdef0123456789abcdef01234567-dirty",
                tree_state: GitTreeState::Clean,
            },
            None,
            None,
        )
        .expect_err("a dirty stamp is not a canonical build revision");

        assert_eq!(error.field(), "build_git_sha");
        assert_eq!(error.length(), 46);
        assert_eq!(error.canonical_form(), BUILD_GIT_SHA_CANONICAL_FORM);
    }

    #[test]
    fn build_provenance_keeps_a_lock_digest_when_identity_is_unavailable() {
        let provenance = build_provenance_from_source(
            BuildGitShaSource::Git {
                revision: "unavailable",
                tree_state: GitTreeState::Clean,
            },
            Some("abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"),
            None,
        )
        .expect("sentinel SHA is omitted before the valid lock digest is checked");

        assert_eq!(provenance.build_git_sha, None);
        assert_eq!(
            provenance.build_lock_digest,
            Some("abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789".to_string())
        );
        assert_eq!(
            provenance.wire_crate_version,
            Some(crate::SUBC_PROTOCOL_CRATE_VERSION.to_string())
        );
    }

    #[test]
    fn build_provenance_omits_fully_unavailable_inputs() {
        let provenance = build_provenance_from_source(
            BuildGitShaSource::NeverDerived,
            Some(" unavailable "),
            Some("   "),
        )
        .expect("omitted and sentinel inputs are not form errors");

        assert_eq!(provenance.build_git_sha, None);
        assert_eq!(provenance.build_lock_digest, None);
        assert_eq!(provenance.store_schema_version, None);
        assert_eq!(
            provenance.wire_crate_version,
            Some(crate::SUBC_PROTOCOL_CRATE_VERSION.to_string())
        );
    }

    #[test]
    fn legacy_build_provenance_keeps_master_wire_bytes_without_an_absence_reason() {
        let revision = "0123456789abcdef0123456789abcdef01234567";
        for (input, expected) in [
            (
                Some(revision),
                format!(
                    r#"{{"build_git_sha":"{revision}","wire_crate_version":"{}"}}"#,
                    crate::SUBC_PROTOCOL_CRATE_VERSION
                ),
            ),
            (
                None,
                format!(
                    r#"{{"wire_crate_version":"{}"}}"#,
                    crate::SUBC_PROTOCOL_CRATE_VERSION
                ),
            ),
            (
                Some("unknown"),
                format!(
                    r#"{{"wire_crate_version":"{}"}}"#,
                    crate::SUBC_PROTOCOL_CRATE_VERSION
                ),
            ),
        ] {
            let provenance = build_provenance(input, None, None)
                .expect("the legacy build facts remain constructible");
            assert_eq!(provenance.build_git_sha_absence_reason, None);
            assert_eq!(
                serde_json::to_string(&provenance).expect("legacy provenance serializes"),
                expected
            );
        }
    }

    #[test]
    fn build_provenance_derives_git_sha_absence_from_the_stamping_inputs() {
        let revision = "0123456789abcdef0123456789abcdef01234567";
        let cases = [
            (
                BuildGitShaSource::Git {
                    revision,
                    tree_state: GitTreeState::Clean,
                },
                Some(revision),
                None,
            ),
            (
                BuildGitShaSource::Git {
                    revision,
                    tree_state: GitTreeState::Dirty,
                },
                None,
                Some(BuildGitShaAbsenceReason::DeclinedDirty),
            ),
            (
                BuildGitShaSource::NeverDerived,
                None,
                Some(BuildGitShaAbsenceReason::NeverDerived),
            ),
            (
                BuildGitShaSource::NoGitDir,
                None,
                Some(BuildGitShaAbsenceReason::NoGitDir),
            ),
        ];

        for (source, expected_sha, expected_reason) in cases {
            let provenance = build_provenance_from_source(source, None, None)
                .expect("every stamping state constructs honest provenance");
            assert_eq!(provenance.build_git_sha.as_deref(), expected_sha);
            assert_eq!(provenance.build_git_sha_absence_reason, expected_reason);
        }
    }

    #[test]
    fn unknown_git_sha_absence_reason_round_trips_byte_faithfully() {
        let wire = format!(
            r#"{{"build_git_sha_absence_reason":"future_stamper_state","wire_crate_version":"{}"}}"#,
            crate::SUBC_PROTOCOL_CRATE_VERSION
        );
        let provenance: ManifestProvenance =
            serde_json::from_str(&wire).expect("future absence reasons remain readable");

        assert_eq!(
            provenance.build_git_sha_absence_reason,
            Some(BuildGitShaAbsenceReason::ForwardCompatibleUnknown(
                "future_stamper_state".to_string()
            ))
        );
        assert_eq!(
            serde_json::to_string(&provenance).expect("future absence reason reserializes"),
            wire
        );
    }

    #[test]
    fn provenance_rejects_an_absence_reason_beside_a_declared_commit() {
        let error = serde_json::from_value::<ManifestProvenance>(json!({
            "build_git_sha": "0123456789abcdef0123456789abcdef01234567",
            "build_git_sha_absence_reason": "declined_dirty"
        }))
        .expect_err("a declared commit cannot also claim an absence reason");

        assert!(error.to_string().contains(
            "build_git_sha_absence_reason has must be omitted when build_git_sha is present"
        ));
    }
}