hecks 1.0.2 → 1.2.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/provisioning.rb

@@ -2,6 +2,12 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
+        # Owner-only schema bootstrap: creates the lineage tables
+        # (`hecks_eras`, `hecks_era_texts`, `hecks_approvals`, the
+        # partitioned journal), sets up its RLS fence, bridges a renamed
+        # domain's history (`rename_domain!`), and attaches each era's
+        # journal partition (`ensure_partition!`) — the build-then-ATTACH
+        # dance that keeps a mint from stopping every writer.
         module Provisioning
           # Provisioning is the OWNER's job, and a deployment's app role is
           # deliberately not the owner — it may append and read, and it
@@ -13,6 +19,15 @@ module Hecks
           # grant_era! exists to constrain could never finish booting
           # ("must be owner of table hecks_eras"). A fence nothing can
           # reach is not a fence.
+          # One bootstrap sequence of DDL, order-dependent throughout —
+          # every guarded ALTER (RLS, REVOKE) is guarded and placed
+          # exactly where it is for measured, documented reasons (see the
+          # inline comments on each: catalog-lock avoidance, RLS timing,
+          # FORCE semantics). Splitting this into smaller methods would
+          # only hide that single ordered sequence behind several call
+          # sites, with nothing gained — each statement already reads as
+          # one step, and the length here is DDL, not branching logic.
+          # rubocop:disable-next Metrics/MethodLength
           def ensure_base!
             rename_domain! if @formerly_known_as
             return unless provisioner?
@@ -183,6 +198,16 @@ module Hecks
           # Anything else (no rows under either name) falls through
           # harmlessly — `formerly_known_as` pointing at a name with no
           # held history is not an error, just inert.
+          # One transactional migration, whose own comment above spells
+          # out a three-way precheck and a FIXED lock-acquisition order
+          # (old before new, eras before ordinal) chosen specifically to
+          # avoid a deadlock against a concurrent rename/mint/write.
+          # Splitting this would separate the precheck from the locking
+          # from the renames from the commit/rollback handling — each a
+          # piece of ONE transaction that must stay in this exact order
+          # or the deadlock-avoidance guarantee stops holding.
+          # rubocop:disable-next Metrics/AbcSize
+          # rubocop:disable-next Metrics/MethodLength
           def rename_domain!
             return unless @db.exec_params("SELECT to_regclass($1)", ["hecks_eras"])[0]["to_regclass"]
             return if @db.exec_params(
@@ -236,17 +261,30 @@ module Hecks
             # ensure_base! at all — only lazily, on first reattest! — so a
             # domain that never needed one must not be forced through an
             # UPDATE against a table that doesn't exist.
-            @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2", [@domain, @formerly_known_as]) if @db.exec_params("SELECT to_regclass($1)", ["hecks_attestations"])[0]["to_regclass"]
+            if @db.exec_params(
+              "SELECT to_regclass($1)", ["hecks_attestations"]
+            )[0]["to_regclass"]
+              @db.exec_params("UPDATE hecks_attestations SET domain = $1 WHERE domain = $2",
+                              [@domain, @formerly_known_as])
+            end
 
             @db.exec("COMMIT")
           rescue PG::LockNotAvailable
-            @db.exec("ROLLBACK") rescue nil
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
             raise Runtime::WiringError,
                   "cannot rename #{@formerly_known_as} to #{@domain}: another rename, mint, or write holds " \
                   "one of the domain locks — waited 10s; try again shortly"
-          rescue PG::Error => error
-            @db.exec("ROLLBACK") rescue nil
-            raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{error.message.strip}"
+          rescue PG::Error => e
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
+            raise Runtime::WiringError, "cannot rename #{@formerly_known_as} to #{@domain}: #{e.message.strip}"
           end
 
           # Nothing provisioned yet — build it. Provisioned and owned —

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/tail_merge.rb

@@ -4,6 +4,10 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
+        # The one deliberate, human-driven command that closes a fork:
+        # `merge_tail!` re-enters an old era's post-cut writes into the
+        # current era under named winners, and `diverged_count` observes how
+        # far the two worlds have drifted at any time before that.
         module TailMerge
           # ── fork observability ─────────────────────────────────────────
 
@@ -29,6 +33,14 @@ module Hecks
           # winner; resolution itself is append-only (the winner's state
           # re-enters as the newest row and wins structurally — originals
           # stay immutable).
+          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          # One Postgres transaction (BEGIN…COMMIT) with a manual ROLLBACK
+          # at every early refusal, and a snapshot-before-mutation
+          # invariant (`new_states` captured before the head rebuild lets
+          # the tail interleave). Splitting the steps into separate
+          # methods would force each to independently know how to roll
+          # back the same shared transaction, and would separate the
+          # snapshot from the mutation it must precede.
           def merge_tail!(aggregates:, edges:, winners: {}, audit: nil)
             @db.exec("BEGIN")
             @db.exec("SET LOCAL lock_timeout = '10s'")
@@ -129,14 +141,23 @@ module Hecks
             @db.exec("COMMIT")
             true
           rescue PG::LockNotAvailable
-            @db.exec("ROLLBACK") rescue nil
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
             raise Runtime::WiringError,
                   "cannot merge the tail of #{@domain}: another mint or merge holds the domain lock — " \
                   "waited 10s; try again shortly"
-          rescue PG::Error => error
-            @db.exec("ROLLBACK") rescue nil
-            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{error.message.strip}"
+          rescue PG::Error => e
+            begin
+              @db.exec("ROLLBACK")
+            rescue StandardError
+              nil
+            end
+            raise Runtime::WiringError, "cannot merge the tail of #{@domain}: #{e.message.strip}"
           end
+          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
           # Ids touched by BOTH worlds since the cut — the old world's
           # post-cut tail INTERSECTed with the new world's own writes.

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/transform_installer.rb

@@ -2,6 +2,12 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
+        # Installs the shared, domain-independent `hecks_tr_*` Postgres
+        # functions (extract/insert/rename/move/convert/drop over jsonb)
+        # that a compiled translation rule set's SQL calls into — the SQL
+        # compilation target kept equal to the Ruby reference transform by
+        # the cross-execution equivalence spec, never a second source of
+        # truth.
         module TransformInstaller
           # The jsonb rule transforms — installed once, idempotently. Kept
           # equal to the port's reference entry-JSON transform by the
@@ -27,7 +33,26 @@ module Hecks
             end
           end
 
+          # Six independent CREATE OR REPLACE FUNCTION statements — each
+          # self-contained SQL, no shared Ruby state, and (per this
+          # module's own header comment) safe in any install order since
+          # plpgsql bodies aren't resolved against each other until
+          # called, not at CREATE time. Split one-per-function below
+          # purely so each has its own name and (where relevant) its own
+          # comment to sit next to, not because the six have any
+          # sequencing dependency on one another.
           def install_transform_functions!
+            install_hecks_tr_extract!
+            install_hecks_tr_insert!
+            install_hecks_tr_rename!
+            install_hecks_tr_move!
+            install_hecks_tr_convert!
+            install_hecks_tr_drop!
+          end
+
+          private
+
+          def install_hecks_tr_extract!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_extract(state jsonb, path text[], OUT remaining jsonb, OUT value jsonb, OUT present boolean)
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -57,15 +82,18 @@ module Hecks
                 END IF;
               END $fn$
             SQL
-            # ADVERSARIAL FINDING: a destination whose top segment already
-            # holds a value — most commonly a reference, a bare scalar id
-            # — used to be silently overwritten with an empty object the
-            # moment a dotted destination needed to nest under it. That is
-            # a drop that never declared itself, the one thing this
-            # language exists to make explicit (see hecks_tr_convert's own
-            # refusal below, the same shape) — refused here instead, with
-            # the Ruby reference transform (ports/persistence/lineage.rb's
-            # `insert`) raising the identical wording.
+          end
+
+          # ADVERSARIAL FINDING: a destination whose top segment already
+          # holds a value — most commonly a reference, a bare scalar id
+          # — used to be silently overwritten with an empty object the
+          # moment a dotted destination needed to nest under it. That is
+          # a drop that never declared itself, the one thing this
+          # language exists to make explicit (see hecks_tr_convert's own
+          # refusal below, the same shape) — refused here instead, with
+          # the Ruby reference transform (ports/persistence/lineage.rb's
+          # `insert`) raising the identical wording.
+          def install_hecks_tr_insert!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_insert(state jsonb, path text[], value jsonb, rule_label text) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -83,6 +111,9 @@ module Hecks
                 RETURN jsonb_set(state, path, value);
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_rename!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_rename(state jsonb, old_name text, new_name text) RETURNS jsonb
               LANGUAGE sql IMMUTABLE AS $fn$
@@ -91,6 +122,9 @@ module Hecks
                   ELSE state END
               $fn$
             SQL
+          end
+
+          def install_hecks_tr_move!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_move(state jsonb, from_path text[], to_path text[], rule_label text) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -101,6 +135,9 @@ module Hecks
                 RETURN hecks_tr_insert(extracted.remaining, to_path, extracted.value, rule_label);
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_convert!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_convert(state jsonb, from_path text[], to_path text[], pairs jsonb, from_label text, rule_label text) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$
@@ -117,6 +154,9 @@ module Hecks
                   from_label, extracted.value, extracted.value;
               END $fn$
             SQL
+          end
+
+          def install_hecks_tr_drop!
             @db.exec(<<~SQL)
               CREATE OR REPLACE FUNCTION hecks_tr_drop(state jsonb, path text[]) RETURNS jsonb
               LANGUAGE plpgsql IMMUTABLE AS $fn$

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/coverage_check.rb

@@ -66,8 +66,8 @@ module Hecks
               declared = edge.for_aggregate(aggregate.name)
               after = begin
                 lineage.translated_latest(aggregate, ordinal, chain)
-              rescue PG::Error => error
-                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{error.message.strip}"
+              rescue PG::Error => e
+                raise Runtime::WiringError, "cannot mint era #{ordinal} of #{bluebook.name}: #{e.message.strip}"
               end
               before = if chain.size > 1
                          lineage.translated_latest(aggregate, ordinal, chain[0..-2])

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/era_resolver.rb

@@ -10,6 +10,15 @@ module Hecks
         # held-but-superseded shape boots read-only-toward-the-fence; an
         # unheld shape goes to the minter.
         module EraResolver
+          # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+          # A single order-dependent dispatch over a closed set of four
+          # boot scenarios (first boot / quiet reboot / held-but-superseded
+          # / unheld-shape-goes-to-minter), each already explained by its
+          # own comment above, all sharing one `db` connection closed in
+          # `ensure`. Splitting the branches into separate methods would
+          # turn each `return` (which exits `check!`, closing `db`) into a
+          # sentinel value threaded back up, obscuring the mutual
+          # exclusivity that IS the method's whole point.
           def check!(registry:, bluebook:, current_text:, settings:, directory: nil)
             db = PostgresEra.connect_for(bluebook.name, settings)
             lineage = Lineage.new(db, bluebook.name, formerly_known_as: bluebook.formerly_known_as)
@@ -78,6 +87,7 @@ module Hecks
           ensure
             db&.close
           end
+          # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         end
       end
     end

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage_manager/minter.rb

@@ -20,10 +20,29 @@ module Hecks
             label = hash[0, Runtime::StorageShape::LABEL_LENGTH]
             ordinal = latest[:ordinal] + 1
 
+            edge = resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
+            ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
+            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
+
+            chain = edge_chain(registry, bluebook, lineage.eras, label)
+            audit!(bluebook, lineage, chain, ordinal, edge)
+            lineage.mint_era!(
+              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
+              aggregates: bluebook.aggregates, edges: chain, role: role,
+              projection: Runtime::StorageShape.project(bluebook)
+            )
+            ordinal
+          end
+
+          # Find the one translation edge that leaves the held era, and
+          # validate it: exactly one edge must leave (eras fork
+          # mechanically — a second edge from the same source is a wiring
+          # mistake, not a merge to resolve automatically), and it must
+          # target the current shape's label (otherwise the edge is stale
+          # and boot must not silently mint past it).
+          def resolve_edge!(registry, bluebook, lineage, latest, label, ordinal, directory)
             edges = registry.translations.select { |t| t.domain == bluebook.name && t.from == latest[:label] }
-            if edges.empty?
-              refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory)
-            end
+            refuse_toward_the_scaffold!(registry, bluebook, lineage, latest, ordinal, directory) if edges.empty?
             if edges.size > 1
               raise Runtime::WiringError,
                     "cannot boot #{bluebook.name}: #{edges.size} translation edges leave era #{latest[:ordinal]} " \
@@ -36,43 +55,35 @@ module Hecks
                     "cannot boot #{bluebook.name}: the translation edge from #{latest[:label]} targets " \
                     "#{edge.to}, but the current shape is #{label} — the edge is stale; re-run bin/scaffold_translation"
             end
+            edge
+          end
 
-            # A compute's (and, the same way, a rekey's) only verification
-            # is the audit's human-approved sample — mint stays
-            # non-interactive by requiring the approval to already exist,
-            # recorded IN THIS DATABASE by `bin/translation_audit …
-            # --approve` and bound to what was actually reviewed: this
-            # edge's parsed content, and the journal as it stood when the
-            # samples were read. A journal that has advanced past the
-            # review invalidates it — the approved samples no longer cover
-            # the data.
-            if edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
-              approval = lineage.approval_for(from: edge.from, to: edge.to)
-              unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
-                raise Runtime::WiringError,
-                      "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
-                      "rule, and the audit's human-approved sample is its only verification — run " \
-                      "bin/translation_audit with --approve, then boot again"
-              end
-              tip = lineage.last_ordinal
-              if approval[:reviewed_ordinal] != tip
-                raise Runtime::WiringError,
-                      "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
-                      "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
-                      "human approved no longer cover the data; re-run bin/translation_audit with --approve"
-              end
-            end
+          # A compute's (and, the same way, a rekey's) only verification
+          # is the audit's human-approved sample — mint stays
+          # non-interactive by requiring the approval to already exist,
+          # recorded IN THIS DATABASE by `bin/translation_audit …
+          # --approve` and bound to what was actually reviewed: this
+          # edge's parsed content, and the journal as it stood when the
+          # samples were read. A journal that has advanced past the
+          # review invalidates it — the approved samples no longer cover
+          # the data.
+          def ensure_compute_rekey_approved!(bluebook, lineage, edge, ordinal)
+            return unless edge.aggregates.any? { |declared| !declared.computes.empty? || !declared.rekeys.empty? }
 
-            check_coverage!(registry, bluebook, shadow(latest[:held_text]), edge)
+            approval = lineage.approval_for(from: edge.from, to: edge.to)
+            unless approval && approval[:edge_digest] == Translation::Audit.edge_digest(edge)
+              raise Runtime::WiringError,
+                    "cannot mint era #{ordinal} of #{bluebook.name}: this edge carries a compute or rekey " \
+                    "rule, and the audit's human-approved sample is its only verification — run " \
+                    "bin/translation_audit with --approve, then boot again"
+            end
+            tip = lineage.last_ordinal
+            return unless approval[:reviewed_ordinal] != tip
 
-            chain = edge_chain(registry, bluebook, lineage.eras, label)
-            audit!(bluebook, lineage, chain, ordinal, edge)
-            lineage.mint_era!(
-              ordinal: ordinal, hash: hash, label: label, held_text: current_text,
-              aggregates: bluebook.aggregates, edges: chain, role: role,
-              projection: Runtime::StorageShape.project(bluebook)
-            )
-            ordinal
+            raise Runtime::WiringError,
+                  "cannot mint era #{ordinal} of #{bluebook.name}: the journal advanced past the approved " \
+                  "review (ordinal #{approval[:reviewed_ordinal]} reviewed, #{tip} now) — the samples a " \
+                  "human approved no longer cover the data; re-run bin/translation_audit with --approve"
           end
 
           # No edge yet: the boot refuses toward the authoring loop —
@@ -96,7 +107,7 @@ module Hecks
           # Diff the held era against the current shape and write the edge
           # file — confident rules inline, ambiguities as parse-refusing
           # `unresolved` lines. Returns the file path.
-          def scaffold!(registry, bluebook, lineage, latest, directory)
+          def scaffold!(_registry, bluebook, lineage, latest, directory)
             ensure_named!(lineage, latest)
             latest = lineage.eras.last
 

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

@@ -1,6 +1,8 @@
 require "json"
 
 require_relative "../../../../adapters/driven/sql_query_builder"
+require_relative "../../../../adapters/driven/postgres/outbox"
+require_relative "../../../../adapters/driven/postgres/reconnect"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
 require_relative "../../../../ports/persistence/append_only"
@@ -40,10 +42,20 @@ module Hecks
     #   operator compiles fully into SQL, or the query refuses loudly.
     class PostgresEra
       include SqlQueryBuilder
+      include Adapters::PostgresOutbox
+      include Adapters::PostgresReconnect
 
       attr_reader :aggregate
 
-      def persistence_capabilities = [:atomic_put]
+      # `:cross_process_lock` tells `Interpreting#run_dispatch_order_with_isolation`
+      # (runtime/interpreting.rb) this repository can hold a REAL
+      # cross-process lock for the whole dispatch order itself, via
+      # `with_write_lock` below — so it should use that instead of the
+      # in-process `AggregateLock` `Mutex` every other non-CAS repository
+      # falls back to. See ADR 0036: that in-process Mutex is invisible
+      # to `rust/host` dispatching against the same PostgresEra-bound
+      # tables from a separate OS process.
+      def persistence_capabilities = %i[atomic_put cross_process_lock]
 
       # The capability idiom: only PostgresEra answers true, and only
       # PostgresEra carries an era_check! for the boot gate to delegate to.
@@ -139,18 +151,42 @@ module Hecks
         # problems) still surface.
         connection.exec("SET client_min_messages = warning")
         connection
-      rescue PG::Error => error
+      rescue PG::Error => e
         raise Runtime::WiringError,
-              "cannot bind PostgresEra at #{declared} for #{name}: #{error.message.strip}"
+              "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
       end
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
+        @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
         # The domain names the journal (one journal per lineage). The
-        # factory injects it; a directly-instantiated adapter (specs,
-        # consoles) journals under the aggregate's own name.
-        @domain = self.class.setting(settings, :domain, default: aggregate.storage_name).to_s
+        # factory injects it as the owning bluebook's own declared name
+        # (`RepositoryFactory.build`'s own `domain` positional arg —
+        # `bluebook.name`, confirmed at `outbox.rb`'s own call site —
+        # never this default in real dispatch). This default exists only
+        # for a directly-instantiated adapter (specs, consoles) that
+        # skips the factory.
+        #
+        # When the aggregate DOES have an owning chapter (`hecks_owner`
+        # set — true for any aggregate sealed through a real bluebook,
+        # even if this adapter itself was built by hand), default to the
+        # chapter's own declared PascalCase name. That's the same string
+        # `rust/host`'s `pg_advisory_xact_lock` key derives from
+        # (`HECKS_DOMAIN`, deploy-time-set to `world.domain`) — the
+        # aggregate's own snake_case `storage_name` silently disagreed
+        # with it (`hashtext` is byte-sensitive: `"chess"` and `"Chess"`
+        # never collide), which is ADR 0036 Blocker 1.
+        #
+        # When there's no owning chapter at all (a bare
+        # `AggregateBuilder` fixture built outside any real bluebook —
+        # `hecks_owner` is only ever stamped by chapter construction, see
+        # `traits.rb`'s `hecks_owner = self`) there is no chapter name to
+        # match Rust against in the first place, so fall back to the
+        # aggregate's own name, same as before this ADR.
+        @domain = self.class.setting(
+          settings, :domain, default: aggregate.hecks_owner&.name || aggregate.storage_name
+        ).to_s
         @lineage = Lineage.new(@db, @domain)
         @lineage.ensure_base!
         # The era gate resolves which era this boot IS (an old checkout
@@ -192,6 +228,7 @@ module Hecks
         @field_caches = ensure_field_caches!
         create_event_table!
         create_saga_table!
+        create_outbox_table!
       end
 
       def table = @aggregate.storage_name
@@ -216,7 +253,10 @@ module Hecks
         return @db.exec(%(SELECT id, state FROM #{quoted_head} ORDER BY id)).map { |row| instance(row) } unless order_by
 
         name = order_by.to_s.split(".").first
-        raise Runtime::WiringError, "#{@aggregate.name} has no attribute #{order_by.inspect} to order by" unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+        unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          raise Runtime::WiringError,
+                "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
+        end
 
         spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
         @db.exec(%(SELECT id, state FROM #{quoted_head} ORDER BY #{order_clause(spec, nil)})).map { |row| instance(row) }
@@ -268,6 +308,18 @@ module Hecks
         head_phase(declared, uncached, ids, args)
       end
 
+      # ADR 0036's actual fix — see `persistence_capabilities` above.
+      # Wraps the WHOLE dispatch order (hydrate through save), not just
+      # `append`'s own transaction below: `lock_writes!` has to be held
+      # before hydrate even starts, or two cross-process writers can
+      # both hydrate unlocked and race for the write, each blind to the
+      # other. `transaction` (via `include Adapters::PostgresOutbox`) is
+      # already re-entrant — `append`/`atomic_put`'s own inner
+      # `transaction do ... end`, deep inside the block below, joins
+      # this SAME transaction instead of opening/committing its own, so
+      # the advisory lock stays held until this whole block returns.
+      def with_write_lock(&block) = transaction { lock_writes!; block.call } # rubocop:disable Style/Semicolon
+
       # HELD FOR THE WHOLE TRANSACTION, not just around the INSERT — the
       # ordinal is assigned by the column's own `nextval()` default, inside
       # this same statement, so the lock has to already be held before that
@@ -284,9 +336,12 @@ module Hecks
       # still runs, cheaply, during AppendOnly#recover!'s full replay on
       # every boot (see `project` below), and a second write there would
       # make that replay pay real DB cost for a snapshot that's already
-      # correct.
+      # correct. When `with_write_lock` above already drove this whole
+      # dispatch, `lock_writes!` here is a harmless re-acquire of the
+      # same already-held (per-session-reentrant) advisory lock; a bare
+      # `repository.save` outside a full dispatch still takes it fresh.
       def append(entry)
-        @db.transaction do
+        transaction do
           lock_writes!
           append_and_project!(entry)
         end
@@ -299,7 +354,7 @@ module Hecks
       # occurs before entering this adapter-native operation.
       def atomic_put(entry, insert_only: false)
         status = nil
-        @db.transaction do
+        transaction do
           lock_writes!
           exists = !@db.exec_params(
             "SELECT 1 FROM #{quoted_head} WHERE id = $1 LIMIT 1",
@@ -418,7 +473,8 @@ module Hecks
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
           "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
           "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory),
+           JSON.generate(completed_compensations)]
         )
       end
 
@@ -433,7 +489,8 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.exec_params(
-          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = $1",
+          "SELECT process_manager, correlation, state, memory, completed_compensations " \
+          "FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
@@ -624,11 +681,12 @@ module Hecks
       end
 
       def cached_where_fields
-        declared_queries.flat_map { |q|
-          q.wheres.map { |clause|
+        fields = declared_queries.flat_map do |q|
+          q.wheres.map do |clause|
             clause.field.to_s
-          }
-        }.uniq.select { |field| cacheable_field?(field) }
+          end
+        end
+        fields.uniq.select { |field| cacheable_field?(field) }
       end
 
       def declared_queries
@@ -709,7 +767,7 @@ module Hecks
           clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
         end
 
-        sql = +"SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(' AND ')}"
+        sql = "SELECT #{select_list} FROM #{from_relation} WHERE #{clauses.join(' AND ')}"
         sql << if declared.order_by
                  " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
                else
@@ -751,7 +809,8 @@ module Hecks
         # this same domain already created before this column existed —
         # the same idiom `rust/host/src/journal.rs`'s own
         # `sagas_backfilled` column addition already uses.
-        @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb NOT NULL DEFAULT '[]'::jsonb")
+        @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
+                 "NOT NULL DEFAULT '[]'::jsonb")
       end
     end
   end

data/lib/hecks/ports/persistence/plugins/era/translation/audit/layer_one.rb

@@ -15,29 +15,27 @@ module Hecks
       module LayerOne
         def layer_one!(violations, aggregate, after)
           after.each do |id, state|
-            begin
-              symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
-              instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
-              lifecycle = aggregate.lifecycle
-              next unless lifecycle
+            symbolized = JSON.parse(JSON.generate(state), symbolize_names: true)
+            instance = Runtime::Instance.new(aggregate: aggregate, id: id, state: symbolized)
+            lifecycle = aggregate.lifecycle
+            next unless lifecycle
 
-              held = instance[lifecycle.field]
-              # `Lifecycle#states` answers default+targets only — a state
-              # legitimately declared just as a `from:` (a terminal
-              # transition's source, never anyone's target) is real and
-              # reachable but invisible to it. `ModelCheck.full_states`
-              # is the full declared set (default, every target, AND
-              # every from) that `fuzzing/properties.rb`'s own replay
-              # check already uses for this identical question — see its
-              # comment on this same hole.
-              allowed = Bluebook::ModelCheck.full_states(lifecycle)
-              unless held.nil? || allowed.include?(held.to_s)
-                violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
-                              "a state this era's lifecycle never reaches"
-              end
-            rescue Runtime::InvariantViolation, Runtime::TypeMismatch => error
-              violations << "#{aggregate.name}##{id}: #{error.message}"
+            held = instance[lifecycle.field]
+            # `Lifecycle#states` answers default+targets only — a state
+            # legitimately declared just as a `from:` (a terminal
+            # transition's source, never anyone's target) is real and
+            # reachable but invisible to it. `ModelCheck.full_states`
+            # is the full declared set (default, every target, AND
+            # every from) that `fuzzing/properties.rb`'s own replay
+            # check already uses for this identical question — see its
+            # comment on this same hole.
+            allowed = Bluebook::ModelCheck.full_states(lifecycle)
+            unless held.nil? || allowed.include?(held.to_s)
+              violations << "#{aggregate.name}##{id}: #{lifecycle.field} is #{held.inspect}, " \
+                            "a state this era's lifecycle never reaches"
             end
+          rescue Runtime::InvariantViolation, Runtime::TypeMismatch => e
+            violations << "#{aggregate.name}##{id}: #{e.message}"
           end
         end
       end