openlatch-client 0.5.4

//! The evaluator's own interface types — plan 02 §2a, §2d, §2f.
//!
//! Three of these (`Event`, `Decision`, `SessionState`) are **not** in the wire
//! schemas: they are the boundary between the caller and the engine, not
//! something that crosses the repo boundary, so they are hand-written here while
//! every wire type comes from [`crate::generated::types`] (the committed typify
//! output). `Verdict` in particular is frozen to four values in schemas 2.0 and
//! is used from there — never redefined.
//!
//! # The serialisation rule that outranks taste
//!
//! **A field the conformance corpus shows as `null` serialises as `null`.** There
//! is no blanket `skip_serializing_if` anywhere in this file, and adding one is a
//! corpus failure, not a style improvement: `schemas/conformance/*.jsonl` is
//! compared field by field with no stripping step, which is the whole reason
//! provenance (`engine_version`, `bundle_digest`) rides the response envelope
//! instead of sitting inside [`Decision`].
//!
//! Field order matches the corpus rows so a hand-diff of one line reads
//! straight down.

use serde::{Deserialize, Serialize};

use crate::generated::types::{Dimension, EffectVerb, Lever, PolicyMode, TargetClass, Verdict};

/// The composed mode that actually enforces.
pub const MODE_ENFORCE: &str = "enforce";
/// The composed mode that only records — a monitor artifact never joins.
pub const MODE_MONITOR: &str = "monitor";

// ── The Event ────────────────────────────────────────────────────────

/// One action, as the evaluator sees it — PRD §Atom language and the Event model.
///
/// Deliberately **tolerant**: no `deny_unknown_fields`, every field defaulted.
/// The deployed client is routinely older than the platform, and a row carrying
/// a key this build does not know must evaluate, not fail.
///
/// `now_ms` is not a field here. It is an argument to
/// [`evaluate`](super::evaluate), injected by the caller, because a clock read
/// inside the engine makes every replay of the same row non-reproducible.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct Event {
    /// `HookEvent`: `pre_tool_use`, `post_tool_use`, `post_tool_batch`,
    /// `message_display`, `session_start`, `stop`. An open string — an event
    /// type the engine does not evaluate contributes nothing and is not an error.
    #[serde(default)]
    pub event_type: String,
    /// The `subject` session state is keyed by, upstream of this function.
    #[serde(default)]
    pub session_id: String,
    /// The harness's id for this tool call.
    #[serde(default)]
    pub tool_use_id: String,
    /// `mcp__<server>__<tool>` for MCP tools.
    #[serde(default)]
    pub tool_name: String,
    /// Verbatim from the harness. Opaque: the engine reads it, never rewrites it.
    #[serde(default)]
    pub tool_input: serde_json::Value,
    /// Post events only; `null` on a `pre_tool_use`.
    #[serde(default)]
    pub tool_result: Option<serde_json::Value>,
    #[serde(default)]
    pub agent: Option<AgentContext>,
    /// Which adapter decided. Held, never read by a leaf — the field vocabulary
    /// is closed and carries no `binding.*` member. Typed as a raw value because
    /// the corpus ships `{kind, mode}` while the PRD's `Binding` is an open
    /// string: the corpus wins, and neither shape is something evaluation reads.
    #[serde(default)]
    pub binding: serde_json::Value,
    /// The host paths the path → `TargetClass` resolver needs, supplied by the
    /// daemon. **With no `env`, the `system_path` and `workspace_file` rows do
    /// not fire and an absolute path no other row places resolves to unknown —
    /// never a guessed `workspace_file`.**
    #[serde(default)]
    pub env: Option<EventEnv>,
    /// Daemon-maintained session facts, for the `session.*` field family.
    #[serde(default)]
    pub session: Option<SessionFacts>,
    /// Post events only (R7). `micro_usd` exists only when a `pricebook` fact
    /// ships — the client never invents money.
    #[serde(default)]
    pub spend_delta: Option<SpendDelta>,
}

/// `agent.*` leaves read this. Every field optional: an adapter that cannot
/// supply one supplies none, and a leaf over an absent field is false.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct AgentContext {
    #[serde(default)]
    pub agent_id: Option<String>,
    #[serde(default)]
    pub agent_row_id: Option<String>,
    #[serde(default)]
    pub agent_type: Option<String>,
    #[serde(default)]
    pub environment: Option<String>,
    #[serde(default)]
    pub function: Option<String>,
    /// From the execution context where the adapter supplies one.
    #[serde(default)]
    pub principal: Option<String>,
}

/// Host paths, declared by the caller. The path classifier reads **these strings
/// only** — it never walks a directory tree, which is guarantee G4.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct EventEnv {
    #[serde(default)]
    pub home: Option<String>,
    #[serde(default)]
    pub cwd: Option<String>,
    #[serde(default)]
    pub path_dirs: Vec<String>,
    #[serde(default)]
    pub additional_dirs: Vec<String>,
}

/// `session.{elapsed_ms,tool_calls,spend_micro_usd,tokens}`.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct SessionFacts {
    #[serde(default)]
    pub elapsed_ms: Option<i64>,
    #[serde(default)]
    pub tool_calls: Option<i64>,
    #[serde(default)]
    pub spend_micro_usd: Option<i64>,
    #[serde(default)]
    pub tokens: Option<i64>,
}

/// What the last call cost, integer only, read by `ADD_SAT` on a post event.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct SpendDelta {
    #[serde(default)]
    pub tokens: Option<i64>,
    #[serde(default)]
    pub micro_usd: Option<i64>,
}

// ── The Decision ─────────────────────────────────────────────────────

/// What the engine answers — PRD §Atom language, and the corpus's `expected.decision`.
///
/// The PRD's prose names fourteen fields; the corpus carries eighteen. The four
/// it adds — `unknown`, `anomalies`, `ground_key`, `warnings` — are real and the
/// corpus is the authority on the serialised shape.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Decision {
    pub verdict: Verdict,
    pub artifact_id: Option<String>,
    pub atom_id: Option<String>,
    pub policy_public_id: Option<String>,
    pub dimension: Option<Dimension>,
    /// The **composed** mode of the artifact that decided — `monitor` for every
    /// artifact when `enforcement_enabled` is false.
    pub mode: Option<PolicyMode>,
    /// 1, 2 or 3. An integer ordinal, not a vocabulary.
    pub tier: Option<i64>,
    /// Shown to the developer verbatim. `""` when nothing decided.
    pub reason: String,
    /// What a monitor-mode artifact would have said. Monitor never joins.
    pub would_have_verdict: Option<Verdict>,
    /// Sorted, deduplicated fact ids that resolved to ⊥ — the gap made visible
    /// rather than silently resolved.
    pub inconclusive_facts: Vec<String>,
    /// Legacy R10 rewrite payload retained until the coordinated activation
    /// checkpoint. Canonical artifact directives are selected in `optimize`.
    pub rewrite: Option<Rewrite>,
    /// The selected actual/Monitor Optimize directives and bounded shadow evidence.
    pub optimize: Option<OptimizeContext>,
    pub hold: Option<HoldRequest>,
    /// The classifier's confident tuples.
    pub effects: Vec<Effect>,
    /// True when **no** artifact contributed. Distinct from `verdict: allow`,
    /// which an artifact may have decided on purpose.
    pub undecided: bool,
    /// D-15: the classifier's coverage gaps, carried ALONGSIDE `effects`, never
    /// in place of them. One unmapped sibling must not erase a confident tuple.
    pub unknown: Vec<UnknownCommand>,
    /// Where the Tier 2 `ANOMALY` op's codes land.
    pub anomalies: Vec<Anomaly>,
    /// The matched exception's ground key, so the corpus proves client/platform
    /// parity rather than asserting it.
    pub ground_key: Option<String>,
    /// Prose for a human — the D-17 fact-id registry warns here. Printed, never
    /// compared: a second implementation is free to word it differently.
    pub warnings: Vec<String>,
}

impl Default for Decision {
    /// The neutral answer: allow, undecided, nothing decided it.
    fn default() -> Self {
        Self {
            verdict: Verdict::Allow,
            artifact_id: None,
            atom_id: None,
            policy_public_id: None,
            dimension: None,
            mode: None,
            tier: None,
            reason: String::new(),
            would_have_verdict: None,
            inconclusive_facts: Vec::new(),
            rewrite: None,
            optimize: None,
            hold: None,
            effects: Vec::new(),
            undecided: true,
            unknown: Vec::new(),
            anomalies: Vec::new(),
            ground_key: None,
            warnings: Vec::new(),
        }
    }
}

/// One classified effect tuple. An action may carry several; a leaf matches if
/// **any** tuple matches.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Effect {
    pub verb: EffectVerb,
    pub target_class: TargetClass,
    /// `effect.attrs.<name>` reads these — `is_production`, `force`, `branch`,
    /// `program`. Always serialised, `{}` when empty.
    #[serde(default)]
    pub attrs: serde_json::Map<String, serde_json::Value>,
}

/// A simple command the classifier could not place, and under which of the 12
/// `unknown → ASK` shapes (PRD §Client evaluator).
///
/// `reason` is prose and is **not** compared across implementations; the runner
/// compares coverage gaps by `shape`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct UnknownCommand {
    /// 1–12, the shape from the PRD's table.
    pub shape: i64,
    pub reason: String,
    /// The simple command as written, or `""` when there is nothing to quote.
    pub command: String,
}

/// A Tier 2 `ANOMALY` op's output. An anomaly records; it never decides.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Anomaly {
    pub code: String,
    pub artifact_id: Option<String>,
    pub atom_id: Option<String>,
}

/// The single OPTIMIZE rewrite an action may carry (R10).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Rewrite {
    pub lever: Lever,
    pub artifact_id: Option<String>,
    /// Required when `lever` is `steer` — the instruction the model receives.
    pub steer_instruction: Option<String>,
}

/// Privacy-bounded Optimize composition evidence handed to record-v2 stamping.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct OptimizeContext {
    pub actual: Option<OptimizeCandidate>,
    pub monitor: Option<OptimizeCandidate>,
    pub shadowed: Vec<OptimizeCandidate>,
}

/// One selected or shadowed artifact identity. Atom parameters never enter evidence.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct OptimizeCandidate {
    pub artifact_id: Option<String>,
    pub atom_id: Option<String>,
    pub policy_id: Option<String>,
    pub layer_unit_id: Option<String>,
    pub lever: Lever,
    pub reason: String,
}

/// The validated directive retained on a loaded artifact.
#[derive(Debug, Clone, PartialEq)]
pub struct OptimizeDirective {
    pub lever: Lever,
    pub params: OptimizeParams,
}

/// A validated atom-owned parameter projection. Values remain internal and are
/// deliberately absent from [`OptimizeCandidate`].
#[derive(Debug, Clone, PartialEq)]
pub enum OptimizeParams {
    EffortClamp(serde_json::Map<String, serde_json::Value>),
    ContextEdit(serde_json::Map<String, serde_json::Value>),
    PrefixGuard(serde_json::Map<String, serde_json::Value>),
    LoopStop(serde_json::Map<String, serde_json::Value>),
    NarrowOutput(serde_json::Map<String, serde_json::Value>),
    Steer(serde_json::Map<String, serde_json::Value>),
    Substitute(serde_json::Map<String, serde_json::Value>),
}

impl OptimizeParams {
    pub(crate) fn parse(
        lever: &str,
        params: &serde_json::Map<String, serde_json::Value>,
    ) -> Option<Self> {
        match lever {
            "effort_clamp" => {
                validate_effort_clamp(params).then(|| Self::EffortClamp(params.clone()))
            }
            "context_edit" => {
                validate_context_edit(params).then(|| Self::ContextEdit(params.clone()))
            }
            "prefix_guard" => {
                validate_prefix_guard(params).then(|| Self::PrefixGuard(params.clone()))
            }
            "loop_stop" => validate_loop_stop(params).then(|| Self::LoopStop(params.clone())),
            "narrow_output" => {
                validate_narrow_output(params).then(|| Self::NarrowOutput(params.clone()))
            }
            "steer" => validate_steer(params).then(|| Self::Steer(params.clone())),
            "substitute" => validate_substitute(params).then(|| Self::Substitute(params.clone())),
            _ => None,
        }
    }

    pub(crate) fn canonical_value(&self) -> serde_json::Value {
        let params = match self {
            Self::EffortClamp(v)
            | Self::ContextEdit(v)
            | Self::PrefixGuard(v)
            | Self::LoopStop(v)
            | Self::NarrowOutput(v)
            | Self::Steer(v)
            | Self::Substitute(v) => v,
        };
        serde_json::Value::Object(params.clone())
    }
}

fn exact_keys(params: &serde_json::Map<String, serde_json::Value>, keys: &[&str]) -> bool {
    params.len() == keys.len() && keys.iter().all(|key| params.contains_key(*key))
}

fn string_array(value: Option<&serde_json::Value>) -> bool {
    value
        .and_then(serde_json::Value::as_array)
        .is_some_and(|items| items.iter().all(|item| item.as_str().is_some()))
}

fn non_negative_integer(value: Option<&serde_json::Value>) -> bool {
    value
        .and_then(serde_json::Value::as_i64)
        .is_some_and(|n| (0..=9_007_199_254_740_991).contains(&n))
}

fn validate_effort_clamp(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["effort", "quality_floor"])
        && params
            .get("effort")
            .and_then(serde_json::Value::as_str)
            .is_some()
        && params
            .get("quality_floor")
            .and_then(serde_json::Value::as_str)
            .is_some()
}

fn validate_context_edit(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(
        params,
        &["trigger", "keep", "clear_at_least", "exclude_tools"],
    ) && non_negative_integer(params.get("trigger"))
        && non_negative_integer(params.get("keep"))
        && non_negative_integer(params.get("clear_at_least"))
        && string_array(params.get("exclude_tools"))
}

fn validate_prefix_guard(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["pin_ttl"])
        && params
            .get("pin_ttl")
            .is_some_and(|value| value.is_null() || value.as_str().is_some())
}

fn validate_loop_stop(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["n_errors", "n_identical", "exempt_patterns"])
        && non_negative_integer(params.get("n_errors"))
        && non_negative_integer(params.get("n_identical"))
        && string_array(params.get("exempt_patterns"))
}

fn validate_narrow_output(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["allowlist"])
        && params
            .get("allowlist")
            .and_then(serde_json::Value::as_array)
            .is_some_and(|items| {
                items.iter().all(|item| {
                    item.as_object().is_some_and(|entry| {
                        exact_keys(entry, &["command_prefix", "filter"])
                            && entry
                                .get("command_prefix")
                                .and_then(serde_json::Value::as_str)
                                .is_some()
                            && entry
                                .get("filter")
                                .and_then(serde_json::Value::as_str)
                                .is_some()
                    })
                })
            })
}

fn validate_steer(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["steer_instruction", "dedupe_window_s"])
        && params
            .get("steer_instruction")
            .and_then(serde_json::Value::as_str)
            .is_some()
        && non_negative_integer(params.get("dedupe_window_s"))
}

fn validate_substitute(params: &serde_json::Map<String, serde_json::Value>) -> bool {
    exact_keys(params, &["pairs"])
        && params
            .get("pairs")
            .and_then(serde_json::Value::as_array)
            .is_some_and(|items| {
                items.iter().all(|item| {
                    item.as_object().is_some_and(|pair| {
                        exact_keys(pair, &["from", "to"])
                            && pair
                                .get("from")
                                .and_then(serde_json::Value::as_str)
                                .is_some()
                            && pair.get("to").and_then(serde_json::Value::as_str).is_some()
                    })
                })
            })
}

/// Selection-only form retained on a contribution until the join explains it.
#[derive(Debug, Clone, PartialEq)]
pub struct OptimizeCandidateInternal {
    pub evidence: OptimizeCandidate,
    pub params: OptimizeParams,
    pub layer_path: Vec<String>,
}

/// The hold this action would open. **The trigger decision only**: the queue,
/// the deadline and the long poll belong to the daemon, outside this pure
/// function. Every field is optional because the `t3_hold` body's are.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct HoldRequest {
    /// `ask_human` holds for a console answer; `reinforcement` puts the
    /// directive in front of the model and reads its reply.
    pub resolve: Option<String>,
    pub directive_template_id: Option<String>,
    pub max_attempts: Option<i64>,
    pub timeout_s: Option<i64>,
    pub on_timeout: Option<Verdict>,
    pub verdict_on_approve: Option<Verdict>,
    pub verdict_on_reject: Option<Verdict>,
}

// ── Session state ────────────────────────────────────────────────────

/// How much per-session state the bundle's Tier 2 programs need, unioned across
/// every program at **bundle load** — plan 02 §2d.
///
/// The engine never allocates per event: the caller owns the storage and its
/// capacity is computed from this, so the memory bound sits somewhere a reader
/// can see it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct StateLayout {
    /// Saturating counters.
    pub c: usize,
    /// Flag bits.
    pub f: usize,
    /// Timestamp slots.
    pub t: usize,
    /// Saturating amount accumulators (tokens, micro-USD).
    pub a: usize,
    /// Whether any program tracks a run of same-shape actions.
    pub run: bool,
}

/// The Tier 2 register file for one session — plan 02 §2d.
///
/// Field order matches the corpus's `state_out`. A state whose array lengths
/// disagree with the bundle's layout is **malformed, never padded**: two
/// implementations cannot agree about which counter is which if one of them
/// silently invents a slot.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct SessionState {
    #[serde(default)]
    pub c: Vec<i64>,
    #[serde(default)]
    pub f: Vec<bool>,
    #[serde(default)]
    pub t: Vec<i64>,
    #[serde(default)]
    pub a: Vec<i64>,
    #[serde(default)]
    pub run: Option<RunState>,
}

impl SessionState {
    /// The zeroed state for a layout — what an evicted session comes back as.
    pub fn blank(layout: &StateLayout) -> Self {
        Self {
            c: vec![0; layout.c],
            f: vec![false; layout.f],
            t: vec![0; layout.t],
            a: vec![0; layout.a],
            run: layout.run.then(RunState::default),
        }
    }

    /// Whether this state's shape matches `layout`. The caller rejects on false;
    /// nothing in here pads.
    pub fn matches(&self, layout: &StateLayout) -> bool {
        self.c.len() == layout.c
            && self.f.len() == layout.f
            && self.t.len() == layout.t
            && self.a.len() == layout.a
            && self.run.is_some() == layout.run
    }
}

/// A run of same-shape actions. **Action shape** is
/// `sha256(tool_name ‖ first effect tuple ‖ command.program or "")` — argument
/// values are ignored, so `Read a.py` and `Read b.py` share a shape. Distinct
/// from the `loop_stop` lever's "identical", which keys on
/// `(tool, normalised input, result hash)`. Two different identicals; never merge them.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct RunState {
    /// `null` before the first tracked action.
    pub shape: Option<String>,
    pub len: i64,
}

// ── Bundle-load reporting ────────────────────────────────────────────

/// One artifact the two-stage parse did not activate.
///
/// **The engine does not log.** It has no tracing dependency and OL-12xx codes
/// live in `src/core/error.rs`; it returns these and the caller writes one line
/// per item. Without them an authoring UI shows a policy author a green light on
/// a rule that is not loaded.
///
/// The three keys are operational fields in `docs/evaluate-protocol.md`.
/// `reason` is an open string: a consumer never switches exhaustively on it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SkippedItem {
    /// The artifact's `kind`, or `""` when it carried none.
    pub kind: String,
    /// The artifact's `artifact_id`, or `""` when it carried none.
    pub id: String,
    pub reason: String,
}

/// An artifact whose `kind` the evaluator cannot read. Skipped, never fatal.
pub const SKIP_UNKNOWN_KIND: &str = "unknown_kind";
/// An optional Optimize directive failed its lever-specific second-stage parse.
pub const SKIP_INVALID_OPTIMIZE_DIRECTIVE: &str = "invalid_optimize_directive";
/// Incompatible directives occupied one authored layer and mode path.
pub const SKIP_SAME_LAYER_CONFLICT: &str = "same_layer_conflict";
/// The stage-2 per-`kind` body parse failed.
pub const SKIP_BODY_PARSE_ERROR: &str = "body_parse_error";
/// A `regex_lite` pattern `regex-syntax` rejected, or one over the size limit.
pub const SKIP_BAD_PATTERN: &str = "bad_pattern";
/// `min_client_version` above the bundle capability this engine implements.
pub const SKIP_BELOW_FLOOR: &str = "below_floor";
/// A non-integer number anywhere in the body. The bundle carries integers only.
pub const SKIP_FLOAT_PRESENT: &str = "float_present";
/// A feed selector's `field` (`effect_classes.entries[].selectors[]`) is
/// outside the closed D-27 vocabulary (`effect::mcp::validate_selector`).
pub const SKIP_UNKNOWN_FIELD: &str = "unknown_field";
/// A feed selector's `pred` is outside the closed D-27 vocabulary.
pub const SKIP_UNKNOWN_PREDICATE: &str = "unknown_predicate";
/// `SkippedItem.kind` for a dropped `effect_classes.entries[]` item — distinct
/// from an artifact's own `kind` (`t1_predicate_tree`, and so on).
pub const SKIP_KIND_EFFECT_CLASS_ENTRY: &str = "effect_class_entry";

// ── Classification ───────────────────────────────────────────────────

/// What the effect classifier answers — plan 02 §2f, D-15.
///
/// **Not** `Result<Vec<Effect>, Unknown>`. `rm -rf /data/x && $UNKNOWN` yields
/// the confident `delete × data_store` **and** an unknown entry; the result type
/// that erases the first is how one unmapped sibling silently disarmed
/// enforcement in the spike (vault issue #34, amendment 7).
#[derive(Debug, Clone, PartialEq, Default)]
pub struct Classification {
    /// Effects we are confident about. May be non-empty even when `unknown` is.
    ///
    /// The oracle calls this field `tuples` (`tools/zone-eval-ref/effect.py`).
    /// Same contents; the name is noted so a reader adjudicating a disagreement
    /// between the two implementations can line them up.
    pub effects: Vec<Effect>,
    /// Which simple commands we could not classify, and under which shape.
    pub unknown: Vec<UnknownCommand>,
    /// Every simple command of the chain, after wrappers and env runners are
    /// stripped. Source of `command.program`, `command.argv` and
    /// `command.simple[]`.
    pub simple: Vec<SimpleCommand>,
    /// Every path the action names, with the class the resolver gave it. Source
    /// of `path.class` and `path.value`.
    ///
    /// **Not interchangeable with [`Effect::target_class`].** A tuple says
    /// `read × workspace_file`; it does not say *which* path produced it, and
    /// `path.value` has no other home.
    pub paths: Vec<ClassifiedPath>,
    /// Every URL the action names. Source of `url.host`, `url.tld`,
    /// `url.scheme` and `url.boundary`.
    pub urls: Vec<ClassifiedUrl>,
}

/// One simple command of a chain, after wrappers and env runners are stripped.
///
/// `program` and `argv` are what the field vocabulary reads. The other three are
/// what the **classifier** needs to see the `unknown → ASK` shapes, and dropping
/// them would make several of the twelve undetectable:
///
/// - `raw` — shape 1 measures the command's length, and shape 12's quote-escape
///   only exists in the text the AST split apart.
/// - `redirects` — shape 10 asks whether a redirection target has a `~`, a glob
///   or an unresolved variable, and the `cp`/`mv`/`tee` row of the shell table
///   reads `>` and `>>` to emit `write × dst`.
/// - `raw_argv` — `argv` with the quotes still on, element for element. Shapes 3
///   and 10 ask *"was this argument a literal?"*, and unquoting has already
///   thrown that answer away. Reading the operand out of the ORIGINAL token list
///   instead is what breaks behind every wrapper: `env bash -c "$X"` strips one
///   token, the index stops lining up, and the shape disappears — a coverage gap
///   silently turned into a confident `execute × shell`.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize)]
pub struct SimpleCommand {
    pub program: String,
    /// Unquoted, element for element with [`SimpleCommand::raw_argv`].
    pub argv: Vec<String>,
    /// The command as written, before splitting.
    pub raw: String,
    /// `(operator, target)` — `>`, `>>`, `2>`, `<`, `<<`, `<<<` and their targets.
    pub redirects: Vec<(String, String)>,
    /// `argv` with the quotes still on. See the type's own doc comment.
    pub raw_argv: Vec<String>,
}

impl SimpleCommand {
    /// What `command.simple[]` exposes to a leaf: `{program, argv}` and nothing
    /// else.
    ///
    /// The projection lives here, in one place, so the client and the oracle
    /// cannot disagree about what that field member *is* — the oracle's
    /// `SimpleCommand.as_dict()` is the same two keys.
    pub fn as_value(&self) -> serde_json::Value {
        serde_json::json!({ "program": self.program, "argv": self.argv })
    }
}

/// A path the action names, and the class the resolver gave it.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClassifiedPath {
    /// First match wins over the ordered resolver table.
    pub class: TargetClass,
    /// The path as the action declared it — a **declared string**, never the
    /// result of walking the filesystem.
    pub value: String,
}

/// A URL the action names, decomposed into the `url.*` field family.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ClassifiedUrl {
    /// The URL as written.
    pub value: String,
    /// Lowercased, with userinfo and port removed; an IPv6 literal stays
    /// bracketed, as the `url` crate reports it.
    pub host: String,
    /// The **registrable public suffix** from `psl`, so `example.co.uk` yields
    /// `co.uk`. The oracle has no PSL and yields the last label (`uk`) — a known,
    /// documented divergence, which is why `tld_in` corpus rows are written
    /// against single-label TLDs.
    pub tld: String,
    pub scheme: String,
    pub boundary: UrlBoundary,
}

/// Which side of the network boundary a host sits on.
///
/// A closed two-valued classification (PRD §Field vocabulary,
/// `url.boundary: internal|external`), so it is an enum rather than a string: an
/// atom gated on `url.boundary == internal` must not be defeatable by a typo on
/// the producing side.
///
/// **`internal` is arithmetic, not a string prefix.** RFC 1918's `172.16.0.0/12`
/// is `172.16.` through `172.31.` — sixteen blocks. A prefix list gets thirteen
/// of them wrong, and every one of those errors calls an internal host
/// `external`, which is the direction that silently stops an atom matching.
/// `localhost`, `::1`, a bare hostname with no dot, the `.local` / `.internal` /
/// `.lan` / `.home.arpa` / `.localdomain` suffixes, and the `10.` / `127.` /
/// `192.168.` / `169.254.` prefixes are the rest of `internal`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum UrlBoundary {
    Internal,
    External,
}

impl UrlBoundary {
    /// The wire spelling, for a leaf comparing against a literal.
    pub fn as_str(self) -> &'static str {
        match self {
            UrlBoundary::Internal => "internal",
            UrlBoundary::External => "external",
        }
    }
}

// ── Per-artifact contributions ───────────────────────────────────────

/// What one artifact contributed, before exceptions and before the join.
///
/// Shared by `tier1`, `tier2`, `tier3`, `exception` and `join`, which is why it
/// lives here rather than in whichever of them happened to need it first.
#[derive(Debug, Clone, PartialEq)]
pub struct Contribution {
    pub artifact_id: Option<String>,
    pub atom_id: Option<String>,
    pub policy_public_id: Option<String>,
    pub dimension: Option<Dimension>,
    /// The **composed** mode: `monitor` when the artifact says so, and for every
    /// artifact when `enforcement_enabled` is false.
    pub mode: PolicyMode,
    pub tier: Option<i64>,
    pub verdict: Verdict,
    pub reason: String,
    /// Fact ids this artifact resolved to ⊥.
    pub inconclusive: Vec<String>,
    /// Anomaly codes this artifact raised.
    pub anomalies: Vec<String>,
    pub hold: Option<HoldRequest>,
    /// Set by `exception::apply` when a selector matched, so the decision can
    /// report the ground the answer was filed under.
    pub exception_ground_key: Option<String>,
    /// Legacy body projection retained until the coordinated activation checkpoint.
    pub lever: Option<Lever>,
    pub steer_instruction: Option<String>,
    pub optimize: Option<OptimizeCandidateInternal>,
}

impl Contribution {
    /// Whether this contribution enters the join. **Monitor never joins** — it
    /// contributes `would_have_verdict` and an anomaly, and nothing else.
    pub fn is_enforcing(&self) -> bool {
        self.mode.as_str() == MODE_ENFORCE
    }
}

// ── The shared evaluation context ────────────────────────────────────

/// Everything the tiers read about one action, plus the two accumulators they
/// write into.
///
/// It carries no clock and no handle: `now_ms` is a value that arrived in the
/// frame. Facts and the classification are computed once per action and read by
/// every artifact, which is what keeps 2,000 atoms inside the p99 budget.
#[derive(Debug)]
pub struct EvalContext<'a> {
    pub event: &'a Event,
    pub classification: &'a Classification,
    pub facts: &'a super::facts::FactSet,
    /// Injected. Never `SystemTime`.
    pub now_ms: i64,
    /// Fact ids this artifact resolved to ⊥, deduplicated on insert.
    pub inconclusive: Vec<String>,
    /// Prose for a human; never compared across implementations.
    pub warnings: Vec<String>,
}

impl<'a> EvalContext<'a> {
    pub fn new(
        event: &'a Event,
        classification: &'a Classification,
        facts: &'a super::facts::FactSet,
        now_ms: i64,
    ) -> Self {
        Self {
            event,
            classification,
            facts,
            now_ms,
            inconclusive: Vec::new(),
            warnings: Vec::new(),
        }
    }

    /// A context for ONE artifact, so the ⊥ facts it notes are its own.
    ///
    /// The alternative — one shared list, recorded into and sliced back off when
    /// the tree turns out not to need it — is undo-by-slice, and it leaked in
    /// the oracle: deduplication meant a fact one artifact had already noted
    /// went missing from the next artifact's list.
    pub fn fork(&self) -> EvalContext<'a> {
        EvalContext::new(self.event, self.classification, self.facts, self.now_ms)
    }

    /// Record a ⊥ fact. Deduplicated — an atom that reads the same fact twice
    /// reports it once.
    pub fn note_inconclusive(&mut self, fact_id: &str) {
        if !self.inconclusive.iter().any(|f| f == fact_id) {
            self.inconclusive.push(fact_id.to_string());
        }
    }

    /// Record prose for a human. Deduplicated for the same reason.
    pub fn warn(&mut self, message: impl Into<String>) {
        let message = message.into();
        if !self.warnings.contains(&message) {
            self.warnings.push(message);
        }
    }

    /// Fold a forked context's warnings back. Warnings are about the BUNDLE, not
    /// about whether one artifact's tree happened to come out false, so they
    /// come back out of every artifact whatever it contributed.
    pub fn merge_warnings(&mut self, child: &EvalContext<'_>) {
        for warning in &child.warnings {
            self.warn(warning.clone());
        }
    }
}