hecks 2.8.0 → 2.9.0

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

@@ -1,9 +1,7 @@
 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.
+      # DDL for one aggregate: head table, entry table, events, saga and outbox tables.
       module SchemaBuilder
         private
 
@@ -12,15 +10,7 @@ module Hecks
           @db.execute(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id TEXT PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
-          # Right here, not as a separate step in `Sqlite#initialize` —
-          # `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.
+          # Called here so D1, which reuses this module, gets automatic indexing too.
           ensure_indexes!
         end
 
@@ -35,6 +25,10 @@ module Hecks
               occurred_at  TEXT
             )
           SQL
+          # Backs #events_for's per-record lookup (a `corrects` command's history read).
+          @db.execute(
+            "CREATE INDEX IF NOT EXISTS hecks_events_aggregate_id_idx ON events (aggregate, aggregate_id)"
+          )
         end
 
         def create_entry_table!
@@ -63,14 +57,8 @@ module Hecks
           @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.
+        # Shared with D1, which includes this module. `domain` is an explicit column so
+        # two domains can share one database file.
         def create_saga_table!
           @db.execute(<<~SQL)
             CREATE TABLE IF NOT EXISTS hecks_saga_instances (
@@ -83,14 +71,8 @@ module Hecks
               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.
+          # The table may predate this column, and SQLite lacks ADD COLUMN IF NOT EXISTS,
+          # so a duplicate-column error is treated as already applied.
           @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")
@@ -118,27 +100,36 @@ module Hecks
           @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
         end
 
+        # One row per aggregate table, naming the highest entry `sequence` this table has
+        # already had projected into it — shared across every aggregate in the database file,
+        # since it is keyed by table name rather than declared per aggregate.
+        def create_checkpoint_table!
+          @db.execute(<<~SQL)
+            CREATE TABLE IF NOT EXISTS hecks_checkpoints (
+              aggregate_table TEXT PRIMARY KEY,
+              last_sequence   INTEGER NOT NULL DEFAULT 0
+            )
+          SQL
+          ensure_checkpoint_compacted_through_column!
+        end
+
+        # CREATE TABLE IF NOT EXISTS never adds a column to an existing table, so this healing
+        # step matches ensure_entry_operation_column!'s own for the entry table.
+        def ensure_checkpoint_compacted_through_column!
+          columns = @db.execute("PRAGMA table_info(hecks_checkpoints)").map { |row| row["name"] }
+          return if columns.include?("compacted_through")
+
+          @db.execute("ALTER TABLE hecks_checkpoints ADD COLUMN compacted_through INTEGER NOT NULL DEFAULT 0")
+        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."
+        # Indexes every field a declared query filters or sorts on, entity queries included
+        # (they compile against this table too). Idempotent, so it is safe on every boot.
         def ensure_indexes!
           declared_query_fields.each { |field| ensure_index_for_field!(field) }
         end
@@ -149,38 +140,10 @@ module Hecks
                  .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.
+        # A scalar or lifecycle field gets a btree index; a value-object path gets an expression
+        # index over `query_expression`'s own text, so the planner matches what queries compile to.
+        # List fields are left unindexed: SQLite cannot index json_each elements.
+        # Unknown fields are skipped rather than raised, since the DSL already refuses them.
         def ensure_index_for_field!(field)
           name, * = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
@@ -195,15 +158,8 @@ module Hecks
           )
         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.
+        # Table-prefixed because SQLite index names are global to the database.
+        # The field is sanitized (a dotted path's ".") to stay a valid identifier.
         def index_name(field)
           sanitized = field.to_s.gsub(/[^a-zA-Z0-9_]/, "_")
           "idx_#{table}_#{sanitized}"

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

@@ -14,10 +14,8 @@ require_relative "../../runtime/instance"
 
 module Hecks
   module Adapters
-    # The SQLite store: one table per aggregate head, an append-only entry
-    # table beside it. The DDL lives in sqlite/schema_builder.rb, the
-    # column codec in sqlite/codec.rb, and the query compilation is the
-    # shared SqlQueryBuilder — this file supplies only SQLite's dialect.
+    # The SQLite store: one table per aggregate head, an append-only entry table beside it.
+    # Supplies SQLite's dialect to the shared SqlQueryBuilder.
     class Sqlite
       include SqlQueryBuilder
       include SchemaBuilder
@@ -44,18 +42,13 @@ module Hecks
       # @raise [LoadError] if the `sqlite3` gem is not installed
       # @raise [SQLite3::Exception] if the file cannot be opened or a table cannot be created
       def initialize(aggregate:, settings: {}, root: nil)
-        # **Lazy, on purpose** — a domain that never wires Sqlite should never
-        # need the gem installed. `require "hecks"` alone must not
-        # force a database client library nobody asked for.
+        # Lazy so a domain that never wires Sqlite does not need the gem installed.
         require "sqlite3"
 
         @aggregate = aggregate
         @path      = resolve_path(settings, root)
-        # The optional saga-persistence capability's own scoping column
-        # (§2/§4) — falls back to the aggregate's own name for a
-        # directly-instantiated adapter (specs), same fallback shape
-        # Postgres's own @domain already uses.
-        @domain    = (
+        # Scopes saga rows; falls back to the aggregate's name for a directly built adapter.
+        @domain = (
           if settings.key?(:domain)
             settings[:domain]
           elsif settings.key?("domain")
@@ -68,8 +61,7 @@ module Hecks
         FileUtils.mkdir_p(File.dirname(@path))
         @db = SQLite3::Database.new(@path)
         @db.results_as_hash = true
-        # The append is the recovery commit point. Keep SQLite's fsync policy
-        # explicit instead of inheriting a process-wide pragma choice.
+        # The append is the recovery commit point, so the fsync policy is explicit.
         @db.execute("PRAGMA synchronous = FULL")
 
         create_aggregate_table!
@@ -79,14 +71,13 @@ module Hecks
         create_event_table!
         create_saga_table!
         create_outbox_table!
+        create_checkpoint_table!
       end
 
       # Runs the block inside one SQLite transaction, joining an already-open one.
       #
-      # **Re-entrant on purpose** — `atomic_put` opens its own transaction
-      # and `Interpreting#run_dispatch_order` opens one around the whole
-      # save+emit pair; SQLite3 refuses a BEGIN inside a BEGIN, so the
-      # inner call joins the outer one instead. Same shape Postgres uses.
+      # Re-entrant because `atomic_put` and `Interpreting#run_dispatch_order` both open one,
+      # and SQLite3 refuses a BEGIN inside a BEGIN.
       #
       # @yield the writes to commit together; an exception raised inside rolls the
       #   outermost transaction back
@@ -117,9 +108,7 @@ module Hecks
 
       # Lists every stored record, ordered by id unless an ordering attribute is given.
       #
-      # order_by is a runtime value — see postgres.rb's own all for the
-      # full reasoning; whitelisted the identical way before it ever
-      # reaches order_expression.
+      # order_by is a runtime value, so it is checked against the aggregate before use.
       #
       # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
       #   by; nil orders by id alone
@@ -154,21 +143,21 @@ module Hecks
 
       # Inserts one journal row, outside any transaction of its own.
       #
+      # Stamps the row's assigned `sequence` onto `entry` in place, so a `project` call right
+      # after (same object, same transaction) can advance the checkpoint with no extra query.
+      #
       # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state` is
       #   encoded through the state codec and `mirrors` stored as JSON, or NULL when nil
-      # @return [Ports::Persistence::Entry] the same `entry`
+      # @return [Ports::Persistence::Entry] the same `entry`, `sequence` now set
       # @raise [SQLite3::Exception] if the insert fails
       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.
+          # `mirrors` is nullable: an absent hash must bind SQL NULL, not the JSON text "null".
           [entry.id, entry.operation, JSON.generate(Ports::Persistence::StateCodec.encode(@aggregate, entry.state)),
            entry.mirrors && JSON.generate(entry.mirrors)]
         )
+        entry.sequence = @db.last_insert_row_id
         entry
       end
 
@@ -179,6 +168,7 @@ module Hecks
       #   for a delete, the `DELETE` statement's empty result rows
       # @raise [SQLite3::Exception] if the statement fails
       def project(entry)
+        advance_checkpoint!(entry.sequence) if entry.sequence
         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)
@@ -201,15 +191,65 @@ module Hecks
       # @raise [SQLite3::Exception] if the statement fails
       # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
       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:     Ports::Persistence::StateCodec.decode(@aggregate, state),
-            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
-          )
-        end
+        entries_matching(
+          "SELECT aggregate_id, operation, state, mirrors, sequence FROM #{quoted_entry_table} ORDER BY sequence"
+        )
+      end
+
+      # Reads only the journal rows past a given `sequence`, for `AppendOnly#recover!` to replay
+      # after a checkpoint instead of the whole journal.
+      #
+      # @param sequence [Integer] the highest `sequence` already projected; rows at or below it
+      #   are skipped
+      # @return [Array<Ports::Persistence::Entry>] the journalled entries past `sequence`, in
+      #   append order, decoded exactly as `entries` decodes them; `[]` when none are newer
+      # @raise [SQLite3::Exception] if the statement fails
+      # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
+      def entries_since(sequence)
+        entries_matching(
+          "SELECT aggregate_id, operation, state, mirrors, sequence FROM #{quoted_entry_table} " \
+          "WHERE sequence > ? ORDER BY sequence",
+          [sequence]
+        )
+      end
+
+      # Reads the highest journal `sequence` this table has already had projected into it.
+      #
+      # @return [Integer] `0` when the table has never been checkpointed (a fresh table, or one
+      #   from before this bookkeeping existed) — `entries_since(0)` then reads the whole journal,
+      #   matching `entries`' own full replay
+      # @raise [SQLite3::Exception] if the statement fails
+      def checkpoint
+        @db.get_first_value("SELECT last_sequence FROM hecks_checkpoints WHERE aggregate_table = ?", [table]).to_i
+      end
+
+      # Reads the highest journal `sequence` compaction has already deleted from this table.
+      #
+      # @return [Integer] `0` when nothing has ever been compacted
+      # @raise [SQLite3::Exception] if the statement fails
+      def compacted_through
+        @db.get_first_value("SELECT compacted_through FROM hecks_checkpoints WHERE aggregate_table = ?", [table]).to_i
+      end
+
+      # Deletes every journal row at or before `through` and records it, so a `:strict`
+      # projection catch-up can tell whether it still has the history it needs.
+      #
+      # Never moves `compacted_through` backwards, and never touches the aggregate's own
+      # table — only the journal, which a `:refresh` projection rebuild never needs.
+      #
+      # @param through [Integer] the highest `sequence` to delete
+      # @return [Integer] the number of journal rows deleted
+      # @raise [SQLite3::Exception] if a statement fails
+      def compact_entries!(through:)
+        @db.execute("DELETE FROM #{quoted_entry_table} WHERE sequence <= ?", [through])
+        removed = @db.changes
+        @db.execute(
+          "INSERT INTO hecks_checkpoints (aggregate_table, compacted_through) VALUES (?, ?) " \
+          "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+          "compacted_through = MAX(compacted_through, excluded.compacted_through)",
+          [table, through]
+        )
+        removed
       end
 
       # Deletes every row of the aggregate's table and its journal; events, saga rows and
@@ -238,9 +278,7 @@ module Hecks
 
       # Stores an entry and reports whether it inserted, replaced or conflicted.
       #
-      # The outcome lookup, journal append and snapshot replacement share one
-      # SQLite transaction. The runtime performs no preliminary find; this
-      # adapter-native operation owns both concurrency and outcome reporting.
+      # The outcome lookup, journal append and snapshot replacement share one transaction.
       #
       # @param entry [Ports::Persistence::Entry] the save to store
       # @param insert_only [Boolean] when true, an existing row is left untouched
@@ -305,16 +343,33 @@ module Hecks
         end
       end
 
+      # Reads back one record's recorded events, oldest first — pushed down as a `WHERE`
+      # clause (`hecks_events_aggregate_id_idx`) instead of filtering `#events`'s whole-table
+      # read, since a `corrects` command's history lookup only ever needs this one record.
+      #
+      # @param aggregate [String] the `"domain::AggregateName"` key events are stored under
+      # @param id [String, Object] the record's identity, matched as `id.to_s`
+      # @return [Array<Runtime::Event>] the record's stored events; `[]` when it has none
+      # @raise [SQLite3::Exception] if the statement fails
+      def events_for(aggregate:, id:)
+        @db.execute(
+          "SELECT * FROM events WHERE aggregate = ? AND aggregate_id = ? ORDER BY id",
+          [aggregate, id.to_s]
+        ).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
+
       # Inserts new outbox rows as pending, skipping any whose `delivery_id` already exists.
       #
-      # The outbox — see `Runtime::Outbox`. Rows land in the same
-      # database as this aggregate (the only way the enqueue shares the
-      # save's transaction), keyed by the aggregate's storage name so an
-      # adapter instance only ever reads back its own rows even when
-      # several aggregates share one file. `INSERT OR IGNORE` on the
-      # unique delivery_id makes a re-enqueue of the same (event,
-      # consumer) a no-op; `outbox_claim`'s `WHERE status = 'pending'`
-      # is the compare-and-set that lets exactly one relay win a row.
+      # Rows share this aggregate's database so the enqueue joins the save's transaction, and
+      # are keyed by storage name so aggregates sharing a file read back only their own.
       #
       # @param rows [Array<Runtime::Outbox::Row>] rows to enqueue; each accepted row has its
       #   `id` and `status` assigned in place. `row.aggregate` is stored as given
@@ -389,19 +444,6 @@ module Hecks
       # Replaces one saga instance's checkpoint, keyed by domain, process manager and
       # correlation.
       #
-      # ── the optional saga-persistence capability (§2) — reuses the
-      # DDL every SQLite-backed aggregate table already lives beside
-      # (`create_saga_table!`, `Sqlite::SchemaBuilder`, shared with D1).
-      # SQLite's `resolve_path` defaults to one `.db` file per
-      # aggregate unless a domain shares one `database` setting across
-      # its aggregates — since saga persistence resolves through
-      # whichever adapter instance backs the domain's first aggregate
-      # (`Registry#saga_persistence`), this table ends up living inside
-      # that one aggregate's own file by default. Correct and durable
-      # either way; a domain that wants an obviously-named saga store
-      # already gets one by sharing `database` across its aggregates,
-      # the recommended, common case.
-      #
       # @param process_manager [String, Symbol] the process manager's name
       # @param correlation [String, Object] the instance's correlation value, stored as
       #   `correlation.to_s`
@@ -462,7 +504,31 @@ module Hecks
 
       private
 
-      # ── SqlQueryBuilder's dialect hooks ─────────────────────────────
+      # Shared decode step for `entries`/`entries_since` — runs a query already selecting
+      # `aggregate_id, operation, state, mirrors, sequence` and builds one Entry per row.
+      def entries_matching(sql, binds = [])
+        @db.execute(sql, binds).map do |row|
+          state = JSON.parse(row["state"])
+          Ports::Persistence::Entry.new(
+            operation: row["operation"] || "save",
+            id:        row["aggregate_id"],
+            state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
+            mirrors:   row["mirrors"] && JSON.parse(row["mirrors"]),
+            sequence:  row["sequence"].to_i
+          )
+        end
+      end
+
+      # Advances this table's checkpoint to `sequence`, never backwards — two overlapping
+      # `project` calls for out-of-order entries must not let an older sequence win.
+      def advance_checkpoint!(sequence)
+        @db.execute(
+          "INSERT INTO hecks_checkpoints (aggregate_table, last_sequence) VALUES (?, ?) " \
+          "ON CONFLICT (aggregate_table) DO UPDATE SET " \
+          "last_sequence = MAX(last_sequence, excluded.last_sequence)",
+          [table, sequence]
+        )
+      end
 
       def outbox_row(row)
         Runtime::Outbox::Row.new(
@@ -499,8 +565,7 @@ module Hecks
         "json_extract(#{quote_ident(name)}, '#{json_path}')"
       end
 
-      # SQLite has no bare OFFSET — LIMIT -1 is its own documented
-      # unbounded spelling, exactly for this case.
+      # SQLite has no bare OFFSET; LIMIT -1 is its unbounded spelling.
       def unbounded_limit = " LIMIT -1"
 
       def order_clause(order_by, policy)
@@ -511,8 +576,6 @@ module Hecks
         @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

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

@@ -4,37 +4,8 @@ require "fileutils"
 
 module Hecks
   module Adapters
-    # The imperative half of provisioning a tenant, pulled out of
-    # `bin/project_tenant` and behind a real driven port
-    # (`Deploy::Tenant.port "TenantProvisioning"`) instead — the same
-    # hexagonal reasoning `GithubChecks` already gives for its own
-    # port: real, impure, side-effecting work (writing the overlay
-    # file) belongs in an adapter, not in a bare script or a command
-    # handler. `Deploy::Tenant`'s own `asks "Provision"` operation calls
-    # `#provision` and turns whatever it returns into `TenantProvisioned`,
-    # or whatever it raises into `ProvisioningRefused` — see
-    # `PortOperationInterpreter#ask`'s own "every failure is an answer"
-    # comment for why nothing here needs its own rescue.
-    #
-    # ## What it leaves out
-    #
-    # Deliberately does not boot the target domain — that step (proving
-    # it boots for real, running the tenant_capable? gate) stays in
-    # `bin/project_tenant` itself, called after this operation answers,
-    # not nested inside it. Booting a whole domain from inside an
-    # adapter method that is itself running mid-dispatch (this port
-    # operation) is a real, separate concern from writing one file, and
-    # keeping the two apart avoids a nested `Hecks.boot` call ever
-    # running inside another boot's own dispatch call stack.
-    #
-    # ## Return shape
-    #
-    # Returns a hash shaped like `Tenancy::Tenant.Register`'s own
-    # arguments, on purpose — `tenancy.hecksagon`'s own `translates`
-    # reaction forwards an answered event's payload verbatim, so this
-    # adapter's own return value is the translation from Deploy's
-    # vocabulary into Tenancy's, decided here rather than in a mapping
-    # layer neither side could see into.
+    # The imperative half of tenant provisioning, behind `Deploy::Tenant.port
+    # "TenantProvisioning"`; booting the domain and its capability gate stay in bin/project_tenant.
     class TenantProvisioner
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
@@ -45,24 +16,10 @@ module Hecks
 
       # Writes the tenant's environment overlay file under its domain directory.
       #
-      # `directory:` is required, not derived from `domain` — a real,
-      # confirmed bug found only under CI's own real-Postgres suite: a
-      # domain's own declared name (`domain`, e.g. "Scratch") is not a
-      # filesystem path, and File.expand_path(domain, Dir.pwd) silently
-      # resolved to the wrong directory (relative to whatever the
-      # running process' own cwd happened to be) whenever the CLI's own
-      # `--domain=` value didn't happen to equal its own directory
-      # argument by coincidence. `bin/project_tenant` passes its own
-      # real `domain_directory` local straight through.
+      # `directory:` must be passed explicitly — a domain's declared name is not a
+      # filesystem path. Each argument arrives either bare or wrapped as `{ value: }`.
       #
-      # Every argument arrives either bare or wrapped as `{ value: ... }`; both are read.
-      #
-      # @param slug [String, Hash] the tenant's slug, which names the overlay file
-      # @param domain [String, Hash] the declared domain name the overlay is for
-      # @param realm [String, Hash] the realm the overlay declares
-      # @param schema [String, Hash] the schema the overlay declares
-      # @param database [String, Hash] the database the overlay declares
-      # @param adapter [String, Hash] the persistence adapter the overlay declares
+      # @param slug [String, Hash] names the overlay file
       # @param directory [String, Hash] the domain's own directory on disk
       # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm` and `:schema`, as given
       def provision(slug:, domain:, realm:, schema:, database:, adapter:, directory:)

data/lib/hecks/adapters/driven.rb

@@ -1,37 +1,14 @@
 module Hecks
-  # Reopened here purely to require in every driven adapter under
-  # adapters/driven/ below (see the comment inside for what "driven side"
-  # means) — the actual namespace is declared in adapters.rb.
+  # The driven side: every store or reader an adapter declaration can bind.
   module Adapters
-    # The driven side — every store or reader an adapter declaration can
-    # bind. A small adapter is one file beside this one; sqlite, postgres
-    # and heki keep a directory for their supporting cast. Each `.adapter`
-    # file alongside is the DSL declaration the grammar bootstrap and the
-    # Folder adapter load as data.
   end
 end
 
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-# `PostgresEra` is not `require_relative`d here — ADR 0033 moved it, and
-# the rest of the era/lineage/translation subsystem, behind a loadable
-# persistence plugin (`hecks/ports/persistence/plugins/era`) rather than
-# requiring every app to carry it whether or not anything ever binds
-# `persisted_by "PostgresEra"`. `Module#autoload` is the one-line seam
-# that makes that genuinely load-nothing-until-asked instead of pushing
-# an explicit `require` onto every one of the ~15 generic `bin/*` tools
-# that boot an arbitrary checked-in domain (several of which — pizzas,
-# compliance, chess, roster — bind PostgresEra): the first real
-# `Adapters.const_get("PostgresEra")` (`registry/verification.rb`'s own
-# adapter resolution, unchanged) transparently `require`s the plugin
-# entry point, which defines the constant and calls `register_plugin`
-# as its own side effect (`plugins/era.rb`'s last line) — the exact
-# same effect an explicit `require "hecks/ports/persistence/plugins/
-# era"` has, just deferred to the moment something is actually asked
-# for `PostgresEra` rather than sprinkled across every caller that
-# might. A domain that never binds it never triggers the autoload, so
-# never loads a line of era code — unchanged from ADR 0033's own goal.
+# PostgresEra lives in a persistence plugin, autoloaded so a domain that never binds
+# it loads no era code; the plugin entry point registers itself on load (ADR 0033).
 Hecks::Adapters.autoload(:PostgresEra, "hecks/ports/persistence/plugins/era")
 require_relative "driven/lambda"
 require_relative "driven/heki"
@@ -44,16 +21,8 @@ require_relative "driven/tenant_provisioner"
 require_relative "driven/secure_random_identity"
 require_relative "driven/in_process_key_vault"
 require_relative "driven/system_clock"
-# `SequentialIdentity` — the deterministic identity_generation test
-# double — is not required here on purpose. It lives at
-# spec/fixtures/sequential_identity.{adapter,rb}, loaded explicitly by
-# whichever spec wants it: this file's `require_relative` list is what
-# `Folder#load_library`'s `.adapter` glob backs, and `.adapter` DSL
-# declarations register into every registry any real `Hecks.boot` ever
-# builds. Two adapters answering `identity_generation` unconditionally
-# would make the port permanently ambiguous — `Ports::IdentityGeneration
-# .adapter` refuses to choose between more than one — for every
-# consumer, forever, not just specs that want the deterministic one.
+# SequentialIdentity (spec/fixtures) is deliberately not required here: a second
+# `identity_generation` adapter would make that port ambiguous for every boot.
 require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
 require_relative "driven/google_authentication"