behavior_contracts/

guard.rs

//! guard — Portability Guard (`assert_portable`).
//!
//! DSL-agnostic IR portability invariant: a portable IR must not contain
//! non-serializable values. In Rust the runtime works over `serde_json::Value`
//! (already JSON-serializable) plus the native [`crate::value::Value`], so the
//! only structurally non-portable case is a non-finite float (NaN/±Inf) which
//! cannot be represented in JSON. `assert_portable` walks a value and rejects it.

use crate::expr::FORBIDDEN_OBJECT_KEY;
use crate::value::Value;
use serde_json::Value as J;

#[derive(Debug, Clone)]
pub struct PortabilityError {
    pub path: String,
    pub message: String,
}

impl std::fmt::Display for PortabilityError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Portability Guard at {}: {}", self.path, self.message)
    }
}
impl std::error::Error for PortabilityError {}

/// Assert that a runtime [`Value`] is portable (JSON-serializable). The only
/// non-portable scalar in the Rust value model is a non-finite float.
pub fn assert_portable(value: &Value) -> Result<(), PortabilityError> {
    assert_portable_at(value, "$")
}

fn assert_portable_at(value: &Value, path: &str) -> Result<(), PortabilityError> {
    match value {
        Value::Float(f) if !f.is_finite() => Err(PortabilityError {
            path: path.to_string(),
            message: format!("non-finite float {f} cannot be placed in portable IR"),
        }),
        Value::Arr(a) => {
            for (i, v) in a.iter().enumerate() {
                assert_portable_at(v, &format!("{path}[{i}]"))?;
            }
            Ok(())
        }
        Value::Obj(o) => {
            for (k, v) in o {
                assert_portable_at(v, &format!("{path}.{k}"))?;
            }
            Ok(())
        }
        _ => Ok(()),
    }
}

/// The closed set of Expression-IR operators allowed in a portable IR (expression-ir.md §3).
pub const PORTABLE_EXPR_OPERATORS: &[&str] = &[
    "int", "float", "ref", "refOpt", "obj", "arr", "add", "sub", "mul", "neg", "div", "mod",
    "concat", "eq", "ne", "lt", "le", "gt", "ge", "and", "or", "not", "coalesce", "cond", "len",
];

fn perr<T>(path: &str, message: impl Into<String>) -> Result<T, PortabilityError> {
    Err(PortabilityError {
        path: path.to_string(),
        message: message.into(),
    })
}

/// The closed set of scalar types in the portable type notation
/// (scp-ir-architecture.md §5.2, bc#44 B0). Compound types are the single-key
/// objects `{opt|arr|map|obj: ...}`.
pub const PORTABLE_SCALAR_TYPES: &[&str] = &["string", "int", "float", "bool", "null"];

/// The generic opaque-value literal (bc#156): the declared type of a driver boundary's generic bound
/// value (`WireValue`). Not a concrete scalar, but in the type notation it appears as the leaf string
/// `"value"` (`{arr:"value"}` = a list of bound values), accepted with the same strength as a scalar
/// (it is a DECLARED opaque type, not an `"any"` escape hatch). Same as the TS guard's
/// `PORTABLE_VALUE_TYPE`.
pub const PORTABLE_VALUE_TYPE: &str = "value";

/// The compound type constructors of the portable type notation (same closed set as the TS guard's
/// `PORTABLE_COMPOUND_KINDS`).
pub const PORTABLE_COMPOUND_KINDS: &[&str] = &["opt", "arr", "map", "obj"];

/// Does the portable type carry the opaque wire value `"value"` ANYWHERE (recursive)? The COUNTERPART
/// of [`wire_passthrough_out_type_ok`]: an output type that contains `value` without being the legal
/// passthrough shape (nested in a record field / map value / nested array) has no de-box contract.
/// Same rule as the TS `portableTypeHasValue` (behavior.ts).
pub fn portable_type_has_value(t: &J) -> bool {
    if t.as_str() == Some(PORTABLE_VALUE_TYPE) {
        return true;
    }
    let Some(o) = t.as_object() else { return false };
    for k in ["opt", "arr", "map"] {
        if let Some(v) = o.get(k) {
            return portable_type_has_value(v);
        }
    }
    match o.get("obj").and_then(|f| f.as_object()) {
        Some(fields) => fields.values().any(portable_type_has_value),
        None => false,
    }
}

/// Is an output-passthrough node's `outType` the legal opaque shape (`value` / `{arr:"value"}`)?
/// Passthrough only covers "the whole output" and "the DIRECT element of an output array" — a `value`
/// anywhere else has no de-box contract. Same rule as the TS `wirePassthroughOutTypeOk` (behavior.ts).
/// Whether the declared type carries an opaque position (= the passthrough flag is meaningful, #221).
/// De-box is DECLARED-TYPE driven, so `value` may sit at any position; there is no shape whitelist.
pub fn wire_passthrough_out_type_ok(out_type: Option<&J>) -> bool {
    out_type.is_some_and(portable_type_has_value)
}

/// Validate a portable type-notation node (§5.2) with the same fail-closed
/// strength as the Expression IR guard. Closed set: a scalar-type string
/// ([`PORTABLE_SCALAR_TYPES`], no `"any"` escape hatch); `{opt: T}` / `{arr: T}`
/// (single-key object, value a type `T`); `{obj: {field: T, ...}}` (single-key
/// object, value a field->type map with the `__proto__` own key forbidden).
fn assert_portable_type_notation(node: &J, path: &str) -> Result<(), PortabilityError> {
    match node {
        J::String(s) => {
            if !PORTABLE_SCALAR_TYPES.contains(&s.as_str()) && s != PORTABLE_VALUE_TYPE {
                return perr(path, format!("unknown scalar type '{s}' (fail-closed)"));
            }
            Ok(())
        }
        J::Object(o) => {
            // #192: obj のみ optional な `name`（宣言型名）を許す。opt/arr はきっかり 1 キー（既存語彙は不変）。
            let kind = PORTABLE_COMPOUND_KINDS
                .iter()
                .find(|k| o.contains_key(**k))
                .copied();
            let kind = match kind {
                Some(k) if k == "obj" || o.len() == 1 => k,
                _ => {
                    return perr(
                        path,
                        format!(
                            "compound type must be a single-key object (opt|arr|map|obj; obj may carry an optional 'name'), got {} keys (fail-closed)",
                            o.len()
                        ),
                    );
                }
            };
            let arg = o.get(kind).unwrap();
            match kind {
                "opt" | "arr" | "map" => assert_portable_type_notation(arg, &format!("{path}.{kind}")),
                "obj" => {
                    for k in o.keys() {
                        if k != "obj" && k != "name" {
                            return perr(
                                path,
                                format!("{{obj}} type allows only 'obj' and optional 'name', got '{k}' (fail-closed)"),
                            );
                        }
                    }
                    if let Some(name_v) = o.get("name") {
                        let ok = name_v.as_str().is_some_and(|s| {
                            let mut cs = s.chars();
                            matches!(cs.next(), Some(c) if c == '_' || c.is_ascii_alphabetic())
                                && cs.all(|c| c == '_' || c.is_ascii_alphanumeric())
                        });
                        if !ok {
                            return perr(
                                &format!("{path}.name"),
                                "obj type 'name' must be a non-empty identifier (fail-closed)".to_string(),
                            );
                        }
                    }
                    let Some(fields) = arg.as_object() else {
                        return perr(
                            &format!("{path}.obj"),
                            "{obj: ...} type expects a field->type object (fail-closed)".to_string(),
                        );
                    };
                    for (k, v) in fields {
                        if k == FORBIDDEN_OBJECT_KEY {
                            return perr(
                                &format!("{path}.obj"),
                                format!("object type key \"{FORBIDDEN_OBJECT_KEY}\" is forbidden (fail-closed)"),
                            );
                        }
                        assert_portable_type_notation(v, &format!("{path}.obj.{k}"))?;
                    }
                    Ok(())
                }
                other => perr(
                    path,
                    format!("unknown compound type kind '{other}' (opt|arr|map|obj) (fail-closed)"),
                ),
            }
        }
        _ => perr(
            path,
            "type notation must be a scalar-type string or a single-key {opt|arr|map|obj} object (fail-closed)".to_string(),
        ),
    }
}

/// Portability Guard for a component-graph IR (scp-ir-architecture.md §5), operating
/// on the raw `serde_json::Value` IR (P0-2). Enforces, fail-closed:
///   1. `component` (componentRef / map) is a string catalog reference only.
///   2. every Expression-IR node in ports / output / map.over / cond uses only the
///      known operator closed set ([`PORTABLE_EXPR_OPERATORS`]).
///   3. any type annotation (`outType` / `outputType`, bc#44 B0) matches the
///      portable type-notation closed set (§5.2). Annotations are additive: an IR
///      without them validates identically to before B0.
pub fn assert_portable_component_graph(ir: &J) -> Result<(), PortabilityError> {
    assert_portable_cg_at(ir, "$")
}

fn assert_portable_cg_at(ir: &J, path: &str) -> Result<(), PortabilityError> {
    // #173: v2 carries portSchemas. #192: v3 adds optional nominal type names on obj types (additive —
    // absent = anonymous, so v2 IR stays valid). Portable versions are 2 | 3.
    if !matches!(
        ir.get("irVersion").and_then(|v| v.as_i64()),
        Some(2) | Some(3)
    ) {
        return perr(
            &format!("{path}.irVersion"),
            "irVersion must be 2 or 3 (v3 adds optional nominal type names) (fail-closed)",
        );
    }
    let components = ir
        .get("components")
        .and_then(|c| c.as_array())
        .ok_or_else(|| PortabilityError {
            path: format!("{path}.components"),
            message: "IR.components must be an array".into(),
        })?;
    for (ci, c) in components.iter().enumerate() {
        assert_portable_component(c, &format!("{path}.components[{ci}]"))?;
    }
    Ok(())
}

fn assert_portable_component(c: &J, path: &str) -> Result<(), PortabilityError> {
    if !c.get("name").map(|n| n.is_string()).unwrap_or(false) {
        return perr(&format!("{path}.name"), "component.name must be a string");
    }
    let body = c
        .get("body")
        .and_then(|b| b.as_array())
        .ok_or_else(|| PortabilityError {
            path: format!("{path}.body"),
            message: "component.body must be an array".into(),
        })?;
    for (ni, n) in body.iter().enumerate() {
        assert_portable_body_node(n, &format!("{path}.body[{ni}]"))?;
    }
    assert_portable_expr(
        c.get("output").unwrap_or(&J::Null),
        &format!("{path}.output"),
    )?;
    // Portable type notation (bc#44 B0): `outputType` is additive/optional.
    if let Some(ot) = c.get("outputType") {
        assert_portable_type_notation(ot, &format!("{path}.outputType"))?;
        // #221: an output contract MAY carry opaque positions — de-box is declared-type driven, so a
        // `value` in the contract IS the contract ("opaque here; the receiver de-boxes once").
    }
    Ok(())
}

fn assert_portable_body_node(n: &J, path: &str) -> Result<(), PortabilityError> {
    assert_portable_body_node_kind(n, path)?;
    // Portable type notation (bc#44 B0): a body node's `outType` is additive/optional
    // (validated for every node kind).
    if let Some(ot) = n.get("outType") {
        assert_portable_type_notation(ot, &format!("{path}.outType"))?;
    }
    // Output wire passthrough (bc#164, additive/optional): a bool only, and the flag and the output type
    // are EQUIVALENT (#205) — "declared opaque" and "passes through" are two faces of one fact, so both
    // directions are checked: (1) flag => opaque shape, (2) an output type carrying `value` => opaque
    // shape AND flag. Either half alone lets a raw IR through with no de-box contract for the caller.
    let out_type = n.get("outType");
    match n.get("wirePassthrough") {
        Some(J::Bool(_)) | None => {}
        Some(_) => {
            return perr(
                &format!("{path}.wirePassthrough"),
                "'wirePassthrough' must be a boolean",
            );
        }
    }
    let passthrough = n.get("wirePassthrough").and_then(|v| v.as_bool()) == Some(true);
    if passthrough && !wire_passthrough_out_type_ok(out_type) {
        return perr(
            &format!("{path}.outType"),
            "an output-passthrough node (wirePassthrough:true) must declare outType 'value' or {arr:\"value\"} (the opaque-wire shape) (fail-closed)",
        );
    }
    // A pure-expression map (#222) CONSTRUCTS its value — it never crosses the wire, so this rule does not
    // apply: a `value` position in its declared type is D4b's INPUT-side opaque (the downstream port boxes
    // it once), not an output without a de-box contract.
    let constructs_value = n
        .get("map")
        .is_some_and(|m| m.get("component").is_none() && m.get("transform").is_some());
    if !constructs_value && out_type.is_some_and(portable_type_has_value) && !passthrough {
        return perr(
            &format!("{path}.outType"),
            "an output type carrying the opaque wire value must BE the passthrough shape ('value' or {arr:\"value\"}) and the node must declare wirePassthrough:true — a nested/unflagged opaque output gives the caller no de-box contract (strict-typing-and-debox.md §D4b, fail-closed)",
        );
    }
    Ok(())
}

fn assert_portable_body_node_kind(n: &J, path: &str) -> Result<(), PortabilityError> {
    if let Some(m) = n.get("map") {
        // The element body has two EXCLUSIVE forms: a Component call (`component` + `ports`) or a pure
        // element expression (`transform`, #222). Iteration belongs to the SCP structural layer, so the
        // Expression IR carries no iteration operator (expression-ir.md §3).
        let is_transform = m.get("transform").is_some();
        if is_transform && (m.get("component").is_some() || m.get("ports").is_some()) {
            return perr(
                &format!("{path}.map.transform"),
                "'transform' (a pure element expression) and 'component'/'ports' (a Component call) are exclusive",
            );
        }
        if is_transform {
            assert_portable_expr(
                m.get("transform").unwrap(),
                &format!("{path}.map.transform"),
            )?;
            for k in [
                "into",
                "batched",
                "elementPolicy",
                "policy",
                "portSchemas",
                "leafSymbol",
            ] {
                if m.get(k).is_some() {
                    return perr(
                        &format!("{path}.map.{k}"),
                        "this key has no meaning on a pure-expression map — no Component is called, so there is no per-element outcome",
                    );
                }
            }
        } else {
            require_string_component(m.get("component"), &format!("{path}.map.component"))?;
            assert_portable_ports(m.get("ports"), &format!("{path}.map.ports"))?;
        }
        assert_portable_expr(
            m.get("over").unwrap_or(&J::Null),
            &format!("{path}.map.over"),
        )?;
        // v2 vocabulary: `when` is an Expression IR node (unknown operators are
        // rejected fail-closed); `into` must be a string key; `batched` a bool.
        if let Some(w) = m.get("when") {
            assert_portable_expr(w, &format!("{path}.map.when"))?;
        }
        if let Some(into) = m.get("into") {
            if !into.is_string() {
                return perr(&format!("{path}.map.into"), "'into' must be a string key");
            }
        }
        if let Some(b) = m.get("batched") {
            if !b.is_boolean() {
                return perr(
                    &format!("{path}.map.batched"),
                    "'batched' must be a boolean",
                );
            }
        }
        // Element Error Policy Kind (scp-error.md): closed set error|skip. `skip` needs a per-element
        // Failure, so a batched map (one outcome for the whole batch) rejects it.
        if let Some(ep) = m.get("elementPolicy") {
            let eps = ep.as_str();
            if eps != Some("error") && eps != Some("skip") {
                return perr(
                    &format!("{path}.map.elementPolicy"),
                    "'elementPolicy' must be \"error\" or \"skip\"",
                );
            }
            if eps == Some("skip") && m.get("batched").and_then(|b| b.as_bool()) == Some(true) {
                return perr(
                    &format!("{path}.map.elementPolicy"),
                    "'elementPolicy' \"skip\" needs a per-element Failure, but a batched map takes ONE outcome for the whole batch",
                );
            }
        }
        // A pure-expression map has no ports, hence no port type contract (#222).
        if is_transform {
            Ok(())
        } else {
            assert_port_schemas_present(m, &format!("{path}.map")) // #173
        }
    } else if let Some(fo) = n.get("fanout") {
        // fanout (the behaviorVersion 3 first-class node kind — same rules as the TS guard): `over` is an
        // Expression IR node, `component` a catalog name, `ports` Expression IR nodes; `as`/`dedupeKey` are
        // non-empty strings, `drop` is "dangling"|"none", `implicitSource` a string or absent, and
        // `relationKind` is fixed to "connection".
        require_string_component(fo.get("component"), &format!("{path}.fanout.component"))?;
        assert_portable_expr(
            fo.get("over").unwrap_or(&J::Null),
            &format!("{path}.fanout.over"),
        )?;
        assert_portable_ports(fo.get("ports"), &format!("{path}.fanout.ports"))?;
        for (field, label) in [("as", "an element-binding"), ("dedupeKey", "a dedupe key")] {
            match fo.get(field).and_then(|v| v.as_str()) {
                Some(sv) if !sv.is_empty() => {}
                _ => {
                    return perr(
                        &format!("{path}.fanout.{field}"),
                        format!("fanout '{field}' must be a non-empty {label} string"),
                    );
                }
            }
        }
        match fo.get("drop").and_then(|v| v.as_str()) {
            Some("dangling") | Some("none") => {}
            _ => {
                return perr(
                    &format!("{path}.fanout.drop"),
                    "fanout 'drop' must be \"dangling\" or \"none\" (fail-closed)",
                );
            }
        }
        if let Some(is) = fo.get("implicitSource") {
            if !is.is_string() {
                return perr(
                    &format!("{path}.fanout.implicitSource"),
                    "fanout 'implicitSource' must be a string or absent",
                );
            }
        }
        if fo.get("relationKind").and_then(|v| v.as_str()) != Some("connection") {
            return perr(
                &format!("{path}.fanout.relationKind"),
                "fanout 'relationKind' must be \"connection\" (fail-closed)",
            );
        }
        assert_port_schemas_present(fo, &format!("{path}.fanout")) // #173
    } else if let Some(co) = n.get("cond") {
        assert_portable_expr(co.get("if").unwrap_or(&J::Null), &format!("{path}.cond.if"))?;
        assert_portable_expr(
            co.get("then").unwrap_or(&J::Null),
            &format!("{path}.cond.then"),
        )?;
        assert_portable_expr(
            co.get("else").unwrap_or(&J::Null),
            &format!("{path}.cond.else"),
        )
    } else if n.get("component").is_some() {
        require_string_component(n.get("component"), &format!("{path}.component"))?;
        assert_portable_ports(n.get("ports"), &format!("{path}.ports"))?;
        assert_port_schemas_present(n, path)
    } else {
        perr(
            path,
            "unknown body node kind (not componentRef/map/cond/fanout)",
        )
    }
}

/// #173: irVersion 2 carries the per-node port type contract. The guard requires the field's
/// PRESENCE (an object) on the port-bearing node kinds for cross-language parity (the TS guard
/// additionally parses its structure, since only TS codegen consumes it). Missing / non-object
/// portSchemas is a malformed v2 IR → fail-closed.
fn assert_port_schemas_present(holder: &J, path: &str) -> Result<(), PortabilityError> {
    match holder.get("portSchemas") {
        Some(ps) if ps.is_object() => Ok(()),
        _ => perr(
            &format!("{path}.portSchemas"),
            "portSchemas is required (irVersion 2 carries the port type contract) and must be an object",
        ),
    }
}

fn require_string_component(v: Option<&J>, path: &str) -> Result<(), PortabilityError> {
    match v {
        Some(J::String(_)) => Ok(()),
        _ => perr(path, "'component' must be a string catalog reference"),
    }
}

fn assert_portable_ports(ports: Option<&J>, path: &str) -> Result<(), PortabilityError> {
    let obj = ports
        .and_then(|p| p.as_object())
        .ok_or_else(|| PortabilityError {
            path: path.to_string(),
            message: "ports must be an object".into(),
        })?;
    for (k, v) in obj {
        assert_portable_expr(v, &format!("{path}.{k}"))?;
    }
    Ok(())
}

fn assert_portable_expr(node: &J, path: &str) -> Result<(), PortabilityError> {
    match node {
        J::Null | J::Bool(_) | J::Number(_) | J::String(_) => Ok(()),
        J::Array(a) => {
            for (i, e) in a.iter().enumerate() {
                assert_portable_expr(e, &format!("{path}[{i}]"))?;
            }
            Ok(())
        }
        J::Object(o) => {
            if o.len() == 1 {
                let (op, arg) = o.iter().next().unwrap();
                if !PORTABLE_EXPR_OPERATORS.contains(&op.as_str()) {
                    return perr(path, format!("unknown operator '{op}' (fail-closed)"));
                }
                // obj は「任意の data key → 子式」の構築ノード（expression-ir.md §3）。arg の
                // key は operator ではなく data であり、値だけを式として再帰する（単一 data key
                // の obj が未知 operator と誤判定されないように — evaluate の意味論と一致）。
                if op == "obj" {
                    let Some(fields) = arg.as_object() else {
                        return perr(
                            &format!("{path}.obj"),
                            "{obj: ...} expects an object".to_string(),
                        );
                    };
                    for (k, v) in fields {
                        // 静的 fail-closed（defense-in-depth）: own key "__proto__" は evaluator
                        // が実行時に FORBIDDEN_KEY で拒否する（expression-ir.md §2.3/§8）。
                        // guard でも静的に拒否する（言語間発散 / prototype pollution 対策）。
                        if k == FORBIDDEN_OBJECT_KEY {
                            return perr(
                                &format!("{path}.obj"),
                                format!("object key \"{FORBIDDEN_OBJECT_KEY}\" is forbidden (fail-closed)"),
                            );
                        }
                        assert_portable_expr(v, &format!("{path}.obj.{k}"))?;
                    }
                    return Ok(());
                }
                assert_portable_expr(arg, &format!("{path}.{op}"))
            } else {
                for (k, v) in o {
                    assert_portable_expr(v, &format!("{path}.{k}"))?;
                }
                Ok(())
            }
        }
    }
}