hecks 2.8.0 → 3.0.0

data/rust/src/kernel/mod.rs

@@ -0,0 +1,133 @@
+//! Hand-written, domain-agnostic floor that every generated per-command function calls into.
+
+pub mod attribute_shapes;
+pub mod cli;
+pub mod dispatch;
+pub mod expr;
+pub mod expression_operators;
+pub mod json;
+pub mod named_query;
+pub mod orchestrate;
+pub mod pattern;
+pub mod query_ordering;
+pub mod vocab;
+// Kept at its old path so existing `refusal_wording::RefusalSite` call sites still resolve.
+pub use vocab::refusal_template as refusal_wording;
+pub mod read_model;
+pub mod query_comparators;
+pub mod reference_lookup;
+pub mod repository;
+pub mod routing;
+
+pub use dispatch::{aggregate_step_site, apply_entity_command, decode_aggregate_arguments, decode_entity_arguments, dispatch, dispatch_entity, enforce_invariants, entity_step_site, ArgumentGates, EnsuresSpec, EntityInvariants, GivenSpec, Hydrate, InvariantSet, InvariantSpec, StepSite, TransitionCheck};
+pub use expr::{interpret, BlockMode, Bound, Comparison, EvalContext, Expr, Field, Fielded, NoFields, Value, WithParent};
+pub use json::Json;
+pub use named_query::{QueryCondition, QueryConditionValue, QueryDef};
+pub use orchestrate::{
+    orchestrate, CompletedCompensation, CrossDomainPolicyRule, DispatchSpec, Handler, PendingCrossDomainReaction, PolicyRule, ProcessManagerDef,
+    SagaInstance, Tables, WithValue, MAX_REACTION_DEPTH, REFUSED,
+};
+pub use reference_lookup::{
+    command_deref, owner_deref, parent_deref, seeded_projections, DerefNode, ProjectedFieldSpec, ReferenceLookup, ReferenceSpec, ReferenceTable,
+    SetProjectedField, WithReferences, DEREFERENCE_DEPTH,
+};
+pub use refusal_wording::RefusalSite;
+pub use repository::{check_reference, check_role_via, filter_entries, holds_role_via, row_json, AggregateScan, InMemoryRepository, Repository};
+pub use routing::{CommandInvocation, RoutingEnvelope};
+
+/// A domain event raised by a successful command dispatch.
+#[derive(Debug, Clone)]
+pub struct Event {
+    pub name: String,
+    pub aggregate: String,
+    pub id: String,
+    /// The dispatching command's arguments as structured JSON.
+    pub payload: json::Json,
+    /// Wall-clock timestamp resolved by the host; the kernel has no clock, to stay deterministic.
+    /// Every event from one top-level step, cascading reactions included, gets the same value.
+    /// `None` until `orchestrate` stamps it, and for callers that never supply one.
+    pub occurred_at: Option<String>,
+    /// Runtime-only saga bookkeeping, never serialized. Stamped by `orchestrate` when a saga leg
+    /// causes the event, so an unrelated saga correlating on another field cannot claim it.
+    pub correlation: Option<std::collections::HashMap<String, String>>,
+}
+
+/// Why a command dispatch was refused; each variant carries the refusal message.
+///
+/// Ruby's `UnknownVerb` has no variant: routing an unknown command name happens before dispatch.
+/// `AbsentArgument` and `UnknownArgument` are raised only at the JSON boundary (`from_json`),
+/// where the input has no static shape; typed args structs make them unconstructible afterwards.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Refusal {
+    GivenNotMet(String),
+    EnsuresNotMet(String),
+    InvariantViolation(String),
+    LifecycleRefused(String),
+    AlreadyExists(String),
+    NotFound(String),
+    TypeMismatch(String),
+    AbsentArgument(String),
+    UnknownArgument(String),
+    Unauthorized(String),
+    Fault(String),
+    /// `corrects` against a record that never emitted the corrected event.
+    NothingToCorrect(String),
+}
+
+impl Refusal {
+    /// The refusal class name, spelled as Ruby raises it; the semantics corpus compares it.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Refusal::GivenNotMet(_) => "GivenNotMet",
+            Refusal::EnsuresNotMet(_) => "EnsuresNotMet",
+            Refusal::InvariantViolation(_) => "InvariantViolation",
+            Refusal::LifecycleRefused(_) => "LifecycleRefused",
+            Refusal::AlreadyExists(_) => "AlreadyExists",
+            Refusal::NotFound(_) => "NotFound",
+            Refusal::TypeMismatch(_) => "TypeMismatch",
+            Refusal::AbsentArgument(_) => "AbsentArgument",
+            Refusal::UnknownArgument(_) => "UnknownArgument",
+            Refusal::Unauthorized(_) => "Unauthorized",
+            Refusal::Fault(_) => "Fault",
+            Refusal::NothingToCorrect(_) => "NothingToCorrect",
+        }
+    }
+}
+
+impl std::fmt::Display for Refusal {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Refusal::GivenNotMet(msg)
+            | Refusal::EnsuresNotMet(msg)
+            | Refusal::InvariantViolation(msg)
+            | Refusal::LifecycleRefused(msg)
+            | Refusal::AlreadyExists(msg)
+            | Refusal::NotFound(msg)
+            | Refusal::TypeMismatch(msg)
+            | Refusal::AbsentArgument(msg)
+            | Refusal::UnknownArgument(msg)
+            | Refusal::Unauthorized(msg)
+            | Refusal::Fault(msg)
+            | Refusal::NothingToCorrect(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+/// The saved record plus the events it raised, or a refusal that leaves state untouched.
+pub type DispatchResult<T> = Result<(T, Vec<Event>), Refusal>;
+
+/// One aggregate record saved by a dispatch, reported so a host can journal per aggregate.
+///
+/// `operation` is always `"save"`: no dispatch path deletes.
+#[derive(Debug, Clone)]
+pub struct MutationRecord {
+    pub aggregate: String,
+    pub id: String,
+    pub operation: &'static str,
+    pub state: Json,
+}
+
+/// Lets `dispatch`/`dispatch_entity`, generic over the record type, call a record's `to_json()`.
+pub trait ToJson {
+    fn to_json(&self) -> Json;
+}

data/rust/src/kernel/named_query.rs

@@ -0,0 +1,219 @@
+//! Interprets declared `query "Name" do ... end` blocks compiled to static `QueryDef` rows.
+//! A query outside the compiled subset has no row and is refused by the string-form step.
+
+use super::refusal_wording::UnauthorizedTenantRequiredArgs;
+use super::{query_comparators::QueryComparator, query_ordering, repository, AggregateScan, Json, Refusal};
+
+/// One declared query, compiled.
+///
+/// `verb` is the qualified "Domain::Aggregate.QueryName"; `aggregate` is the bare
+/// "Domain::Aggregate" that `AggregateScan::scan` expects.
+#[derive(Debug, Clone, Copy)]
+pub struct QueryDef {
+    pub verb: &'static str,
+    pub aggregate: &'static str,
+    pub conditions: &'static [QueryCondition],
+    /// `where` clauses that hop through a reference (`customer/status`), after `conditions`.
+    pub reference_hop_conditions: &'static [super::read_model::ReferenceHopCondition],
+    pub order_by: Option<query_ordering::OrderBy>,
+    pub offset: Option<query_ordering::Offset>,
+    pub limit: Option<query_ordering::Limit>,
+    /// `None` when no `authorize` is declared, or it declares no `tenant:`.
+    pub authorization: Option<TenantAuth>,
+}
+
+/// `authorize policy, tenant: :field`, mirroring `Runtime::TenantScope.apply`.
+///
+/// A missing tenant arg refuses `Unauthorized`; otherwise `field == args[tenant]` is ANDed
+/// onto the query's conditions at codegen time. `tenant_field` is both the field and the arg key.
+#[derive(Debug, Clone, Copy)]
+pub struct TenantAuth {
+    /// The bare declared query name (not the qualified verb), used as `{query}` in the refusal.
+    pub query_name: &'static str,
+    pub tenant_field: &'static str,
+    /// The `authorize` policy, carried but not enforced: Ruby never reads it either, and enforcing
+    /// it here would make Rust refuse queries Ruby answers.
+    pub policy: &'static str,
+}
+
+/// One where clause, compiled; `value` is what a declared query adds over the ad hoc filter.
+#[derive(Debug, Clone, Copy)]
+pub struct QueryCondition {
+    pub field: &'static str,
+    pub comparator: QueryComparator,
+    pub value: QueryConditionValue,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub enum QueryConditionValue {
+    /// A wire string baked in at codegen time. Emitted only for string-shaped fields or the
+    /// `in`/`contains` comparators, which stringify their argument in Ruby too. Never for
+    /// gt/gte/lt/lte.
+    Literal(&'static str),
+    /// A literal for a field proven numeric at codegen time. Resolves to `Json::Num`, never
+    /// `Json::Float`: it is only a comparison operand and is never serialised back out.
+    NumericLiteral(f64),
+    /// A caller-bound attribute name, read from the call's `args`; a missing key reads as
+    /// `Json::Null`, as Ruby's `resolve_query_value` does.
+    Arg(&'static str),
+}
+
+/// Runs a declared query: chained `filter_entries` per condition (keeping id order), then
+/// `query_ordering::apply` for `order_by`/`offset`/`limit`, as Ruby filters then orders.
+pub fn run(store: &impl AggregateScan, def: &QueryDef, args: &Json, caller_role: Option<&str>) -> Result<Vec<(String, Json)>, Refusal> {
+    run_cross_domain(store, def, args, &[], caller_role)
+}
+
+/// `run` with an explicit `cross_domain` search list for `NoneInState` conditions.
+///
+/// `caller_role` is threaded through for future tenant-policy enforcement and is not yet checked.
+pub fn run_cross_domain(
+    store: &impl AggregateScan,
+    def: &QueryDef,
+    args: &Json,
+    cross_domain: &[(&str, &dyn AggregateScan)],
+    _caller_role: Option<&str>,
+) -> Result<Vec<(String, Json)>, Refusal> {
+    if let Some(auth) = &def.authorization {
+        if args.get(auth.tenant_field).is_none() {
+            return Err(Refusal::Unauthorized(
+                UnauthorizedTenantRequiredArgs { query: auth.query_name, field: auth.tenant_field }.render_args(),
+            ));
+        }
+    }
+
+    // Reduced once per condition, as `filter_entries` reduces its operand.
+    let wants: Vec<(&QueryCondition, Json)> = def
+        .conditions
+        .iter()
+        .map(|condition| {
+            let want = match condition.value {
+                QueryConditionValue::Literal(text) => Json::Str(text.to_string()),
+                QueryConditionValue::NumericLiteral(n) => Json::Num(n, None),
+                QueryConditionValue::Arg(name) => args.get(name).cloned().unwrap_or(Json::Null),
+            };
+            (condition, super::query_comparators::comparable(&want))
+        })
+        .collect();
+
+    // Every condition is tested against the borrowed row, so only a row that passes them all is
+    // cloned. ANDing per row keeps what chaining one filter per condition kept.
+    let mut entries: Vec<(String, Json)> = Vec::new();
+    let known = store.scan_each(def.aggregate, &mut |id, record| {
+        let kept = wants
+            .iter()
+            .all(|(c, want)| repository::entry_matches(record, c.field, c.comparator, want, cross_domain));
+        if kept {
+            entries.push((id.to_string(), record.clone()));
+        }
+    });
+    if !known {
+        return Err(Refusal::TypeMismatch(format!("unknown aggregate {:?}", def.aggregate)));
+    }
+    entries.sort_by(|a, b| a.0.cmp(&b.0));
+
+    entries = super::read_model::apply_reference_hops(entries, def.reference_hop_conditions, args, store)?;
+
+    Ok(query_ordering::apply(entries, def.order_by.as_ref(), def.offset.as_ref(), def.limit.as_ref(), args))
+}
+
+/// Finds a query by verb; a linear scan is enough for the small generated `QUERIES` table.
+pub fn find<'a>(table: &'a [QueryDef], verb: &str) -> Option<&'a QueryDef> {
+    table.iter().find(|def| def.verb == verb)
+}
+
+/// A declared entity query (`Domain::Aggregate.Entity.Query`), compiled.
+///
+/// Mirrors `Runtime::QueryInterpreter#entity_rows`: filter each record's `list_field` elements,
+/// order by parent id then identity keys, then apply offset and limit.
+#[derive(Debug, Clone, Copy)]
+pub struct EntityQueryDef {
+    pub verb: &'static str,
+    pub aggregate: &'static str,
+    /// The aggregate's list attribute holding this entity (`withdrawals`).
+    pub list_field: &'static str,
+    /// The key each row names its owning record under (`atm_card`).
+    pub parent_key: &'static str,
+    /// The heads of the entity's `identified_by` paths, in order.
+    pub identity_keys: &'static [&'static str],
+    pub conditions: &'static [QueryCondition],
+    pub order_by: Option<query_ordering::OrderBy>,
+    pub offset: Option<query_ordering::Offset>,
+    pub limit: Option<query_ordering::Limit>,
+}
+
+pub fn find_entity<'a>(table: &'a [EntityQueryDef], verb: &str) -> Option<&'a EntityQueryDef> {
+    table.iter().find(|def| def.verb == verb)
+}
+
+pub fn run_entity(store: &impl AggregateScan, def: &EntityQueryDef, args: &Json) -> Result<Vec<Json>, Refusal> {
+    let records = store
+        .scan(def.aggregate)
+        .ok_or_else(|| Refusal::TypeMismatch(format!("unknown aggregate {:?}", def.aggregate)))?;
+
+    // One entry per element, keyed by parent id, the `(id, record)` shape `filter_entries` takes.
+    let mut entries: Vec<(String, Json)> = Vec::new();
+    for (parent_id, record) in records {
+        if let Some(elements) = record.get(def.list_field).and_then(Json::as_array) {
+            entries.extend(elements.iter().map(|element| (parent_id.clone(), element.clone())));
+        }
+    }
+
+    for condition in def.conditions {
+        let want = match condition.value {
+            QueryConditionValue::Literal(text) => Json::Str(text.to_string()),
+            QueryConditionValue::NumericLiteral(n) => Json::Num(n, None),
+            QueryConditionValue::Arg(name) => args.get(name).cloned().unwrap_or(Json::Null),
+        };
+        entries = repository::filter_entries(entries, condition.field, condition.comparator, &want);
+    }
+
+    // `query_ordering::apply` re-sorts stably by parent id, so identity order survives per parent.
+    entries.sort_by(|(parent_a, a), (parent_b, b)| parent_a.cmp(parent_b).then_with(|| identity_order(a, b, def.identity_keys)));
+    let ordered = query_ordering::apply(entries, def.order_by.as_ref(), def.offset.as_ref(), def.limit.as_ref(), args);
+
+    Ok(ordered.into_iter().map(|(parent_id, element)| row_under_parent(def.parent_key, parent_id, element)).collect())
+}
+
+fn identity_order(a: &Json, b: &Json, keys: &[&str]) -> std::cmp::Ordering {
+    keys.iter()
+        .map(|key| compare_comparable(comparable(a.get(key)), comparable(b.get(key))))
+        .find(|ordering| *ordering != std::cmp::Ordering::Equal)
+        .unwrap_or(std::cmp::Ordering::Equal)
+}
+
+/// A single-field value object reduces to its one value.
+fn comparable(value: Option<&Json>) -> Option<&Json> {
+    match value {
+        Some(Json::Object(fields)) if fields.len() == 1 => comparable(Some(&fields[0].1)),
+        other => other,
+    }
+}
+
+fn compare_comparable(a: Option<&Json>, b: Option<&Json>) -> std::cmp::Ordering {
+    use std::cmp::Ordering;
+    match (a, b) {
+        (Some(Json::Num(x, _)), Some(Json::Num(y, _))) => x.partial_cmp(y).unwrap_or(Ordering::Equal),
+        (Some(Json::Str(x)), Some(Json::Str(y))) => x.cmp(y),
+        (None | Some(Json::Null), None | Some(Json::Null)) => Ordering::Equal,
+        (None | Some(Json::Null), _) => Ordering::Less,
+        (_, None | Some(Json::Null)) => Ordering::Greater,
+        _ => Ordering::Equal,
+    }
+}
+
+/// `{ parent_key => record.id }.merge(element)`: the parent key leads, and an element field of
+/// the same name wins its value.
+fn row_under_parent(parent_key: &str, parent_id: String, element: Json) -> Json {
+    let mut fields = vec![(parent_key.to_string(), Json::Str(parent_id))];
+    if let Json::Object(pairs) = element {
+        for (key, value) in pairs {
+            if key == parent_key {
+                fields[0].1 = value;
+            } else {
+                fields.push((key, value));
+            }
+        }
+    }
+    Json::Object(fields)
+}