hecks 2.8.0 → 3.0.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,38 +4,22 @@ 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"`, for `Tenant.Provision` and for hecks deploy provision; booting the
+    # domain and its capability gate stay in hecks deploy provision.
     class TenantProvisioner
+      # Raised when a value is outside its allow-list or the overlay path leaves `environments/`.
+      class Refused < ArgumentError; end
+
+      # Each argument's allow-list. `\A...\z` anchors: `$` would let a newline end the value early.
+      IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+      LABEL      = /\A[A-Za-z0-9][A-Za-z0-9_ .:-]*\z/
+      CONSTANT   = /\A[A-Z][A-Za-z0-9]*\z/
+      CONNECTION = /\A[^\x00-\x20\x7f]+\z/
+
+      RULES = { slug: IDENTIFIER, schema: IDENTIFIER, domain: LABEL, realm: LABEL,
+                database: CONNECTION, adapter: CONSTANT }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -43,44 +27,74 @@ module Hecks
       # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
-      # Writes the tenant's environment overlay file under its domain directory.
+      # Writes the tenant's environment overlay under `<directory>/environments/`.
       #
-      # `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.
+      # Each argument arrives bare or wrapped as `{ value: }`; the record's other fields are
+      # ignored. Values are allow-listed and written as Ruby string literals.
       #
-      # 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 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:)
-        domain_directory = File.expand_path(directory[:value] || directory)
-
-        overlay_path = File.join(domain_directory, "environments", "#{slug[:value] || slug}.world")
+      # @param slug [String, Hash] names the overlay file
+      # @param directory [String, Hash] the domain's own directory on disk (not its declared name)
+      # @param adapter [String, Hash, nil] the adapter the overlay binds; PostgresEra when none
+      # @return [Hash{Symbol => Object}] `:slug`, `:domain`, `:realm`, `:schema` and `:output`
+      # @raise [Refused] when a value is outside its allow-list or the path leaves `environments/`
+      def write_overlay(slug:, domain:, realm:, schema:, database:, directory:, adapter: nil, **)
+        values = { slug: unwrap(slug), domain: unwrap(domain), realm: unwrap(realm),
+                   schema: unwrap(schema), database: unwrap(database),
+                   adapter: adapter_name(adapter) }
+        values.each { |name, value| check(name, value) }
+
+        overlay_path = overlay_path_for(unwrap(directory), values[:slug])
+        refuse_missing_directory(unwrap(directory))
         FileUtils.mkdir_p(File.dirname(overlay_path))
-        File.write(overlay_path, <<~WORLD)
-          Hecks.world "#{domain[:value] || domain}" do
-            realm "#{realm[:value] || realm}"
-            persisted_by("#{adapter[:value] || adapter}") do
-              database "#{database[:value] || database}"
-              schema   "#{schema[:value] || schema}"
+        File.write(overlay_path, render(values))
+
+        { slug: slug, domain: domain, realm: realm, schema: schema,
+          output: { value: "wrote #{overlay_path}\n" } }
+      end
+
+      private
+
+      # A tenant overlay belongs to a domain that exists: a missing directory is a mistyped path,
+      # not a place to create.
+      def refuse_missing_directory(directory)
+        return if File.directory?(directory.to_s)
+
+        raise Refused, "directory #{directory.to_s.inspect} is not an existing domain directory"
+      end
+
+      def render(values)
+        <<~WORLD
+          Hecks.world #{values[:domain].inspect} do
+            realm #{values[:realm].inspect}
+            persisted_by(#{values[:adapter].inspect}) do
+              database #{values[:database].inspect}
+              schema   #{values[:schema].inspect}
             end
           end
         WORLD
+      end
+
+      def unwrap(argument) = argument.is_a?(Hash) ? argument[:value] : argument
+
+      def check(name, value)
+        return if value.is_a?(String) && RULES.fetch(name).match?(value)
+
+        raise Refused, "#{name} #{value.inspect} is not an accepted #{name}"
+      end
+
+      def overlay_path_for(directory, slug)
+        raise Refused, "directory is required" unless directory.is_a?(String) && !directory.empty?
+
+        environments = File.join(File.expand_path(directory), "environments")
+        path = File.expand_path("#{slug}.world", environments)
+        return path if path.start_with?("#{environments}#{File::SEPARATOR}")
+
+        raise Refused, "overlay path #{path} is outside #{environments}"
+      end
 
-        { slug: slug, domain: domain, realm: realm, schema: schema }
+      def adapter_name(adapter)
+        name = unwrap(adapter)
+        name.nil? || name.to_s.empty? ? "PostgresEra" : name
       end
     end
   end