hecks 1.3.0 → 1.5.0

data/lib/hecks/language/bluebook/vocabulary.bluebook

@@ -2,8 +2,11 @@ Hecks.bluebook "Bluebook" do
   aggregate "Vocabulary" do
     # These are DECLARATIONS, not runtime state — a language's admitted sets are
     # fixed when the language is defined, which is what one_of means. They carry
-    # no commands on purpose : nothing dispatches a vocabulary, the conformance
-    # check READS them from the IR and holds the runtime's hand-typed tables to them.
+    # no commands on purpose : nothing dispatches a vocabulary. They are READ
+    # from the IR and projected — bin/project_vocabulary writes the Ruby tables
+    # (lib/hecks/vocabulary.rb) the runtime's constants read, and
+    # bin/project_rust_vocabulary writes rust/src/kernel/vocab/ — so the
+    # runtimes carry no hand-typed copies to drift.
     #
     # Every one of these is a set the runtime must agree with, and every one has
     # already drifted or leaked at least once :
@@ -171,9 +174,17 @@ Hecks.bluebook "Bluebook" do
     # fires for a creating command, advance_lifecycle only when a transition
     # applies — so this is the order a command that does both follows,
     # confirmed by tracing a real dispatch, not read off the source.
+    #
+    # decode_arguments leads both dispatch orders: turning the caller's raw
+    # facts into a command's declared arguments, before any argument gate
+    # judges them. A no-op in Ruby today (routing already hands the
+    # interpreter a decoded hash) and in the Rust kernel's dispatch loop
+    # (generated `from_json` still decodes and gates in one pass) — declared
+    # now so the Rust kernel's step enum has a place for a generated decoder
+    # to move into, rather than the order being implied by generated code.
     value_object "AggregateDispatchOrder" do
       attribute :step, String,
-                one_of: ["refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
+                one_of: ["decode_arguments", "refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
                          "refuse_role_mismatch", "resolve_references", "hydrate", "enforce_givens",
                          "admissible_transition", "assign_creation_attributes", "apply_mutations",
                          "advance_lifecycle", "delegate_to_entity", "enforce_ensures", "enforce_invariants",
@@ -197,7 +208,7 @@ Hecks.bluebook "Bluebook" do
     # both interpreters), even though nothing in the real corpus does yet.
     value_object "EntityDispatchOrder" do
       attribute :step, String,
-                one_of: ["refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
+                one_of: ["decode_arguments", "refuse_unknown_arguments", "refuse_absent_arguments", "normalize_args",
                          "refuse_role_mismatch", "resolve_references", "hydrate_parent",
                          "locate_element", "enforce_givens", "admissible_transition", "apply_mutations",
                          "advance_lifecycle", "enforce_ensures", "enforce_invariants", "save", "emit"]
@@ -219,11 +230,10 @@ Hecks.bluebook "Bluebook" do
     # declared them. Everything here is different in kind: a LANGUAGE-LEVEL
     # refusal, the same wording for every domain, not authored per-bluebook —
     # closer to Comparison/SignTest beside it than to a given. So it follows
-    # THEIR pattern, not given's: declared here for a human to read and a
-    # conformance spec to hold equal, and a hand-typed table
-    # (RefusalWording) is what a dispatch
-    # actually reads — the same reason Evaluator::SIGN_TEST_OPERATORS is
-    # hand-typed rather than read live off this very chapter at every call.
+    # THEIR pattern, not given's: declared here, and projected into the
+    # generated tables a dispatch actually reads (Runtime::RefusalWording in
+    # Ruby, kernel::vocab::RefusalSite in Rust) rather than read live off
+    # this very chapter at every call.
     #
     # `{name}` markers are placeholders — plain text substitution, not
     # expression syntax ; a template is read, never evaluated. Two call
@@ -351,6 +361,303 @@ Hecks.bluebook "Bluebook" do
                        "or read {reference}.{remote_field} directly if this rule cannot wait"
     end
 
+    # THE ARGUMENTS EACH RefusalTemplate TAKES, AND HOW EACH ONE IS WRITTEN.
+    # A template says WHERE a value goes; this says WHICH values a site
+    # takes (in the order its placeholders first appear) and how each is
+    # rendered before it goes there — so a caller hands over the raw value
+    # (a list of names, a name) rather than a string it formatted itself.
+    # BUG#134 was exactly the hand-formatted kind: Ruby's `declared_reading`
+    # fell back to "none" for an empty list, the Rust generators joined
+    # the list themselves and never did.
+    #
+    # Read by Runtime::RefusalWording.render_site (a missing or extra
+    # argument refuses to render at all) and projected into
+    # rust/src/kernel/vocab/refusal_template.rs as one typed args struct
+    # per site (`render_args` — a missing argument does not compile).
+    #
+    #   shape      — "scalar" (one value) or "list" (a collection of them)
+    #   quoting    — "none" (the value's own text) or "inspect" (Ruby's
+    #                `#inspect`; Rust's `{:?}`), per value or per item
+    #   separator  — what a list's items are joined with
+    #   sorted     — "true" sorts a list's items first (before quoting)
+    #   when_empty — what an empty list renders as
+    #
+    # Recorded from what the Ruby call sites did when this table was
+    # introduced; no wording changed. A value whose rendering depends on
+    # its runtime type (`Rendering.describe`, `offered.inspect` of an
+    # arbitrary value) stays a caller-rendered "none" scalar, as do the
+    # identity readings (`identity`, `heads`, `wants`) the Rust side already
+    # joins once at codegen time or inside `extract_wants`.
+    value_object "RefusalSiteArgument" do
+      attribute :refusal,    String, admits: "Vocabulary::DomainRefusal"
+      attribute :site,       String
+      attribute :argument,   String
+      attribute :shape,      String
+      attribute :quoting,    String
+      attribute :separator,  String
+      attribute :sorted,     String
+      attribute :when_empty, String
+
+      member refusal: "NotFound", site: "creating_no_identity", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "creating_no_identity", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "creating_no_identity", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "creating_duplicate", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "creating_duplicate", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "creating_duplicate", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "creating_duplicate", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "entity_duplicate", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "entity_duplicate", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AlreadyExists", site: "entity_duplicate", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      # One described value per identity head (MutationApplier), or the
+      # one offered element identity (EntityListCoercion).
+      member refusal: "AlreadyExists", site: "entity_duplicate", argument: "offered",
+             shape: "list", quoting: "none", separator: ", ", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "acting_no_identity", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "acting_no_identity", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "acting_no_identity", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "record_missing", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "record_missing", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "record_missing", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_parent_no_identity", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_parent_no_identity", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_parent_no_identity", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_parent_no_identity", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_unknown", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_unknown", argument: "entity",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_no_identity", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_no_identity", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_no_identity", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_missing", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_missing", argument: "identity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_missing", argument: "wants",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_missing", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "entity_element_missing", argument: "parent_id",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "reference_target_missing", argument: "target",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "reference_target_missing", argument: "heads",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "reference_target_missing", argument: "key",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "read_model_reference_missing", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "NotFound", site: "read_model_reference_missing", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "read_model_object_reference", argument: "query",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "read_model_object_reference", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_query", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_query", argument: "query",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_query_missing", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_query_missing", argument: "query",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_holds_no_list", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_holds_no_list", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_no_command", argument: "entity",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "entity_no_command", argument: "command",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "aggregate_no_command", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "aggregate_no_command", argument: "command",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "port_no_operation", argument: "port",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "port_no_operation", argument: "operation",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_domain", argument: "domain",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_domain", argument: "verb",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_read_model", argument: "domain",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_read_model", argument: "query",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "not_fully_qualified", argument: "verb",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_aggregate", argument: "domain",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownVerb", site: "no_aggregate", argument: "aggregate",
+             shape: "scalar", quoting: "inspect", separator: "", sorted: "false", when_empty: ""
+      member refusal: "LifecycleRefused", site: "transition_blocked", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "LifecycleRefused", site: "transition_blocked", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "LifecycleRefused", site: "transition_blocked", argument: "current",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "LifecycleRefused", site: "transition_blocked", argument: "allowed",
+             shape: "list", quoting: "inspect", separator: " or ", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "value_object_shape", argument: "name",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "value_object_shape", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "value_object_shape", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "reference_wrong_shape", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "reference_wrong_shape", argument: "attribute",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "reference_wrong_shape", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "reference_wrong_shape", argument: "known_by",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "multi_field_scalar", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "composite_identity", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "numeric_field", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "numeric_field", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "numeric_field", argument: "expected",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "numeric_field", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "non_finite_field", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "non_finite_field", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "non_finite_field", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "integer_range", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "integer_range", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "integer_range", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "pattern_mismatch", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "pattern_mismatch", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "pattern_mismatch", argument: "pattern",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "pattern_mismatch", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_amount", argument: "op",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_amount", argument: "target",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_amount", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_current", argument: "op",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_current", argument: "target",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_current", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_shared_field", argument: "op",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "TypeMismatch", site: "arithmetic_shared_field", argument: "target",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownArgument", site: "unknown_args", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "UnknownArgument", site: "unknown_args", argument: "unknown",
+             shape: "list", quoting: "none", separator: ", ", sorted: "true", when_empty: ""
+      member refusal: "UnknownArgument", site: "unknown_args", argument: "declared",
+             shape: "list", quoting: "none", separator: ", ", sorted: "false", when_empty: "none"
+      member refusal: "AbsentArgument", site: "absent_args", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AbsentArgument", site: "absent_args", argument: "absent",
+             shape: "list", quoting: "none", separator: ", ", sorted: "true", when_empty: ""
+      member refusal: "AbsentArgument", site: "absent_args", argument: "declared",
+             shape: "list", quoting: "none", separator: ", ", sorted: "false", when_empty: "none"
+      member refusal: "InvariantViolation", site: "closed_set_member", argument: "type",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "closed_set_member", argument: "admitted",
+             shape: "list", quoting: "inspect", separator: ", ", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "closed_set_member", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "value_object_invariant", argument: "name",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "value_object_invariant", argument: "description",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "value_object_invariant", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "admits_declared_set", argument: "name",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "admits_declared_set", argument: "admits",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "admits_declared_set", argument: "admitted",
+             shape: "list", quoting: "inspect", separator: ", ", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "admits_declared_set", argument: "offered",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "undeclared_set", argument: "name",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "InvariantViolation", site: "undeclared_set", argument: "admits",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "tenant_required", argument: "query",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "tenant_required", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "role_mismatch", argument: "command",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "role_mismatch", argument: "role",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "role_mismatch", argument: "caller_role",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "tenant",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "attribute",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "target",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "target_field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "Unauthorized", site: "cross_tenant_reference", argument: "other",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AttributeAbsent", site: "absent_read", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "AttributeAbsent", site: "absent_read", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "ProjectionAbsent", site: "absent_read", argument: "aggregate",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "ProjectionAbsent", site: "absent_read", argument: "field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "ProjectionAbsent", site: "absent_read", argument: "reference",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+      member refusal: "ProjectionAbsent", site: "absent_read", argument: "remote_field",
+             shape: "scalar", quoting: "none", separator: "", sorted: "false", when_empty: ""
+    end
+
     # SagaInterpreter::REFUSED.
     #
     # A leg answers an EVENT — `on "AccountDebited"` — or it answers one of these,
@@ -373,10 +680,9 @@ Hecks.bluebook "Bluebook" do
     # rendering convention, the same guess for every domain, not
     # authored per-bluebook — closer to Comparison/SignTest than to a
     # given. `pattern` is the regex SOURCE, no delimiters or flags
-    # (Ruby's own `Regexp#source`) — spec/field_hint_conformance_spec.rb
-    # holds FieldShape's four hand-typed constants equal to this, both
-    # directions, the same conformance shape refusal_wording_
-    # conformance_spec.rb already holds RefusalTemplate to.
+    # (Ruby's own `Regexp#source`) — FieldShape builds its four constants
+    # off these rows, and bin/project_field_hints writes the Rust host's
+    # copy from them, so neither side is typed by hand.
     #
     # `resolves_to` names WHICH Field attribute a match sets — `html_type`
     # for email/url/tel (three candidates, only one wins, checked in that
@@ -392,5 +698,34 @@ Hecks.bluebook "Bluebook" do
       member name: "tel",      pattern: 'phone|\btel(ephone)?\b',                                 resolves_to: "html_type"
       member name: "textarea", pattern: '\b(text|body|note|notes|description|message|comment)\b', resolves_to: "kind"
     end
+
+    # The Rust keywords (strict + reserved) a generated identifier must not
+    # collide with — RustProjection::Projector::RUST_KEYWORDS (rust/project/
+    # naming.rb) reads this, and bin/project_reserved_names projects it into
+    # rust/codegen/src/reserved_names.rs, so the Ruby and Rust generators
+    # escape (a field: `r#type`) or refuse (a module name) the SAME words.
+    # Declared once here because the two hand-typed copies were held equal
+    # by nothing but a comment.
+    value_object "RustReservedWord" do
+      attribute :word, String,
+                one_of: ["as", "break", "const", "continue", "crate", "dyn", "else", "enum", "extern", "false",
+                         "fn", "for", "if", "impl", "in", "let", "loop", "match", "mod", "move", "mut", "pub",
+                         "ref", "return", "self", "Self", "static", "struct", "super", "trait", "true", "type",
+                         "unsafe", "use", "where", "while", "abstract", "become", "box", "do", "final", "macro",
+                         "override", "priv", "typeof", "unsized", "virtual", "yield", "try"]
+    end
+
+    # The keys a domain's own name must not take, because that name doubles
+    # as a Cargo `[features]` key: every key rust/Cargo.toml already uses
+    # outside `[features]` (`[package]`, `[lib]`, `[[bin]]`) plus `default`,
+    # which Cargo reserves for the auto-enabled feature set. Read by
+    # RustProjection::Projector::CARGO_RESERVED_DOMAIN_NAMES and projected by
+    # bin/project_reserved_names, same as RustReservedWord above.
+    value_object "CargoReservedName" do
+      attribute :name, String,
+                one_of: ["name", "version", "edition", "path", "authors", "license", "description", "default",
+                         "features", "package", "lib", "bin", "dependencies", "dev-dependencies",
+                         "build-dependencies", "workspace"]
+    end
   end
 end

data/lib/hecks/language/hecksagon/hecksagon.bluebook

@@ -100,6 +100,16 @@ Hecks.bluebook "Hecksagon" do
       member word: "uses_framework",  context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members"
       member word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks"
       member word: "port",            context: "Hecksagon",     body: "keywords", inner: "DomainPort",    opens: "DomainPort",    fills: "", calls: "port_impl"
+      # A CROSS-DOMAIN REACTION, WIRED HERE INSTEAD OF THE BLUEBOOK — same
+      # underlying `Policy` shape a `policy` block already builds
+      # (`inner`/`opens: "Policy"` reuses that context's own `on`/`trigger`
+      # wholesale, zero new inner vocabulary), but declared as a wiring
+      # decision (which FOREIGN domain's event this chapter conforms to),
+      # the same kind of decision `port`/`uses_framework` already are.
+      # No `calls:` — `HecksagonBuilder#translates` is an ordinary method,
+      # the same shape `subscribe`/`uses_framework` already are, reached
+      # by Ruby's own method lookup before `word_gate` ever runs.
+      member word: "translates",      context: "Hecksagon",     body: "keywords", inner: "Policy",        opens: "Policy",        fills: ""
 
     end
 
@@ -125,6 +135,7 @@ Hecks.bluebook "Hecksagon" do
       member keyword: "uses_framework",  context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members"
       member keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks"
       member keyword: "port",            context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
+      member keyword: "translates",      context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name"
 
     end
   end

data/lib/hecks/language/oidc.json

@@ -76,6 +76,11 @@
       "verb": "Bluebook::Bluebook.Normalise",
       "role": "Language"
     },
+    {
+      "scope": "bluebook:bluebook.provide",
+      "verb": "Bluebook::Bluebook.Provide",
+      "role": "Language"
+    },
     {
       "scope": "bluebook:command.acts_on",
       "verb": "Bluebook::Command.ActsOn",

data/lib/hecks/literal.rb

@@ -1,31 +1,31 @@
 module Hecks
-  # THE ONE SPELLING FOR A CAPTURED RUBY LITERAL ON THE WIRE.
+  # The one spelling for a captured Ruby literal on the wire.
   #
   # Several `to_h` fields hold a value the author wrote in a bluebook —
   # `where(status: { eq: "open" })`, `then_set append: { direction: { value:
   # "credit" } }`, `dispatch ... with: { number: :source }`, an attribute's
-  # `default:` — as TEXT, because the export has to stand on its own and a
+  # `default:` — as text, because the export has to stand on its own and a
   # String field cannot say "this one was a Symbol". Every such field is the
   # same question and now gets the same answer.
   #
   # It was three answers before, and they disagreed on both axes that matter.
-  # `Mutation#appended_fields` spelled a Symbol BARE and everything else
-  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a COLON
+  # `Mutation#appended_fields` spelled a Symbol bare and everything else
+  # `inspect`; `QuerySpecification.render_value` spelled a Symbol with a colon
   # and everything else `to_s`. So `:amount` crossed as "amount" in a mutation
   # and ":amount" in a saga binding — the same value, two spellings, and each
   # reader had to know which field it was looking at. Worse, `to_s`/`inspect`
-  # on a Hash is Ruby's OWN rendering, which moved under us: 3.3 writes
+  # on a Hash is Ruby's own rendering, which moved under us: 3.3 writes
   # `{:value=>"credit"}` and 3.4 writes `{value: "credit"}` for the identical
   # Hash, so the wire format was silently pinned to an interpreter version.
   #
-  # SELF-DESCRIBING IS THE RULE, stated once here rather than inherited from
+  # Self-describing is the rule, stated once here rather than inherited from
   # whatever `inspect` happens to do: a symbol wears its colon, a string wears
   # its quotes, a hash wears `{key: value}` braces, a list wears its brackets,
   # and a number, a boolean and nil are bare. `read` is the exact inverse, and
   # is the only thing that should ever take one of these strings apart.
-  # A MUTATION SOURCE THAT READS THE RECORD'S OWN STATE — `sets :positions,
+  # A mutation source that reads the record's own state — `sets :positions,
   # append: { knights: state(:knights) }`. A bare Symbol in a mutation
-  # source always names a command ARGUMENT (and imports it as one when
+  # source always names a command argument (and imports it as one when
   # the target's own field carries the same name — `CommandBuilder
   # #resolve_append_fields!`); before this there was no way to say "the
   # value this field already holds", so a command could not snapshot its
@@ -43,6 +43,12 @@ module Hecks
   module Literal
     module_function
 
+    # Turns a Ruby value into its self-describing wire spelling.
+    #
+    # @param value [Object] value to render: nil, Symbol, String, StateRef, true,
+    #   false, Integer, Float, Hash, or Array (recursively)
+    # @return [String] the self-describing spelling `read` can parse back
+    # @raise [ArgumentError] if `value` is a type with no pinned literal spelling
     def render(value)
       case value
       when nil    then "nil"
@@ -67,6 +73,9 @@ module Hecks
     # `return`; splitting them into named predicates would just rename
     # each line without changing what it does, and would separate this
     # method from the `render` it is the deliberate mirror of.
+    # @param text [String, #to_s] wire spelling produced by `render`, or a bare word
+    # @return [Object] nil, true, false, Integer, Float, Symbol, StateRef, String,
+    #   Hash, or Array — or `text` itself, stripped, when it matches no known spelling
     # rubocop:disable-next Metrics/CyclomaticComplexity
     # rubocop:disable-next Metrics/PerceivedComplexity
     def read(text)
@@ -87,12 +96,28 @@ module Hecks
 
     ESCAPED = { '"' => '\\"', "\\" => "\\\\" }.freeze
 
+    # Wraps `text` in double quotes, escaping embedded quotes and backslashes.
+    #
+    # @param text [String] raw text to quote
+    # @return [String] the quoted, escaped spelling
     def quote(text) = "\"#{text.gsub(/["\\]/) { |char| ESCAPED[char] }}\""
 
+    # Tells whether `raw` is a double-quoted literal.
+    #
+    # @param raw [String] wire text to check
+    # @return [Boolean]
     def quoted?(raw) = raw.length >= 2 && raw.start_with?('"') && raw.end_with?('"')
 
+    # Strips the surrounding quotes from a quoted literal and unescapes it.
+    #
+    # @param raw [String] a quoted literal, as `quoted?` would confirm
+    # @return [String] the unescaped text inside the quotes
     def unquote(raw) = raw[1..-2].gsub(/\\(.)/) { ::Regexp.last_match(1) }
 
+    # Parses a `{key: value, ...}` wire literal.
+    #
+    # @param raw [String] text starting with `{` and ending with `}`
+    # @return [Hash{Symbol => Object}] the parsed hash, values read recursively via `read`
     def read_hash(raw)
       split_items(raw[1..-2]).to_h do |item|
         key, _, held = item.partition(":")
@@ -100,12 +125,19 @@ module Hecks
       end
     end
 
+    # Parses a `[value, ...]` wire literal.
+    #
+    # @param raw [String] text starting with `[` and ending with `]`
+    # @return [Array<Object>] the parsed values, each read recursively via `read`
     def read_array(raw) = split_items(raw[1..-2]).map { |item| read(item) }
 
-    # Split on the commas that are actually SEPARATORS — never one inside a
+    # Split on the commas that are actually separators — never one inside a
     # quoted string or a nested brace/bracket. Scanned rather than
     # `String#split(", ")`, which tore `"a, b"` in half and lost the second
     # field of anything nested.
+    #
+    # @param body [String] the text between a literal's outer braces or brackets
+    # @return [Array<String>] each item's raw text, stripped, with empty items dropped
     def split_items(body)
       items = []
       current = +""