hecks 0.2.0 → 0.3.0

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

@@ -0,0 +1,51 @@
+require_relative "../../ports/query/in_memory"
+require_relative "../../ports/query/ordering"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../query_specification/field_path"
+require_relative "../../runtime/errors"
+
+module Hecks
+  module Adapters
+    # SHARED BY every adapter that holds decoded Ruby records rather than
+    # running real SQL (Memory, Lambda, Heki) — the identical dotted-path
+    # value-object member-picking Postgres/Sqlite/D1's own
+    # order_expression does (numeric member wins, else the one-field
+    # convention "value"), just walked in Ruby instead of compiled to a
+    # JSONB/json_extract path, because there is no query engine
+    # underneath any of these three to hide that walk inside.
+    module InMemoryOrdering
+      module_function
+
+      # order_by IS A RUNTIME VALUE (an HTTP query param, in the
+      # console's case), not framework-authored bluebook source — see
+      # postgres.rb's own all for the full reasoning. Whitelisted the
+      # identical way before FieldPath.dig ever runs.
+      def ordered(records, aggregate:, order_by:, direction:)
+        return records unless order_by
+
+        name = order_by.to_s.split(".").first
+        raise Runtime::WiringError, "#{aggregate.name} has no attribute #{order_by.inspect} to order by" unless aggregate.lifecycle&.field.to_s == name || aggregate.attribute(name)
+
+        path = sortable_path(aggregate, order_by)
+        spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
+        Ports::Query::Ordering.apply(records, spec, nil, identity: ->(record) { record.id.to_s }) do |record|
+          Ports::Query::InMemory.comparable(QuerySpecification::FieldPath.dig(record, path))
+        end
+      end
+
+      def sortable_path(aggregate, field)
+        name, *path = field.to_s.split(".")
+        return field.to_s unless path.empty?
+
+        attribute = aggregate.attribute(name)
+        return field.to_s if aggregate.lifecycle&.field.to_s == name || attribute.nil?
+
+        vo = aggregate.value_object(attribute.type)
+        return field.to_s unless vo
+
+        member = vo.attributes.find { |a| %w[Integer Float].include?(a.type) }&.name || "value"
+        "#{name}.#{member}"
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/lambda/client.rb

@@ -0,0 +1,63 @@
+require "json"
+
+module Hecks
+  module Adapters
+    class Lambda
+      # THE THIN AWS CLIENT — shared by this adapter's own read methods
+      # (Lambda#find/#all/#count/#query) and Runtime::RemoteDispatcher's
+      # write methods. One Lambda invoke, one JSON round trip, nothing
+      # domain-specific: neither caller needs to know an AWS SDK is
+      # involved at all.
+      #
+      # FUNCTION NAME IS COMPUTED, NOT PASSED — `"hecks-#{domain}"`,
+      # lowercased, matches bin/project_deploy's own `stack_name`
+      # exactly (bin/project_deploy: `stack_name = "hecks-#{domain_name}"`,
+      # `domain_name = File.basename(domain)`). `domain` here is the
+      # bluebook's OWN declared name (`Embryonaut`, not the directory);
+      # today's real corpus has directory name == declared name
+      # lowercased for every domain that deploys, so `.downcase` alone
+      # reproduces the same string bin/project_deploy computes from the
+      # directory — this is a real, load-bearing assumption, not a
+      # coincidence to lean on silently forever if that ever stops
+      # holding.
+      class Client
+        def initialize(domain:, region:)
+          require "aws-sdk-lambda"
+          @function_name = "hecks-#{domain.to_s.downcase}"
+          @client = Aws::Lambda::Client.new(region: region)
+        end
+
+        # THE WHOLE DOMAIN, EVERY TIME — matches dispatch::read's own
+        # rehydrate-the-full-journal design (Phase 1, rust/host). No
+        # caching here, deliberately not even per-request: Lambda#all
+        # used to memoize this across calls, which silently served
+        # stale reads for a warm web process's whole lifetime once a
+        # write happened elsewhere — see Lambda#instances's own comment
+        # on the real, live bug that caught it.
+        def read
+          invoke({ "read" => true })
+        end
+
+        def dispatch(verb, args, role: nil)
+          payload = { "verb" => verb, "args" => args }
+          payload["role"] = role if role
+          invoke(payload)
+        end
+
+        private
+
+        def invoke(payload)
+          response = @client.invoke(function_name: @function_name, payload: JSON.generate(payload))
+          body = JSON.parse(response.payload.read)
+
+          if response.function_error
+            raise Runtime::WiringError,
+                  "Lambda #{@function_name} (#{response.function_error}): #{body['errorMessage'] || body}"
+          end
+
+          body
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+Hecks.adapter "Lambda" do
+  port "persistence"
+  field :region
+end

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

@@ -0,0 +1,131 @@
+require_relative "lambda/client"
+require_relative "../../ports/query/in_memory"
+require_relative "../../ports/persistence/remote_runtime"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # THE READ-SIDE HALF OF LAMBDA ROUTING — `persisted_by("Lambda")`'s
+    # own adapter, resolved through the SAME `Ports::Persistence`
+    # machinery `persisted_by("Postgres")`/`persisted_by("Memory")`
+    # already use (`Runtime::Registry#repository`, `RepositoryFactory
+    # .build`) — no new framework plumbing, just a new adapter class at
+    # the name the existing lookup already expects. See
+    # `Runtime::RemoteDispatcher` for the write-side half; the two
+    # compose through one shared `Client` per domain rather than each
+    # inventing its own AWS wiring.
+    #
+    # READ-ONLY, DELIBERATELY — `append`/`project` raise rather than
+    # silently no-op. A write reaching this class would mean
+    # `Runtime::CommandInterpreter` ran locally against a Lambda-routed
+    # domain, which is exactly the bypass `Runtime::RemoteDispatcher`
+    # exists to prevent (business-rule validation must happen in Rust
+    # for these domains, not be pre-computed here against an
+    # incomplete local view). A loud failure here is the correct
+    # outcome, not a bug to route around.
+    class Lambda
+      include Ports::Persistence::RemoteRuntime
+
+      attr_reader :aggregate
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        domain = settings[:domain] || settings["domain"] || aggregate.name
+        region = settings[:region] || settings["region"] || "us-east-1"
+        # TWO DIFFERENT "domain"s, deliberately not conflated: `domain`
+        # (this aggregate's OWN bluebook name — "Identity", "Governance")
+        # only ever prefixes the instances lookup, since that's how
+        # rust/host's own `Store::instances()` keys every record
+        # (`registry.rb`'s own `"#{a[:domain_name]}::#{a[:name]}#"`
+        # dump format, unchanged by which chapter attached it). The
+        # FUNCTION to actually call is a different question: Governance
+        # and Identity aggregates are compiled into the ATTACHING
+        # domain's own Lambda (one merged `Store` per target — Phase 0's
+        # framework-bluebook work), never a function of their own, so
+        # `settings[:domain]` is the wrong signal for `Client.new`.
+        # `root` is the boot's own directory (`Registry#root`, shared by
+        # EVERY bluebook in one registry regardless of which one
+        # attached it) — `File.basename(root)` reproduces the exact
+        # same string `bin/project_deploy`'s own `stack_name` computes
+        # from the domain PATH, so the two can never name two
+        # different functions for the same deploy... on a LOCAL boot,
+        # where `root` is a real project directory. Inside the deployed
+        # Lambda itself `root` is ALWAYS `/var/task` (every Lambda's own
+        # fixed code root, regardless of domain) — `File.basename` gives
+        # "task", not the domain name, and invokes the wrong function
+        # entirely. A real, live AccessDeniedException on
+        # "hecks-task" caught this: invisible through every earlier
+        # phase's own verify step, all run from a local boot, until
+        # WebFunction became the first Ruby process to EVER make this
+        # exact call from inside a deployed Lambda. `DOMAIN_NAME` (set
+        # by bin/project_deploy's own WebFunction Environment) is the
+        # real, unambiguous signal in that specific context; the
+        # root-basename heuristic stays as the local-boot fallback,
+        # unchanged.
+        function_domain = ENV["DOMAIN_NAME"] || (root ? File.basename(root) : domain)
+        @client = Client.new(domain: function_domain, region: region)
+        @prefix = "#{domain}::#{aggregate.hecks_name}#"
+      end
+
+      def find(id)
+        instances[id.to_s]
+      end
+
+      def all(order_by: nil, direction: :asc)
+        InMemoryOrdering.ordered(instances.values, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def count = instances.size
+
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(instances.values, specification, args)
+      end
+
+      # `entries`/`append`/`project` — the append-only contract
+      # `Ports::Persistence::AppendOnly` requires of every adapter
+      # (raises at construction if any are missing). Answered by
+      # `Ports::Persistence::RemoteRuntime`, included above: `entries` is
+      # `[]` unconditionally (Lambda's own Postgres is already the
+      # durable store — rust/host's rehydrate-and-replay journal, Phase
+      # 1 — there is no local write-ahead log for `recover!` to replay),
+      # `append`/`project` raise rather than silently no-op.
+
+      private
+
+      # RE-FETCHED EVERY CALL, deliberately NOT memoized across them —
+      # this adapter itself is long-lived (one instance per aggregate,
+      # held by the registry `RUNTIME = Hecks.boot(...)` builds ONCE
+      # per Lambda web process — WebFunction's own top-level constant,
+      # reused warm across every HTTP request that process serves, not
+      # rebuilt per request the way a memoize-for-one-request comment
+      # here used to assume). A real, live bug caught this: a mutation
+      # dispatched fine (RemoteDispatcher always calls the dispatch
+      # Lambda fresh) and the very next `.all` on the SAME warm
+      # container kept returning the state from BEFORE that mutation,
+      # forever, until the container cold-started — memoizing here
+      # made every write invisible to every read on a warm container.
+      # Keyed by bare id (the part after "Domain::Aggregate#"), not the
+      # full "Domain::Aggregate#id" string — callers already know which
+      # aggregate they're asking this instance about.
+      def instances
+        @client.read.fetch("instances", {}).filter_map { |key, state|
+          next unless key.start_with?(@prefix)
+
+          [key.delete_prefix(@prefix), build_instance(key.delete_prefix(@prefix), state)]
+        }.to_h
+      end
+
+      # Lambda's own JSON response is already Ruby-decoded with STRING
+      # keys (plain `JSON.parse`, no `symbolize_names:`) — every other
+      # adapter's own `instance(row)` builder (Postgres, Sqlite) hands
+      # `Runtime::Instance.new` a SYMBOL-keyed state hash instead. A
+      # round trip through `JSON.generate`/`JSON.parse` is simpler and
+      # safer than a hand-rolled deep-symbolize helper for what is not
+      # a hot path.
+      def build_instance(id, state)
+        Runtime::Instance.new(aggregate: @aggregate, id: id, state: JSON.parse(JSON.generate(state), symbolize_names: true))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+Hecks.adapter "Memory" do
+  port   "persistence"
+end

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

@@ -0,0 +1,103 @@
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/query/in_memory"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    class Memory
+      # TENANT-CAPABLE TRIVIALLY — see Runtime::TenantCheck's own header
+      # for the full reasoning. `@records` is a plain instance variable;
+      # two `Runtime.boot` calls build two entirely separate Registry
+      # objects and, through them, two entirely separate Memory
+      # instances, so two tenant boots never share this adapter's state
+      # by construction — nothing here needs to know "tenant" exists.
+      def self.tenant_capable? = true
+      def persistence_capabilities = [:atomic_put]
+
+      attr_reader :aggregate
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        @records   = {}
+        @events    = []
+        @entries   = []
+      end
+
+      def find(id) = @records[id.to_s]
+      def count    = @records.size
+
+      def all(order_by: nil, direction: :asc)
+        InMemoryOrdering.ordered(@records.values, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
+      end
+
+      def append(entry)
+        @entries << entry
+        entry
+      end
+
+      def project(entry)
+        if entry.save?
+          @records[entry.id] = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state.dup)
+        else
+          @records.delete(entry.id)
+        end
+      end
+
+      def save(instance)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        append(entry)
+        project(entry)
+      end
+
+      # One in-memory critical section in the only thread touching this plain
+      # Hash: classify and replace without a preliminary repository lookup.
+      # Durable append and projection remain ordered exactly as ordinary save.
+      def atomic_put(entry, insert_only: false)
+        exists = @records.key?(entry.id.to_s)
+        return :conflicted if insert_only && exists
+
+        status = exists ? :replaced : :inserted
+        append(entry)
+        project(entry)
+        status
+      end
+
+      def delete(id)
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+      end
+
+      def record_event(event) = @events << event
+
+      def events = @events
+
+      def entries = @entries.dup
+
+      # Every other driven adapter (Postgres/PostgresEra/Sqlite/D1)
+      # already implements this — `Ports::Persistence::AppendOnly#reset!`
+      # forwards to it and only raises when the wrapped adapter doesn't
+      # respond to `reset!` at all, which was always this adapter's own
+      # gap, not a deliberate omission (nothing about "in memory" implies
+      # "cannot be cleared"). Existing callers that fully re-`Hecks.boot`
+      # a domain per test case don't need this — they get a brand new
+      # `Memory` instance, with brand new empty `@records`/`@events`/
+      # `@entries`, for free. This is for the other case: a caller that
+      # deliberately keeps ONE booted runtime across many cases (to skip
+      # `load_domain`'s own per-boot parse/verify cost) and wants each
+      # case to start from the same clean slate `Hecks.boot` would have
+      # given it, without paying for a fresh boot to get there.
+      def reset!
+        @records = {}
+        @events  = []
+        @entries = []
+        self
+      end
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+Hecks.adapter "MockStripeAdapter" do
+  port "checkout"
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Adapters
+    # A GENERIC STAND-IN for a real Checkout-Session-style adapter — no
+    # network call, no real account, matching whatever real payment
+    # adapter a project pairs it with by shape alone
+    # (`create_session(event:, registration_id:, success_url:, cancel_url:)
+    # -> a URL string`), the same way `Memory` stands in for a real
+    # persistence adapter without knowing anything about the domain bound
+    # to it. Never reads `event`'s own fields — a real adapter needs the
+    # price/name inside it to build a session a payer actually sees;
+    # this only needs to look enough like one to swap in.
+    #
+    # The URL it returns carries the same `registration_id` a real
+    # webhook's metadata would, so a caller building its own signed
+    # webhook against it (a smoke test, CI) has something real to key
+    # off of — the real shape production has, minus the network hop.
+    class MockStripeAdapter
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      def create_session(event:, registration_id:, success_url:, cancel_url:)
+        separator = success_url.include?("?") ? "&" : "?"
+        "#{success_url}#{separator}mock_checkout=1&mock_registration_id=#{registration_id}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+require_relative "../../../runtime/value"
+
+module Hecks
+  module Adapters
+    class Postgres
+      # How a state crosses the column boundary: which fields persist, and
+      # how each one encodes into (and decodes out of) its column. Same
+      # SHAPE as Sqlite::Codec (one column per attribute, JSON for
+      # nested/list) — not its mechanics. Sqlite's own columns carry no
+      # type affinity worth trusting on the way back out (SQLite gives it
+      # back typed anyway via the driver), but `pg` hands every column
+      # back as TEXT unless a type map says otherwise, so a real `bigint`/
+      # `double precision` column needs its OWN coercion on decode that
+      # Sqlite never had to write.
+      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 — same reasoning as Sqlite::Codec's own
+          # comment: a list attribute nothing has ever appended to has to
+          # stay NULL to answer the same as Memory does, not become `[]`
+          # invented by this adapter's own storage.
+          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
+                coerce_scalar(attr, raw)
+              end
+          end
+        end
+
+        # `pg` returns every column as a Ruby String by default (no type
+        # map installed) — a `bigint`/`double precision` column has to be
+        # coerced back on the way out, unlike Sqlite3's own driver, which
+        # already types a row by the column's declared affinity. Mirrors
+        # SQL_TYPES' own mapping: whatever gets a real numeric column here
+        # gets converted back here, everything else (String, references,
+        # enums, ...) passes through as the text it already is.
+        def coerce_scalar(attr, raw)
+          return nil if raw.nil?
+
+          case attr.type
+          when "Integer" then raw.to_i
+          when "Float"   then raw.to_f
+          else raw
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+require "digest"
+
+module Hecks
+  module Adapters
+    class Postgres
+      # The DDL: one table per aggregate, a real column per attribute (a
+      # jsonb column per nested/list attribute), an append-only entry
+      # table beside it, the shared events/saga tables — and the automatic
+      # indexing this adapter carries that `PostgresEra` does not (see
+      # docs/implemented/postgres-era-adapter-split-plan.md, governing principle 3:
+      # every field a declared query filters or sorts on is safe to index
+      # directly here, since there is no `head_view` reduction to route
+      # around the way `PostgresEra`'s own cache-table story exists for).
+      module SchemaBuilder
+        private
+
+        def create_aggregate_table!
+          columns = persisted_fields.map { |field| "#{quote_ident(field[:name])} #{field[:sql_type]}" }
+          @db.exec(
+            "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
+          )
+          # RIGHT HERE, NOT A SEPARATE STEP IN `Postgres#initialize` —
+          # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
+          # uses: index creation runs unconditionally, right after the
+          # table it indexes exists, the same self-healing shape
+          # `ensure_head_snapshot!`/`ensure_first_head!` already use on
+          # `PostgresEra`'s side.
+          ensure_indexes!
+        end
+
+        def create_entry_table!
+          @db.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS #{quoted_entry_table} (
+              sequence     bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+              aggregate_id text NOT NULL,
+              operation    text NOT NULL DEFAULT 'save',
+              state        jsonb NOT NULL,
+              mirrors      jsonb
+            )
+          SQL
+        end
+
+        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
+        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
+        def create_event_table!
+          @db.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS events (
+              id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+              name         text NOT NULL,
+              aggregate    text NOT NULL,
+              aggregate_id text NOT NULL,
+              payload      jsonb,
+              occurred_at  text
+            )
+          SQL
+        end
+
+        # Same DDL as `PostgresEra`'s own — not lineage-specific, copied
+        # verbatim (see docs/implemented/postgres-era-adapter-split-plan.md).
+        def create_saga_table!
+          @db.exec(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_saga_instances (
+              domain          text NOT NULL,
+              process_manager text NOT NULL,
+              correlation     text NOT NULL,
+              state           text NOT NULL,
+              memory          jsonb NOT NULL,
+              updated_at      timestamptz NOT NULL DEFAULT now(),
+              PRIMARY KEY (domain, process_manager, correlation)
+            )
+          SQL
+        end
+
+        def sql_type(attr)
+          return "jsonb" if attr.list? || value_object?(attr)
+
+          SQL_TYPES.fetch(attr.type, "text")
+        end
+
+        # ── automatic indexing ───────────────────────────────────────
+        #
+        # Derived from every declared query's `where`/`order_by` fields —
+        # no bluebook author opts in, matching every other self-healing
+        # schema move this adapter makes. Walks the aggregate's own
+        # queries AND each entity's own queries — the same enumeration
+        # `dsl/aggregate_builder.rb`'s own `query_surfaces` walks at
+        # declaration-seal time — but an entity's own fields never
+        # produce an index below: an entity has no table of its own, its
+        # rows live inside a LIST-typed attribute on the AGGREGATE's own
+        # table (`QueryInterpreter#entity_rows` resolves it that way, and
+        # answers an entity query entirely in memory over `repository.all`
+        # — it never reaches this adapter's own `query` method at all).
+        # Every list-typed attribute is excluded below regardless (see
+        # `index_field!`), so an entity's own field would always resolve
+        # to "skip" anyway. Walked explicitly rather than silently
+        # dropped, so a reader can see entities were considered here, not
+        # forgotten.
+        def ensure_indexes!
+          query_surfaces.each do |owner, queries|
+            next unless owner.equal?(@aggregate)
+
+            queries.each { |query| index_query!(query) }
+          end
+        end
+
+        def query_surfaces
+          [[@aggregate, @aggregate.queries]] +
+            @aggregate.entities.map { |entity| [entity, entity.queries] }
+        end
+
+        def index_query!(query)
+          query.wheres.each { |clause| index_field!(clause.field) }
+          index_field!(query.order_by.field) if query.order_by
+        end
+
+        # A `list_of` attribute is never indexed here — this adapter's
+        # own `contains` on a list field compiles to `EXISTS (SELECT 1
+        # FROM jsonb_array_elements(...) ...)` (see `list_contains_clause`
+        # below), a SQL shape neither a plain btree on the raw jsonb
+        # column nor even a GIN jsonb index (`@>`, `?`) accelerates —
+        # Postgres's own GIN jsonb operators match a DIFFERENT SQL shape
+        # than the `EXISTS` + `jsonb_array_elements` this codebase always
+        # compiles a list `contains` to. An index here would be dead
+        # weight, not free correctness, so none is attempted.
+        def index_field!(field)
+          name, *_path = field.to_s.split(".")
+          attribute = @aggregate.attribute(name)
+          return if attribute&.list?
+
+          # THE SAME EXPRESSION THE QUERY ITSELF COMPILES TO — calling
+          # `query_expression`/`plain_column`, the real dialect methods,
+          # rather than a second, hand-rolled derivation of the same
+          # path that could silently drift from it. An index whose
+          # expression doesn't match the planner's own candidate
+          # expression byte-for-byte is invisible to the planner,
+          # created or not.
+          expression = query_expression(field.to_s)
+          if expression == plain_column(name)
+            create_plain_index!(name)
+          else
+            create_expression_index!(expression, field.to_s)
+          end
+        end
+
+        def create_plain_index!(column)
+          name = index_name(column.to_s)
+          @db.exec("CREATE INDEX IF NOT EXISTS #{quote_ident(name)} ON #{quoted_table} (#{quote_ident(column)})")
+        end
+
+        def create_expression_index!(expression, field)
+          name = index_name(field)
+          @db.exec("CREATE INDEX IF NOT EXISTS #{quote_ident(name)} ON #{quoted_table} ((#{expression}))")
+        end
+
+        # Postgres identifiers cap at 63 bytes. Hashing TABLE + FIELD
+        # together keeps every generated index name well under that no
+        # matter how long an aggregate or attribute name gets, and keeps
+        # two distinct fields — on the same table or different ones —
+        # from ever colliding, or truncating into the same name the way
+        # a naive `"idx_#{table}_#{field}"` could once either got long
+        # enough.
+        def index_name(field)
+          "hecks_idx_#{Digest::SHA256.hexdigest("#{table}:#{field}")[0, 40]}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+Hecks.adapter "Postgres" do
+  port  "persistence"
+  field :database
+  field :schema
+end