aion_package/

contract.rs

//! Durable worker-contract records and their canonical identity encoding.

use std::time::Duration;

use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::Manifest;

/// Refusal returned when a stored package predates contract-bound identity.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum ContractIdentityError {
    /// The package is integrity-valid but its identity commits to no contract.
    #[error(
        "package identity `{stored_version}` predates `.v4` worker-contract commitment; re-deploy this package under `.v4`"
    )]
    RedeployRequired {
        /// Stored pre-`.v4` package identity.
        stored_version: String,
    },
}

/// The complete contract surface committed into a package's `.v4` identity.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PackageContract {
    /// Primary workflow input schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
    /// Primary workflow output schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub output_schema: Value,
    /// Queue-scoped activity declarations.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub workers: Vec<WorkerContract>,
    /// Declared child workflow callables.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub children: Vec<ChildContract>,
    /// Declared signal payloads.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub signals: Vec<SignalContract>,
    /// Additional workflow entry schemas in this package.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub additional_workflows: Vec<AdditionalWorkflowContract>,
    /// Activity names retained by legacy project manifests that cannot declare a
    /// queue or typed activity surface. They remain identity-bound but do not
    /// create a queue declaration.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub unscoped_activities: Vec<String>,
    /// The workloop declaration surface, when the package's entry document is
    /// a `workloop`. This is what the ENGINE reads at start time to arm the
    /// cadence, seed generation 1's carries and evaluate tolerances, so it
    /// must travel with the deployed archive rather than only with the
    /// in-process compile output — a server restart must not forget what a
    /// deployed loop's tolerances were.
    ///
    /// IDENTITY-BOUND, and that is not a formality: a tolerance rewritten in
    /// storage changes WHEN a loop alarms, and a retention window rewritten in
    /// storage changes WHAT is destroyed. Both are executable authority, so
    /// two packages that differ in them must not be one version.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workloop: Option<WorkloopContract>,
}

/// The workloop declaration surface, as compiled from a `workloop` document
/// (workloop design brief R2/R8/R13): everything the engine needs to arm
/// the loop, seed the first generation's carries from the declared
/// defaults, and evaluate tolerances without re-reading AWL source.
///
/// Carried on the COMPILE OUTPUT (`aion_awl::CompiledWorkflow::workloop`) and
/// on the deployed archive's [`PackageContract`], where it is bound into
/// package identity: the engine reads it at START time to arm the cadence,
/// seed generation 1's carries and evaluate tolerances, so it must survive a
/// server restart and must not be rewritable in storage without changing the
/// package's version.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct WorkloopContract {
    /// The `every` cadence in seconds, when declared.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cadence_seconds: Option<u64>,
    /// The `on <signal>` arming signal names, in declaration order.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub arms: Vec<String>,
    /// The carries: name, value schema, and the declared default the engine
    /// seeds the FIRST generation with (later generations carry the values
    /// `route start` minted).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub carries: Vec<CarryContract>,
    /// The invariants, with their declared tolerances and confirming routes.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub invariants: Vec<InvariantContract>,
    /// The declared `retention` window in seconds (R8.1 — required, no
    /// default).
    pub retention_seconds: u64,
    /// The `detached` hatch-target contracts: name and start schema.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub detached: Vec<DetachedContract>,
    /// The report tiles: name and value schema.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub reports: Vec<ReportContract>,
    /// Whether the document declares a `retire` block, and therefore whether
    /// the deployed module exports `retire/1`.
    ///
    /// 🔴 A DECLARATION, NOT A CALLER PREFERENCE. Retirement has two engine
    /// verbs — one that invokes the declared cleanup and one for a loop that
    /// declares none — and which applies is decided by the DOCUMENT. If an
    /// operator could choose, a declared cleanup could be skipped by passing
    /// an argument, which is how a lease is lost. If the engine guessed, it
    /// could not tell a module compiled before the entry existed from a loop
    /// that declared no cleanup, which is the same failure wearing a
    /// different hat. So the answer travels with the package, bound into its
    /// identity like every other executable authority here.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub has_retire_body: bool,
}

/// One `carry` declaration: name, schema, and the folded default seed.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct CarryContract {
    /// Carry name (an input-record field of every generation).
    pub name: String,
    /// The carry's value schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub schema: Value,
    /// The declared default, folded to a JSON literal.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub default: Value,
}

/// One declared tolerance form (R2.3 — no default; both may stand).
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "form", rename_all = "snake_case")]
pub enum ToleranceContract {
    /// `tolerance <N> windows` — N consecutive unhealthy samples.
    Windows {
        /// The declared window count.
        count: u64,
    },
    /// `tolerance unconfirmed for <duration>` — the only form evaluable
    /// with zero samples (R2.4a).
    UnconfirmedFor {
        /// The declared window in seconds.
        seconds: u64,
    },
}

/// One `invariant` declaration.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct InvariantContract {
    /// Invariant name.
    pub name: String,
    /// The DECLARED type name of the current-state record (`invariant serving:
    /// type Board` → `"Board"`).
    ///
    /// Carried beside the schema, not derived from it: the engine stamps this
    /// on every durable invariant current-state record as provenance, so a
    /// reader can tell which declaration a stored value was written under. A
    /// schema is structural and two different declarations can share one.
    pub record_type: String,
    /// The current-state record schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub schema: Value,
    /// The declared tolerance forms, in declaration order (never empty for
    /// a checked document — C3).
    pub tolerances: Vec<ToleranceContract>,
    /// The route whose firing confirms the invariant, when declared.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub confirms: Option<String>,
}

/// One `detached` hatch-target contract.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct DetachedContract {
    /// The detached workflow's logical name (the hatch dedupe scope is
    /// namespace + this name + the site's key).
    pub name: String,
    /// Start-contract schema over the declared parameters.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
}

/// One `report` tile contract.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ReportContract {
    /// Report name (registered through the answer surface).
    pub name: String,
    /// The tile's value schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub schema: Value,
}

impl PackageContract {
    /// Produces the most precise contract available from a legacy manifest.
    ///
    /// This never invents a queue or schemas for bare activity names. Such names
    /// are committed as unscoped records and therefore cannot satisfy a
    /// structural queue-service check.
    #[must_use]
    pub fn from_manifest(manifest: &Manifest) -> Self {
        Self {
            input_schema: manifest.input_schema.clone(),
            output_schema: manifest.output_schema.clone(),
            workers: Vec::new(),
            children: Vec::new(),
            signals: Vec::new(),
            additional_workflows: manifest
                .additional_workflows
                .iter()
                .map(|entry| AdditionalWorkflowContract {
                    workflow_type: entry.workflow_type.clone(),
                    input_schema: entry.input_schema.clone(),
                    output_schema: entry.output_schema.clone(),
                })
                .collect(),
            unscoped_activities: manifest
                .activities
                .iter()
                .map(|activity| activity.activity_type.clone())
                .collect(),
            // A legacy manifest declares no workloop surface: the header a
            // loop needs did not exist when it was built, and inventing one
            // would arm a cadence nobody wrote.
            workloop: None,
        }
    }

    /// Returns the deterministic binary encoding committed by the current
    /// identity domain.
    ///
    /// Declaration vectors and JSON object keys are sorted before encoding.
    /// JSON whitespace and source map insertion order therefore cannot affect
    /// package identity.
    #[must_use]
    pub fn canonical_bytes(&self) -> Vec<u8> {
        self.canonical_bytes_in(ContractDomain::V6)
    }

    /// The superseded `.v5` encoding, exactly as every released cut from
    /// v0.19 through v0.24 computed it: no per-action agent byte, no
    /// workloop block.
    ///
    /// 🔴 VERIFICATION-ONLY MIGRATION SURFACE. This exists so the verifier
    /// in [`crate::hash`] can re-attest archives those releases minted —
    /// a store restarted under the current build must not strand its own
    /// recorded deployments. Nothing ever MINTS a `.v5` identity again;
    /// calling this anywhere except a verifier is a defect.
    #[must_use]
    pub fn legacy_v5_canonical_bytes(&self) -> Vec<u8> {
        self.canonical_bytes_in(ContractDomain::LegacyV5)
    }

    fn canonical_bytes_in(&self, domain: ContractDomain) -> Vec<u8> {
        let mut bytes = Vec::new();
        encode_json(&mut bytes, None, &self.input_schema);
        encode_json(&mut bytes, None, &self.output_schema);

        let mut workers = self
            .workers
            .iter()
            .map(|worker| worker.canonical_bytes_in(domain))
            .collect::<Vec<_>>();
        workers.sort();
        encode_len(&mut bytes, workers.len());
        for worker in workers {
            update_record(&mut bytes, &worker);
        }

        let mut children = self
            .children
            .iter()
            .map(ChildContract::canonical_bytes)
            .collect::<Vec<_>>();
        children.sort();
        encode_len(&mut bytes, children.len());
        for child in children {
            update_record(&mut bytes, &child);
        }

        let mut signals = self.signals.iter().collect::<Vec<_>>();
        signals.sort_by(|left, right| left.name.cmp(&right.name));
        encode_len(&mut bytes, signals.len());
        for signal in signals {
            encode_text(&mut bytes, &signal.name);
            encode_json(&mut bytes, None, &signal.input_schema);
        }

        let mut additional = self.additional_workflows.iter().collect::<Vec<_>>();
        additional.sort_by(|left, right| left.workflow_type.cmp(&right.workflow_type));
        encode_len(&mut bytes, additional.len());
        for workflow in additional {
            encode_text(&mut bytes, &workflow.workflow_type);
            encode_json(&mut bytes, None, &workflow.input_schema);
            encode_json(&mut bytes, None, &workflow.output_schema);
        }

        let mut unscoped = self.unscoped_activities.iter().collect::<Vec<_>>();
        unscoped.sort();
        encode_len(&mut bytes, unscoped.len());
        for activity in unscoped {
            encode_text(&mut bytes, activity);
        }

        // The WORKLOOP block, encoded UNCONDITIONALLY (a presence
        // discriminant, then the whole surface) under the `.v6` domain. Every
        // value here is executable authority the engine acts on: the cadence
        // decides when the loop fires, the tolerances decide when it alarms,
        // the retention window decides what is destroyed, and the carry
        // defaults decide what generation 1 starts from. The `.v5` domain
        // predates the field entirely, so its encoding stops here — and the
        // verifier refuses to attest a workloop under `.v5` for the same
        // reason this block encodes under `.v6`.
        if domain == ContractDomain::V6 {
            match &self.workloop {
                None => bytes.push(0),
                Some(workloop) => {
                    bytes.push(1);
                    update_record(&mut bytes, &workloop.canonical_bytes());
                }
            }
        }
        bytes
    }
}

/// Which identity domain a canonical encoding targets.
///
/// `LegacyV5` exists ONLY for the verifier's migration accommodation
/// ([`crate::hash`]); it is never a minting target.
#[derive(Clone, Copy, PartialEq, Eq)]
enum ContractDomain {
    /// The superseded released domain (v0.19–v0.24): no per-action agent
    /// byte, no workloop block.
    LegacyV5,
    /// The current domain.
    V6,
}

impl WorkloopContract {
    fn canonical_bytes(&self) -> Vec<u8> {
        let mut bytes = Vec::new();
        match self.cadence_seconds {
            None => bytes.push(0),
            Some(seconds) => {
                bytes.push(1);
                bytes.extend_from_slice(&seconds.to_be_bytes());
            }
        }
        // Arming signals, carries, invariants, detached targets and reports
        // are all encoded in DECLARATION order rather than sorted: unlike a
        // worker's action set, these are ordered declarations in the document
        // and reordering them is a source change the author made.
        encode_len(&mut bytes, self.arms.len());
        for arm in &self.arms {
            encode_text(&mut bytes, arm);
        }
        encode_len(&mut bytes, self.carries.len());
        for carry in &self.carries {
            encode_text(&mut bytes, &carry.name);
            encode_json(&mut bytes, None, &carry.schema);
            encode_json(&mut bytes, None, &carry.default);
        }
        encode_len(&mut bytes, self.invariants.len());
        for invariant in &self.invariants {
            encode_text(&mut bytes, &invariant.name);
            encode_text(&mut bytes, &invariant.record_type);
            encode_json(&mut bytes, None, &invariant.schema);
            encode_len(&mut bytes, invariant.tolerances.len());
            for tolerance in &invariant.tolerances {
                match tolerance {
                    ToleranceContract::Windows { count } => {
                        bytes.push(1);
                        bytes.extend_from_slice(&count.to_be_bytes());
                    }
                    ToleranceContract::UnconfirmedFor { seconds } => {
                        bytes.push(2);
                        bytes.extend_from_slice(&seconds.to_be_bytes());
                    }
                }
            }
            encode_optional_text(&mut bytes, invariant.confirms.as_deref());
        }
        bytes.extend_from_slice(&self.retention_seconds.to_be_bytes());
        encode_len(&mut bytes, self.detached.len());
        for detached in &self.detached {
            encode_text(&mut bytes, &detached.name);
            encode_json(&mut bytes, None, &detached.input_schema);
        }
        encode_len(&mut bytes, self.reports.len());
        for report in &self.reports {
            encode_text(&mut bytes, &report.name);
            encode_json(&mut bytes, None, &report.schema);
        }
        bytes.push(u8::from(self.has_retire_body));
        bytes
    }
}

/// The actions a worker queue must serve.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct WorkerContract {
    /// Declared task queue.
    pub task_queue: String,
    /// Typed activities on the queue.
    pub actions: Vec<ActionContract>,
}

impl WorkerContract {
    fn canonical_bytes_in(&self, domain: ContractDomain) -> Vec<u8> {
        let mut bytes = Vec::new();
        encode_text(&mut bytes, &self.task_queue);
        let mut actions = self
            .actions
            .iter()
            .map(|action| action.canonical_bytes_in(domain))
            .collect::<Vec<_>>();
        actions.sort();
        encode_len(&mut bytes, actions.len());
        for action in actions {
            update_record(&mut bytes, &action);
        }
        bytes
    }
}

/// Typed activity surface advertised by a concrete worker build.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ActivityDescriptor {
    /// Activity type.
    pub name: String,
    /// Schema accepted by the worker.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
    /// Schema produced by the worker.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub output_schema: Value,
}

/// One typed activity declaration.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ActionContract {
    /// Activity type.
    pub name: String,
    /// Object schema over the activity parameters.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
    /// Activity result schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub output_schema: Value,
    /// Declared node selector.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node: Option<String>,
    /// Declared schedule-to-close timeout.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout: Option<Duration>,
    /// Declaration-owned retry envelope.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retry: Option<RetryContract>,
    /// Whether the declaration classes this activity as ADVISORY: a side
    /// channel whose failure warns on the run and never faults the calling
    /// step (RUNTIME-OPERATIONS.md R5). Identity-bound — flipping it changes
    /// what the package promises a caller.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub advisory: bool,
    /// Whether the declaration classes this activity as an AGENT seam: its one
    /// `String` parameter carries a prompt and its `String` result carries the
    /// reply, so a worker hands the call to an agent harness rather than to a
    /// typed handler. The checker enforces that shape, so a worker reading this
    /// flag may rely on it.
    ///
    /// Identity-bound for the same reason `advisory` is — an action that
    /// becomes an agent seam promises a caller something different — and
    /// skipped when false, so a document with no agent action hashes exactly as
    /// it did before the marker existed.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub agent: bool,
    /// The declarative body the action carries, when it declares one.
    ///
    /// `None` is a requirement on an out-of-band worker: the action's name
    /// and schemas are the whole promise, and something must connect to
    /// serve it. `Some` means the package itself says what the action DOES,
    /// so the host can execute it with no worker connected.
    ///
    /// Identity-bound deliberately: the body is executable authority, and an
    /// authority that did not participate in the package hash could be
    /// rewritten in storage without changing what the deployment claims to
    /// be. A body edit is a new package, always.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<ActionBodyContract>,
}

/// A declarative action body committed into package identity.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ActionBodyContract {
    /// One command line, executed directly with argv-element parameter
    /// substitution — never through a shell. The text is the authored form
    /// with `$` interpolation intact; the executor parses it and substitutes
    /// each referenced parameter as one whole argument.
    Run {
        /// The authored command text.
        command: String,
    },
    /// One DECLARED command (`runs command <name>`), carried in its emitted
    /// typed form: literal program words, one templated slot per argument,
    /// declared environment bindings, working directory and timeout.
    ///
    /// The difference from [`ActionBodyContract::Run`] is not spelling. A
    /// `Run` body is a command LINE that the executor still has to split; a
    /// `Command` body was split by the AWL emitter at compile time and travels
    /// as an argument list, so nothing downstream ever holds a string that
    /// could be re-split.
    Command {
        /// What the action's result is taken from.
        capture: CommandBodyCapture,
        /// The emitted command.
        command: Box<crate::declared_command::DeclaredCommandContract>,
    },
}

/// What a `runs command` body's result is, and therefore what the action's
/// declared return type has to be.
///
/// Two forms, not three: a declared command's caller is asking for the
/// command's OUTPUT, and the outcome record that a bare `run "…"` body yields
/// is the shape the string form has for historical reasons. An action that
/// wants an exit code takes it from a `run` body.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CommandBodyCapture {
    /// Trimmed stdout becomes a JSON string. A non-zero exit is a retryable
    /// failure carrying stderr.
    Text,
    /// Trimmed stdout is parsed as JSON and becomes the result. A non-zero
    /// exit is a retryable failure carrying stderr; stdout that is not valid
    /// JSON is a terminal one.
    Json,
}

impl CommandBodyCapture {
    /// The byte this capture contributes to a canonical identity record.
    const fn identity_byte(self) -> u8 {
        match self {
            Self::Text => 0,
            Self::Json => 1,
        }
    }
}

impl ActionContract {
    /// Whether serving this action is a WORKER's job.
    ///
    /// `true` when the action carries no declared body: the declaration is a
    /// requirement on an out-of-band worker, and nothing runs until one
    /// connects and advertises the action. `false` when the action carries a
    /// declared body: the package itself says what the action does, the host
    /// executes it, and no worker is needed or admitted for it.
    ///
    /// This is the one place the body-exemption rule lives. Every surface
    /// that splits a queue's actions into worker-owed and server-run —
    /// admission diffs, availability, scaffolding, codegen — must call this
    /// rather than restate `body.is_none()`.
    #[must_use]
    pub fn worker_owed(&self) -> bool {
        self.body.is_none()
    }

    fn canonical_bytes_in(&self, domain: ContractDomain) -> Vec<u8> {
        let mut bytes = Vec::new();
        encode_text(&mut bytes, &self.name);
        encode_json(&mut bytes, None, &self.input_schema);
        encode_json(&mut bytes, None, &self.output_schema);
        encode_optional_text(&mut bytes, self.node.as_deref());
        encode_optional_duration(&mut bytes, self.timeout);
        match &self.retry {
            None => bytes.push(0),
            Some(RetryContract::Every { count, every }) => {
                bytes.push(1);
                bytes.extend_from_slice(&count.to_be_bytes());
                encode_duration(&mut bytes, *every);
            }
            Some(RetryContract::Backoff { count, min, max }) => {
                bytes.push(2);
                bytes.extend_from_slice(&count.to_be_bytes());
                encode_duration(&mut bytes, *min);
                encode_duration(&mut bytes, *max);
            }
        }
        // ADVISORY is encoded ONLY when true: a single marker byte appended
        // after the retry block, and nothing at all when false. It is
        // injective because absence and the marker cannot be confused at the
        // end of a positional record — the block that FOLLOWS it always
        // begins with a body discriminant, and no body discriminant is ever
        // `ADVISORY_MARKER`. Stated as the rule rather than as a list of the
        // discriminants that exist today, because the list grows.
        if self.advisory {
            bytes.push(ADVISORY_MARKER);
        }
        // The BODY block always encodes — a discriminant byte, then the
        // command text for `Run`. Adding it consumed the record's optional
        // tail (the advisory marker was the one tail-append the previous
        // domain could injectively absorb), which is why this encoding lives
        // under the bumped `.v5` identity domain rather than as a second
        // conditional suffix: two optional tails are not injective, and a
        // contract identity that two different declarations can share is a
        // spoofable deployment.
        //
        // LAW for the next field: encode it UNCONDITIONALLY after this
        // block and bump the identity domain again. Never append another
        // optional tail.
        match &self.body {
            None => bytes.push(0),
            Some(ActionBodyContract::Run { command }) => {
                bytes.push(1);
                encode_text(&mut bytes, command);
            }
            // A DECLARED command body encodes its whole emitted form, not a
            // name: the argv slots, the environment, the working directory and
            // the timeout are each executable authority, and a package whose
            // identity named only `say_hello` could have its argument list
            // rewritten in storage without changing what the deployment claims
            // to be. The discriminant continues the same positional block, so
            // no optional tail is added and the domain does not move again.
            Some(ActionBodyContract::Command { capture, command }) => {
                bytes.push(2);
                bytes.push(capture.identity_byte());
                crate::declared_command::encode_identity(&mut bytes, command);
            }
        }
        // 🔴 THE AGENT MARKER (aion#158). Its own doc comment above says it is
        // identity-bound "for the same reason `advisory` is" — and it was
        // referenced ZERO times in this encoder, so the claim was false and two
        // declarations that differ only in whether an action is an agent seam
        // hashed identically. An action that becomes an agent seam promises a
        // caller something different: its `String` parameter is a prompt and
        // its `String` result is a reply, and a worker may rely on that shape.
        //
        // Encoded UNCONDITIONALLY, exactly as the law above prescribes, under
        // the bumped `.v6` domain — never as a second optional tail, which
        // would not be injective alongside the advisory marker. Under the
        // `.v5` migration accommodation the byte is absent because that is
        // what every released cut computed: a re-attested `.v5` archive's
        // agent flags travel AS STORED, un-vouched, at exactly the trust
        // level those releases gave them — redeploying mints the `.v6`
        // identity that binds them.
        if domain == ContractDomain::V6 {
            bytes.push(u8::from(self.agent));
        }
        bytes
    }
}

/// The marker byte appended to an advisory action's canonical record.
///
/// Distinct from every retry-kind discriminant (`0`/`1`/`2`) it can follow,
/// so a reader of the trailing bytes is never ambiguous.
const ADVISORY_MARKER: u8 = 0xA0;

/// A declaration-owned retry envelope.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RetryContract {
    /// Constant delay between attempts.
    Every {
        /// Number of further attempts after the first.
        count: u64,
        /// Delay between attempts.
        every: Duration,
    },
    /// Bounded backoff between attempts.
    Backoff {
        /// Number of further attempts after the first.
        count: u64,
        /// Minimum delay.
        min: Duration,
        /// Maximum delay.
        max: Duration,
    },
}

/// One declared child workflow callable.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChildContract {
    /// Child workflow type.
    pub name: String,
    /// Object schema over child parameters.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
    /// Child result schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub output_schema: Value,
}

impl ChildContract {
    fn canonical_bytes(&self) -> Vec<u8> {
        let mut bytes = Vec::new();
        encode_text(&mut bytes, &self.name);
        encode_json(&mut bytes, None, &self.input_schema);
        encode_json(&mut bytes, None, &self.output_schema);
        bytes
    }
}

/// One declared signal payload.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct SignalContract {
    /// Signal name.
    pub name: String,
    /// Signal payload schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
}

/// Typed shape of an additional entry in the same package.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct AdditionalWorkflowContract {
    /// Routing workflow type.
    pub workflow_type: String,
    /// Entry input schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub input_schema: Value,
    /// Entry output schema.
    #[serde(serialize_with = "crate::canonical::serialize_value")]
    pub output_schema: Value,
}

fn encode_json(bytes: &mut Vec<u8>, parent_key: Option<&str>, value: &Value) {
    match value {
        Value::Null => bytes.push(0),
        Value::Bool(value) => bytes.extend_from_slice(&[1, u8::from(*value)]),
        Value::Number(value) => {
            bytes.push(2);
            encode_text(bytes, &value.to_string());
        }
        Value::String(value) => {
            bytes.push(3);
            encode_text(bytes, value);
        }
        Value::Array(values) => {
            bytes.push(4);
            let mut values = values.iter().collect::<Vec<_>>();
            if matches!(parent_key, Some("required" | "enum")) {
                values.sort_by_key(ToString::to_string);
            }
            encode_len(bytes, values.len());
            for value in values {
                encode_json(bytes, None, value);
            }
        }
        Value::Object(values) => {
            bytes.push(5);
            let mut entries = values.iter().collect::<Vec<_>>();
            entries.sort_by_key(|(left, _)| *left);
            encode_len(bytes, entries.len());
            for (key, value) in entries {
                encode_text(bytes, key);
                encode_json(bytes, Some(key), value);
            }
        }
    }
}

fn encode_len(bytes: &mut Vec<u8>, len: usize) {
    bytes.extend_from_slice(&(len as u64).to_be_bytes());
}

fn encode_text(bytes: &mut Vec<u8>, value: &str) {
    encode_len(bytes, value.len());
    bytes.extend_from_slice(value.as_bytes());
}

fn update_record(bytes: &mut Vec<u8>, record: &[u8]) {
    encode_len(bytes, record.len());
    bytes.extend_from_slice(record);
}

fn encode_optional_text(bytes: &mut Vec<u8>, value: Option<&str>) {
    match value {
        Some(value) => {
            bytes.push(1);
            encode_text(bytes, value);
        }
        None => bytes.push(0),
    }
}

fn encode_optional_duration(bytes: &mut Vec<u8>, value: Option<Duration>) {
    match value {
        Some(value) => {
            bytes.push(1);
            encode_duration(bytes, value);
        }
        None => bytes.push(0),
    }
}

fn encode_duration(bytes: &mut Vec<u8>, value: Duration) {
    bytes.extend_from_slice(&value.as_secs().to_be_bytes());
    bytes.extend_from_slice(&value.subsec_nanos().to_be_bytes());
}

#[cfg(test)]
#[path = "contract_tests.rs"]
mod tests;