harness-spec

use harness_spec;

pub use error::{SpecError, ValidationError, Violation, ViolationCode};

pub use hash::ManifestHash;

pub use manifest::{
    CapabilitiesTable, ContextScope, ContextTable, EconomicsTable, Gate, HarnessTable,
    IdentityTable, InferenceTable, LoopTable, Manifest, MemoryTable, PerceptionTable, PolicyTable,
    SpawnTable, SubstrateTable, TelemetryStream, TelemetryTable, ToolsTable, VerificationTable,
    VoiceTable,
};

pub use validate::{
    ToolRegistry, ValidatedManifest, ValidationContext, BUILTIN_LOOP_STRATEGIES,
    DEFAULT_MAX_DERIVATION_DEPTH, NOUS_INGEST_CAP_BYTES,
};

pub use vocab::{
    AckPolicy, AsrRouteClass, BargeIn, CacheClass, ContextProvider, DataClass, Enrichment,
    GateKind, Interjection, Isolation, MediaRetention, MemoryType, Modality, Narrowing,
    OnBudgetExhausted, PerceptionProvider, PlaneName, PolicyEngine, RouteDecision, Settlement,
    StreamKind, SubstrateClass, TtsRouteClass, WritePolicy,
};

#[derive(Debug, Error)]
pub enum SpecError {
    /// The manifest is not well-formed TOML or violates the strict serde
    /// schema (unknown tables, unknown keys, unknown enum variants, wrong
    /// scalar types). This is the first §5.16 fail-closed layer.
    #[error("manifest parse failed: {0}")]
    Parse(#[from] toml::de::Error),

    /// The manifest parsed but violated one or more §5 validation rules.
    #[error("manifest validation failed:\n{0}")]
    Validation(#[from] ValidationError),

    /// The canonical JSON projection could not be produced. Unreachable for
    /// derive-only manifests; reserved for defensive completeness.
    #[error("canonical projection failed: {0}")]
    Canonicalization(#[from] serde_json::Error),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationError {

}

pub fn violations(&self) -> &[Violation];

pub fn contains(&self, code: ViolationCode) -> bool;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Violation {
/// Machine-checkable rule code.

pub code: ViolationCode,
/// Dotted manifest path of the offending value (e.g. `tools.deny_default`).

pub path: String,
/// Human-readable explanation, including the governing spec section.

pub message: String
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ViolationCode {
    /// `spec_version` is absent or not `"0.1"` (§5.1).
    InvalidSpecVersion,
    /// A URI-shaped field is malformed (§5.3, §5.4).
    InvalidUri,
    /// An OAS DID field is malformed (§5.3).
    InvalidDid,
    /// A `*_env` field is not a valid environment variable name (§5.2
    /// discipline: env names, never values, live in manifests).
    InvalidEnvVarName,
    /// A required string field is empty.
    EmptyField,
    /// A tool identifier is not `<interface>/<action>` shaped (§5.9).
    InvalidToolIdentifier,
    /// A tool identifier does not resolve against the host registry
    /// supplied via [`crate::ValidationContext`] (§5.9).
    UnresolvableToolReference,
    /// A harness with a non-empty tool allowlist declares no capability
    /// grants (§5.4).
    EmptyCapabilityGrants,
    /// `tools.deny_default` is absent or `false` (§5.9, §5.16).
    DenyDefaultViolation,
    /// `tools.approval_required` names a tool absent from `tools.allow`.
    ApprovalOutsideAllowlist,
    /// `verification.gates` is empty for a harness with a non-empty tool
    /// allowlist (§5.10 static approximation of the mutation rule).
    EmptyVerificationGates,
    /// A budget is absent, non-finite, or non-positive (§5.8, §5.16).
    NonFiniteBudget,
    /// `inference.route_policy` is neither `catalog:live` nor a `model:<id>`
    /// pin (§5.8).
    InvalidRoutePolicy,
    /// A meter key is not exactly two dot-separated segments (§5.11, Garden
    /// v4 `validate_meter_key`).
    InvalidMeterKey,
    /// `telemetry.event_prefix` does not match the Cambium v1 grammar
    /// (§5.12).
    InvalidTelemetryPrefix,
    /// `telemetry.event_prefix` requests a privileged prefix
    /// (`policy`/`capability`/`approval`/`billing`) that a manifest must
    /// not claim (§5.12).
    PrivilegedTelemetryPrefix,
    /// A `telemetry.emit` entry is not `<subject...>.<verb>` shaped (§5.12).
    InvalidTelemetryEvent,
    /// `loop.strategy` names no registered strategy (§5.13).
    UnregisteredLoopStrategy,
    /// `spawn.child_budget_fraction_max` is non-finite or outside `(0, 1]`
    /// (§5.13).
    InvalidBudgetFraction,
    /// `identity.max_child_depth` exceeds the runtime maximum derivation
    /// depth (§5.3).
    ChildDepthExceedsMaximum,
    /// `[perception].require_signed_ir` is absent or `false` (§5.14, §5.16).
    UnsignedPerceptionIr,
    /// `[perception].modalities` is empty (§5.14).
    EmptyModalities,
    /// `[perception].modalities` contains duplicates and is therefore not a
    /// set (§5.14).
    DuplicateModalities,
    /// `[perception].max_media_bytes` exceeds the provider ingest cap
    /// (§5.14: a manifest may be stricter, never looser).
    MediaCapExceeded,
    /// A capability grant or tool binding targets the voice surface,
    /// violating voice zero-authority (§5.15, §5.16).
    VoiceAuthorityGrant,
    /// A `[voice]` rule was violated: `constrained_verbalization` not
    /// `true`, or another §5.15 MUST (§5.15, §5.16).
    VoiceRuleViolation,
    /// `[voice].faithfulness_sampling` is non-finite or outside `[0, 1]`
    /// (§5.15).
    InvalidSamplingFraction,
}

#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct ManifestHash([u8; 32]);

pub fn from_bytes(bytes: [u8; 32]) -> Self;

pub fn as_bytes(&self) -> &[u8; 32];

pub fn to_hex(&self) -> String;

pub use error::{SpecError, ValidationError, Violation, ViolationCode};

pub use hash::ManifestHash;

pub use manifest::{
    CapabilitiesTable, ContextScope, ContextTable, EconomicsTable, Gate, HarnessTable,
    IdentityTable, InferenceTable, LoopTable, Manifest, MemoryTable, PerceptionTable, PolicyTable,
    SpawnTable, SubstrateTable, TelemetryStream, TelemetryTable, ToolsTable, VerificationTable,
    VoiceTable,
};

pub use validate::{
    ToolRegistry, ValidatedManifest, ValidationContext, BUILTIN_LOOP_STRATEGIES,
    DEFAULT_MAX_DERIVATION_DEPTH, NOUS_INGEST_CAP_BYTES,
};

pub use vocab::{
    AckPolicy, AsrRouteClass, BargeIn, CacheClass, ContextProvider, DataClass, Enrichment,
    GateKind, Interjection, Isolation, MediaRetention, MemoryType, Modality, Narrowing,
    OnBudgetExhausted, PerceptionProvider, PlaneName, PolicyEngine, RouteDecision, Settlement,
    StreamKind, SubstrateClass, TtsRouteClass, WritePolicy,
};

pub const SPEC_VERSION: &str;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Manifest {
/// Spec revision; must be `"0.1"` for this revision (§5.1).

pub spec_version: String,
/// Harness identity block (§5.3).

pub harness: HarnessTable,
/// Agent identity and lineage block (§5.3).

pub identity: IdentityTable,
/// Capability grants (§5.4).

pub capabilities: CapabilitiesTable,
/// Policy plane binding (§5.5).

pub policy: PolicyTable,
/// Context plane binding (§5.6).

pub context: ContextTable,
/// Optional perception ingress binding (§5.14).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub perception: Option<PerceptionTable>,
/// Memory plane binding (§5.7).

pub memory: MemoryTable,
/// Inference plane binding (§5.8).

pub inference: InferenceTable,
/// Tool policy (§5.9).

pub tools: ToolsTable,
/// Verification gates (§5.10).

pub verification: VerificationTable,
/// Economics plane binding (§5.11).

pub economics: EconomicsTable,
/// Telemetry plane binding (§5.12).

pub telemetry: TelemetryTable,
/// Execution substrate class (§5.13).

pub substrate: SubstrateTable,
/// Loop strategy configuration (§5.13).

pub r#loop: LoopTable,
/// Child-harness spawn policy (§5.13).

pub spawn: SpawnTable,
/// Optional voice surface binding (§5.15).

#[serde(default, skip_serializing_if = "Option::is_none")]
pub voice: Option<VoiceTable>
}

pub fn from_toml(source: &str) -> Result<Self, SpecError>;

pub fn validate(&self) -> Result<ValidatedManifest, SpecError>;

pub fn validate_with(
        &self,
        context: &ValidationContext,
    ) -> Result<ValidatedManifest, SpecError>;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct HarnessTable {
/// Stable harness URI (e.g. `harness://l1fe/one/brownfield-coder`).

pub id: String,
/// Human-readable name.

pub name: String,
/// Harness version (SemVer).

pub version: String,
/// Human-readable description.

pub description: String,
/// Accountable owner: an OAS DID of kind `hmr`, or an entity whose

/// lineage terminates at one (lineage termination is verified at bind

/// time, not by this crate).

pub owner: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IdentityTable {
/// The harness's OAS DID.

pub did: String,
/// Lineage proof reference; must resolve to a chain terminating at

/// `[harness].owner`'s human root (resolution is a bind-time concern).

pub lineage_proof: String,
/// Maximum child derivation depth; must not exceed the runtime's

/// configured maximum (ANVIL default 16).

pub max_child_depth: u32
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct CapabilitiesTable {
/// ACT grant URIs (e.g. `arsenal://act/one-coder/repo-rw`). Must be

/// non-empty for any harness with a non-empty tool allowlist.

pub act_refs: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PolicyTable {
/// Policy engine provider.

pub engine: PolicyEngine,
/// Policy document references (e.g. `lanes://policy/source-code-private`).

pub policy_refs: Vec<String>,
/// Allowed Cambium data classes; a subset of the frozen vocabulary.

pub data_classes_allowed: Vec<DataClass>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ContextTable {
/// Context provider (`lanes` or `static`).

pub provider: ContextProvider,
/// Environment variable holding the provider base URL. Required when

/// `provider = "lanes"`; meaningless for `static`.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub base_url_env: Option<String>,
/// Tenant scope for context requests.

pub scope: ContextScope,
/// Hard cap per packed frame, in tokens. Enforced at pack time.

pub frame_budget_tokens: u64,
/// Answer-vs-model-call routing decision owner.

pub route_decision: RouteDecision,
/// Cache classes the context plane may use.

#[serde(default)]
pub cache_classes: Vec<CacheClass>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ContextScope {
/// Platform identifier.

pub platform_id: String,
/// Organization identifier.

pub organization_id: String,
/// Project identifier.

pub project_id: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PerceptionTable {
/// Perception provider (`nous` in v0.1).

pub provider: PerceptionProvider,
/// Environment variable holding the provider base URL.

pub base_url_env: String,
/// Ingest modalities; a non-empty subset of the Nous ingest surfaces.

pub modalities: Vec<Modality>,
/// Enrichment mode; `deterministic` only in v0.1 (`ml` is reserved for

/// Ring 2 and rejected).

pub enrichment: Enrichment,
/// Fail-closed signed-IR requirement; must be `true` in v0.1.

pub require_signed_ir: bool,
/// Per-artifact media cap in bytes; finite, and never looser than the

/// provider's own ingest cap (Nous ships 64 MiB).

pub max_media_bytes: u64,
/// Route derived IR/embeddings to the `[memory]` mind via the

/// provider's MIND emission path.

pub emit_to_memory: bool,
/// Source-media retention discipline.

pub retention: MediaRetention
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MemoryTable {
/// Memory provider (e.g. `akasha`).

pub provider: String,
/// Mind URI (e.g. `akasha://minds/one-coder`).

pub mind: String,
/// Active memory types; a subset of the Akasha vocabulary.

pub types: Vec<MemoryType>,
/// Write policy governing the memory plane.

pub write_policy: WritePolicy
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InferenceTable {
/// Inference provider (e.g. `foundry`).

pub provider: String,
/// Environment variable holding the provider base URL.

pub base_url_env: String,
/// Route policy: `catalog:live` (recommended) or a `model:<id>` pin

/// that fails closed when the route is no longer offered.

pub route_policy: String,
/// IAM permission required to invoke inference (frozen wire vocabulary).

pub required_permission: String,
/// Entitlement consumed by inference calls.

pub entitlement: String,
/// USD budget cap; present and finite.

pub budget_usd: f64,
/// Token budget cap; present and finite.

pub budget_tokens: u64,
/// Behavior on budget exhaustion (default `halt_and_settle`).

#[serde(default)]
pub on_budget_exhausted: OnBudgetExhausted
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolsTable {
/// Must be present and `true` in v0.1: there is no allow-by-default

/// harness.

pub deny_default: bool,
/// Allowlisted `<interface>/<action>` tool identifiers, resolved against

/// the host's interface/tool registry at validation.

#[serde(default)]
pub allow: Vec<String>,
/// Tools whose every invocation requires a human (or designated

/// approver-harness) decision through the host's approval surface.

#[serde(default)]
pub approval_required: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct VerificationTable {
/// Binds the L1F-8 honesty policy: evidence refs pass through verbatim

/// or are absent — never synthesized.

pub evidence_required: bool,
/// Verification gates; must be non-empty for any harness that can

/// mutate state outside its own memory plane.

pub gates: Vec<Gate>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Gate {
/// Gate kind (`command` in v0.1).

pub kind: GateKind,
/// The command to execute; exit code plus captured output ref are the

/// minimum machine-checkable evidence.

pub run: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct EconomicsTable {
/// Settlement provider (`garden` in v0.1).

pub settlement: Settlement,
/// Meter map; every value must satisfy the Garden v4 two-segment

/// meter-key rule (`<platform>.<meter>`).

pub meters: BTreeMap<String, String>,
/// Idempotency key discipline for replay-safe usage events.

pub idempotency: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TelemetryTable {
/// Telemetry provider (e.g. `cambium`).

pub provider: String,
/// Stream binding; the stream id is derived server-side.

pub stream: TelemetryStream,
/// Event type prefix; must conform to the Cambium v1 grammar

/// (`ai.cambium.<platform>.<subject...>`) and must not request a

/// privileged prefix.

pub event_prefix: String,
/// Event subjects emitted under the prefix (`<subject...>.<verb>`).

pub emit: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TelemetryStream {
/// Stream kind (`run` in v0.1).

pub kind: StreamKind
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SubstrateTable {
/// Substrate class.

pub class: SubstrateClass,
/// Isolation class.

pub isolation: Isolation
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct LoopTable {
/// A registered loop strategy (`react`, `microdag`, `plan_execute`, or

/// one registered with the validation context). Strategies receive

/// plane handles already bound and narrowed; they cannot widen

/// authority.

pub strategy: String,
/// Maximum loop steps.

pub max_steps: u64,
/// Human Interjection Protocol toggle.

pub interjection: Interjection
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct SpawnTable {
/// Whether this harness may spawn children.

pub allowed: bool,
/// Narrowing mode; `strict` in v0.1 (child authority ⊆ parent).

pub narrowing: Narrowing,
/// Maximum fraction of the parent's remaining budget any child may

/// receive; enforced by the economics plane, not by strategy code.

pub child_budget_fraction_max: f64,
/// Planes whose bindings children inherit.

#[serde(default)]
pub inherit: Vec<PlaneName>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct VoiceTable {
/// ASR route class, resolved via the `[inference]` live catalog.

pub asr_route_class: AsrRouteClass,
/// TTS route class, resolved via the `[inference]` live catalog.

pub tts_route_class: TtsRouteClass,
/// Acknowledgment track policy.

pub ack_policy: AckPolicy,
/// Barge-in behavior; `interrupt` is the only v0.1 value.

pub barge_in: BargeIn,
/// Spoken-register paraphrase constraint; must be `true` in v0.1.

pub constrained_verbalization: bool,
/// Fraction of TTS utterances round-tripped and semantically diffed;

/// must lie in `[0, 1]`.

pub faithfulness_sampling: f64,
/// Maximum utterance length in seconds; finite.

pub max_utterance_seconds: u64,
/// Voice meter map; values follow the Garden two-segment rule (§5.11).

pub meters: BTreeMap<String, String>
}

pub const DEFAULT_MAX_DERIVATION_DEPTH: u32;

pub const NOUS_INGEST_CAP_BYTES: u64;

pub const BUILTIN_LOOP_STRATEGIES: [&str; 3];

pub trait ToolRegistry: Send + Sync {
    /// True when `<interface>/<action>` resolves against the host registry.
    fn contains(&self, tool: &str) -> bool;
}

#[derive(Clone)]
pub struct ValidationContext {

}

pub fn new() -> Self;

pub fn with_max_derivation_depth(mut self, max: u32) -> Self;

pub fn with_additional_loop_strategies<I, S>(mut self, strategies: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,;

pub fn with_tool_registry(mut self, registry: Arc<dyn ToolRegistry>) -> Self;

pub fn max_derivation_depth(&self) -> u32;

#[derive(Debug, Clone)]
pub struct ValidatedManifest {

}

pub fn from_toml(source: &str) -> Result<Self, SpecError>;

pub fn from_toml_with(source: &str, context: &ValidationContext) -> Result<Self, SpecError>;

pub fn manifest(&self) -> &Manifest;

pub fn into_manifest(self) -> Manifest;

pub fn canonical_json(&self) -> &str;

pub fn manifest_hash(&self) -> ManifestHash;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PolicyEngine {
    /// Lanes governed information-flow (builtin evaluator or Cedar backend).
    Lanes,
    /// Eden Logos capability/risk evaluation.
    Logos,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum DataClass {
    /// Public information.
    Public,
    /// Tenant-internal information.
    TenantInternal,
    /// Personal data.
    PersonalData,
    /// Credentials and secrets.
    Credentials,
    /// Payment data.
    PaymentData,
    /// Regulated data.
    Regulated,
    /// Customer-secret data.
    CustomerSecret,
    /// Private source code.
    SourceCodePrivate,
    /// Model-prompt-sensitive data.
    ModelPromptSensitive,
    /// Legally privileged material.
    LegalPrivileged,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ContextProvider {
    /// Lanes context plane (cache/local/model routing).
    Lanes,
    /// A pinned, hashed context bundle for air-gapped runs.
    #[serde(rename = "static")]
    Static,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RouteDecision {
    /// Lanes decides answer-vs-model-call routing.
    Lanes,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CacheClass {
    /// Exact-match cache.
    Exact,
    /// Semantic-similarity cache.
    Semantic,
    /// Perceptual cache.
    Perceptual,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PerceptionProvider {
    /// Nous perception ingress.
    Nous,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Modality {
    /// Text ingest.
    Text,
    /// Image ingest.
    Image,
    /// Audio ingest.
    Audio,
    /// Video ingest.
    Video,
    /// OCR ingest.
    Ocr,
    /// Sensor ingest.
    Sensor,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Enrichment {
    /// Deterministic baselines (dHash, STFT, container metadata, OCR
    /// edge-density, sensor statistics).
    Deterministic,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaRetention {
    /// Source bytes evicted from the provider CAS at archive.
    TaskScoped,
    /// Source media custody transferred to Lockers.
    Custodial,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemoryType {
    /// Episodic memory.
    Episodic,
    /// Procedural memory.
    Procedural,
    /// Resource memory.
    Resource,
    /// Knowledge vault.
    KnowledgeVault,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum WritePolicy {
    /// Read-only memory plane.
    None,
    /// Episodic writes during the run; vault consolidation gated on
    /// verification.
    TaskScoped,
    /// Unrestricted writes (development only; hosts may refuse).
    Unrestricted,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum OnBudgetExhausted {
    /// Halt the run and settle usage (default).
    #[default]
    HaltAndSettle,
    /// Surface an approval to extend; extension mints a new budget epoch.
    RequestApproval,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum GateKind {
    /// A shell command whose exit code and captured output are the evidence.
    Command,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Settlement {
    /// Garden settlement.
    Garden,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum StreamKind {
    /// A run stream; the stream id is derived server-side.
    Run,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SubstrateClass {
    /// Flocks agent workload fabric.
    Flocks,
    /// Omega WASM/MicroVM orchestration.
    Omega,
    /// Stations.
    Stations,
    /// Local process (development).
    LocalProcess,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Isolation {
    /// Process isolation.
    Process,
    /// Jail isolation.
    Jail,
    /// MicroVM isolation.
    Microvm,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Narrowing {
    /// Strict narrowing; child authority ⊆ parent authority.
    Strict,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PlaneName {
    /// Policy plane.
    Policy,
    /// Context plane.
    Context,
    /// Perception plane.
    Perception,
    /// Memory plane.
    Memory,
    /// Inference plane.
    Inference,
    /// Tools plane.
    Tools,
    /// Verification plane.
    Verification,
    /// Economics plane.
    Economics,
    /// Telemetry plane.
    Telemetry,
    /// Substrate plane.
    Substrate,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Interjection {
    /// Interjection honored.
    Enabled,
    /// Interjection disabled.
    Disabled,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AckPolicy {
    /// Host/client-side canned audio; never touches inference or economics.
    ClientLocal,
    /// Server-templated acknowledgment.
    Scripted,
    /// A fast catalog route; metered like any inference call.
    Model,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum BargeIn {
    /// Cancel TTS and brain streams on user speech.
    Interrupt,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum AsrRouteClass {
    /// Audio transcription route class.
    AudioTranscription,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TtsRouteClass {
    /// Speech synthesis route class.
    SpeechSynthesis,
}