openreceive-rails 0.4.9 → 0.4.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c53bf506f1db08240a35a17c509b74d5bdb13964f10bdc0b3e8d580d71e0f6c1
-  data.tar.gz: b3361f7e657d7d0e96228b1a8a8f5531ed61ed6924f002b6bebdb70a80f91efe
+  metadata.gz: 9b819ffb0e4f2872cd4de6da728c6404804496da560443a928d54d0aa25a5ac6
+  data.tar.gz: 674d40eb671af219dbaafd038eb4e8bee4849649e8bf32d82bf3fd1f45405414
 SHA512:
-  metadata.gz: 07c085990621609cde309b305d3887079232ddfa00c191b409a8aa2bba38370d2937422607cb3479dfff78edbe0bde4976e6ec9e50aa3bd0ff1525f429905b3f
-  data.tar.gz: 0ed794db39837fb586b2e49d705fc8064f2aadf647544e51bd13888f748fbf3ad897700950211ca2f5087739d2036bcf748d3af9a28668d13bb1a2c6660b4864
+  metadata.gz: a2ad30551213e01ce2fce1ccd0f083d0a26aacf8782a0e38d78c8e628d5a8bf68ebb765ba122fc8c9f8375c375bf7582e0fce8f92a5c8902d6e5a0f7effece7e
+  data.tar.gz: 16b67e1d5797202128acb827f388f371c6d391158c5227f6d8f5acf5fd530b2f3b32604ebbe81609b51cf03b4049f6fcf41a756cf5e81c8119c986e4eec466e9

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+on a USDT or USDC checkout: the payment breakdown and transaction details
+express “You send” and the swap fee in the token and no longer show the
+fiat valuation of the deposit, which read as the deposit amount with a typo.
+Update `@openreceive/elements` and rebuild the frontend to receive this fix;
+upgrading the gem alone does not update the checkout UI.
+
 ## 0.4.9 - 2026-09-14
 
 Release alongside the packaged checkout fix that hides the Lightning pane

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.9"
+    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