hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,80 @@
+require "prism"
+require_relative "../../bluebook/expression/canonical_form"
+
+module Hecks
+  module Adapters
+    class NotExtractable < StandardError; end
+
+    module Prism
+      TREES = {}
+
+      module_function
+
+      def canonical(block)
+        body = body_source(block)
+        body && canonicalise(body)
+      end
+
+      def body_source(block)
+        file, line = block.source_location
+        return nil unless file && File.readable?(file)
+
+        node = block_node_at(file, line)
+        node&.body&.slice
+      end
+
+      def block_node_at(file, line)
+        found = nil
+        walk(tree_for(file)) do |node|
+          next unless node.is_a?(::Prism::BlockNode)
+          next unless node.location.start_line == line
+
+          found ||= node
+        end
+        found
+      end
+
+      def tree_for(file)
+        # ::Prism.parse_file(file) reads the file itself, at the C
+        # extension level — bypassing Ruby's own File/IO layer entirely.
+        # That's invisible to anything that virtualizes the filesystem at
+        # the Ruby level instead of the OS level (e.g. tebako's memfs,
+        # used to press a hecks-based app into a single executable —
+        # see domain/README.md's "Deploying" section in lifeadelics for
+        # why that matters). ::Prism.parse(File.read(file)) parses the
+        # exact same bytes, just read through Ruby's File.read first,
+        # which those tools do intercept.
+        TREES[file] ||= ::Prism.parse(File.read(file)).value
+      end
+
+      # `TREES` caches for the life of the PROCESS, keyed by path, with
+      # no staleness check — correct for every ordinary caller (a file
+      # loads once per process: one `bin/ir` run, one rspec worker,
+      # never edited out from under it), but WRONG for anything that
+      # legitimately reloads an edited file in-process: a stale cached
+      # tree reports a `given`/`ensures` block at its OLD line number,
+      # which no longer matches the freshly re-executed file's own
+      # `block.source_location` — surfacing as "did not survive
+      # extraction" on a perfectly valid file. Found for real building
+      # `Hecks::Codemod` (lib/hecks/codemod.rb), which used to
+      # reach into `TREES.clear` directly — a private implementation
+      # detail poked from outside. `forget`/`forget_all` are the real
+      # API so nothing else that reloads an edited file in-process has
+      # to know `TREES` exists at all.
+      def forget(file) = TREES.delete(file)
+
+      def forget_all = TREES.clear
+
+      def walk(node, &visit)
+        return unless node.is_a?(::Prism::Node)
+
+        visit.call(node)
+        node.compact_child_nodes.each { |child| walk(child, &visit) }
+      end
+
+      def canonicalise(source)
+        Bluebook::Expression::CanonicalForm.apply(source)
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/secure_random_identity.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "SecureRandomIdentity" do
+  port "identity_generation"
+end

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

@@ -0,0 +1,14 @@
+require "securerandom"
+
+module Hecks
+  module Adapters
+    # The real `identity_generation` fulfillment — an actual random
+    # UUID, for an actual deployment. `SequentialIdentity` is the
+    # deterministic sibling specs/fuzzing bind instead.
+    module SecureRandomIdentity
+      module_function
+
+      def uuid = SecureRandom.uuid
+    end
+  end
+end

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

@@ -0,0 +1,221 @@
+require_relative "../../forms/value_object_shape"
+require_relative "../../query_specification/common/null_policy"
+require_relative "../../query_specification/field_path"
+require_relative "../../runtime/errors"
+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
+    # 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.
+    #
+    # What a dialect actually differs on is narrow, and each adapter
+    # supplies exactly those hooks:
+    #
+    #   placeholder(binds, value)     — "?" or "$N", recording the bind
+    #   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)
+    #   empty_in_clause               — "0" or "FALSE"
+    #   comparable_expression(e, v)   — ::numeric cast, where the dialect casts
+    #   plain_column(name)            — a real column or a jsonb path
+    #   nested_expression(name, path, member) — json_extract or state #>>
+    #   order_clause(order_by, policy)
+    #   execute_query(sql, binds)     — run it, return instances
+    #   dialect_name                  — for the refusal message
+    module SqlQueryBuilder
+      COMPARATORS = {
+        "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
+      }.freeze
+
+      def query(declared, args = {}, context: {})
+        sql = +"SELECT #{select_list} FROM #{from_relation}"
+        clauses = []
+        binds = []
+        declared.wheres.each do |clause|
+          value = query_value(clause.value, args)
+          expression = query_expression(clause.field, value: value)
+          if (null_predicate = QuerySpecification::Common::NullPolicy.sql_predicate(expression, clause.op, value))
+            clauses << null_predicate.first
+            next
+          end
+          clauses << where_clause(clause.op.to_s, expression, value, binds, field: clause.field)
+        end
+        sql << " WHERE #{clauses.join(' AND ')}" unless clauses.empty?
+        sql << if declared.order_by
+                 " ORDER BY #{order_clause(declared.order_by, declared.null_semantics)}"
+               else
+                 " ORDER BY id"
+               end
+        sql << " LIMIT #{placeholder(binds, query_value(declared.limit.value, args).to_i)}" if declared.limit
+        # An offset with no declared limit — SQLite refuses a bare OFFSET
+        # outright (LIMIT -1 is its unbounded idiom) while Postgres accepts
+        # one, so the dialect supplies its own unbounded spelling. Found by
+        # the adapter-agreement gate on its first run, not by either
+        # adapter's own spec: each was self-consistent, they just disagreed.
+        sql << unbounded_limit if !declared.limit && declared.offset
+        sql << " OFFSET #{placeholder(binds, query_value(declared.offset.value, args).to_i)}" if declared.offset
+        execute_query(sql, binds)
+      end
+
+      private
+
+      def where_clause(op, expression, value, binds, field: nil)
+        case op
+        when "eq", "ne", "gt", "gte", "lt", "lte"
+          "#{comparable_expression(expression, value)} #{COMPARATORS.fetch(op)} #{placeholder(binds, value)}"
+        when "contains"
+          member = field && list_member(field)
+          if member
+            list_contains_clause(field.to_s, member, placeholder(binds, value.to_s))
+          else
+            contains_clause(expression, placeholder(binds, value.to_s))
+          end
+        when "in"
+          members = in_members(value)
+          return empty_in_clause if members.empty?
+
+          # 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
+          # could not agree: `in_members` binds '100', while the column
+          # expression yields the number 100, and `100 IN ('100','300')`
+          # is false in SQLite (a json_extract result carries no column
+          # affinity to coerce it) where Memory matched. Casting the
+          # expression rather than typing the members keeps one rule for
+          # every field: no type inference, and `in` means the same thing
+          # 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`,
+          # which Postgres overrides to cast numerics.
+          "CAST(#{expression} AS TEXT) IN (#{members.map { |member| placeholder(binds, member) }.join(', ')})"
+        else
+          raise ArgumentError, "#{dialect_name} query adapter does not support #{op.inspect}"
+        end
+      end
+
+      # 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
+      # Ports::Query::InMemory and QueryInterpreter's own `members`
+      # already handled 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
+      # this doesn't reproduce — every real caller of `in` today, and
+      # the cross-aggregate hop this exists for, passes plain scalar
+      # ids, never a value-object element.
+      def in_members(value)
+        return value.map(&:to_s).reject(&:empty?) if value.is_a?(Array)
+
+        value.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      # Every declared field compiles into an expression over the stored
+      # shape — or the query never runs. The member-picking rules are the
+      # same in both dialects: a value-object field compares through the
+      # 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 —
+      # `Runtime::Value.refuse_object_reference` guarantees it), so it
+      # 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.
+      def query_expression(field, value: nil)
+        name, *path = field.to_s.split(".")
+        attribute = @aggregate.attribute(name)
+
+        return plain_column(name) if path.empty? && @aggregate.lifecycle&.field.to_s == name
+        return plain_column(name) if path.empty? && attribute && !value_object?(attribute)
+
+        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) }
+                   numeric ? numeric.first : nil
+                 end
+        member ||= if path.empty? && attribute && value_object?(attribute)
+                     object = @aggregate.value_object(attribute.type)
+                     Forms::ValueObjectShape.numeric_member(object)&.name
+                   end
+        nested_expression(name, path, member)
+      end
+
+      # 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
+      # `nested_expression(name, path, member || "value")` already
+      # 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
+      # comparison have to agree on which field they mean, or they
+      # compare two different things and call it a where clause.
+      def query_value(value, args)
+        value = args[value] if value.is_a?(Symbol)
+        hash = value.is_a?(Runtime::Value) ? value.to_h : value
+        if hash.is_a?(Hash)
+          numeric = hash.find { |_key, item| item.is_a?(Numeric) }
+          return numeric.last if numeric
+          return hash[:value] if hash.key?(:value)
+          return hash.values.first if hash.size == 1
+        end
+
+        Runtime::Value.scalar(value)
+      rescue Runtime::TypeMismatch
+        value.is_a?(Hash) && value.size == 1 ? value.values.first : value
+      end
+
+      def value_object?(attr)
+        !attr.list? && !@aggregate.value_object(attr.type).nil?
+      end
+
+      # `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
+      # "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
+      # is refused rather than guessed.
+      def list_member(field)
+        return nil if field.to_s.include?(".")
+
+        attribute = @aggregate.attribute(field.to_s)
+        return nil unless attribute&.list?
+
+        object = @aggregate.value_object(attribute.type)
+        return "" unless object
+        return object.attributes.first.name.to_s if object.attributes.size == 1
+
+        raise ArgumentError,
+              "#{dialect_name} query adapter cannot compile contains on #{field} — " \
+              "#{attribute.type} carries more than one field, so no single scalar to compare"
+      end
+
+      # The dialect that casts nothing overrides nothing.
+      def comparable_expression(expression, _value) = expression
+
+      # The dialect that accepts a bare OFFSET overrides nothing.
+      def unbounded_limit = ""
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+require_relative "../../../runtime/value"
+
+module Hecks
+  module Adapters
+    class Sqlite
+      # How a state crosses the column boundary: which fields persist,
+      # and how each one encodes into (and decodes out of) its column.
+      module Codec
+        private
+
+        def persisted_fields
+          fields = @aggregate.attributes.reject { |attribute| attribute.name == :id }.map do |attribute|
+            { name: attribute.name, attribute: attribute, sql_type: sql_type(attribute) }
+          end
+          lifecycle = @aggregate.lifecycle
+          fields << { name: lifecycle.field, attribute: nil, sql_type: "TEXT" } if lifecycle && !fields.any? { |field| field[:name] == lifecycle.field }
+          fields
+        end
+
+        def encode(attr, value)
+          # 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
+          # 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)
+
+          value
+        end
+
+        def encode_field(field, value)
+          return value unless field[:attribute]
+
+          encode(field[:attribute], value)
+        end
+
+        def decode(row)
+          persisted_fields.each_with_object({}) do |field, state|
+            attr = field[:attribute]
+            unless attr
+              state[field[:name]] = row[field[:name].to_s]
+              next
+            end
+            raw = row[attr.name.to_s]
+            state[attr.name] =
+              if attr.list? || value_object?(attr)
+                raw ? JSON.parse(raw, symbolize_names: true) : nil
+              else
+                # 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
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+require_relative "../../../runtime/instance"
+require_relative "../../../runtime/value"
+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
+# creates resolves correctly from either entry point.
+require_relative "../sqlite"
+
+module Hecks
+  module Adapters
+    # Rebuilds a read store from the authoritative journal, entry by entry.
+    # A value object is written as its JSON object and a reference as the
+    # 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
+      def project(entry)
+        return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
+
+        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
+        values  = [entry.id.to_s] + persisted_fields.map { |field| encode_field(field, entry.state[field[:name]]) }
+        @db.execute(
+          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{Array.new(columns.size,
+                                                                                              '?').join(', ')})", values
+        )
+        entry
+      end
+
+      # Execute a declared read model against the projected aggregate-head
+      # tables. The report shape is assembled from SQL-selected rows, rather
+      # than scanning repositories and matching references in Ruby.
+      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
+        # 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
+        eligible = model.filtered_head_name
+        reports = {}
+        model.aggregate_heads.each do |head|
+          aggregate = bluebook.aggregate(head[:aggregate])
+          rows = if head[:aggregate] == model.reference_target
+                   [select_projected(aggregate, reference_id)].compact
+                 else
+                   select_related(aggregate, model.reference_target, reference_id)
+                 end
+          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          reports[head[:as]] = if head[:many]
+                                 rows.map { |row| Runtime::Value.materialize(row.to_h) }
+                               else
+                                 rows.first && Runtime::Value.materialize(rows.first.to_h)
+                               end
+        end
+        [reports]
+      end
+
+      private
+
+      def select_projected(aggregate, id)
+        row = @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id.to_s])
+        row && projected_instance(aggregate, row)
+      end
+
+      def select_related(aggregate, target, id)
+        references = aggregate.attributes.select do |attribute|
+          attribute.reference? && attribute.type.target_name == target.to_s
+        end
+        return [] if references.empty?
+
+        # 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.
+        clauses = references.map { |attribute| "#{quote_ident(attribute.name)} = ?" }
+        bind = references.map { id.to_s }
+        @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(' OR ')} ORDER BY id", bind)
+           .map { |row| projected_instance(aggregate, row) }
+      end
+
+      def projected_instance(aggregate, row)
+        Runtime::Instance.new(aggregate: aggregate, id: row["id"], state: decode_for(aggregate, row))
+      end
+
+      def decode_for(aggregate, row)
+        fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
+        if (lifecycle = aggregate.lifecycle) && !fields.any? { |name, _| name == lifecycle.field }
+          fields << [lifecycle.field, nil]
+        end
+        fields.each_with_object({}) do |(name, attribute), state|
+          raw = row[name.to_s]
+          state[name] =
+            if attribute.nil?
+              raw
+            elsif attribute.list? || !aggregate.value_object(attribute.type).nil?
+              raw ? JSON.parse(raw, symbolize_names: true) : nil
+            else
+              # A reference is a scalar id — see Codec#decode.
+              raw
+            end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # The DDL: one table per aggregate head, an append-only entry table
+      # beside it, the shared events table, and the two ALTERs that let an
+      # older database grow the columns newer code writes.
+      module SchemaBuilder
+        private
+
+        def create_aggregate_table!
+          columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
+          @db.execute(
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
+          )
+          # 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,
+          # 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
+          # wiring needed, because D1 never has to know this exists.
+          ensure_indexes!
+        end
+
+        def create_event_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS events (
+              id           INTEGER PRIMARY KEY AUTOINCREMENT,
+              name         TEXT NOT NULL,
+              aggregate    TEXT NOT NULL,
+              aggregate_id TEXT NOT NULL,
+              payload      TEXT,
+              occurred_at  TEXT
+            )
+          SQL
+        end
+
+        def create_entry_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{quoted_entry_table} (
+              sequence     INTEGER PRIMARY KEY AUTOINCREMENT,
+              aggregate_id TEXT NOT NULL,
+              operation    TEXT NOT NULL DEFAULT 'save',
+              state        TEXT NOT NULL,
+              mirrors      TEXT
+            )
+          SQL
+        end
+
+        def ensure_entry_operation_column!
+          columns = @db.execute("PRAGMA table_info(#{quoted_entry_table})").map { |row| row["name"] }
+          return if columns.include?("operation")
+
+          @db.execute("ALTER TABLE #{quoted_entry_table} ADD COLUMN operation TEXT NOT NULL DEFAULT 'save'")
+        end
+
+        def ensure_entry_mirrors_column!
+          columns = @db.execute("PRAGMA table_info(#{quoted_entry_table})").map { |row| row["name"] }
+          return if columns.include?("mirrors")
+
+          @db.execute("ALTER TABLE #{quoted_entry_table} ADD COLUMN mirrors TEXT")
+        end
+
+        # 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
+        # schema/namespace concept the way Postgres does — matches
+        # `hecks_saga_instances`' own Postgres shape (§3) and covers the
+        # (uncommon but real) case of a domain explicitly sharing one
+        # `database` file/D1 database with another.
+        def create_saga_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_saga_instances (
+              domain          TEXT NOT NULL,
+              process_manager TEXT NOT NULL,
+              correlation     TEXT NOT NULL,
+              state           TEXT NOT NULL,
+              memory          TEXT NOT NULL,
+              PRIMARY KEY (domain, process_manager, correlation)
+            )
+          SQL
+        end
+
+        def sql_type(attr)
+          return "TEXT" if attr.list?
+
+          SQL_TYPES.fetch(attr.type, "TEXT")
+        end
+
+        # ── automatic indexing (plan principle 3: derived from existing
+        # declared `where`/`order_by` IR, no new DSL keyword — this runs
+        # unconditionally on every boot, `CREATE INDEX IF NOT EXISTS`,
+        # the same self-healing idiom `postgres_era.rb`'s own
+        # `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 —
+        # `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
+        # `@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
+        # concern."
+        def ensure_indexes!
+          declared_query_fields.each { |field| ensure_index_for_field!(field) }
+        end
+
+        def declared_query_fields
+          queries = @aggregate.queries + @aggregate.entities.flat_map(&:queries)
+          queries.flat_map { |query| query.wheres.map(&:field) + [query.order_by&.field] }
+                 .compact.map(&:to_s).uniq
+        end
+
+        # One field name resolves to exactly one of three outcomes:
+        #
+        #   - a plain scalar attribute (or the lifecycle field itself)
+        #     — a real btree index on the column, using `plain_column`'s
+        #     own `quote_ident(name)` phrasing (reached by calling
+        #     `query_expression` itself, not a second copy of its
+        #     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
+        #     `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`
+        #     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
+        #     column (or even an expression index on it) does nothing to
+        #     speed, since neither indexes the elements individually.
+        #     SQLite has no inverted/array index short of FTS5/R-tree,
+        #     and neither fits a `list_of` scalar or value-object field
+        #     — well beyond this plan's scope. Left unindexed
+        #     deliberately, not a silent gap.
+        #
+        # 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
+        # than crashes ugly if that invariant is ever violated.
+        def ensure_index_for_field!(field)
+          name, * = field.to_s.split(".")
+          attribute = @aggregate.attribute(name)
+          lifecycle_field = @aggregate.lifecycle&.field.to_s == name
+
+          return if !lifecycle_field && attribute.nil?
+          return if attribute&.list?
+
+          expression = query_expression(field)
+          @db.execute(
+            "CREATE INDEX IF NOT EXISTS #{quote_ident(index_name(field))} ON #{quoted_table}(#{expression})"
+          )
+        end
+
+        # `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)
+        # to stay a valid identifier while remaining visibly tied to
+        # what it indexes — collision-free across every field/path this
+        # aggregate declares, since `declared_query_fields` already
+        # de-duplicates the field strings themselves.
+        def index_name(field)
+          sanitized = field.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
+          "idx_#{table}_#{sanitized}"
+        end
+      end
+    end
+  end
+end