hecks 3.0.5 → 3.1.0

data/rust/build/src/resolve.rs

@@ -77,12 +77,45 @@ pub fn grammar_files(root: &Path) -> Result<Vec<PathBuf>, String> {
     bluebook_files(&dir)
 }
 
-pub fn resolve_uses_framework(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
-    resolve_json(parser_bin, chapter_name, hecksagon_path, "uses_framework")
+// The names `attaches "Name"` gave, for a chapter the gem carries.
+pub fn resolve_gem_chapters(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
+    resolve_json(parser_bin, chapter_name, hecksagon_path, "gem_chapters")
 }
 
-pub fn resolve_uses_embryonaut_bluebook(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
-    resolve_json(parser_bin, chapter_name, hecksagon_path, "uses_embryonaut_bluebook")
+// The names `attaches "name", from: :vendor` gave, for a vendored package.
+pub fn resolve_vendored_packages(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
+    resolve_json(parser_bin, chapter_name, hecksagon_path, "vendored_packages")
+}
+
+// Where the gem keeps the chapters other than framework members, relative to `lib/hecks`; the
+// same places `Hecks::Chapters::GLOBS` lists.
+const OTHER_GEM_CHAPTER_DIRS: &[&str] = &["language", "grammar", "tenancy/bluebook", "deploy/bluebook", "quality_control"];
+
+// The names of the chapters the gem carries beside the framework members, found by reading each
+// file's header. Only the Ruby runtime loads them, so the build uses this list to tell a real
+// gem chapter from a misspelt name.
+pub fn other_gem_chapter_names(root: &Path) -> Result<Vec<String>, String> {
+    fn walk(directory: &Path, names: &mut Vec<String>) -> Result<(), String> {
+        let Ok(entries) = std::fs::read_dir(directory) else { return Ok(()) };
+        for entry in entries {
+            let path = entry.map_err(|e| format!("reading {}: {e}", directory.display()))?.path();
+            if path.is_dir() {
+                walk(&path, names)?;
+            } else if path.extension().and_then(|e| e.to_str()) == Some("bluebook") {
+                if let Ok(name) = header_chapter_name(&path) {
+                    names.push(name);
+                }
+            }
+        }
+        Ok(())
+    }
+    let mut names = Vec::new();
+    for directory in OTHER_GEM_CHAPTER_DIRS {
+        walk(&root.join("lib/hecks").join(directory), &mut names)?;
+    }
+    names.sort();
+    names.dedup();
+    Ok(names)
 }
 
 fn resolve_json(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path, key: &str) -> Result<Vec<String>, String> {
@@ -105,13 +138,13 @@ pub fn valid_package_name(name: &str) -> bool {
 pub fn vendored_bluebook_files(domain: &Path, pkg_name: &str) -> Result<Vec<PathBuf>, String> {
     if !valid_package_name(pkg_name) {
         return Err(format!(
-            "uses_embryonaut_bluebook {pkg_name:?} is not a package name — it must match [a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
+            "attaches {pkg_name:?}, from: :vendor is not a package name — it must match [a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
         ));
     }
     let dir = domain.join("vendor").join("embryonaut_bluebooks").join(pkg_name).join("bluebook");
     if !dir.is_dir() {
         return Err(format!(
-            "uses_embryonaut_bluebook {pkg_name:?} names no vendored bluebook at {} — run hecks vendor {pkg_name}",
+            "attaches {pkg_name:?}, from: :vendor names no vendored bluebook at {} — run hecks vendor {pkg_name}",
             dir.display()
         ));
     }

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.0.5
+3.1.0

data/rust/host/src/api.rs

@@ -780,7 +780,7 @@ async fn presentation_save(
 const PRESENTATION_WRITE_REFUSAL: &str =
     "this host's kernel carries no ConsoleSettings chapter, so it has no StateStyle/Collection/Overview \
      commands to dispatch, and writing the rows behind its back would skip the invariants those commands \
-     enforce. Attach it with `uses_framework \"ConsoleSettings\"` in this domain's own .hecksagon and \
+     enforce. Attach it with `attaches \"ConsoleSettings\"` in this domain's own .hecksagon and \
      rebuild the kernel, or save from the Ruby console engine instead.";
 
 // ---- response envelopes ---------------------------------------------

data/rust/host/src/dispatch.rs

@@ -31,7 +31,9 @@ pub const ANONYMOUS_ROLE: &str = "Anonymous";
 pub enum Enforcement {
     /// A caller with no role is unchecked, as before.
     Off,
-    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`.
+    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`; a
+    /// caller that states a role is checked exactly as under `Enforce`, so shadow never accepts
+    /// what `Off` would not.
     Shadow,
     /// An unidentified or unassigned caller is refused.
     Enforce,
@@ -62,6 +64,15 @@ impl Enforcement {
     }
 }
 
+/// Where a dispatch comes from. A host-internal dispatch is the host acting on its own behalf (a
+/// signup, a provisioning step, a presentation write); it names no caller and is never subject to
+/// `HECKS_ROLE_ENFORCEMENT`, which guards what callers outside the host may do.
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Origin {
+    External,
+    HostInternal,
+}
+
 /// Whether the kernel refused the command for the caller's role.
 fn refused_for_role(result: &serde_json::Value) -> bool {
     result.get("refusals").and_then(|r| r.as_array()).is_some_and(|all| {
@@ -189,6 +200,10 @@ pub async fn handle_facts_as(
 // `role` is optional, matching `Adapters::Lambda::Client#dispatch`'s own
 // `role: nil` default: a step with no role looks the same on the wire
 // whether or not a caller is bound.
+//
+// This entry point and `handle_facts`/`handle_routed` are the host's own: a call with no role is a
+// host-internal dispatch and is unchecked in every enforcement mode. A call that names a role is
+// still checked against it. Callers outside the host go through the `_as` entry points.
 pub async fn handle(
     client: &Mutex<Client>,
     wasm_path: &Path,
@@ -198,7 +213,8 @@ pub async fn handle(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    handle_as(client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
+    let origin = if role.is_none() { Origin::HostInternal } else { Origin::External };
+    dispatch_in(Enforcement::from_env(), origin, client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
 }
 
 /// Dispatches for a caller, applying `HECKS_ROLE_ENFORCEMENT`: unidentified callers are refused (or,
@@ -212,12 +228,13 @@ pub async fn handle_as(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    handle_with(Enforcement::from_env(), client, wasm_path, verb, args, caller, config, invoker).await
+    dispatch_in(Enforcement::from_env(), Origin::External, client, wasm_path, verb, args, caller, config, invoker).await
 }
 
 #[allow(clippy::too_many_arguments)]
-async fn handle_with(
+async fn dispatch_in(
     mode: Enforcement,
+    origin: Origin,
     client: &Mutex<Client>,
     wasm_path: &Path,
     verb: &str,
@@ -226,9 +243,11 @@ async fn handle_with(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    let checked = mode.effective(caller);
+    let checked = if origin == Origin::HostInternal { caller } else { mode.effective(caller) };
     let outcome = run(client, wasm_path, verb, args.clone(), checked, config, invoker).await?;
-    if mode == Enforcement::Shadow && !outcome.accepted && refused_for_role(&outcome.result) {
+    // Only a caller that stated no role (unidentified, or an actor Governance holds no grant for)
+    // is let through; a stated role that does not match stays refused, as it is under `Off`.
+    if mode == Enforcement::Shadow && caller.role.is_none() && !outcome.accepted && refused_for_role(&outcome.result) {
         crate::log::error("would_refuse_role", serde_json::json!({
             "verb": verb, "role": checked.role, "actor_id": checked.actor_id,
             "refusals": outcome.result.get("refusals"),
@@ -287,6 +306,8 @@ async fn run(
     let mut args = args;
     if let Some(domain_ir) = crate::ir::ir() {
         crate::needs::fill_needs(domain_ir, verb, &mut args, &crate::needs::ProcessClock);
+        // An argument with a declared default is filled the same way, so the journal holds it too.
+        crate::needs::fill_defaults(domain_ir, verb, &mut args);
     }
     let mut step = serde_json::json!({ "verb": verb, "args": args.clone() });
     if let Some(role) = role {
@@ -330,6 +351,10 @@ async fn run(
         if table.as_object().is_some_and(|t| !t.is_empty()) {
             input["needs"] = table;
         }
+        let defaults = crate::needs::defaults_table(domain_ir);
+        if defaults.as_object().is_some_and(|t| !t.is_empty()) {
+            input["defaults"] = defaults;
+        }
     }
     let input = input.to_string();
     // `wasm_runner::run` is sync, and wasmtime-wasi's sync bridge spins up
@@ -1353,7 +1378,7 @@ pub(crate) mod tests {
             let client = &client;
             let config = &config;
             async move {
-                handle_with(mode, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                dispatch_in(mode, Origin::External, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
                     .await
                     .unwrap()
             }
@@ -1375,6 +1400,61 @@ pub(crate) mod tests {
         assert_eq!(steps.len(), 2, "the enforced refusal was not persisted; off and shadow were");
     }
 
+    // Shadow may only let through what Off would: a caller that stated a wrong role is refused.
+    #[tokio::test]
+    async fn shadow_refuses_a_stated_wrong_role_and_still_lets_an_unidentified_caller_through() {
+        let client = scratch_db("rust_host_dispatch_test_shadow_stated").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, origin: Origin, caller: Caller<'static>, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                dispatch_in(mode, origin, client, &wasm_path(), "Banking::Customer.Register", register(id), caller, config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+        let wrong = Caller { role: Some("Auditor"), actor_id: None };
+
+        let shadow_wrong = go(Enforcement::Shadow, Origin::External, wrong, "CUST-0031").await;
+        assert!(!shadow_wrong.accepted, "shadow must not accept a stated wrong role: {:?}", shadow_wrong.result);
+        assert!(refused_for_role(&shadow_wrong.result), "{:?}", shadow_wrong.result);
+        let off_wrong = go(Enforcement::Off, Origin::External, wrong, "CUST-0032").await;
+        assert!(!off_wrong.accepted, "off refuses it too: {:?}", off_wrong.result);
+
+        let nobody = go(Enforcement::Shadow, Origin::External, Caller::default(), "CUST-0033").await;
+        assert!(nobody.accepted, "shadow lets an unidentified caller through: {:?}", nobody.result);
+
+        let steps = journal::load_steps(&*client.lock().await).await.unwrap();
+        assert_eq!(steps.len(), 1, "only the unidentified caller's registration was persisted");
+    }
+
+    // A host-internal dispatch names no caller and is unchecked in every mode, while an external
+    // unidentified caller is refused under enforce.
+    #[tokio::test]
+    async fn a_host_internal_dispatch_is_unchecked_under_enforce_but_an_external_one_is_refused() {
+        let client = scratch_db("rust_host_dispatch_test_internal").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, origin: Origin, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                dispatch_in(mode, origin, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+
+        let external = go(Enforcement::Enforce, Origin::External, "CUST-0041").await;
+        assert!(!external.accepted, "{:?}", external.result);
+        for (mode, id) in [(Enforcement::Enforce, "CUST-0042"), (Enforcement::Shadow, "CUST-0043"), (Enforcement::Off, "CUST-0044")] {
+            let internal = go(mode, Origin::HostInternal, id).await;
+            assert!(internal.accepted, "{mode:?}: {:?}", internal.result);
+        }
+    }
+
     #[tokio::test]
     async fn a_mid_transaction_failure_rolls_back_any_saga_state_already_written() {
         // Deliberately doesn't provision "Transfer": its mutation fails

data/rust/host/src/needs.rs

@@ -110,6 +110,52 @@ pub fn table(domain_ir: &Value) -> Value {
     Value::Object(verbs)
 }
 
+/// The command's attributes that declare a default (`attribute :runs, Count, default: 30`), each
+/// with the declared value. An attribute whose default is null declares none.
+fn declared_defaults<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, &'a Value)> {
+    let Some((qualified_aggregate, command_name)) = verb.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let named = |value: &Value, name: &str| value.get("name").and_then(Value::as_str) == Some(name);
+    let list = |value: &'a Value, key: &str| -> Vec<&'a Value> {
+        value.get(key).and_then(Value::as_array).map(|a| a.iter().collect()).unwrap_or_default()
+    };
+    list(domain_ir, "aggregates")
+        .into_iter()
+        .filter(|a| named(a, aggregate))
+        .flat_map(|a| list(a, "commands"))
+        .filter(|c| named(c, command_name))
+        .flat_map(|c| list(c, "attributes"))
+        .filter_map(|a| {
+            let default = a.get("default").filter(|d| !d.is_null())?;
+            Some((a.get("name").and_then(Value::as_str)?, default))
+        })
+        .collect()
+}
+
+/// Every command's declared defaults as the kernel's input `"defaults"` reads them:
+/// `{ verb: { attribute: value } }`. The kernel fills a reaction's command from this the same way
+/// the host fills the outermost one.
+pub fn defaults_table(domain_ir: &Value) -> Value {
+    let domain = domain_ir.get("name").and_then(Value::as_str).unwrap_or_default();
+    let mut verbs = serde_json::Map::new();
+    let aggregates = domain_ir.get("aggregates").and_then(Value::as_array).into_iter().flatten();
+    for aggregate in aggregates {
+        let aggregate_name = aggregate.get("name").and_then(Value::as_str).unwrap_or_default();
+        for command in aggregate.get("commands").and_then(Value::as_array).into_iter().flatten() {
+            let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+            let verb = format!("{domain}::{aggregate_name}.{command_name}");
+            let defaults: serde_json::Map<String, Value> = declared_defaults(domain_ir, &verb)
+                .into_iter()
+                .map(|(name, value)| (name.to_string(), value.clone()))
+                .collect();
+            if !defaults.is_empty() {
+                verbs.insert(verb, Value::Object(defaults));
+            }
+        }
+    }
+    Value::Object(verbs)
+}
+
 /// The facts of a command invocation: the `with` object when the call carries one, else the
 /// flat object itself (the kernel's `CommandInvocation` reads both shapes).
 fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
@@ -147,6 +193,22 @@ pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn C
     }
 }
 
+/// Gives each argument `verb` declares a default for, and `args` leaves out, that default, after
+/// `fill_needs` and before any gate reads the arguments. A key the caller supplied (even a null)
+/// is kept, as is a fact `fill_needs` already answered.
+pub fn fill_defaults(domain_ir: &Value, verb: &str, args: &mut Value) {
+    let defaults = declared_defaults(domain_ir, verb);
+    if defaults.is_empty() {
+        return;
+    }
+    let Some(facts) = facts_mut(args) else { return };
+    for (name, value) in defaults {
+        if !facts.contains_key(name) {
+            facts.insert(name.to_string(), value.clone());
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -240,4 +302,53 @@ mod tests {
         clear_fixed_clock();
         assert!(ProcessClock.now_secs() > 1_700_000_000);
     }
+
+    // A command with one defaulted attribute, one plain, and one whose default is null.
+    fn defaulted_ir() -> Value {
+        json!({"name": "Qc", "aggregates": [{"name": "Check", "commands": [
+            {"name": "Start", "attributes": [
+                {"name": "ref", "type": "Ref", "default": null},
+                {"name": "runs", "type": "Count", "default": 30},
+                {"name": "note", "type": "String", "default": null}
+            ], "needs": []}
+        ]}]})
+    }
+
+    #[test]
+    fn an_omitted_argument_is_filled_with_its_declared_default() {
+        let mut args = json!({"with": {"ref": {"value": "a"}}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["with"]["runs"], 30);
+        assert!(args["with"].get("note").is_none(), "a null default declares none");
+    }
+
+    #[test]
+    fn a_flat_invocation_gets_its_defaults_at_its_top_level() {
+        let mut args = json!({"ref": {"value": "a"}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["runs"], 30);
+    }
+
+    #[test]
+    fn a_supplied_argument_is_kept_even_when_null() {
+        let mut args = json!({"runs": null});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert!(args["runs"].is_null());
+        let mut args = json!({"runs": {"value": 7}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["runs"], json!({"value": 7}));
+    }
+
+    #[test]
+    fn a_command_that_declares_no_default_is_untouched() {
+        let mut args = json!({"with": {}});
+        fill_defaults(&integer_ir(), "Qc::Check.Run", &mut args);
+        assert_eq!(args, json!({"with": {}}));
+    }
+
+    #[test]
+    fn the_kernel_table_lists_each_command_that_declares_a_default() {
+        assert_eq!(defaults_table(&defaulted_ir()), json!({"Qc::Check.Start": {"runs": 30}}));
+        assert_eq!(defaults_table(&integer_ir()), json!({}));
+    }
 }

data/rust/parser/src/keywords.rs

@@ -182,9 +182,9 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "answers_query", context: "DomainPort", body: "none", inner: "", opens: "", fills: "answered_queries", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "hecksagon", context: "File", body: "keywords", inner: "Hecksagon", opens: "Hecksagon", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "subscribe", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_framework", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "attaches", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attached_chapters", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "attaches", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "uses_framework", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "port", context: "Hecksagon", body: "keywords", inner: "DomainPort", opens: "DomainPort", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "translates", context: "Hecksagon", body: "keywords", inner: "Policy", opens: "Policy", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "bounded", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
@@ -466,9 +466,10 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "asks", context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "hecksagon", context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "subscribe", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_framework", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attached_chapters", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "", named: "from", kind: "symbol", required: "false", fills: "source", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "uses_framework", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "port", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "translates", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "reference_to", context: "PortOperation", at: "1", named: "", kind: "constant", required: "true", fills: "type", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/main.rs

@@ -91,7 +91,8 @@ fn run_chapter(args: &[String]) -> Result<(), RunError> {
 }
 
 /// `hecks-parse resolve --chapter <Name> <file.hecksagon>`: prints that chapter's
-/// `uses_framework` and `uses_embryonaut_bluebook` names as JSON, in file order.
+/// `attaches` names as JSON, in file order: `gem_chapters` for a chapter the gem carries and
+/// `vendored_packages` for `from: :vendor`.
 ///
 /// `--chapter` is required because one file can hold several `Hecks.hecksagon` blocks.
 fn run_resolve(args: &[String]) -> Result<(), RunError> {
@@ -120,7 +121,7 @@ fn run_resolve(args: &[String]) -> Result<(), RunError> {
     let value = emit::JsonValue::Object(vec![
         ("domain".to_string(), emit::JsonValue::String(chapter_name)),
         (
-            "uses_framework".to_string(),
+            "gem_chapters".to_string(),
             emit::JsonValue::Array(
                 framework_names
                     .into_iter()
@@ -129,7 +130,7 @@ fn run_resolve(args: &[String]) -> Result<(), RunError> {
             ),
         ),
         (
-            "uses_embryonaut_bluebook".to_string(),
+            "vendored_packages".to_string(),
             emit::JsonValue::Array(
                 vendored_names
                     .into_iter()

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

@@ -306,7 +306,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
     Ok(bluebook)
 }
 
-/// Lists the chapters `<Name>`'s block pulls in via `uses_framework`/`uses_embryonaut_bluebook`.
+/// Lists the chapters `<Name>`'s block pulls in via `attaches` (or its deprecated spellings).
 /// Every block is still gated; the IR accumulator is a throwaway.
 pub fn resolve_hecksagon_dependencies(
     chapter_name: &str,

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

@@ -1,4 +1,4 @@
-//! The `Hecksagon` construct: a `.hecksagon` file's `port` blocks and `uses_framework` words.
+//! The `Hecksagon` construct: a `.hecksagon` file's `port` blocks and `attaches` words.
 //! Adapter binds (`persisted_by`, `projected_by`, `subscribe`) are shape-matched and dropped.
 
 use super::domain_port;
@@ -14,8 +14,10 @@ pub fn not_implemented(file: &str, line: usize, word: &str) -> Diagnostic {
 /// Applies a `.hecksagon` body onto an already-built `ir::Bluebook`, attaching
 /// aggregate-scoped ports to the aggregates the sibling `.bluebook` registered.
 ///
-/// `uses_framework_names` and `vendored_bluebook_names` collect each argument in file order
-/// for `hecks-parse resolve`; `ir.json` itself carries neither.
+/// `gem_chapter_names` collects each `attaches "Name"` (and the deprecated `uses_framework`) and
+/// `vendored_bluebook_names` each `attaches "name", from: :vendor` (and the deprecated
+/// `uses_embryonaut_bluebook`), in file order, for `hecks-parse resolve`; `ir.json` itself
+/// carries neither.
 ///
 /// `require_matching_aggregate` is `false` for resolve, which never sees a `.bluebook`, so an
 /// aggregate-scoped `port` skips the attach step instead of failing the lookup.
@@ -24,7 +26,7 @@ pub fn apply(
     lines: &[SourceLine],
     pos: &mut usize,
     bluebook: &mut ir::Bluebook,
-    uses_framework_names: &mut Vec<String>,
+    gem_chapter_names: &mut Vec<String>,
     vendored_bluebook_names: &mut Vec<String>,
     require_matching_aggregate: bool,
 ) -> ParseResult<()> {
@@ -96,9 +98,9 @@ pub fn apply(
                     let built = policy::parse_body(file, lines, pos, &name)?;
                     bluebook.policies.push(built);
                 }
-                // Gated, then collected; `ir.json` carries no `uses_framework` key.
+                // Deprecated spelling of `attaches "Name"`; gated, then collected.
                 "uses_framework" => {
-                    uses_framework_names.push(super::positional_text(
+                    gem_chapter_names.push(super::positional_text(
                         file,
                         gated.line.number,
                         "uses_framework",
@@ -106,7 +108,7 @@ pub fn apply(
                         1,
                     )?);
                 }
-                // Collected like `uses_framework`; a binding fact, absent from `ir.json`.
+                // Deprecated spelling of `attaches "name", from: :vendor`; collected the same way.
                 "uses_embryonaut_bluebook" => {
                     vendored_bluebook_names.push(super::positional_text(
                         file,
@@ -117,10 +119,23 @@ pub fn apply(
                     )?);
                 }
                 "subscribe" => {}
-                // A chapter the gem carries, attached by name (ADR 0080); only the Ruby runtime
-                // loads it, so its one argument is checked and then dropped like `subscribe`.
+                // One word for a chapter the gem carries and for a vendored package; a binding
+                // fact collected for `resolve`, absent from `ir.json`. Only `from: :vendor`
+                // is admitted as a source, and anything else is refused.
                 "attaches" => {
-                    super::positional_text(file, gated.line.number, "attaches", &gated.args, 1)?;
+                    let name =
+                        super::positional_text(file, gated.line.number, "attaches", &gated.args, 1)?;
+                    match super::named_symbol(&gated.args, "from").as_deref() {
+                        None => gem_chapter_names.push(name),
+                        Some("vendor") => vendored_bluebook_names.push(name),
+                        Some(other) => {
+                            return Err(Diagnostic::new(
+                                file,
+                                gated.line.number,
+                                format!("'attaches' from: takes only :vendor, got :{other}"),
+                            ))
+                        }
+                    }
                 }
                 // Consumer-owned bounded-context mark; a wiring fact, dropped like `subscribe`.
                 "bounded" => {}

data/rust/project/mutations.rb

@@ -1,3 +1,5 @@
+require "hecks/rust_build/append_optionals"
+
 module RustProjection
   module Projector
     module_function
@@ -60,13 +62,7 @@ module RustProjection
 
     # Resolves an `append` target to its entity or value object, or nil if it is neither.
     def append_element(aggregate, target_type, value_objects_by_name)
-      # LOCAL FIRST — an aggregate's own nested entity is scoped to that
-      # Local entities win over the domain-wide value objects: Syntax's local `Argument` entity
-      # shares a name with Command's `Argument` value object.
-      local = aggregate[:entities].find { |e| e[:name] == target_type }
-      return local if local
-
-      value_objects_by_name[target_type]
+      Hecks::RustBuild::AppendOptionals.element(aggregate, target_type, value_objects_by_name)
     end
 
     # Identity attribute and its single-field value object for an auto-minted entity element,
@@ -454,29 +450,7 @@ module RustProjection
     # attribute
     # hash once, before the emitters read it, and never resets a `true`.
     def mark_append_optional_fields!(aggregate, value_objects_by_name)
-      aggregate[:attributes].each do |target_attr|
-        element = append_element(aggregate, target_attr[:type], value_objects_by_name)
-        next unless element
-
-        aggregate[:commands].each do |command|
-          command[:mutations].each do |m|
-            next unless m[:op].to_s == "append" && m[:target].to_s == target_attr[:name].to_s
-
-            m[:fields].each do |field_name, source|
-              # A Symbol is an argument name (optional ones are what this pass wants); else a
-              # literal.
-              parsed = append_field_source(source)
-              next unless parsed.is_a?(Symbol)
-
-              source_attr = command[:attributes].find { |a| a[:name].to_s == parsed.to_s }
-              next unless source_attr && source_attr[:optional]
-
-              field_attr = element[:attributes].find { |a| a[:name].to_s == field_name.to_s }
-              field_attr[:optional] = true if field_attr
-            end
-          end
-        end
-      end
+      Hecks::RustBuild::AppendOptionals.mark_aggregate(aggregate, value_objects_by_name)
     end
 
     # Derives the mutations of a `corrects EVENT, reverses: true` command from the commands that

data/rust/project/naming.rb

@@ -1,5 +1,7 @@
 require "hecks/vocabulary"
 require "hecks/bluebook/model_check"
+require "hecks/rust_build/domain_name"
+require "hecks/rust_build/rust_literal"
 
 module RustProjection
   # Domain-to-Rust codegen support: type mapping, reserved-name checks, and
@@ -59,15 +61,10 @@ module RustProjection
     # feature set.
     #
     # Declared once as the `CargoReservedName` vocabulary.
-    CARGO_RESERVED_DOMAIN_NAMES = Hecks::Vocabulary.fetch("CargoReservedName")
-
-    # Checks identifier shape locally; delegates the reserved-word half to
-    # `ModelCheck.rust_reserved_name_findings`, the one shared check.
-    def valid_domain_mod_name?(name)
-      str = name.to_s
-      str.match?(/\A[a-z_][a-z0-9_]*\z/) &&
-        Hecks::Bluebook::ModelCheck.rust_reserved_name_findings(domain_name: str).empty?
-    end
+    CARGO_RESERVED_DOMAIN_NAMES = Hecks::RustBuild::DomainName::CARGO_RESERVED
+
+    # Moved to `Hecks::RustBuild::DomainName`, which the codegen-backed `hecks project_rust` uses.
+    def valid_domain_mod_name?(name) = Hecks::RustBuild::DomainName.valid?(name)
 
     # Identifier-shape check only (a PascalCase name always passes); whether
     # the downcased name is a Rust keyword is `reserved_name_refusal`'s job,
@@ -220,24 +217,7 @@ module RustProjection
       end
     end
 
-    # Ruby's String#inspect escapes for Ruby's own read-back (e.g. a
-    # brace-less `\uXXXX`), which isn't valid Rust syntax. This escapes
-    # only what Rust's string-literal grammar needs: backslash,
-    # double-quote, and control characters.
-    def rust_string_literal(str)
-      escaped = str.to_s.each_char.map do |ch|
-        case ch
-        when "\\" then "\\\\"
-        when "\"" then "\\\""
-        when "\n" then "\\n"
-        when "\r" then "\\r"
-        when "\t" then "\\t"
-        else
-          cp = ch.ord
-          cp < 0x20 || cp == 0x7F ? format("\\u{%x}", cp) : ch
-        end
-      end.join
-      "\"#{escaped}\""
-    end
+    # Moved to `Hecks::RustBuild::RustLiteral`, which the codegen-backed `hecks project_rust` uses.
+    def rust_string_literal(str) = Hecks::RustBuild::RustLiteral.string(str)
   end
 end