hecks 2.8.0 → 2.9.0

data/lib/hecks/adapters/driven/memory.rb

@@ -5,22 +5,13 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # The default, no-external-dependency persistence/query adapter — a
-    # plain in-process Hash of `Runtime::Instance` records per aggregate,
-    # with an append-only `@entries`/`@events` log alongside it. Every
-    # behaviors suite must resolve to this one (see
-    # Behaviors::Expectations#guard_memory_only!) precisely because a fresh
-    # instance really is a fresh store, with nothing shared across tests or
-    # tenants.
+    # The default in-process adapter: a Hash of `Runtime::Instance` records
+    # per aggregate, plus an append-only `@entries`/`@events` log.
     class Memory
       # Reports that two tenant boots of this adapter never share state.
       #
-      # **Tenant-capable trivially** — see `Runtime::TenantCheck`'s own header
-      # for the full reasoning. `@records` is a plain instance variable;
-      # two `Runtime.boot` calls build two entirely separate Registry
-      # objects and, through them, two entirely separate Memory
-      # instances, so two tenant boots never share this adapter's state
-      # by construction — nothing here needs to know "tenant" exists.
+      # Trivially true: `@records` is a plain ivar, and each `Runtime.boot`
+      # builds a wholly separate Memory instance.
       #
       # @return [Boolean] always true
       def self.tenant_capable? = true
@@ -81,11 +72,10 @@ module Hecks
 
       # Records one journal entry, holding a codec copy of its state.
       #
-      # Through the state codec, like every durable adapter (PR A3): the
-      # journal holds `StateCodec.copy` — exactly what an encode-to-JSON
-      # then decode would hand back — never the caller's own live state
-      # objects, so an entry read back here has the same deep-symbol,
-      # plain-Hash shape a Heki/Sqlite/Postgres entry has.
+      # Like every durable adapter, the journal holds `StateCodec.copy` —
+      # what an encode-to-JSON then decode would hand back — never the
+      # caller's own live state objects, so an entry read back here has
+      # the same deep-symbol, plain-Hash shape a Heki/Sqlite/Postgres entry has.
       #
       # @param entry [Ports::Persistence::Entry] the save or delete to journal
       # @return [Ports::Persistence::Entry] the caller's own `entry`, not the journalled copy
@@ -163,18 +153,8 @@ module Hecks
 
       # Empties the records, journal, event log and outbox, keeping the adapter itself.
       #
-      # Every other driven adapter (Postgres/PostgresEra/Sqlite/D1)
-      # implements this too — `Ports::Persistence::AppendOnly#reset!`
-      # forwards to it and only raises when the wrapped adapter doesn't
-      # respond to `reset!` at all, and nothing about "in memory" implies
-      # "cannot be cleared". Existing callers that fully re-`Hecks.boot`
-      # a domain per test case don't need this — they get a brand new
-      # `Memory` instance, with brand new empty `@records`/`@events`/
-      # `@entries`, for free. This is for the other case: a caller that
-      # deliberately keeps one booted runtime across many cases (to skip
-      # `load_domain`'s own per-boot parse/verify cost) and wants each
-      # case to start from the same clean slate `Hecks.boot` would have
-      # given it, without paying for a fresh boot to get there.
+      # Lets a caller that keeps one booted runtime across many cases reset
+      # to a clean slate without paying for a fresh boot.
       #
       # @return [Adapters::Memory] self, now empty
       def reset!
@@ -253,74 +233,13 @@ module Hecks
 
       private
 
-      # The language's own bootstrap saves its self-description quadratically
-      # otherwise. `MetaValidator::Judge` dispatches every declaration in the
-      # self-hosted grammar into a fresh, private, never-durable `Memory`
-      # store (meta_validator.rb's own header: "each bluebook is judged in a
-      # fresh in-memory store") — and every nested-entity dispatch (a
-      # `ValueObject::Member`, then one `ValueObject::Member::Pair` per
-      # key/value pair) re-saves the whole parent aggregate, because entities
-      # have no storage of their own (S17, ADR 0026). A table of N member
-      # rows costs O(N) dispatches, each paying twice for the aggregate's own
-      # size-N state: once in `StateCodec.copy` (`append`/`project`'s own
-      # encode-then-decode round trip) and again in `Instance#initialize`'s
-      # `hydrate_with_defaults`, which re-walks and re-validates every
-      # element of an entity list on every save regardless of how many of
-      # them were already valid as of the previous one
-      # (`Value::EntityListCoercion#hydrate_entity_list` has no "already
-      # hydrated" shortcut for entity elements — only a value-object list
-      # element gets one). Both are O(N) per save, so a table of N rows
-      # costs O(N^2) total — and it is paid by every rspec worker and every
-      # `bin/*` subprocess that boots the language at all (found live: PR
-      # #738's 128-row `RefusalSiteArgument` table alone tripled this one
-      # aggregate's own save time, 6.7s -> 18.2s).
-      #
-      # `Runtime::Value.judge_bootstrapping?` (judge.rb's own `send_to`,
-      # wrapping every dispatch the judge makes) is already the flag that
-      # marks exactly this window and nothing else — "never for a real
-      # domain's own declared value objects... which Judge never dispatches
-      # commands against" (coercion.rb's own comment on the same flag). It
-      # is reused here rather than a new toggle for the same reason: one
-      # flag, one meaning, checked by two unrelated callers for two
-      # unrelated purposes (loosening a scalar-shape check there, skipping
-      # both round trips here) is simpler to reason about than two flags
-      # that would always be true or false together.
-      #
-      # Why skipping both is safe here, and only here: `entry.state` a save
-      # ever hands this adapter is always `instance.state.dup`
-      # (`AppendOnly#save`) — a shallow copy of an already-hydrated,
-      # already-validated live `Instance`'s own state, built by the very
-      # same `Value.for_attribute`/`hydrate_with_defaults` machinery
-      # `StateCodec.copy` and `Instance.new`'s default (`hydrate: true`)
-      # path would otherwise redo. Every value inside it — a `Runtime::
-      # Value` (frozen through, see value.rb's own header) or a `list_of`
-      # attribute's own array (`Freezer.deep`d the moment it was built,
-      # instance.rb's own header on `Instance#dup`) — is already immutable,
-      # so a bare top-level `.dup` is exactly as safe as `Instance#dup`
-      # already trusts it to be everywhere else in this codebase; nothing
-      # below the top level is ever mutated in place. Re-deriving the same
-      # answer through the codec and through re-hydration is therefore
-      # pure, avoidable cost for this one caller — never a correctness
-      # requirement.
-      #
-      # `bootstrap_fast_path?` is the guard, and it is deliberately cheap —
-      # O(this aggregate's own declared attribute count), never O(N) — so
-      # it cannot reintroduce the very cost it exists to avoid: `StateCodec.
-      # decoded?` (the obvious-looking alternative) recurses into every
-      # `list_of` element to check it, which is exactly the O(N) walk this
-      # whole change removes. A `Hash` with every top-level key already a
-      # `Symbol` is what `Instance#state` always looks like (`Value.hydrate`
-      # refuses anything else, coercion.rb's own header), so it is checked
-      # here instead — true for the actual shape every real save has,
-      # false (falling back to the always-correct slow path) for anything
-      # that somehow doesn't.
-      #
-      # Verified empirically before landing, not just argued: instrumenting
-      # every bootstrapping-time save across a full `grammar_registry` boot
-      # and comparing this fast path's own state, journal entry, and stored
-      # `Instance` against the unmodified `StateCodec.copy` + `Instance.new
-      # (hydrate: true)` pipeline's found them equal (`==`) for every one of
-      # 6,617 saves, zero mismatches.
+      # Skips the codec copy and rehydration round trip while judging the
+      # self-hosted grammar (S17, ADR 0026), where re-validating already-valid
+      # entity state costs O(N) per save and O(N^2) across an N-row table.
+      # Safe only here: `entry.state` is already hydrated, validated, deep-
+      # frozen state from the same Value machinery the skipped paths rerun.
+      # The check itself must stay O(this aggregate's attribute count), not
+      # O(N), so it can't reintroduce the cost it exists to avoid.
       def bootstrap_fast_path?(state)
         Runtime::Value.judge_bootstrapping? && state.is_a?(Hash) && state.keys.all?(Symbol)
       end

data/lib/hecks/adapters/driven/mock_stripe_adapter.rb

@@ -2,20 +2,8 @@
 
 module Hecks
   module Adapters
-    # A generic stand-in for a real Checkout-Session-style adapter — no
-    # network call, no real account, matching whatever real payment
-    # adapter a project pairs it with by shape alone
-    # (`create_session(event:, registration_id:, success_url:, cancel_url:)
-    # -> a URL string`), the same way `Memory` stands in for a real
-    # persistence adapter without knowing anything about the domain bound
-    # to it. Never reads `event`'s own fields — a real adapter needs the
-    # price/name inside it to build a session a payer actually sees;
-    # this only needs to look enough like one to swap in.
-    #
-    # The URL it returns carries the same `registration_id` a real
-    # webhook's metadata would, so a caller building its own signed
-    # webhook against it (a smoke test, CI) has something real to key
-    # off of — the real shape production has, minus the network hop.
+    # A network-free stand-in for a Checkout-Session-style payment adapter, matching it by
+    # method shape alone. The returned URL carries `registration_id`, as webhook metadata would.
     class MockStripeAdapter
       # Accepts and discards the shared adapter constructor arguments; this adapter holds no
       # state of its own.
@@ -29,14 +17,10 @@ module Hecks
       # Builds a fake checkout URL carrying `registration_id`, standing in for a real
       # Checkout-Session call.
       #
-      # @param event [Object] the record data a real adapter would read the price and name
-      #   from; adapter-defined shape (whatever the declaring bluebook's `checkout` port
-      #   operation supplies as `event`) and never read here
-      # @param registration_id [String] the registration id to key a signed webhook off of;
-      #   embedded in the returned URL, never read otherwise
+      # @param event [Object] the record data a real adapter would read; never read here
+      # @param registration_id [String] embedded in the returned URL, never read otherwise
       # @param success_url [String] the base URL to redirect a successful payer to
-      # @param cancel_url [String] accepted for the shared checkout-adapter call shape and
-      #   never read
+      # @param cancel_url [String] accepted for the shared call shape and never read
       # @return [String] `success_url` with `mock_checkout=1` and `mock_registration_id`
       #   query parameters appended
       def create_session(event:, registration_id:, success_url:, cancel_url:)

data/lib/hecks/adapters/driven/postgres/codec.rb

@@ -3,15 +3,8 @@ require_relative "../../../runtime/value"
 module Hecks
   module Adapters
     class Postgres
-      # How a state crosses the column boundary: which fields persist, and
-      # how each one encodes into (and decodes out of) its column. Same
-      # shape as Sqlite::Codec (one column per attribute, JSON for
-      # nested/list) — not its mechanics. Sqlite's own columns carry no
-      # type affinity worth trusting on the way back out (SQLite gives it
-      # back typed anyway via the driver), but `pg` hands every column
-      # back as text unless a type map says otherwise, so a real `bigint`/
-      # `double precision` column needs its own coercion on decode that
-      # Sqlite never had to write.
+      # Encodes and decodes a state to and from its columns, coercing `pg`'s text back to
+      # numbers.
       module Codec
         private
 
@@ -23,9 +16,7 @@ module Hecks
           fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && fields.none? do |field|
             field[:name] == lifecycle.field
           end
-          # `projects` fields (S12, ADR 0025) are a local column too — see
-          # Sqlite::Codec#persisted_fields' own comment; identical reasoning,
-          # `text` to match this file's own lowercase SQL type spelling.
+          # `projects` fields are local columns too (ADR 0025).
           @aggregate.projected_fields.each do |field|
             next if fields.any? { |f| f[:name] == field.name }
 
@@ -35,10 +26,7 @@ module Hecks
         end
 
         def encode(attr, value)
-          # **Never set is not empty** — same reasoning as Sqlite::Codec's own
-          # comment: a list attribute nothing has ever appended to has to
-          # stay NULL to answer the same as Memory does, not become `[]`
-          # invented by this adapter's own storage.
+          # A never-set list stays NULL rather than becoming `[]`, matching Memory.
           return (value.nil? ? nil : state_json(value)) if attr.list?
           return state_json(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
 
@@ -51,13 +39,9 @@ module Hecks
           encode(field[:attribute], value)
         end
 
-        # Every jsonb column's text goes through the state codec's `encode`
-        # (PR A3) — see Sqlite::Codec#state_json.
         def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
 
-        # Columns reassembled, then decoded once through the state codec
-        # (PR A3) — see Sqlite::Codec#decode, including why a NULL
-        # projected-only column reads back absent.
+        # A NULL projected-only column reads back absent.
         def decode(row)
           state = persisted_fields.each_with_object({}) do |field, raw_state|
             attr = field[:attribute]
@@ -84,13 +68,7 @@ module Hecks
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
 
-        # `pg` returns every column as a Ruby String by default (no type
-        # map installed) — a `bigint`/`double precision` column has to be
-        # coerced back on the way out, unlike Sqlite3's own driver, which
-        # already types a row by the column's declared affinity. Mirrors
-        # SQL_TYPES' own mapping: whatever gets a real numeric column here
-        # gets converted back here, everything else (String, references,
-        # enums, ...) passes through as the text it already is.
+        # `pg` returns every column as a String, so numeric columns are coerced back.
         def coerce_scalar(attr, raw)
           return nil if raw.nil?
 

data/lib/hecks/adapters/driven/postgres/outbox.rb

@@ -3,21 +3,12 @@ require_relative "../../../runtime/outbox"
 
 module Hecks
   module Adapters
-    # **The outbox, Postgres-shaped** — shared verbatim by `Postgres` and the
-    # era plugin's `PostgresEra`, the same way their `events` and
-    # `hecks_saga_instances` DDL is copied between them: nothing here is
-    # lineage-specific. Needs `@db` (a `PG::Connection`) and `table`
-    # (the aggregate's storage name) from the including class. See
-    # `Runtime::Outbox` for what the four verbs mean, and Sqlite's copy
-    # for the SQL idioms (`ON CONFLICT DO NOTHING` = idempotent enqueue,
-    # `WHERE status = 'pending'` = the compare-and-set claim).
+    # Outbox storage shared by `Postgres` and `PostgresEra`; needs `@db` and `table`.
+    # See `Runtime::Outbox` for the four verbs.
     module PostgresOutbox
       # Runs the block inside one Postgres transaction, joining an already-open one.
       #
-      # **Re-entrant** — `Interpreting#run_dispatch_order` opens one
-      # transaction around save+emit+outbox and the adapter's own
-      # `append`/`atomic_put`/`delete` each open theirs; PG refuses
-      # BEGIN inside BEGIN, so an inner call joins the open one.
+      # Re-entrant: PG refuses BEGIN inside BEGIN, so an inner call joins the open one.
       #
       # @yield the writes to commit together; an exception raised inside rolls the
       #   outermost transaction back

data/lib/hecks/adapters/driven/postgres/reconnect.rb

@@ -1,28 +1,7 @@
 module Hecks
   module Adapters
-    # **Self-healing connection** — shared verbatim by `Postgres` and the era
-    # plugin's `PostgresEra`, the same way `PostgresOutbox` (outbox.rb) is:
-    # nothing here is lineage-specific, and `PostgresOutbox`'s own
-    # `@db.exec*` calls route through this module's `pg_exec`/
-    # `pg_exec_params` too, since both classes mix it in. Needs `@db` (a
-    # `PG::Connection`), `@aggregate`, and `@settings` from the including
-    # class — the same three `self.class.connect_for(@aggregate.name,
-    # @settings)` already needs to build one in the first place.
-    #
-    # A backend killed out from under an adapter (a DBA's own
-    # `pg_terminate_backend`, a load balancer's failover, a restart) —
-    # chaos-tested against the plain `Postgres` adapter: `PG::ConnectionBad`
-    # on the query that hit it, and permanently on every query after,
-    # since nothing ever replaced `@db` with a live connection.
-    # `pg_exec`/`pg_exec_params` are the two primitives every other method
-    # in either class funnels through — wrapping them here, once,
-    # self-heals `@db` for the next caller. The current call still
-    # raises — reconnecting cannot tell a caller whether its own write
-    # reached the server before the connection died, so silently
-    # retrying it here could silently double it; that ambiguity is
-    # exactly why `Runtime::SagaInterpreter`'s own defect-retry exists
-    # one layer up, where a dispatch is retried as a whole (fresh
-    # hydrate, fresh `given`s), not as a lone SQL statement.
+    # Replaces a dead `@db` after `PG::ConnectionBad`; shared by `Postgres` and `PostgresEra`.
+    # Needs `@db`, `@aggregate` and `@settings`.
     module PostgresReconnect
       # Runs one parameterless statement, replacing a dead connection before re-raising.
       #
@@ -56,13 +35,8 @@ module Hecks
 
       private
 
-      # **Best-effort** — a reconnect attempt that itself fails (the server
-      # is actually down, not just this one backend) leaves `@db`
-      # unchanged; the `PG::ConnectionBad` already being re-raised by
-      # `pg_exec`/`pg_exec_params` above still reaches the caller either
-      # way, so swallowing a failed reconnect attempt here loses no
-      # information — it only avoids masking the original error with a
-      # second one.
+      # The failing call still raises and is never retried: it may have reached the server.
+      # A failed reconnect is swallowed so it does not mask the original error.
       def reconnect!
         @db = self.class.connect_for(@aggregate.name, @settings)
       rescue PG::Error

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -3,14 +3,8 @@ require "digest"
 module Hecks
   module Adapters
     class Postgres
-      # The DDL: one table per aggregate, a real column per attribute (a
-      # jsonb column per nested/list attribute), an append-only entry
-      # table beside it, the shared events/saga tables — and the automatic
-      # indexing this adapter carries that `PostgresEra` does not (see
-      # docs/implemented/postgres-era-adapter-split-plan.md, governing principle 3:
-      # every field a declared query filters or sorts on is safe to index
-      # directly here, since there is no `head_view` reduction to route
-      # around the way `PostgresEra`'s own cache-table story exists for).
+      # DDL for the aggregate, entry, event and saga tables, plus the automatic
+      # indexes derived from declared queries.
       module SchemaBuilder
         private
 
@@ -19,40 +13,15 @@ module Hecks
           @db.exec(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
-          # **Self-healing, same idiom as `ensure_indexes!` below** —
-          # `CREATE TABLE IF NOT EXISTS` above does not retroactively add a
-          # column to an already-existing table (a committed database from
-          # before optimistic-concurrency CAS existed), so this runs
-          # unconditionally on every boot and no-ops once the column is
-          # there. Adapter bookkeeping only — never listed in
-          # `persisted_fields` (Codec), so it never appears in `decode`'s
-          # domain-state hash or `Instance#to_h`.
+          # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
+          # the bookkeeping column is healed on every boot.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
-          # Same self-healing shape, for domain attributes themselves —
-          # `hecks_version` above only heals the adapter's own bookkeeping
-          # column; a bluebook attribute added (or, via `translations/`,
-          # renamed) after this table already exists is not bookkeeping,
-          # but the identical gap applies: `CREATE TABLE IF NOT EXISTS`
-          # is a no-op against the existing table, so without this a new
-          # attribute boots clean and then dies `PG::UndefinedColumn` on
-          # the first `project` — discovered chaos-testing a live rename
-          # against this adapter (no era, no translation prompt; those
-          # live in `PostgresEra` — this is the plain adapter's own,
-          # simpler contract: "the table always has every column the
-          # bluebook currently declares"). No `NOT NULL`, no `DEFAULT` —
-          # existing rows get SQL NULL for a column they never had a
-          # value for, exactly what a fresh row would get for an unset
-          # optional attribute (`encode_field`'s own nil handling).
+          # Same healing for declared attributes: existing rows get NULL, as an unset
+          # optional attribute would.
           persisted_fields.each do |field|
             @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
                      "#{quote_ident(field[:name])} #{field[:sql_type]}")
           end
-          # Right here, not a separate step in `Postgres#initialize` —
-          # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
-          # uses: index creation runs unconditionally, right after the
-          # table it indexes exists, the same self-healing shape
-          # `ensure_head_snapshot!`/`ensure_first_head!` already use on
-          # `PostgresEra`'s side.
           ensure_indexes!
         end
 
@@ -68,8 +37,6 @@ module Hecks
           SQL
         end
 
-        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
-        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
         def create_event_table!
           @db.exec(<<~SQL)
             CREATE TABLE IF NOT EXISTS events (
@@ -81,10 +48,27 @@ module Hecks
               occurred_at  text
             )
           SQL
+          # Backs #events_for's per-record lookup (a `corrects` command's history read).
+          @db.exec(
+            "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"
+          )
+        end
+
+        # One row per aggregate table, naming the highest entry `sequence` this table has
+        # already had projected into it — shared across every aggregate, since it is keyed
+        # by table name rather than declared per aggregate.
+        def create_checkpoint_table!
+          @db.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_checkpoints (
+              aggregate_table text PRIMARY KEY,
+              last_sequence   bigint NOT NULL DEFAULT 0
+            )
+          SQL
+          # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so
+          # the bookkeeping column is healed on every boot, same as create_aggregate_table!.
+          @db.exec("ALTER TABLE hecks_checkpoints ADD COLUMN IF NOT EXISTS compacted_through bigint NOT NULL DEFAULT 0")
         end
 
-        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
-        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
         def create_saga_table!
           @db.exec(<<~SQL)
             CREATE TABLE IF NOT EXISTS hecks_saga_instances (
@@ -98,11 +82,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, for the
-          # identical reason.
+          # Heals a table created before this column existed.
           @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb " \
                    "NOT NULL DEFAULT '[]'::jsonb")
         end
@@ -113,24 +93,8 @@ module Hecks
           SQL_TYPES.fetch(attr.type, "text")
         end
 
-        # ── automatic indexing ───────────────────────────────────────
-        #
-        # Derived from every declared query's `where`/`order_by` fields —
-        # no bluebook author opts in, matching every other self-healing
-        # schema move this adapter makes. Walks the aggregate's own
-        # queries and each entity's own queries — the same enumeration
-        # `dsl/aggregate_builder.rb`'s own `query_surfaces` walks at
-        # declaration-seal time — but an entity's own fields never
-        # produce an index below: an entity has no table of its own, its
-        # rows live inside a list-typed attribute on the aggregate's own
-        # table (`QueryInterpreter#entity_rows` resolves it that way, and
-        # answers an entity query entirely in memory over `repository.all`
-        # — it never reaches this adapter's own `query` method at all).
-        # Every list-typed attribute is excluded below regardless (see
-        # `index_field!`), so an entity's own field would always resolve
-        # to "skip" anyway. Walked explicitly rather than silently
-        # dropped, so a reader can see entities were considered here, not
-        # forgotten.
+        # Indexes every field a declared query filters or sorts on. Entity queries are
+        # skipped: entities have no table, and their queries run in memory.
         def ensure_indexes!
           query_surfaces.each do |owner, queries|
             next unless owner.equal?(@aggregate)
@@ -149,50 +113,18 @@ module Hecks
           index_field!(query.order_by.field) if query.order_by
         end
 
-        # A `list_of` attribute is never indexed here — this adapter's
-        # own `contains` on a list field compiles to `EXISTS (SELECT 1
-        # FROM jsonb_array_elements(...) ...)` (see `list_contains_clause`
-        # below), a SQL shape neither a plain btree on the raw jsonb
-        # column nor even a GIN jsonb index (`@>`, `?`) accelerates —
-        # Postgres's own GIN jsonb operators match a different SQL shape
-        # than the `EXISTS` + `jsonb_array_elements` this codebase always
-        # compiles a list `contains` to. An index here would be dead
-        # weight, not free correctness, so none is attempted.
+        # A list attribute is never indexed: `contains` compiles to EXISTS over
+        # jsonb_array_elements, which neither a btree nor a GIN jsonb index accelerates.
         def index_field!(field)
-          # A hop path ("owner/field" — `Bluebook::AggregateBuilder`'s own
-          # convention for a field reached by crossing a reference,
-          # `aggregate_builder.rb`'s own `field.to_s.include?("/")`
-          # checks) is never indexed here — same reasoning as `list_of`
-          # below: `query_expression`/`nested_expression` below have no
-          # dialect for this shape at all (they'd compile the whole
-          # "owner/field" string as one bare column/jsonb-path segment,
-          # which is not a real column and errors PG::UndefinedColumn on
-          # `CREATE INDEX`, discovered fuzzing a real Postgres boot of
-          # `examples/banking` — Account's own `projects :customer_status,
-          # from: :"customer.status"` compiles to exactly this shape).
-          # Skipping the index is always safe, the same way skipping a
-          # `list_of` index is: an index is a perf optimization, not
-          # correctness, so "never built" beats "built wrong." Whether a
-          # hop-path field can be queried at all against this adapter is
-          # a separate, still-open question this skip does not answer —
-          # see docs/future-features.md's fuzzer-adapter entry, and
-          # docs/1.0-readiness.md item 2 for this gap's other two
-          # independent failure points (Postgres querying, Rust codegen's
-          # `OpenForSuspendedCustomers` — bin/rust_coverage's own
-          # allowlist) — tracked together, not as three unrelated bugs.
+          # A hop path ("owner/field") has no column or jsonb path to index; it would
+          # fail CREATE INDEX with PG::UndefinedColumn.
           return if field.to_s.include?("/")
 
           name, *_path = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
           return if attribute&.list?
 
-          # The same expression the query itself compiles to — calling
-          # `query_expression`/`plain_column`, the real dialect methods,
-          # rather than a second, hand-rolled derivation of the same
-          # path that could silently drift from it. An index whose
-          # expression doesn't match the planner's own candidate
-          # expression byte-for-byte is invisible to the planner,
-          # created or not.
+          # Built from the query's own expression so the planner can match it byte for byte.
           expression = query_expression(field.to_s)
           if expression == plain_column(name)
             create_plain_index!(name)
@@ -211,13 +143,7 @@ module Hecks
           @db.exec("CREATE INDEX IF NOT EXISTS #{quote_ident(name)} ON #{quoted_table} ((#{expression}))")
         end
 
-        # Postgres identifiers cap at 63 bytes. Hashing table + field
-        # together keeps every generated index name well under that no
-        # matter how long an aggregate or attribute name gets, and keeps
-        # two distinct fields — on the same table or different ones —
-        # from ever colliding, or truncating into the same name the way
-        # a naive `"idx_#{table}_#{field}"` could once either got long
-        # enough.
+        # Hashed so the name stays under Postgres's 63-byte identifier limit and never collides.
         def index_name(field)
           "hecks_idx_#{Digest::SHA256.hexdigest("#{table}:#{field}")[0, 40]}"
         end