hecks 0.3.0 → 1.0.1

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

data/lib/hecks/runtime/aggregate_lock.rb

@@ -0,0 +1,45 @@
+module Hecks
+  module Runtime
+    # A PROCESS-WIDE, STRIPED MUTEX REGISTRY — the concurrency-control
+    # mechanism for every adapter that does NOT declare
+    # `:optimistic_concurrency` (Heki, Memory today; see
+    # `CommandInterpreter#call`/`EntityInterpreter#call`, which choose
+    # between this and Postgres's CAS+retry purely off
+    # `repository.capabilities`).
+    #
+    # WHY A LOCK SUFFICES HERE AND CAS IS NOT NEEDED: both adapters hold
+    # process-local data. `Adapters::Memory.tenant_capable?`'s own comment
+    # states the confirmed fact this relies on — two `Runtime.boot` calls
+    # get two entirely separate adapter instances; there is never a SECOND
+    # PROCESS writing the same Heki file or the same Memory Hash, only
+    # possibly other THREADS within this one process. A `Mutex` held for
+    # the full hydrate-through-save critical section closes the identical
+    # lost-update gap CAS closes for Postgres, with no schema, no version
+    # column, and no retry loop — the second thread simply doesn't start
+    # its own hydrate until the first thread's save has landed.
+    #
+    # STRIPED, NOT ONE GLOBAL LOCK: keyed by `[domain, aggregate.hecks_name,
+    # id]`, so two dispatches against two DIFFERENT records never block
+    # each other. The registry Hash itself is guarded by its own top-level
+    # Mutex only for the moment a new per-key Mutex is created — two
+    # threads locking DIFFERENT keys for the first time never wait on one
+    # another beyond that brief creation window.
+    module AggregateLock
+      @registry_lock = Mutex.new
+      @locks = {}
+
+      class << self
+        # `AggregateLock.for(domain, aggregate, id).synchronize { ... }`
+        # `id: nil` — identity could not be resolved yet (see
+        # `Identity.best_effort`) — locks by aggregate TYPE alone, coarser
+        # (every record of this aggregate serializes against every other)
+        # but still correct: it can only ever make dispatch MORE
+        # conservative than a resolved id would.
+        def for(domain, aggregate, id = nil)
+          key = id.nil? ? [domain.to_s, aggregate.hecks_name] : [domain.to_s, aggregate.hecks_name, id.to_s]
+          @registry_lock.synchronize { @locks[key] ||= Mutex.new }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/boot_gates.rb

@@ -0,0 +1,41 @@
+module Hecks
+  module Runtime
+    # A boot's own small set of phase-tagged, conditionally-present gates —
+    # ADR 0031. Registration is instance-scoped, ONE PER `Loader.boot`
+    # CALL, never a module-level singleton: a process that boots more than
+    # one registry in its lifetime (every spec suite does) must never let
+    # one boot's capability profile leak into the next boot's gate list.
+    #
+    # A gate is anything `.call(registry, directory)`-able — an existing
+    # module method handed over as a `Method` object (`EraCheck.method
+    # (:check_lineage!)`) needs no wrapper; a bare block does. Phases run
+    # in the order `run!` is called, gates within a phase in registration
+    # order — today exactly one gate per phase, so ordering among
+    # same-phase gates has never been exercised.
+    #
+    # This is deliberately NOT the same registry `Hecks::Projector` uses
+    # (ADR 0027) — that one is a process-wide, static IR-in/artifact-out
+    # registry with no bindings and no live-state mutation; this one is
+    # per-boot and gates real I/O (a Postgres mint, a saga-store read).
+    # Sharing a primitive between them is deferred until a third consumer
+    # actually wants it (0031's own Rejected Alternatives).
+    class BootGates
+      def initialize
+        @gates = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def register(name, gate, phase:)
+        @gates[phase] << [name, gate]
+        self
+      end
+
+      def registered?(name)
+        @gates.values.flatten(1).any? { |registered_name, _gate| registered_name == name }
+      end
+
+      def run!(phase, registry, directory)
+        @gates[phase].each { |pair| pair.last.call(registry, directory) }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/caller.rb

@@ -19,15 +19,31 @@ module Hecks
       # `CommandRules::Authorization` check a real Governance
       # `RoleAssignment` instead, once the command's domain has Governance
       # attached — see that module's own header for the full split.
-      Current = Struct.new(:role, :actor_id, keyword_init: true)
+      #
+      # `as_of` and `scope` are BOTH optional too, and both self-asserted
+      # by the caller rather than derived from the command — deliberately:
+      # `as_of` is filled at the door from `Ports::Clock.now`, never
+      # inside the interpreter (see `Ports::Clock`'s own header), so
+      # there is no other place to source it from. `scope` stays here
+      # rather than becoming a command-level DSL construct on purpose —
+      # a scope check that lived in the bluebook would put an
+      # authorization concern inside the domain declaration itself; this
+      # keeps it an application-boundary fact instead, the same shape
+      # `role`/`actor_id` already are. The tradeoff: a caller states what
+      # scope it is acting in, and `holds_role?` verifies a live grant
+      # exists for THAT scope — it does not independently confirm the
+      # scope matches whatever the command's own target data belongs to.
+      Current = Struct.new(:role, :actor_id, :as_of, :scope, keyword_init: true)
 
       module_function
 
       def current = Thread.current[:hecks_caller]
 
-      def as(role:, actor_id: nil)
+      def as(role:, actor_id: nil, as_of: nil, scope: nil)
         previous = Thread.current[:hecks_caller]
-        Thread.current[:hecks_caller] = Current.new(role: role.to_s, actor_id: actor_id&.to_s)
+        Thread.current[:hecks_caller] = Current.new(
+          role: role.to_s, actor_id: actor_id&.to_s, as_of: as_of, scope: scope&.to_s
+        )
         yield
       ensure
         Thread.current[:hecks_caller] = previous

data/lib/hecks/runtime/command_interpreter/argument_gate.rb

@@ -19,8 +19,19 @@ module Hecks
         # the aggregate rather than describe it : `id`, whatever the aggregate is
         # identified by, and the reference key of the root a command reaches
         # through. Refusing those would refuse every dispatch there is.
-        def refuse_unknown_arguments(domain, aggregate, command, args)
-          addressing = [:id, *aggregate.identity_heads, reference_key(command)] + correlation_keys(domain)
+        #
+        # `extra_identity_heads:` — EntityInterpreter's own callers only. An
+        # entity dispatch addresses not just the root aggregate but every
+        # entity ALONG THE CHAIN it walks to reach the piece the command
+        # actually belongs to (`Handler.Dispatch.Bind` is two hops), and each
+        # hop's own `identity_heads` is addressing the same way the root's
+        # are — `element_of` (entity_element.rb) reads them straight out of
+        # `args` to find the element, never as a fact the command itself
+        # declares. `[]` for a plain aggregate/port-operation dispatch, which
+        # has no chain to add.
+        def refuse_unknown_arguments(domain, aggregate, command, args, extra_identity_heads: [])
+          addressing = [:id, *aggregate.identity_heads, *extra_identity_heads, reference_key(command)] +
+                       correlation_keys(domain)
           known      = (command.attributes.map(&:name) + addressing).compact.map(&:to_sym)
           # SORTED. Payload order is whatever the caller happened to write, and
           # refusal wording is contract — pinned byte-for-byte by the corpus, so

data/lib/hecks/runtime/command_interpreter/mutation_applier.rb

@@ -71,6 +71,18 @@ module Hecks
           # never through this method.
           when :delegate
             nil
+          # `corrects` — CommandBuilder#corrects_impl's own comment gives
+          # the full reasoning for storing it as a mutation at all. A REAL
+          # no-op here too: it targets no field on THIS instance either —
+          # its own event name, and whether THIS record has actually
+          # emitted it, is checked once, up front, by
+          # CommandRules::Admissibility#enforce_correction_target, not
+          # here. Whatever field this correction actually changes is an
+          # ORDINARY declared (or, for `reverses: true`, derived — see
+          # AggregateBuilder#seal_correction_targets) mutation of its own,
+          # applied by one of the branches above like any other.
+          when :corrects
+            nil
           else
             # Every declared op has a `when` above — this is not a real
             # runtime path today, only a backstop against the day one