hecks 3.0.3 → 3.0.4

data/rust/src/kernel/needs.rs

@@ -0,0 +1,194 @@
+//! Facts a command `needs` (ADR 0081), answered before the argument gates read the arguments.
+//!
+//! The Ruby interpreter fills them in its `decode_arguments` step; here the same fill runs at the
+//! head of `orchestrate`, ahead of `decode_aggregate_arguments`' own `decode_arguments` slot (the
+//! first thing a dispatch does), so no step is added to the vocabulary. A fact is filled only
+//! when the caller left the key out, so a supplied value wins.
+//!
+//! Which commands need what comes from the host's input, not from generated code: the input's
+//! top-level `"needs"` is `{ "Domain::Aggregate.Command": [{"fact": "now", "type": "Integer"}] }`
+//! (see `cli::run`). With no table installed nothing is filled and behavior is unchanged.
+//!
+//! The clock answers the step's `occurred_at` (the host stamps it once per step and journals it,
+//! so a replay answers the same moment) and, with none, the system clock.
+
+use super::Json;
+use std::cell::{Cell, RefCell};
+use std::collections::HashMap;
+
+/// One needed fact of a command: its name and the type of the command's attribute of that name.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Need {
+    pub fact: String,
+    pub attribute_type: String,
+}
+
+thread_local! {
+    static TABLE: RefCell<HashMap<String, Vec<Need>>> = RefCell::new(HashMap::new());
+    static FIXED_CLOCK: Cell<Option<i64>> = const { Cell::new(None) };
+}
+
+/// Installs the table the host passed (an absent or malformed `"needs"` installs an empty one).
+pub fn install(table: Option<&Json>) {
+    let parsed = match table {
+        Some(Json::Object(entries)) => entries
+            .iter()
+            .map(|(verb, needs)| {
+                let needs = needs
+                    .as_array()
+                    .unwrap_or(&[])
+                    .iter()
+                    .filter_map(|n| {
+                        let fact = n.get("fact")?.as_str()?.to_string();
+                        let attribute_type = n.get("type").and_then(Json::as_str).unwrap_or("").to_string();
+                        Some(Need { fact, attribute_type })
+                    })
+                    .collect();
+                (verb.clone(), needs)
+            })
+            .collect(),
+        _ => HashMap::new(),
+    };
+    TABLE.with(|t| *t.borrow_mut() = parsed);
+}
+
+/// Makes the kernel clock answer `secs` on this thread until cleared; the test seam.
+pub fn fix_clock(secs: Option<i64>) {
+    FIXED_CLOCK.with(|c| c.set(secs));
+}
+
+/// The clock's answer: epoch seconds, UTC. The step's `occurred_at` when it parses, else the
+/// system clock (unless fixed).
+pub fn now_secs(occurred_at: Option<&str>) -> i64 {
+    if let Some(fixed) = FIXED_CLOCK.with(Cell::get) {
+        return fixed;
+    }
+    occurred_at.and_then(parse_iso8601_utc).unwrap_or_else(|| {
+        std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(|d| d.as_secs() as i64).unwrap_or_default()
+    })
+}
+
+/// `YYYY-MM-DDTHH:MM:SSZ` to epoch seconds (the format the host stamps).
+fn parse_iso8601_utc(text: &str) -> Option<i64> {
+    let text = text.strip_suffix('Z')?;
+    let (date, time) = text.split_once('T')?;
+    let mut d = date.split('-');
+    let (y, m, day): (i64, i64, i64) = (d.next()?.parse().ok()?, d.next()?.parse().ok()?, d.next()?.parse().ok()?);
+    let mut t = time.split(':');
+    let (h, mi, s): (i64, i64, i64) = (t.next()?.parse().ok()?, t.next()?.parse().ok()?, t.next()?.split('.').next()?.parse().ok()?);
+    // Howard Hinnant's days-from-civil.
+    let y = if m <= 2 { y - 1 } else { y };
+    let era = if y >= 0 { y } else { y - 399 } / 400;
+    let yoe = y - era * 400;
+    let doy = (153 * (if m > 2 { m - 3 } else { m + 9 }) + 2) / 5 + day - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    let days = era * 146_097 + doe - 719_468;
+    Some(days * 86_400 + h * 3600 + mi * 60 + s)
+}
+
+fn answer(need: &Need, occurred_at: Option<&str>) -> Option<Json> {
+    match need.fact.as_str() {
+        "now" => {
+            let secs = now_secs(occurred_at);
+            Some(if need.attribute_type == "Integer" { Json::int(secs) } else { Json::obj(vec![("value", Json::int(secs))]) })
+        }
+        _ => None,
+    }
+}
+
+/// `args` with each fact `verb` needs and the caller left out answered, or `None` when nothing
+/// needed filling (no needs, or every fact supplied). Reads `with` when the call carries one,
+/// else the flat object, as `CommandInvocation` does.
+pub fn enrich(verb: &str, args: &Json, occurred_at: Option<&str>) -> Option<Json> {
+    let needs = TABLE.with(|t| t.borrow().get(verb).cloned())?;
+    let explicit = matches!(args.get("with"), Some(Json::Object(_)));
+    let facts = if explicit { args.get("with")? } else { args };
+    let Json::Object(held) = facts else { return None };
+    let mut filled = held.clone();
+    let before = filled.len();
+    for need in &needs {
+        if held.iter().any(|(k, _)| k == &need.fact) {
+            continue;
+        }
+        if let Some(value) = answer(need, occurred_at) {
+            filled.push((need.fact.clone(), value));
+        }
+    }
+    if filled.len() == before {
+        return None;
+    }
+    if !explicit {
+        return Some(Json::Object(filled));
+    }
+    let Json::Object(envelope) = args else { return None };
+    Some(Json::Object(envelope.iter().map(|(k, v)| if k == "with" { (k.clone(), Json::Object(filled.clone())) } else { (k.clone(), v.clone()) }).collect()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn table() -> Json {
+        Json::parse(
+            r#"{"D::A.Instant": [{"fact": "now", "type": "LeaseInstant"}],
+                "D::A.Seconds": [{"fact": "now", "type": "Integer"}]}"#,
+        )
+        .unwrap()
+    }
+
+    fn with(fields: Vec<(&str, Json)>) -> Json {
+        Json::obj(vec![("with", Json::obj(fields))])
+    }
+
+    #[test]
+    fn a_needed_fact_left_out_is_answered_by_the_clock() {
+        install(Some(&table()));
+        fix_clock(Some(1_700_000_000));
+        let filled = enrich("D::A.Instant", &with(vec![("x", Json::int(1))]), None).unwrap();
+        assert_eq!(filled.get("with").unwrap().get("now"), Some(&Json::obj(vec![("value", Json::int(1_700_000_000))])));
+        assert_eq!(filled.get("with").unwrap().get("x"), Some(&Json::int(1)));
+    }
+
+    #[test]
+    fn a_supplied_value_is_kept() {
+        install(Some(&table()));
+        fix_clock(Some(1));
+        let args = with(vec![("now", Json::obj(vec![("value", Json::int(42))]))]);
+        assert_eq!(enrich("D::A.Instant", &args, None), None);
+    }
+
+    #[test]
+    fn a_command_with_no_needs_is_untouched() {
+        install(Some(&table()));
+        assert_eq!(enrich("D::A.Plain", &with(vec![]), None), None);
+        install(None);
+        assert_eq!(enrich("D::A.Instant", &with(vec![]), None), None);
+    }
+
+    #[test]
+    fn an_integer_attribute_gets_a_bare_integer_and_an_instant_a_value_object() {
+        install(Some(&table()));
+        fix_clock(Some(9));
+        assert_eq!(enrich("D::A.Seconds", &with(vec![]), None).unwrap().get("with").unwrap().get("now"), Some(&Json::int(9)));
+        assert_eq!(
+            enrich("D::A.Instant", &with(vec![]), None).unwrap().get("with").unwrap().get("now"),
+            Some(&Json::obj(vec![("value", Json::int(9))]))
+        );
+    }
+
+    #[test]
+    fn a_flat_invocation_is_filled_at_the_top_level() {
+        install(Some(&table()));
+        fix_clock(Some(5));
+        let filled = enrich("D::A.Seconds", &Json::obj(vec![("x", Json::int(1))]), None).unwrap();
+        assert_eq!(filled.get("now"), Some(&Json::int(5)));
+    }
+
+    #[test]
+    fn the_step_s_occurred_at_is_the_answer_when_no_clock_is_fixed() {
+        fix_clock(None);
+        assert_eq!(now_secs(Some("2023-11-14T22:13:20Z")), 1_700_000_000);
+        assert_eq!(now_secs(Some("1970-01-01T00:00:00Z")), 0);
+        assert!(now_secs(None) > 1_700_000_000);
+    }
+}

data/rust/src/kernel/orchestrate.rs

@@ -226,6 +226,10 @@ pub fn orchestrate<S: AggregateScan>(
     reaction_log: &mut Vec<Json>,
     saga_log: &mut Vec<Json>,
 ) -> Result<(), Refusal> {
+    // A fact the command `needs` is answered ahead of every gate (ADR 0081), for a reaction's
+    // dispatch as for the outermost one.
+    let enriched = super::needs::enrich(verb, args, occurred_at);
+    let args = enriched.as_ref().unwrap_or(args);
     let mut events = dispatch_fn(store, verb, args, caller_role, caller_actor_id, mutations)?;
 
     if let Some(stamp) = saga_correlation {
@@ -1271,6 +1275,86 @@ mod tests {
         );
     }
 
+    // Stands in for a command whose generated `refuse_absent_arguments` lists `now` as declared
+    // and non-optional: it refuses when `now` is missing and records what the gates saw.
+    thread_local! { static SEEN: std::cell::RefCell<Option<Json>> = const { std::cell::RefCell::new(None) }; }
+    fn strict_now_dispatch(
+        _store: &mut MultiLegTestStore,
+        _verb: &str,
+        args: &Json,
+        _caller_role: Option<&str>,
+        _caller_actor_id: Option<&str>,
+        _mutations: &mut Vec<MutationRecord>,
+    ) -> Result<Vec<Event>, Refusal> {
+        let facts = args.get("with").unwrap_or(args);
+        if facts.get("now").is_none() {
+            return Err(Refusal::GivenNotMet("absent argument: now".to_string()));
+        }
+        SEEN.with(|s| *s.borrow_mut() = Some(facts.clone()));
+        Ok(vec![])
+    }
+
+    fn run_strict_now(verb: &str, args: &Json, occurred_at: Option<&str>) -> Result<(), Refusal> {
+        static NONE_P: &[PolicyRule] = &[];
+        static NONE_X: &[CrossDomainPolicyRule] = &[];
+        static NONE_M: &[ProcessManagerDef] = &[];
+        static NONE_Q: &[crate::kernel::QueryDef] = &[];
+        let tables = Tables {
+            policies: NONE_P,
+            cross_domain_policies: NONE_X,
+            process_managers: NONE_M,
+            reference_key_fn: multi_leg_no_reference_key,
+            queries: NONE_Q,
+            command_creates_fn: multi_leg_always_creates,
+            identity_head_fn: multi_leg_no_identity_head,
+            command_attributes_fn: multi_leg_no_declared_attributes,
+            entity_identity_head_fn: multi_leg_no_entity_identity_head,
+        };
+        SEEN.with(|s| *s.borrow_mut() = None);
+        orchestrate(
+            &mut MultiLegTestStore,
+            strict_now_dispatch,
+            tables,
+            &mut HashMap::new(),
+            verb,
+            args,
+            None,
+            None,
+            None,
+            occurred_at,
+            0,
+            &mut Vec::new(),
+            &mut Vec::new(),
+            &mut Vec::new(),
+            &mut Vec::new(),
+            &mut Vec::new(),
+        )
+    }
+
+    // Both kernel-path guarantees at once: the fill lands before the absent-argument gate runs, so
+    // the strict refusal does not fire for a needed fact, and a supplied value is the one the
+    // gates see.
+    #[test]
+    fn a_needed_fact_is_answered_before_the_absent_argument_gate_and_a_supplied_one_is_kept() {
+        let table = Json::parse(r#"{"T::Slot.Lease": [{"fact": "now", "type": "Integer"}]}"#).unwrap();
+        crate::kernel::needs::install(Some(&table));
+        crate::kernel::needs::fix_clock(Some(77));
+
+        let args = Json::obj(vec![("with", Json::obj(vec![("holder", Json::str("a"))]))]);
+        assert!(run_strict_now("T::Slot.Lease", &args, None).is_ok());
+        SEEN.with(|s| assert_eq!(s.borrow().as_ref().unwrap().get("now"), Some(&Json::int(77))));
+
+        let supplied = Json::obj(vec![("with", Json::obj(vec![("now", Json::int(5))]))]);
+        assert!(run_strict_now("T::Slot.Lease", &supplied, None).is_ok());
+        SEEN.with(|s| assert_eq!(s.borrow().as_ref().unwrap().get("now"), Some(&Json::int(5))));
+
+        // A command that declares no need keeps the strict refusal.
+        assert!(run_strict_now("T::Slot.Other", &args, None).is_err());
+
+        crate::kernel::needs::fix_clock(None);
+        crate::kernel::needs::install(None);
+    }
+
     // Pins domain-qualifying a same-domain entity command (`Manifest::Slot.Fill`): its leftover
     // `::` looks cross-domain, and an unqualified name would fail as an unknown command. The fake
     // dispatch panics on any verb but the qualified, dot-joined form.

data/rust/src/kernel/repository.rs

@@ -198,7 +198,8 @@ pub fn holds_role_via(
 
 /// Refuses with `Unauthorized` when the caller's role does not satisfy `command_role`.
 ///
-/// Unchecked unless both a caller and a command role are present. With `caller_actor_id` and an
+/// Unchecked unless both a caller and a command role are present, except that an identified caller
+/// (`caller_actor_id`) with no stated role is held to what Governance assigned them. With `caller_actor_id` and an
 /// authorization provider compiled in (`assignments` names a query in `queries`), the role must be
 /// held through `holds_role_via`; otherwise the caller's stated role is compared as a string.
 /// Governance's own commands get no exemption: the running Ruby checks them like any other,
@@ -213,9 +214,19 @@ pub fn check_role_via(
     queries: &[super::QueryDef],
     assignments: Option<&str>,
 ) -> Result<(), super::Refusal> {
+    let attached = assignments.and_then(|verb| super::named_query::find(queries, verb)).is_some();
+    // An identified caller with no stated role is checked against what Governance assigned them: the
+    // caller need not claim a role it may not hold. Unchecked without a Governance provider, as ever.
+    if let (None, Some(role), Some(actor_id)) = (caller_role, command_role, caller_actor_id) {
+        if !attached || holds_role_via(store, queries, assignments, actor_id, role) {
+            return Ok(());
+        }
+        return Err(super::Refusal::Unauthorized(
+            super::refusal_wording::UnauthorizedRoleMismatchArgs { command: command_name, role, caller_role: "no assigned role" }.render_args(),
+        ));
+    }
     let (Some(caller), Some(role)) = (caller_role, command_role) else { return Ok(()) };
 
-    let attached = assignments.and_then(|verb| super::named_query::find(queries, verb)).is_some();
     let authorized = match caller_actor_id {
         Some(actor_id) if attached => holds_role_via(store, queries, assignments, actor_id, role),
         _ => caller == role,
@@ -389,6 +400,36 @@ mod check_role_actor_id_tests {
         assert!(result.is_err(), "a revoked grant must not authorize: {result:?}");
     }
 
+    // An identified caller that states no role is held to what Governance assigned them.
+    #[test]
+    fn an_identified_caller_with_no_stated_role_needs_a_live_assignment_of_the_commands_role() {
+        let store = FakeStore { role_assignments: vec![("ra1".to_string(), role_assignment("u1", "Chef", None))] };
+        let queries = [assignments_for_actor_query()];
+
+        assert!(check_role(Some("Chef"), "Prepare", None, Some("u1"), &store, &queries).is_ok(), "an assigned actor needs no stated role");
+        assert!(check_role(Some("Waiter"), "Serve", None, Some("u1"), &store, &queries).is_err(), "an actor not assigned the role is refused");
+        assert!(check_role(Some("Chef"), "Prepare", None, Some("u2"), &store, &queries).is_err(), "an unassigned actor is refused");
+    }
+
+    // Revoked assignments do not count for a caller with no stated role either.
+    #[test]
+    fn an_identified_caller_with_no_stated_role_is_refused_on_a_revoked_assignment() {
+        let store = FakeStore { role_assignments: vec![("ra1".to_string(), role_assignment("u1", "Chef", Some("2026-06-01")))] };
+        let queries = [assignments_for_actor_query()];
+
+        assert!(check_role(Some("Chef"), "Prepare", None, Some("u1"), &store, &queries).is_err());
+    }
+
+    // No Governance provider attached: an actor with no stated role stays unchecked, as before.
+    #[test]
+    fn an_identified_caller_with_no_stated_role_is_unchecked_when_governance_is_not_attached() {
+        let store = FakeStore { role_assignments: vec![] };
+
+        let result = check_role_via(Some("Chef"), "Prepare", None, Some("u1"), &store, &[], None);
+
+        assert!(result.is_ok(), "no provider, nothing to check against: {result:?}");
+    }
+
     // A caller with only `role:` keeps the plain string comparison, whatever grants exist.
     #[test]
     fn a_bare_role_only_caller_is_unaffected_by_any_real_grant_data() {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.0.3
+  version: 3.0.4
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -336,6 +336,7 @@ files:
 - lib/hecks/fuzzing/sweep_depth.rb
 - lib/hecks/fuzzing/target_capabilities.rb
 - lib/hecks/fuzzing/value_generator.rb
+- lib/hecks/gate/stages.yml
 - lib/hecks/grammar.rb
 - lib/hecks/grammar/evolve.rb
 - lib/hecks/grammar/expression.bluebook
@@ -346,6 +347,7 @@ files:
 - lib/hecks/hecks/adapters/codebase/codemods.rb
 - lib/hecks/hecks/adapters/codebase/conformance.rb
 - lib/hecks/hecks/adapters/codebase/corpus_tasks.rb
+- lib/hecks/hecks/adapters/codebase/gate.rb
 - lib/hecks/hecks/adapters/codebase/gem_registry.rb
 - lib/hecks/hecks/adapters/codebase/kernel_tables.rb
 - lib/hecks/hecks/adapters/codebase/language.rb
@@ -728,6 +730,8 @@ files:
 - lib/hecks/three_zero/forms.yml
 - lib/hecks/tools.rb
 - lib/hecks/tools/argument_gate_matrix.rb
+- lib/hecks/tools/ci_gate_decision.rb
+- lib/hecks/tools/ci_gates.rb
 - lib/hecks/tools/comment_style.rb
 - lib/hecks/tools/corpus_report.rb
 - lib/hecks/tools/deploy_recipe.rb
@@ -737,6 +741,7 @@ files:
 - lib/hecks/tools/era_reattest.rb
 - lib/hecks/tools/evolve_run.rb
 - lib/hecks/tools/fuzz_sweep.rb
+- lib/hecks/tools/gate.rb
 - lib/hecks/tools/heki_compaction.rb
 - lib/hecks/tools/hoist_local_givens.rb
 - lib/hecks/tools/journal_compaction.rb
@@ -833,6 +838,7 @@ files:
 - rust/host/src/log.rs
 - rust/host/src/main.rs
 - rust/host/src/mint.rs
+- rust/host/src/needs.rs
 - rust/host/src/payments.rs
 - rust/host/src/payments/keystore.rs
 - rust/host/src/payments/tests.rs
@@ -961,6 +967,7 @@ files:
 - rust/src/kernel/json.rs
 - rust/src/kernel/mod.rs
 - rust/src/kernel/named_query.rs
+- rust/src/kernel/needs.rs
 - rust/src/kernel/orchestrate.rs
 - rust/src/kernel/pattern.rs
 - rust/src/kernel/query_comparators.rs