hecks 3.0.2 → 3.0.4

data/rust/parser/src/emit.rs

@@ -43,25 +43,20 @@ pub fn write(value: &JsonValue) -> String {
 /// The pinned `Expression::CanonicalForm.table` rules from projection.json, in Ruby's field
 /// order; `position` is a string.
 fn canonical_form_table() -> JsonValue {
-    JsonValue::Array(vec![
-        JsonValue::Object(vec![
-            (
-                "strategy".to_string(),
-                JsonValue::str("collapse_whitespace"),
-            ),
-            ("source_token".to_string(), JsonValue::str("")),
-            ("replacement".to_string(), JsonValue::str("")),
-            ("boundary".to_string(), JsonValue::str("none")),
-            ("position".to_string(), JsonValue::str("1")),
-        ]),
-        JsonValue::Object(vec![
-            ("strategy".to_string(), JsonValue::str("replace")),
-            ("source_token".to_string(), JsonValue::str(".length")),
-            ("replacement".to_string(), JsonValue::str(".size")),
-            ("boundary".to_string(), JsonValue::str("word")),
-            ("position".to_string(), JsonValue::str("2")),
-        ]),
-    ])
+    JsonValue::Array(
+        crate::canonical::TABLE
+            .iter()
+            .map(|(strategy, token, replacement, boundary, position)| {
+                JsonValue::Object(vec![
+                    ("strategy".to_string(), JsonValue::str(*strategy)),
+                    ("source_token".to_string(), JsonValue::str(*token)),
+                    ("replacement".to_string(), JsonValue::str(*replacement)),
+                    ("boundary".to_string(), JsonValue::str(*boundary)),
+                    ("position".to_string(), JsonValue::str(*position)),
+                ])
+            })
+            .collect(),
+    )
 }
 
 /// `IR::Bluebook#to_h`; field order is pinned there.
@@ -304,6 +299,17 @@ fn command_json(c: &ir::Command) -> JsonValue {
             "ensures".to_string(),
             JsonValue::Array(c.ensures.iter().map(given_json).collect()),
         ),
+        (
+            "needs".to_string(),
+            JsonValue::Array(
+                c.needs
+                    .iter()
+                    .map(|fact| {
+                        JsonValue::Object(vec![("fact".to_string(), JsonValue::str(fact.clone()))])
+                    })
+                    .collect(),
+            ),
+        ),
         (
             "mutations".to_string(),
             JsonValue::Array(c.mutations.iter().map(mutation_json).collect()),

data/rust/parser/src/ir.rs

@@ -98,6 +98,8 @@ pub struct Command {
     pub attributes: Vec<Attribute>,
     pub givens: Vec<Given>,
     pub ensures: Vec<Ensures>,
+    // Outside facts the runtime supplies before any given runs (`needs :now`); only `now` today.
+    pub needs: Vec<String>,
     pub mutations: Vec<Mutation>,
     pub emits: Vec<String>,
     // The lifecycle state this command is admissible from; see `CommandFrom`.

data/rust/parser/src/keywords.rs

@@ -107,6 +107,7 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "state", context: "Command", body: "none", inner: "", opens: "", fills: "mutations", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "attribute", context: "Command", body: "none", inner: "", opens: "", fills: "attributes", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "needs", context: "Command", body: "none", inner: "", opens: "", fills: "needs", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "corrects", context: "Command", body: "none", inner: "", opens: "", fills: "mutations", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "description", context: "Entity", body: "none", inner: "", opens: "", fills: "description", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "identified_by", context: "Entity", body: "keywords", inner: "ValueObject", opens: "ValueObject", fills: "identified_by", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
@@ -308,6 +309,7 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "reference_to", context: "Command", at: "", named: "optional", kind: "flag", required: "false", fills: "optional", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "given", context: "Command", at: "1", named: "", kind: "text", required: "true", fills: "description", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "ensures", context: "Command", at: "1", named: "", kind: "text", required: "true", fills: "description", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "needs", context: "Command", at: "1", named: "", kind: "symbol", required: "true", fills: "fact", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "1", named: "", kind: "symbol", required: "true", fills: "target", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "", named: "to", kind: "literal", required: "false", fills: "source", selects: "op=set", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "", named: "append", kind: "literal", required: "false", fills: "source", selects: "op=append", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/main.rs

@@ -179,6 +179,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("reference_to", "Command"),
     ("given", "Command"),
     ("ensures", "Command"),
+    ("needs", "Command"),
     ("sets", "Command"),
     ("corrects", "Command"),
     ("delegates_to", "Command"),

data/rust/parser/src/parse/command.rs

@@ -164,6 +164,7 @@ pub fn parse_body(
                 owner_entities,
             );
             refuse_duplicate_targets(file, *pos, &command)?;
+            refuse_undeclared_needs(file, *pos, &command)?;
             return Ok((command, pending));
         };
         let line = gated.line.number;
@@ -205,6 +206,27 @@ pub fn parse_body(
                     canonical: canonical::apply(&raw),
                 });
             }
+            "needs" => {
+                let fact = super::positional_symbol(file, line, "needs", &gated.args, 1)?;
+                if !NEEDABLE_FACTS.contains(&fact.as_str()) {
+                    return Err(Diagnostic::new(
+                        file,
+                        line,
+                        format!(
+                            "{} needs :{fact}, which the runtime cannot supply — it supplies :now",
+                            command.name
+                        ),
+                    ));
+                }
+                if command.needs.contains(&fact) {
+                    return Err(Diagnostic::new(
+                        file,
+                        line,
+                        format!("{} declares needs :{fact} twice", command.name),
+                    ));
+                }
+                command.needs.push(fact);
+            }
             "provenance" => {
                 let raw = super::named_raw(&gated.args, "from")
                     .ok_or_else(|| Diagnostic::new(file, line, "'provenance' requires a from:"))?;
@@ -297,6 +319,28 @@ fn state_ref(raw: &str) -> Option<String> {
     Some(inner.to_string())
 }
 
+/// The outside facts a command may declare it needs; mirrors `CommandBuilder::NEEDABLE_FACTS`.
+const NEEDABLE_FACTS: &[&str] = &["now"];
+
+/// A need names the attribute the runtime fills, so the command must declare it.
+fn refuse_undeclared_needs(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {
+    match command
+        .needs
+        .iter()
+        .find(|fact| !command.attributes.iter().any(|a| &a.name == *fact))
+    {
+        Some(fact) => Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{} needs :{fact} but declares no attribute :{fact} for the runtime to fill — add `attribute :{fact}, <type>`",
+                command.name
+            ),
+        )),
+        None => Ok(()),
+    }
+}
+
 /// Refuses a field written twice: a command's effects are one update set (C4.2).
 /// `delegates_to`/`corrects` name no field and are not counted.
 fn refuse_duplicate_targets(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {

data/rust/project/naming.rb

@@ -100,12 +100,14 @@ module RustProjection
 
     # Every declared `name` in the IR, in document order. The `fields` maps under
     # `mutations` are skipped: their keys are attribute names and their values
-    # are source text, not declarations.
+    # are source text, not declarations. So is `translations`: an era edge names
+    # data paths (`attendee.first_name`, a backfill into a nested value object)
+    # that the host applies to stored rows and never writes into Rust.
     def declared_names(node, out = [])
       case node
       when Hash
         node.each do |key, value|
-          if key.to_s == "fields"
+          if %w[fields translations].include?(key.to_s)
             next
           elsif key.to_s == "name" && value.is_a?(String)
             out << value

data/rust/project_rust_pipeline.rb

@@ -70,6 +70,10 @@ module RustProjectPipeline
     # vendor/embryonaut_bluebooks/<name>/bluebook/, sorted. A vendored
     # package has no .hecksagon of its own either, just its .bluebook(s).
     chapters += uses_embryonaut_bluebook_names.map do |pkg_name|
+      unless pkg_name.to_s.match?(Hecks::EmbryonautBluebook::PACKAGE_NAME)
+        abort "hecks project_rust (Rust path): uses_embryonaut_bluebook #{pkg_name.inspect} is not a package " \
+              "name — it must match [a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
+      end
       pkg_dir = File.join(domain, "vendor", "embryonaut_bluebooks", pkg_name.to_s, "bluebook")
       pkg_files = Dir.glob(File.join(pkg_dir, "*.bluebook")).sort
       if pkg_files.empty?

data/rust/src/kernel/cli.rs

@@ -16,6 +16,9 @@ pub fn run(input: &str) -> String {
         Err(e) => return error_output(&format!("invalid JSON on stdin: {e}")),
     };
 
+    // Optional `"needs"`: which commands need which outside facts (ADR 0081), passed by the host.
+    super::needs::install(parsed.get("needs"));
+
     let steps = match parsed.get("steps").and_then(Json::as_array) {
         Some(s) => s,
         None => return error_output("expected a top-level {\"steps\": [...]} object"),

data/rust/src/kernel/mod.rs

@@ -7,6 +7,7 @@ pub mod expr;
 pub mod expression_operators;
 pub mod json;
 pub mod named_query;
+pub mod needs;
 pub mod orchestrate;
 pub mod pattern;
 pub mod query_ordering;

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.2
+  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