hecks 4.0.0 → 6.0.0

data/rust/codegen/src/presenters.rs

@@ -0,0 +1,335 @@
+//! The bare answer shape, generated: a port of Ruby's `Value.materialize_unwrapped`, emitted as
+//! type-directed Rust over `crate::kernel::Json`.
+//!
+//! A single-attribute value object answers as its sole field's value, a multi-field one as an
+//! object of its fields, each unwrapped the same way; a list maps item-wise and an entity's
+//! fields are unwrapped. Stored state stays wrapped: this is only what a caller is answered with
+//! (`group_by` rows, and the kernel's `{"present": answer}` input).
+
+use crate::json::Json;
+use crate::registry::AggregateEntry;
+use std::collections::HashMap;
+
+/// Emits an expression unwrapping the `Json` named `expr` as a `type_name` (a `list` of them
+/// when `list`), resolving value objects in `value_objects_by_name` and entities in `aggregate`.
+pub fn unwrap_json_expr(
+    expr: &str,
+    type_name: &str,
+    list: bool,
+    aggregate: &Json,
+    value_objects_by_name: &HashMap<String, &Json>,
+) -> String {
+    Unwrapper {
+        aggregate,
+        value_objects_by_name,
+    }
+    .expr(expr, type_name, list, &mut Vec::new())
+}
+
+/// Emits `pub fn present(state) -> Json` for one aggregate's module: its state (or one of its
+/// events' payloads) with every field it declares unwrapped, other keys passed through.
+///
+/// The fields are the aggregate's attributes and projected fields, then every aggregate and
+/// entity command argument not already named, since an event payload carries a command's
+/// arguments. A name declared with more than one type unwraps by whichever type's field names
+/// the value's own keys fit, first declared first.
+pub fn emit_aggregate_presenter(
+    aggregate: &Json,
+    value_objects_by_name: &HashMap<String, &Json>,
+) -> String {
+    let unwrapper = Unwrapper {
+        aggregate,
+        value_objects_by_name,
+    };
+    let arms: Vec<String> = presented_fields(aggregate)
+        .iter()
+        .map(|(name, candidates)| format!("{name:?} => {},", unwrapper.candidates("v", candidates)))
+        .collect();
+    if arms.is_empty() {
+        return format!("{PRESENT_DOC}pub fn present(state: crate::kernel::Json) -> crate::kernel::Json {{\n    state\n}}\n");
+    }
+    let arms = arms.join(" ");
+    format!(
+        "{PRESENT_DOC}pub fn present(state: crate::kernel::Json) -> crate::kernel::Json {{\n    match state {{ crate::kernel::Json::Object(fields) => crate::kernel::Json::Object(fields.into_iter().map(|(k, v)| {{ let new_v = match k.as_str() {{ {arms} _ => v }}; (k, new_v) }}).collect()), other => other }}\n}}\n"
+    )
+}
+
+const PRESENT_DOC: &str = "/// This aggregate's state, or one of its events' payloads, as a caller is answered with\n/// it: each single-field value object as its bare field (the shape a command takes it in).\n";
+
+/// Emits the merged target's `present(aggregate, state)`: one arm per generated aggregate across
+/// every bluebook, keyed by its qualified `Domain::Aggregate` name; any other name passes through.
+pub fn emit_present_router(aggregates: &[AggregateEntry]) -> String {
+    let arms: Vec<String> = aggregates
+        .iter()
+        .map(|a| {
+            format!(
+                "        {} => crate::generated::{}::{}::present(state),",
+                crate::naming::ruby_inspect_string(&format!("{}::{}", a.domain_name, a.name)),
+                a.bluebook_mod,
+                a.module_name
+            )
+        })
+        .collect();
+    format!(
+        "/// One `\"Domain::Aggregate\"` state as a caller is answered with it (the kernel's\n/// `{{\"present\": answer}}` input); stored state stays wrapped. An unknown name passes through.\npub fn present(aggregate: &str, state: crate::kernel::Json) -> crate::kernel::Json {{\n    match aggregate {{\n{}\n        _ => state,\n    }}\n}}\n",
+        arms.join("\n")
+    )
+}
+
+// Each presented name with its distinct declared (type, list) pairs, in declaration order.
+fn presented_fields(aggregate: &Json) -> Vec<(String, Vec<(String, bool)>)> {
+    let mut attributes: Vec<Json> = aggregate
+        .get("attributes")
+        .map_or_default(Json::each)
+        .to_vec();
+    attributes.extend(crate::types::projected_field_pseudo_attributes(aggregate));
+    let commands = aggregate
+        .get("commands")
+        .map_or_default(Json::each)
+        .iter()
+        .chain(
+            aggregate
+                .get("entities")
+                .map_or_default(Json::each)
+                .iter()
+                .flat_map(|e| e.get("commands").map_or_default(Json::each)),
+        );
+    for command in commands {
+        attributes.extend(
+            command
+                .get("attributes")
+                .map_or_default(Json::each)
+                .iter()
+                .cloned(),
+        );
+    }
+
+    let mut fields: Vec<(String, Vec<(String, bool)>)> = Vec::new();
+    for attribute in &attributes {
+        let name = crate::attr::name(attribute).to_string();
+        let candidate = (
+            crate::attr::type_name(attribute).to_string(),
+            crate::attr::list(attribute),
+        );
+        match fields.iter_mut().find(|(n, _)| *n == name) {
+            Some((_, candidates)) if !candidates.contains(&candidate) => candidates.push(candidate),
+            Some(_) => {}
+            None => fields.push((name, vec![candidate])),
+        }
+    }
+    fields
+}
+
+struct Unwrapper<'a> {
+    aggregate: &'a Json,
+    value_objects_by_name: &'a HashMap<String, &'a Json>,
+}
+
+impl Unwrapper<'_> {
+    // The declared fields of a value object or entity type, and whether it is a value object.
+    fn fields_of(&self, type_name: &str) -> Option<(&[Json], bool)> {
+        if let Some(vo) = self.value_objects_by_name.get(type_name) {
+            return vo.get("attributes").map(|a| (Json::each(a), true));
+        }
+        self.aggregate
+            .get("entities")
+            .map_or_default(Json::each)
+            .iter()
+            .find(|e| e.get("name").map(Json::to_s).unwrap_or_default() == type_name)
+            .and_then(|e| e.get("attributes").map(|a| (Json::each(a), false)))
+    }
+
+    // `seen` holds the types being expanded, so a type that contains itself stops there and
+    // passes its nested value through rather than recursing without end.
+    fn expr(&self, expr: &str, type_name: &str, list: bool, seen: &mut Vec<String>) -> String {
+        if list {
+            let inner = self.expr("item", type_name, false, seen);
+            return format!("match {expr} {{ crate::kernel::Json::Array(items) => crate::kernel::Json::Array(items.into_iter().map(|item| {inner}).collect()), other => other }}");
+        }
+        let Some((fields_meta, is_value_object)) = self.fields_of(type_name) else {
+            return expr.to_string();
+        };
+        if seen.iter().any(|s| s == type_name) {
+            return expr.to_string();
+        }
+        seen.push(type_name.to_string());
+        let out = if is_value_object && fields_meta.len() == 1 {
+            let field = &fields_meta[0];
+            let unwrapped = self.expr(
+                "field_value",
+                crate::attr::type_name(field),
+                crate::attr::list(field),
+                seen,
+            );
+            let field_name = crate::attr::name(field);
+            format!("match {expr} {{ crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == {field_name:?}).map_or(crate::kernel::Json::Null, |(_, field_value)| {unwrapped}), other => other }}")
+        } else {
+            let inner_arms: Vec<String> = fields_meta
+                .iter()
+                .map(|f| {
+                    let unwrapped =
+                        self.expr("v", crate::attr::type_name(f), crate::attr::list(f), seen);
+                    format!("{:?} => {unwrapped},", crate::attr::name(f))
+                })
+                .collect();
+            let inner_arms = inner_arms.join(" ");
+            format!("match {expr} {{ crate::kernel::Json::Object(fields) => crate::kernel::Json::Object(fields.into_iter().map(|(k, v)| {{ let new_v = match k.as_str() {{ {inner_arms} _ => v }}; (k, new_v) }}).collect()), other => other }}")
+        };
+        seen.pop();
+        out
+    }
+
+    // One declared type unwraps unconditionally; several are told apart by the value's keys.
+    fn candidates(&self, expr: &str, candidates: &[(String, bool)]) -> String {
+        if let [(type_name, list)] = candidates {
+            return self.expr(expr, type_name, *list, &mut Vec::new());
+        }
+        let branches: Vec<String> = candidates
+            .iter()
+            .filter_map(|(type_name, list)| {
+                let guard = self.fits(&format!("&{expr}"), type_name, *list)?;
+                let unwrapped = self.expr(expr, type_name, *list, &mut Vec::new());
+                Some(format!("if {guard} {{ {unwrapped} }}"))
+            })
+            .collect();
+        if branches.is_empty() {
+            return expr.to_string();
+        }
+        format!("{} else {{ {expr} }}", branches.join(" else "))
+    }
+
+    // Whether the value at `expr` (a `&Json`) has the shape of `type_name`: an object whose keys
+    // are all its declared fields. `None` for a type with no fields to unwrap.
+    fn fits(&self, expr: &str, type_name: &str, list: bool) -> Option<String> {
+        if list {
+            let item = self.fits("item", type_name, false)?;
+            return Some(format!("matches!({expr}, crate::kernel::Json::Array(items) if items.iter().all(|item| {item}))"));
+        }
+        let (fields_meta, _) = self.fields_of(type_name)?;
+        let names: Vec<String> = fields_meta
+            .iter()
+            .map(|f| format!("{:?}", crate::attr::name(f)))
+            .collect();
+        Some(format!("matches!({expr}, crate::kernel::Json::Object(fields) if fields.iter().all(|(k, _)| matches!(k.as_str(), {})))", names.join(" | ")))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn attribute(name: &str, type_name: &str, list: bool) -> String {
+        format!(r#"{{"name": "{name}", "type": "{type_name}", "list": {list}}}"#)
+    }
+
+    fn value_object(name: &str, attributes: &[String]) -> String {
+        format!(
+            r#"{{"name": "{name}", "attributes": [{}]}}"#,
+            attributes.join(", ")
+        )
+    }
+
+    // Pizzas' `Order`, cut down: a single-field name, a multi-field pizza holding two
+    // single-field value objects, a list of single-field tags, and two commands that both
+    // take an `amount` of a different single-field type.
+    fn order() -> Json {
+        let text = format!(
+            r#"{{"name": "Order",
+                "attributes": [{}, {}, {}],
+                "value_objects": [{}, {}, {}, {}, {}, {}],
+                "commands": [
+                  {{"name": "CreatePizza", "attributes": [{}, {}]}},
+                  {{"name": "AddTopping", "attributes": [{}]}},
+                  {{"name": "Purchase", "attributes": [{}]}}
+                ]}}"#,
+            attribute("name", "PizzaName", false),
+            attribute("pizza", "Pizza", false),
+            attribute("tags", "Tag", true),
+            value_object("PizzaName", &[attribute("value", "String", false)]),
+            value_object("Price", &[attribute("cents", "Integer", false)]),
+            value_object("Size", &[attribute("value", "String", false)]),
+            value_object("Tag", &[attribute("value", "String", false)]),
+            value_object("ToppingAmount", &[attribute("value", "Integer", false)]),
+            value_object(
+                "Pizza",
+                &[
+                    attribute("price_cents", "Price", false),
+                    attribute("size", "Size", false)
+                ]
+            ),
+            attribute("name", "PizzaName", false),
+            attribute("pizza", "Pizza", false),
+            attribute("amount", "ToppingAmount", false),
+            attribute("amount", "Price", false),
+        );
+        Json::parse(&text).unwrap()
+    }
+
+    fn presenter() -> String {
+        let order = order();
+        let vos: Vec<&Json> = order
+            .get("value_objects")
+            .map_or_default(Json::each)
+            .iter()
+            .collect();
+        let by_name: HashMap<String, &Json> = vos
+            .iter()
+            .map(|vo| (vo.get("name").map(Json::to_s).unwrap_or_default(), *vo))
+            .collect();
+        emit_aggregate_presenter(&order, &by_name)
+    }
+
+    #[test]
+    fn a_single_field_attribute_presents_as_its_sole_field() {
+        assert!(presenter().contains(r#""name" => match v { crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == "value")"#));
+    }
+
+    #[test]
+    fn a_multi_field_value_object_keeps_its_object_and_unwraps_each_field() {
+        let text = presenter();
+        assert!(text.contains(r#""pizza" => match v { crate::kernel::Json::Object(fields) => crate::kernel::Json::Object("#));
+        assert!(text.contains(r#""price_cents" => match v { crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == "cents")"#));
+        assert!(text.contains(r#""size" => match v { crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == "value")"#));
+    }
+
+    #[test]
+    fn a_list_of_single_field_value_objects_maps_item_wise() {
+        assert!(presenter().contains(r#""tags" => match v { crate::kernel::Json::Array(items) => crate::kernel::Json::Array(items.into_iter().map(|item| match item { crate::kernel::Json::Object(fields) => fields.into_iter().find(|(k, _)| k == "value")"#));
+    }
+
+    #[test]
+    fn a_name_declared_with_two_types_is_told_apart_by_its_keys() {
+        let text = presenter();
+        let arm = text.split(r#""amount" => "#).nth(1).unwrap();
+        assert!(arm.starts_with(r#"if matches!(&v, crate::kernel::Json::Object(fields) if fields.iter().all(|(k, _)| matches!(k.as_str(), "value")))"#));
+        assert!(arm.contains(r#"else if matches!(&v, crate::kernel::Json::Object(fields) if fields.iter().all(|(k, _)| matches!(k.as_str(), "cents")))"#));
+    }
+
+    #[test]
+    fn a_command_argument_already_named_by_an_attribute_adds_no_second_arm() {
+        assert_eq!(presenter().matches(r#""name" => "#).count(), 1);
+    }
+
+    #[test]
+    fn the_router_names_each_aggregate_qualified_and_passes_any_other_through() {
+        let entry = AggregateEntry {
+            name: "Order".to_string(),
+            module_name: "order".to_string(),
+            record: "Order".to_string(),
+            commands: vec![],
+            entity_commands: vec![],
+            nested_entity_commands: vec![],
+            ports: vec![],
+            bluebook_mod: "pizzas".to_string(),
+            domain_name: "Pizzas".to_string(),
+            reference_specs: vec![],
+            identified_by: vec![],
+            entities: vec![],
+        };
+        let text = emit_present_router(&[entry]);
+        assert!(
+            text.contains(r#""Pizzas::Order" => crate::generated::pizzas::order::present(state),"#)
+        );
+        assert!(text.contains("_ => state,"));
+    }
+}

data/rust/codegen/src/queries.rs

@@ -228,8 +228,23 @@ pub fn query_where_skip_reason(
     if raw_value.starts_with(':') {
         return None;
     }
-
     let op = where_clause.get("op").map(Json::to_s).unwrap_or_default();
+    // `eq`/`ne` against nil is `QueryConditionValue::Null`; an ordered or membership comparison
+    // against nil means nothing in Ruby either, so it has no generated form.
+    if raw_value == "nil" {
+        if matches!(op.as_str(), "eq" | "ne") {
+            return None;
+        }
+        return Some(skip(
+            "where_literal",
+            format!(
+                "where clause on {} uses op {} against nil — only eq and ne compare a field to nil, so this has no generated form",
+                naming::ruby_inspect_string(&field),
+                naming::ruby_inspect_string(&op)
+            ),
+        ));
+    }
+
     if !known_query_comparator(&op) {
         return Some(skip(
             "where_none_in_state",
@@ -374,7 +389,7 @@ pub fn query_skip_reason(
     value_objects_by_name: &HashMap<String, &Json>,
     aggregates_by_name: &HashMap<String, &Json>,
 ) -> Option<SkipReason> {
-    let extra_keys = ["cursor", "consistency", "freshness", "inspection"];
+    let extra_keys = ["consistency", "freshness", "inspection"];
     let extras: Vec<&str> = extra_keys
         .iter()
         .filter(|k| query.get(k).is_some())
@@ -842,6 +857,7 @@ pub fn emit_query_condition_value(condition: &Condition) -> String {
                 "crate::kernel::QueryConditionValue::NumericLiteral({})",
                 ruby_float_inspect(*n)
             ),
+            Literal::Nil => "crate::kernel::QueryConditionValue::Null".to_string(),
             _ => format!(
                 "crate::kernel::QueryConditionValue::Literal({})",
                 literal_inspect(lit)
@@ -871,8 +887,10 @@ pub struct QueryDef {
     pub order_by: Option<String>,
     pub offset: Option<String>,
     pub limit: Option<String>,
+    /// `cursor` is declared: `limit` is the page size and `after` names the position.
+    pub cursor: bool,
     pub authorization: Option<String>,
-    /// True when the chapter's `provides "authorization", assignments:` names this query.
+    /// True when the bluebook's `provides "authorization", live_assignments:` names this query.
     pub assignments: bool,
     /// `Some` for a declared entity query — emitted into `ENTITY_QUERIES`.
     pub entity: Option<EntityScope>,
@@ -884,7 +902,7 @@ pub fn provided_assignments(ir: &Json) -> Option<String> {
         .iter()
         .find(|row| {
             row.get("capability").and_then(Json::as_str) == Some("authorization")
-                && row.get("key").and_then(Json::as_str) == Some("assignments")
+                && row.get("key").and_then(Json::as_str) == Some("live_assignments")
         })
         .and_then(|row| row.get("verb").and_then(Json::as_str))
         .map(str::to_string)
@@ -896,7 +914,7 @@ pub fn emit_authorization_assignments(query_defs: &[QueryDef]) -> String {
         |q| format!("Some({})", naming::ruby_inspect_string(&q.verb)),
     );
     format!(
-        "/// `provides \"authorization\", assignments:` — the query `kernel::check_role_via` reads; `None` when no chapter here declares one.\npub const AUTHORIZATION_ASSIGNMENTS: Option<&str> = {value};\n"
+        "/// `provides \"authorization\", live_assignments:` — the query `kernel::check_role_via` reads; `None` when no bluebook here declares one.\npub const AUTHORIZATION_ASSIGNMENTS: Option<&str> = {value};\n"
     )
 }
 
@@ -1008,14 +1026,15 @@ pub fn emit_query_def(query_def: &QueryDef) -> String {
         .as_ref()
         .map_or_else(|| "None".to_string(), |a| format!("Some({a})"));
 
+    let cursor = query_def.cursor;
     format!(
-        "crate::kernel::QueryDef {{\n    verb: {},\n    aggregate: {},\n    conditions: &[\n{conditions}\n    ],\n    reference_hop_conditions: &[\n{reference_hop_conditions}\n    ],\n    order_by: {order_by},\n    offset: {offset},\n    limit: {limit},\n    authorization: {authorization},\n}},",
+        "crate::kernel::QueryDef {{\n    verb: {},\n    aggregate: {},\n    conditions: &[\n{conditions}\n    ],\n    reference_hop_conditions: &[\n{reference_hop_conditions}\n    ],\n    order_by: {order_by},\n    offset: {offset},\n    limit: {limit},\n    cursor: {cursor},\n    authorization: {authorization},\n}},",
         naming::ruby_inspect_string(&query_def.verb),
         naming::ruby_inspect_string(&query_def.aggregate)
     )
 }
 
-const QUERY_TABLE_ROW_PLACEHOLDER: &str = "crate::kernel::QueryDef {\n    verb: \"tmpl_verb\",\n    aggregate: \"tmpl_aggregate\",\n    conditions: &[\n        crate::kernel::QueryCondition {\n            field: \"tmpl_field\",\n            comparator: crate::kernel::query_comparators::QueryComparator::Eq,\n            value: crate::kernel::QueryConditionValue::Literal(\"tmpl_literal\"),\n        },\n    ],\n    reference_hop_conditions: &[\n        crate::kernel::read_model::ReferenceHopCondition {\n            via_field: \"tmpl_via_field\",\n            target_aggregate: \"tmpl_target_aggregate\",\n            through: &[crate::kernel::read_model::HopStep { via_field: \"tmpl_via_field\", target_aggregate: \"tmpl_target_aggregate\" }],\n            inner_field: \"tmpl_inner_field\",\n            inner_comparator: crate::kernel::query_comparators::QueryComparator::Eq,\n            inner_value: crate::kernel::QueryConditionValue::Literal(\"tmpl_literal\"),\n        },\n    ],\n    order_by: Some(crate::kernel::query_ordering::OrderBy { field: \"tmpl_order_field\", descending: true, nulls: crate::kernel::query_ordering::NullsMode::Last }),\n    offset: Some(crate::kernel::query_ordering::Offset::Literal(1)),\n    limit: Some(crate::kernel::query_ordering::Limit::Literal(5)),\n    authorization: Some(crate::kernel::named_query::TenantAuth { query_name: \"tmpl_query_name\", tenant_field: \"tmpl_tenant_field\", policy: \"tmpl_policy\" }),\n},";
+const QUERY_TABLE_ROW_PLACEHOLDER: &str = "crate::kernel::QueryDef {\n    verb: \"tmpl_verb\",\n    aggregate: \"tmpl_aggregate\",\n    conditions: &[\n        crate::kernel::QueryCondition {\n            field: \"tmpl_field\",\n            comparator: crate::kernel::query_comparators::QueryComparator::Eq,\n            value: crate::kernel::QueryConditionValue::Literal(\"tmpl_literal\"),\n        },\n    ],\n    reference_hop_conditions: &[\n        crate::kernel::read_model::ReferenceHopCondition {\n            via_field: \"tmpl_via_field\",\n            target_aggregate: \"tmpl_target_aggregate\",\n            through: &[crate::kernel::read_model::HopStep { via_field: \"tmpl_via_field\", target_aggregate: \"tmpl_target_aggregate\" }],\n            inner_field: \"tmpl_inner_field\",\n            inner_comparator: crate::kernel::query_comparators::QueryComparator::Eq,\n            inner_value: crate::kernel::QueryConditionValue::Literal(\"tmpl_literal\"),\n        },\n    ],\n    order_by: Some(crate::kernel::query_ordering::OrderBy { field: \"tmpl_order_field\", descending: true, nulls: crate::kernel::query_ordering::NullsMode::Last }),\n    offset: Some(crate::kernel::query_ordering::Offset::Literal(1)),\n    limit: Some(crate::kernel::query_ordering::Limit::Literal(5)),\n    cursor: false,\n    authorization: Some(crate::kernel::named_query::TenantAuth { query_name: \"tmpl_query_name\", tenant_field: \"tmpl_tenant_field\", policy: \"tmpl_policy\" }),\n},";
 
 pub fn emit_query_table(exemplar: &Exemplar, query_defs: &[QueryDef]) -> String {
     let (entity_defs, aggregate_defs): (Vec<&QueryDef>, Vec<&QueryDef>) =
@@ -1152,6 +1171,36 @@ mod path_tests {
         });
     }
 
+    #[test]
+    fn the_role_check_reads_the_live_assignments_query_not_every_assignment() {
+        let ir = Json::parse(
+            r#"{"provides":[
+                {"capability":"authorization","key":"assignments","verb":"G.All"},
+                {"capability":"authorization","key":"live_assignments","verb":"G.Live"}]}"#,
+        )
+        .unwrap();
+        assert_eq!(provided_assignments(&ir).as_deref(), Some("G.Live"));
+    }
+
+    #[test]
+    fn a_nil_comparison_is_generated_for_eq_and_ne_only() {
+        with_schema(|aggregate, vos| {
+            for op in ["eq", "ne"] {
+                let nil_title =
+                    Json::parse(&format!(r#"{{"field":"title","op":"{op}","value":"nil"}}"#))
+                        .unwrap();
+                assert!(query_where_skip_reason(&nil_title, aggregate, vos).is_none());
+            }
+            let ordered = Json::parse(r#"{"field":"title","op":"gt","value":"nil"}"#).unwrap();
+            let reason = query_where_skip_reason(&ordered, aggregate, vos).unwrap();
+            assert_eq!(reason.construct, "where_literal");
+            assert!(reason.text.contains("against nil"));
+            let open_title =
+                Json::parse(r#"{"field":"title","op":"eq","value":"\"open\""}"#).unwrap();
+            assert!(query_where_skip_reason(&open_title, aggregate, vos).is_none());
+        });
+    }
+
     #[test]
     fn booleans_and_numeric_types_follow_a_single_member_down() {
         with_schema(|aggregate, vos| {

data/rust/codegen/src/reactions.rs

@@ -132,11 +132,12 @@ fn cross_domain_policy_rows(domain_name: &str, policies: &[Json]) -> Vec<String>
             let name = policy.get("name").map(Json::to_s).unwrap_or_default();
 
             Some(format!(
-                "    crate::kernel::CrossDomainPolicyRule {{ policy_name: {}, event_name: {}, event_qualifier: {qualifier_expr}, target_domain: {}, target_verb: {}, where_expr: {} }},",
+                "    crate::kernel::CrossDomainPolicyRule {{ policy_name: {}, event_name: {}, event_qualifier: {qualifier_expr}, target_domain: {}, target_verb: {}, with_spec: {}, where_expr: {} }},",
                 naming::ruby_inspect_string(&name),
                 naming::ruby_inspect_string(&event_name),
                 naming::ruby_inspect_string(&target_domain),
                 naming::ruby_inspect_string(&target_verb),
+                with_spec_expr(policy),
                 where_expr(policy)
             ))
         })
@@ -157,13 +158,13 @@ pub fn emit_cross_domain_policy_table(
     exemplar.render(
         "cross_domain_policy_table",
         &[(
-            "crate::kernel::CrossDomainPolicyRule { policy_name: \"tmpl_policy_name\", event_name: \"tmpl_event_name\", event_qualifier: None, target_domain: \"tmpl_target_domain\", target_verb: \"tmpl_target_verb\", where_expr: None },",
+            "crate::kernel::CrossDomainPolicyRule { policy_name: \"tmpl_policy_name\", event_name: \"tmpl_event_name\", event_qualifier: None, target_domain: \"tmpl_target_domain\", target_verb: \"tmpl_target_verb\", with_spec: &[], where_expr: None },",
             rows.join("\n"),
         )],
     )
 }
 
-/// One chapter's policies for a merged-table call. `aggregates` feeds the fan-out
+/// One bluebook's policies for a merged-table call. `aggregates` feeds the fan-out
 /// addressing key of local rows only; cross-domain rows ignore it.
 pub struct PolicySource<'a> {
     pub domain_name: &'a str,
@@ -171,10 +172,10 @@ pub struct PolicySource<'a> {
     pub aggregates: &'a [Json],
 }
 
-/// The policy table for `merged.rs`, spanning the target domain and every attached chapter.
+/// The policy table for `merged.rs`, spanning the target domain and every attached bluebook.
 ///
 /// Each source's `target_verb` is qualified against its own domain, never the target's;
-/// omitting a chapter's policies would leave them out of the table `kernel::orchestrate` reads.
+/// omitting a bluebook's policies would leave them out of the table `kernel::orchestrate` reads.
 pub fn emit_merged_policy_table(exemplar: &Exemplar, sources: &[PolicySource]) -> String {
     let rows: Vec<String> = sources
         .iter()
@@ -198,7 +199,7 @@ pub fn emit_merged_policy_table(exemplar: &Exemplar, sources: &[PolicySource]) -
     }
 }
 
-/// The cross-domain policy table for `merged.rs`, folding in every attached chapter.
+/// The cross-domain policy table for `merged.rs`, folding in every attached bluebook.
 pub fn emit_merged_cross_domain_policy_table(
     exemplar: &Exemplar,
     sources: &[PolicySource],
@@ -215,7 +216,7 @@ pub fn emit_merged_cross_domain_policy_table(
     exemplar.render(
         "cross_domain_policy_table",
         &[(
-            "crate::kernel::CrossDomainPolicyRule { policy_name: \"tmpl_policy_name\", event_name: \"tmpl_event_name\", event_qualifier: None, target_domain: \"tmpl_target_domain\", target_verb: \"tmpl_target_verb\", where_expr: None },",
+            "crate::kernel::CrossDomainPolicyRule { policy_name: \"tmpl_policy_name\", event_name: \"tmpl_event_name\", event_qualifier: None, target_domain: \"tmpl_target_domain\", target_verb: \"tmpl_target_verb\", with_spec: &[], where_expr: None },",
             rows.join("\n"),
         )],
     )
@@ -372,8 +373,11 @@ pub fn emit_process_manager_table(exemplar: &Exemplar, process_managers: &[Json]
     )
 }
 
-pub fn emit_reference_key_table(exemplar: &Exemplar, chapters: &[(String, Vec<String>)]) -> String {
-    let arms: Vec<String> = chapters
+pub fn emit_reference_key_table(
+    exemplar: &Exemplar,
+    declarations: &[(String, Vec<String>)],
+) -> String {
+    let arms: Vec<String> = declarations
         .iter()
         .flat_map(|(domain_name, aggregate_names)| {
             aggregate_names.iter().map(move |name| {
@@ -625,7 +629,7 @@ mod tests {
     use super::*;
 
     // Mirrors the fixtures in `spec/rust_project/reactions_merge_spec.rb`; no real corpus
-    // domain exercises this merged-chapter shape.
+    // domain exercises this merged-bluebook shape.
     fn policy(
         name: &str,
         on_event: &str,
@@ -642,7 +646,7 @@ mod tests {
     }
 
     #[test]
-    fn merged_policy_table_carries_the_target_and_a_vendored_chapters_own_same_domain_policy() {
+    fn merged_policy_table_carries_the_target_and_a_vendored_bluebooks_own_same_domain_policy() {
         let orders_policies = vec![policy("OnOrderPlaced", "OrderPlaced", "Invoice.Open", None)];
         let payments_policies = vec![
             policy(
@@ -675,7 +679,7 @@ mod tests {
 
         // The target domain's own policy, qualified against its own domain.
         assert!(table.contains("target_verb: \"Orders::Invoice.Open\""));
-        // A vendored chapter's same-domain policy, qualified against its own domain.
+        // A vendored bluebook's same-domain policy, qualified against its own domain.
         assert!(table.contains("policy_name: \"OnPaymentConfirmedByProcessor\""));
         assert!(table.contains("target_verb: \"Payments::Payment.Succeed\""));
         // Cross-domain policies belong to the cross-domain table.
@@ -683,7 +687,8 @@ mod tests {
     }
 
     #[test]
-    fn merged_cross_domain_policy_table_carries_only_a_vendored_chapters_own_cross_domain_policy() {
+    fn merged_cross_domain_policy_table_carries_only_a_vendored_bluebooks_own_cross_domain_policy()
+    {
         let orders_policies = vec![policy("OnOrderPlaced", "OrderPlaced", "Invoice.Open", None)];
         let payments_policies = vec![
             policy(
@@ -714,7 +719,7 @@ mod tests {
 
         let table = emit_merged_cross_domain_policy_table(&Exemplar::load(), &sources);
 
-        // A vendored chapter's own cross-domain policy, qualified
+        // A vendored bluebook's own cross-domain policy, qualified
         // against its own trigger domain.
         assert!(table.contains("policy_name: \"OnPaymentFailed\""));
         assert!(table.contains("target_domain: \"Ledger\""));