hecks 0.2.0 → 1.0.0

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,80 @@
+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 }
+          # `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
+          # `save`'s own `columns =`/`values =` build (this file, not
+          # here) silently drops it on every write. No `attribute` of
+          # their own to carry (`ProjectedField` is a bare name/
+          # reference/remote_field triple, not a typed attribute) —
+          # treated as a raw scalar, same as the lifecycle field just
+          # above: every real corpus use projects a status/lifecycle
+          # string, and `encode_field`/`decode` both already pass a
+          # `attribute: nil` field through untouched, not JSON-encoded.
+          @aggregate.projected_fields.each do |field|
+            next if fields.any? { |f| f[:name] == field.name }
+
+            fields << { name: field.name, attribute: nil, sql_type: "TEXT" }
+          end
+          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,172 @@
+require_relative "../../../runtime/instance"
+require_relative "../../../runtime/value"
+require_relative "../../../runtime/errors"
+require_relative "../../../runtime/refusal_wording"
+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
+# 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.
+      #
+      # M19 (docs/audits/2026-08-10-main-bug-audit.md,
+      # docs/audits/2026-08-11-bug-triage.md) — this used to diverge from
+      # `Runtime::ReadModelInterpreter#project` (the in-process path) on
+      # two counts, both fixed here to agree with it:
+      #
+      # 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
+      # against a record that never existed and get back something that
+      # 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
+      # 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
+      # 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
+      # there as L2, not a gap introduced here).
+      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
+
+        # 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.
+        root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
+        projected = []
+        reports = {}
+        (root_heads + other_heads).each do |head|
+          aggregate = bluebook.aggregate(head[:aggregate])
+          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)))]
+                 else
+                   select_related(aggregate, projected)
+                 end
+          rows = Ports::Query::InMemory.execute(rows, model, args) if head[:as] == eligible
+          projected << { aggregate: head[:aggregate], rows: rows }
+          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
+
+      # 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.
+      def select_related(aggregate, projected)
+        matches = projected.flat_map do |source|
+          references = aggregate.attributes.select do |attribute|
+            attribute.reference? && attribute.type.target_name == source[:aggregate].to_s
+          end
+          next [] if references.empty?
+
+          ids = source[:rows].map { |row| row.id.to_s }
+          next [] if ids.empty?
+
+          references.product(ids)
+        end
+        return [] if matches.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 = matches.map { |attribute, _id| "#{quote_ident(attribute.name)} = ?" }
+        bind = matches.map { |_attribute, id| id }
+        @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
+        # `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
+        # consulted it — a column `project` populated correctly, silently
+        # dropped on every read back out. Same raw-passthrough treatment as
+        # the lifecycle field just above: `attribute: nil` down in the loop.
+        aggregate.projected_fields.each do |field|
+          fields << [field.name, nil] unless fields.any? { |name, _| name == field.name }
+        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,192 @@
+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,
+              completed_compensations  TEXT NOT NULL DEFAULT '[]',
+              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 reason Postgres's own `create_saga_table!` needs
+          # its own `ADD COLUMN IF NOT EXISTS`. SQLite/D1's own `ALTER
+          # TABLE ... ADD COLUMN` has no `IF NOT EXISTS` guard on every
+          # version this adapter supports, so a duplicate-column error
+          # is caught and treated as "already there" rather than relied
+          # on to never happen.
+          @db.execute("ALTER TABLE hecks_saga_instances ADD COLUMN completed_compensations TEXT NOT NULL DEFAULT '[]'")
+        rescue StandardError => e
+          raise unless e.message.include?("duplicate column name")
+        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

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

@@ -0,0 +1,9 @@
+Hecks.adapter "SqlitePersistence" do
+  port   "persistence"
+  field  :database
+end
+
+Hecks.adapter "SqliteProjection" do
+  port  "projection"
+  field :database
+end