openreceive-rails 0.4.10 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 624dd853dd3e316cd20bacb9a6c8f669ddb61558c6540d05da6000cc71d3efd2
-  data.tar.gz: b2acac5e32343925c1d6974cb7ee1451f4ea34335aec82921feebe05c33b90e8
+  metadata.gz: 9b819ffb0e4f2872cd4de6da728c6404804496da560443a928d54d0aa25a5ac6
+  data.tar.gz: 674d40eb671af219dbaafd038eb4e8bee4849649e8bf32d82bf3fd1f45405414
 SHA512:
-  metadata.gz: 86971442440a6ce6dc19c7f884ebac554e0a28999976ad6761b3843fbe1dee6daa9bb03087863e14f651d644140be222dace9e84df6b37de823af5b4151c71a0
-  data.tar.gz: 1cf150cc363e76166a216f830a550a42d4615f0c99f287f9e9d69dc537fd60754e1fc26e3a1558a584b33056c88a49ccfe23d420ab565fdb4b4a14c65f3cfbeb
+  metadata.gz: a2ad30551213e01ce2fce1ccd0f083d0a26aacf8782a0e38d78c8e628d5a8bf68ebb765ba122fc8c9f8375c375bf7582e0fce8f92a5c8902d6e5a0f7effece7e
+  data.tar.gz: 16b67e1d5797202128acb827f388f371c6d391158c5227f6d8f5acf5fd530b2f3b32604ebbe81609b51cf03b4049f6fcf41a756cf5e81c8119c986e4eec466e9

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.11 - 2026-09-21
+
+Reconciliation progress is durable and bounded. A capped wallet walk now
+stores its window — attempt identities, page offset, view and page
+fingerprint — in `OpenReceive::ReconcileScan`, so the next request or worker
+resumes where the last one stopped instead of restarting the history, and a
+resumed scan is never treated as proof that a payment is absent. Scans carry
+a deadline into the wallet request, and fulfillment commits in the same
+transaction as settlement.
+
+The default repository maps an unexpected persistence failure to
+`HostPersistenceError` (retryable 503, payer instructions withheld) rather
+than letting it surface as an unrelated error.
+
 ## 0.4.10 - 2026-09-16
 
 Release alongside the packaged checkout fix that shows one amount to send

data/README.md

@@ -98,3 +98,36 @@ overrides it. Keep ordinary settings such as `config.price_currencies` in
 - Changelog: [CHANGELOG.md](CHANGELOG.md)
 
 MIT license.
+
+### Reconciliation upgrades and operator recovery
+
+Explicit jobs, the notifications worker, notification fallback and mounted routes
+share the durable lease/CAS gate and bounded scheduler. Disabling
+`opportunistic_reconcile` disables request triggers only. Stop old application and
+worker processes before deploying this scheduler contract, then start the updated
+processes together. Resumed history slices discover positive wallet finality but
+never prove absence; unpaid dense histories stay pending until a fresh complete
+covering scan fits the budget. Deposit countdown/reuse expiry remains separate
+from the saved Lightning invoice's settlement deadline.
+
+`OpenReceivePayment.maintenance_candidates(after: cursor, limit: 100)` is a
+read-only report with `candidates`, `next_cursor` and `scanned`. An operator can
+review a selected candidate and call
+`OpenReceivePayment.requeue_reviewed_attempt!(candidate, decision_id: "ticket-42")`.
+The model checks the unchanged row under its reference lock, records the decision
+in `openreceive_meta`, and requeues it without granting fulfillment. The ordinary
+gated reconciler must still discover wallet finality. Settled rows remain
+immutable, and genuine sibling payments never grant a second entitlement.
+Candidates distinguish early swap-deadline closure from ordinary operator
+attention; reports contain no swap credentials. Follow the
+[coordinated upgrade guide](https://github.com/OpenReceive/openreceive/blob/master/docs/guides/payment-safety-upgrade.md).
+
+MySQL repository operations require an outermost transaction; wrapping them in
+an ambient ActiveRecord transaction is rejected before taking the named lock.
+
+Fulfillment database writes and a host outbox belong in `on_paid`; a callback can
+run again after rollback. External jobs need their own durable idempotency.
+Storage-free `openreceive-server` handlers can call `on_paid` on every settled
+poll, so advanced hosts own the conditional write/outbox. A raw create hook
+refusal returns 409 with instructions withheld; repository infrastructure failures
+remain retryable 503.

data/app/models/open_receive_meta.rb

@@ -68,29 +68,58 @@ class OpenReceiveMeta < ActiveRecord::Base
     end
   end
 
-  # Claim the durable global reconcile gate. Returns true when this caller may
-  # run a wallet scan now; false (gate_busy) when another worker scanned within
-  # interval_seconds. The winner is identified by reading back its own token —
-  # the portable equivalent of an affected-row count, matching the JS
-  # claimReconcileGate. A failed scan leaves claimed_at in place on purpose —
-  # the next interval retries without a stampede.
-  def self.claim_reconcile_gate(now:, interval_seconds:)
+  # The durable global scan gate returns a token/scheduler claim or nil.
+  # Checkpoints require that token and an unexpired lease; failed scans retain
+  # the interval and pre-scan queue so another worker can retry fairly.
+  def self.claim_reconcile_gate(now:, interval_seconds:, lease_seconds: 10)
     assert_supported_schema!
-    claim = JSON.generate("claimed_at" => Integer(now), "token" => SecureRandom.uuid)
+    now = Integer(now)
     CAS_RETRIES.times do
       row = find_by(key: RECONCILE_GATE_KEY)
-      if row.nil?
-        cas(RECONCILE_GATE_KEY, claim, nil)
-      else
-        claimed_at = parse_claimed_at(row.value)
-        if claimed_at && fresh_timestamp?(Integer(now), claimed_at, Integer(interval_seconds))
-          return false
-        end
-        cas(RECONCILE_GATE_KEY, claim, row.rev)
-      end
-      return true if where(key: RECONCILE_GATE_KEY).pick(:value) == claim
+      current = parse_gate(row&.value)
+      claimed = current["claimed_at"]
+      return nil if claimed && fresh_timestamp?(now, claimed, interval_seconds)
+      return nil if current.fetch("lease_until", 0) > now && current.fetch("claimed_at", 0) <= now + 60
+
+      gate = {
+        "version" => 1, "claimed_at" => now, "token" => SecureRandom.uuid,
+        "lease_until" => now + lease_seconds, "interval_seconds" => interval_seconds,
+        "scheduler" => current.fetch("scheduler", { "cursor" => nil, "windows" => [] })
+      }
+      next unless cas(RECONCILE_GATE_KEY, JSON.generate(gate), row&.rev)
+
+      return { "token" => gate.fetch("token"), "scheduler" => gate.fetch("scheduler") }
     end
-    false
+    nil
+  end
+
+  def self.checkpoint_reconcile_gate(claim, scheduler, now:, release: false)
+    assert_supported_schema!
+    row = find_by(key: RECONCILE_GATE_KEY)
+    return false if row.nil?
+
+    gate = parse_gate(row.value)
+    return false unless gate["token"] == claim.fetch("token") && gate.fetch("lease_until", 0) > now
+
+    windows = scheduler.fetch("windows")
+    raise ArgumentError, "Reconciliation checkpoint exceeded bounded cohorts" if windows.length > 2 || windows.any? { |w| w.fetch("attempts").length > 200 }
+
+    gate["scheduler"] = scheduler
+    gate["lease_until"] = 0 if release
+    encoded = JSON.generate(gate)
+    raise ArgumentError, "Reconciliation checkpoint exceeded 128 KiB" if encoded.bytesize > 128 * 1024
+
+    cas(RECONCILE_GATE_KEY, encoded, row.rev)
+  end
+
+  def self.parse_gate(value)
+    gate = value.nil? ? {} : JSON.parse(value.to_s)
+    gate = {} unless gate.is_a?(Hash)
+    raise OpenReceive::ConfigurationError, "Unsupported reconciliation checkpoint version; upgrade OpenReceive." if gate.fetch("version", 0) > 1
+
+    gate["version"] == 1 ? gate : { "scheduler" => { "cursor" => nil, "windows" => [] } }
+  rescue JSON::ParserError
+    { "scheduler" => { "cursor" => nil, "windows" => [] } }
   end
 
   def self.stored_schema_version
@@ -113,13 +142,5 @@ class OpenReceiveMeta < ActiveRecord::Base
     age < window_seconds
   end
 
-  def self.parse_claimed_at(value)
-    parsed = JSON.parse(value.to_s)
-    claimed_at = parsed["claimed_at"]
-    claimed_at.is_a?(Numeric) ? Integer(claimed_at) : nil
-  rescue JSON::ParserError
-    nil
-  end
-
-  private_class_method :stored_schema_version, :fresh_timestamp?, :parse_claimed_at
+  private_class_method :stored_schema_version, :fresh_timestamp?
 end

data/app/models/open_receive_payment.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "digest"
+require "time"
 
 # Engine-owned payment attempts. The table lives in the host application's
 # database (the install generator emits the migration), but the schema, locking,
@@ -88,6 +89,10 @@ class OpenReceivePayment < ActiveRecord::Base
   # COMMIT — releasing inside the transaction would leave a window where a
   # second worker could commit against state this one has already read.
   def self.with_mysql_reference_lock(key)
+    if connection.transaction_open?
+      raise RuntimeError, "OpenReceive MySQL reference operations require an outermost transaction; ambient transactions cannot retain the connection-scoped reference lock."
+    end
+
     name = "openreceive:#{Digest::SHA256.hexdigest(key)[0, 40]}"
     acquired = connection.select_value(
       sanitize_sql_array(["SELECT GET_LOCK(?, ?)", name, MYSQL_LOCK_TIMEOUT_SECONDS])
@@ -218,7 +223,7 @@ class OpenReceivePayment < ActiveRecord::Base
 
     with_reference_lock(payment.reference) do
       payment.reload
-      return payment if payment.status == "settled"
+      return payment unless payment.status == "pending"
 
       first_for_order = !where(reference: payment.reference).settled.exists?
       payment.update!(
@@ -240,11 +245,16 @@ class OpenReceivePayment < ActiveRecord::Base
       raise ArgumentError, "invalid reconciliation status: #{status_text}"
     end
 
-    where(payment_hash: payment_hash.to_s.downcase, status: "pending").update_all(
-      status: status_text,
-      status_reason: reason,
-      updated_at: Time.at(Integer(observed_at)).utc
-    )
+    payment = find_by(payment_hash: payment_hash.to_s.downcase)
+    return if payment.nil?
+
+    with_reference_lock(payment.reference) do
+      where(payment_hash: payment.payment_hash, status: "pending").update_all(
+        status: status_text,
+        status_reason: reason,
+        updated_at: Time.at(Integer(observed_at)).utc
+      )
+    end
   end
 
   # Pending attempts for the reconciler's next wallet scan — oldest first, one
@@ -252,19 +262,103 @@ class OpenReceivePayment < ActiveRecord::Base
   # closest to their closure deadline are always covered, and a backlog drains
   # over several passes instead of widening one wallet scan window without
   # bound. Terminal rows never return.
-  def self.reconcilable_attempts
+  def self.reconcilable_attempts(after: nil, limit: OpenReceive::Server::RECONCILE_BATCH_SIZE)
     OpenReceiveMeta.assert_supported_schema!
-    pending.order(created_at: :asc)
-           .limit(OpenReceive::Server::RECONCILE_BATCH_SIZE)
-           .pluck(:payment_hash, :created_at, :expires_at).map do |hash, created_at, expires_at|
+    query = pending.order(created_at: :asc, payment_hash: :asc)
+    if after
+      created = Time.at(after.fetch("created_at")).utc
+      query = query.where("created_at > ? OR (created_at = ? AND payment_hash > ?)", created, created, after.fetch("payment_hash"))
+    end
+    query.limit([limit, OpenReceive::Server::RECONCILE_BATCH_SIZE].min)
+         .pluck(:payment_hash, :created_at, :checkout_data).map do |hash, created_at, checkout|
       {
-        "payment_hash" => hash,
-        "created_at" => created_at.to_i,
-        "expires_at" => expires_at.to_i
+        "payment_hash" => hash, "created_at" => created_at.to_i,
+        "expires_at" => settlement_expires_at(checkout, hash),
+        "created_at_source" => checkout["created_at_source"] || checkout[:created_at_source] || "host"
       }
     end
   end
 
+  # Same reconciliation DTO for authenticated by-hash notification lookup.
+  def self.find_pending_attempt(payment_hash)
+    OpenReceiveMeta.assert_supported_schema!
+    row = pending.where(payment_hash: payment_hash.to_s.downcase).pick(:payment_hash, :created_at, :checkout_data)
+    return nil if row.nil?
+
+    hash, created_at, checkout = row
+    {
+      "payment_hash" => hash, "created_at" => created_at.to_i,
+      "expires_at" => settlement_expires_at(checkout, hash),
+      "created_at_source" => checkout["created_at_source"] || checkout[:created_at_source] || "host"
+    }
+  end
+
+  # Saved Lightning deadline, independent of the payer's deposit countdown.
+  def self.settlement_expires_at(checkout, payment_hash)
+    value = checkout[:expires_at] || checkout["expires_at"] || checkout[:expiresAt] || checkout["expiresAt"]
+    raise ArgumentError unless value.is_a?(Integer) || (value.is_a?(String) && value.match?(/\A[0-9]+\z/))
+
+    expiry = Integer(value)
+    raise ArgumentError if expiry <= 0
+
+    expiry
+  rescue TypeError, ArgumentError, NoMethodError
+    raise RuntimeError, "Corrupt checkout_data wallet expiry on openreceive payment attempt #{payment_hash}."
+  end
+
+  # Host-invoked dry-run report. Normal routes never read terminal repair candidates.
+  def self.maintenance_candidates(after: nil, limit: 100)
+    OpenReceiveMeta.assert_supported_schema!
+    limit = [[limit, 1].max, 1000].min
+    query = where(status: %w[attention expired])
+    if after
+      stamp = Time.iso8601(after.fetch("updated_at"))
+      query = query.where("updated_at > ? OR (updated_at = ? AND payment_hash > ?)", stamp, stamp, after.fetch("payment_hash"))
+    end
+    rows = query.order(:updated_at, :payment_hash).limit(limit).to_a
+    cursor = rows.length == limit ? { "updated_at" => rows.last.updated_at.utc.iso8601(6), "payment_hash" => rows.last.payment_hash } : nil
+    { "candidates" => rows.filter_map { |row| repair_candidate(row) }, "next_cursor" => cursor, "scanned" => rows.length }
+  end
+
+  def self.requeue_reviewed_attempt!(candidate, decision_id:)
+    OpenReceiveMeta.assert_supported_schema!
+    unless /\A[A-Za-z0-9._:-]{1,120}\z/.match?(decision_id.to_s)
+      raise ArgumentError, "decision_id must be a nonsecret operator ticket identifier."
+    end
+    payment = find_by(payment_hash: candidate.fetch("payment_hash"))
+    return false if payment.nil?
+
+    with_reference_lock(payment.reference) do
+      payment.reload
+      return false unless repair_candidate(payment) == candidate
+
+      audit_key = "repair:#{payment.payment_hash}:#{decision_id}"
+      return false if OpenReceiveMeta.exists?(key: audit_key)
+
+      audit = candidate.merge("decision_id" => decision_id, "requeued_at" => Time.now.to_i)
+      OpenReceiveMeta.create!(key: audit_key, value: JSON.generate(audit), rev: 0)
+      payment.update!(status: "pending", status_reason: "operator_requeued")
+      true
+    end
+  end
+
+  def self.repair_candidate(row)
+    return nil unless %w[attention expired].include?(row.status)
+
+    wallet_expiry = settlement_expires_at(row.checkout_data, row.payment_hash)
+    reason = row.status == "attention" ? "operator_attention" : nil
+    if row.swap_data.present? && %w[not_found_after_expiry no_finality_after_expiry unsettled_after_expiry].include?(row.status_reason) &&
+       wallet_expiry > row.expires_at.to_i && row.updated_at.to_i >= row.expires_at.to_i + 900 && row.updated_at.to_i < wallet_expiry + 900
+      reason = "early_deposit_deadline_closure"
+    end
+    return nil if reason.nil?
+
+    { "reference" => row.reference, "payment_hash" => row.payment_hash,
+      "status" => row.status, "status_reason" => row.status_reason,
+      "updated_at" => row.updated_at.utc.iso8601(6), "instruction_expires_at" => row.expires_at.to_i,
+      "wallet_expires_at" => wallet_expiry, "reason" => reason }
+  end
+
   def self.reusable?(payment, now = Time.current)
     payment.expires_at.to_i - now.to_i > REUSE_BUFFER_SECONDS
   end

data/lib/openreceive/configuration.rb

@@ -359,6 +359,8 @@ module OpenReceive
           # 409 CONFLICT. Leaving AttemptConflict unwrapped lets request_handler
           # #commit treat it as infrastructure failure (retryable 503 persist).
           raise OpenReceive::Server::ConflictError, e.message
+        rescue StandardError
+          raise OpenReceive::Server::HostPersistenceError
         end
       end
     end

data/lib/openreceive/generated/fulfillment_note.rb

@@ -13,13 +13,22 @@ module OpenReceive
       "",
       "WHAT OPENRECEIVE GUARANTEES",
       "",
-      "Across every settlement path OpenReceive itself owns (wallet notifications,",
-      "the opportunistic reconcile pass, an explicit reconcile job), the settlement",
-      "hook runs AT MOST ONCE per reference. The library serializes on its own",
-      "`{{table}}` rows, decides the winner there, and runs your hook",
-      "inside that same transaction. A second payment to a second invoice for the",
-      "same order is still recorded - with `status_reason = 'duplicate_settlement'`",
-      "- but never fulfills a second time. You do not need to add a lock for this.",
+      "Repository-backed settlement paths (wallet notifications, gated reconciliation,",
+      "and explicit jobs) commit fulfillment for only the first settled attempt per",
+      "reference. The library locks its `{{table}}` rows, decides the winner,",
+      "and awaits your hook inside the same database transaction. A failure rolls",
+      "back payment and host writes together; the hook can run again on a retry.",
+      "A genuine second payment is still recorded with",
+      "`status_reason = 'duplicate_settlement'`, without another fulfillment.",
+      "",
+      "Write an entitlement or an outbox job through the supplied transaction. Email,",
+      "shipping APIs, and other external effects cannot commit atomically with it;",
+      "your outbox worker must use durable idempotency for external delivery.",
+      "A best-effort after-paid callback may be lost after commit and is not an outbox.",
+      "",
+      "Raw storage-free handlers do not provide this transaction: their on_paid hook",
+      "may run on every settled poll. Those hosts own the durable conditional write",
+      "or outbox themselves; process-local deduplication does not replace it.",
       "",
       "That makes the reference the unit of fulfillment: give every payable order",
       "its own reference, created before checkout, kept across retries, and never",
@@ -51,7 +60,7 @@ module OpenReceive
       "conditional UPDATE, take a row lock for the duration instead:",
       "",
       "  SELECT * FROM orders WHERE id = :reference FOR UPDATE;  -- postgres/mysql",
-      "  -- ...check state, ship, write the new state, all before COMMIT.",
+      "  -- ...check state, grant entitlement/enqueue work, all before COMMIT.",
       "",
       "Run either one inside the transaction OpenReceive hands your settlement",
       "hook, so the order transition and the payment record commit together.",

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.10"
+    VERSION = "0.4.11"
   end
 end

data/lib/openreceive/reconcile.rb

@@ -2,17 +2,15 @@
 
 require "json"
 require "openreceive/server"
+require "openreceive/reconcile_scan"
 
 module OpenReceive
   # Floor for the durable reconcile-gate interval (seconds); stretched by
   # invoice age (2s while any pending invoice is under 2 minutes old, 6s under
   # 5 minutes, else 12s). Mirrors the JS OPENRECEIVE_MIN_RECONCILE_INTERVAL_SECONDS.
   MIN_RECONCILE_INTERVAL_SECONDS = 2
-  # Wall-clock bound on an awaited request-path pass. Enforced as a deadline
-  # the wallet scan checks between page fetches rather than a Timeout.timeout:
-  # Thread#raise at an arbitrary point could tear down an ActiveRecord
-  # connection or kill a host's on_paid fulfillment mid-flight, on every
-  # winning request. A pass that runs out of budget simply stops walking.
+  # The deadline reaches the wallet adapter, which bounds only network I/O.
+  # Never interrupt the whole pass: it also runs host/database transactions.
   RECONCILE_SCAN_TIMEOUT_SECONDS = 9
   # Wallet-history pages a request-path pass may walk, mirroring the JS
   # OPENRECEIVE_RECONCILE_SCAN_MAX_PAGES.
@@ -29,8 +27,8 @@ module OpenReceive
     # from a successful wallet scan result observed at or after expiry plus
     # OpenReceive::Server::Reconciliation::EXPIRY_GRACE_SECONDS — a local clock
     # alone never closes a row, because a payment could have settled while the
-    # application was offline. A wallet failure raises and leaves every row
-    # pending for the next pass, and a hash absent from the pass results (a
+    # application was offline. A later wallet failure preserves already committed
+    # finality and leaves unresolved rows pending. A hash absent from pass results (a
     # truncated scan never proved it absent) is no information — the attempt
     # stays untouched.
     #
@@ -41,34 +39,6 @@ module OpenReceive
     # { "payment_hash", "status", "paid_at"?, "details"? } hashes) so callers —
     # notably payments/check — can serve a requested hash straight from the
     # pass instead of adding a second per-invoice wallet walk.
-    def reconcile!(overlap_seconds: 60, now: nil, max_pages: nil, deadline: nil)
-      attempts = OpenReceivePayment.reconcilable_attempts
-      return [] if attempts.empty?
-
-      observed_at = Integer(now || Time.now.to_i)
-      request = {
-        "attempts" => attempts,
-        "overlap_seconds" => overlap_seconds,
-        "until" => observed_at + overlap_seconds
-      }
-      request["max_pages"] = max_pages unless max_pages.nil?
-      request["deadline"] = deadline unless deadline.nil?
-      results = config.service.reconcile_payments(request)
-      log_reconcile_pass(attempts, results, overlap_seconds, observed_at)
-      by_hash = attempts.to_h { |attempt| [attempt.fetch("payment_hash"), attempt] }
-      results.each do |checked|
-        attempt = by_hash[checked.fetch("payment_hash")]
-        next if attempt.nil?
-
-        if checked["status"] == "settled" && checked["paid_at"]
-          settle_attempt(checked)
-        else
-          record_attempt_transition(attempt, checked, observed_at)
-        end
-      end
-      results
-    end
-
     # Opportunistic settlement discovery, piggybacked on any OpenReceive call
     # (the engine's around_action runs it before every mounted route): skip
     # without a wallet call when nothing is pending, try the durable
@@ -87,30 +57,99 @@ module OpenReceive
       setting = config.opportunistic_reconcile
       return { "reason" => "disabled" } if setting == false
 
+      gated_reconcile!(now: now)
+    end
+
+    def reconcile!(overlap_seconds: 60, now: nil)
+      gated_reconcile!(overlap_seconds: overlap_seconds, now: now).fetch("checks", [])
+    end
+
+    def gated_reconcile!(overlap_seconds: 60, now: nil)
       attempts = OpenReceivePayment.reconcilable_attempts
       return { "reason" => "no_pending" } if attempts.empty?
 
       observed_at = Integer(now || Time.now.to_i)
-      interval = reconcile_gate_interval_seconds(attempts, observed_at, setting)
-      unless OpenReceiveMeta.claim_reconcile_gate(now: observed_at, interval_seconds: interval)
-        # Another worker scanned within the interval; this request pays nothing.
-        openreceive_logger&.debug(
-          "[openreceive] opportunistic reconcile: gate_busy " \
-          "(#{attempts.length} pending, interval #{interval}s)"
-        )
-        return { "reason" => "gate_busy" }
+      interval = reconcile_gate_interval_seconds(attempts, observed_at, config.opportunistic_reconcile)
+      claim = OpenReceiveMeta.claim_reconcile_gate(now: observed_at, interval_seconds: interval)
+      return { "reason" => "gate_busy" } if claim.nil?
+
+      scheduler = claim.fetch("scheduler")
+      windows = scheduler.fetch("windows")
+      if windows.length < 2
+        candidates = OpenReceivePayment.reconcilable_attempts(after: scheduler["cursor"])
+        if candidates.empty?
+          scheduler["cursor"] = nil
+          candidates = OpenReceivePayment.reconcilable_attempts
+        end
+        unless candidates.empty?
+          last = candidates.last
+          scheduler["cursor"] = candidates.length < Server::RECONCILE_BATCH_SIZE ? nil : last.slice("created_at", "payment_hash")
+          queued = windows.flat_map { |w| w.fetch("attempts").map { |a| a.fetch("payment_hash") } }
+          cohort = candidates.reject { |a| queued.include?(a.fetch("payment_hash")) }
+          windows << ReconcileScan.new_window(cohort, observed_at, overlap_seconds) unless cohort.empty?
+        end
+      end
+      window = windows.shift
+      # Checkpoint without the active window, so failures and process loss free
+      # its slot. Pending rows return on cursor wrap; successful slices resume.
+      checkpoint_now = now.nil? ? Time.now.to_i : observed_at
+      return { "reason" => "gate_busy" } unless OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now)
+      if window.nil?
+        OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now, release: true)
+        return { "reason" => "no_pending" }
       end
 
-      checks = reconcile!(
-        now: observed_at,
+      by_hash = window.fetch("attempts").to_h { |a| [a.fetch("payment_hash"), a] }
+      delivered = {}
+      before_scan = JSON.parse(JSON.generate(scheduler))
+      deliver_finality = lambda do |checked|
+        hash = checked.fetch("payment_hash")
+        current = now.nil? ? Time.now.to_i : observed_at
+        unless OpenReceiveMeta.checkpoint_reconcile_gate(claim, before_scan, now: current)
+          delivered[hash] = false
+          next
+        end
+        if checked["status"] == "settled" && checked["paid_at"]
+          delivered[hash] = settle_attempt(checked)
+        else
+          record_attempt_transition(by_hash.fetch(hash), checked, observed_at)
+          delivered[hash] = true
+        end
+      end
+      checks, complete, stalled = ReconcileScan.slice(config.service, window,
         max_pages: RECONCILE_SCAN_MAX_PAGES,
-        deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + RECONCILE_SCAN_TIMEOUT_SECONDS
-      )
-      { "reason" => "ran", "checks" => checks }
+        deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + RECONCILE_SCAN_TIMEOUT_SECONDS, on_finality: deliver_finality)
+      lease_owned = OpenReceiveMeta.checkpoint_reconcile_gate(claim, before_scan, now: now.nil? ? Time.now.to_i : observed_at)
+      committed = checks.filter_map do |checked|
+        if delivered.key?(checked.fetch("payment_hash"))
+          next unless delivered.fetch(checked.fetch("payment_hash"))
+        elsif checked["status"] == "settled" && checked["paid_at"]
+          next
+        else
+          next unless lease_owned
+
+          record_attempt_transition(by_hash.fetch(checked.fetch("payment_hash")), checked,
+            checked.fetch("_coverage_started_at", observed_at))
+        end
+        checked.reject { |key, _| key.start_with?("_") }
+      end
+      unless complete || stalled
+        times = window.fetch("attempts").map { |a| a.fetch("created_at") }.uniq.sort
+        if windows.empty? && times.length > 1 && window.fetch("attempts").all? { |a| a["created_at_source"] == "wallet" }
+          middle = times[times.length / 2]
+          window.fetch("attempts").partition { |a| a.fetch("created_at") < middle }.each do |half|
+            windows << ReconcileScan.new_window(half, observed_at, overlap_seconds)
+          end
+        else
+          windows << window
+        end
+      end
+      checkpoint_now = now.nil? ? Time.now.to_i : observed_at
+      OpenReceiveMeta.checkpoint_reconcile_gate(claim, scheduler, now: checkpoint_now, release: true)
+      log_reconcile_pass(window.fetch("attempts"), committed, window)
+      { "reason" => "ran", "checks" => committed }
     rescue StandardError => e
-      openreceive_logger&.warn(
-        "[openreceive] opportunistic reconcile failed (will retry): #{sanitize_failure_message(e)}"
-      )
+      openreceive_logger&.warn("[openreceive] reconciliation failed (will retry): #{sanitize_failure_message(e)}")
       { "reason" => "scan_failed" }
     end
 
@@ -172,13 +211,12 @@ module OpenReceive
     # `openreceive:notifications` worker — the process most likely to see a
     # connect error — logs failures of its own.
     def sanitize_failure_message(error)
-      "#{error.class}: #{error.message}"
-        .gsub(/nostr\+walletconnect:[^\s"'`<>]+/, "[REDACTED_NWC]")
-        .gsub(/lightning\+swapconnect:[^\s"'`<>]+/, "[REDACTED_LSC]")
+      OpenReceive::Nwc.redact_error_text("#{error.class}: #{error.message}")
     end
 
     private
 
+
     # Rails.logger when the engine runs inside Rails; nil in bare-gem tests.
     # Settlement behavior never depends on logging.
     def openreceive_logger
@@ -196,11 +234,13 @@ module OpenReceive
         "paid_at" => checked.fetch("paid_at"),
         "details" => checked["details"]
       )
+      OpenReceivePayment.where(payment_hash: checked.fetch("payment_hash"), status: "settled").exists?
     rescue StandardError => e
       openreceive_logger&.warn(
         "[openreceive] settlement for #{checked.fetch('payment_hash')} failed " \
         "(will retry next pass): #{sanitize_failure_message(e)}"
       )
+      false
     end
 
     # Closure is decided by the shared reconciliation rules from a scan result
@@ -233,7 +273,7 @@ module OpenReceive
     # never one wallet call per invoice. One short line per poll: this fires
     # on every status poll while a payer waits. Mirrors the JS
     # payment.reconcile.completed line.
-    def log_reconcile_pass(attempts, results, overlap_seconds, observed_at)
+    def log_reconcile_pass(attempts, results, window)
       logger = openreceive_logger
       return if logger.nil?
 
@@ -245,10 +285,9 @@ module OpenReceive
       decided = ["0 decided"] if decided.empty?
       # Attempts scanned vs hashes decided: a gap is how a truncated scan shows up.
       scanned = results.length == attempts.length ? "" : " of #{attempts.length} attempts"
-      window_from = [attempts.map { |attempt| Integer(attempt.fetch("created_at")) }.min - overlap_seconds, 0].max
       logger.info(
         "[openreceive] payment.reconcile.completed: #{decided.join(', ')}#{scanned} " \
-        "attempt_count=#{attempts.length} window=#{window_from}..#{observed_at + overlap_seconds}"
+        "attempt_count=#{attempts.length} window=#{window.fetch("from")}..#{window["until"] || "unbounded"}"
       )
     rescue StandardError
       # Diagnostics must never affect the pass.
@@ -303,7 +342,7 @@ module OpenReceive
       payment_hash = transaction["payment_hash"].to_s.downcase
       return false if payment_hash.empty?
 
-      return false unless OpenReceivePayment.pending.where(payment_hash: payment_hash).exists?
+      return false if OpenReceivePayment.find_pending_attempt(payment_hash).nil?
 
       observed_at = Time.now.to_i
       config.settlement_hook.call(
@@ -315,7 +354,7 @@ module OpenReceive
           "paid_at_source" => transaction["settled_at"] ? "settled_at" : "observed_at"
         }
       )
-      true
+      OpenReceivePayment.where(payment_hash: payment_hash, status: "settled").exists?
     rescue StandardError
       # A direct-settlement failure falls back to the scan-based safety net.
       false

data/lib/openreceive/reconcile_scan.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module OpenReceive
+  # Durable scan slices store only identities, offsets and minimal classifications.
+  module ReconcileScan
+    module_function
+
+    def new_window(attempts, now, overlap)
+      trusted = attempts.all? { |a| a["created_at_source"] == "wallet" }
+      {
+        "attempts" => attempts,
+        "from" => trusted ? [attempts.map { |a| a.fetch("created_at") }.min - overlap, 0].max : 0,
+        "until" => trusted ? attempts.map { |a| a.fetch("created_at") }.max + overlap : nil,
+        "view" => "default", "offset" => 0, "anchor_offset" => nil, "fingerprint" => nil,
+        "started_at" => now, "absence_safe" => true, "observations" => {}
+      }
+    end
+
+    def slice(service, window, max_pages:, deadline:, on_finality: nil)
+      results = {}
+      expected = window.fetch("attempts").map { |a| a.fetch("payment_hash") }
+      resumed = window.fetch("offset").positive? || window.fetch("view") != "default"
+      window["absence_safe"] = false if resumed
+      anchor = resumed ? window["anchor_offset"] : nil
+      replaying = !anchor.nil?
+      previous = window["fingerprint"]
+      max_pages.times do
+        break if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        offset = replaying ? anchor : window.fetch("offset")
+        request = { "type" => "incoming", "limit" => 20, "offset" => offset, "from" => window.fetch("from") }
+        request["until"] = window["until"] unless window["until"].nil?
+        request["unpaid"] = true if window.fetch("view") == "inclusive"
+        request["_deadline"] = deadline
+        page = OpenReceive.normalize_list_transactions_response(service.send(:call_nwc, :list_transactions, request))
+        return [results.values, false, false] if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+        rows = page.fetch("transactions")
+        physical = rows.length + page.fetch("skipped_rows", 0)
+        fingerprint = Digest::SHA256.hexdigest(JSON.generate(rows.map { |row| row["payment_hash"] }))
+        rows.each do |row|
+          hash = row["payment_hash"]
+          next unless expected.include?(hash) && [nil, "incoming"].include?(row["type"])
+          next if window.fetch("observations").dig(hash, "status") == "settled"
+
+          status = OpenReceive::Settlement.status(row)
+          if %w[settled expired failed].include?(status)
+            results[hash] = service.send(:payment_result, hash, row)
+            on_finality&.call(results[hash]) if Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
+          end
+          window.fetch("observations")[hash] = { "status" => status, "transaction_state" => row["transaction_state"] }
+        end
+        if replaying
+          replaying = false
+          window["offset"] = offset + physical
+          previous = fingerprint
+          unless physical.zero?
+            window["anchor_offset"] = offset
+            window["fingerprint"] = fingerprint
+            next
+          end
+        end
+        if physical.zero?
+          if window.fetch("view") == "default"
+            window.merge!("view" => "inclusive", "offset" => 0, "anchor_offset" => nil, "fingerprint" => nil)
+            previous = nil
+            next
+          end
+          if window.fetch("absence_safe")
+            expected.each do |hash|
+              observation = window.fetch("observations")[hash]
+              next if results.key?(hash) || %w[settled expired failed].include?(observation&.fetch("status"))
+
+              result = { "payment_hash" => hash, "status" => observation.nil? ? "not_found" : observation.fetch("status"), "_coverage_started_at" => window.fetch("started_at") }
+              result["details"] = { "transaction" => { "transaction_state" => observation["transaction_state"] } } unless observation.nil?
+              results[hash] = result
+            end
+          end
+          return [results.values, true, false]
+        end
+        return [results.values, false, true] if fingerprint == previous
+
+        window.merge!("anchor_offset" => offset, "fingerprint" => fingerprint, "offset" => offset + physical)
+        previous = fingerprint
+        return [results.values, true, false] if expected.all? { |hash| %w[settled expired failed].include?(window.fetch("observations").dig(hash, "status")) }
+      end
+      [results.values, false, false]
+    end
+  end
+end

data/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
@@ -119,6 +119,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the plugin itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -157,9 +159,9 @@ invoices, checkout, webhooks and Greenfield API are the host.
 
 In BTCPay, open **Server Settings → Plugins**, search the plugin directory
 for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
-BTCPay creates the plugin's one table (`openreceive_swaps`, schema
-`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
-else is created.
+BTCPay creates the plugin's two tables (`openreceive_invoices` and
+`openreceive_swaps`, schema `BTCPayServer.Plugins.OpenReceive`) in its own
+Postgres at startup; nothing else is created.
 
 To build the plugin from source instead, follow
 [the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).

data/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -130,7 +130,7 @@ itself, and they hold for every integration.
   a placeholder that allows everything (`manage.py check` warns
   `openreceive.W002` while it is set) — replace it with this app's real
   ownership check, same as `on_paid`.
-- `on_paid` must be idempotent. It runs once per `reference` — your order
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -307,6 +307,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -480,7 +482,7 @@ The host class needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read the Starlette request's session, cookie or
   auth dependency; never trust a body field.
-- `on_paid` must be idempotent. It runs once per `reference` — your order id, one
+- `on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -301,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -475,7 +477,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `on_paid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -524,7 +526,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A page without a bundler renders the same checkout as a custom element:
 `<openreceive-checkout reference="…" prefix="/openreceive">` from

data/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -107,7 +107,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -284,6 +284,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -477,7 +479,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -526,7 +528,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -121,7 +121,7 @@ itself, and they hold for every integration.
   scaffolds `use AllowAllAuthorize;`, a placeholder trait that allows
   everything (the engine warns at boot while it is there) — replace it with
   this app's real ownership check, same as `onPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -291,6 +291,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -456,7 +458,7 @@ variable as set/unset only.
 price, and fulfillment. All three receive the `reference` — a string you
 choose, and the fulfillment identity: your order id, one per thing you
 fulfill, created before checkout, kept across retries, never reused.
-OpenReceive never looks inside it, but `onPaid` runs once per reference, a new
+OpenReceive never looks inside it, but `onPaid` commits fulfillment once per reference, a new
 checkout under a reference that already settled is refused with 409, and a
 fresh id per page load lets one order be paid twice.
 

data/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -109,7 +109,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -290,6 +290,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -496,7 +498,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -576,7 +578,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -104,7 +104,7 @@ itself, and they hold for every integration.
   payer-supplied amounts.
 - `authorize` runs on every request, and the `resource` it receives is a CLAIM
   the payer made, not proof. Read a framework session; never trust a body field.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -276,6 +276,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -454,7 +456,7 @@ the `reference`. OpenReceive never prices from payer input.
 The `reference` is a string you choose, and it is the fulfillment identity:
 your order id — one per thing you fulfill, created before checkout, kept
 across retries, never reused. OpenReceive never looks inside it, but `onPaid`
-runs once per reference, a new checkout under a reference that already
+commits fulfillment once per reference, a new checkout under a reference that already
 settled is refused with 409, and a fresh id per page load lets one order be
 paid twice.
 
@@ -503,7 +505,7 @@ Content-Security-Policy has a strict `img-src`, allow `data:`
 ([Provider registry](https://openreceive.org/guides/provider-registry.md#assets)).
 
 That is the whole loop: your server owns the price and the order, the payer gets
-an invoice, and `onPaid` runs once inside the settlement transaction.
+an invoice, and `onPaid` runs inside the settlement transaction. Rolled-back transactions may retry the callback; use a host outbox for external delivery.
 
 A runnable illustration of this boundary — not a template to copy models from —
 is Buy a Button

data/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -125,7 +125,7 @@ itself, and they hold for every integration.
   is a placeholder that allows everything (the engine warns at boot while a
   host uses it) — replace it with this app's real ownership check, same as
   `onPaid`'s `Hosts\LoggingOnPaid`.
-- `onPaid` must be idempotent. It runs once per `reference` — your order id, one
+- `onPaid` must be idempotent. Its database fulfillment commits once per `reference` — your order id, one
   per thing you fulfill, created before checkout, kept across retries, never
   reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -301,6 +301,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -512,7 +514,7 @@ prices with exact decimal math, and returns the order id the page will pass as
 the `reference`. OpenReceive never prices from payer input. The `reference` is
 a string you choose, and it is the fulfillment identity: your order id — one
 per thing you fulfill, created before checkout, kept across retries, never
-reused. `onPaid` runs once per reference, a new checkout under a reference
+reused. `onPaid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the
@@ -116,7 +116,7 @@ itself, and they hold for every integration.
   body field. The generator installs `OpenReceive::ALLOW_ALL_AUTHORIZE`, a
   placeholder that allows everything (the engine warns at boot while it is
   set) — replace it with this app's real ownership check, same as `on_paid`.
-- `config.on_paid` must be idempotent. It runs once per `reference` — your order
+- `config.on_paid` must be idempotent. Its database fulfillment commits once per `reference` — your order
   id, one per thing you fulfill, created before checkout, kept across retries,
   never reused. A fresh id per page load lets one order be paid twice.
 - Receive-only NWC is required; a spend-capable code fails closed at boot unless
@@ -285,6 +285,8 @@ enough; drop the `.md` for the same page a person would read.
 Questions, or a problem with the library itself:
 https://openreceive.org/contact
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full
@@ -432,7 +434,7 @@ The initializer needs three things: authorization, the trusted price, and
 fulfillment. All three receive the `reference` — a string you choose, and the
 fulfillment identity: your order id, one per thing you fulfill, created before
 checkout, kept across retries, never reused. OpenReceive never looks inside
-it, but `on_paid` runs once per reference, a new checkout under a reference
+it, but `on_paid` commits fulfillment once per reference, a new checkout under a reference
 that already settled is refused with 409, and a fresh id per page load lets
 one order be paid twice.
 

data/skills/integrate-openreceive/references/woocommerce.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.10.
+These directions describe OpenReceive 0.4.11.
 
 Install and configure the OpenReceive gateway in the existing WooCommerce
 store. Preserve its theme, checkout, customer accounts, order model and prices.
@@ -73,6 +73,8 @@ flows; a receive-only NWC wallet cannot send payments.
 - [Agent Directions: BTCPay Server](https://openreceive.org/guides/agent-directions-btcpay.md)
 - [WordPress + WooCommerce Quickstart](https://openreceive.org/guides/quickstart-woocommerce.md)
 
+- https://openreceive.org/guides/payment-safety-upgrade.md — coordinated upgrades and reviewed repair of existing attempts
+
 ---
 
 ## The quickstart, in full

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.10
+  version: 0.4.11
 platform: ruby
 authors:
 - OpenReceive
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
 - !ruby/object:Gem::Dependency
   name: openreceive-server
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.10
+        version: 0.4.11
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -129,6 +129,7 @@ files:
 - lib/openreceive/rails.rb
 - lib/openreceive/rails/version.rb
 - lib/openreceive/reconcile.rb
+- lib/openreceive/reconcile_scan.rb
 - lib/tasks/openreceive.rake
 - skills/debug-openreceive-payment/SKILL.md
 - skills/integrate-openreceive/SKILL.md