harness-runtime

use harness_runtime;

pub mod admission;

pub mod budget;

pub mod error;

pub mod planes;

pub mod record;

pub mod spawn;

pub mod spine;

pub mod strategy;

pub mod trace;

pub use admission::{
    AdmissionRequest, AdmittedHarness, AdmittedParts, HarnessAdmission, RunContext,
};

pub use budget::BudgetLedger;

pub use error::{
    AdmissionError, AmplificationRule, AmplificationViolation, BudgetError, PlaneError,
    PlaneUnbound, RuntimeError, SpawnError, TraceContextError,
};

pub use planes::{
    ApprovalDecision, ApprovalRequest, BudgetReservation, BudgetReservationRequest, ContextFrame,
    ContextPlane, ContextRequest, EconomicsPlane, GateRequest, GateResult, HttpPlaneClient,
    IdentityPlane, InferencePlane, InferenceRequest, InferenceResponse, InferenceUsage,
    LineageVerification, LineageVerificationRequest, MediaArtifact, MemoryPlane, MemoryWrite,
    ModelOutput, NoopPlanes, PerceptionPlane, PerceptionRecord, Placement, PlacementRequest, Plane,
    PlaneKind, PlaneRegistry, PolicyDecision, PolicyPlane, PolicyRequest, SettlementRecord,
    SettlementRequest, SubstratePlane, TelemetryEvent, TelemetryPlane, ToolInvocation, ToolOutput,
    ToolsPlane, TranscriptEntry, TranscriptRole, VerificationPlane,
};

pub use record::{
    AdmissionEvidence, HaltReason, PlaneDecision, RunOutcome, RunOutcomeKind, RunRecord,
    SettlementEvidence, UsageTotals, RUN_RECORD_SCHEMA_VERSION,
};

pub use spawn::{spawn_child, SpawnedChild};

pub use spine::{
    MapContextPlane, MapMemoryPlane, MapSpineClient, MapSpineConfig, SpineDispatchRecord,
    SpineDispatchStatus,
};

pub use strategy::{
    DagError, LoopStrategy, MicroDag, MicroDagNode, MicroDagStrategy, ReactLoop, RunPlan,
    StrategyRegistry,
};

pub use trace::{TraceContext, TRACEPARENT_HEADER};

#[derive(Debug, Clone)]
pub struct RunContext {
/// Derivation depth (0 for a root harness; §4.5).

pub depth: u32,
/// Parent run id for spawned children.

pub parent_run_id: Option<String>,
/// The run's trace context, propagated to every provider call.

pub trace: TraceContext
}

pub fn root() -> Self;

pub fn child(
        parent_run_id: impl Into<String>,
        depth: u32,
        parent_trace: &TraceContext,
    ) -> Self;

#[derive(Debug)]
pub struct AdmissionRequest {
/// The sealed manifest (already §5-validated by `harness-spec`).

pub manifest: ValidatedManifest,
/// The plane providers bound for this run.

pub planes: PlaneRegistry,
/// Where this run sits in the delegation tree.

pub run_context: RunContext
}

#[derive(Debug)]
pub struct AdmittedHarness {

}

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

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

pub fn planes(&self) -> &PlaneRegistry;

pub fn budget(&self) -> &BudgetLedger;

pub fn budget_mut(&mut self) -> &mut BudgetLedger;

pub fn evidence(&self) -> &AdmissionEvidence;

pub fn context(&self) -> &RunContext;

pub fn started_at(&self) -> DateTime<Utc>;

pub async fn execute(
        self,
        strategies: &StrategyRegistry,
        task: impl Into<String>,
    ) -> Result<RunRecord, RuntimeError>;

pub fn into_parts(self) -> AdmittedParts;

#[derive(Debug)]
pub struct AdmittedParts {
/// The run id minted at admission.

pub run_id: String,
/// The sealed manifest.

pub manifest: ValidatedManifest,
/// The bound planes.

pub planes: PlaneRegistry,
/// The run budget ledger.

pub budget: BudgetLedger,
/// Admission evidence.

pub evidence: AdmissionEvidence,
/// The run context.

pub context: RunContext,
/// Admission time.

pub started_at: DateTime<Utc>
}

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

}

pub fn new(strategies: StrategyRegistry, context: ValidationContext) -> Self;

pub fn with_defaults() -> Self;

pub fn validation_context(&self) -> &ValidationContext;

pub async fn admit_toml(
        &self,
        source: &str,
        planes: PlaneRegistry,
        run_context: RunContext,
    ) -> Result<AdmittedHarness, AdmissionError>;

pub async fn admit(
        &self,
        request: AdmissionRequest,
    ) -> Result<AdmittedHarness, AdmissionError>;

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

}

pub fn new(granted_usd: f64, granted_tokens: u64, on_exhausted: OnBudgetExhausted) -> Self;

pub fn remaining_usd(&self) -> f64;

pub fn remaining_tokens(&self) -> u64;

pub fn on_exhausted(&self) -> OnBudgetExhausted;

pub fn inference_calls(&self) -> u64;

pub fn is_exhausted(&self) -> bool;

pub fn check_can_spend(&self) -> Result<(), BudgetError>;

pub fn charge(&mut self, usage: &InferenceUsage);

pub fn record_tool_invocation(&mut self);

pub fn carve(&mut self, usd: f64, tokens: u64) -> Result<(), BudgetError>;

pub fn usage(&self) -> UsageTotals;

#[derive(Debug, Error)]
pub enum RuntimeError {
    /// An operation reached a plane that is not bound to a provider.
    #[error(transparent)]
    PlaneUnbound(#[from] PlaneUnbound),

    /// Admission denied the harness (§4.4: denied is a terminal state that
    /// still settles and archives).
    #[error(transparent)]
    Admission(#[from] AdmissionError),

    /// Child spawning violated the spawn policy or the no-amplification
    /// invariant (§4.5).
    #[error(transparent)]
    Spawn(#[from] SpawnError),

    /// The manifest selected a loop strategy the runtime has no driver
    /// for (§5.13: `loop.strategy` must name a registered strategy).
    #[error("loop strategy {strategy:?} has no registered driver in this runtime")]
    StrategyUnavailable {
        /// The strategy named by `loop.strategy`.
        strategy: String,
    },
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[error("plane {plane} is unbound: cannot perform {operation}")]
pub struct PlaneUnbound {
/// The unbound plane.

pub plane: PlaneKind,
/// The operation that was attempted.

pub operation: &'static str
}

pub fn new(plane: PlaneKind, operation: &'static str) -> Self;

#[derive(Debug, Clone, PartialEq, Error)]
pub enum PlaneError {
    /// The plane has no provider bound (noop fail-closed path).
    #[error(transparent)]
    Unbound(#[from] PlaneUnbound),

    /// The provider is unreachable or unavailable. Per §4.6, availability
    /// is never disguised as success: admission denies, execution halts.
    #[error("provider unavailable: {message}")]
    Unavailable {
        /// Human-readable detail.
        message: String,
    },

    /// The provider actively denied the request (e.g. policy miss,
    /// insufficient entitlement).
    #[error("provider denied the request: {message}")]
    Denied {
        /// Human-readable detail.
        message: String,
    },

    /// The provider did not answer within the configured timeout.
    #[error("provider timed out after {timeout_ms} ms: {message}")]
    Timeout {
        /// The configured timeout in milliseconds.
        timeout_ms: u64,
        /// Human-readable detail.
        message: String,
    },

    /// The provider answered with a response that could not be decoded or
    /// fails the plane's contract.
    #[error("invalid provider response: {message}")]
    InvalidResponse {
        /// Human-readable detail.
        message: String,
    },

    /// Any other provider failure, with an optional upstream status code.
    #[error("provider error{status_suffix}: {message}")]
    Provider {
        /// Upstream status code when the provider is HTTP-backed.
        status: Option<u16>,
        /// Human-readable detail.
        message: String,
        /// Pre-rendered status suffix for the Display impl.
        status_suffix: String,
    },
}

pub fn unavailable(message: impl Into<String>) -> Self;

pub fn denied(message: impl Into<String>) -> Self;

pub fn invalid_response(message: impl Into<String>) -> Self;

pub fn provider(status: Option<u16>, message: impl Into<String>) -> Self;

#[derive(Debug, Error)]
pub enum AdmissionError {
    /// The manifest failed §5 validation when admission was invoked with
    /// raw TOML (§5.16: a conforming runtime must refuse to execute a
    /// manifest that fails validation).
    #[error("manifest validation failed: {0}")]
    ValidationFailed(#[from] SpecError),

    /// A plane the manifest requires is not bound to a provider.
    #[error("admission requires the {0}")]
    PlaneUnbound(#[from] PlaneUnbound),

    /// The identity plane rejected the lineage: the harness DID does not
    /// chain to the declared human root, or the provider could not verify
    /// it (§5.3, §4.6).
    #[error("identity verification failed for {did}: {reason}")]
    IdentityRejected {
        /// The harness agent DID.
        did: String,
        /// Why verification failed.
        reason: String,
    },

    /// The policy plane denied the inference permission/entitlement the
    /// manifest requires (§5.8, §4.6: a policy engine miss denies
    /// in-contract).
    #[error("policy denied {permission}: {reason}")]
    PolicyDenied {
        /// The permission that was checked.
        permission: String,
        /// Why the policy plane denied it.
        reason: String,
    },

    /// The economics plane refused or could not complete the budget
    /// reservation (§4.4 step 3: metering failure is denial).
    #[error("budget reservation failed: {0}")]
    ReservationFailed(#[source] PlaneError),

    /// The identity plane verified the lineage but returned no durable
    /// evidence reference (§4.4 step 3: an admission allow without a
    /// durable `evidenceRef` must not exist).
    #[error("identity verification returned no evidence reference")]
    MissingEvidenceRef,

    /// The manifest's `loop.strategy` has no registered driver in this
    /// runtime (§5.13: `loop.strategy` must name a registered strategy).
    #[error("loop strategy {strategy:?} has no registered driver in this runtime")]
    StrategyUnavailable {
        /// The strategy named by `loop.strategy`.
        strategy: String,
    },
}

#[derive(Debug, Error)]
pub enum SpawnError {
    /// The parent manifest declares `spawn.allowed = false`.
    #[error("harness {harness_id:?} does not permit child spawning ([spawn].allowed = false)")]
    SpawningDisabled {
        /// The parent harness id.
        harness_id: String,
    },

    /// The child would sit deeper than the manifest bound or the runtime
    /// maximum derivation depth (§4.5, §5.3).
    #[error("child depth {child_depth} exceeds the maximum derivation depth {max}")]
    DepthLimitExceeded {
        /// The depth the child would occupy.
        child_depth: u32,
        /// The effective maximum (min of manifest bound, runtime bound).
        max: u32,
    },

    /// The child manifest failed §5 validation on its own terms.
    #[error("child manifest invalid: {0}")]
    InvalidChildManifest(#[from] SpecError),

    /// The child would widen authority relative to its parent — the
    /// no-amplification invariant (§4.5).
    #[error("no-amplification violation: {0}")]
    Amplification(#[from] AmplificationViolation),

    /// The child's declared budgets could not be carved out of the
    /// parent's remaining budget (§4.5: sibling budgets must not overlap).
    #[error("budget carve failed: {0}")]
    BudgetCarve(#[from] BudgetError),
}

#[derive(Debug, Clone, PartialEq, Error)]
#[error("[{rule}] {path}: {message}")]
pub struct AmplificationViolation {
/// Machine-checkable rule code.

pub rule: AmplificationRule,
/// Dotted manifest path of the offending child value.

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

pub message: String
}

pub fn new(
        rule: AmplificationRule,
        path: impl Into<String>,
        message: impl Into<String>,
    ) -> Self;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AmplificationRule {
    /// `tools.allow` is not a subset of the parent's (§4.5).
    ToolSuperset,
    /// `capabilities.act_refs` is not a subset of the parent's (§4.5).
    CapabilitySuperset,
    /// `policy.data_classes_allowed` is not a subset of the parent's
    /// (§4.5).
    DataClassSuperset,
    /// A declared budget exceeds `spawn.child_budget_fraction_max` of the
    /// parent's remaining budget (§4.5, §5.13).
    BudgetFractionExceeded,
    /// `memory.types` is not a subset of the parent's (§4.5: effective
    /// authority of any subtree node is bounded by the root's).
    MemoryTypeSuperset,
    /// The parent is text-only (no `[perception]`) but the child declares
    /// one (§4.7: perception is authority, narrowed on spawn).
    PerceptionIntroduced,
    /// `perception.modalities` is not a subset of the parent's (§4.7.5).
    ModalitySuperset,
    /// `perception.max_media_bytes` exceeds the parent's cap (§4.5:
    /// budgets and caps narrow, they never loosen).
    MediaCapLoosened,
    /// `identity.max_child_depth` exceeds the parent's bound (§4.5:
    /// derivation depth respects the manifest bound).
    ChildDepthSuperset,
    /// A parent-required tool approval was dropped by the child for a tool
    /// it keeps (§5.9: dropping a HITL gate widens effective authority).
    ApprovalGateDropped,
}

#[derive(Debug, Clone, PartialEq, Error)]
pub enum BudgetError {
    /// A carve or charge exceeded the remaining budget.
    #[error(
        "insufficient budget: requested {requested_usd} USD / {requested_tokens} tokens, \
         remaining {remaining_usd} USD / {remaining_tokens} tokens"
    )]
    Insufficient {
        /// Requested USD.
        requested_usd: f64,
        /// Requested tokens.
        requested_tokens: u64,
        /// Remaining USD.
        remaining_usd: f64,
        /// Remaining tokens.
        remaining_tokens: u64,
    },

    /// The budget is exhausted; the configured `on_budget_exhausted`
    /// policy now applies (§5.8).
    #[error("budget exhausted ({remaining_usd} USD / {remaining_tokens} tokens remaining)")]
    Exhausted {
        /// Remaining USD (may be zero or negative after the final charge).
        remaining_usd: f64,
        /// Remaining tokens.
        remaining_tokens: u64,
    },
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[error("invalid W3C traceparent value {value:?}: {reason}")]
pub struct TraceContextError {
/// The offending header value.

pub value: String,
/// Why it is invalid.

pub reason: String
}

pub mod admission;

pub mod budget;

pub mod error;

pub mod planes;

pub mod record;

pub mod spawn;

pub mod spine;

pub mod strategy;

pub mod trace;

pub use admission::{
    AdmissionRequest, AdmittedHarness, AdmittedParts, HarnessAdmission, RunContext,
};

pub use budget::BudgetLedger;

pub use error::{
    AdmissionError, AmplificationRule, AmplificationViolation, BudgetError, PlaneError,
    PlaneUnbound, RuntimeError, SpawnError, TraceContextError,
};

pub use planes::{
    ApprovalDecision, ApprovalRequest, BudgetReservation, BudgetReservationRequest, ContextFrame,
    ContextPlane, ContextRequest, EconomicsPlane, GateRequest, GateResult, HttpPlaneClient,
    IdentityPlane, InferencePlane, InferenceRequest, InferenceResponse, InferenceUsage,
    LineageVerification, LineageVerificationRequest, MediaArtifact, MemoryPlane, MemoryWrite,
    ModelOutput, NoopPlanes, PerceptionPlane, PerceptionRecord, Placement, PlacementRequest, Plane,
    PlaneKind, PlaneRegistry, PolicyDecision, PolicyPlane, PolicyRequest, SettlementRecord,
    SettlementRequest, SubstratePlane, TelemetryEvent, TelemetryPlane, ToolInvocation, ToolOutput,
    ToolsPlane, TranscriptEntry, TranscriptRole, VerificationPlane,
};

pub use record::{
    AdmissionEvidence, HaltReason, PlaneDecision, RunOutcome, RunOutcomeKind, RunRecord,
    SettlementEvidence, UsageTotals, RUN_RECORD_SCHEMA_VERSION,
};

pub use spawn::{spawn_child, SpawnedChild};

pub use spine::{
    MapContextPlane, MapMemoryPlane, MapSpineClient, MapSpineConfig, SpineDispatchRecord,
    SpineDispatchStatus,
};

pub use strategy::{
    DagError, LoopStrategy, MicroDag, MicroDagNode, MicroDagStrategy, ReactLoop, RunPlan,
    StrategyRegistry,
};

pub use trace::{TraceContext, TRACEPARENT_HEADER};

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContextRequest {
/// Tenant scope from `[context].scope`.

pub scope: ContextScope,
/// The task text the frame is packed around.

pub task: String,
/// Hard cap for the packed frame, from `[context].frame_budget_tokens`.

pub frame_budget_tokens: u64
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContextFrame {
/// The packed frame content delivered to the inference plane.

pub packed: String,
/// Actual frame size in tokens. The runtime rejects the frame when

/// this exceeds the declared cap (§5.6).

pub tokens: u64
}

#[async_trait]
pub trait ContextPlane: Plane {
    /// Pack the governed context frame for one run.
    async fn pack_frame(&self, request: ContextRequest) -> Result<ContextFrame, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BudgetReservationRequest {
/// The run id this reservation is tied to.

pub run_id: String,
/// BLAKE3 manifest hash (hex) identifying the harness contract.

pub manifest_hash: String,
/// Requested USD cap (`[inference].budget_usd`).

pub budget_usd: f64,
/// Requested token cap (`[inference].budget_tokens`).

pub budget_tokens: u64,
/// Declared meter map (`[economics].meters`, Garden two-segment keys).

pub meters: BTreeMap<String, String>,
/// Idempotency key per `[economics].idempotency` discipline.

pub idempotency_key: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BudgetReservation {
/// Provider-side reservation id, echoed back at settlement.

pub reservation_id: String,
/// Granted USD cap.

pub granted_usd: f64,
/// Granted token cap.

pub granted_tokens: u64,
/// Durable evidence reference for the reservation.

pub evidence_ref: Option<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettlementRequest {
/// The run id.

pub run_id: String,
/// The reservation being settled.

pub reservation_id: String,
/// Terminal usage totals.

pub usage: UsageTotals,
/// Terminal outcome kind.

pub outcome: RunOutcomeKind,
/// Idempotency key (same discipline as the reservation).

pub idempotency_key: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettlementRecord {
/// Provider-side settlement id.

pub settlement_id: String,
/// Settled USD.

pub settled_usd: f64,
/// Settled tokens.

pub settled_tokens: u64,
/// Durable evidence reference for the settlement.

pub evidence_ref: Option<String>
}

#[async_trait]
pub trait EconomicsPlane: Plane {
    /// Reserve the run budget at admission. Failure is denial (§4.4,
    /// §4.6): the harness must not execute.
    async fn reserve_budget(
        &self,
        request: BudgetReservationRequest,
    ) -> Result<BudgetReservation, PlaneError>;

    /// Settle the run exactly once, on every terminal state — verified,
    /// failed, halted, denied all still settle (§4.4).
    async fn settle(&self, request: SettlementRequest) -> Result<SettlementRecord, PlaneError>;
}

#[derive(Debug, Error)]
pub enum HttpClientError {
    /// The base URL is not a valid absolute http(s) URL.
    #[error("invalid plane base URL {url:?}: {reason}")]
    InvalidBaseUrl {
        /// The offending URL.
        url: String,
        /// Why it is invalid.
        reason: String,
    },

    /// The underlying HTTP client could not be built.
    #[error("http client build failed: {0}")]
    BuildFailed(String),
}

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

}

pub fn new(
        plane: PlaneKind,
        base_url: impl Into<String>,
        timeout: Duration,
    ) -> Result<Self, HttpClientError>;

pub fn with_default_header(mut self, name: &str, value: impl Into<String>) -> Self;

pub fn plane(&self) -> PlaneKind;

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

pub fn timeout(&self) -> Duration;

pub fn url(&self, path: &str) -> String;

pub async fn post_json<B, T>(
        &self,
        path: &str,
        body: &B,
        trace: &TraceContext,
    ) -> Result<T, PlaneError>
    where
        B: Serialize + Sync,
        T: DeserializeOwned,;

pub async fn get_json<T>(&self, path: &str, trace: &TraceContext) -> Result<T, PlaneError>
    where
        T: DeserializeOwned,;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LineageVerificationRequest {
/// The harness agent DID (`[identity].did`).

pub did: String,
/// The lineage proof reference (`[identity].lineage_proof`).

pub lineage_proof: String,
/// The accountable owner the chain must terminate at

/// (`[harness].owner`).

pub expected_owner: String,
/// Derivation depth of this run (0 for a root harness).

pub depth: u32
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LineageVerification {
/// True when the chain resolves and terminates at the expected human

/// root.

pub verified: bool,
/// The human root the chain terminates at, when resolved.

pub human_root: Option<String>,
/// Durable evidence reference for the verification (§4.4 step 3: an

/// admission allow without a durable `evidenceRef` must not exist).

pub evidence_ref: Option<String>
}

#[async_trait]
pub trait IdentityPlane: Plane {
    /// Verify that `request.did` chains to `request.expected_owner`'s
    /// human root. Provider unavailability is a typed
    /// [`PlaneError::Unavailable`], never a silent pass (§4.6).
    async fn verify_lineage(
        &self,
        request: LineageVerificationRequest,
    ) -> Result<LineageVerification, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InferenceRequest {
/// The task (or packed context frame) the call is grounded in.

pub task: String,
/// The loop transcript so far (actions and observations, oldest

/// first).

pub transcript: Vec<TranscriptEntry>,
/// Optional output-token cap for this call.

pub max_output_tokens: Option<u64>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TranscriptEntry {
/// Whether this entry is an action the loop took or an observation it

/// received back.

pub role: TranscriptRole,
/// Entry content.

pub content: String
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TranscriptRole {
    /// Something the loop did (a tool call, an answer attempt).
    Action,
    /// What came back (tool output, denials, errors).
    Observation,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ModelOutput {
    /// A text completion (the loop's final answer candidate).
    Completion {
        /// The completion text.
        text: String,
    },
    /// A request to invoke a tool.
    ToolCall {
        /// The `<interface>/<action>` tool identifier.
        tool: String,
        /// Opaque tool input (plane-defined encoding).
        input: String,
    },
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct InferenceUsage {
/// Prompt/input tokens.

pub input_tokens: u64,
/// Completion/output tokens.

pub output_tokens: u64,
/// USD cost of this call.

pub cost_usd: f64
}

pub fn total_tokens(&self) -> u64;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InferenceResponse {
/// Structured model output.

pub output: ModelOutput,
/// Metered usage for the call.

pub usage: InferenceUsage
}

#[async_trait]
pub trait InferencePlane: Plane {
    /// Run one model call through the binding. Routes resolve per
    /// `[inference].route_policy` (§5.8: live catalog by default; pins
    /// fail closed when no longer offered).
    async fn complete(&self, request: InferenceRequest) -> Result<InferenceResponse, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemoryWrite {
/// Which memory type the write targets.

pub kind: MemoryType,
/// Application-defined key.

pub key: String,
/// The content to store.

pub content: String
}

#[async_trait]
pub trait MemoryPlane: Plane {
    /// Write into the bound mind. Returns the provider's evidence
    /// reference for the write, when it produces one.
    async fn write(&self, write: MemoryWrite) -> Result<Option<String>, PlaneError>;

    /// Consolidate the run's task-scoped writes into durable memory.
    /// The runtime invokes this only for `verified` runs (§5.7:
    /// consolidation must not occur for runs that end `failed`, `halted`,
    /// or `denied`). Returns the consolidation evidence reference, when
    /// the provider produces one.
    async fn consolidate(&self, mind: String) -> Result<Option<String>, PlaneError>;
}

pub use context::{ContextFrame, ContextPlane, ContextRequest};

pub use economics::{
    BudgetReservation, BudgetReservationRequest, EconomicsPlane, SettlementRecord,
    SettlementRequest,
};

pub use http::HttpPlaneClient;

pub use identity::{IdentityPlane, LineageVerification, LineageVerificationRequest};

pub use inference::{
    InferencePlane, InferenceRequest, InferenceResponse, InferenceUsage, ModelOutput,
    TranscriptEntry, TranscriptRole,
};

pub use memory::{MemoryPlane, MemoryWrite};

pub use noop::NoopPlanes;

pub use perception::{MediaArtifact, PerceptionPlane, PerceptionRecord};

pub use policy::{PolicyDecision, PolicyPlane, PolicyRequest};

pub use substrate::{Placement, PlacementRequest, SubstratePlane};

pub use telemetry::{TelemetryEvent, TelemetryPlane};

pub use tools::{ApprovalDecision, ApprovalRequest, ToolInvocation, ToolOutput, ToolsPlane};

pub use verification::{GateRequest, GateResult, VerificationPlane};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PlaneKind {
    /// Identity plane (OAS DID lineage).
    Identity,
    /// Policy plane (information-flow / capability authorization).
    Policy,
    /// Context plane (packed governed frames).
    Context,
    /// Memory plane (episodic/procedural/resource/vault).
    Memory,
    /// Inference plane (model calls through the binding).
    Inference,
    /// Tools plane (allowlisted invocation + approvals).
    Tools,
    /// Verification plane (declared gates).
    Verification,
    /// Economics plane (reservation, metering, settlement).
    Economics,
    /// Telemetry plane (event emission).
    Telemetry,
    /// Substrate plane (execution placement).
    Substrate,
    /// Perception ingress (signed, typed SemanticIR — optional binding,
    /// §4.7).
    Perception,
}

pub trait Plane: Send + Sync {
    /// Which plane this adapter serves.
    fn kind(&self) -> PlaneKind;

    /// Stable provider identifier for records and logs (e.g. `foundry`,
    /// `lanes`, `noop`).
    fn provider_id(&self) -> &str;

    /// True when a real provider is bound. Noop adapters return false.
    fn is_bound(&self) -> bool ;
}

#[derive(Clone, Default)]
pub struct PlaneRegistry {

}

pub fn new() -> Self;

pub fn noop_filled() -> Self;

pub fn with_identity(mut self, plane: Arc<dyn IdentityPlane>) -> Self;

pub fn with_policy(mut self, plane: Arc<dyn PolicyPlane>) -> Self;

pub fn with_context(mut self, plane: Arc<dyn ContextPlane>) -> Self;

pub fn with_memory(mut self, plane: Arc<dyn MemoryPlane>) -> Self;

pub fn with_inference(mut self, plane: Arc<dyn InferencePlane>) -> Self;

pub fn with_tools(mut self, plane: Arc<dyn ToolsPlane>) -> Self;

pub fn with_verification(mut self, plane: Arc<dyn VerificationPlane>) -> Self;

pub fn with_economics(mut self, plane: Arc<dyn EconomicsPlane>) -> Self;

pub fn with_telemetry(mut self, plane: Arc<dyn TelemetryPlane>) -> Self;

pub fn with_substrate(mut self, plane: Arc<dyn SubstratePlane>) -> Self;

pub fn with_perception(mut self, plane: Arc<dyn PerceptionPlane>) -> Self;

pub fn bound_identity(&self) -> Result<&Arc<dyn IdentityPlane>, PlaneUnbound>;

pub fn bound_policy(&self) -> Result<&Arc<dyn PolicyPlane>, PlaneUnbound>;

pub fn bound_context(&self) -> Result<&Arc<dyn ContextPlane>, PlaneUnbound>;

pub fn bound_memory(&self) -> Result<&Arc<dyn MemoryPlane>, PlaneUnbound>;

pub fn bound_inference(&self) -> Result<&Arc<dyn InferencePlane>, PlaneUnbound>;

pub fn bound_tools(&self) -> Result<&Arc<dyn ToolsPlane>, PlaneUnbound>;

pub fn bound_verification(&self) -> Result<&Arc<dyn VerificationPlane>, PlaneUnbound>;

pub fn bound_economics(&self) -> Result<&Arc<dyn EconomicsPlane>, PlaneUnbound>;

pub fn bound_telemetry(&self) -> Result<&Arc<dyn TelemetryPlane>, PlaneUnbound>;

pub fn bound_substrate(&self) -> Result<&Arc<dyn SubstratePlane>, PlaneUnbound>;

pub fn bound_perception(&self) -> Result<&Arc<dyn PerceptionPlane>, PlaneUnbound>;

pub struct NoopPlanes;

pub fn registry() -> PlaneRegistry;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct MediaArtifact {
/// Declared modality; must be within `[perception].modalities`.

pub modality: Modality,
/// Raw source bytes (bounded by `[perception].max_media_bytes`).

pub bytes: Vec<u8>,
/// MIME media type hint.

pub media_type: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PerceptionRecord {
/// Provider perception id; downstream consumers reference this, never

/// the raw bytes.

pub perception_id: String,
/// True when the IR is signed per the provider's signing model

/// (`require_signed_ir = true` makes unsigned records inadmissible).

pub signed: bool,
/// Content-addressed reference to the typed SemanticIR.

pub ir_ref: String,
/// Modalities actually perceived.

pub modalities: Vec<Modality>
}

#[async_trait]
pub trait PerceptionPlane: Plane {
    /// Ingest one media artifact, yielding a signed, typed record.
    /// §4.7.3: fail-closed — unsigned, unresolvable, or unverifiable
    /// artifacts are rejected, never delivered best-effort.
    async fn ingest(&self, artifact: MediaArtifact) -> Result<PerceptionRecord, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PolicyRequest {
/// The harness agent DID requesting the action.

pub subject_did: String,
/// The permission being checked (`[inference].required_permission`).

pub permission: String,
/// The entitlement consumed (`[inference].entitlement`).

pub entitlement: String,
/// Policy document references from `[policy].policy_refs`.

pub policy_refs: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PolicyDecision {
/// True when the action is permitted.

pub allowed: bool,
/// Why the decision was made (denials MUST carry a reason).

pub reason: String
}

#[async_trait]
pub trait PolicyPlane: Plane {
    /// Authorize the requested permission/entitlement for the subject.
    async fn authorize(&self, request: PolicyRequest) -> Result<PolicyDecision, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PlacementRequest {
/// The run id.

pub run_id: String,
/// Substrate class (`[substrate].class`).

pub class: SubstrateClass,
/// Isolation class (`[substrate].isolation`).

pub isolation: Isolation
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Placement {
/// Provider-side placement id.

pub placement_id: String,
/// Durable evidence reference for the placement, when produced.

pub evidence_ref: Option<String>
}

#[async_trait]
pub trait SubstratePlane: Plane {
    /// Prepare the execution placement for a run.
    async fn prepare(&self, request: PlacementRequest) -> Result<Placement, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TelemetryEvent {
/// Full event type (`<event_prefix>.<declared-subject>`).

pub event_type: String,
/// Event subject (the run id).

pub subject: String,
/// Event payload.

pub data: serde_json::Value,
/// Emission time.

pub time: DateTime<Utc>
}

#[async_trait]
pub trait TelemetryPlane: Plane {
    /// Emit one event. Returns the provider's event receipt reference,
    /// when it produces one.
    async fn emit(&self, event: TelemetryEvent) -> Result<Option<String>, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolInvocation {
/// The run id the invocation belongs to.

pub run_id: String,
/// The `<interface>/<action>` tool identifier.

pub tool: String,
/// Opaque tool input (plane-defined encoding).

pub input: String,
/// Capability grants offered for authorization

/// (`[capabilities].act_refs`).

pub act_refs: Vec<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ToolOutput {
/// The tool's result content.

pub content: String,
/// Provider evidence reference for the invocation, when produced.

pub evidence_ref: Option<String>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApprovalRequest {
/// The run id.

pub run_id: String,
/// The tool awaiting approval.

pub tool: String,
/// The input awaiting approval.

pub input: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "decision", rename_all = "snake_case")]
pub enum ApprovalDecision {
    /// Approved; the invocation may proceed.
    Approved {
        /// Who approved (human principal or approver-harness DID).
        approver: String,
    },
    /// Denied; the loop receives the denial as an observation.
    Denied {
        /// Why the invocation was denied.
        reason: String,
    },
}

#[async_trait]
pub trait ToolsPlane: Plane {
    /// Invoke an allowlisted tool against a covering capability grant.
    async fn invoke(&self, invocation: ToolInvocation) -> Result<ToolOutput, PlaneError>;

    /// Request approval for a gated invocation. Called only for tools in
    /// `[tools].approval_required`; the runtime records the decision
    /// either way (§5.9).
    async fn request_approval(
        &self,
        request: ApprovalRequest,
    ) -> Result<ApprovalDecision, PlaneError>;
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GateRequest {
/// The run id.

pub run_id: String,
/// The gate as declared in `[verification].gates`.

pub gate: Gate
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GateResult {
/// The gate that was attempted.

pub gate: Gate,
/// Whether the gate actually executed. `passed` is meaningless —

/// and MUST be ignored — when this is false.

pub executed: bool,
/// Whether the executed gate passed.

pub passed: bool,
/// Exit code for command gates, when executed.

pub exit_code: Option<i32>,
/// Provider evidence reference, passed through verbatim or absent —

/// never synthesized (§5.10).

pub evidence_ref: Option<String>,
/// Human-readable detail (captured output summary, error).

pub detail: String
}

pub fn counts_as_pass(&self) -> bool;

#[async_trait]
pub trait VerificationPlane: Plane {
    /// Execute one declared gate and return its machine-checkable result.
    async fn run_gate(&self, request: GateRequest) -> Result<GateResult, PlaneError>;
}

pub const RUN_RECORD_SCHEMA_VERSION: &str;

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct UsageTotals {
/// Total input tokens across all inference calls.

pub input_tokens: u64,
/// Total output tokens across all inference calls.

pub output_tokens: u64,
/// `input_tokens + output_tokens`.

pub total_tokens: u64,
/// Total USD charged.

pub cost_usd: f64,
/// Number of inference calls made.

pub inference_calls: u64,
/// Number of tool invocations executed.

pub tool_invocations: u64
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RunOutcomeKind {
    /// All declared gates executed and passed.
    Verified,
    /// Execution finished but a gate failed, or a gate could not run.
    Failed,
    /// The run stopped early (budget, step limit, plane failure).
    Halted,
    /// Admission refused the run.
    Denied,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "reason", rename_all = "snake_case")]
pub enum HaltReason {
    /// The inference budget was exhausted (§5.8 `halt_and_settle`).
    BudgetExhausted,
    /// The budget was exhausted and the manifest's policy is
    /// `request_approval` (§5.8): an extension approval was requested and
    /// the run halted pending it — extension mints a new budget epoch, it
    /// never edits the exhausted one.
    BudgetExhaustedApprovalRequested,
    /// `[loop].max_steps` was reached without a final answer.
    StepLimitExceeded,
    /// A plane call failed in-run (§4.4: any failure lands in a terminal
    /// state with settlement — never silent continuation).
    PlaneFailure {
        /// The plane that failed.
        plane: PlaneKind,
        /// What happened.
        detail: String,
    },
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "snake_case")]
pub enum RunOutcome {
    /// All declared gates executed and passed.
    Verified {
        /// The final answer, when the loop produced one.
        answer: Option<String>,
    },
    /// Execution finished but verification failed (§4.6: `failed` is
    /// terminal with evidence; still settles).
    Failed {
        /// Why the run failed.
        reason: String,
    },
    /// The run halted before completion.
    Halted {
        /// Why it halted.
        cause: HaltReason,
    },
    /// Admission denied the run (§4.4: denied still settles and archives).
    Denied {
        /// Why admission denied the run.
        reason: String,
    },
}

pub fn kind(&self) -> RunOutcomeKind;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PlaneDecision {
/// The plane that made the decision.

pub plane: PlaneKind,
/// The operation decided (e.g. `tool.invoke`, `inference.complete`).

pub operation: String,
/// Whether the operation was allowed to proceed.

pub allowed: bool,
/// Why / what happened (tool id, denial reason, budget state).

pub detail: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct AdmissionEvidence {
/// The durable admission evidence reference.

pub evidence_ref: String,
/// The identity plane's lineage verification evidence, when produced.

pub lineage_evidence_ref: Option<String>,
/// The economics plane's reservation id.

pub reservation_id: String,
/// The reservation's evidence reference, when produced.

pub reservation_evidence_ref: Option<String>,
/// Granted USD budget.

pub granted_usd: f64,
/// Granted token budget.

pub granted_tokens: u64
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SettlementEvidence {
/// The provider's settlement id.

pub settlement_id: String,
/// Settled USD.

pub settled_usd: f64,
/// Settled tokens.

pub settled_tokens: u64,
/// The settlement evidence reference, when produced.

pub evidence_ref: Option<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RunRecord {
/// Schema version ([`RUN_RECORD_SCHEMA_VERSION`]).

pub schema_version: String,
/// The run id minted at admission.

pub run_id: String,
/// BLAKE3 manifest hash (hex) identifying the harness contract.

pub manifest_hash: String,
/// Parent run id for spawned children (§4.5).

pub parent_run_id: Option<String>,
/// Derivation depth of this run (0 for a root harness).

pub depth: u32,
/// The harness id (`[harness].id`).

pub harness_id: String,
/// The agent DID (`[identity].did`).

pub agent_did: String,
/// The loop strategy that executed (`[loop].strategy`).

pub loop_strategy: String,
/// Admission evidence.

pub admission: AdmissionEvidence,
/// Ordered plane decisions.

pub decisions: Vec<PlaneDecision>,
/// Declared gate results, in manifest order.

pub gate_results: Vec<GateResult>,
/// Terminal usage totals.

pub usage: UsageTotals,
/// Terminal outcome.

pub outcome: RunOutcome,
/// Settlement evidence; present on every terminal state (§4.4: all

/// still settle). Absent only when settlement itself failed — which is

/// itself recorded in `telemetry_failures`.

pub settlement: Option<SettlementEvidence>,
/// Telemetry/consolidation failures observed during the run. Recording

/// them here keeps observability honest without silently dropping

/// events or rewriting the terminal outcome.

pub telemetry_failures: Vec<String>,
/// The run's W3C trace id (32 hex chars) propagated to providers.

pub trace_id: String,
/// When the run started (admission time).

pub started_at: DateTime<Utc>,
/// When the run reached its terminal state.

pub ended_at: DateTime<Utc>
}

#[derive(Debug)]
pub struct SpawnedChild {

}

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

pub fn depth(&self) -> u32;

pub fn carved_usd(&self) -> f64;

pub fn carved_tokens(&self) -> u64;

pub fn inherited_planes(&self) -> &[PlaneName];

pub fn spawn_child(
    parent: &mut AdmittedHarness,
    child_source: &str,
    context: &ValidationContext,
) -> Result<SpawnedChild, SpawnError>;

pub const MAP_BASE_URL_ENV: &str;

pub const MAP_AUTH_TYPE_ENV: &str;

pub const MAP_TENANT_ID_ENV: &str;

pub const MAP_AGENT_DID_ENV: &str;

pub const MAP_SCOPES_ENV: &str;

pub const MAP_TIMEOUT_MS_ENV: &str;

pub const MAP_MAX_RETRIES_ENV: &str;

pub const MAP_BEARER_TOKEN_ENV: &str;

pub const MIM_VERSION: &str;

pub const DEFAULT_MODULE_VERSION: &str;

pub const DEFAULT_TIMEOUT: Duration;

pub const DEFAULT_MAX_RETRIES: u32;

pub const RETRY_BACKOFF: Duration;

#[derive(Clone, Debug)]
pub struct MapSpineConfig {
/// MAP daemon base URL (no trailing slash).

pub base_url: String,
/// `x-l1fe-auth-type` header value.

pub auth_type: String,
/// `x-l1fe-tenant-id` header value; omitted when unset.

pub tenant_id: Option<String>,
/// Sender DID (`x-l1fe-agent-did` + envelope sender).

pub agent_did: String,
/// Scopes sent on every dispatch.

pub scopes: Vec<String>,
/// Per-attempt HTTP timeout.

pub timeout: Duration,
/// Retries after the first attempt.

pub max_retries: u32,
/// Protocol module version requested on dispatch.

pub module_version: String,
/// Optional bearer token for daemons in local development auth mode

/// (`MAP_BEARER_TOKEN`). Wire-only; never logged or recorded.

pub bearer_token: Option<String>
}

pub fn from_env() -> Option<Self>;

pub fn for_base_url(base_url: impl Into<String>) -> Self;

#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum SpineDispatchStatus {
    /// The spine answered 2xx with a contract-shaped body.
    Ok,
    /// The spine answered a non-success status (a real answer, believed).
    RemoteStatus,
    /// The dispatch never reached a MAP answer after retries.
    Transport,
    /// A 2xx body broke the response contract.
    InvalidResponse,
}

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct SpineDispatchRecord {
/// Protocol dispatched to (e.g. `MIND`).

pub protocol: String,
/// Operation dispatched (e.g. `store_memory`).

pub operation: String,
/// The HTTP path the envelope was projected onto.

pub endpoint: String,
/// Local correlation id (the request envelope's id).

pub correlation_id: String,
/// The daemon's `requestId`, when it returned one.

pub remote_request_id: Option<String>,
/// The W3C `traceparent` sent on the wire.

pub traceparent: String,
/// Attempts made (1 + retries).

pub attempts: u32,
/// Terminal outcome of the dispatch.

pub status: SpineDispatchStatus,
/// Upstream HTTP status, when the spine answered.

pub http_status: Option<u16>
}

#[derive(Debug, Clone)]
pub struct SpineDispatch {
/// The protocol module's response payload, passed through verbatim.

pub output: Value,
/// The exact MAP envelope message sent (`{ header, payload }`,

/// mirroring the `map.json` schema) — the auditable request record,

/// kept for evidence bundles the way ONE's client keeps

/// `request_envelope`.

pub request_envelope: Value,
/// The audit record for this dispatch (also appended to the client's

/// dispatch log).

pub record: SpineDispatchRecord
}

#[derive(Clone)]
pub struct MapSpineClient {

}

pub fn new(config: MapSpineConfig) -> Result<Self, PlaneError>;

pub fn from_env() -> Option<Self>;

pub fn is_configured() -> bool;

pub fn config(&self) -> &MapSpineConfig;

pub fn dispatch_log(&self) -> Vec<SpineDispatchRecord>;

pub async fn health_check(&self) -> bool;

#[instrument(skip(self, input))]
pub async fn invoke(
        &self,
        protocol: &str,
        operation: &str,
        input: Value,
    ) -> Result<SpineDispatch, PlaneError>;

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RecallHit {
/// The memory's id.

pub memory_id: String,
/// The memory's content (possibly capped at [`RECALL_CONTENT_CAP`]).

pub content: String
}

#[derive(Clone)]
pub struct MapContextPlane {

}

pub fn new(client: MapSpineClient, recall_scope: impl Into<String>) -> Self;

pub fn with_recall_limit(mut self, limit: usize) -> Self;

pub fn with_marc_decomposition(mut self) -> Self;

pub fn client(&self) -> &MapSpineClient;

#[derive(Clone)]
pub struct MapMemoryPlane {

}

pub fn new(client: MapSpineClient, mind: impl Into<String>) -> Self;

pub fn client(&self) -> &MapSpineClient;

pub use client::{
    MapSpineClient, MapSpineConfig, SpineDispatchRecord, SpineDispatchStatus, MAP_AUTH_TYPE_ENV,
    MAP_BASE_URL_ENV,
};

pub use context::{MapContextPlane, RecallHit};

pub use memory::MapMemoryPlane;

pub use payloads::{
    MarcReasoningTask, MarcTaskResult, MindMemoryMetadata, MindMemoryObject, MindMemoryQuery,
    MindQueryResult, MindStorageResult, MindSymbolicFilter,
};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindMemoryObject {
/// MIND protocol version the object conforms to.

pub mind_version: String,
/// UUID identifying the memory.

pub memory_id: String,
/// Core textual content.

pub content: String,
/// Provenance chain entries (opaque to the runtime).

#[serde(default)]
pub provenance_chain: Vec<Value>,
/// Access control rules (opaque to the runtime).

#[serde(default)]
pub access_control_list: Vec<Value>,
/// Annotations (opaque to the runtime).

#[serde(default)]
pub annotations: Vec<Value>,
/// Triggers (opaque to the runtime).

#[serde(default)]
pub triggers: Vec<Value>,
/// Object metadata (timestamp, source DID, tags).

pub metadata: MindMemoryMetadata
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindMemoryMetadata {
/// RFC 3339 timestamp of the write.

pub timestamp: String,
/// DID of the agent the memory is attributed to.

pub source_agent_did: String,
/// Free-form tags.

#[serde(default)]
pub tags: Vec<String>,
/// Ontology references.

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

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindSymbolicFilter {
/// Subject pattern.

#[serde(skip_serializing_if = "Option::is_none")]
pub subject: Option<String>,
/// Predicate pattern.

#[serde(skip_serializing_if = "Option::is_none")]
pub predicate: Option<String>,
/// Object pattern.

#[serde(skip_serializing_if = "Option::is_none")]
pub object: Option<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindMemoryQuery {
/// Caller-minted query id.

pub query_id: String,
/// Symbolic triple filter.

#[serde(skip_serializing_if = "Option::is_none")]
pub symbolic_filter: Option<MindSymbolicFilter>,
/// DID of the agent requesting recall (the spine tenant principal).

pub requesting_agent_did: String,
/// Result cap.

#[serde(skip_serializing_if = "Option::is_none")]
pub limit: Option<usize>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindStorageResult {
/// The stored memory's id.

pub memory_id: String,
/// Store timestamp (provider-rendered).

pub stored_at: String,
/// Backend that stored the object (`LOCAL` | `AKASHA`).

pub backend: String,
/// Stored version.

pub version: u64
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct MindQueryResult {
/// Echo of the query id.

pub query_id: String,
/// The recalled memory objects.

pub results: Vec<MindMemoryObject>,
/// Provider-measured execution time.

pub execution_time_ms: u64,
/// Provider message (may be empty).

pub message: String
}

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct MarcReasoningTask {
/// Caller-minted task id.

pub task_id: String,
/// Reasoning type (`"deductive"` for the context-plane projection).

pub reasoning_type: String,
/// Reasoning mode; the spine projection is always Monolithic.

pub mode: Value,
/// Premise statements. MARC's deductive engine rejects an empty

/// premise list (`InsufficientPremises`) — callers must supply at

/// least one real premise (recalled memory contents or the task

/// text); a fabricated premise would poison the trace.

pub premises: Vec<String>,
/// The query the engine evaluates.

pub query: String,
/// Optional context string.

#[serde(skip_serializing_if = "Option::is_none")]
pub context: Option<String>,
/// Engine parameters (provenance markers ride here).

pub engine_params: Value
}

pub fn deductive(
        task_id: impl Into<String>,
        premises: Vec<String>,
        query: impl Into<String>,
        context: Option<String>,
    ) -> Self;

#[derive(Debug, Clone, PartialEq, Deserialize)]
pub struct MarcTaskResult {
/// Echo of the task id.

pub task_id: String,
/// The engine's result value.

pub result: Value,
/// Engine-reported confidence in `[0, 1]`.

pub confidence: f64,
/// The reasoning trace (steps, totals, timing).

pub reasoning_trace: Value,
/// Synthesis details, when the mode produced them.

#[serde(default)]
pub synthesis_details: Option<Value>,
/// Issues raised by the engine.

#[serde(default)]
pub issues: Vec<Value>
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
pub enum DagError {
    /// Two nodes share an id.
    #[error("duplicate node id {0:?}")]
    DuplicateNode(String),
    /// A `depends_on` edge names a node that does not exist.
    #[error("node {node:?} depends on unknown node {dependency:?}")]
    UnknownDependency {
        /// The node carrying the edge.
        node: String,
        /// The missing dependency.
        dependency: String,
    },
    /// The graph contains a dependency cycle.
    #[error("dependency cycle involving {0:?}")]
    Cycle(Vec<String>),
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MicroDagNode {
/// Unique step id.

pub id: String,
/// Ids of steps that must complete before this one starts.

pub depends_on: Vec<String>
}

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

}

pub fn new(nodes: Vec<MicroDagNode>) -> Result<Self, DagError>;

pub fn nodes(&self) -> &[MicroDagNode];

pub fn layers(&self) -> Result<Vec<Vec<String>>, DagError>;

pub trait MicroDagStrategy: LoopStrategy {
    /// Compile a task and admitted manifest into an executable MicroDAG.
    fn compile(&self, task: &str) -> Result<MicroDag, DagError>;
}