hecks 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 798ee36082afdda202f54dfb446727e79c38f99a
-  data.tar.gz: 120419fa4fcd0b8f0dc2401fea4482c37e5924e1
+SHA256:
+  metadata.gz: 9d056aad218f4fe26394319c5ce486211ac9790022de8159ba23f050a634f5df
+  data.tar.gz: d6fa0c2f693152be740b0c5f658008a6ba71ae9bd80e175e8da78b142f00f133
 SHA512:
-  metadata.gz: 7f100beec30a025476d12fd3061cdddbf24a1111f8123805c890a4d654b611f59c674364c3fa820be9895cc9a4be4f235b86ad18574fc76c04d14e94e8c08eed
-  data.tar.gz: d2ee8bb2c264169866082e0b176a616ad8bb0fc02bd8c8468a5088faa6ca8acd4bfb70bfabe915f32c817343fc22355f4e2e8128ad165a09880dc95d91ad1b04
+  metadata.gz: 4ae526f5a34b194a9b3d23751fae0bb6bdee1bcd8011653904d2b324bf4478ee7b4049d96f0b2a74d005a810ac7023d6efa5a8d0639fb079ed8691da93a5f217
+  data.tar.gz: c2b1a7be12ebfbd52ad5cb13ddd1aa7693a7d903d1402c580baad40414a7f3318d7263379658debc502492986956f97b5377681ac93cf5cb36e058c3e1ccfb46

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

@@ -0,0 +1,3 @@
+Hecks.adapter "ClaudeCode" do
+  port "agent"
+end

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

@@ -0,0 +1,127 @@
+require "open3"
+require "json"
+require "timeout"
+
+require_relative "../../ports/agent"
+
+module Hecks
+  module Adapters
+    # THE REAL `agent` FULFILLMENT — shells out to the `claude` CLI
+    # itself, `claude -p --output-format json`, one process per call.
+    # `Ports::Agent`'s own scripted double (`spec/fixtures/scripted_
+    # agent.{adapter,rb}`) is the deterministic sibling every spec binds
+    # instead, the same relationship `SecureRandomIdentity` already has
+    # to `SequentialIdentity`.
+    #
+    # THIS FILE OWNS TRANSPORT ONLY — spawning the process, unwrapping
+    # the CLI's own JSON envelope (`{"result": "..."}`) down to the
+    # model's raw text, and parsing THAT text as JSON. It hands back a
+    # plain Hash. Whether that Hash has the keys a caller asked for, and
+    # whether its values are within the closed vocabularies this port
+    # recognizes (a critique's `kind`, a proposal's `verb` pattern) is
+    # `Ports::Agent::Answers`' job, not this file's — see `ports/agent.rb`'s
+    # own header for why that split is load-bearing.
+    #
+    # `Open3.capture2` with an explicit argv array, never a shell string
+    # — the same shape every other subprocess call in this repo already
+    # uses (`bin/rust_conformance`), and the reason `claude` being
+    # shell-aliased to `claude --dangerously-skip-permissions` in a
+    # human's own terminal never reaches this code at all: an argv spawn
+    # invokes the real binary directly, no shell, no alias.
+    #
+    # `--allowedTools ""` — this adapter asks a question and reads back
+    # text; it never wants the model reaching for a tool mid-answer.
+    module ClaudeCode
+      TIMEOUT_SECONDS = 120
+
+      SYSTEM_PREFIX = "You are assisting a domain-modeling interview for the hecks " \
+                      "event-sourced framework. Reply with EXACTLY ONE JSON object, no prose " \
+                      "before or after it, no markdown code fence. "
+
+      module_function
+
+      # THE NEXT BEST QUESTION. `state` is whatever
+      # `Interview::Session#declaration`/`#gaps` produced — passed
+      # through as JSON, not reformatted, so this adapter never
+      # re-derives what the session already knows.
+      def ask(state:, asked:)
+        call(
+          system:  SYSTEM_PREFIX + "Given the domain model so far, ask the single best next " \
+                                   'discovery question. Reply as {"questions": [{"text": "...", "because": "..."}]} ' \
+                                   "with exactly one entry. Never repeat a question already asked.",
+          payload: { state: state, already_asked: asked }
+        )
+      end
+
+      # PROSE -> PROPOSED DECLARATIONS.
+      def interpret(prose:, state:)
+        call(
+          system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
+                                   "propose zero or more declarations that capture what the sentence names as domain " \
+                                   "fact. A verb must be fully qualified as Chapter::Aggregate.Command. Reply as " \
+                                   '{"proposals": [{"verb": "...", "rationale": "...", "arguments": ' \
+                                   '[{"name": "...", "field": "...", "value": "..."}]}]}. If the sentence carries no ' \
+                                   'declaration (a question back, a clarification), reply {"proposals": []}.',
+          payload: { state: state, prose: prose }
+        )
+      end
+
+      # WHAT IS WRONG WITH THIS AS A MODEL — closed to the same kind
+      # vocabulary `Ports::Agent::CRITIQUE_KINDS` declares, spelled out
+      # here too since the system prompt is the only place the model
+      # itself ever sees that list.
+      def critique(declared:, refusals:, findings:)
+        kinds = Ports::Agent::CRITIQUE_KINDS.join(", ")
+        call(
+          system:  SYSTEM_PREFIX + "Given a domain declaration, the refusals it already triggered, and " \
+                                   "the mechanical findings already reported, judge it on TASTE — do not restate what is " \
+                                   "already known. Only use one of these kinds: #{kinds}. Only use severity error or " \
+                                   'warning. Reply as {"findings": [{"kind": "...", "severity": "...", "subject": "...", ' \
+                                   '"message": "..."}]}. Reply {"findings": []} if there is nothing worth saying.',
+          payload: { declared: declared, refusals: refusals, findings: findings }
+        )
+      end
+
+      # VOCABULARY HELP. Named `suggest_name`, not `name` — see
+      # `Ports::Agent#suggest_name`'s own comment for why `name` is
+      # never a safe module-function name here.
+      def suggest_name(meaning:, kind:, near:)
+        call(
+          system:  SYSTEM_PREFIX + "Suggest a name for a #{kind} meaning \"#{meaning}\", distinct from " \
+                                   'the names already in use nearby. Reply as {"names": [{"name": "...", "because": ' \
+                                   '"...", "rejected": ["...", "..."]}]} with exactly one entry.',
+          payload: { meaning: meaning, kind: kind, near: near }
+        )
+      end
+
+      # ── transport ───────────────────────────────────────────────────
+
+      def call(system:, payload:)
+        stdout, status = Timeout.timeout(TIMEOUT_SECONDS) {
+          Open3.capture2(
+            "claude", "-p", "--output-format", "json",
+            "--append-system-prompt", system, "--allowedTools", "",
+            stdin_data: JSON.generate(payload)
+          )
+        }
+        raise Ports::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
+
+        unwrap(stdout)
+      rescue Timeout::Error
+        raise Ports::Agent::Unavailable, "claude did not answer within #{TIMEOUT_SECONDS}s"
+      rescue Errno::ENOENT => e
+        raise Ports::Agent::Unavailable, "claude is not on PATH: #{e.message}"
+      end
+
+      def unwrap(stdout)
+        envelope = JSON.parse(stdout)
+        result = envelope["result"]
+        raise Ports::Agent::ValidationError, "no \"result\" in the claude envelope: #{stdout}" unless result
+
+        JSON.parse(result)
+      rescue JSON::ParserError => e
+        raise Ports::Agent::ValidationError, "claude's reply was not JSON: #{e.message}\n#{stdout}"
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+Hecks.adapter "D1" do
+  port  "persistence"
+  field :account_id
+  field :database_id
+  secret :api_token
+end
+
+# No "D1Projection" declared yet, unlike Sqlite/SqliteProjection —
+# read-model projection support (query_read_model, mirroring
+# sqlite/projection.rb) is real future work, not started here. Declaring
+# the adapter without the class behind it would just be a WiringError trap
+# for whoever binds projected_by("D1Projection") first.

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

@@ -0,0 +1,427 @@
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "sql_query_builder"
+require_relative "sqlite/schema_builder"
+require_relative "sqlite/codec"
+require_relative "sqlite" # for Sqlite::SchemaBuilder/Sqlite::Codec — see the reuse note below
+require_relative "../../ports/persistence/append_only"
+require_relative "../../query_specification/common/null_policy"
+require_relative "../../query_specification/common/order_by"
+require_relative "../../runtime/errors"
+require_relative "../../runtime/event"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # Cloudflare D1 — SQLite, managed, reached over its REST API rather
+    # than a local file. D1 IS SQLite, dialect and all, so this file
+    # reuses Sqlite::SchemaBuilder and Sqlite::Codec UNCHANGED (the DDL
+    # and the column encode/decode) and SqlQueryBuilder's dialect hooks
+    # are copied near-verbatim from sqlite.rb — the only real difference
+    # is the transport (D1::Connection, an HTTP call per query, vs a
+    # persistent local sqlite3 handle). See sqlite.rb's own header
+    # comment: "this file supplies only SQLite's dialect" — true here too.
+    class D1
+      # THE TRANSPORT — mirrors just the slice of SQLite3::Database's own
+      # interface (execute/get_first_row/get_first_value, rows as
+      # column-name-keyed hashes) that Sqlite::SchemaBuilder, Sqlite::Codec,
+      # and this file's own methods already assume. One stateless HTTP call
+      # per execute, not a persistent connection — D1 has no connection to
+      # hold open.
+      class Connection
+        ENDPOINT = "https://api.cloudflare.com/client/v4"
+
+        def initialize(account_id:, database_id:, api_token:)
+          @uri = URI("#{ENDPOINT}/accounts/#{account_id}/d1/database/#{database_id}/query")
+          @api_token = api_token
+        end
+
+        def execute(sql, binds = [])
+          response_results({ sql: sql, params: binds }).first.fetch("results", [])
+        end
+
+        # D1 batches are SQL transactions: statements execute in order and a
+        # failure rolls the entire sequence back. Keep the tuple-shaped local
+        # seam small so adapter code and focused fakes do not need to know the
+        # REST request envelope.
+        # https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
+        def batch(statements)
+          payload = {
+            batch: statements.map do |sql, binds|
+              { sql: sql, params: binds || [] }
+            end
+          }
+          response_results(payload).map { |result| result.fetch("results", []) }
+        end
+
+        private
+
+        def response_results(payload)
+          request = Net::HTTP::Post.new(@uri)
+          request["Authorization"] = "Bearer #{@api_token}"
+          request["Content-Type"] = "application/json"
+          request.body = JSON.generate(payload)
+
+          response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: true) { |http| http.request(request) }
+          body =
+            begin
+              JSON.parse(response.body)
+            rescue JSON::ParserError
+              raise Runtime::WiringError, "D1 query failed: non-JSON response (HTTP #{response.code}): #{response.body}"
+            end
+
+          unless body["success"]
+            messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
+            raise Runtime::WiringError, "D1 query failed: #{messages.empty? ? response.body : messages}"
+          end
+
+          results = body.fetch("result")
+          failed = results.find { |result| result["success"] == false }
+          if failed
+            messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
+            detail =
+              if failed.key?("error")
+                failed["error"]
+              elsif failed.key?("message")
+                failed["message"]
+              else
+                messages
+              end
+            raise Runtime::WiringError, "D1 query failed: #{detail.to_s.empty? ? 'a batched statement failed' : detail}"
+          end
+
+          results
+        end
+
+        public
+
+        def get_first_row(sql, binds = [])
+          execute(sql, binds).first
+        end
+
+        def get_first_value(sql, binds = [])
+          get_first_row(sql, binds)&.values&.first
+        end
+      end
+
+      include SqlQueryBuilder
+      include Sqlite::SchemaBuilder
+      include Sqlite::Codec
+
+      SQL_TYPES = { "Integer" => "INTEGER", "Float" => "REAL" }.freeze
+
+      attr_reader :aggregate
+
+      def persistence_capabilities = [:atomic_put]
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+
+        account_id  = settings.key?(:account_id)  ? settings[:account_id]  : settings["account_id"]
+        database_id = settings.key?(:database_id) ? settings[:database_id] : settings["database_id"]
+        api_token   = settings.key?(:api_token)   ? settings[:api_token]   : settings["api_token"]
+        { "account_id" => account_id, "database_id" => database_id, "api_token" => api_token }.each do |name, value|
+          raise Runtime::WiringError, "D1 needs a #{name.inspect} in its world settings" if value.to_s.empty?
+        end
+
+        @db = Connection.new(account_id: account_id, database_id: database_id, api_token: api_token)
+        # THE OPTIONAL saga-persistence capability's own scoping column
+        # (§2/§4) — D1's domain isolation is by whole-database identity
+        # (one D1 database per domain in practice), so unlike Sqlite's
+        # own per-aggregate-file default, there's no "which file does
+        # this end up in" ambiguity here: every aggregate on D1 within a
+        # domain already shares one database.
+        @domain = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        ).to_s
+
+        # No PRAGMA synchronous here, unlike Sqlite — D1 is a managed
+        # durable service; there is no local fsync policy for a caller to
+        # tune, and the query endpoint has no PRAGMA write-access to it.
+        create_aggregate_table!
+        create_entry_table!
+        ensure_entry_operation_column!
+        ensure_entry_mirrors_column!
+        create_event_table!
+        create_saga_table!
+      end
+
+      def table = @aggregate.storage_name
+
+      def find(id)
+        row = @db.get_first_row("SELECT * FROM #{quoted_table} WHERE id = ?", [id.to_s])
+        return nil unless row
+
+        Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+      end
+
+      # order_by IS A RUNTIME VALUE — see postgres.rb's own all for the
+      # full reasoning; whitelisted the identical way, same order_clause
+      # Sqlite's own all reuses (D1 speaks the identical dialect).
+      def all(order_by: nil, direction: :asc)
+        order_sql = "ORDER BY id"
+        if 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)
+
+          spec = QuerySpecification::Common::OrderBy.new(field: order_by, direction: direction)
+          order_sql = "ORDER BY #{order_clause(spec, nil)}"
+        end
+
+        @db.execute("SELECT * FROM #{quoted_table} #{order_sql}").map do |row|
+          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+        end
+      end
+
+      def count = @db.get_first_value("SELECT COUNT(*) FROM #{quoted_table}").to_i
+
+      def append(entry)
+        @db.execute(
+          "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
+          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # mirrors hash must bind a real SQL NULL, not the four-character
+          # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
+          # check against it would never match. Same guard `postgres_era.rb`
+          # already uses for its own journal's `mirrors` column.
+          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+        )
+        entry
+      end
+
+      def project(entry)
+        return @db.execute("DELETE FROM #{quoted_table} WHERE id = ?", [entry.id]) if entry.delete?
+
+        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |c| quote_ident(c) }
+        values  = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
+        slots   = Array.new(columns.size, "?").join(", ")
+
+        @db.execute(
+          "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{slots})",
+          values
+        )
+        instance
+      end
+
+      def entries
+        @db.execute("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
+          state = JSON.parse(row["state"])
+          Ports::Persistence::Entry.new(
+            operation: row["operation"] || "save",
+            id:        row["aggregate_id"],
+            state:     state&.transform_keys(&:to_sym),
+            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
+          )
+        end
+      end
+
+      def reset!
+        @db.execute("DELETE FROM #{quoted_table}")
+        @db.execute("DELETE FROM #{quoted_entry_table}")
+        self
+      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
+
+      # Classification, durable journal append and current-state projection
+      # are one D1 batch transaction and therefore one HTTP request. The first
+      # statement supplies the outcome from database state inside that same
+      # transaction; the runtime performs no preliminary find.
+      #
+      # `insert_only:` used to spend a SEPARATE, EARLIER round trip finding
+      # out whether the row existed before ever building the batch — a real
+      # TOCTOU gap (two concurrent creates at the same identity could both
+      # pass that check before either wrote). D1's batch has no conditional
+      # BRANCH of its own, true, but it does not need one: a batch's own
+      # statements already execute in order, atomically, as one transaction
+      # (Connection#batch's own comment) — the exact guarantee the single-
+      # connection adapters' own `@db.transaction do ... end` gets locally.
+      # So the existence check moves INSIDE the batch as its own first
+      # statement, and the two writes are individually gated with `WHERE NOT
+      # EXISTS (...)` against that same table, evaluated in the same
+      # transaction — a row that already existed makes both writes into
+      # real, zero-row no-ops rather than skipping them from the Ruby side,
+      # matching Sqlite#atomic_put's `next` (skip append AND project both,
+      # together) with no second HTTP call and no gap for another writer to
+      # land in between the check and the write.
+      def atomic_put(entry, insert_only: false)
+        instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
+        columns = (["id"] + persisted_fields.map { |field| field[:name].to_s }).map { |column| quote_ident(column) }
+        values = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
+        slots = Array.new(columns.size, "?").join(", ")
+        not_exists = "WHERE NOT EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?)"
+
+        status_sql =
+          if insert_only
+            "SELECT CASE WHEN EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?) " \
+              "THEN 'conflicted' ELSE 'inserted' END AS status"
+          else
+            "SELECT CASE WHEN EXISTS (SELECT 1 FROM #{quoted_table} WHERE id = ?) " \
+              "THEN 'replaced' ELSE 'inserted' END AS status"
+          end
+
+        # `mirrors` is NULLABLE (unlike `state`) — see `append`'s own comment.
+        encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
+
+        entry_sql, entry_binds =
+          if insert_only
+            [
+              "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) " \
+              "SELECT ?, ?, ?, ? #{not_exists}",
+              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors, entry.id.to_s]
+            ]
+          else
+            [
+              "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
+              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors]
+            ]
+          end
+
+        aggregate_sql, aggregate_binds =
+          if insert_only
+            [
+              "INSERT INTO #{quoted_table} (#{columns.join(', ')}) SELECT #{slots} #{not_exists}",
+              values + [entry.id.to_s]
+            ]
+          else
+            [
+              "INSERT OR REPLACE INTO #{quoted_table} (#{columns.join(', ')}) VALUES (#{slots})",
+              values
+            ]
+          end
+
+        results = @db.batch([
+                              [status_sql, [entry.id.to_s]],
+                              [entry_sql, entry_binds],
+                              [aggregate_sql, aggregate_binds]
+                            ])
+
+        results.fetch(0).fetch(0).fetch("status").to_sym
+      end
+
+      def delete(id)
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+        true
+      end
+
+      def record_event(event)
+        @db.execute(
+          "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES (?, ?, ?, ?, ?)",
+          [event.name, event.aggregate, event.id.to_s, JSON.generate(event.payload), event.occurred_at]
+        )
+      end
+
+      def events
+        @db.execute("SELECT * FROM events ORDER BY id").map do |row|
+          Runtime::Event.new(
+            name:        row["name"],
+            aggregate:   row["aggregate"],
+            id:          row["aggregate_id"],
+            payload:     JSON.parse(row["payload"], symbolize_names: true),
+            occurred_at: row["occurred_at"]
+          )
+        end
+      end
+
+      # ── the OPTIONAL saga-persistence capability (§2) — reuses the DDL
+      # `Sqlite::SchemaBuilder` already shares with Sqlite (`d1.rb`'s own
+      # file header). Same `?`-placeholder shape every other write here
+      # already uses through `Connection#execute`.
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+        @db.execute(
+          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+          "VALUES (?, ?, ?, ?, ?, ?)",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
+        )
+      end
+
+      def delete_saga(process_manager:, correlation:)
+        @db.execute(
+          "DELETE FROM hecks_saga_instances WHERE domain = ? AND process_manager = ? AND correlation = ?",
+          [@domain, process_manager.to_s, correlation.to_s]
+        )
+      end
+
+      def each_saga
+        return enum_for(:each_saga) unless block_given?
+
+        @db.execute(
+          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = ?",
+          [@domain]
+        ).each do |row|
+          yield row["process_manager"], row["correlation"], row["state"],
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
+        end
+      end
+
+      private
+
+      # ── SqlQueryBuilder's dialect hooks — identical to Sqlite's, since
+      # D1 speaks the same dialect (copied, not shared by module include,
+      # because Sqlite's own copies are private instance methods on a
+      # different class — see the file header) ───────────────────────
+      def select_list = "*"
+      def from_relation = quoted_table
+      def dialect_name = "D1"
+      def empty_in_clause = "0"
+
+      def placeholder(binds, value)
+        binds << value
+        "?"
+      end
+
+      def contains_clause(expression, placeholder)
+        "instr(#{expression}, #{placeholder}) > 0"
+      end
+
+      def list_contains_clause(column, member, placeholder)
+        target = member.empty? ? "json_each.value" : "json_extract(json_each.value, '$.#{member}')"
+        "EXISTS (SELECT 1 FROM json_each(#{quote_ident(column)}) WHERE #{target} = #{placeholder})"
+      end
+
+      def plain_column(name) = quote_ident(name)
+
+      def nested_expression(name, path, member)
+        json_path = path.empty? ? "$.#{member || 'value'}" : "$.#{path.join('.')}"
+        "json_extract(#{quote_ident(name)}, '#{json_path}')"
+      end
+
+      # SQLite (and D1, the same engine) has no bare OFFSET — LIMIT -1 is
+      # its own documented unbounded spelling, exactly for this case.
+      def unbounded_limit = " LIMIT -1"
+
+      def order_clause(order_by, policy)
+        QuerySpecification::Common::NullPolicy.sql_order(query_expression(order_by.field), order_by.direction, policy)
+      end
+
+      def execute_query(sql, binds)
+        @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+      end
+
+      # ── the rest of the dialect ─────────────────────────────────────
+
+      def quote_ident(name)
+        %("#{name.to_s.gsub('"', '""')}")
+      end
+
+      def quoted_table = quote_ident(table)
+      def entry_table = "#{table}_entries"
+      def quoted_entry_table = quote_ident(entry_table)
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+Hecks.adapter "Folder" do
+  port "loading"
+end