hecks 0.3.0 → 1.0.0

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/audit/layer_two.rb

@@ -1,5 +1,5 @@
-require_relative "../../ports/persistence/append_only"
-require_relative "../../ports/persistence/lineage"
+require_relative "../../../../../../ports/persistence/append_only"
+require_relative "../../lineage"
 
 module Hecks
   module Translation
@@ -53,15 +53,14 @@ module Hecks
           return if rekeyed
 
           rules = Ports::Persistence::Lineage.from_declared(declared, aggregate.name)
-          compute_tops = declared.computes.flat_map { |compute| [compute.from, compute.to] }
-                                 .map { |path| path.to_s.split(".").first }
+          compute_paths = declared.computes.flat_map { |compute| [compute.from, compute.to] }.map(&:to_s)
 
           before.each do |id, state|
             next unless after.key?(id)
 
             entry = Ports::Persistence::Entry.new(operation: "save", id: id, state: state.transform_keys(&:to_sym))
-            expected = normalize(rules.translate(entry).state).reject { |key, _| compute_tops.include?(key) }
-            actual = normalize(after[id]).reject { |key, _| compute_tops.include?(key) }
+            expected = strip_compute_paths(normalize(rules.translate(entry).state), compute_paths)
+            actual = strip_compute_paths(normalize(after[id]), compute_paths)
             next if expected == actual
 
             diverged = (expected.keys | actual.keys).select { |key| expected[key] != actual[key] }
@@ -71,6 +70,32 @@ module Hecks
         end
 
         def normalize(state) = JSON.parse(JSON.generate(state))
+
+        # Exempts exactly the paths a compute owns, not the whole
+        # top-level attribute it happens to live under. A bare path
+        # ("price_cents") is itself the compute's entire value — dropping
+        # the whole top-level key is correct, there's nothing else there
+        # to check. A DOTTED path ("price.cents") only owns that one
+        # member of the value object it reaches into; every sibling
+        # member (e.g. "price.currency") is untouched by the compute and
+        # must stay subject to the equivalence check below. Blanket-
+        # dropping the whole top-level key for a dotted compute used to
+        # exempt the entire attribute — silent data loss elsewhere in the
+        # same value object (a migration that nulls or drops a sibling
+        # field) produced zero violations, defeating the one gate whose
+        # entire purpose is to catch exactly that.
+        def strip_compute_paths(state, paths)
+          paths.each do |path|
+            segments = path.split(".")
+            if segments.length == 1
+              state.delete(segments.first)
+            else
+              parent = segments[0..-2].reduce(state) { |node, segment| node.is_a?(Hash) ? node[segment] : nil }
+              parent.delete(segments.last) if parent.is_a?(Hash)
+            end
+          end
+          state
+        end
       end
     end
   end

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/audit/unfed_report.rb

@@ -33,7 +33,11 @@ module Hecks
           path.to_s.split(".").reduce(state) do |node, segment|
             break nil unless node.is_a?(Hash)
 
-            node[segment] || node[segment.to_sym]
+            # `key?` decides which spelling answers, never `||` — a
+            # `false` genuinely held at this path must not fall through
+            # to the other spelling (usually absent) and read as `nil`,
+            # which would wrongly mark a `false`-valued attribute "unfed".
+            node.key?(segment) ? node[segment] : node[segment.to_sym]
           end
         end
       end

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/reattest.rb

@@ -1,7 +1,7 @@
 require "tempfile"
-require_relative "../runtime/era_guard"
-require_relative "../runtime/registry"
-require_relative "../runtime/storage_shape"
+require_relative "../era_guard"
+require_relative "../../../../../runtime/registry"
+require_relative "../storage_shape"
 
 module Hecks
   module Translation

data/lib/hecks/{translation → ports/persistence/plugins/era/translation}/scaffold/differ.rb

@@ -1,4 +1,4 @@
-require_relative "../../runtime/storage_shape"
+require_relative "../../storage_shape"
 
 module Hecks
   module Translation

data/lib/hecks/ports/persistence/plugins/era.rb

@@ -0,0 +1,48 @@
+require_relative "../plugin"
+require_relative "era/era_check"
+require_relative "era/era_guard"
+require_relative "era/era_tamper"
+require_relative "era/storage_shape"
+require_relative "era/lineage"
+require_relative "era/postgres_era"
+require_relative "era/translation"
+
+module Hecks
+  module Ports
+    module Persistence
+      module Plugins
+        # ADR 0033 — requiring THIS FILE is installing the plugin. Nothing in
+        # Hecks core requires it; an app that binds `PostgresEra`, or wants
+        # schema-translation support at all, requires it explicitly — the
+        # same shape every adapter-specific spec fixture already uses to
+        # load one particular `.adapter` file rather than all of them.
+        module Era
+          module_function
+
+          # `Runtime::Loader.run_boot_gates!` asks every loaded persistence
+          # plugin to contribute here, generically — it never mentions
+          # `EraCheck` or "era" by name. Two gates, both `:pre_verify`:
+          #
+          # `:era_compute_rules` — unconditional, whenever this plugin is
+          # loaded at all. A `compute`/`rekey` rule requires Postgres
+          # whatever adapter is actually bound (ADR 0031's own reasoning,
+          # unchanged) — this is the rich, adapter-aware version of that
+          # check; `Runtime::Loader`'s own structural backstop (plain
+          # `Bluebook::Translation` data, no plugin-specific class) only
+          # ever fires when NO persistence plugin is loaded at all.
+          #
+          # `:era_check` — conditional, exactly ADR 0031's own gate,
+          # unchanged: registered only when this registry has an aggregate
+          # actually bound to a lineage-capable adapter.
+          def contribute_boot_gates(registry, gates)
+            gates.register(:era_compute_rules, ->(reg, _dir) { Runtime::EraCheck.check_compute_rules_for_registry!(reg) }, phase: :pre_verify)
+            gates.register(:era_check, Runtime::EraCheck.method(:check_lineage!), phase: :pre_verify) if
+              Runtime::EraCheck.lineage_capable_registry?(registry)
+          end
+        end
+      end
+    end
+  end
+end
+
+Hecks::Ports::Persistence.register_plugin(:era, Hecks::Ports::Persistence::Plugins::Era)

data/lib/hecks/ports/persistence.rb

@@ -9,7 +9,7 @@ module Hecks
 end
 
 require_relative "persistence/binding_policy"
-require_relative "persistence/lineage"
+require_relative "persistence/plugin"
 require_relative "persistence/repository_factory"
 require_relative "persistence/append_only"
 require_relative "persistence/execution"

data/lib/hecks/ports/projection.rb

@@ -29,10 +29,30 @@ module Hecks
       class Worker
         attr_reader :projection
 
+        # The only two policies anything in this codebase ever passes
+        # (`bin/project`, every spec) — there is no third, legitimate
+        # "lenient append" policy on record anywhere. Before this, any
+        # value OTHER than the exact symbol `:strict` silently fell
+        # through the `consistent?` check below and appended onto
+        # divergent history without a word — not just a real typo like
+        # `:strikt`, but a caller-supplied String `"strict"` too (this
+        # duck-typed fine via `policy.to_sym`, but that was luck, not a
+        # contract: nothing here declared what a valid policy even was).
+        # Refusing loudly at construction, once, for anything outside
+        # this list turns a silent no-op into an immediate, named error
+        # — the "refuse rather than silently skip" reading of L1, since
+        # `:strict` really is meant to be the only enforcing contract.
+        VALID_POLICIES = %i[refresh strict].freeze
+
         def initialize(authoritative, projection, policy: :refresh)
           @authoritative = authoritative
           @projection = projection
           @policy = policy.to_sym
+          unless VALID_POLICIES.include?(@policy)
+            raise ArgumentError,
+                  "unknown projection catch_up! policy #{@policy.inspect} — expected one of " \
+                  "#{VALID_POLICIES.map(&:inspect).join(' or ')}"
+          end
         end
 
         # Invoke from a separate process or scheduler. The command-side write

data/lib/hecks/projections/diagrams.rb

@@ -48,7 +48,19 @@ module Hecks
     #                                          declares at least one command
     #                                          or query — everything you can
     #                                          DO to it and ASK about it,
+    #                                          AND what each command WRITES,
     #                                          in one place
+    #   <Name>_saga.mmd       stateDiagram-v2  one per process_manager —
+    #                                          its own states, and what
+    #                                          each transition dispatches
+    #                                          elsewhere in the domain
+    #   frameworks.mmd        flowchart        every OTHER domain this one
+    #                                          depends on — a shared
+    #                                          framework it `uses_framework`,
+    #                                          or a domain a policy reaches
+    #                                          `across` — the one diagram
+    #                                          here that looks OUTWARD past
+    #                                          this domain's own boundary
     #
     # CONSTRUCT NAMES (aggregate/entity/command/event) ARE USED BARE,
     # UNSANITIZED, as Mermaid node/entity ids — safe because this
@@ -100,6 +112,14 @@ module Hecks
           files["#{holder.hecks_name}_surface.mmd"] = surface_diagram(bluebook, holder)
         end
 
+        bluebook.process_managers.each do |saga|
+          files["#{saga.hecks_name}_saga.mmd"] = saga_diagram(bluebook, saga)
+        end
+
+        if (diagram = frameworks_diagram(bluebook, options[:hecksagon]))
+          files["frameworks.mmd"] = diagram
+        end
+
         files
       end
 
@@ -397,17 +417,226 @@ module Hecks
       # 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".
+      #
+      # A WRITE TARGET IS A PLAIN RECTANGLE — a sixth shape, the first
+      # here with no special bracket at all: an attribute is the
+      # smallest, most passive thing this vocabulary names, a single
+      # field living INSIDE the cylinder rather than a bounded thing of
+      # its own. `command.mutations` (`sets`/`increment`/`decrement`/
+      # `append`) was invisible everywhere before this — not just in a
+      # diagram, in ANY projection, including the prose ones — despite
+      # being the single densest fact in the whole IR (53 real
+      # mutations across pizzas + banking). `dispatch.mmd` draws what a
+      # command EMITS; this draws what it WRITES, the other half of
+      # "what actually happens" a command never showed before.
+      #
+      # THE SAME ATTRIBUTE NODE MERGES ACROSS COMMANDS — real in
+      # banking: `Account.Credit` and `Account.Debit` both point at the
+      # same `balance` node, the same "one node, several incoming
+      # edges" merge `read_models.mmd` already does for an aggregate
+      # fed by several read_models.
+      #
+      # THE LABEL NAMES THE REAL SOURCE, NOT JUST THE VERB — an
+      # increment/decrement/set almost always takes its value from an
+      # argument, but not always the SAME-NAMED one: real in banking,
+      # `Account.Credit`'s own `balance` is incremented by its
+      # `amount` argument, and `LedgerEntry.Amend`'s own `amount` is
+      # incremented by its `adjustment` argument. A literal source
+      # (pizzas' own `Order.Purchase` sets `status` to the literal
+      # `"sold"`, not an argument at all) is named as verbatim as
+      # every other fact in this file. `append`'s own fields carry no
+      # single source at all — its own field NAMES are the fact worth
+      # stating (real: `Order.AddTopping` appends `name, amount`).
       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.commands.flat_map { |command| command.mutations.map { |mutation| mutation_edge(holder, command, mutation) } }
         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"
+        subject = "#{holder.hecks_name}'s own declared commands (and what each writes) 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
+
+      def mutation_edge(holder, command, mutation)
+        shape = mutation.to_h
+        label = mutation_label(shape)
+        target = attribute_node(holder.hecks_name, shape[:target])
+        %(    #{command_node(holder.hecks_name, command.hecks_name)} -->|"#{label}"| #{target})
+      end
+
+      def mutation_label(shape)
+        verb = "#{shape[:op]}s"
+        # `fields:` (not `source:`) IS the multi-binding shape
+        # (`Mutation#to_h`'s own `[:append, :delegate, :corrects]`
+        # branch) — checked by the KEY'S PRESENCE, not by re-listing
+        # which ops use it a second time here, the same lesson
+        # `Change.op`'s own `admits: Vocabulary::MutationOp` already
+        # drew (command.bluebook's own comment): a second list of "the
+        # ops that mean multi-binding" is exactly the kind of copy that
+        # drifts — `:delegate` already carried this shape with nothing
+        # here reading it correctly, caught only once `:corrects` gave
+        # banking's own real diagrams a fields:-shaped mutation to
+        # actually render.
+        detail = shape[:fields] ? shape[:fields].keys.join(", ") : mutation_source_detail(shape[:source])
+        "#{verb}: #{detail}"
+      end
+
+      # A LITERAL VALUE CAN CONTAIN A DOUBLE QUOTE OF ITS OWN — real in
+      # banking: `Customer.Reinstate` sets `standing` to a rendered
+      # value-object literal, `{:value=>"good"}`, whose own embedded `"`
+      # broke this label's outer `|"..."|` quoting outright (caught by
+      # running the real generated output through mermaid.parse(), not
+      # by eye — the same way `read_models.mmd`'s own unquoted `[]` bug
+      # was caught). Swapped for a single quote here rather than
+      # escaped, the same "state it, don't invent it, just make it
+      # legal Mermaid" trade `read_models.mmd`'s own quoting fix made.
+      def mutation_source_detail(source)
+        case source[:kind]
+        when "literal"  then "'#{source[:value].to_s.tr('"', "'")}'"
+        when "argument" then source[:name]
+        else source[:kind] # a source kind this file has no real corpus example of yet — named, not hidden
+        end
+      end
+
+      def attribute_node(holder_name, attribute_name)
+        %(attr_#{holder_name}_#{attribute_name}[#{attribute_name}])
+      end
+
+      # ── sagas -> stateDiagram-v2 ─────────────────────────────────────
+
+      # A SAGA HAS A LIFECYCLE TOO — the same `stateDiagram-v2` shape
+      # `lifecycle_diagram` already draws, one file per process_manager
+      # the same way lifecycle is one file per lifecycle-bearing holder.
+      # What's different is the label: a lifecycle's own edge is labeled
+      # by the COMMAND that causes it (an aggregate transitions because
+      # something was DONE to it); a saga's edge is labeled by the EVENT
+      # that causes it (a saga advances because something HAPPENED,
+      # possibly nowhere near the saga itself) — the same command/event
+      # split `dispatch.mmd`'s own stadium/hexagon vocabulary already
+      # draws, here spent on which noun labels a stateDiagram-v2 edge
+      # instead.
+      #
+      # THE LABEL ALSO NAMES WHAT THE TRANSITION DISPATCHES — a fact no
+      # existing diagram states for a saga at all: a lifecycle's own
+      # edge only ever names the one command that caused it; a saga's
+      # edge can fire several commands at once (real in banking:
+      # Settlement's own AccountDebited handler dispatches both
+      # Transfer.Debited and Account.Credit). Confirmed real in the
+      # corpus: no saga dispatch ever declares a `to:`/`target_domain`
+      # of its own (unlike a policy's `across`) — every command a saga
+      # fires lands inside its own bluebook chapter, so this never needs
+      # `dispatch.mmd`'s own "triggers in X" cross-domain label.
+      #
+      # THE COMPENSATING LEG READS LIKE ANY OTHER — its own trigger is
+      # the literal string "refused" (`ProcessManager::REFUSED`, this
+      # language's own Trigger vocabulary), not invented text: a
+      # dispatch declined is exactly as real a cause of a state
+      # transition as an event announced, and the diagram states it
+      # exactly as verbatim as every other edge here does.
+      def saga_diagram(bluebook, saga)
+        edges = saga.handlers.map { |handler| saga_edge(handler, saga) }
+
+        subject = "#{saga.hecks_name}'s own declared states and what each transition dispatches " \
+                  "(starts on #{saga.starts_on}, ends on #{saga.ends_on})"
+        <<~MERMAID
+          #{header(bluebook.name, subject)}stateDiagram-v2
+              [*] --> #{saga.states.first}
+          #{edges.join("\n")}
+        MERMAID
+      end
+
+      # THE REFUSED EDGE'S OWN DISPATCH LIST IS PARTLY DERIVED NOW —
+      # per-dispatch saga compensation (`compensates`) moved a saga's own
+      # compensating dispatches OFF the hand-written `on :refused` leg
+      # and onto whichever forward dispatch each one undoes, so
+      # `handler.dispatches` alone would render an EMPTY compensating
+      # edge for any saga using it — accurate to the DECLARATION, wrong
+      # about what the runtime actually does at refusal (it derives and
+      # fires every declared `compensates`, newest first). `saga` is
+      # passed through for exactly this — only the REFUSED handler needs
+      # it, every other edge's own `handler.dispatches` already says
+      # everything real about it.
+      def saga_edge(handler, saga)
+        label = handler.event_type
+        # DERIVED FIRST, then the hand-written body — the same order
+        # `SagaInterpreter#unwind` actually runs them in (every
+        # completed leg's own `compensates` before this leg's own
+        # hand-written dispatches), not declaration order on the page.
+        dispatched = handler.event_type == Bluebook::ProcessManager::REFUSED ? derived_compensations(saga) : []
+        dispatched += handler.dispatches.map(&:command_name)
+        label += " / dispatches #{dispatched.join(', ')}" unless dispatched.empty?
+
+        "    #{handler.from_state} --> #{handler.to_state}: #{label}"
+      end
+
+      # Every `compensates` any forward dispatch in this saga declares,
+      # declaration order — the same commands `SagaInterpreter#unwind`
+      # derives and fires (newest-first, at actual refusal time; this
+      # diagram states them in declaration order, since it draws the
+      # saga's own shape, not one instance's own runtime history).
+      def derived_compensations(saga)
+        saga.handlers.flat_map { |handler| handler.dispatches.filter_map { |dispatch| dispatch.compensates&.command_name } }
+      end
+
+      # ── frameworks -> flowchart ─────────────────────────────────────
+
+      # EVERY OTHER DIAGRAM IN THIS FILE STAYS INSIDE ONE DOMAIN'S OWN
+      # BOUNDARY — this is the one that steps outside it. A real domain
+      # depends on another domain's own aggregates in exactly two ways:
+      # `uses_framework "X"` in its `.hecksagon` (`Hecksagon#framework_
+      # members`), which loads X's whole bluebook into THIS registry,
+      # unconditionally, the moment this domain boots; or a policy's own
+      # `across "X"` (`Policy#target_domain`), which only reaches X when
+      # the policy's declared event actually fires. Same underlying
+      # fact `dispatch.mmd`'s own `trigger_edge` already draws from the
+      # command's side ("triggers in X") — this draws it again from the
+      # DOMAIN's side, next to the structural `uses_framework` fact
+      # `dispatch.mmd` never sees at all (that lives in the `.hecksagon`,
+      # which no other diagram here is handed).
+      #
+      # NEITHER THIS DOMAIN NOR EACH DEPENDENCY GETS THE holders() TREATMENT
+      # — a whole domain is drawn as ONE cylinder, the same "a bounded,
+      # addressable thing" shape every other diagram here already spends
+      # on a single aggregate, just scaled up one level: a domain is a
+      # bigger box the same kind of box lives inside.
+      #
+      # DOTTED FOR `attaches`, SOLID FOR `reaches across` — the reverse
+      # of which fact is "always true" between the two: attaching a
+      # framework is a standing declaration, true every time this domain
+      # boots, so it gets the same dotted "this always belongs" treatment
+      # `ports.mmd` gives an aggregate's own `-.->|exposes|` edge.
+      # Reaching across only happens when a real policy actually fires —
+      # the same solid edge `dispatch.mmd`'s own `trigger_edge` already
+      # draws for the identical fact, kept solid here so the same
+      # relationship reads the same way in both diagrams.
+      #
+      # `options[:hecksagon]` IS THE ONE DIAGRAM IN THIS FILE THAT NEEDS
+      # MORE THAN `bluebook` — `framework_members` lives on the
+      # `Hecksagon`, a sibling IR object `bin/project_diagrams` already
+      # has in hand (`registry.hecksagon(chapter_name)`) but `bluebook`
+      # itself carries no reference to. No hecksagon handed in (an older
+      # caller, or a spec that doesn't care) just means no frameworks.mmd
+      # — same "nothing to state" skip every other diagram here already
+      # takes when its own underlying data is empty.
+      def frameworks_diagram(bluebook, hecksagon)
+        return nil unless hecksagon
+
+        lines = hecksagon.framework_members.map { |name| domain_edge(bluebook.name, "attaches", name, dotted: true) }
+        lines += bluebook.policies.filter_map(&:target_domain).uniq
+                         .map { |name| domain_edge(bluebook.name, "reaches across", name, dotted: false) }
+        return nil if lines.empty?
+
+        subject = "#{bluebook.name}'s own declared uses_framework and cross-domain policy targets"
+        "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
+      end
+
+      def domain_edge(from, label, to, dotted:)
+        arrow = dotted ? "-.->" : "-->"
+        %(    #{from}[(#{from})] #{arrow}|#{label}| #{to}[(#{to})])
+      end
     end
   end
 end

data/lib/hecks/projections/shape.rb

@@ -1,4 +1,4 @@
-require_relative "../runtime/storage_shape"
+require_relative "../ports/persistence"
 require_relative "../projector"
 
 module Hecks
@@ -25,7 +25,20 @@ module Hecks
 
       module_function
 
-      def call(bluebook:, options: {}) = Runtime::StorageShape.project(bluebook)
+      # 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

data/lib/hecks/projector/cli_projector.rb

@@ -192,7 +192,8 @@ module Hecks
         end
 
         { verb: fqn(bluebook, aggregate, command, entity), kind: :command,
-          summary: command.goal, role: command.role, creates: command.creates?,
+          summary: command.goal, role: command.role, role_gated: !command.role.to_s.empty?,
+          creates: command.creates?,
           receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
           legacy_arguments: legacy_arguments,
           refusals: refusals(command, holder), arguments: arguments }
@@ -227,7 +228,15 @@ module Hecks
         # names it short, which is the same split `shorten` already makes.
         { verb: [fqn(bluebook, aggregate, operation).sub(/\.[^.]+\z/, ""), port.name, operation.hecks_name].join("."),
           kind: :command, creates: false, receiver: :aggregate, refusals: [],
+          # `role:` HERE IS DESCRIPTIVE TEXT, NOT AN AUTHORIZATION GATE —
+          # who calls whom through the port, for `--help`/`verb_help`'s
+          # "issued by" line. A port operation never reaches
+          # `CommandRules::Authorization#refuse_role_mismatch` (only
+          # `CommandInterpreter`/`EntityInterpreter` call it, never the port
+          # dispatch path), so `role_gated: false` always, unlike
+          # `command_spec` where the same key name means a real one.
           role: operation.outbound? ? "#{aggregate.hecks_name} asking #{port.name}" : "#{port.name} telling #{aggregate.hecks_name}",
+          role_gated: false,
           summary: port_summary(port, operation), arguments: arguments }
       end
 

data/lib/hecks/projector/exporter.rb

@@ -1,6 +1,5 @@
 require "json"
-require_relative "../runtime/era_check"
-require_relative "../translation/rule_compiler"
+require_relative "../ports/persistence"
 
 module Hecks
   module Projector
@@ -30,7 +29,15 @@ module Hecks
       # Reuses `Runtime::EraCheck`'s own capability predicates rather than
       # re-deriving them — the boot-time gate and this export must never
       # answer differently for the same aggregate.
+      #
+      # ADR 0033 — `Runtime::EraCheck` lives in the (optional) era
+      # persistence plugin now; unloaded, this answers exactly what it
+      # already answers for a domain with nothing lineage-capable bound —
+      # `capable_aggregates: []` — rather than raising on an undefined
+      # constant.
       def lineage(registry, domain_name)
+        return { capable_aggregates: [] } unless Ports::Persistence.plugin?(:era)
+
         bluebook = registry.bluebooks.fetch(domain_name)
         capable = bluebook.aggregates.select do |aggregate|
           adapter_name = Runtime::EraCheck.adapter_for(registry, domain_name, aggregate)
@@ -130,7 +137,17 @@ module Hecks
       # expression` is nil unless this edge rekeys — the bare
       # `aggregate_id` passthrough head_compiler.rb itself falls back to
       # for the overwhelming common case.
+      # ADR 0033 — `Translation::RuleCompiler` lives in the era plugin;
+      # unloaded, there is nothing that can compile this SQL, so this
+      # falls back to the bare declared fields (`translation_aggregate`
+      # alone) rather than raising on an undefined constant. A consumer
+      # embedding this JSON without the era plugin loaded gets the same
+      # declared-rules shape, just without precompiled SQL to execute —
+      # consistent with there being no mint/audit machinery to run it
+      # against either.
       def compiled_translation_aggregate(aggregate)
+        return translation_aggregate(aggregate) unless Ports::Persistence.plugin?(:era)
+
         translation_aggregate(aggregate).merge(
           compiled_state_expression: Translation::RuleCompiler.compile_rules(aggregate),
           compiled_id_expression:    Translation::RuleCompiler.rekeyed?(aggregate) ? Translation::RuleCompiler.compile_id_expression(aggregate) : nil

data/lib/hecks/query_ir.rb

@@ -233,6 +233,25 @@ module Hecks
     # hand whether this is ALREADY a chapter-wide reference before
     # assuming it's fresh duplication," not as an automatic signal
     # either way.
+    #
+    # THE IDENTICAL GAP, ONE LEVEL DOWN: chapter-wide ENTITY-scoped
+    # sharing (`EntityBuilder#given`'s own bare form,
+    # `docs/implemented/resolution-rules/chapter-entity-given.md`) hits this same wall for
+    # the same structural reason — `SafeDepositBox.Visit` still shows
+    # as its own "(declared)" owner here even after becoming a bare
+    # reference to `Account.LedgerEntry`'s declaration, because a piece
+    # resolving a chapter-wide reference still write-throughs the
+    # resolved `Given` into its own `@named_givens` (so ITS OWN
+    # commands can read it back locally without a second hop). This is
+    # not a NEW limitation this feature introduces — it is the exact
+    # same IR-cannot-distinguish-declared-from-referenced fact, one
+    # scope wider. `bin/query_ir duplicates` confirms this directly:
+    # `Account.LedgerEntry (declared)` and `SafeDepositBox.Visit
+    # (declared)` both appear under the same `given: "customer is
+    # active"` group — verify by hand, same as the aggregate-level
+    # case above, before assuming a group naming two pieces under
+    # different aggregates is fresh duplication rather than an already-
+    # resolved chapter-wide reference.
     def declaration_count(rules)
       declared = rules.select { |r| r.location.end_with?(" (declared)") }
       declared_owners = declared.map { |r| owner_of(r.location) }.to_set

data/lib/hecks/query_specification/common/null_policy.rb

@@ -25,12 +25,24 @@ module Hecks
           end
         end
 
+        # M3 — an UNDECLARED (`native`) null policy used to render no
+        # `NULLS ...` clause at all here, leaving each dialect's own
+        # default to decide: Postgres puts nulls LAST on ASC (and FIRST
+        # on DESC), while `#order` above — this same "native" default,
+        # for Memory — puts nulls FIRST on ASC (and LAST on DESC), the
+        # SQLite convention. Same query, same data, different row order
+        # depending only on which adapter ran it. Rendered explicitly
+        # here instead, so an undeclared policy means the SAME total
+        # order everywhere rather than "whatever this store already does"
+        # — matching `#order`'s own default rather than the other way
+        # round, since that default is unconditional (Memory/Heki have no
+        # dialect to defer to) and SQLite already agrees with it natively.
         def sql_order(expression, direction, policy)
           direction = direction.to_s.downcase == "desc" ? "DESC" : "ASC"
           nulls = case policy&.mode.to_s
                   when "first" then " NULLS FIRST"
                   when "last" then " NULLS LAST"
-                  else ""
+                  else direction == "DESC" ? " NULLS LAST" : " NULLS FIRST"
                   end
           "#{expression} #{direction}#{nulls}, id #{direction}"
         end

data/lib/hecks/query_specification/field_path.rb

@@ -31,7 +31,11 @@ module Hecks
       # plain row hash); the rest read through whatever each step holds. A
       # stored nested value object is a plain hash by the time it is read
       # back, keyed by symbol in memory and by string off a wire decode,
-      # so both spellings are tried.
+      # so both spellings are tried — `key?` first, never `||`, because
+      # `||` falls through a genuinely-stored `false` to the OTHER
+      # spelling (usually absent) and returns `nil` instead. The seal
+      # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
+      # here is a real, held answer, not a missing one.
       def dig(holder, field)
         return nil if field.nil?
 
@@ -40,7 +44,21 @@ module Hecks
 
       def read(current, segment)
         return nil if current.nil?
-        return current[segment.to_sym] || current[segment] if current.is_a?(Hash)
+
+        if current.is_a?(Hash)
+          sym = segment.to_sym
+          return current.key?(sym) ? current[sym] : current[segment]
+        end
+
+        # M5 — "or nil, never raise" is this method's whole contract, and
+        # an Array broke it: `Array#[]` demands an Integer index, so
+        # `current[segment]` (a String) raised `TypeError` straight
+        # through `dig` instead of answering nil. A dotted path stepping
+        # INTO a list_of attribute (`where "tags.name" == "x"` against a
+        # bare list, rather than each element) has no single member a
+        # bare index would name anyway — nil is the honest answer, the
+        # same one a dangling reference or a missing key already gets.
+        return nil if current.is_a?(Array)
 
         current[segment]
       end

data/lib/hecks/query_specification/hop_path.rb

@@ -7,11 +7,13 @@ module Hecks
     # sibling, not its member. FieldPath walks a SHAPE, which cannot
     # loop, and answers nil, never raising, because there is nothing
     # left to say beyond "not found." HopPath walks the REFERENCE
-    # GRAPH instead, which the language does not guarantee acyclic —
-    # aggregates only refuse a DIRECT bidirectional pair
-    # (BluebookBuilder#validate_no_bidirectional_references! explicitly
-    # declines to take a position on a longer ring) — so a walk here
-    # needs to say WHY it stopped, not just that it did.
+    # GRAPH instead — `BluebookBuilder#validate_no_bidirectional_references!`
+    # refuses any reference CYCLE at declaration time (ADR 0025,
+    # "References" — widened from a direct pair to any ring, DFS over
+    # the chapter's own reference graph), so what's left to guard here
+    # is depth, not cycles: MAX_HOPS below, and this module's own
+    # `refusal` states for a target the chapter doesn't resolve. A walk
+    # here still needs to say WHY it stopped, not just that it did.
     #
     # Every method below takes an ATTRIBUTE ARRAY, never a "shape"
     # object — deliberately, because the two real callers hold their