hecks 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c40a3c6e1879b5df4a299ae07488cffe80fc0c9ee22905044b876b3887c2cfc3
-  data.tar.gz: 983121c63439d9f7d79c77e0dabcf34e1625df7067368c27438ff64f0065291e
+  metadata.gz: 9d056aad218f4fe26394319c5ce486211ac9790022de8159ba23f050a634f5df
+  data.tar.gz: d6fa0c2f693152be740b0c5f658008a6ba71ae9bd80e175e8da78b142f00f133
 SHA512:
-  metadata.gz: 17ffccfc67272cb90216229ebb41e6fdf4199b6ca6f4e1f5ecee7964191190c2e0f562b2c1fd0c0f7d304f3da95ab3521a3ca13fdcc162935fc99c9a33aca866
-  data.tar.gz: 9cb2f68d53120a1e7a7ab59e91387661151243d51927f7de690986597c3e2932f09b7680cabb0933e1b82683dffd29b9581167f05799864c56e3ddfa1b502970
+  metadata.gz: 4ae526f5a34b194a9b3d23751fae0bb6bdee1bcd8011653904d2b324bf4478ee7b4049d96f0b2a74d005a810ac7023d6efa5a8d0639fb079ed8691da93a5f217
+  data.tar.gz: c2b1a7be12ebfbd52ad5cb13ddd1aa7693a7d903d1402c580baad40414a7f3318d7263379658debc502492986956f97b5377681ac93cf5cb36e058c3e1ccfb46

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

@@ -81,7 +81,14 @@ module Hecks
           failed = results.find { |result| result["success"] == false }
           if failed
             messages = (body["errors"] || []).map { |error| error["message"] }.join("; ")
-            detail = failed["error"] || failed["message"] || messages
+            detail =
+              if failed.key?("error")
+                failed["error"]
+              elsif failed.key?("message")
+                failed["message"]
+              else
+                messages
+              end
             raise Runtime::WiringError, "D1 query failed: #{detail.to_s.empty? ? 'a batched statement failed' : detail}"
           end
 
@@ -112,9 +119,9 @@ module Hecks
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
 
-        account_id  = settings[:account_id]  || settings["account_id"]
-        database_id = settings[:database_id] || settings["database_id"]
-        api_token   = settings[:api_token]   || settings["api_token"]
+        account_id  = settings.key?(:account_id)  ? settings[:account_id]  : settings["account_id"]
+        database_id = settings.key?(:database_id) ? settings[:database_id] : settings["database_id"]
+        api_token   = settings.key?(:api_token)   ? settings[:api_token]   : settings["api_token"]
         { "account_id" => account_id, "database_id" => database_id, "api_token" => api_token }.each do |name, value|
           raise Runtime::WiringError, "D1 needs a #{name.inspect} in its world settings" if value.to_s.empty?
         end
@@ -126,7 +133,15 @@ module Hecks
         # own per-aggregate-file default, there's no "which file does
         # this end up in" ambiguity here: every aggregate on D1 within a
         # domain already shares one database.
-        @domain = (settings[:domain] || settings["domain"] || aggregate.name).to_s
+        @domain = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        ).to_s
 
         # No PRAGMA synchronous here, unlike Sqlite — D1 is a managed
         # durable service; there is no local fsync policy for a caller to
@@ -171,7 +186,12 @@ module Hecks
       def append(entry)
         @db.execute(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-          [entry.id, entry.operation, JSON.generate(entry.state), JSON.generate(entry.mirrors)]
+          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # mirrors hash must bind a real SQL NULL, not the four-character
+          # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
+          # check against it would never match. Same guard `postgres_era.rb`
+          # already uses for its own journal's `mirrors` column.
+          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
@@ -252,17 +272,20 @@ module Hecks
               "THEN 'replaced' ELSE 'inserted' END AS status"
           end
 
+        # `mirrors` is NULLABLE (unlike `state`) — see `append`'s own comment.
+        encoded_mirrors = entry.mirrors && JSON.generate(entry.mirrors)
+
         entry_sql, entry_binds =
           if insert_only
             [
               "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) " \
               "SELECT ?, ?, ?, ? #{not_exists}",
-              [entry.id, entry.operation, JSON.generate(entry.state), JSON.generate(entry.mirrors), entry.id.to_s]
+              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors, entry.id.to_s]
             ]
           else
             [
               "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES (?, ?, ?, ?)",
-              [entry.id, entry.operation, JSON.generate(entry.state), JSON.generate(entry.mirrors)]
+              [entry.id, entry.operation, JSON.generate(entry.state), encoded_mirrors]
             ]
           end
 
@@ -318,11 +341,11 @@ module Hecks
       # `Sqlite::SchemaBuilder` already shares with Sqlite (`d1.rb`'s own
       # file header). Same `?`-placeholder shape every other write here
       # already uses through `Connection#execute`.
-      def save_saga(process_manager:, correlation:, state:, memory:)
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.execute(
-          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory) " \
-          "VALUES (?, ?, ?, ?, ?)",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory)]
+          "INSERT OR REPLACE INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+          "VALUES (?, ?, ?, ?, ?, ?)",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
         )
       end
 
@@ -337,11 +360,12 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.execute(
-          "SELECT process_manager, correlation, state, memory FROM hecks_saga_instances WHERE domain = ?",
+          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = ?",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
-                JSON.parse(row["memory"], symbolize_names: true)
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
         end
       end
 

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

@@ -1,3 +1,5 @@
+require "time"
+
 module Hecks
   module Adapters
     # THE `authorization` PORT, FULFILLED BY GOVERNANCE — same registry,
@@ -19,13 +21,50 @@ module Hecks
     module GovernanceAuthorization
       module_function
 
-      def holds_role?(registry, actor_id:, role:)
+      # `as_of` and `scope` are BOTH optional, same opt-in shape
+      # `refuse_role_mismatch` already gives `actor_id` itself — an
+      # unbound `as_of` skips the `starts_at` check and an unbound
+      # `scope` skips the `scope` check, exactly the behavior before
+      # either existed. Neither is fetched here: `as_of` arrives already
+      # resolved from `Ports::Clock.now`, called by the caller at the
+      # door, never by this adapter — see `Ports::Clock`'s own header
+      # for why the dispatch path must not consult the clock itself.
+      def holds_role?(registry, actor_id:, role:, as_of: nil, scope: nil)
         rows = Runtime::Dispatcher.new(registry).query(
           "Governance::RoleAssignment.AssignmentsForActor",
           actor_id: { value: actor_id.to_s }
         )
 
-        rows.any? { |row| row[:role_name][:value] == role.to_s && row[:ends_at].nil? }
+        rows.any? do |row|
+          row[:role_name][:value] == role.to_s &&
+            row[:ends_at].nil? &&
+            in_scope?(row, scope) &&
+            started?(row, as_of)
+        end
+      end
+
+      # `scope` UNCHECKED WHEN NOT STATED, same as every other opt-in
+      # field here — a caller that never says which scope it is acting
+      # in gets the pre-scope behavior: any live assignment for the role
+      # authorizes, everywhere. A caller that does state one only
+      # authorizes against an assignment granted for THAT scope.
+      def in_scope?(row, scope)
+        scope.nil? || row[:scope][:value] == scope.to_s
+      end
+
+      # `starts_at` IS A FREE-TEXT STRING in the bluebook (`Timestamp`'s
+      # only invariant is "present", not any particular format) — parsed
+      # here with `Time.parse` rather than compared lexically, since
+      # nothing guarantees every caller writes it zero-padded ISO 8601.
+      # FAILS CLOSED : a `starts_at` that does not parse is treated as
+      # not-yet-started rather than silently ignored, the same direction
+      # every other check in this method already fails.
+      def started?(row, as_of)
+        return true if as_of.nil?
+
+        Time.parse(row[:starts_at][:value].to_s).to_i <= as_of
+      rescue ArgumentError, TypeError
+        false
       end
 
       # THE OTHER HALF — may role X act as role Y. `RoleTransition.Allowed`

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

@@ -38,9 +38,14 @@ module Hecks
         end
 
         def append_entry(operation, id, state)
+          line = "#{JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors)}\n"
+
+          # One write, not JSON-then-newline as two: two concurrent
+          # appends can only interleave *between* writes, never inside
+          # one, so this line can't come out split by another process's
+          # line landing in the middle of it.
           File.open(@journal_path, "ab") do |journal|
-            journal.write(JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors))
-            journal.write("\n")
+            journal.write(line)
             journal.flush
             journal.fsync
           end

data/lib/hecks/adapters/driven/heki/snapshot.rb

@@ -23,15 +23,42 @@ module Hecks
           raise Malformed, "#{@path}: json error: #{e.message}"
         end
 
+        # Temp-file-plus-rename, fsynced before the rename: a reader can
+        # only ever see the last complete snapshot or the one before it,
+        # never a truncated or partial one — `File.binwrite`'s old
+        # truncate-then-write left a window, proportional to the whole
+        # dataset, where the file on disk was neither.
         def write(records)
           sorted = records.sort_by { |id, _| id }.to_h
           json   = JSON.generate(sorted)
+          body   = MAGIC + [sorted.size].pack("N") + Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
+          tmp    = "#{@path}.tmp.#{Process.pid}.#{object_id}"
 
-          File.binwrite(
-            @path,
-            MAGIC + [sorted.size].pack("N") + Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
-          )
+          File.open(tmp, "wb") do |file|
+            file.write(body)
+            file.flush
+            file.fsync
+          end
+          File.rename(tmp, @path)
         end
+
+        # Serializes the read-modify-write each save/delete does against
+        # the snapshot (and the journal append that precedes it) across
+        # processes — `flock` is per-process advisory, so every writer
+        # has to go through this to matter, which `with_lock`'s only two
+        # callers (`Heki#save`/`#delete`, `SagaStore#save_saga`/
+        # `#delete_saga`) both do. The lock file is separate from
+        # `@path` so a held lock never blocks `write`'s own rename.
+        def with_lock
+          File.open(lock_path, File::CREAT | File::RDWR, 0o644) do |lock|
+            lock.flock(File::LOCK_EX)
+            yield
+          ensure
+            lock.flock(File::LOCK_UN)
+          end
+        end
+
+        def lock_path = "#{@path}.lock"
       end
     end
   end

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

@@ -34,7 +34,15 @@ module Hecks
         # — falls back to the aggregate's own name for a directly-
         # instantiated adapter (specs), same fallback shape Postgres's
         # own @domain already uses.
-        @domain    = (settings[:domain] || settings["domain"] || aggregate.name).to_s
+        @domain    = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        ).to_s
 
         FileUtils.mkdir_p(File.dirname(@path))
       end
@@ -72,8 +80,12 @@ module Hecks
         @entry_mirrors = nil
       end
 
+      # Reads fresh rather than trusting the memoized `store` — under
+      # `with_lock`, another process may have projected a snapshot since
+      # this one last read it, and mutating *its* stale copy would
+      # overwrite that write on disk rather than layer on top of it.
       def project(entry)
-        current = store
+        current = read
         entry.save? ? current[entry.id] = entry.state.dup : current.delete(entry.id)
         write(current)
         @store = current
@@ -82,8 +94,10 @@ module Hecks
 
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
-        append(entry)
-        project(entry)
+        with_lock do
+          append(entry)
+          project(entry)
+        end
         instance
       end
 
@@ -91,8 +105,10 @@ module Hecks
         return false unless find(id)
 
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
-        append(entry)
-        project(entry)
+        with_lock do
+          append(entry)
+          project(entry)
+        end
         true
       end
 
@@ -104,8 +120,8 @@ module Hecks
       # shape (a sibling snapshot+journal file pair, `SagaStore`,
       # heki/saga_store.rb) rather than a table in a store this adapter
       # doesn't have.
-      def save_saga(process_manager:, correlation:, state:, memory:)
-        saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, state.to_s, memory)
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
+        saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, state.to_s, memory, completed_compensations)
       end
 
       def delete_saga(process_manager:, correlation:)
@@ -137,8 +153,23 @@ module Hecks
         replay_journal(snapshot)
       end
 
+      # `dir: :default` — a bare Symbol, the framework's own convention
+      # for "a DECLARED value that resolves by convention, never a silent
+      # fallback" — used to crash `File.join` outright
+      # (`TypeError: no implicit conversion of Symbol into String`):
+      # `resolve_path` only ever checked for a MISSING `dir` setting,
+      # never a Symbol one. Treated the same as no setting at all — falls
+      # back to the existing "data" default, not a new special case.
       def resolve_path(settings, root)
-        declared = settings[:dir] || settings["dir"] || "data"
+        declared =
+          if settings.key?(:dir)
+            settings[:dir]
+          elsif settings.key?("dir")
+            settings["dir"]
+          else
+            "data"
+          end
+        declared = "data" if declared == :default
         dir      = declared.start_with?("/") ? declared : File.join(root || Dir.pwd, declared)
 
         File.join(dir, "#{@aggregate.storage_name}.heki")

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

@@ -31,8 +31,22 @@ module Hecks
 
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
-        domain = settings[:domain] || settings["domain"] || aggregate.name
-        region = settings[:region] || settings["region"] || "us-east-1"
+        domain =
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.name
+          end
+        region =
+          if settings.key?(:region)
+            settings[:region]
+          elsif settings.key?("region")
+            settings["region"]
+          else
+            "us-east-1"
+          end
         # TWO DIFFERENT "domain"s, deliberately not conflated: `domain`
         # (this aggregate's OWN bluebook name — "Identity", "Governance")
         # only ever prefixes the instances lookup, since that's how

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

@@ -21,6 +21,14 @@ module Hecks
           end
           lifecycle = @aggregate.lifecycle
           fields << { name: lifecycle.field, attribute: nil, sql_type: "text" } if lifecycle && !fields.any? { |field| field[:name] == lifecycle.field }
+          # `projects` FIELDS (S12, ADR 0025) ARE A LOCAL COLUMN TOO — see
+          # Sqlite::Codec#persisted_fields' own comment; identical reasoning,
+          # `text` to match this file's own lowercase SQL type spelling.
+          @aggregate.projected_fields.each do |field|
+            next if fields.any? { |f| f[:name] == field.name }
+
+            fields << { name: field.name, attribute: nil, sql_type: "text" }
+          end
           fields
         end
 

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

@@ -19,6 +19,15 @@ module Hecks
           @db.exec(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{columns.empty? ? '' : ', '}#{columns.join(', ')})"
           )
+          # SELF-HEALING, SAME IDIOM AS `ensure_indexes!` BELOW —
+          # `CREATE TABLE IF NOT EXISTS` above does NOT retroactively add a
+          # column to an already-existing table (a committed database from
+          # before optimistic-concurrency CAS existed), so this runs
+          # unconditionally on every boot and no-ops once the column is
+          # there. ADAPTER BOOKKEEPING ONLY — never listed in
+          # `persisted_fields` (Codec), so it never appears in `decode`'s
+          # domain-state hash or `Instance#to_h`.
+          @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
           # RIGHT HERE, NOT A SEPARATE STEP IN `Postgres#initialize` —
           # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
           # uses: index creation runs unconditionally, right after the
@@ -60,15 +69,22 @@ module Hecks
         def create_saga_table!
           @db.exec(<<~SQL)
             CREATE TABLE IF NOT EXISTS hecks_saga_instances (
-              domain          text NOT NULL,
-              process_manager text NOT NULL,
-              correlation     text NOT NULL,
-              state           text NOT NULL,
-              memory          jsonb NOT NULL,
-              updated_at      timestamptz NOT NULL DEFAULT now(),
+              domain               text NOT NULL,
+              process_manager      text NOT NULL,
+              correlation          text NOT NULL,
+              state                text NOT NULL,
+              memory               jsonb NOT NULL,
+              completed_compensations  jsonb NOT NULL DEFAULT '[]'::jsonb,
+              updated_at           timestamptz NOT NULL DEFAULT now(),
               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 idiom `rust/host/src/journal.rs`'s own
+          # `sagas_backfilled` column addition already uses, for the
+          # identical reason.
+          @db.exec("ALTER TABLE hecks_saga_instances ADD COLUMN IF NOT EXISTS completed_compensations jsonb NOT NULL DEFAULT '[]'::jsonb")
         end
 
         def sql_type(attr)
@@ -123,6 +139,29 @@ module Hecks
         # compiles a list `contains` to. An index here would be dead
         # weight, not free correctness, so none is attempted.
         def index_field!(field)
+          # A HOP PATH ("owner/field" — `Bluebook::AggregateBuilder`'s own
+          # convention for a field reached by crossing a reference,
+          # `aggregate_builder.rb`'s own `field.to_s.include?("/")`
+          # checks) IS NEVER INDEXED HERE — same reasoning as `list_of`
+          # below: `query_expression`/`nested_expression` below have no
+          # dialect for this shape at all (they'd compile the whole
+          # "owner/field" string as one bare column/jsonb-path segment,
+          # which is not a real column and errors PG::UndefinedColumn on
+          # `CREATE INDEX`, discovered fuzzing a real Postgres boot of
+          # `examples/banking` — Account's own `projects :customer_status,
+          # from: :"customer.status"` compiles to exactly this shape).
+          # Skipping the index is always safe, the same way skipping a
+          # `list_of` index is: an index is a perf optimization, not
+          # correctness, so "never built" beats "built wrong." Whether a
+          # hop-path field can be QUERIED at all against this adapter is
+          # a separate, still-open question this skip does not answer —
+          # see docs/future-features.md's fuzzer-adapter entry, and
+          # docs/1.0-readiness.md item 2 for this gap's OTHER two
+          # independent failure points (Postgres querying, Rust codegen's
+          # `OpenForSuspendedCustomers` — bin/rust_coverage's own
+          # allowlist) — tracked together, not as three unrelated bugs.
+          return if field.to_s.include?("/")
+
           name, *_path = field.to_s.split(".")
           attribute = @aggregate.attribute(name)
           return if attribute&.list?

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

@@ -49,7 +49,7 @@ module Hecks
 
       attr_reader :aggregate
 
-      def persistence_capabilities = [:atomic_put]
+      def persistence_capabilities = [:atomic_put, :optimistic_concurrency]
 
       def self.connect_for(name, settings)
         # LAZY, ON PURPOSE — same reasoning as PostgresEra's own
@@ -57,7 +57,7 @@ module Hecks
         # need the gem installed.
         require "pg"
 
-        declared = settings[:database] || settings["database"]
+        declared = settings.key?(:database) ? settings[:database] : settings["database"]
         if declared.to_s.empty?
           raise Runtime::WiringError,
                 "#{name} binds Postgres, which needs a database connection, " \
@@ -76,7 +76,7 @@ module Hecks
         # with other domains, so every unqualified reference this
         # adapter constructs resolves through search_path. A domain with
         # no `schema` setting keeps Postgres's own default (public).
-        schema = settings[:schema] || settings["schema"]
+        schema = settings.key?(:schema) ? settings[:schema] : settings["schema"]
         connection.exec("SET search_path TO #{connection.quote_ident(schema)}") if schema.to_s != ""
 
         # QUIET ON PURPOSE — same reasoning as PostgresEra's own: a
@@ -96,7 +96,15 @@ module Hecks
         # (§2/§4) — falls back to the aggregate's own storage name for a
         # directly-instantiated adapter (specs), same fallback shape
         # Sqlite's own @domain already uses.
-        @domain = (settings[:domain] || settings["domain"] || aggregate.storage_name).to_s
+        @domain = (
+          if settings.key?(:domain)
+            settings[:domain]
+          elsif settings.key?("domain")
+            settings["domain"]
+          else
+            aggregate.storage_name
+          end
+        ).to_s
 
         create_aggregate_table!
         create_entry_table!
@@ -110,7 +118,7 @@ module Hecks
         result = @db.exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
         return nil if result.ntuples.zero?
 
-        Runtime::Instance.new(aggregate: @aggregate, id: result[0]["id"], state: decode(result[0]))
+        instance_from_row(result[0])
       end
 
       # order_by IS A RUNTIME VALUE — see Sqlite#all's own reasoning;
@@ -126,9 +134,7 @@ module Hecks
           order_sql = "ORDER BY #{order_clause(spec, nil)}"
         end
 
-        @db.exec("SELECT * FROM #{quoted_table} #{order_sql}").map do |row|
-          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
-        end
+        @db.exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
       end
 
       def count = @db.exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
@@ -136,25 +142,55 @@ module Hecks
       def append(entry)
         @db.exec_params(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES ($1, $2, $3, $4)",
-          [entry.id, entry.operation, JSON.generate(entry.state), JSON.generate(entry.mirrors)]
+          # `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 `sqlite.rb`/
+          # `d1.rb`/`postgres_era.rb` already use for their own journal's
+          # `mirrors` column.
+          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
 
-      def project(entry)
+      # `expected_version:` requests optimistic-concurrency CAS (see
+      # `persistence_capabilities`/`Ports::Persistence::AppendOnly#save`).
+      # `hecks_version` is ADAPTER BOOKKEEPING — never in `persisted_fields`
+      # (Codec), so it never reaches `decode`'s domain-state hash. It goes
+      # in the INSERT column list at `1` (a genuinely new row) and bumps by
+      # one in the `ON CONFLICT DO UPDATE` branch; when `expected_version`
+      # is given, that UPDATE branch additionally requires
+      # `hecks_version = expected_version` to apply at all — Postgres's own
+      # `INSERT ... ON CONFLICT DO UPDATE ... WHERE`, which gates only
+      # whether the CONFLICT branch's update applies. A genuinely new row
+      # never reaches that branch at all, so it always inserts regardless
+      # of this WHERE. `RETURNING hecks_version` plus `ntuples.zero?` is
+      # how a real version mismatch is told apart from an ordinary write:
+      # zero rows back means the conflict branch's WHERE excluded the row
+      # entirely — the version had already moved — so `nil` is returned
+      # for the caller (`AppendOnly#save`) to treat as "stale, no-op".
+      def project(entry, expected_version: nil)
         return @db.exec_params("DELETE FROM #{quoted_table} WHERE id = $1", [entry.id]) if entry.delete?
 
         instance = Runtime::Instance.new(aggregate: @aggregate, id: entry.id, state: entry.state)
-        columns  = (["id"] + persisted_fields.map { |field| field[:name].to_s })
-        values   = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) }
-        updates  = persisted_fields.map { |field| "#{quote_ident(field[:name])} = EXCLUDED.#{quote_ident(field[:name])}" }
+        columns  = (["id"] + persisted_fields.map { |field| field[:name].to_s } + ["hecks_version"])
+        values   = [instance.id.to_s] + persisted_fields.map { |field| encode_field(field, instance[field[:name]]) } + [1]
+        updates  = persisted_fields.map { |field| "#{quote_ident(field[:name])} = EXCLUDED.#{quote_ident(field[:name])}" } +
+                   ["hecks_version = #{quoted_table}.hecks_version + 1"]
+
+        sql = "INSERT INTO #{quoted_table} (#{columns.map { |c| quote_ident(c) }.join(', ')}) " \
+              "VALUES (#{(1..columns.size).map { |n| "$#{n}" }.join(', ')}) " \
+              "ON CONFLICT (id) DO UPDATE SET #{updates.join(', ')}"
+        if expected_version
+          values += [expected_version]
+          sql += " WHERE #{quoted_table}.hecks_version = $#{values.size}"
+        end
+        sql += " RETURNING hecks_version"
 
-        @db.exec_params(
-          "INSERT INTO #{quoted_table} (#{columns.map { |c| quote_ident(c) }.join(', ')}) " \
-          "VALUES (#{(1..columns.size).map { |n| "$#{n}" }.join(', ')}) " \
-          "ON CONFLICT (id) DO UPDATE SET #{updates.join(', ')}",
-          values
-        )
+        result = @db.exec_params(sql, values)
+        return nil if result.ntuples.zero?
+
+        instance.version = result[0]["hecks_version"].to_i
         instance
       end
 
@@ -245,13 +281,14 @@ module Hecks
       # ── the OPTIONAL saga-persistence capability (§2) — same DDL and
       # shape as PostgresEra's own (postgres_era.rb), not lineage-
       # specific, copied verbatim.
-      def save_saga(process_manager:, correlation:, state:, memory:)
+      def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         @db.exec_params(
-          "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory) " \
-          "VALUES ($1, $2, $3, $4, $5) " \
+          "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
+          "VALUES ($1, $2, $3, $4, $5, $6) " \
           "ON CONFLICT (domain, process_manager, correlation) DO UPDATE " \
-          "SET state = EXCLUDED.state, memory = EXCLUDED.memory, updated_at = now()",
-          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory)]
+          "SET state = EXCLUDED.state, memory = EXCLUDED.memory, " \
+          "completed_compensations = EXCLUDED.completed_compensations, updated_at = now()",
+          [@domain, process_manager.to_s, correlation.to_s, state.to_s, JSON.generate(memory), JSON.generate(completed_compensations)]
         )
       end
 
@@ -266,11 +303,12 @@ module Hecks
         return enum_for(:each_saga) unless block_given?
 
         @db.exec_params(
-          "SELECT process_manager, correlation, state, memory FROM hecks_saga_instances WHERE domain = $1",
+          "SELECT process_manager, correlation, state, memory, completed_compensations FROM hecks_saga_instances WHERE domain = $1",
           [@domain]
         ).each do |row|
           yield row["process_manager"], row["correlation"], row["state"],
-                JSON.parse(row["memory"], symbolize_names: true)
+                JSON.parse(row["memory"], symbolize_names: true),
+                JSON.parse(row["completed_compensations"] || "[]", symbolize_names: true)
         end
       end
 
@@ -332,9 +370,18 @@ module Hecks
       end
 
       def execute_query(sql, binds)
-        @db.exec_params(sql, binds).map do |row|
-          Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
-        end
+        @db.exec_params(sql, binds).map { |row| instance_from_row(row) }
+      end
+
+      # Stamps `.version` (adapter bookkeeping, never domain state — see
+      # `Instance`'s own comment) from the row's `hecks_version` column on
+      # every Instance this adapter builds from a real stored row, so a
+      # later `save`'s optimistic-concurrency CAS has something to check
+      # against.
+      def instance_from_row(row)
+        instance = Runtime::Instance.new(aggregate: @aggregate, id: row["id"], state: decode(row))
+        instance.version = row["hecks_version"].to_i
+        instance
       end
 
       # ── the rest of the dialect ─────────────────────────────────────