hecks 1.3.0 → 1.4.0

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

@@ -7,8 +7,8 @@ require_relative "../../runtime/value"
 module Hecks
   module Adapters
     # The one SQL query compilation, shared by the SQLite and Postgres
-    # adapters — each used to carry its own copy of this walk, near-line-
-    # identical, and the copies could only drift. Every declared operator
+    # adapters — one walk rather than a near-line-identical copy per
+    # adapter, because copies can only drift. Every declared operator
     # compiles fully into SQL or the query refuses loudly; the null-policy
     # predicate, the comma-separated `in` convention, and the identity
     # ORDER BY fallback are spelled once, here.
@@ -17,7 +17,7 @@ module Hecks
     # supplies exactly those hooks:
     #
     #   placeholder(binds, value)     — "?" or "$N", recording the bind
-    #   contains_clause(expr, ph)     — instr() or position(), for a SCALAR field
+    #   contains_clause(expr, ph)     — instr() or position(), for a scalar field
     #   list_contains_clause(name, member, ph) — real element containment,
     #                                  for a `list_of` field (json_each /
     #                                  jsonb_array_elements)
@@ -33,6 +33,18 @@ module Hecks
         "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
       }.freeze
 
+      # Compiles a declared query into one SQL statement and runs it through the dialect's
+      # own `execute_query`, so filtering, ordering and paging all happen in the database.
+      #
+      # @param declared [QuerySpecification::Common::Options] the declared query: its
+      #   `wheres`, `order_by`, `limit` and `offset` are compiled; nothing else is read
+      # @param args [Hash{Symbol => Object}] values for the specification's symbolic operands
+      # @param context [Hash] execution context from `Ports::Query.execute`; accepted for the
+      #   port's call shape and not read
+      # @return [Array<Runtime::Instance>] the matching records in declared order, then by
+      #   id; `[]` when none match
+      # @raise [ArgumentError] if a where clause uses an operator this builder cannot compile,
+      #   or `contains` targets a list of a value object with more than one field
       def query(declared, args = {}, context: {})
         sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
@@ -91,7 +103,7 @@ module Hecks
           members = in_members(value)
           return empty_in_clause if members.empty?
 
-          # BOTH SIDES AS TEXT. `in` is a textual reading everywhere else
+          # **Both sides as text**. `in` is a textual reading everywhere else
           # — Ports::Query::InMemory#holds? compares `held.to_s` against
           # stringified members, and `in_members` above stringifies its
           # own — so a numeric field was the one shape where the engines
@@ -104,7 +116,7 @@ module Hecks
           # on a String, an Integer, and a value-object member.
           #
           # `eq`/`gt`/`lt` never had this problem because they bind the
-          # value's OWN type and route through `comparable_expression`,
+          # value's own type and route through `comparable_expression`,
           # which Postgres overrides to cast numerics.
           "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
         else
@@ -112,16 +124,16 @@ module Hecks
         end
       end
 
-      # A REAL ARRAY ALREADY SAYS WHERE ITS MEMBERS END. Splitting one on
+      # A real array already says where its members end. Splitting one on
       # commas re-reads a boundary it already drew — and an id is a
       # domain value (Naming::IDENTITY_JOIN joins a composite identity's
       # own parts, and the parts it joins are whatever an identity path
       # pulled out of real data), so a name carrying a comma would
       # silently become two members matching the wrong rows, or nothing.
-      # This branch used to call `value.to_s` unconditionally, which
-      # meant only a comma-joined STRING ever worked here, while
+      # Calling `value.to_s` unconditionally would mean only a
+      # comma-joined string ever works here, while
       # Ports::Query::InMemory and QueryInterpreter's own `members`
-      # already handled a real Array — three implementations of `in`,
+      # handle a real Array — three implementations of `in`,
       # two readings of it. Narrower than those two on one point,
       # deliberately: they unwrap a value-object/Hash element to its
       # own scalar first (`comparable`) before stringifying, a rule
@@ -140,15 +152,15 @@ module Hecks
       # member the bound value (or the declared types) say is numeric,
       # falling back to the one-field convention `value`.
       #
-      # A REFERENCE IS AN ID, stored as a bare scalar (never wrapped —
+      # A reference is an ID, stored as a bare scalar (never wrapped —
       # `Runtime::Value.refuse_object_reference` guarantees it), so it
-      # takes the SAME plain-column path as any other non-value-object
+      # takes the same plain-column path as any other non-value-object
       # attribute. Excluding it into the value-object member-picking logic
       # compiles a nested read against a row that has no nested key — a
       # path that can never match. Measured, not assumed: a `where` on a
       # has_one/belongs_to/reference_to field returned zero rows against
       # real data until that exclusion was removed.
-      # `member` resolves through two ORDERED fallback tiers — the bound
+      # `member` resolves through two ordered fallback tiers — the bound
       # value's own numeric field first, then the declared value object's
       # numeric-or-sole attribute — each documented above as fixing a
       # real, measured bug (a reference field matching nothing, a
@@ -168,7 +180,7 @@ module Hecks
         member = if path.empty? && value
                    hash = value.is_a?(Runtime::Value) ? value.to_h : value
                    numeric = hash.is_a?(Hash) && hash.find { |_key, item| item.is_a?(Numeric) }
-                   # NOT &.-able: `numeric` can be `false` (hash.is_a?(Hash) came
+                   # Not &.-able: `numeric` can be `false` (hash.is_a?(Hash) came
                    # back false) as well as nil (.find came back empty) — `&.`
                    # only guards nil, so `false.first` raises. False positive.
                    # rubocop:disable-next Style/SafeNavigation
@@ -176,8 +188,8 @@ module Hecks
                  end
         member ||= if path.empty? && attribute && value_object?(attribute)
                      object = @aggregate.value_object(attribute.type)
-                     # A SOLE attribute is the fallback when no member is
-                     # numeric — a single-attribute value object IS its one
+                     # A sole attribute is the fallback when no member is
+                     # numeric — a single-attribute value object is its one
                      # field whatever that field is named (`Behaviour::
                      # ValueObject#sole_attribute`, the same strict rule
                      # `Runtime::Value`'s own `.value` alias enforces), so
@@ -192,11 +204,11 @@ module Hecks
         nested_expression(name, path, member)
       end
 
-      # A NUMERIC MEMBER WINS if the value object has one (Price, Money —
+      # A numeric member wins if the value object has one (Price, Money —
       # what every ordered comparison in the corpus until now compared),
-      # otherwise the SAME single-field fallback `query_expression`'s own
+      # otherwise the same single-field fallback `query_expression`'s own
       # `nested_expression(name, path, member || "value")` already
-      # makes for the COLUMN side — a plain `attribute :value, String`
+      # makes for the column side — a plain `attribute :value, String`
       # value object (IdentityId, RoleName, ...) has no numeric member at
       # all, and returning nil there silently turned an equality
       # comparison into `IS NULL`, matching nothing. Both sides of one
@@ -221,16 +233,16 @@ module Hecks
         !attr.list? && !@aggregate.value_object(attr.type).nil?
       end
 
-      # `contains` on a `list_of` field means real ELEMENT membership, not
+      # `contains` on a `list_of` field means real element membership, not
       # a substring search over the column's raw JSON text — the reading
       # QueryInterpreter#holds? and Ports::Query::InMemory already give a
-      # real Array, and the SQL side used to disagree with it (a substring
-      # match over `[{"value":"not_high_risk"}]` falsely matches
+      # real Array, and a substring search would disagree with it (a
+      # substring match over `[{"value":"not_high_risk"}]` falsely matches
       # "high_risk"). Returns nil for a non-list field (the caller falls
       # back to `contains_clause`, unchanged), "" for a list of bare
       # scalars (no member to walk into), or the one field name a
       # single-field value-object element carries. A list of a
-      # MULTI-field value object has no one scalar to compare against and
+      # multi-field value object has no one scalar to compare against and
       # is refused rather than guessed.
       def list_member(field)
         return nil if field.to_s.include?(".")

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

@@ -16,7 +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 —
+          # `projects` fields (S12, ADR 0025) are a local column too —
           # `CommandInterpreter#seed_projected_fields`/`RebuildSweep`
           # both write one straight into `Instance#state` the same as
           # any other field, so a column has to exist to hold it or
@@ -37,15 +37,15 @@ module Hecks
         end
 
         def encode(attr, value)
-          # NEVER SET IS NOT EMPTY. `then_set ... append:` starts a list at `[]`
+          # **Never set is not empty**. `then_set ... append:` starts a list at `[]`
           # the moment the first element lands, but a list attribute nothing has
-          # ever appended to — the shape every OTHER aggregate in the corpus
+          # ever appended to — the shape every other aggregate in the corpus
           # happened not to carry, until one declared a list-typed head
           # attribute that no creating command populates by default — has to
           # stay NULL to answer the same as Memory does. Forcing it to `[]`
           # here is how a persistence topology invented data no dispatch wrote.
-          return (value.nil? ? nil : JSON.generate(value)) if attr.list?
-          return JSON.generate(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
+          return (value.nil? ? nil : state_json(value)) if attr.list?
+          return state_json(value) if value.is_a?(Hash) || value.is_a?(Runtime::Value)
 
           value
         end
@@ -56,25 +56,53 @@ module Hecks
           encode(field[:attribute], value)
         end
 
+        # Every JSON column's text goes through the state codec's `encode`
+        # (PR A3) — string keys at every depth, Values materialized.
+        def state_json(value) = JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, value))
+
+        # The row's columns reassembled into the stored state, then decoded
+        # once through the state codec (PR A3) — the same deep, IR-driven
+        # key spelling every other adapter's read now produces, instead of
+        # this codec's own `symbolize_names:` walk.
         def decode(row)
-          persisted_fields.each_with_object({}) do |field, state|
+          state = persisted_fields.each_with_object({}) do |field, raw_state|
             attr = field[:attribute]
             unless attr
-              state[field[:name]] = row[field[:name].to_s]
+              value = row[field[:name].to_s]
+              next if value.nil? && projected_only?(field)
+
+              raw_state[field[:name]] = value
               next
             end
             raw = row[attr.name.to_s]
-            state[attr.name] =
+            raw_state[attr.name] =
               if attr.list? || value_object?(attr)
-                raw ? JSON.parse(raw, symbolize_names: true) : nil
+                raw ? JSON.parse(raw) : nil
               else
-                # A REFERENCE lands here now, with the ordinary scalars. It holds
+                # A reference lands here now, with the ordinary scalars. It holds
                 # the id of a head, which is text — `JSON.parse("acct-1")` raises,
                 # so reading it as JSON was only ever survivable while the column
                 # held an object.
                 raw
               end
           end
+          Ports::Persistence::StateCodec.decode(@aggregate, state)
+        end
+
+        # A NULL `projects` column is a field never seeded, not a stored
+        # NIL — so it reads back absent, the way Heki/PostgresEra (one blob
+        # holding only what was written) already answer it. A column holds
+        # every persisted field whether or not the record ever had one, so
+        # NULL is the only spelling "never set" has here; and nothing ever
+        # stores a nil projected value to confuse it with —
+        # `CommandInterpreter#seed_projected_fields` and
+        # `RebuildSweep#refresh` both skip a nil remote value. Absent is also
+        # what `RebuildSweep#refresh`'s `record.key?` and
+        # `Registry#projection_current?`'s row comparison expect. The
+        # lifecycle field (the other `attribute: nil` column) keeps its NULL.
+        def projected_only?(field)
+          @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
+            @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
       end
     end

data/lib/hecks/adapters/driven/sqlite/projection.rb

@@ -6,7 +6,7 @@ require_relative "../../../rendering"
 require_relative "../../../ports/query/in_memory"
 
 # The subclass needs its parent — and sqlite.rb requires this file at
-# its BOTTOM, after class Sqlite is defined, so the require cycle this
+# its bottom, after class Sqlite is defined, so the require cycle this
 # creates resolves correctly from either entry point.
 require_relative "../sqlite"
 
@@ -17,6 +17,13 @@ module Hecks
     # bare id it holds — the same shapes the command path writes, so there
     # is no second representation to accept here any more.
     class SqliteProjection < Sqlite
+      # Replaces or deletes the read store's row for one journal entry, encoding the entry's
+      # state directly rather than through a `Runtime::Instance`.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+      # @return [Ports::Persistence::Entry, Array] the same `entry` for a save; for a delete,
+      #   the `DELETE` statement's empty result rows
+      # @raise [SQLite3::Exception] if the statement fails
       def project(entry)
         return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
 
@@ -34,36 +41,51 @@ module Hecks
       # than scanning repositories and matching references in Ruby.
       #
       # M19 (docs/audits/2026-08-10-main-bug-audit.md,
-      # docs/audits/2026-08-11-bug-triage.md) — this used to diverge from
+      # docs/audits/2026-08-11-bug-triage.md) — this agrees with
       # `Runtime::ReadModelInterpreter#project` (the in-process path) on
-      # two counts, both fixed here to agree with it:
+      # the two counts where a native path can most easily diverge:
       #
-      # MISSING ROOT: the in-process path's own `fetch` refuses with
-      # `NotFound` when the reference argument names no record —
-      # `query_read_model` used to answer a silent `{root: nil, ...}`
-      # instead, the one path a caller could dispatch a read model
+      # **Missing root**: the in-process path's own `fetch` refuses with
+      # `NotFound` when the reference argument names no record, and so
+      # does this. Answering a silent `{root: nil, ...}` instead would
+      # make this the one path where a caller could dispatch a read model
       # against a record that never existed and get back something that
-      # LOOKS like an empty report rather than the refusal every other
+      # looks like an empty report rather than the refusal every other
       # path gives.
       #
-      # CHAINED-INCLUDE JOIN SCOPE: a non-root head was always matched
-      # against the ROOT's own id, regardless of what it actually
-      # references — correct for a head that references the root
-      # directly, silently EMPTY for one that references another
+      # **Chained-include join scope**: matching a non-root head against
+      # the root's own id alone, regardless of what it actually
+      # references, is correct for a head that references the root
+      # directly and silently empty for one that references another
       # included head instead (`Leaf` -> `Mid` -> `Root`, `Leaf` itself
-      # has no attribute referencing `Root` at all, so `references`
-      # was always `[]`). The in-process path's own root-first fix
-      # (`ReadModelInterpreter#project`'s "ROOT FIRST, ALWAYS" comment)
-      # already matches a head against ANY already-projected source, not
-      # only the root — `select_related` now does the same: each head is
+      # has no attribute referencing `Root` at all, so its `references`
+      # would always be `[]`). The in-process path
+      # (`ReadModelInterpreter#project`'s "root first, always" comment)
+      # matches a head against any already-projected source, not
+      # only the root — `select_related` does the same: each head is
       # matched against every source resolved so far (root first, then
       # declared order — the same one-level-of-declaration-order
-      # dependency the in-process path itself still has, documented
+      # dependency the in-process path itself has, documented
       # there as L2, not a gap introduced here).
+      #
+      # @param _domain [String, Symbol] name of the domain declaring the read model; not read
+      # @param model [Bluebook::ReadModel, Runtime::TenantScope::Scoped] the read model to
+      #   answer, or the tenant-scoping delegator around one; must have a reference target
+      # @param args [Hash{Symbol => Object}] the read model's arguments; the entry under
+      #   `model.reference_name` is the root record's id
+      # @param bluebook [Bluebook::Chapter, nil] the domain's bluebook, which resolves each
+      #   included aggregate by name; nil is refused
+      # @return [Array<Hash>] a one-element Array holding the report Hash, keyed by each
+      #   head's `as` name: an Array of plain state Hashes (each with `:id`) for a `many`
+      #   head, otherwise one such Hash, or nil when that head matched no row
+      # @raise [ArgumentError] if `bluebook` is nil
+      # @raise [KeyError] if `args` has no entry for the model's reference argument
+      # @raise [Runtime::NotFound] if no projected row has the referenced root id
+      # @raise [SQLite3::Exception] if a statement fails
       def query_read_model(_domain, model, args, bluebook = nil)
         raise ArgumentError, "projection query needs its domain bluebook" unless bluebook
 
-        # The REFERENCE's own shape, read the same way ReadModelInterpreter
+        # The reference's own shape, read the same way ReadModelInterpreter
         # reads it — not the identity unwrap, which is gone : an identity is
         # declared as a path and followed.
         reference_id = args.fetch(model.reference_name).to_s
@@ -72,7 +94,7 @@ module Hecks
         # eligible in the same read model now.
         eligible = model.filtered_head_names
 
-        # ROOT FIRST, ALWAYS — see this method's own header. Mirrors
+        # **Root first, always** — see this method's own header. Mirrors
         # `ReadModelInterpreter#project`'s identical partition, for the
         # identical reason: a later head's own join has to be able to
         # match against a root (or another head) already resolved.
@@ -84,9 +106,9 @@ module Hecks
           rows = if head[:aggregate] == model.reference_target
                    [select_projected(aggregate, reference_id) ||
                      raise(Runtime::NotFound,
-                           Runtime::RefusalWording.render("NotFound", "read_model_reference_missing",
-                                                          aggregate: head[:aggregate],
-                                                          offered:   Hecks::Rendering.describe(reference_id)))]
+                           Runtime::RefusalWording.render_site("NotFound", "read_model_reference_missing",
+                                                               aggregate: head[:aggregate],
+                                                               offered:   Hecks::Rendering.describe(reference_id)))]
                  else
                    select_related(aggregate, projected)
                  end
@@ -108,12 +130,12 @@ module Hecks
         row && projected_instance(aggregate, row)
       end
 
-      # Matched against EVERY source already projected (root first, then
+      # Matched against every source already projected (root first, then
       # declared order — see this class's own `query_read_model` header),
       # not only the root — a head whose own reference points at another
-      # included head rather than the root directly used to match nothing
-      # at all, since its reference attribute was compared against a
-      # target (the root) it never names.
+      # included head rather than the root directly would otherwise match
+      # nothing at all, since its reference attribute would be compared
+      # against a target (the root) it never names.
       def select_related(aggregate, projected)
         matches = projected.flat_map do |source|
           references = aggregate.attributes.select do |attribute|
@@ -128,7 +150,7 @@ module Hecks
         end
         return [] if matches.empty?
 
-        # A REFERENCE COLUMN HOLDS THE ID, so it compares as itself. The
+        # A reference column holds the ID, so it compares as itself. The
         # `json_extract(col,'$.value') = ? OR col = ?` this replaced was
         # reading both shapes because both existed — one written by the
         # command path, one by older journals. There is one shape now.
@@ -154,7 +176,7 @@ module Hecks
         if (lifecycle = aggregate.lifecycle) && fields.none? { |name, _| name == lifecycle.field }
           fields << [lifecycle.field, nil]
         end
-        # `projects` FIELDS (S12, ADR 0025) NEED READING BACK TOO — `project`
+        # `projects` fields (S12, ADR 0025) need reading back too — `project`
         # (above) already writes one into its own column via `persisted_fields`
         # (`Codec#persisted_fields`, this class's own superclass module), but
         # this method built its own independent field list that never
@@ -167,24 +189,30 @@ module Hecks
         fields
       end
 
+      # Decoded through the state codec (PR A3) against the row's own
+      # aggregate — see Codec#decode, including why a NULL projected-only
+      # column reads back absent.
       def decode_fields(fields, aggregate, row)
-        fields.each_with_object({}) do |(name, attribute), state|
+        state = fields.each_with_object({}) do |(name, attribute), raw_state|
           raw = row[name.to_s]
           # rubocop:disable Lint/DuplicateBranch -- the nil-attribute and
           # reference-id branches both just answer `raw`, coincidentally, for
           # two unrelated reasons (see each branch's own comment); merging
           # them would blur that distinction.
-          state[name] =
+          next if attribute.nil? && raw.nil? && aggregate.lifecycle&.field&.to_sym != name.to_sym
+
+          raw_state[name] =
             if attribute.nil?
               raw
             elsif attribute.list? || !aggregate.value_object(attribute.type).nil?
-              raw ? JSON.parse(raw, symbolize_names: true) : nil
+              raw ? JSON.parse(raw) : nil
             else
               # A reference is a scalar id — see Codec#decode.
               raw
             end
           # rubocop:enable Lint/DuplicateBranch
         end
+        Ports::Persistence::StateCodec.decode(aggregate, state)
       end
     end
   end

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

@@ -12,11 +12,11 @@ module Hecks
           @db.execute(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
-          # RIGHT HERE, NOT AS A SEPARATE STEP IN `Sqlite#initialize` —
+          # Right here, not as a separate step in `Sqlite#initialize` —
           # `create_aggregate_table!` is the one piece of DDL `D1`
           # already calls verbatim through this same shared module
           # (`d1.rb`'s own header: "reuses Sqlite::SchemaBuilder and
-          # Sqlite::Codec UNCHANGED"). Folding index creation in here,
+          # Sqlite::Codec unchanged"). Folding index creation in here,
           # right after the table it indexes exists, is what makes D1's
           # own automatic indexing a real, running thing rather than an
           # aspiration that only Sqlite ever calls — no D1-specific
@@ -63,7 +63,7 @@ module Hecks
           @db.execute("ALTER TABLE #{quoted_entry_table} ADD COLUMN mirrors TEXT")
         end
 
-        # THE OPTIONAL saga-persistence capability's own table (§2/§4) —
+        # The optional saga-persistence capability's own table (§2/§4) —
         # shared here so `D1`, which `include`s this module verbatim for
         # its own `events`-table DDL (`d1.rb`), gets this for free too.
         # `domain` stays an explicit column even though SQLite has no
@@ -131,10 +131,10 @@ module Hecks
         # `ensure_head_snapshot!`/`ensure_first_head!` already use) ────
 
         # Every field a declared query ever filters or sorts on, across
-        # the aggregate's OWN queries and every entity's own queries —
+        # the aggregate's own queries and every entity's own queries —
         # `query_surfaces` in `dsl/aggregate_builder.rb` walks the
-        # identical pair. AN ENTITY'S QUERY STILL RUNS AGAINST THIS
-        # TABLE: it compiles through `query_expression`, which is
+        # identical pair. An entity's query still runs against this
+        # table: it compiles through `query_expression`, which is
         # `@aggregate`-scoped, not entity-scoped, so an entity's
         # declared `where`/`order_by` is indexed here too, same as any
         # other declared query — not skipped as "some other table's
@@ -158,14 +158,14 @@ module Hecks
         #     plain-vs-nested decision);
         #   - a non-list value-object attribute, referenced bare or
         #     through a member path (`field` or `field.member`) — an
-        #     EXPRESSION index over `query_expression(field)`'s own
+        #     expression index over `query_expression(field)`'s own
         #     `json_extract(...)` text. Reusing the query compiler's own
         #     expression, not re-deriving the string a second way, is
         #     the whole point: a textual mismatch between the index and
         #     what a real query compiles to is invisible to SQLite's
         #     planner, and two independent copies of this logic can only
         #     drift apart over time;
-        #   - a list-typed attribute — NO index. SQLite's `contains`
+        #   - a list-typed attribute — no index. SQLite's `contains`
         #     compiles to `EXISTS (SELECT 1 FROM json_each(col) WHERE
         #     ...)` (`list_contains_clause`, in `sql_query_builder.rb`)
         #     — an element-membership scan a plain index on the raw
@@ -178,8 +178,8 @@ module Hecks
         #
         # A field naming neither a real attribute nor the lifecycle
         # field can't happen through the DSL today — `seal_query_field`
-        # (`dsl/aggregate_builder.rb`) already refuses it at PARSE time.
-        # This runs at adapter BOOT, not parse time, so it skips rather
+        # (`dsl/aggregate_builder.rb`) already refuses it at parse time.
+        # This runs at adapter boot, not parse time, so it skips rather
         # than crashes ugly if that invariant is ever violated.
         def ensure_index_for_field!(field)
           name, * = field.to_s.split(".")
@@ -195,8 +195,8 @@ module Hecks
           )
         end
 
-        # `idx_<table>_<sanitized field>` — TABLE-PREFIXED because
-        # SQLite index names are GLOBAL to the database, not scoped per
+        # `idx_<table>_<sanitized field>` — table-prefixed because
+        # SQLite index names are global to the database, not scoped per
         # table the way a column name is; two different aggregates each
         # indexing a field called "name" would collide without it. The
         # field itself is sanitized (a dotted path's "." in particular)