hecks 5.0.0 → 6.0.0

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

@@ -1,8 +1,11 @@
 require_relative "../../forms/value_object_shape"
+require_relative "../../ports/query/in_memory"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/field_path"
 require_relative "../../runtime/errors"
+require_relative "../../text"
 require_relative "../../runtime/value"
+require_relative "sql_keyset"
 require_relative "sql_value_members"
 
 module Hecks
@@ -13,27 +16,35 @@ module Hecks
     # and dialect_name.
     module SqlQueryBuilder
       include SqlValueMembers
+      include SqlKeyset
 
       COMPARATORS = {
         "eq" => "=", "ne" => "<>", "gt" => ">", "gte" => ">=", "lt" => "<", "lte" => "<="
       }.freeze
 
+      # The operators answered from this store's records in Ruby, not compiled. `none_in_state`
+      # reads another aggregate's records through the registry, which one SQL statement over this
+      # aggregate's table cannot reach. Any other operator this builder cannot compile refuses.
+      IN_MEMORY_OPERATORS = %w[none_in_state].freeze
+
       # Compiles a declared query into one SQL statement and runs it through the dialect's
-      # own `execute_query`, so filtering, ordering and paging all happen in the database.
+      # own `execute_query`, so filtering, ordering and paging all happen in the database. A
+      # query with a where clause in `IN_MEMORY_OPERATORS` is answered over `all` instead.
       #
       # @param declared [QuerySpecification::Common::Options] the declared query: its
       #   `wheres`, `order_by`, `limit` and `offset` are compiled; nothing else is read
       # @param args [Hash{Symbol => Object}] values for the specification's symbolic operands
-      # @param context [Hash] execution context from `Ports::Query.execute`; accepted for the
-      #   port's call shape and not read
-      # @return [Array<Runtime::Instance>] the matching records in declared order, then by
-      #   id; `[]` when none match
+      # @param context [Hash] execution context from `Ports::Query.execute`; its `:registry` is
+      #   read only for a query answered over `all`
+      # @return [Array<Runtime::Instance>] the matches in declared order, then by id; `[]` if none
       # @raise [ArgumentError] if a where clause uses an operator this builder cannot compile,
       #   or `contains` targets a list of a value object with more than one field
       def query(declared, args = {}, context: {})
+        return in_memory_answer(declared, args, context) if in_memory?(declared)
+
         sql = "SELECT #{select_list} FROM #{from_relation}"
         binds = []
-        clauses = where_clauses(declared, args, binds)
+        clauses = restricting_clauses(declared, args, binds)
         sql << " WHERE #{clauses.join(" AND ")}" unless clauses.empty?
         sql << order_by_sql(declared)
         sql << paging_sql(declared, args, binds)
@@ -42,6 +53,12 @@ module Hecks
 
       private
 
+      def in_memory?(declared) = declared.wheres.any? { |clause| IN_MEMORY_OPERATORS.include?(clause.op.to_s) }
+
+      def in_memory_answer(declared, args, context)
+        Ports::Query::InMemory.execute(all, declared, args, registry: context[:registry])
+      end
+
       # The LIMIT and OFFSET text, with their placeholders bound after the where binds.
       def paging_sql(declared, args, binds)
         sql = +""
@@ -109,7 +126,7 @@ module Hecks
       def in_members(value)
         return value.map(&:to_s).reject(&:empty?) if value.is_a?(Array)
 
-        value.to_s.split(",").map(&:strip).reject(&:empty?)
+        Text.comma_list(value)
       end
 
       # Compiles a declared field into an expression over the stored shape. A value-object
@@ -126,7 +143,7 @@ module Hecks
 
       # Whether a bare field name reads as one plain column: the lifecycle field, or a scalar.
       def plain_field?(name, attribute)
-        @aggregate.lifecycle&.field.to_s == name || (attribute && !value_object?(attribute))
+        @aggregate.lifecycle_field.to_s == name || (attribute && !value_object?(attribute))
       end
 
       def value_object?(attr)
@@ -144,7 +161,9 @@ module Hecks
 
         object = Runtime::Value.value_object_for(@aggregate, attribute.type)
         return "" unless object
-        return object.sole_attribute.name.to_s if object.sole_attribute
+
+        sole = object.sole_attribute
+        return sole.name.to_s if sole
 
         raise ArgumentError,
               "#{dialect_name} query adapter cannot compile contains on #{field} — " \

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

@@ -72,7 +72,7 @@ module Hecks
         # A NULL `projects` column means never seeded, so it reads back absent as under Heki and
         # PostgresEra; nothing stores a nil projected value. The lifecycle field keeps its NULL.
         def projected_only?(field)
-          @aggregate.lifecycle&.field&.to_sym != field[:name].to_sym &&
+          @aggregate.lifecycle_field&.to_sym != field[:name].to_sym &&
             @aggregate.projected_fields.any? { |projected| projected.name.to_sym == field[:name].to_sym }
         end
       end

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

@@ -56,6 +56,13 @@ module Hecks
           )
         SQL
 
+        DISPATCH_CLAIMS = <<~SQL.freeze
+          CREATE TABLE IF NOT EXISTS hecks_dispatch_claims (
+            claim_key   TEXT PRIMARY KEY,
+            claimed_at  TEXT NOT NULL
+          )
+        SQL
+
         CHECKPOINTS = <<~SQL.freeze
           CREATE TABLE IF NOT EXISTS hecks_checkpoints (
             aggregate_table TEXT PRIMARY KEY,

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

@@ -10,9 +10,10 @@ module Hecks
         def dialect_name = "SQLite"
         def empty_in_clause = "0"
 
+        # Numbered, so a statement may place its binds' text in any order (ADR 0129).
         def placeholder(binds, value)
           binds << value
-          "?"
+          "?#{binds.size}"
         end
 
         def contains_clause(expression, placeholder)

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

@@ -0,0 +1,28 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # Saga dispatches already applied, one row per dispatch key in the aggregate's own database
+      # file so a claim joins the save's transaction. See `Runtime::DispatchClaim`.
+      module DispatchClaims
+        # Whether the dispatch with this key has been applied.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true once `dispatch_claim` has accepted the key
+        def dispatch_applied?(key)
+          !@db.get_first_row("SELECT 1 FROM hecks_dispatch_claims WHERE claim_key = ?", [key]).nil?
+        end
+
+        # Records that the dispatch with this key is being applied, refusing a second claim.
+        #
+        # @param key [String] the dispatch key a saga leg stamped on the command
+        # @return [Boolean] true when the key was new and is now held; false when already held
+        # @raise [SQLite3::Exception] if the insert fails
+        def dispatch_claim(key) # rubocop:disable Naming/PredicateMethod -- the claim port's verb
+          @db.execute("INSERT OR IGNORE INTO hecks_dispatch_claims (claim_key, claimed_at) VALUES (?, ?)",
+                      [key, Time.now.utc.iso8601])
+          @db.changes.positive?
+        end
+      end
+    end
+  end
+end

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

@@ -92,8 +92,54 @@ module Hecks
           removed
         end
 
+        # Reads the chain heads the ledger sealed beside this journal, oldest first.
+        #
+        # @return [Array<Hash>] `through:` the highest sequence a seal covers, `head:` the chain
+        #   digest at that point and `previous:` the head the seal followed (genesis digest first)
+        # @raise [SQLite3::Exception] if a statement fails
+        def ledger_anchors
+          ensure_ledger_anchors!
+          @db.execute(
+            "SELECT through_sequence, head, previous FROM hecks_ledger_anchors " \
+            "WHERE aggregate_table = ? ORDER BY through_sequence", [table]
+          ).map { |row| { through: row["through_sequence"].to_i, head: row["head"], previous: row["previous"] } }
+        end
+
+        # Seals a chain head beside this journal. Sealing the same point twice with the same head
+        # changes nothing; a different head for a sealed point is refused, never overwritten.
+        #
+        # @param through [Integer] the highest journal sequence the head covers
+        # @param head [String] the chain digest at `through`
+        # @param previous [String] the head of the seal before this one
+        # @return [void]
+        # @raise [Runtime::WiringError] if the point is already sealed with another head
+        # @raise [SQLite3::Exception] if a statement fails
+        def record_ledger_anchor(through:, head:, previous:)
+          ensure_ledger_anchors!
+          sealed = ledger_anchors.find { |anchor| anchor[:through] == through }
+          if sealed
+            return if sealed[:head] == head
+
+            raise Runtime::WiringError, "#{table} is already sealed through #{through} with another head: the journal changed"
+          end
+
+          @db.execute(
+            "INSERT INTO hecks_ledger_anchors (aggregate_table, through_sequence, head, previous) " \
+            "VALUES (?, ?, ?, ?)", [table, through, head, previous]
+          )
+        end
+
         private
 
+        def ensure_ledger_anchors!
+          @db.execute(
+            "CREATE TABLE IF NOT EXISTS hecks_ledger_anchors (" \
+            "aggregate_table TEXT NOT NULL, through_sequence INTEGER NOT NULL, head TEXT NOT NULL, " \
+            "previous TEXT NOT NULL, sealed_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP, " \
+            "PRIMARY KEY (aggregate_table, through_sequence))"
+          )
+        end
+
         # 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 = [])

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

@@ -64,7 +64,8 @@ module Hecks
         #   keys; `[]` when none match
         # @raise [SQLite3::Exception] if the statement fails
         def outbox_rows(status: nil)
-          sql   = "SELECT * FROM hecks_outbox WHERE aggregate = ?"
+          sql   = "SELECT *, CAST(strftime('%s', 'now') AS INTEGER) - CAST(strftime('%s', claimed_at) AS INTEGER) " \
+                  "AS claimed_for FROM hecks_outbox WHERE aggregate = ?"
           binds = [table]
           if status
             sql << " AND status = ?"
@@ -89,7 +90,7 @@ module Hecks
             id: row["id"], delivery_id: row["delivery_id"], event_uid: row["event_uid"], aggregate: row["aggregate"],
             domain: row["domain"], kind: row["kind"], consumer: row["consumer"],
             event: JSON.parse(row["event"], symbolize_names: true), status: row["status"],
-            attempts: row["attempts"].to_i, error: row["error"]
+            attempts: row["attempts"].to_i, error: row["error"], claimed_for: row["claimed_for"]&.to_f
           )
         end
       end

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

@@ -1,9 +1,5 @@
-require_relative "../../../runtime/instance"
-require_relative "../../../runtime/value"
-require_relative "../../../runtime/errors"
-require_relative "../../../runtime/refusal_wording"
-require_relative "../../../rendering"
-require_relative "../../../ports/query/in_memory"
+require "json"
+require_relative "../projection/read_model_walk"
 
 # The subclass needs its parent — and sqlite.rb requires this file at
 # its bottom, after class Sqlite is defined, so the require cycle this
@@ -15,8 +11,7 @@ module Hecks
     # Rebuilds a read store from the authoritative journal, entry by entry.
     # Values are written as JSON, references as bare ids — the shapes the command path writes.
     class SqliteProjection < Sqlite
-      # The state of one `query_read_model` call, threaded through its per-head steps.
-      ReadModelRun = Struct.new(:model, :args, :bluebook, :reference_id, :eligible, :projected)
+      include Projection::ReadModelWalk
 
       # Replaces or deletes the read store's row for one journal entry, encoding the entry's
       # state directly rather than through a `Runtime::Instance`.
@@ -33,147 +28,26 @@ module Hecks
         entry
       end
 
-      # Executes a declared read model against the projected read-store tables.
-      #
-      # A missing root raises, matching the in-process interpreter; a head
-      # matches against any already-projected source, not only the root.
-      #
-      # @param _domain [String, Symbol] domain name; not read
-      # @param model [Bluebook::ReadModel, Runtime::TenantScope::Scoped] read model to answer
-      # @param args [Hash] arguments; `model.reference_name` holds the root id
-      # @param bluebook [Bluebook::Chapter, nil] resolves each included aggregate; nil refused
-      # @return [Array<Hash>] one-element Array of the report, keyed by each head's `as`
-      # @raise [ArgumentError] if bluebook is nil
-      # @raise [Runtime::NotFound] if no projected row matches the referenced root id
-      def query_read_model(_domain, model, args, bluebook = nil)
-        raise ArgumentError, "projection query needs its domain bluebook" unless bluebook
-
-        # Read the same way ReadModelInterpreter reads it: an identity is a
-        # declared path, not unwrapped.
-        reference_id = args.fetch(model.reference_name).to_s
-        # Plural (ADR 0055) — `on:` lets `where`/`order_by`/`limit`/`offset`
-        # each name a different many-side head, so more than one may be
-        # eligible in the same read model.
-        run = ReadModelRun.new(model, args, bluebook, reference_id, model.filtered_head_names, [])
-        [ordered_heads(model).to_h { |head| [head[:as], resolve_head(run, head)] }]
-      end
-
       private
 
-      # Root first, always (see `query_read_model`'s own header): a later head's
-      # join must match against a root or head already resolved.
-      def ordered_heads(model)
-        root_heads, other_heads = model.aggregate_heads.partition { |head| head[:aggregate] == model.reference_target }
-        root_heads + other_heads
-      end
-
-      # Reads one head's rows, records them as projected so later heads can join against them,
-      # and returns the head's report entry.
-      def resolve_head(run, head)
-        rows = head_rows(run, head, run.bluebook.aggregate(head[:aggregate]))
-        rows = filter_rows(run, head, rows)
-        run.projected << { aggregate: head[:aggregate], rows: rows }
-        head_report(head, rows)
-      end
-
-      # Applies the head's `where`/`order_by`/`limit`/`offset` when the read model names it.
-      def filter_rows(run, head, rows)
-        return rows unless run.eligible.include?(head[:as])
-
-        Ports::Query::InMemory.execute(rows, run.model.options_for(head[:as]), run.args)
-      end
-
-      def head_report(head, rows)
-        return rows.map { |row| Runtime::Value.materialize(row.to_h) } if head[:many]
-
-        rows.first && Runtime::Value.materialize(rows.first.to_h)
-      end
-
-      def head_rows(run, head, aggregate)
-        return select_related(aggregate, run.projected) unless head[:aggregate] == run.model.reference_target
-
-        [select_projected(aggregate, run.reference_id) || raise(Runtime::NotFound, missing_root_wording(run, head))]
-      end
-
-      def missing_root_wording(run, head)
-        Runtime::RefusalWording.render_site("NotFound", "read_model_reference_missing",
-                                            aggregate: head[:aggregate],
-                                            offered:   Hecks::Rendering.describe(run.reference_id))
-      end
-
       def row_values(entry)
         [entry.id.to_s] + persisted_fields.map { |field| encode_field(field, entry.state[field[:name]]) }
       end
 
-      def select_projected(aggregate, id)
-        row = @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id.to_s])
-        row && projected_instance(aggregate, row)
+      def projected_row(aggregate, id)
+        @db.get_first_row("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE id = ?", [id])
       end
 
-      # Matches every already-projected source, not just the root, so a head
-      # referencing another included head still matches.
-      def select_related(aggregate, projected)
-        matches = projected.flat_map { |source| reference_matches(aggregate, source) }
-        return [] if matches.empty?
-
-        # A reference column holds the id, so it compares directly against itself.
+      # A reference column holds the id, so it compares directly against itself.
+      def related_rows(aggregate, matches)
         clauses = matches.map { |attribute, _id| "#{quote_ident(attribute.name)} = ?" }
         bind = matches.map { |_attribute, id| id }
         @db.execute("SELECT * FROM #{quote_ident(aggregate.storage_name)} WHERE #{clauses.join(" OR ")} ORDER BY id", bind)
-           .map { |row| projected_instance(aggregate, row) }
-      end
-
-      # Every (reference attribute, id) pair by which `aggregate` points at one projected source.
-      def reference_matches(aggregate, source)
-        references = aggregate.attributes.select do |attribute|
-          attribute.reference? && attribute.type.target_name == source[:aggregate].to_s
-        end
-        return [] if references.empty?
-
-        ids = source[:rows].map { |row| row.id.to_s }
-        references.product(ids)
-      end
-
-      def projected_instance(aggregate, row)
-        Runtime::Instance.new(aggregate: aggregate, id: row["id"], state: decode_for(aggregate, row))
-      end
-
-      def decode_for(aggregate, row)
-        decode_fields(fields_for(aggregate), aggregate, row)
-      end
-
-      # Declared attributes plus the lifecycle field and any unlisted
-      # `projects` fields, all read back raw (see `decode_fields`).
-      def fields_for(aggregate)
-        fields = aggregate.attributes.map { |attribute| [attribute.name, attribute] }
-        # `projects` fields (ADR 0025) read back raw too — see `persisted_fields`.
-        lifecycle = aggregate.lifecycle
-        raw_names = (lifecycle ? [lifecycle.field] : []) + aggregate.projected_fields.map(&:name)
-        raw_names.each { |raw| fields << [raw, nil] unless fields.any? { |name, _| name == raw } }
-        fields
-      end
-
-      # Decoded through the state codec against the row's own aggregate —
-      # see Codec#decode for why a NULL projected-only column reads back absent.
-      def decode_fields(fields, aggregate, row)
-        state = fields.each_with_object({}) do |(name, attribute), raw_state|
-          raw = row[name.to_s]
-          next if unset_projected?(aggregate, name, attribute, raw)
-
-          raw_state[name] = decode_column(aggregate, attribute, raw)
-        end
-        Ports::Persistence::StateCodec.decode(aggregate, state)
-      end
-
-      # A NULL column with no attribute reads back absent, except the lifecycle field.
-      def unset_projected?(aggregate, name, attribute, raw)
-        attribute.nil? && raw.nil? && aggregate.lifecycle&.field&.to_sym != name.to_sym
       end
 
+      # A reference is a scalar id (see Codec#decode); a list or value object is JSON.
       def decode_column(aggregate, attribute, raw)
-        return raw if attribute.nil?
-        # A reference is a scalar id — see Codec#decode.
-        return raw unless attribute.list? || !aggregate.value_object(attribute.type).nil?
+        return raw if attribute.nil? || !json_column?(aggregate, attribute)
 
         raw ? JSON.parse(raw) : nil
       end

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

@@ -110,7 +110,7 @@ module Hecks
           return "ORDER BY id" unless order_by
 
           name = order_by.to_s.split(".").first
-          unless @aggregate.lifecycle&.field.to_s == name || @aggregate.attribute(name)
+          unless @aggregate.lifecycle_field.to_s == name || @aggregate.attribute(name)
             raise Runtime::WiringError,
                   "#{@aggregate.name} has no attribute #{order_by.inspect} to order by"
           end

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

@@ -5,6 +5,9 @@ module Hecks
     class Sqlite
       # DDL for one aggregate: head table, entry table, events, saga and outbox tables.
       module SchemaBuilder
+        # Any character an SQLite index name may not hold unquoted.
+        NON_IDENTIFIER_CHARACTER = /[^a-zA-Z0-9_]/
+
         private
 
         def create_aggregate_table!
@@ -58,6 +61,10 @@ module Hecks
           @db.execute("CREATE INDEX IF NOT EXISTS idx_hecks_outbox_status ON hecks_outbox(aggregate, status)")
         end
 
+        def create_dispatch_claims_table!
+          @db.execute(Ddl::DISPATCH_CLAIMS)
+        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.
@@ -89,8 +96,13 @@ module Hecks
 
         def declared_query_fields
           queries = @aggregate.queries + @aggregate.entities.flat_map(&:queries)
-          queries.flat_map { |query| query.wheres.map(&:field) + [query.order_by&.field] }
-                 .compact.map(&:to_s).uniq
+          fields = queries.flat_map { |query| query_fields(query) }
+          fields.compact.map(&:to_s).uniq
+        end
+
+        # The fields a query filters on, then the one it orders by (nil when it orders by none).
+        def query_fields(query)
+          query.wheres.map(&:field) + [query.order_by_field]
         end
 
         # A scalar or lifecycle field gets a btree index; a value-object path gets an expression
@@ -100,7 +112,7 @@ module Hecks
         def ensure_index_for_field!(field)
           name, * = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
-          lifecycle_field = @aggregate.lifecycle&.field.to_s == name
+          lifecycle_field = @aggregate.lifecycle_field.to_s == name
 
           return if !lifecycle_field && attribute.nil?
           return if attribute&.list?
@@ -114,7 +126,7 @@ module Hecks
         # 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_]/, "_")
+          sanitized = field.to_s.gsub(NON_IDENTIFIER_CHARACTER, "_")
           "idx_#{table}_#{sanitized}"
         end
       end

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

@@ -0,0 +1,39 @@
+module Hecks
+  module Adapters
+    class Sqlite
+      # SQLite's spellings for the shared {SetTransform} statement (ADR 0129).
+      module SetDialect
+        # @return [String] the dialect the operator ledger's renderings name
+        def set_transform_dialect = "sqlite"
+
+        private
+
+        # Numbered, so a guard can repeat an operand's text and still bind the same value.
+        def typed_placeholder(binds, value, _type)
+          binds << value
+          "?#{binds.size}"
+        end
+
+        def null_safe_equality(left, right, negated:) = "(#{left} IS #{"NOT " if negated}#{right})"
+
+        # SQLite compares text by bytes, as Ruby compares Strings.
+        def text_ordering(sql) = sql
+
+        # An integer result that overflowed comes back as a real, which Ruby would refuse.
+        def integer_guard(sql) = "typeof(#{sql}) = 'integer'"
+
+        def scalar_read(column, member, _type) = "json_extract(#{quote_ident(column)}, '$.#{member}')"
+
+        def scalar_write(member, sql) = "json_object('#{member}', #{sql})"
+
+        def version_bump = []
+
+        def run_set_transform(sql, binds)
+          @db.execute(sql, binds).map { |row| Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row)) }
+        rescue SQLite3::Exception => e
+          raise SetTransform::Declined, "SQLite refused the set transform: #{e.message}"
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,8 @@
 Hecks.adapter "SqlitePersistence" do
   port   "persistence"
   field  :database, default: "data/{storage_name}.db"
+  # Rewrites every row of an aggregate in one statement.
+  provides "set_transform"
 end
 
 Hecks.adapter "SqliteProjection" do

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

@@ -8,8 +8,11 @@ require_relative "sqlite/dialect"
 require_relative "sqlite/events"
 require_relative "sqlite/journal"
 require_relative "sqlite/outbox"
+require_relative "sqlite/dispatch_claims"
 require_relative "sqlite/repository"
 require_relative "sqlite/sagas"
+require_relative "sqlite/set_dialect"
+require_relative "set_transform"
 require_relative "../../ports/persistence/append_only"
 require_relative "../../query_specification/common/null_policy"
 require_relative "../../query_specification/common/order_by"
@@ -30,17 +33,22 @@ module Hecks
       include Journal
       include Events
       include Outbox
+      include DispatchClaims
       include Sagas
       include Dialect
+      include SetTransform
+      include SetDialect
 
       SQL_TYPES = { "Integer" => "INTEGER", "Float" => "REAL" }.freeze
 
       attr_reader :aggregate, :path
 
       # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      # `:dispatch_claims`: `dispatch_claim` joins the save's transaction, so a claim and the
+      # write it guards commit or roll back together.
       #
-      # @return [Array<Symbol>] `[:atomic_put]`
-      def persistence_capabilities = [:atomic_put]
+      # @return [Array<Symbol>] `[:atomic_put, :dispatch_claims]`
+      def persistence_capabilities = %i[atomic_put dispatch_claims]
 
       # Opens (creating if absent) the database file and its aggregate, journal, event, saga
       # and outbox tables.
@@ -103,6 +111,7 @@ module Hecks
         create_event_table!
         create_saga_table!
         create_outbox_table!
+        create_dispatch_claims_table!
         create_checkpoint_table!
       end
 

data/lib/hecks/adapters/driven.rb

@@ -7,10 +7,14 @@ end
 require_relative "driven/memory"
 require_relative "driven/sqlite"
 require_relative "driven/postgres"
-# 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")
+# PostgresEra is autoloaded so a domain that never binds it loads no era code; loading it
+# installs the era persistence plugin, which registers itself (ADR 0033).
+Hecks::Adapters.autoload(:PostgresEra, "hecks/adapters/driven/postgres_era")
 require_relative "driven/lambda"
+# Loaded on first mention: nothing about a domain's own boot needs the dump
+# tooling, and it wants the optional `pg` gem.
+Hecks::Adapters.autoload(:PostgresDump, File.join(__dir__, "driven/postgres_dump"))
+Hecks::Ports::Persistence.autoload(:PostgresDump, File.join(__dir__, "driven/postgres_dump"))
 require_relative "driven/heki"
 require_relative "driven/local_storage"
 require_relative "driven/prism"
@@ -24,5 +28,6 @@ require_relative "driven/system_clock"
 # `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"
 require_relative "driven/claude_code"
 require_relative "driven/script_runner"

data/lib/hecks/adapters/driving/cli.rb

@@ -79,7 +79,7 @@ module Hecks
           else value
           end
         rescue ArgumentError
-          raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the chapter declares this field as #{type}"
+          raise Runtime::TypeMismatch, "#{value.inspect} is not #{type} — the bluebook declares this field as #{type}"
         end
 
         # Reads a Boolean word: `true`, `yes`, `1` or `on` is true; `false`, `no`, `0` or `off` is