hecks 2.8.0 → 3.0.0

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

@@ -3,8 +3,10 @@ require "json"
 require_relative "../../../../adapters/driven/sql_query_builder"
 require_relative "../../../../adapters/driven/postgres/outbox"
 require_relative "../../../../adapters/driven/postgres/reconnect"
+require_relative "../../../../adapters/driven/postgres/shared_connection"
 require_relative "postgres_era/lineage"
 require_relative "postgres_era/lineage_manager"
+require_relative "postgres_era/events"
 require_relative "../../../../ports/persistence/append_only"
 require_relative "../../../../query_specification/common/order_by"
 require_relative "../../../../runtime/errors"
@@ -14,100 +16,45 @@ require_relative "../../../../runtime/registry"
 
 module Hecks
   module Adapters
-    # The enforcement-grade persistence adapter — and the only one that
-    # declares the lineage capability: it may act on shape drift
-    # (translate, fork, merge) where every other adapter can only refuse
-    # toward it. Sibling to the plain `Postgres` adapter (postgres.rb),
-    # which is the same database with none of this machinery — pick
-    # PostgresEra only once a domain actually needs to survive a shape
-    # change live. See docs/implemented/postgres-era-adapter-split-plan.md for why
-    # the two are split and what each one carries.
-    #
-    # ## Storage model
-    #
-    # See postgres_era/lineage.rb for the DDL.
-    #
-    # - One journal per domain, list-partitioned by era, one ordinal
-    #   sequence spanning partitions. Appends go there; nothing updates
-    #   or deletes a journal row (immutability by privilege — UPDATE and
-    #   DELETE revoked; a deployment's app role connects as a non-owner).
-    # - Per aggregate, the head is derived: era 1 reads a plain view
-    #   (latest save per id); later eras read a view overlaying the
-    #   materialized, translated ancestor tail with live current-era
-    #   rows. `project` is therefore a no-op — old entries are never
-    #   rewritten, and the head is never a table anything writes.
-    # - State is one jsonb column. jsonb normalizes key order (and drops
-    #   duplicate keys), so anything comparing stored state — the corpus
-    #   history gate above all — must compare canonicalized state, never
-    #   raw bytes; `bin/canonicalise` deep-sorts keys, which is exactly
-    #   why the gate survives this normalization.
-    # - Query pushdown is the shared SqlQueryBuilder: every declared
-    #   operator compiles fully into SQL, or the query refuses loudly.
+    # Postgres adapter that journals each write per domain and derives every head by era; the
+    # only one that can translate, fork or merge on shape drift. Compare jsonb state canonicalized.
     class PostgresEra
       include SqlQueryBuilder
       include Adapters::PostgresOutbox
       include Adapters::PostgresReconnect
+      include Events
 
       attr_reader :aggregate
 
       # Names the optional persistence capabilities this adapter implements natively.
       #
-      # `: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.
+      # `:cross_process_lock` lets dispatch hold `with_write_lock` instead of the in-process
+      # mutex, which `rust/host` in another OS process cannot see (ADR 0036). `:atomic_append`
+      # tells `RepositoryFactory.build` that `append` (below) already commits the snapshot in
+      # the same transaction as the journal row, so replaying the journal through `project` on
+      # boot has nothing left to fix up.
       #
-      # @return [Array<Symbol>] always `[:atomic_put, :cross_process_lock]`
-      def persistence_capabilities = %i[atomic_put cross_process_lock]
+      # @return [Array<Symbol>] always `[:atomic_put, :cross_process_lock, :atomic_append]`
+      def persistence_capabilities = %i[atomic_put cross_process_lock atomic_append]
 
       # Declares that this adapter can act on shape drift rather than only refuse.
       #
-      # The capability idiom: only PostgresEra answers true, and only
-      # PostgresEra carries an era_check! for the boot gate to delegate to.
-      #
       # @return [Boolean] always true
       def self.lineage_capable? = true
 
-      # Declares that two tenant boots of this adapter keep their tables apart.
-      #
-      # **Tenant-capable** — see Runtime::TenantCheck's own header for the
-      # full reasoning. `connect_for`'s own `schema:` setting (the
-      # Storehouse shared-instance mechanism, already built, already
-      # proven for eras) is what keeps two tenant boots' tables apart:
-      # each boot's own `SET search_path` means every unqualified
-      # reference this adapter and its lineage classes construct
-      # resolves into that boot's own schema, never another tenant's —
-      # proven for real, not assumed, by tenant_isolation_spec.rb, the
-      # same discipline lineage_capable? already holds itself to.
+      # Declares that two tenant boots on separate `schema:` settings keep their tables apart.
       #
       # @return [Boolean] always true
       def self.tenant_capable? = true
 
-      # Resolves which era this boot is, minting the next one when the shape has drifted
-      # and a covering translation edge exists. The boot gate's entry point; the work is
-      # `LineageManager.check!` (see `LineageManager::EraResolver`).
+      # Resolves this boot's era, minting the next one when the shape drifted and a translation
+      # edge covers it. Delegates to `LineageManager.check!`.
       #
-      # @param registry [Runtime::Registry] the booting registry; receives the resolved
-      #   ordinal in `resolved_eras` and, for a superseded boot, `superseded_eras`
-      # @param bluebook [Bluebook::Chapter] the domain being booted
-      # @param current_text [String] the domain's bluebook source as it stands on disk
-      # @param settings [Hash{Symbol, String => Object}] the world's persistence settings
-      #   for this binding; `database` is required, `schema`, `role` and
-      #   `allow_superuser` are honored
-      # @param directory [String, nil] the domain's bluebook directory, where
-      #   `HECKS_SCAFFOLD=1` writes a translation edge; nil disables scaffolding
-      # @return [Integer, nil] the ordinal of the era this boot minted, or nil when it
-      #   minted nothing (first boot, quiet reboot, or a held-but-superseded shape)
-      # @raise [Runtime::WiringError] if the database cannot be reached, the connection
-      #   is a superuser without `allow_superuser`, a held text fails its integrity
-      #   check, or the shape drifted and the mint refuses (no edge, a stale or forked
-      #   edge, an unapproved compute or rekey, uncovered drift, or a failed audit)
-      # @raise [Bluebook::DSL::Malformed] if a held era's text parses under neither the
-      #   current nor the legacy grammar
+      # @param settings [Hash{Symbol, String => Object}] persistence settings; needs `database`
+      # @param directory [String, nil] where `HECKS_SCAFFOLD=1` writes a translation edge
+      # @return [Integer, nil] the ordinal of the era this boot minted, or nil when none
+      # @raise [Runtime::WiringError] if the database is unreachable or the mint refuses
+      # @raise [Bluebook::DSL::Malformed] if a held era's text parses under no grammar
       def self.era_check!(registry:, bluebook:, current_text:, settings:, directory: nil)
         LineageManager.check!(
           registry: registry, bluebook: bluebook, current_text: current_text,
@@ -115,23 +62,11 @@ module Hecks
         )
       end
 
-      # Reads one setting from a world's settings hash under either key spelling.
+      # Reads one setting under either its Symbol or String spelling.
       #
-      # Both spellings of a setting are honored — a world's settings hash
-      # may arrive symbol-keyed (built straight in Ruby) or string-keyed
-      # (round-tripped through JSON), and a domain that names one is not
-      # obligated to also skip the other. `key?` decides which spelling
-      # actually exists, never `||` — `||` cannot tell a genuinely stored
-      # `false` apart from an absent key, and would silently prefer the
-      # other spelling (or `default`) instead of returning the real, held
-      # answer. See Hecks::QuerySpecification::FieldPath#read for the same
-      # discipline applied to stored state instead of settings.
+      # Uses `key?` rather than `||` so a stored `false` is not mistaken for an absent key.
       #
-      # @param settings [Hash{Symbol, String => Object}] the settings hash to read
-      # @param key [Symbol, String] the setting name; tried as given, then as a String
-      # @param default [Object, nil] what to return when neither spelling is a key
-      # @return [Object, nil] the stored value, including a stored `false` or `nil`, or
-      #   `default` when the key is absent under both spellings
+      # @return [Object, nil] the stored value, or `default` when neither spelling is present
       def self.setting(settings, key, default: nil)
         return settings[key] if settings.key?(key)
 
@@ -141,20 +76,15 @@ module Hecks
         default
       end
 
-      # Opens a connection to the database a world declares, creating and selecting the
-      # declared `schema` and silencing sub-warning notices. The caller owns the
-      # connection and closes it.
+      # Opens a connection to the declared database, selecting the declared `schema` if any.
+      # The caller owns the connection and closes it.
       #
       # @param name [String] the domain or aggregate name, used only in refusal messages
-      # @param settings [Hash{Symbol, String => Object}] the world's settings; `database`
-      #   is a database name or a `postgres://`/`postgresql://` URL, `schema` is optional
-      # @return [PG::Connection] an open connection with `search_path` set when a schema
-      #   is declared
-      # @raise [Runtime::WiringError] if the settings declare no `database`, or Postgres
-      #   refuses the connection, the `CREATE SCHEMA` or either `SET`
+      # @param settings [Hash{Symbol, String => Object}] `database` is a name or `postgres://` URL
+      # @return [PG::Connection] an open connection
+      # @raise [Runtime::WiringError] if `database` is missing or Postgres refuses a statement
       def self.connect_for(name, settings)
-        # **Lazy, on purpose** — same reasoning as Sqlite's own initialize:
-        # a domain that never wires PostgresEra should never need the gem.
+        # Lazy so a domain that never wires PostgresEra does not need the pg gem.
         require "pg"
 
         declared = setting(settings, :database)
@@ -171,39 +101,17 @@ module Hecks
             PG.connect(dbname: declared)
           end
 
-        # **Shared-instance isolation**. A domain that declares `schema` is
-        # sharing its Postgres instance with other domains (the
-        # storehouse) — every unqualified table/view/function reference
-        # this adapter and its lineage classes ever construct resolves
-        # through search_path, so this one SET is what makes ALTER
-        # TABLE ... SET SCHEMA migrations transparent to the rest of the
-        # adapter. A domain with no `schema` setting keeps Postgres's
-        # own default search_path (public).
+        # A declared `schema` means the instance is shared; search_path makes every unqualified
+        # name this adapter and its lineage classes build resolve inside that schema.
         schema = setting(settings, :schema)
         if schema.to_s != ""
-          # **The schema itself, idempotently** — without this, a domain
-          # naming a `schema:` nobody has created yet fails on its first
-          # table-creation attempt with Postgres's own "no schema has been
-          # selected to create in", found live provisioning tenant_
-          # isolation_spec.rb's own multi-schema fixture by hand.
-          # `CREATE SCHEMA IF NOT EXISTS` is exactly the
-          # same self-healing idempotency this adapter's own table/era
-          # provisioning already holds itself to (see the comment right
-          # below on `client_min_messages`) — a schema that already
-          # exists is the ordinary case for every boot after the first,
-          # not news.
+          # Idempotent: the schema may not exist yet on the first boot.
           connection.exec("CREATE SCHEMA IF NOT EXISTS #{connection.quote_ident(schema)}")
           connection.exec("SET search_path TO #{connection.quote_ident(schema)}")
         end
 
-        # **Quiet on purpose**. Provisioning re-runs its own idempotent
-        # `CREATE ... IF NOT EXISTS` checks on every boot — a schema that
-        # already exists is the ordinary case, not news, and Postgres
-        # surfaces every one as a notice by default. `bin/set-password`
-        # boots a real registry just to mint an Identity, and nobody
-        # setting a password needs to see a page of "relation ...
-        # already exists, skipping" to do it. Warning and above (real
-        # problems) still surface.
+        # Provisioning re-runs CREATE ... IF NOT EXISTS on every boot; silence the notices.
+        # Warnings and above still surface.
         connection.exec("SET client_min_messages = warning")
         connection
       rescue PG::Error => e
@@ -211,118 +119,53 @@ module Hecks
               "cannot bind PostgresEra at #{declared} for #{name}: #{e.message.strip}"
       end
 
-      # Connects, provisions the domain's journal, this aggregate's head and field
-      # caches, and the event, saga and outbox tables. Every step is idempotent.
+      # Joins the process's shared connection for the declared database and schema, so every
+      # aggregate of a domain runs on one connection, then provisions the journal, this
+      # aggregate's head and field caches, and the event, saga and outbox tables. Every step is
+      # idempotent.
       #
-      # @param aggregate [Bluebook::Aggregate] the aggregate this repository persists
-      # @param settings [Hash{Symbol, String => Object}] the world's settings plus what
-      #   `RepositoryFactory.build` merges in: `domain` (journal name), `era` (the
-      #   resolved ordinal, nil to self-resolve to the newest) and `superseded_by` (the
-      #   ordinal that superseded this boot's era, nil for a current-era boot)
-      # @param root [String, nil] the registry root every adapter is offered; unused here
-      # @raise [Runtime::WiringError] if the settings declare no `database`, the
-      #   connection is refused, or a held era text fails its integrity check
+      # @param settings [Hash{Symbol, String => Object}] world settings plus what
+      #   `RepositoryFactory.build` merges in: `domain`, `era` and `superseded_by`
+      # @raise [Runtime::WiringError] if `database` is missing or the connection is refused
       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 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.
+        @db = PostgresSharedConnection.for(aggregate.name, settings, connector: self.class)
+        # Journal name: the owning bluebook's declared name, matching the key rust/host derives its
+        # advisory lock from (ADR 0036). A bare aggregate with no owner falls back to its own name.
         @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
-        # boots a held-but-superseded era and keeps writing its own
-        # partition); a directly-instantiated adapter defaults to the
-        # newest.
-        #
-        # Not `self.class.setting(...)` here — RepositoryFactory#build
-        # always merges `era: registry.resolved_eras[domain]` into
-        # settings, so the key is genuinely present (not absent) for
-        # any domain the era boot gate hasn't resolved yet (or that
-        # doesn't have one at all), just holding `nil`. `setting`'s own
-        # presence-over-truthiness discipline (correct for a field like
-        # `:role`, where a stored `false` is a real, distinct answer
-        # from "unset") does the wrong thing for `:era` specifically:
-        # `nil` can never be a meaningful era override — only a real
-        # ordinal or "not resolved, self-resolve" ever apply — so
-        # coalescing here, not `setting`'s presence check, is what
-        # actually honors this comment's own "defaults to the newest"
-        # promise.
+        # Coalesce instead of `setting`: the factory always passes `era:`, nil until the boot gate
+        # resolves it, and nil can never be a real override.
         @era = settings.key?(:era) ? settings[:era] : settings["era"]
         @era ||= @lineage.current_era
-        # The in-process half of the era fence. `EraResolver.check!` sets
-        # `registry.superseded_eras[domain]` for a held-but-superseded
-        # boot only, and `RepositoryFactory.build` merges it in here as
-        # `superseded_by:` — so this is nil for every current-era boot and
-        # for a directly-instantiated adapter (specs, consoles), which,
-        # like `era:` above, self-resolves rather than being told. When
-        # set, `append`/`atomic_put` refuse before issuing an INSERT (see
-        # `refuse_superseded_write!`): the RLS fence already refuses the
-        # same write for an ordinary role, but a superuser walks through
-        # RLS (BUG#24), and this checkout's own knowledge that it is stale
-        # is the one guard no role attribute can void. Same coalescing as
-        # `era:` — the key is always present from the factory, holding nil
-        # for the ordinary case.
+        # Non-nil only for a held-but-superseded boot. `append` and `atomic_put` refuse on it
+        # because a superuser walks through the RLS fence.
         @superseded_by = settings.key?(:superseded_by) ? settings[:superseded_by] : settings["superseded_by"]
-        # Unconditional and idempotent, regardless of era — belt-and-
-        # suspenders self-healing (compile_head! already ensures this for
-        # a freshly-minted era's own name; ensure_first_head! for era 1's)
-        # against any boot-ordering surprise, at the cost of one
-        # CREATE TABLE IF NOT EXISTS nobody pays for twice.
+        # Idempotent self-healing against any boot-ordering surprise.
         @lineage.ensure_head_snapshot!(table, @era)
         @lineage.ensure_first_head!(table) if @era == 1
-        # The read-cache side of the era workaround (Track C,
-        # docs/implemented/postgres-era-adapter-split-plan.md §3) — one row-cache
-        # table per `where`-field this aggregate's own declared queries
-        # (and its entities' own) actually use, derived automatically
-        # (principle 3 — no bluebook keyword), self-healing and
-        # idempotent like everything else booted here. `@field_caches`
-        # maps field -> cache-table name; `query` below consults it to
-        # decide whether a declared query can skip the DISTINCT ON
-        # reduction entirely.
+        # One row-cache table per where-field the aggregate's queries use; `query` consults it
+        # to skip the head reduction.
         @field_caches = ensure_field_caches!
         create_event_table!
         create_saga_table!
         create_outbox_table!
       end
 
-      # Names this aggregate in storage: the journal's `aggregate` column value and the
-      # stem of its head view, head snapshot and field-cache names.
+      # Names this aggregate in storage: the journal's `aggregate` value and the stem of its
+      # head view, head snapshot and field-cache names.
       #
       # @return [String] the aggregate's snake_case storage name
       def table = @aggregate.storage_name
 
-      # Reads one record's current state through the lineage-aware head view, so a record
-      # written under an ancestor era comes back translated to the current shape.
+      # Reads one record's current state through the head view, translated to the current shape.
       #
       # @param id [String, Object] the record's identity, compared as `id.to_s`
-      # @return [Runtime::Instance, nil] the stored record, or nil when the head holds no
-      #   saved row for that id (never written, or deleted)
+      # @return [Runtime::Instance, nil] the record, or nil when never written or deleted
       def find(id)
         result = @db.exec_params(%(SELECT id, state FROM #{quoted_head} WHERE id = $1), [id.to_s])
         return nil if result.ntuples.zero?
@@ -332,21 +175,12 @@ module Hecks
 
       # Lists every current record, ordered by id unless the caller names a field.
       #
-      # order_by is a runtime value, not framework-authored bluebook source
-      # like every other caller of order_expression — a query param off an
-      # HTTP request, in the console's case. Whitelisted against the
-      # aggregate's own real attributes (plus its lifecycle field) before
-      # it ever reaches order_expression, unlike a declared query's
-      # order_by, which the language itself already only lets name a real
-      # attribute at parse time. Without this, an unknown field wouldn't
-      # error — query_expression degrades a nil attribute to a harmless
-      # no-op path — it would just silently sort by nothing.
+      # `order_by` is a runtime value (an HTTP param), so it is checked against the aggregate's
+      # attributes; an unknown field would otherwise sort by nothing without erroring.
       #
-      # @param order_by [String, Symbol, nil] an attribute name, the lifecycle field, or a
-      #   dotted path whose first segment is one of those; nil orders by id
-      # @param direction [Symbol, String] `desc` in any case sorts descending, anything
-      #   else ascending; nulls sort first ascending and last descending
-      # @return [Array<Runtime::Instance>] every saved record, `[]` when there are none
+      # @param order_by [String, Symbol, nil] an attribute, the lifecycle field, or a dotted path
+      # @param direction [Symbol, String] `desc` sorts descending; nulls sort first ascending
+      # @return [Array<Runtime::Instance>] every saved record
       # @raise [Runtime::WiringError] if `order_by` names no attribute of this aggregate
       def all(order_by: nil, direction: :asc)
         return @db.exec(%(SELECT id, state FROM #{quoted_head} ORDER BY id)).map { |row| instance(row) } unless order_by
@@ -366,51 +200,16 @@ module Hecks
       # @return [Integer] how many saved, undeleted records the head holds
       def count = @db.exec(%(SELECT COUNT(*) FROM #{quoted_head}))[0]["count"].to_i
 
-      # Runs a declared query, looking candidate ids up in the field caches first when
-      # its `where` clauses allow it.
+      # Runs a declared query, looking candidate ids up in the field caches when every `where`
+      # clause allows it and only then reading those ids from the head view.
       #
-      # The two-phase shortcut (Track C, docs/implemented/postgres-era-adapter-
-      # split-plan.md §3). `SqlQueryBuilder#query` (`super`, unmodified per
-      # principle 2) always runs correctly here — it filters against
-      # `head_view`, which is already the fully-reduced current state —
-      # but for a domain that has minted a second era, that reduction
-      # itself is the expensive part, and no index on the jsonb path
-      # changes that (see field_cache.rb's own header for the SQL-
-      # semantics reason why). When every `where` clause this query
-      # declares either targets a cached field or is eligible to (an
-      # ordinary comparator, not a null-vs-value special case — see
-      # `cache_eligible?`), skip the reduction: look candidate ids up in
-      # the cache table(s) first (cheap, indexed, no reduction involved),
-      # then read only those ids' current state from `head_view` — safe
-      # through the reduction because `id` is its own partition key. Any
-      # clause that isn't cache-eligible (an uncached field, or a null
-      # comparison) is simply re-checked against `head_view` in the
-      # second phase, exactly as `super` would have checked it anyway —
-      # this can only ever narrow what phase two has to look at, never
-      # change what a clause means.
-      #
-      # Falls back to `super` whenever no clause can be accelerated — a
-      # query with no `where` at all (order_by-only — no cache table
-      # exists for these, see field_cache.rb), a query whose only clauses
-      # target fields with no cache table, or a domain that has never
-      # minted a second era at all (`@field_caches` is never empty just
-      # because era 1 has no reduction to skip — the cache tables still
-      # exist and still accelerate era 1 the same way, but the fallback
-      # path is already just as cheap there since head_view is the
-      # snapshot table verbatim for era 1; skipping straight to `super`
-      # in that case would be a valid future optimization, not attempted
-      # here to keep this one code path correct for every era uniformly).
+      # The cache only narrows candidates; the head view stays authoritative, so results match
+      # `super`. Uncached or null-comparison clauses are re-checked against the head view.
       #
       # @param declared [Bluebook::Query] the declared query, or a delegator wrapping one
-      #   (tenant scoping and reference hops fold extra `where` clauses in that way)
-      # @param args [Hash{Symbol => Object}] caller-supplied values for the clauses, limit
-      #   and offset that name an argument
-      # @param context [Hash] execution context the query port passes to every adapter;
-      #   unused here
-      # @return [Array<Runtime::Instance>] the matching records in declared order, or by
-      #   id when the query declares none; `[]` when nothing matches
-      # @raise [ArgumentError] if a clause uses an operator this dialect cannot compile,
-      #   or `contains` on a list of multi-field value objects
+      # @param args [Hash{Symbol => Object}] caller-supplied values for named arguments
+      # @return [Array<Runtime::Instance>] the matching records, by id when no order is declared
+      # @raise [ArgumentError] if a clause uses an operator this dialect cannot compile
       def query(declared, args = {}, context: {})
         return super if @field_caches.empty? || declared.wheres.empty?
 
@@ -424,59 +223,27 @@ module Hecks
         head_phase(declared, uncached, ids, args)
       end
 
-      # Runs a block inside one transaction holding the domain's cross-process write lock.
+      # Runs a block in one transaction holding the domain's cross-process write lock (ADR 0036).
       #
-      # 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.
+      # The lock must be taken before hydrate, so it wraps the whole dispatch order; the
+      # nested `append` joins this transaction and the lock is held until the block returns.
       #
-      # @yield the dispatch order to run under the lock; an exception rolls the
-      #   transaction back
-      # @yieldreturn [Object] whatever the dispatch order produces
+      # @yield the dispatch order; an exception rolls the transaction back
       # @return [Object] the block's own value
-      # @raise [PG::ConnectionBad] if the connection dropped; the adapter reconnects first,
-      #   then re-raises so the caller decides whether to retry
-      # @raise [Runtime::WiringError] if the connection dropped and the reconnect attempt
-      #   (`connect_for`) is refused as well
+      # @raise [PG::ConnectionBad] if the connection dropped; it reconnects, then re-raises
       def with_write_lock(&block) = transaction { lock_writes!; block.call } # rubocop:disable Style/Semicolon
 
-      # Appends one entry to the journal and brings the head snapshot and every field
-      # cache up to date, all in one transaction under the domain's write lock.
+      # Appends one entry to the journal and updates the head snapshot and every field cache,
+      # all in one transaction under the domain's write lock.
       #
-      # The lock is 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
-      # default evaluates. A different key from `mint_era!`/`merge_tail!`'s
-      # `hecks_eras:domain` : this serializes plain writes against each
-      # other, never against a mint. See postgres/lineage.rb's own comment
-      # for why only that half of the race is closed.
-      # The journal insert and the snapshot upsert/delete happen in the
-      # same transaction — real ACID atomicity, not the append-then-
-      # project two-step a file-based adapter needs a crash-recovery
-      # replay for (see Heki). If this transaction commits, the snapshot
-      # is already exactly as current as the journal; if it doesn't,
-      # neither happened. `project` stays uninvolved on purpose — it
-      # 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. 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.
+      # The lock precedes the INSERT because the ordinal comes from `nextval()` inside it. It is
+      # a different key from `mint_era!`'s, so it serializes writes, never a write against a mint.
+      # `project` stays out of it: AppendOnly#recover! already replays it on every boot.
       #
-      # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state`
-      #   is decoded domain state, encoded through `StateCodec` on the way in
+      # @param entry [Ports::Persistence::Entry] the save or delete to journal
       # @return [Ports::Persistence::Entry] the same entry, unchanged
       # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
-      # @raise [PG::Error] if Postgres refuses a statement, such as the era fence's
-      #   row-level security rejecting the INSERT
+      # @raise [PG::Error] if Postgres refuses a statement, such as the era fence's RLS
       def append(entry)
         refuse_superseded_write!
         transaction do
@@ -487,16 +254,10 @@ module Hecks
       end
 
       # Refuses a write from a checkout whose era a later mint has superseded.
-      #
-      # Before the transaction, before the lock, before the INSERT — a
-      # superseded checkout takes nothing and touches nothing. Reads are
-      # deliberately untouched: `EraResolver.check!`'s own contract for an
-      # old checkout is "may keep booting and reading, but may not keep
-      # writing", and the head views it reads through are its own era's.
+      # Runs before the transaction so a stale checkout takes no lock; reads stay allowed.
       #
       # @return [nil] when this boot's era is current
       # @raise [Runtime::WiringError] if the boot gate marked this era superseded
-      #   (`superseded_by` in the settings)
       def refuse_superseded_write!
         return unless @superseded_by
 
@@ -507,19 +268,12 @@ module Hecks
               "reboot to write again."
       end
 
-      # Saves an entry and reports whether it inserted or replaced, deciding that under the
-      # same lock that guards the write.
-      #
-      # Outcome detection, journal append and every derived projection share
-      # the same transaction and domain write lock. The lineage-aware head
-      # determines whether this id is already visible; no repository `find`
-      # occurs before entering this adapter-native operation.
+      # Saves an entry and reports whether it inserted or replaced, decided under the same lock
+      # that guards the write.
       #
       # @param entry [Ports::Persistence::Entry] the save to journal
-      # @param insert_only [Boolean] when true, an id the head already shows is left
-      #   untouched and nothing is journaled
-      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met
-      #   an existing record
+      # @param insert_only [Boolean] when true, an id already in the head is left untouched
+      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` hit a record
       # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
       # @raise [PG::Error] if Postgres refuses a statement
       def atomic_put(entry, insert_only: false)
@@ -541,31 +295,22 @@ module Hecks
         status
       end
 
-      # Builds the instance an entry describes, writing nothing.
-      #
-      # The head is derived — projecting is reading, so there is nothing
-      # to write here. `append` above already keeps the snapshot the head
-      # view reads from current, transactionally. The instance is still
-      # built (and validated) so a save returns what every other adapter
-      # returns.
+      # Builds the instance an entry describes, writing nothing; the head is derived, so
+      # projecting is reading.
       #
       # @param entry [Ports::Persistence::Entry] a journaled save or delete
       # @return [Runtime::Instance, nil] the saved record, or nil for a delete entry
-      # @raise [Runtime::WiringError] if the entry's state is still in its stored
-      #   (undecoded) form; see `Ports::Persistence::CodecBoundary`
+      # @raise [Runtime::WiringError] if the entry's state is still in its stored form
       def project(entry)
         return if entry.delete?
 
         Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
       end
 
-      # Reads this aggregate's whole journal, every era, in the order it was written.
-      # States come back decoded but untranslated: an ancestor era's row keeps the shape
-      # it was written in.
+      # Reads this aggregate's whole journal, every era, in write order. States are decoded but
+      # not translated: an ancestor era's row keeps the shape it was written in.
       #
-      # @return [Array<Ports::Persistence::Entry>] saves and deletes by ascending ordinal;
-      #   a delete's `state` is nil, `mirrors` is nil when none were recorded, and a row
-      #   with no recorded operation reads as `"save"`; `[]` for an empty journal
+      # @return [Array<Ports::Persistence::Entry>] entries by ascending ordinal
       def entries
         @db.exec_params(
           "SELECT aggregate_id, operation, state, mirrors FROM #{@lineage.quoted_journal} " \
@@ -582,30 +327,15 @@ module Hecks
         end
       end
 
-      # Deletes this aggregate's journal rows, refusing when row-level security silently
-      # turns the DELETE into a no-op.
-      #
-      # The journal carries FORCE ROW LEVEL SECURITY with exactly two
-      # policies — hecks_current_era's INSERT and hecks_read_all's
-      # SELECT (advance_era! above) — and no DELETE policy at all, for
-      # anyone. `FORCE` means even the table's own owner is fenced by
-      # that (only an actual Postgres superuser or a role granted
-      # BYPASSRLS sits above it — see lineage.rb's own header), so a
-      # plain `DELETE ... WHERE aggregate = $1` from an ordinary
-      # connection silently matches zero rows: no privilege error, no
-      # exception, just a no-op that looks like success. Counting
-      # before and comparing to what the DELETE itself reports is what
-      # tells "nothing to delete" apart from "RLS silently ate the
-      # delete" — the same row count, from the same statement, either
-      # way, with no separate query racing the DELETE for an answer.
+      # Deletes this aggregate's journal rows, refusing when row-level security turns the DELETE
+      # into a silent no-op.
       #
-      # Only the journal is cleared: head snapshots, field caches, the `events` table and
-      # saga rows are left as they are.
+      # The journal forces RLS with no DELETE policy, so an ordinary connection matches zero rows
+      # without error; comparing the count before with the DELETE's own count exposes that.
+      # Head snapshots, field caches, `events` and saga rows are left as they are.
       #
       # @return [Adapters::PostgresEra] this adapter
-      # @raise [Runtime::WiringError] if the journal held rows for this aggregate and the
-      #   DELETE removed none, which means the connection is neither a superuser nor
-      #   granted BYPASSRLS
+      # @raise [Runtime::WiringError] if the journal held rows and the DELETE removed none
       def reset!
         before = @db.exec_params(
           "SELECT count(*) FROM #{@lineage.quoted_journal} WHERE aggregate = $1", [table]
@@ -621,86 +351,39 @@ module Hecks
         self
       end
 
-      # Journals an instance's current state as a save entry. The direct-adapter
-      # convenience for specs and consoles; a runtime saves through
-      # `Ports::Persistence::AppendOnly`, which builds the entry itself.
+      # Journals an instance's current state as a save entry. A direct-adapter convenience for
+      # specs and consoles; a runtime saves through `Ports::Persistence::AppendOnly`.
       #
       # @param instance [Runtime::Instance] the record to persist
       # @return [Runtime::Instance] a fresh instance built from the journaled state
       # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
-      # @raise [PG::Error] if Postgres refuses a statement
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
         append(entry)
         project(entry)
       end
 
-      # Journals a delete entry for an id and tombstones it in the head snapshot, without
-      # checking first that the record exists.
+      # Journals a delete entry and tombstones the id in the head snapshot, without checking
+      # that the record exists.
       #
       # @param id [String, Object] the record's identity, journaled as `id.to_s`
-      # @return [true] always, whether or not a record had that id
+      # @return [true] always
       # @raise [Runtime::WiringError] if this boot's era has been superseded by a mint
-      # @raise [PG::Error] if Postgres refuses a statement
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         append(entry)
         true
       end
 
-      # Stores one emitted event durably in the `events` table, which every aggregate
-      # bound to this database and schema shares.
-      #
-      # @param event [Runtime::Event] the event to record; `payload` is stored as JSON,
-      #   `occurred_at` as text (an ISO 8601 UTC string, or nil), and `correlation` is
-      #   not stored
-      # @return [PG::Result] the INSERT's result, which carries no rows
-      def record_event(event)
-        @db.exec_params(
-          "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES ($1, $2, $3, $4, $5)",
-          [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
-        )
-      end
-
-      # Reads every recorded event in the order it was recorded. The `events` table is
-      # shared, so this is not limited to this adapter's aggregate.
-      #
-      # @return [Array<Runtime::Event>] events with symbol-keyed `payload`, `occurred_at`
-      #   as stored text and `correlation` nil; `[]` when none are recorded
-      def events
-        @db.exec("SELECT * FROM events ORDER BY id").map do |row|
-          Runtime::Event.new(
-            name:        row["name"],
-            aggregate:   row["aggregate"],
-            id:          row["aggregate_id"],
-            payload:     JSON.parse(row["payload"], symbolize_names: true),
-            occurred_at: row["occurred_at"]
-          )
-        end
-      end
+      # Saga rows keep `domain` as a column so domains sharing one schema stay isolated. No lock
+      # here: `SagaInterpreter`'s own mutex already serializes in-process writers.
 
-      # ── the optional saga-persistence capability (Ports::Persistence's
-      # own three-method shape, §2) — one row per (domain, process_manager,
-      # correlation), `domain` kept as an explicit column even under
-      # schema isolation so two domains sharing one schema (neither
-      # declares its own `schema`) still isolate correctly, matching
-      # `hecks_eras`' own precedent (postgres/lineage/provisioning.rb).
-      # No advisory lock of its own: every call here already runs inside
-      # `SagaInterpreter`'s own mutex (§7) serializing in-process writers,
-      # and gets the same cross-process safety an aggregate's own writes
-      # get from this adapter — no better, no worse.
-
-      # Checkpoints one saga instance, replacing the row for the same
-      # (domain, process manager, correlation) if one exists.
+      # Checkpoints one saga instance, replacing the row for the same (domain, process manager,
+      # correlation) if one exists.
       #
-      # @param process_manager [String, Symbol] the process manager's name
-      # @param correlation [String, Object] the instance's correlation value, stored as
-      #   `correlation.to_s`
-      # @param state [String, Symbol] the saga's current state name
       # @param memory [Hash] the saga's memory, stored as JSON
-      # @param completed_compensations [Array] the ledger of compensable legs already
-      #   completed, stored as JSON; `[]` when there are none
-      # @return [PG::Result] the upsert's result, which carries no rows
+      # @param completed_compensations [Array] compensable legs already completed, stored as JSON
+      # @return [PG::Result] the upsert's result
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.exec_params(
           "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
@@ -715,10 +398,7 @@ module Hecks
 
       # Removes a finished saga instance's checkpoint; a no-op when no such row exists.
       #
-      # @param process_manager [String, Symbol] the process manager's name
-      # @param correlation [String, Object] the instance's correlation value, matched as
-      #   `correlation.to_s`
-      # @return [PG::Result] the DELETE's result, which carries no rows
+      # @return [PG::Result] the DELETE's result
       def delete_saga(process_manager:, correlation:)
         @db.exec_params(
           "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
@@ -726,18 +406,10 @@ module Hecks
         )
       end
 
-      # Yields every saga checkpoint stored for this domain, so a booting registry can
-      # rehydrate its in-flight sagas.
+      # Yields every saga checkpoint stored for this domain, so a booting registry can rehydrate.
       #
-      # @yieldparam process_manager [String] the process manager's name
-      # @yieldparam correlation [String] the instance's correlation value
-      # @yieldparam state [String] the saga's state name
-      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, keys symbolized at
-      #   every depth
-      # @yieldparam completed_compensations [Array] the completed-compensation ledger,
-      #   `[]` when the row stores none
-      # @return [Enumerator, PG::Result] an enumerator over the same five values when no
-      #   block is given; otherwise the query result, which callers ignore
+      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, keys symbolized
+      # @return [Enumerator, PG::Result] an enumerator when no block is given
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
@@ -777,34 +449,14 @@ module Hecks
             "state = EXCLUDED.state WHERE #{quoted_head_snapshot}.ordinal < EXCLUDED.ordinal",
             [entry.id, ordinal, state_json]
           )
-          # **Same transaction, same ordinal** — every field cache stays
-          # exactly as current as the snapshot it's derived from, for
-          # the identical reason `postgres_era.rb`'s own header comment
-          # gives for the journal/snapshot pair: if this transaction
-          # commits, every cache row is already correct; if it doesn't,
-          # none of them changed.
+          # Same transaction and ordinal, so every cache is exactly as current as the snapshot.
           @field_caches.each do |field, cache_table|
             @lineage.upsert_field_cache_row!(cache_table, entry.id, ordinal, state_json, query_expression(field))
           end
         else
-          # A tombstone row, not a bare DELETE — H3 (docs/audits/2026-08-
-          # 10-main-bug-audit.md). A plain `DELETE FROM head_snapshot` is
-          # correct in isolation but wrong
-          # once an ancestor era is in the picture: for a record carried
-          # into this era from an ancestor, removing this era's row leaves
-          # nothing on the current-era side of `compile_head!`'s union to
-          # outrank the ancestor matview's own (still-present, still
-          # `save`) row, so `DISTINCT ON` picks the ancestor's row and
-          # the "deleted" record keeps reading back forever. Upserting a
-          # tombstone (`operation = 'delete'`, `state` NULL) instead
-          # means this era always has its own newest-ordinal row for the
-          # id, exactly like a real re-save does ("re-saves are
-          # masked correctly" — the audit's own phrasing for why that
-          # half never breaks) — it just carries `operation
-          # = 'delete'` instead of `'save'`, so `head_view`'s own `WHERE
-          # operation = 'save'` still correctly hides it. Ordinal-guarded
-          # the same as every other upsert here, so an out-of-order
-          # replay can never let a stale delete clobber a newer save.
+          # A tombstone row, not a bare DELETE: without one, an ancestor era's saved row would win
+          # the head's DISTINCT ON and the deleted record would read back. The ordinal guard keeps
+          # a stale replayed delete from clobbering a newer save.
           @db.exec_params(
             "INSERT INTO #{quoted_head_snapshot} (id, ordinal, operation, state) VALUES ($1, $2, 'delete', NULL) " \
             "ON CONFLICT (id) DO UPDATE SET ordinal = EXCLUDED.ordinal, operation = EXCLUDED.operation, " \
@@ -817,8 +469,6 @@ module Hecks
         ordinal
       end
 
-      # ── SqlQueryBuilder's dialect hooks ─────────────────────────────
-
       def select_list = "id, state"
       def from_relation = quoted_head
       def dialect_name = "PostgresEra"
@@ -854,17 +504,11 @@ module Hecks
         @db.exec_params(sql, binds).map { |row| instance(row) }
       end
 
-      # ── the rest of the dialect ─────────────────────────────────────
-
       def instance(row)
         Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row["state"]))
       end
 
-      # Through the state codec (PR A3), after any SQL-side era
-      # translation has already run: the head view hands back the
-      # translated jsonb, and decoding it is the last step, the same as
-      # every other adapter's read. A never-seeded projected field is
-      # simply absent from the blob, and stays absent.
+      # Runs after SQL-side era translation, as the last step of every read.
       def decode(state_json)
         Ports::Persistence::StateCodec.decode(@aggregate, JSON.parse(state_json))
       end
@@ -878,11 +522,8 @@ module Hecks
         numeric_field?(field) ? "(#{expression})::numeric" : expression
       end
 
-      # Postgres defaults to NULLS LAST on ASC; the port's in-memory
-      # semantics (NullPolicy.order, which SQLite's own default happens
-      # to match) put null rows FIRST ascending and LAST
-      # descending. Compile the placement explicitly so a declared query
-      # answers identically no matter which adapter serves it.
+      # Postgres defaults to NULLS LAST on ASC; place nulls explicitly (first ascending, last
+      # descending) so a declared query answers the same on every adapter.
       def order_clause(order_by, policy)
         direction = order_by.direction.to_s.downcase == "desc" ? "DESC" : "ASC"
         nulls = case policy&.mode.to_s
@@ -893,10 +534,7 @@ module Hecks
         "#{order_expression(order_by.field)} #{direction}#{nulls}, id #{direction}"
       end
 
-      # One shared walk decides numericness at any depth — inspecting
-      # only the first nested segment would let a two-level path
-      # (pizza.price_cents.cents) skip the ::numeric cast and order
-      # as text: "900" above "1200".
+      # One shared walk decides numericness at any depth, so a nested path is not ordered as text.
       def numeric_field?(field)
         name, *path = field.to_s.split(".")
         QuerySpecification::FieldPath.numeric?(@aggregate.attribute(name), path) do |type|
@@ -904,31 +542,16 @@ module Hecks
         end
       end
 
-      # `ARRAY[...]` of individually-escaped literals, never the hand-rolled
-      # '{a,b,c}' array-literal syntax — a segment is a field or
-      # value-object member name, and while today's callers only ever
-      # pass schema-declared names, this method has no way to know
-      # that, and the '{...}' form has no escaping at all: a segment
-      # containing a single quote closes the string early and whatever
-      # follows becomes live SQL. Measured, not assumed — a crafted
-      # field name of `x}' = '' OR $1::text = $1::text -- ` made a
-      # `where(secret: "public")` clause return every row regardless,
-      # against the '{...}' form; the `ARRAY[]` form below closes it, verified
-      # against the identical payload.
+      # `ARRAY[...]` of escaped literals, never the '{a,b}' syntax: that form has no escaping, so
+      # a quote in a segment would become live SQL.
       def jsonb_path(segments)
         "state #>> ARRAY[#{segments.map { |segment| text_literal(segment) }.join(', ')}]::text[]"
       end
 
       def text_literal(text) = "'#{text.to_s.gsub("'", "''")}'"
 
-      # ── the field-cache read shortcut (Track C) ─────────────────────
-
-      # Every declared `where`-field this aggregate's own queries and its
-      # entities' own queries use, minus anything a cache table can't
-      # represent (see `cacheable_field?`) — never `order_by`-only
-      # fields, which never needed a cache in the first place (sorting
-      # the reduced output was never blocked by the reduction; only
-      # filtering was — see field_cache.rb's own header).
+      # Where-fields of the aggregate's and its entities' queries that a cache table can represent;
+      # order_by-only fields never needed a cache.
       def ensure_field_caches!
         cached_where_fields.to_h do |field|
           [field, @lineage.ensure_field_cache!(table, @era, field, query_expression(field))]
@@ -948,14 +571,7 @@ module Hecks
         @aggregate.queries + @aggregate.entities.flat_map(&:queries)
       end
 
-      # List-typed fields are excluded, same boundary the plain `Postgres`
-      # and `Sqlite`/`D1` adapters independently landed on for their own
-      # automatic indexing: `contains` means element membership, and a
-      # (id, ordinal, one value) cache row has nowhere to put more than
-      # one element. Everything else — a plain scalar, the lifecycle
-      # field, or a non-list value-object member path — reduces to
-      # exactly one comparable value per id, which is the one shape this
-      # cache table represents.
+      # List fields are excluded: a one-value cache row cannot hold `contains` membership.
       def cacheable_field?(field)
         name = field.to_s.split(".").first
         return true if @aggregate.lifecycle&.field.to_s == name
@@ -964,28 +580,16 @@ module Hecks
         !attribute.nil? && !attribute.list?
       end
 
-      # A clause can be served by the cache when its field has a cache
-      # table and it isn't the null-vs-value special case
-      # `QuerySpecification::Common::NullPolicy` intercepts before
-      # `where_clause` ever runs (see `query`'s own header comment) — a
-      # clause that fails either check simply flows to `head_phase`
-      # unaccelerated, exactly as `super` would have evaluated it.
+      # A clause is cache-served when its field has a cache table and it is not a null comparison,
+      # which `NullPolicy` intercepts before `where_clause`.
       def cache_eligible?(clause, value)
         @field_caches.key?(clause.field.to_s) &&
           QuerySpecification::Common::NullPolicy.sql_predicate(query_expression(clause.field, value: value), clause.op,
                                                                value).nil?
       end
 
-      # **Phase one** — candidate ids, no reduction touched. One SELECT per
-      # cached clause against its own narrow (id, ordinal, value) table,
-      # `INTERSECT`ed into the set that satisfies every cached clause at
-      # once. Reuses `where_clause` (SqlQueryBuilder, private, already
-      # mixed into this class) unchanged against the cache table's own
-      # `value` column instead of a jsonb path expression — the exact
-      # same operator compilation (`eq`/`ne`/`gt`/`gte`/`lt`/`lte`/`in`)
-      # a live query already gets against the real column, so a cached
-      # field supports every comparator `super` would have, not just the
-      # `eq` example in the plan doc's own illustration.
+      # Phase one: candidate ids from the narrow cache tables, INTERSECTed. Reuses `where_clause`
+      # against each cache's `value` column, so every operator `super` supports works here.
       def cache_phase(cached)
         binds = []
         clauses = cached.map do |clause, value|
@@ -996,20 +600,8 @@ module Hecks
         @db.exec_params(clauses.join("\nINTERSECT\n"), binds).map { |row| row["id"] }
       end
 
-      # **Phase two** — `head_view`, restricted to phase one's candidate ids
-      # plus whatever clauses phase one couldn't accelerate, applied
-      # exactly the way `SqlQueryBuilder#query` (`super`) already applies
-      # every clause today: against the fully-reduced view, which is
-      # already correct regardless of caching (see this file's own
-      # `query` comment — a cache is a speed shortcut, never a
-      # correctness fix; head_view was always safe to filter directly,
-      # just expensive to reduce in the first place). Duplicates a small
-      # slice of `SqlQueryBuilder#query`'s own tail assembly (order_by/
-      # limit/offset) rather than reaching into it — principle 2
-      # (docs/implemented/postgres-era-adapter-split-plan.md): SqlQueryBuilder stays
-      # untouched by the era workaround, so this stays local to
-      # PostgresEra rather than growing a shared hook only one adapter
-      # would ever call.
+      # Phase two: the head view restricted to phase one's ids plus the clauses it could not
+      # accelerate. Repeats the tail of `SqlQueryBuilder#query` so that module stays untouched.
       def head_phase(declared, uncached, ids, args)
         binds = []
         clauses = ["id IN (#{ids.map { |id| placeholder(binds, id) }.join(', ')})"]
@@ -1034,19 +626,6 @@ module Hecks
         execute_query(sql, binds)
       end
 
-      def create_event_table!
-        @db.exec(<<~SQL)
-          CREATE TABLE IF NOT EXISTS events (
-            id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-            name         text NOT NULL,
-            aggregate    text NOT NULL,
-            aggregate_id text NOT NULL,
-            payload      jsonb,
-            occurred_at  text
-          )
-        SQL
-      end
-
       def create_saga_table!
         @db.exec(<<~SQL)
           CREATE TABLE IF NOT EXISTS hecks_saga_instances (
@@ -1060,10 +639,7 @@ module Hecks
             PRIMARY KEY (domain, process_manager, correlation)
           )
         SQL
-        # `CREATE TABLE IF NOT EXISTS` above is a no-op against a table
-        # 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.
+        # Covers a table created before this column existed, where IF NOT EXISTS is a no-op.
         @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
                  "NOT NULL DEFAULT '[]'::jsonb")
       end