hecks 0.2.0 → 1.0.0

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

data/lib/hecks/projections/oidc.rb

@@ -0,0 +1,110 @@
+require_relative "../naming"
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # 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
+    # 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
+    # live runtime one dispatch at a time.
+    #
+    # This is that catalogue, and the two are checked against each other
+    # rather than merely coexisting: `verb` here is spelled exactly as
+    # `Runtime::Dispatcher#dispatch` takes it and exactly as
+    # `Bluebook#verbs` lists it, so a scope can never name a command
+    # the domain does not have (spec/projections/oidc_projection_spec.rb
+    # holds the two lists equal), and `role` is the same string
+    # `Ports::Authorization.holds_role?` compares against a real
+    # `Governance::RoleAssignment`.
+    #
+    # 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
+    # command actually demands, not merely which role vocabulary the
+    # application happened to mount.
+    #
+    # A command with no declared role projects `"role" => nil` rather
+    # than being dropped — an unguarded command is a real fact about the
+    # domain, and silently omitting it would make the manifest read as
+    # though the command did not exist.
+    module OIDC
+      extend Projector::Target
+
+      projects_as :oidc
+
+      module_function
+
+      # `audience:` overrides the domain name, for the ordinary case
+      # where the IdP's registered audience is a URL rather than a bare
+      # chapter name.
+      def call(bluebook:, options: {})
+        scopes = scopes_for(bluebook)
+
+        {
+          "audience" => (options[:audience] || bluebook.name).to_s,
+          "scopes"   => scopes,
+          "roles"    => scopes.map { |scope| scope["role"] }.compact.uniq.sort
+        }
+      end
+
+      # Sorted by scope, not left in declaration order — a manifest is
+      # something two versions of get diffed, and the same precedent
+      # `StorageShape.project` sets for its own aggregate list.
+      #
+      # Recurses into entities, not just an aggregate's own direct
+      # commands — the exact same gap `Bluebook#verbs` closed for the
+      # same reason (`chapter.rb`'s own comment): a command reached
+      # through `Dispatcher#dispatch`'s dotted `Entity.Command` routing
+      # is real and callable, so a manifest that never names it can
+      # never grant a client a scope for it either.
+      def scopes_for(bluebook)
+        bluebook.aggregates.flat_map { |aggregate| aggregate_scopes(bluebook, aggregate) }
+                .sort_by { |scope| scope["scope"] }
+      end
+
+      def aggregate_scopes(bluebook, aggregate)
+        verb_prefix  = "#{bluebook.name}::#{aggregate.hecks_name}"
+        scope_prefix = "#{Naming.snake(bluebook.name)}:#{Naming.snake(aggregate.hecks_name)}"
+
+        command_scopes(aggregate.commands, verb_prefix, scope_prefix) +
+          aggregate.entities.flat_map { |entity| entity_scopes(entity, verb_prefix, scope_prefix) }
+      end
+
+      # S17, ADR 0026 — an entity can nest further entities (`Dispatch`,
+      # inside `Handler`), so this recurses the same way `Chapter#verbs`
+      # now does. The verb and scope prefixes grow in lockstep, each
+      # `.`-joined the same way its own kind already was.
+      def entity_scopes(entity, verb_prefix, scope_prefix)
+        verb_prefix  = "#{verb_prefix}.#{entity.hecks_name}"
+        scope_prefix = "#{scope_prefix}.#{Naming.snake(entity.hecks_name)}"
+
+        command_scopes(entity.commands, verb_prefix, scope_prefix) +
+          entity.entities.flat_map { |piece| entity_scopes(piece, verb_prefix, scope_prefix) }
+      end
+
+      # `banking:account.open` — the shape an OIDC scope is conventionally
+      # 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)
+        commands.map do |command|
+          {
+            "scope" => "#{scope_prefix}.#{Naming.snake(command.hecks_name)}",
+            "verb"  => "#{verb_prefix}.#{command.hecks_name}",
+            "role"  => command.role
+          }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/parser_table.rb

@@ -0,0 +1,159 @@
+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
+    # 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
+    # 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
+      extend Projector::Target
+      projects_as :parser_table, declares: "Syntax"
+
+      module_function
+
+      def call(bluebook:, options: {}) = render(bluebook)
+
+      module_function
+
+      # 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.
+      def syntax(bluebook) = bluebook.aggregate("Syntax")
+
+      # Every cell as text — exactly spec/syntax_conformance_spec.rb's own
+      # `rows` helper, reused rather than re-derived: a member's fields decode
+      # back through typed literal decoding on the way out of reconstruction,
+      # and this reads it back as what was written.
+      def rows(bluebook, name)
+        syntax(bluebook).value_objects.find { |vo| vo.hecks_name == name }
+              .members.map { |row| row.to_h.transform_values(&:to_s) }
+      end
+
+      def closed_set_members(bluebook, name) = rows(bluebook, name).map { |row| row[:name] }
+
+      KEYWORD_FIELDS  = %i[word context body inner opens fills status was resolves_via disambiguator].freeze
+      ARGUMENT_FIELDS = %i[keyword context at named kind required fills selects
+                           pair_key_fills pair_value_fills pairs_shape status variadic minimum].freeze
+
+      # A Rust string literal for one field's value — every field here is
+      # plain ASCII (a word, a context name, a digit, "true"/"false"), so this
+      # only has to be safe against the two characters Rust string literals
+      # themselves reserve.
+      def rust_string(value) = "\"#{value.to_s.gsub('\\', '\\\\\\\\').gsub('"', '\\"')}\""
+
+      def keyword_row(row)
+        fields = KEYWORD_FIELDS.map { |field| rust_string(row[field]) }
+        "    KeywordRow { #{KEYWORD_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
+      end
+
+      def argument_row(row)
+        fields = ARGUMENT_FIELDS.map { |field| rust_string(row[field]) }
+        "    ArgumentRow { #{ARGUMENT_FIELDS.zip(fields).map { |name, value| "#{name}: #{value}" }.join(', ')} },"
+      end
+
+      def const_str_array(name, values)
+        lines = values.map { |value| "    #{rust_string(value)}," }
+        "pub static #{name}: &[&str] = &[\n#{lines.join("\n")}\n];\n"
+      end
+
+      # 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
+      # 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
+      # — symbol keys, string values, `status` included — so nothing
+      # else in this file needed to change.
+      def render(bluebook)
+        table     = Hecks::Bluebook::MetaValidator::SyntaxBoot.call
+        keywords  = table[:keywords]
+        arguments = table[:arguments]
+
+        <<~RUST
+          // GENERATED by bin/project_parser_table from
+          // aggregate-local syntax tables under lib/hecks/language/ — DO NOT EDIT BY HAND.
+          //
+          // Re-run `bin/project_parser_table` after any syntax-table change.
+          // spec/parser_table_spec.rb regenerates this into memory and fails the
+          // normal `bundle exec rspec` suite the moment this file drifts from what
+          // the language currently declares — see that spec and
+          // bin/project_parser_table's own header for why this file is never
+          // hand-edited.
+
+          #[derive(Debug, Clone, Copy)]
+          pub struct KeywordRow {
+              pub word: &'static str,
+              pub context: &'static str,
+              pub body: &'static str,
+              pub inner: &'static str,
+              pub opens: &'static str,
+              pub fills: &'static str,
+              pub status: &'static str,
+              pub was: &'static str,
+              /// Which shared Hecks::Bluebook::DSL::RuleReference
+              /// primitive this word's own bare form resolves through,
+              /// once it has one ("hash_chain" / "owner_keyed" /
+              /// "sibling_scan") — "" for every word that only ever
+              /// declares.
+              pub resolves_via: &'static str,
+              /// Which disambiguator keyword argument a bare reference
+              /// may supply — "declared_by" today, "" otherwise.
+              pub disambiguator: &'static str,
+          }
+
+          #[derive(Debug, Clone, Copy)]
+          pub struct ArgumentRow {
+              pub keyword: &'static str,
+              pub context: &'static str,
+              pub at: &'static str,
+              pub named: &'static str,
+              pub kind: &'static str,
+              pub required: &'static str,
+              pub fills: &'static str,
+              pub selects: &'static str,
+              pub pair_key_fills: &'static str,
+              pub pair_value_fills: &'static str,
+              pub pairs_shape: &'static str,
+              pub status: &'static str,
+              pub variadic: &'static str,
+              pub minimum: &'static str,
+          }
+
+          impl KeywordRow {
+              /// An absent status reads as admitted — the grown-column convention
+              /// syntax_conformance_spec.rb's own `status_of`/`live?` already use.
+              pub fn live(&self) -> bool {
+                  matches!(self.status, "" | "admitted" | "deprecated")
+              }
+          }
+
+          impl ArgumentRow {
+              pub fn live(&self) -> bool {
+                  matches!(self.status, "" | "admitted" | "deprecated")
+              }
+          }
+
+          pub static KEYWORDS: &[KeywordRow] = &[
+          #{keywords.map { |row| keyword_row(row) }.join("\n")}
+          ];
+
+          pub static ARGUMENTS: &[ArgumentRow] = &[
+          #{arguments.map { |row| argument_row(row) }.join("\n")}
+          ];
+
+          #{const_str_array('CONTEXTS', closed_set_members(bluebook, 'Context'))}
+          #{const_str_array('BODIES', closed_set_members(bluebook, 'Body'))}
+          #{const_str_array('ARGUMENT_KINDS', closed_set_members(bluebook, 'ArgumentKind'))}
+          #{const_str_array('PAIRS_SHAPES', closed_set_members(bluebook, 'PairsShape'))}
+          #{const_str_array('STATUSES', closed_set_members(bluebook, 'Status'))}
+        RUST
+      end
+    end
+  end
+end

data/lib/hecks/projections/reference.rb

@@ -0,0 +1,38 @@
+require_relative "../doc/reference"
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # 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,
+    # 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
+    # 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.
+    module Reference
+      extend Projector::Target
+
+      projects_as :reference, declares: "Syntax", emits: :files
+
+      module_function
+
+      def call(bluebook:, options: {})
+        from = options[:from] or
+          raise ArgumentError,
+                ":reference harvests prose from the committed pages, so it needs " \
+                "`from:` — the directory they live in"
+
+        Doc::Reference.pages(from)
+      end
+    end
+  end
+end

data/lib/hecks/projections/shape.rb

@@ -0,0 +1,44 @@
+require_relative "../ports/persistence"
+require_relative "../projector"
+
+module Hecks
+  module Projections
+    # THE STORAGE SHAPE of one bluebook — the same structural form
+    # `StorageShape.mint_hash` hashes to name an era, which is what makes
+    # a bump/no-bump question answerable by diffing two of these.
+    #
+    # THE RETROFIT, and the point of it: `Runtime::StorageShape.project`
+    # was written long before this framework existed, and it already
+    # takes exactly one bluebook, already returns a plain Hash, already
+    # touches no disk and no live runtime — it even already uses the
+    # word. Nothing about it was shaped to fit `call(bluebook:, options:)`.
+    #
+    # That it fits anyway, by a two-line keyword adapter and no change to
+    # `StorageShape` itself, is the evidence that the protocol is a real
+    # description of what projections do here rather than a shape fitted
+    # around its own first example (`:ir`, whose `call` is `to_h`, proves
+    # much less on its own).
+    module Shape
+      extend Projector::Target
+
+      projects_as :shape
+
+      module_function
+
+      # ADR 0033 — `Runtime::StorageShape` lives in the era persistence
+      # plugin now; the `:shape` projection itself stays registered
+      # unconditionally (the seam `spec/projector_seam_spec.rb` enforces
+      # is "every file here registers," not "every projection always
+      # succeeds") but refuses clearly if asked to run with the plugin
+      # unloaded, rather than raising on an undefined constant.
+      def call(bluebook:, options: {})
+        unless Ports::Persistence.plugin?(:era)
+          raise "the :shape projection needs the era persistence plugin loaded " \
+                "(require \"hecks/ports/persistence/plugins/era\")"
+        end
+
+        Runtime::StorageShape.project(bluebook)
+      end
+    end
+  end
+end