hecks 1.2.0 → 1.4.0

data/lib/hecks/projections/model/deviations.rb

@@ -1,32 +1,19 @@
 module Hecks
   module Projections
     module Model
-      # HOW THE MODEL'S SHAPE DIFFERS FROM THE LANGUAGE'S, and why.
+      # How the model's shape differs from the language's, and why.
       #
       # Every construct's `emits_ir` restates what the grammar declares —
       # and the two legitimately differ, in seven ways. These lived only
       # as prose in Ruby comments until spec/model_shape_conformance_spec
-      # made them checkable; they live HERE so the generator and the gate
+      # made them checkable; they live here so the generator and the gate
       # read one source rather than two that must agree.
       #
       # A reason is carried beside each entry because the generated file
-      # will CARRY it: a deviation is exactly the kind of thing whose
+      # will carry it: a deviation is exactly the kind of thing whose
       # explanation must survive regeneration, and the only way it can is
       # to be emitted rather than typed into the output.
       module Deviations
-        # The grammar is relational — a Command points UP at its
-        # Aggregate — where the model composes. An explicit `as:` still
-        # keeps its `_id` (Command's own `entity_id`, kept as data); the
-        # parent link itself mints bare now (ADR 0025) — `aggregate` or
-        # `bluebook`, whichever this category's creating command declares
-        # first — so both spellings are checked. Entity spells its own
-        # (separate, non-colliding) text twin of the parent link `owner`.
-        PARENT_REF = ->(field) { field.to_s.match?(/_id\z/) || %i[owner aggregate bluebook].include?(field) }
-
-        # The judge's own field, never the model's — contracts.rb already
-        # says so with `derived: { position: :walk }`.
-        JUDGE_ONLY = %i[position].freeze
-
         # What the model holds that the grammar declares elsewhere: the
         # containment edges, stated in syntax.bluebook's Keyword rows as
         # `context` -> `opens`.
@@ -64,7 +51,7 @@ module Hecks
           "Policy"      => { where_ast:      "the structured form of `where`, derived from the same text at emission" }
         }.freeze
 
-        # DECLARED, AND DELIBERATELY NOT EMITTED. The category that had no
+        # **Declared, and deliberately not emitted**. The category that had no
         # home anywhere before — each of these was a comment and nothing
         # more.
         OFF_THE_WIRE = {
@@ -85,6 +72,20 @@ module Hecks
 
         module_function
 
+        # The grammar is relational — a Command points up at its
+        # Aggregate — where the model composes. An explicit `as:` still
+        # keeps its `_id` (Command's own `entity_id`, kept as data); the
+        # parent link itself mints bare now (ADR 0025) — `aggregate` or
+        # `bluebook`, whichever this category's creating command declares
+        # first. Entity spells its own (separate, non-colliding) text twin
+        # of the parent link `owner`. Not restated here: the one list is
+        # `Assembly::PARENT_POINTERS`, which the assembly gate reads too.
+        def parent_ref?(field) = Hecks::Bluebook::Assembly.parent_pointer?(field)
+
+        # The judge's own fields, never the model's — read off the
+        # category's contract (`derived: { position: :walk }`), not restated.
+        def judge_only(name) = Hecks::Bluebook::Assembly.contract(name).walked
+
         # The tables that carry a reason answer with names only when the
         # caller wants the set rather than the explanations.
         def off_the_wire(name) = OFF_THE_WIRE.fetch(name, {}).keys

data/lib/hecks/projections/model.rb

@@ -3,22 +3,22 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE MODEL CLASSES, PROJECTED FROM THE LANGUAGE THAT DECLARES THEM.
+    # The model classes, projected from the language that declares them.
     #
-    # A construct's HOLDING half — its readers, its emission, a
+    # A construct's holding half — its readers, its emission, a
     # constructor that assigns declared fields and hands off — restates
     # what `bluebook.bluebook` already says, three times over in Ruby.
     # This renders it instead.
     #
-    # ONLY THE HOLDING HALF. `Behaviour::X` is hand-written and permanent,
+    # **Only the holding half**. `Behaviour::X` is hand-written and permanent,
     # and `settle` is the seam: everything a declaration cannot state
     # lives behind it, so regenerating can never be lossy. That property
     # was established construct by construct before any of this was
     # written — the chapter looked generatable and was not, until its
     # `@hecks_root`, ports table and child stamping moved behind `settle`.
     #
-    # THE HOST MANIFEST IS THE HONEST PART. The grammar states the fields;
-    # it does not state which constructs are Ruby CLASSES rather than
+    # The HOST manifest is the honest part. The grammar states the fields;
+    # it does not state which constructs are Ruby classes rather than
     # instances, what a constructor's defaults are, or how a value is
     # coerced on the way in. Those are facts about Ruby, not about
     # bluebooks, so they are declared here rather than pretended into the
@@ -29,7 +29,7 @@ module Hecks
 
       projects_as :model, declares: "Bluebook", emits: :files
 
-      # PER-CONSTRUCT RUBY FACTS. `coerce` is the only fiddly column: a
+      # **Per-construct Ruby facts**. `coerce` is the only fiddly column: a
       # declared field arrives as whatever the builder handed over, and
       # each construct has always normalised its own on the way in.
       HOST = {
@@ -37,21 +37,25 @@ module Hecks
           construct: "Policy",
           file:      "policy.rb",
           behaviour: "Behaviour::Policy",
-          readers:   %i[name on_event trigger_command target_domain where for_each with_spec],
+          readers:   %i[name on_event trigger_command target_domain expect_undelivered where for_each with_spec],
           accessors: %i[aggregate],
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
-                       target_domain: "nil", where: "nil", for_each: "nil",
+                       target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
-          coerce:    { name: ".to_s", aggregate: "&.to_s" },
-          # A LIST OF BINDINGS IS NOT A SCALAR ON THE WIRE. Every other
+          # A flag on the wire is a boolean — the language holds it as
+          # text ("true"), the builder hands over `true`, and a
+          # reconstruction hands back whichever it read; all three land
+          # as the same `true`/`false`.
+          coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },
+          # A list of bindings is not a scalar on the wire. Every other
           # field emits as itself; this one has to render the way
           # `DispatchSpec`'s own `with_spec` does — keys to strings, and
-          # `render_value` KEEPING the leading colon on a Symbol, because
+          # `render_value` keeping the leading colon on a Symbol, because
           # a binding that reads an event field and one that supplies a
           # literal string are otherwise indistinguishable once written
           # down (see `MetaValidator::Readings`' own note on exactly that).
           renders:   { with_spec: "-> { with_spec.map { |key, value| [key.to_s, Bluebook.render_value(value)] } }",
-                       # COMPUTED (Deviations::COMPUTED["Policy"]): the structured
+                       # Computed (Deviations::COMPUTED["Policy"]): the structured
                        # form of `where`, a pure function of that text, the same
                        # `ast` every rule row carries beside its `canonical`.
                        where_ast: "-> { where_ast }" },
@@ -67,8 +71,8 @@ module Hecks
 
       def render(bluebook, name, host)
         <<~RUBY
-          # GENERATED — projected from the language's own #{name} aggregate.
-          # DO NOT EDIT: the holding half is rendered, and #{host.fetch(:behaviour)}
+          # Generated — projected from the language's own #{name} aggregate.
+          # Do not edit: the holding half is rendered, and #{host.fetch(:behaviour)}
           # is where anything hand-written belongs.
           require_relative "behaviour/#{File.basename(host.fetch(:file), '.rb')}"
 
@@ -91,9 +95,9 @@ module Hecks
 
       # The emission, keyed as the model spells it and sourced as the
       # language declares it.
-      # A COMPUTED field (Deviations::COMPUTED) is emitted too — it is
+      # A computed field (Deviations::COMPUTED) is emitted too — it is
       # model-only by definition, so it rides after the declared fields
-      # and MUST have a `renders` entry, there being nothing to `send`.
+      # and must have a `renders` entry, there being nothing to `send`.
       def emits(bluebook, name)
         fields  = emitted_fields(bluebook, name) + Deviations.computed(name)
         renders = HOST.fetch(name).fetch(:renders, {})
@@ -102,14 +106,14 @@ module Hecks
         "emits_ir(\n#{fields.map { |f| "  #{"#{f}:".ljust(width + 1)} #{renders.fetch(f, ":#{f}")}" }.join(",\n")}\n)"
       end
 
-      # WHAT THE CONSTRUCT EMITS: what the language declares, less every
+      # What the construct emits: what the language declares, less every
       # deviation the tables account for. The generator and
       # spec/model_shape_conformance_spec compute this the same way, from
       # the same tables, which is the point of the tables being in lib.
       def emitted_fields(bluebook, name)
         bluebook.aggregate(name).attributes.map(&:name)
-                .reject { |f| Deviations::PARENT_REF.call(f) } -
-          Deviations::JUDGE_ONLY -
+                .reject { |f| Deviations.parent_ref?(f) } -
+          Deviations.judge_only(name) -
           Deviations.off_the_wire(name) -
           Deviations.dynamic_tail(name) -
           Deviations.folded(name).values.flatten -
@@ -122,13 +126,13 @@ module Hecks
         return lines.join("\n") if accessors.empty?
 
         # A declared field the model deliberately does not emit still
-        # needs a reader, and the REASON it is off the wire is carried
+        # needs a reader, and the reason it is off the wire is carried
         # here rather than typed in — a comment that survives
         # regeneration is one the generator writes.
         reasons = Deviations::OFF_THE_WIRE.fetch(host.fetch(:construct, ""), {})
         (lines + accessors.map do |a|
           why = reasons[a]
-          (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
+          (why ? "\n# #{a.to_s.capitalize}, declared and deliberately off the wire\n# #{wrap(why)}\n" : "") +
             "attr_accessor :#{a}"
         end).join("\n")
       end

data/lib/hecks/projections/oidc.rb

@@ -3,16 +3,16 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # AN OIDC CLIENT/SCOPE MANIFEST derived from a domain's own IR: what
+    # An OIDC client/scope manifest derived from a domain's own IR: what
     # an identity provider has to know about this domain before it can
     # issue a token that means anything here.
     #
-    # THE ARTIFACT HALF OF SOMETHING ALREADY HALF-BUILT.
-    # `spec/oidc_projection_spec.rb` covers the INTEGRATION half — verified
+    # The artifact half of something already half-built.
+    # `spec/oidc_projection_spec.rb` covers the integration half — verified
     # claims in, `IdentityResolution.resolve` → `Authorization.holds_role?`
     # → a dispatch scoped by `Hecks.as_caller(role:)`. That half enforces
     # a role per command. It just had no way to say, up front and as data,
-    # WHICH role each command wants — every answer came from asking the
+    # which role each command wants — every answer came from asking the
     # live runtime one dispatch at a time.
     #
     # This is that catalogue, and the two are checked against each other
@@ -24,12 +24,12 @@ module Hecks
     # `Ports::Authorization.holds_role?` compares against a real
     # `Governance::RoleAssignment`.
     #
-    # ROLES COME FROM THE COMMANDS, NOT FROM GOVERNANCE. A command's own
+    # Roles come from the commands, not from governance. A command's own
     # `role "Compliance officer"` is in the bluebook IR
     # (`Command#role`), whereas `uses_framework "Governance"` is
     # declared in the `.hecksagon` — which `call(bluebook:, options:)`
     # cannot see at all. Reading the commands is both the only thing
-    # available here AND the more accurate source: it says what each
+    # available here and the more accurate source: it says what each
     # command actually demands, not merely which role vocabulary the
     # application happened to mount.
     #
@@ -93,7 +93,7 @@ module Hecks
       end
 
       # `banking:account.open` — the shape an OIDC scope is conventionally
-      # spelled in, and snake_cased through the SAME `Naming.snake` the
+      # spelled in, and snake_cased through the same `Naming.snake` the
       # facade uses to name a command's own door method, so a scope and
       # the Ruby call that satisfies it cannot drift apart.
       def command_scopes(commands, verb_prefix, scope_prefix)

data/lib/hecks/projections/parser_table.rb

@@ -2,12 +2,12 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE RUST PARSER'S KEYWORD TABLE, projected from the chapter's own
-    # Syntax aggregate — "the parser's grammar knowledge is DERIVED from
+    # The Rust parser's keyword table, projected from the chapter's own
+    # Syntax aggregate — "the parser's grammar knowledge is derived from
     # hecks's self-description, not hand-typed a second time", which
     # is the anti-drift idea the whole Rust-parser plan rests on.
     #
-    # A REGISTERED TARGET NOW, rather than a module living inside its own
+    # A registered target now, rather than a module living inside its own
     # bin/ script. It was already a projection in everything but call
     # shape; this only stops it being a fifth way of spelling one.
     module ParserTable
@@ -20,7 +20,7 @@ module Hecks
 
       module_function
 
-      # THE CHAPTER IS HANDED OVER, not reached for. This used to open the
+      # The chapter is handed over, not reached for. This used to open the
       # grammar registry itself, which meant the projection could only ever
       # project one chapter — the language's own. Taking it as an argument is
       # what the projector protocol asks for, and it costs nothing.
@@ -64,7 +64,7 @@ module Hecks
 
       # S14, ADR 0026 — Keyword/Argument are genuine entities of Syntax
       # now, dispatched (not merely declared) so their own `status`
-      # really is a lifecycle. `SyntaxBoot.call` reads the STILL-STATIC
+      # really is a lifecycle. `SyntaxBoot.call` reads the still-static
       # seed rows (`KeywordSeed`/`ArgumentSeed`), dispatches each one
       # through the real admission/lifecycle door, and hands back the
       # exact same shape `rows` used to read straight off the closed set

data/lib/hecks/projections/reference.rb

@@ -3,18 +3,18 @@ require_relative "../projector"
 
 module Hecks
   module Projections
-    # THE DSL REFERENCE PAGES, projected from the chapter's own Syntax
+    # The DSL reference pages, projected from the chapter's own Syntax
     # aggregate — the tables come from the declaration, the prose is
     # preserved from whatever is already committed.
     #
-    # THE FIRST PROJECTION THAT EMITS A TREE. `emits: :files` says so,
+    # The first projection that emits a tree. `emits: :files` says so,
     # and the framework writes the map rather than inferring one: a Hash
     # of path => contents and a Hash that merely holds strings are the
     # same object to Ruby, so only the projection can know which it
     # meant. This is the case the output contract was designed for and
     # deliberately left unimplemented until something real needed it.
     #
-    # NOT PURE, and it cannot be. `Doc::Reference.pages` READS the
+    # Not pure, and it cannot be. `Doc::Reference.pages` reads the
     # committed pages to harvest their prose, so the existing directory
     # is an input — passed as `from:` rather than assumed, so the
     # projection never reaches for a path of its own choosing.