hecks 0.2.0 → 0.3.0

data/lib/hecks/projections/diagrams.rb

@@ -0,0 +1,413 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # A DOMAIN'S OWN SHAPE, PROJECTED AS MERMAID DIAGRAMS — the same
+    # trick `Projections::Reference`/`DocsProjector` already play for
+    # prose, one level further: a diagram generated FROM the
+    # declaration can't drift from it the way a hand-drawn one
+    # inevitably does, because there is no second copy to forget to
+    # update.
+    #
+    # MERMAID, NOT GRAPHVIZ (the two considered) — every diagram type
+    # below has a Mermaid form purpose-built for exactly what the
+    # underlying construct already is (a `lifecycle` IS a state
+    # machine, `has_many`/`belongs_to` already speaks in cardinality,
+    # `emits`/`trigger` already IS a directed graph), and the output is
+    # plain text that renders natively wherever this project's own docs
+    # already live — GitHub markdown, this repo's generated docs, Claude
+    # Artifacts — with no build step and no external binary. Graphviz's
+    # DOT format needs an actual render step (a `dot` binary, or a WASM
+    # port) to become anything viewable, which is a real dependency this
+    # repository's own discipline (see rust/parser's Cargo.toml: "no
+    # dependency earns its way past std") would rather not take just to
+    # draw a diagram.
+    #
+    # FOUR DIAGRAM KINDS, one file each per domain except lifecycles
+    # (one per lifecycle-bearing construct, since that's how a reader
+    # actually reaches for it — looking at ONE aggregate's states, not
+    # every aggregate's at once):
+    #
+    #   <Name>_lifecycle.mmd  stateDiagram-v2  one per lifecycle
+    #   relationships.mmd     erDiagram        the whole domain's has_many/
+    #                                          has_one/belongs_to/reference_to
+    #   dispatch.mmd          flowchart        the whole domain's command
+    #                                          emits -> policy trigger chains
+    #   roles.mmd             flowchart        every role that issues a
+    #                                          command, wired to every
+    #                                          command it issues
+    #   ports.mmd             flowchart        every port operation, which
+    #                                          aggregate exposes it, which
+    #                                          aggregate it routes to: (if
+    #                                          any), and what it emits
+    #   read_models.mmd       flowchart        every read_model, and every
+    #                                          aggregate it's assembled
+    #                                          from — the read-side
+    #                                          complement to relationships.mmd
+    #   <Name>_surface.mmd    flowchart        one per aggregate/entity that
+    #                                          declares at least one command
+    #                                          or query — everything you can
+    #                                          DO to it and ASK about it,
+    #                                          in one place
+    #
+    # CONSTRUCT NAMES (aggregate/entity/command/event) ARE USED BARE,
+    # UNSANITIZED, as Mermaid node/entity ids — safe because this
+    # language's own word grammar only ever admits simple CamelCase/
+    # snake_case identifiers there (confirmed: no space or punctuation
+    # appears in any real aggregate/command/event name across the corpus
+    # this projects from). A `role:` STRING IS FREE TEXT, though — the
+    # real corpus already has "Back office"/"Vault officer"/"Branch
+    # clerk" — so `roles.mmd` is the one diagram here that sanitizes a
+    # name into an id (`role_id`) while keeping the real string as the
+    # node's own displayed label.
+    module Diagrams
+      extend Hecks::Projector::Target
+
+      projects_as :diagrams, emits: :files
+
+      module_function
+
+      def call(bluebook:, options: {})
+        files = {}
+
+        holders_with_lifecycle(bluebook).each do |holder|
+          files["#{holder.hecks_name}_lifecycle.mmd"] = lifecycle_diagram(bluebook, holder)
+        end
+
+        if (diagram = relationship_diagram(bluebook))
+          files["relationships.mmd"] = diagram
+        end
+
+        if (diagram = dispatch_diagram(bluebook))
+          files["dispatch.mmd"] = diagram
+        end
+
+        if (diagram = roles_diagram(bluebook))
+          files["roles.mmd"] = diagram
+        end
+
+        if (diagram = ports_diagram(bluebook))
+          files["ports.mmd"] = diagram
+        end
+
+        if (diagram = read_model_diagram(bluebook))
+          files["read_models.mmd"] = diagram
+        end
+
+        holders(bluebook).each do |holder|
+          next if holder.commands.empty? && holder.queries.empty?
+
+          files["#{holder.hecks_name}_surface.mmd"] = surface_diagram(bluebook, holder)
+        end
+
+        files
+      end
+
+      # ── shared ────────────────────────────────────────────────────────
+
+      # AN ENTITY CAN CARRY ITS OWN LIFECYCLE, RELATIONSHIP, OR COMMAND
+      # TOO — its own `lifecycle`/`reference_to`/`command` block,
+      # addressed through its holding aggregate the same way
+      # `DocsProjector` already treats an aggregate and its entities
+      # alike. Walking both here means a domain's entity gaining any of
+      # these needs no change to this file.
+      def holders(bluebook)
+        bluebook.aggregates.flat_map { |aggregate| [aggregate, *aggregate.entities] }
+      end
+
+      def holders_with_lifecycle(bluebook) = holders(bluebook).select(&:lifecycle)
+
+      # `chapter_name` DRIVES THE RE-RUN HINT ALWAYS — that's the one
+      # argument `bin/project_diagrams` actually takes, regardless of
+      # which single aggregate/entity `subject` happens to name. Passing
+      # the wrong one here once already produced a real, committed
+      # `Order_lifecycle.mmd` telling a reader to run
+      # `bin/project_diagrams <domain-path> Order` — a chapter name
+      # Hecks.boot has never heard of.
+      def header(chapter_name, subject)
+        <<~HEADER
+          %% GENERATED by bin/project_diagrams from #{subject} — DO NOT EDIT BY HAND.
+          %% Re-run `bin/project_diagrams <domain-path> #{chapter_name}` after any change.
+        HEADER
+      end
+
+      # ── lifecycle -> stateDiagram-v2 ─────────────────────────────────
+
+      def lifecycle_diagram(bluebook, holder)
+        lifecycle = holder.lifecycle
+        edges = lifecycle.transitions.flat_map do |command_name, transition|
+          Array(transition.from).map { |from_state| "    #{from_state} --> #{transition.target}: #{command_name}" }
+        end
+
+        subject = "#{holder.hecks_name}'s own declared lifecycle (field: #{lifecycle.field})"
+        <<~MERMAID
+          #{header(bluebook.name, subject)}stateDiagram-v2
+              [*] --> #{lifecycle.default}
+          #{edges.join("\n")}
+        MERMAID
+      end
+
+      # ── relationships -> erDiagram ───────────────────────────────────
+
+      # STANDARD CROW'S-FOOT READING, the same convention every ORM's own
+      # ERD generator (Rails' erd gem included) already uses:
+      # `has_many`/`has_one` are read from the OWNING side — one Holder
+      # relates to many/one Target. `belongs_to`/`reference_to` are read
+      # from the TARGET's side instead — one Target can be pointed at by
+      # MANY Holders — because a bare reference carries no promise about
+      # how many holders point back at it; "many" is the honest default
+      # absent a declared uniqueness rule this language doesn't expose.
+      # `optional?` only ever softens the side that can genuinely be
+      # absent (a nilable reference, an empty has_one) — never the
+      # crow's-foot "many" marker, which is a structural fact independent
+      # of any one instance's optionality.
+      def relationship_diagram(bluebook)
+        edges = holders(bluebook).flat_map do |holder|
+          holder.attributes.select(&:reference?).map { |attribute| relationship_edge(holder, attribute) }
+        end
+        return nil if edges.empty?
+
+        subject = "#{bluebook.name}'s own declared reference_to/belongs_to/has_many/has_one attributes"
+        "#{header(bluebook.name, subject)}erDiagram\n#{edges.join("\n")}\n"
+      end
+
+      def relationship_edge(holder, attribute)
+        target = attribute.type.target_name
+        case attribute.relationship
+        when "has_many"
+          %(    #{holder.hecks_name} ||--o{ #{target} : "#{attribute.name}")
+        when "has_one"
+          %(    #{holder.hecks_name} ||--#{attribute.optional? ? 'o|' : '||'} #{target} : "#{attribute.name}")
+        when "belongs_to", "reference_to"
+          %(    #{target} #{attribute.optional? ? '|o' : '||'}--o{ #{holder.hecks_name} : "#{attribute.name}")
+        end
+      end
+
+      # ── dispatch -> flowchart ─────────────────────────────────────────
+
+      # A COMMAND NODE, STADIUM-SHAPED (`(["..."])`); AN EVENT NODE,
+      # HEXAGONAL (`{{"..."}}`) — one visual vocabulary for "a thing
+      # someone does" versus "a fact that happened", matching the
+      # language's own verb/event distinction. Command ids are qualified
+      # by their owning aggregate (`cmd_Order_Purchase`) since two
+      # aggregates may share a command name; event ids are bare
+      # (`evt_PizzaCreated`) since an event is this domain's own
+      # addressing key, the same way `policy.on_event` reaches it.
+      def dispatch_diagram(bluebook)
+        lines = []
+
+        holders(bluebook).each do |holder|
+          holder.commands.each do |command|
+            command.emits.each { |event| lines << emits_edge(holder, command, event) }
+          end
+        end
+
+        bluebook.policies.each { |policy| lines << trigger_edge(policy) }
+
+        lines.compact!
+        return nil if lines.empty?
+
+        subject = "#{bluebook.name}'s own declared commands' emits and policies' on/trigger"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def emits_edge(holder, command, event)
+        %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|emits| #{event_node(event)})
+      end
+
+      # `on_event` IS SOMETIMES AGGREGATE-QUALIFIED
+      # (`"Account.AccountFrozen"`) AND SOMETIMES BARE
+      # (`"CustomerSuspended"`) in the real corpus — `emits` never is,
+      # so this always matches against the bare tail, the same
+      # normalization a reader has to do by eye today.
+      #
+      # A TRIGGER CROSSING INTO ANOTHER DOMAIN (`policy.target_domain`)
+      # still draws — the target command just has no incoming `emits`
+      # edge of its own here, which honestly shows "dispatch continues
+      # elsewhere" rather than silently dropping the edge. The label
+      # names which domain, so that's not a dead end on the page either.
+      def trigger_edge(policy)
+        bare_event = policy.on_event.to_s.split(".").last
+        aggregate_name, command_name = policy.trigger_command.to_s.split(".", 2)
+        label = policy.target_domain ? "triggers in #{policy.target_domain}" : "triggers"
+        %(    #{event_node(bare_event)} -->|#{label}| #{command_node(aggregate_name, command_name)})
+      end
+
+      def command_node(aggregate_name, command_name)
+        %(cmd_#{aggregate_name}_#{command_name}(["#{aggregate_name}.#{command_name}"]))
+      end
+
+      def event_node(event_name) = %(evt_#{event_name}{{"#{event_name}"}})
+
+      # ── roles -> flowchart ────────────────────────────────────────────
+
+      # WHO ISSUES WHAT, ACROSS THE WHOLE DOMAIN — data no existing
+      # projection draws at all today (the reference pages' own
+      # `command_entry` only ever prints a command's role as a single
+      # line of prose, never assembled across commands). A command with
+      # no declared `role` draws nothing — there is no fact to state.
+      # Circle-shaped so a role reads as "who" beside `dispatch.mmd`'s
+      # stadium ("what someone does") and hexagon ("what happened").
+      def roles_diagram(bluebook)
+        lines = holders(bluebook).flat_map do |holder|
+          holder.commands.select(&:role).map { |command| role_edge(holder, command) }
+        end
+        return nil if lines.empty?
+
+        subject = "#{bluebook.name}'s own declared command roles"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def role_edge(holder, command)
+        %(    #{role_node(command.role)} -->|issues| #{command_node(holder.hecks_name, command.hecks_name)})
+      end
+
+      def role_node(role_name) = %(#{role_id(role_name)}((#{role_name})))
+
+      # A ROLE NAME IS FREE TEXT ("Back office", "Vault officer") —
+      # unlike every other name this file uses as a bare id, this one
+      # has to be sanitized to become a legal Mermaid identifier. The
+      # real string still appears as the node's own label
+      # (`role_node`); only the id is mangled.
+      def role_id(role_name) = "role_#{role_name.to_s.gsub(/[^A-Za-z0-9]+/, '_')}"
+
+      # ── ports -> flowchart ───────────────────────────────────────────
+
+      # A PORT OPERATION IS A BOUNDARY TRANSLATION, NOT A VERB OR A FACT —
+      # its own reference page says so plainly ("the builder behind it
+      # defines no `given` or `sets`, so an operation cannot read
+      # aggregate state or mutate a record itself"), so it gets a third
+      # shape, a trapezoid, beside `dispatch.mmd`'s stadium/hexagon
+      # vocabulary. An aggregate drawn as a `to:` target is a cylinder —
+      # state landing somewhere, the same reason a data store gets one
+      # in an ordinary flowchart.
+      #
+      # TWO EDGE KINDS PER OPERATION: a dotted "exposes" edge from the
+      # aggregate the port hangs off (always present — a port always
+      # belongs to exactly one aggregate), and a solid "to:" edge to
+      # whichever aggregate the operation itself names as its receiver
+      # (present only when `to:` is declared — PR #351's own real
+      # addition; before it, this data didn't exist to draw at all).
+      # `emits` reuses `dispatch.mmd`'s own `event_node` unchanged — the
+      # same fact, reached from a different direction.
+      #
+      # `bluebook.aggregates`, NOT the shared `holders` — unlike a
+      # lifecycle/relationship/command, a port belongs to an AGGREGATE
+      # only; an entity has no `ports` method at all (confirmed: calling
+      # it raises, it isn't just always empty), so walking entities here
+      # the way every other diagram in this file does would crash on
+      # the first entity-bearing domain.
+      def ports_diagram(bluebook)
+        lines = bluebook.aggregates.flat_map do |holder|
+          holder.ports.flat_map { |port| port.operations.map { |operation| port_edges(holder, port, operation) } }
+        end.flatten
+
+        return nil if lines.empty?
+
+        subject = "#{bluebook.name}'s own declared port operations (which aggregate exposes each, its to:, and its emits)"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def port_edges(holder, port, operation)
+        op = port_operation_node(holder.hecks_name, port.name, operation.hecks_name)
+        edges = ["    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|exposes| #{op}"]
+        edges << "    #{op} -->|to: #{operation.to}| #{operation.to}[(#{operation.to})]" if operation.to
+        operation.emits.each { |event| edges << "    #{op} -->|emits| #{event_node(event)}" }
+        edges
+      end
+
+      def port_operation_node(aggregate_name, port_name, operation_name)
+        id = "op_#{aggregate_name}_#{port_name}_#{operation_name}"
+        %(#{id}[/"#{port_name}.#{operation_name}"/])
+      end
+
+      # ── read models -> flowchart ─────────────────────────────────────
+
+      # THE READ-SIDE COMPLEMENT TO `relationships.mmd` — that diagram
+      # shows how aggregates reference each other for WRITES
+      # (`has_many`/`belongs_to`/`reference_to`); this shows how a
+      # `read_model` ASSEMBLES data for READS, from
+      # `aggregate_heads` — the same list `where`/`group_by`/`order_by`
+      # all operate over, and the one fact every read_model has
+      # regardless of whether it's rooted (`reference_target`) or
+      # gathers heads with no root at all (a rootless read model, real
+      # in the corpus: `AccountsByKind`).
+      #
+      # A READ MODEL IS A SUBROUTINE SHAPE (`[[...]]`, "a predefined
+      # process") — a fourth shape, beside `ports.mmd`'s trapezoid and
+      # `dispatch.mmd`'s stadium/hexagon: not a verb, not a fact, not a
+      # boundary translation, but a standing, reusable view. Every
+      # aggregate it draws from is a cylinder — the same "state lands
+      # somewhere" shape `ports.mmd`'s `to:` target already uses, and
+      # the same bare id, so an aggregate feeding several read_models
+      # (real in banking: `Account` feeds four) merges into one node
+      # across the whole diagram.
+      #
+      # THE LABEL NAMES THE SHAPE OF THE ANSWER, NOT JUST THE NAME —
+      # `(count)`/`(median: field)` for the two real aggregations in the
+      # corpus, nothing appended for an ordinary row-returning
+      # read_model. Still MVP scope: `where`/`group_by`/`order_by`
+      # aren't drawn at all yet — real facts, not invented, just not
+      # this diagram's job yet.
+      def read_model_diagram(bluebook)
+        lines = bluebook.read_models.flat_map { |read_model| read_model_edges(read_model) }
+        return nil if lines.empty?
+
+        subject = "#{bluebook.name}'s own declared read_models and the aggregates each is assembled from"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def read_model_edges(read_model)
+        shape = read_model.to_h
+        node = %(rm_#{shape[:name]}[["#{read_model_label(shape)}"]])
+        Array(shape[:aggregate_heads]).map do |head|
+          # QUOTED, NOT BARE — an edge label containing `[` or `]`
+          # (`accounts[]`, marking the "many" side) breaks Mermaid's own
+          # `|label|` parser outright if left unquoted: it reads the
+          # `[` as the START OF A NEW NODE SHAPE mid-label, not text.
+          # Confirmed live against the real parser before this quoting
+          # existed — every OTHER edge label in this file happens to be
+          # a bare word or already-quoted string, so this is the one
+          # spot that needed it.
+          label = head[:many] ? "#{head[:as]}[]" : head[:as]
+          %(    #{head[:aggregate]}[(#{head[:aggregate]})] -->|"#{label}"| #{node})
+        end
+      end
+
+      def read_model_label(shape)
+        return "#{shape[:name]} (count)" if shape[:count]
+        return "#{shape[:name]} (median: #{shape[:median_field]})" if shape[:median_field]
+
+        shape[:name]
+      end
+
+      # ── surface -> flowchart ─────────────────────────────────────────
+
+      # "WHAT CAN I DO TO THIS, WHAT CAN I ASK ABOUT IT" — one file per
+      # holder, unlike every other diagram here: `dispatch.mmd` already
+      # shows a command's own onward reaction chain, but never an
+      # aggregate's own FULL command/query menu in one place, and
+      # `roles.mmd` shows who issues a command without saying what else
+      # that same aggregate answers. This is the one diagram meant to
+      # be read starting from the aggregate, not from a verb or a fact.
+      #
+      # A QUERY IS A DIAMOND — a fifth shape, beside `dispatch.mmd`'s
+      # stadium/hexagon, `ports.mmd`'s trapezoid, and `read_models.mmd`'s
+      # subroutine: a question with an answer, not a verb that changes
+      # anything. Command edges are solid ("does"); query edges are
+      # dotted ("asks") — the same solid/dotted split `ports.mmd`
+      # already uses for "routes to:" versus "exposes".
+      def surface_diagram(bluebook, holder)
+        lines = holder.commands.map { |command| "    #{holder.hecks_name}[(#{holder.hecks_name})] -->|does| #{command_node(holder.hecks_name, command.hecks_name)}" }
+        lines += holder.queries.map { |query| "    #{holder.hecks_name}[(#{holder.hecks_name})] -.->|asks| #{query_node(holder.hecks_name, query.hecks_name)}" }
+
+        subject = "#{holder.hecks_name}'s own declared commands and queries"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def query_node(aggregate_name, query_name)
+        %(qry_#{aggregate_name}_#{query_name}{"#{aggregate_name}.#{query_name}"})
+      end
+    end
+  end
+end

data/lib/hecks/projections/ir.rb

@@ -0,0 +1,18 @@
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # The canonical IR, as a constant. The implementation already existed
+    # and is already golden-tested (`Projector::IRProjector`, registered
+    # as `:ir`) — this only gives it the constant spelling every other
+    # target has, by re-registering the SAME module under the same key.
+    #
+    # Deliberately not a new implementation: two things named `IR` that
+    # each rendered IR their own way is exactly the drift this namespace
+    # exists to avoid.
+    IR = Projector::IRProjector
+
+    IR.extend(Projector::Target)
+    IR.projects_as :ir, requires: Hecks::IR
+  end
+end

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

@@ -0,0 +1,98 @@
+module Hecks
+  module Projections
+    module Model
+      # 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
+      # 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
+      # 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`.
+        CONTAINED = {
+          "Bluebook"       => %i[aggregates read_models policies process_managers],
+          "Aggregate"      => %i[commands entities queries value_objects],
+          # S17, ADR 0026 — an entity may nest further entities now
+          # (`Dispatch`, inside `Handler`) — same containment edge as
+          # Aggregate's own `entities`, one level down.
+          "Entity"         => %i[commands entities queries],
+          "ValueObject"    => %i[members],
+          "ProcessManager" => %i[handlers]
+        }.freeze
+
+        # One model field gathered from several declared ones —
+        # contracts.rb's own `[:folded, ...]` shape, as the pair it is.
+        FOLDED = {
+          "Aggregate" => { lifecycle: %i[state_field state_start transitions] },
+          "Entity"    => { lifecycle: %i[state_field state_start transitions] },
+          "Query"     => { order_by: %i[order_field order_way] }
+        }.freeze
+
+        # The inverse of a fold, and it had no name at all: one declared
+        # field opening into several the model holds apart.
+        UNPACKED = {
+          "ReadModel" => { options: %i[wheres order_by limit] }
+        }.freeze
+
+        # Model-only, each for its own reason rather than by oversight.
+        COMPUTED = {
+          "Bluebook"    => { ir_version:     "the EMISSION's own version, not the domain's",
+                             canonical_form: "the normalisation table every reader needs beside the IR" },
+          "ValueObject" => { closed_set:     "an empty one_of and no one_of are otherwise indistinguishable" },
+          "Aggregate"   => { ports:          "declared in the hecksagon, attached after the aggregate exists" }
+        }.freeze
+
+        # 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 = {
+          "Policy"      => { aggregate: "the wire format is a pinned contract, and it does not carry " \
+                                        "where a policy was written before the builder hoisted it" },
+          "Bluebook"    => { formerly_known_as: "a rename's old name is a fact about the source",
+                             normalisations:    "the normalisation table rides on canonical_form instead" },
+          "ValueObject" => { rows: "the language's name for a closed set's members; emitted as `members`" }
+        }.freeze
+
+        # Emitted by `to_h`'s own merge rather than by `emits_ir` — the
+        # two constructs whose shape is genuinely not fixed, because the
+        # query specification layer grew options after them.
+        DYNAMIC_TAIL = {
+          "Query"     => %i[options],
+          "ReadModel" => %i[options group_by aggregate_heads count median_field]
+        }.freeze
+
+        module_function
+
+        # 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
+        def computed(name)     = COMPUTED.fetch(name, {}).keys
+        def contained(name)    = CONTAINED.fetch(name, [])
+        def folded(name)       = FOLDED.fetch(name, {})
+        def unpacked(name)     = UNPACKED.fetch(name, {})
+        def dynamic_tail(name) = DYNAMIC_TAIL.fetch(name, [])
+      end
+    end
+  end
+end

data/lib/hecks/projections/model.rb

@@ -0,0 +1,145 @@
+require_relative "model/deviations"
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # THE MODEL CLASSES, PROJECTED FROM THE LANGUAGE THAT DECLARES THEM.
+    #
+    # 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,
+    # 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
+    # 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
+    # language — and keeping them in one table is what would let a second
+    # host swap this file rather than edit thirteen.
+    module Model
+      extend Projector::Target
+
+      projects_as :model, declares: "Bluebook", emits: :files
+
+      # 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 = {
+        "Policy" => {
+          construct: "Policy",
+          file:      "policy.rb",
+          behaviour: "Behaviour::Policy",
+          readers:   %i[name on_event trigger_command target_domain 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",
+                       with_spec: "[]", aggregate: "nil" },
+          coerce:    { name: ".to_s", aggregate: "&.to_s" },
+          # 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
+          # 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)] } }" },
+          settles:   false
+        }
+      }.freeze
+
+      module_function
+
+      def call(bluebook:, options: {})
+        HOST.to_h { |name, host| [host.fetch(:file), render(bluebook, name, host)] }
+      end
+
+      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)}
+          # is where anything hand-written belongs.
+          require_relative "behaviour/#{File.basename(host.fetch(:file), ".rb")}"
+
+          module Hecks
+            module Bluebook
+              class #{name}
+                include Hecks::IR
+                include #{host.fetch(:behaviour)}
+
+          #{indent(emits(bluebook, name), 6)}
+
+          #{indent(readers(host), 6)}
+
+          #{indent(constructor(host), 6)}
+              end
+            end
+          end
+        RUBY
+      end
+
+      # The emission, keyed as the model spells it and sourced as the
+      # language declares it.
+      def emits(bluebook, name)
+        fields  = emitted_fields(bluebook, name)
+        renders = HOST.fetch(name).fetch(:renders, {})
+        width   = fields.map { |f| f.to_s.length }.max.to_i
+
+        "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
+      # 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 -
+          Deviations.off_the_wire(name) -
+          Deviations.dynamic_tail(name) -
+          Deviations.folded(name).values.flatten -
+          Deviations.unpacked(name).keys
+      end
+
+      def readers(host)
+        lines = ["attr_reader #{host.fetch(:readers).map { |r| ":#{r}" }.join(', ')}"]
+        accessors = host.fetch(:accessors, [])
+        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
+        # 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 { |a|
+          why = reasons[a]
+          (why ? "\n# #{a.upcase}, DECLARED AND DELIBERATELY OFF THE WIRE\n# #{wrap(why)}\n" : "") +
+            "attr_accessor :#{a}"
+        }).join("\n")
+      end
+
+      def constructor(host)
+        args = host.fetch(:defaults).map { |f, d| d ? "#{f}: #{d}" : "#{f}:" }.join(", ")
+        body = host.fetch(:defaults).keys.map { |f|
+          "  @#{f} = #{f}#{host.fetch(:coerce, {})[f]}"
+        }
+        body << "\n  settle" if host.fetch(:settles, true)
+
+        "def initialize(#{args})\n#{body.join("\n")}\nend"
+      end
+
+      def indent(text, by) = text.lines.map { |l| l.strip.empty? ? l : (" " * by) + l }.join
+      def wrap(text) = text.scan(/.{1,62}(?:\s|$)/).map(&:strip).join("\n# ")
+    end
+  end
+end