clm-kernel 0.0.23

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Layer 0: Identity and keys for quoted specifications (profile `clm.spec.v1`)
//! Canonical Path: kernel/clm_rust_core/src/layer0/spec_identity.rs
//!
//! A specification is data before it is a computation. This module encodes a
//! restricted JSON payload to canonical bytes, derives an identity from those
//! bytes, and derives two keys for a quoted recipe. Every function here is pure.
//! None of them evaluates an operand, resolves a handle or reads a store.
//!
//! The payload profile is deliberately narrow so that three runtimes agree on
//! the bytes. It allows objects with ASCII keys, arrays, strings, booleans, null
//! and integers inside the IEEE-754 safe range. It refuses floats and duplicate
//! keys. A decimal travels as a string. The profile does not claim RFC 8785.

use std::collections::{BTreeMap, BTreeSet};

use serde_json::{json, Map, Number, Value};

use crate::layer0::hash::compute_blake3;
use crate::layer0::spec_profile::{descend, is_safe_integer, Refusable};

pub use crate::layer0::spec_profile::{
    SpecProfileError, SPEC_DOMAIN_TAG, SPEC_HASH_QUALIFIER, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_NESTING_DEPTH,
    MAX_RECIPE_DEPTH, REFUSED_FLOAT, REFUSED_DUPLICATE_KEY, REFUSED_NON_ASCII_KEY, REFUSED_INTEGER_RANGE,
    REFUSED_UNSUPPORTED_TYPE, REFUSED_INVALID_STRING, REFUSED_MALFORMED, REFUSED_ACTION_OPERAND,
    REFUSED_UNRESOLVED_INPUT, REFUSED_UNKNOWN_COMPONENT, OPERAND_REFERENCE, OPERAND_DEFERRED, OPERAND_ACTION,
    KIND_RECIPE, KIND_DEEP_KEY, KIND_SHALLOW_KEY,
};
pub use crate::layer0::spec_scan::decode_payload;
use crate::layer0::spec_scan::FIRST_UNESCAPED_BYTE;

/// An operand that names stored content by its hash.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Reference {
    pub reference: String,
}

/// An operand that is immediate and effectful. A recipe that holds one has no key.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Action {
    pub name: String,
}

/// A quoted unit: a function reference, ordered operands and named operands.
///
/// `rule_refs` lists the hashes of the rules that shaped the unit, in the order
/// they were applied. `decoder_policy` names how the unit's output is read back.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Recipe {
    pub function_ref: String,
    pub args: Vec<Operand>,
    pub kwargs: Vec<(String, Operand)>,
    pub rule_refs: Vec<String>,
    pub decoder_policy: String,
}

/// One input of a recipe. Each operand has exactly one class.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Operand {
    Reference(Reference),
    Deferred(Recipe),
    Action(Action),
}

fn validate_number(number: &Number, path: &str) -> Refusable<()> {
    match number.as_i64() {
        Some(integer) if is_safe_integer(integer) => Ok(()),
        Some(_) => Err(SpecProfileError::new(REFUSED_INTEGER_RANGE, format!("{path} holds {number}"))),
        None if number.is_u64() => Err(SpecProfileError::new(REFUSED_INTEGER_RANGE, format!("{path} holds {number}"))),
        None => Err(SpecProfileError::new(REFUSED_FLOAT, format!("{path} holds a float; write a decimal as a string"))),
    }
}

/// Refuses any value outside the payload profile, in the order the value lists its members.
fn validate(value: &Value, path: &mut String, depth: usize) -> Refusable<()> {
    match value {
        Value::Null | Value::Bool(_) | Value::String(_) => Ok(()),
        Value::Number(number) => validate_number(number, path),
        Value::Array(items) => {
            let depth = descend(depth, MAX_NESTING_DEPTH, path)?;
            let mark = path.len();
            for (index, item) in items.iter().enumerate() {
                path.push_str(&format!("[{index}]"));
                validate(item, path, depth)?;
                path.truncate(mark);
            }
            Ok(())
        }
        Value::Object(members) => {
            let depth = descend(depth, MAX_NESTING_DEPTH, path)?;
            let mark = path.len();
            for (key, item) in members {
                if !key.is_ascii() {
                    return Err(SpecProfileError::new(REFUSED_NON_ASCII_KEY, format!("{path} has the key {key:?}")));
                }
                path.push('.');
                path.push_str(key);
                validate(item, path, depth)?;
                path.truncate(mark);
            }
            Ok(())
        }
    }
}

fn write_string(text: &str, out: &mut Vec<u8>) {
    out.push(b'"');
    for &byte in text.as_bytes() {
        match byte {
            b'"' => out.extend_from_slice(br#"\""#),
            b'\\' => out.extend_from_slice(br"\\"),
            0x08 => out.extend_from_slice(br"\b"),
            0x0C => out.extend_from_slice(br"\f"),
            b'\n' => out.extend_from_slice(br"\n"),
            b'\r' => out.extend_from_slice(br"\r"),
            b'\t' => out.extend_from_slice(br"\t"),
            control if control < FIRST_UNESCAPED_BYTE => out.extend_from_slice(format!("\\u{control:04x}").as_bytes()),
            plain => out.push(plain),
        }
    }
    out.push(b'"');
}

/// Writes a validated value. Keys are ASCII, so byte order is the sort order.
fn write_canonical(value: &Value, out: &mut Vec<u8>) {
    match value {
        Value::Null => out.extend_from_slice(b"null"),
        Value::Bool(true) => out.extend_from_slice(b"true"),
        Value::Bool(false) => out.extend_from_slice(b"false"),
        Value::Number(number) => out.extend_from_slice(number.to_string().as_bytes()),
        Value::String(text) => write_string(text, out),
        Value::Array(items) => {
            out.push(b'[');
            for (index, item) in items.iter().enumerate() {
                if index > 0 {
                    out.push(b',');
                }
                write_canonical(item, out);
            }
            out.push(b']');
        }
        Value::Object(members) => {
            let mut sorted: Vec<(&String, &Value)> = members.iter().collect();
            sorted.sort_by(|left, right| left.0.as_bytes().cmp(right.0.as_bytes()));
            out.push(b'{');
            for (index, (key, item)) in sorted.into_iter().enumerate() {
                if index > 0 {
                    out.push(b',');
                }
                write_string(key, out);
                out.push(b':');
                write_canonical(item, out);
            }
            out.push(b'}');
        }
    }
}

/// Canonical bytes of a payload: sorted keys, no whitespace, UTF-8, minimal escapes.
pub fn encode_payload(payload: &Value) -> Refusable<Vec<u8>> {
    validate(payload, &mut String::from("$"), 0)?;
    let mut out = Vec::new();
    write_canonical(payload, &mut out);
    Ok(out)
}

/// `blake3:<hex>` over the domain tag, a newline and the canonical bytes.
pub fn spec_identity(payload: &Value) -> Refusable<String> {
    let preimage = [SPEC_DOMAIN_TAG.as_bytes(), b"\n", &encode_payload(payload)?].concat();
    Ok(format!("{SPEC_HASH_QUALIFIER}:{}", compute_blake3(&preimage)))
}

/// The one class of an operand.
pub fn operand_class(operand: &Operand) -> &'static str {
    match operand {
        Operand::Reference(_) => OPERAND_REFERENCE,
        Operand::Deferred(_) => OPERAND_DEFERRED,
        Operand::Action(_) => OPERAND_ACTION,
    }
}

fn operand_payload(operand: &Operand, depth: usize) -> Refusable<Value> {
    let (name, value) = match operand {
        Operand::Reference(reference) => ("ref", Value::String(reference.reference.clone())),
        Operand::Deferred(recipe) => ("recipe", recipe_payload_at(recipe, depth)?),
        Operand::Action(action) => ("name", Value::String(action.name.clone())),
    };
    let mut members = Map::new();
    members.insert("class".to_string(), Value::String(operand_class(operand).to_string()));
    members.insert(name.to_string(), value);
    Ok(Value::Object(members))
}

/// The named operands in the order given. Refuses a name that appears twice.
fn named(kwargs: &[(String, Operand)]) -> Refusable<&[(String, Operand)]> {
    let mut seen = BTreeSet::new();
    for (name, _) in kwargs {
        if !seen.insert(name.as_str()) {
            let detail = format!("the named operand {name:?} appears twice");
            return Err(SpecProfileError::new(REFUSED_DUPLICATE_KEY, detail));
        }
    }
    Ok(kwargs)
}

/// The recursive walks below use plain loops and keep `json!` in leaf functions,
/// so one level of nesting costs a small and steady amount of call stack.
fn recipe_payload_at(recipe: &Recipe, depth: usize) -> Refusable<Value> {
    let depth = descend(depth, MAX_RECIPE_DEPTH, "the recipe")?;
    let mut args = Vec::with_capacity(recipe.args.len());
    for operand in &recipe.args {
        args.push(operand_payload(operand, depth)?);
    }
    let mut kwargs = Map::new();
    for (name, operand) in named(&recipe.kwargs)? {
        kwargs.insert(name.clone(), operand_payload(operand, depth)?);
    }
    Ok(unit_payload(recipe, args, kwargs))
}

#[inline(never)]
fn unit_payload(recipe: &Recipe, args: Vec<Value>, kwargs: Map<String, Value>) -> Value {
    json!({
        "args": args,
        "decoder": recipe.decoder_policy,
        "function": recipe.function_ref,
        "kwargs": kwargs,
        "rules": recipe.rule_refs,
    })
}

/// The quoted form of a recipe, as a payload inside the profile.
pub fn recipe_payload(recipe: &Recipe) -> Refusable<Value> {
    recipe_payload_at(recipe, 0)
}

fn incomplete(what: &str) -> SpecProfileError {
    SpecProfileError::new(REFUSED_MALFORMED, format!("the recipe payload is incomplete: {what}"))
}

fn member<'a>(members: &'a Map<String, Value>, name: &str) -> Refusable<&'a Value> {
    members.get(name).ok_or_else(|| incomplete(&format!("no member {name:?}")))
}

fn text_member(members: &Map<String, Value>, name: &str) -> Refusable<String> {
    let text = member(members, name)?.as_str().ok_or_else(|| incomplete(&format!("{name:?} is not a string")))?;
    Ok(text.to_string())
}

fn list_member<'a>(members: &'a Map<String, Value>, name: &str) -> Refusable<&'a Vec<Value>> {
    member(members, name)?.as_array().ok_or_else(|| incomplete(&format!("{name:?} is not a list")))
}

fn operand_from_payload(payload: &Value, depth: usize) -> Refusable<Operand> {
    let members = payload.as_object().ok_or_else(|| incomplete("an operand is not an object"))?;
    match members.get("class").and_then(Value::as_str) {
        Some(OPERAND_REFERENCE) => Ok(Operand::Reference(Reference { reference: text_member(members, "ref")? })),
        Some(OPERAND_DEFERRED) => Ok(Operand::Deferred(recipe_from_payload_at(member(members, "recipe")?, depth)?)),
        Some(OPERAND_ACTION) => Ok(Operand::Action(Action { name: text_member(members, "name")? })),
        _ => {
            let kind = members.get("class").map_or_else(|| "null".to_string(), Value::to_string);
            Err(SpecProfileError::new(REFUSED_UNSUPPORTED_TYPE, format!("unknown operand class {kind}")))
        }
    }
}

fn recipe_from_payload_at(payload: &Value, depth: usize) -> Refusable<Recipe> {
    let depth = descend(depth, MAX_RECIPE_DEPTH, "the recipe payload")?;
    let members = payload.as_object().ok_or_else(|| incomplete("a recipe is not an object"))?;
    let function_ref = text_member(members, "function")?;
    let mut args = Vec::new();
    for item in list_member(members, "args")? {
        args.push(operand_from_payload(item, depth)?);
    }
    let quoted = member(members, "kwargs")?.as_object().ok_or_else(|| incomplete("\"kwargs\" is not an object"))?;
    let mut sorted: Vec<(&String, &Value)> = quoted.iter().collect();
    sorted.sort_by(|left, right| left.0.cmp(right.0));
    let mut kwargs = Vec::with_capacity(sorted.len());
    for (name, item) in sorted {
        kwargs.push((name.clone(), operand_from_payload(item, depth)?));
    }
    let mut rule_refs = Vec::new();
    for rule in list_member(members, "rules")? {
        rule_refs.push(rule.as_str().ok_or_else(|| incomplete("a rule is not a string"))?.to_string());
    }
    let decoder_policy = text_member(members, "decoder")?;
    Ok(Recipe { function_ref, args, kwargs, rule_refs, decoder_policy })
}

/// Rebuilds a recipe from its quoted form. The inverse of `recipe_payload`.
pub fn recipe_from_payload(payload: &Value) -> Refusable<Recipe> {
    recipe_from_payload_at(payload, 0)
}

/// Identity of the quoted recipe itself. It commits to every operand as written.
pub fn recipe_identity(recipe: &Recipe) -> Refusable<String> {
    spec_identity(&json!({ "kind": KIND_RECIPE, "recipe": recipe_payload(recipe)? }))
}

fn operands(recipe: &Recipe) -> impl Iterator<Item = &Operand> {
    recipe.args.iter().chain(recipe.kwargs.iter().map(|(_, operand)| operand))
}

/// False when the recipe, or any recipe it defers to, holds an action operand.
pub fn is_keyable(recipe: &Recipe) -> bool {
    let mut pending = vec![recipe];
    while let Some(unit) = pending.pop() {
        for operand in operands(unit) {
            match operand {
                Operand::Reference(_) => {}
                Operand::Deferred(inner) => pending.push(inner),
                Operand::Action(_) => return false,
            }
        }
    }
    true
}

fn action_has_no_key(action: &Action) -> SpecProfileError {
    SpecProfileError::new(REFUSED_ACTION_OPERAND, format!("the action {:?} has no key", action.name))
}

/// One key over the header of a recipe and one input string for each operand.
fn key_over(kind: &str, recipe: &Recipe, input: impl Fn(&Operand) -> Refusable<String>) -> Refusable<String> {
    let mut args = Vec::with_capacity(recipe.args.len());
    for operand in &recipe.args {
        args.push(input(operand)?);
    }
    let mut kwargs = Map::new();
    for (name, operand) in named(&recipe.kwargs)? {
        kwargs.insert(name.clone(), Value::String(input(operand)?));
    }
    key_identity(kind, recipe, args, kwargs)
}

#[inline(never)]
fn key_identity(kind: &str, recipe: &Recipe, args: Vec<String>, kwargs: Map<String, Value>) -> Refusable<String> {
    let header =
        json!({ "decoder": recipe.decoder_policy, "function": recipe.function_ref, "rules": recipe.rule_refs });
    spec_identity(&json!({ "kind": kind, "header": header, "inputs": { "args": args, "kwargs": kwargs } }))
}

fn deep_key_at(recipe: &Recipe, depth: usize) -> Refusable<String> {
    let depth = descend(depth, MAX_RECIPE_DEPTH, "the recipe")?;
    key_over(KIND_DEEP_KEY, recipe, |operand| match operand {
        Operand::Reference(reference) => Ok(reference.reference.clone()),
        Operand::Deferred(inner) => deep_key_at(inner, depth),
        Operand::Action(action) => Err(action_has_no_key(action)),
    })
}

/// Key over the function, the rules, the decoder policy and the deep keys of the inputs.
///
/// It is computable from the quoted recipe alone, so a lookup under it reads no
/// upstream content. It gives no early cutoff: any upstream change changes it.
pub fn deep_key(recipe: &Recipe) -> Refusable<String> {
    deep_key_at(recipe, 0)
}

/// Key over the same header and the content references of the direct inputs.
///
/// `content_refs` maps the deep key of each direct deferred input to the content
/// reference of its result. The caller supplies it, and this function evaluates
/// nothing. Two upstream changes that yield identical bytes give one shallow key.
pub fn shallow_key(recipe: &Recipe, content_refs: &BTreeMap<String, String>) -> Refusable<String> {
    key_over(KIND_SHALLOW_KEY, recipe, |operand| match operand {
        Operand::Reference(reference) => Ok(reference.reference.clone()),
        Operand::Deferred(inner) => {
            let upstream = deep_key_at(inner, 1)?;
            content_refs.get(&upstream).cloned().ok_or_else(|| {
                let detail = format!("no content reference is known for the input {upstream}");
                SpecProfileError::new(REFUSED_UNRESOLVED_INPUT, detail)
            })
        }
        Operand::Action(action) => Err(action_has_no_key(action)),
    })
}

/// Named operands for the components a unit reads, out of a composite value.
///
/// A composite value is a mapping of component names to operands. A unit that
/// reads two of five components names only those two, so a change to any other
/// component leaves both of its keys unchanged.
pub fn select_components<'a>(
    components: &BTreeMap<String, Operand>,
    reads: impl IntoIterator<Item = &'a str>,
) -> Refusable<Vec<(String, Operand)>> {
    let wanted: BTreeSet<&str> = reads.into_iter().collect();
    wanted
        .into_iter()
        .map(|name| match components.get(name) {
            Some(operand) => Ok((name.to_string(), operand.clone())),
            None => {
                let detail = format!("the composite value has no component {name:?}");
                Err(SpecProfileError::new(REFUSED_UNKNOWN_COMPONENT, detail))
            }
        })
        .collect()
}