@openreceive/http 0.4.10 → 0.4.12

package/dist/{chunk-TJY2HBVU.js → chunk-PGZAFYN6.js}

@@ -1,7 +1,8 @@
 // src/errors.ts
 import {
   isErrorCode,
-  isRetryableErrorCode
+  isRetryableErrorCode,
+  publicErrorBody
 } from "@openreceive/core";
 var HttpError = class extends Error {
   status;
@@ -56,13 +57,13 @@ function hostError(message, status = 400, code = "INVALID_REQUEST") {
 }
 function mapHostRouteError(error) {
   if (error instanceof HostError || isServiceErrorShape(error)) {
-    return { status: error.status, body: error.body };
+    return { status: error.status, body: publicErrorBody(error.body) };
   }
   if (isWalletErrorShape(error)) {
     const retryable = error.retryable ?? isRetryableErrorCode(error.code);
     return {
       status: walletErrorStatus(error.code, retryable),
-      body: { code: error.code, message: error.message, retryable }
+      body: publicErrorBody({ code: error.code, message: error.message, retryable })
     };
   }
   return null;
@@ -98,13 +99,13 @@ function errorResponse(error, requestId) {
   if (error instanceof HttpError) {
     return jsonResponse(
       error.status,
-      {
+      publicErrorBody({
         code: error.code,
         message: error.message,
         ...error.retryable === void 0 ? {} : { retryable: error.retryable },
         request_id: requestId,
         ...error.details === void 0 ? {} : { details: error.details }
-      },
+      }),
       requestId,
       error.retryAfterSeconds === void 0 ? void 0 : [["retry-after", String(Math.max(1, Math.ceil(error.retryAfterSeconds)))]]
     );
@@ -112,7 +113,7 @@ function errorResponse(error, requestId) {
   if (isServiceErrorShape(error)) {
     return jsonResponse(
       error.status,
-      { ...error.body, request_id: error.body.request_id ?? requestId },
+      publicErrorBody({ ...error.body, request_id: error.body.request_id ?? requestId }),
       requestId
     );
   }
@@ -120,7 +121,12 @@ function errorResponse(error, requestId) {
     const retryable = error.retryable ?? isRetryableErrorCode(error.code);
     return jsonResponse(
       walletErrorStatus(error.code, retryable),
-      { code: error.code, message: error.message, retryable, request_id: requestId },
+      publicErrorBody({
+        code: error.code,
+        message: error.message,
+        retryable,
+        request_id: requestId
+      }),
       requestId
     );
   }
@@ -220,10 +226,10 @@ function isUnderPrefix(pathname, prefix) {
 }
 
 // src/handler.ts
-import { compact as compact2, unixSeconds as unixSeconds7 } from "@openreceive/core";
+import { compact, unixSeconds as unixSeconds7 } from "@openreceive/core";
 
 // src/reconcile-gate.ts
-import { compact, unixSeconds as unixSeconds5 } from "@openreceive/core";
+import { createPaymentScanWindow, unixSeconds as unixSeconds5 } from "@openreceive/core";
 
 // src/host-payments.ts
 import { unixSeconds as unixSeconds3 } from "@openreceive/core";
@@ -283,7 +289,9 @@ import { randomUUID } from "crypto";
 import {
   OPENRECEIVE_PAYMENTS_SCHEMA_VERSION,
   paymentsDdlStatements,
-  unixSeconds as unixSeconds2
+  unixSeconds as unixSeconds2,
+  OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS as OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS2,
+  redactSecrets
 } from "@openreceive/core";
 
 // src/sql-adapters.ts
@@ -472,13 +480,18 @@ function isMissingTableError(error, dialect) {
   }
   return /no such table/i.test(message);
 }
-function parseClaimedAt(value) {
+function parseGate(value) {
+  let gate;
   try {
-    const parsed = JSON.parse(String(value));
-    return typeof parsed.claimed_at === "number" && Number.isFinite(parsed.claimed_at) ? parsed.claimed_at : void 0;
+    gate = JSON.parse(String(value));
   } catch {
     return void 0;
   }
+  if (gate.version > 1)
+    throw new TypeError(
+      "A newer reconcile scheduler is installed; upgrade every application and worker together."
+    );
+  return gate.version === 1 ? gate : void 0;
 }
 function paymentsSchemaSql(dialect, tableName = "openreceive_payments", metaTableName = "openreceive_meta") {
   return paymentsDdlStatements({ dialect, tableName, metaTableName }).map((statement) => `${statement};`).join("\n");
@@ -539,19 +552,30 @@ function createSqlPayments(db, options = {}) {
       await assertSupportedSchema();
       return rowsForReference(adapter, reference);
     },
-    async listReconcilableAttempts() {
+    async findByPaymentHash(paymentHash) {
+      await assertSupportedSchema();
+      const rows = await adapter.query(statement(`SELECT * FROM ${table} WHERE payment_hash = ?`), [
+        paymentHash.toLowerCase()
+      ]);
+      return rows[0] === void 0 ? void 0 : recordFromRow(rows[0]);
+    },
+    async listReconcilableAttempts(after) {
       await assertSupportedSchema();
       const rows = await adapter.query(
         statement(
-          `SELECT payment_hash, created_at, expires_at FROM ${table} WHERE status = 'pending' ORDER BY created_at ASC LIMIT ?`
+          `SELECT payment_hash, created_at, checkout_data FROM ${table} WHERE status = 'pending' ${after == null ? "" : "AND (created_at > ? OR (created_at = ? AND payment_hash > ?))"} ORDER BY created_at ASC, payment_hash ASC LIMIT ?`
         ),
-        [OPENRECEIVE_RECONCILE_BATCH_SIZE]
+        [
+          ...after == null ? [] : [after.created_at, after.created_at, after.payment_hash],
+          OPENRECEIVE_RECONCILE_BATCH_SIZE
+        ]
       );
       return rows.map(
         (row) => ({
           paymentHash: asString(row.payment_hash, "payment_hash"),
           createdAt: asInteger(row.created_at, "created_at"),
-          expiresAt: asInteger(row.expires_at, "expires_at")
+          createdAtSource: savedCheckout(row).createdAtSource ?? "host",
+          expiresAt: settlementExpiresAt(row)
         })
       );
     },
@@ -559,7 +583,7 @@ function createSqlPayments(db, options = {}) {
       await assertSupportedSchema();
       const rows = await adapter.query(
         statement(
-          `SELECT payment_hash, created_at, expires_at FROM ${table} WHERE payment_hash = ? AND status = 'pending'`
+          `SELECT payment_hash, created_at, checkout_data FROM ${table} WHERE payment_hash = ? AND status = 'pending'`
         ),
         [paymentHash.toLowerCase()]
       );
@@ -568,13 +592,13 @@ function createSqlPayments(db, options = {}) {
       return {
         paymentHash: asString(row.payment_hash, "payment_hash"),
         createdAt: asInteger(row.created_at, "created_at"),
-        expiresAt: asInteger(row.expires_at, "expires_at")
+        createdAtSource: savedCheckout(row).createdAtSource ?? "host",
+        expiresAt: settlementExpiresAt(row)
       };
     },
-    async claimReconcileGate({ now, intervalSeconds }) {
+    async claimReconcileGate({ now, intervalSeconds, leaseSeconds = 10 }) {
       await assertSupportedSchema();
       const token = randomUUID();
-      const claimValue = JSON.stringify({ claimed_at: now, token });
       const insertIfAbsent = adapter.dialect === "postgres" ? `INSERT INTO ${metaTable} (key, value, rev) VALUES (?, ?, 0) ON CONFLICT (key) DO NOTHING` : `INSERT OR IGNORE INTO ${metaTable} (key, value, rev) VALUES (?, ?, 0)`;
       for (let attempt = 0; attempt < RECONCILE_GATE_CAS_RETRIES; attempt += 1) {
         const rows = await adapter.query(
@@ -582,13 +606,27 @@ function createSqlPayments(db, options = {}) {
           [RECONCILE_GATE_META_KEY]
         );
         const current = rows[0];
+        const gate = current === void 0 ? void 0 : parseGate(current.value);
+        if (gate !== void 0 && isFreshTimestamp(
+          now,
+          gate.claimed_at,
+          Math.max(intervalSeconds, gate.interval_seconds ?? 2)
+        ))
+          return null;
+        if (gate !== void 0 && gate.claimed_at <= now + META_CLOCK_SKEW_SECONDS && gate.lease_until > now)
+          return null;
+        const scheduler = gate?.scheduler ?? { cursor: null, windows: [] };
+        const claimValue = JSON.stringify({
+          version: 1,
+          claimed_at: now,
+          token,
+          lease_until: now + leaseSeconds,
+          interval_seconds: intervalSeconds,
+          scheduler
+        });
         if (current === void 0) {
           await adapter.query(statement(insertIfAbsent), [RECONCILE_GATE_META_KEY, claimValue]);
         } else {
-          const claimedAt = parseClaimedAt(current.value);
-          if (claimedAt !== void 0 && isFreshTimestamp(now, claimedAt, intervalSeconds)) {
-            return false;
-          }
           await adapter.query(
             statement(`UPDATE ${metaTable} SET value = ?, rev = rev + 1 WHERE key = ? AND rev = ?`),
             [claimValue, RECONCILE_GATE_META_KEY, asInteger(current.rev, "rev")]
@@ -598,9 +636,99 @@ function createSqlPayments(db, options = {}) {
           statement(`SELECT value FROM ${metaTable} WHERE key = ? LIMIT 1`),
           [RECONCILE_GATE_META_KEY]
         );
-        if (readback[0] !== void 0 && String(readback[0].value) === claimValue) return true;
+        if (readback[0] !== void 0 && String(readback[0].value) === claimValue)
+          return { token, scheduler };
       }
-      return false;
+      return null;
+    },
+    async checkpointReconcileGate({ claim, scheduler, now, release = false, intervalSeconds }) {
+      await assertSupportedSchema();
+      if (scheduler.windows.length > 2 || scheduler.windows.some(
+        (window) => window.attempts.length > OPENRECEIVE_RECONCILE_BATCH_SIZE
+      ))
+        throw new RangeError("Reconcile progress exceeds its cohort bound.");
+      const rows = await adapter.query(
+        statement(`SELECT value, rev FROM ${metaTable} WHERE key = ? LIMIT 1`),
+        [RECONCILE_GATE_META_KEY]
+      );
+      const current = rows[0];
+      if (current === void 0) return false;
+      const gate = parseGate(current.value);
+      if (gate?.token !== claim.token || gate.lease_until <= now) return false;
+      const value = JSON.stringify({
+        ...gate,
+        scheduler,
+        lease_until: release ? 0 : gate.lease_until,
+        interval_seconds: intervalSeconds ?? gate.interval_seconds
+      });
+      if (new TextEncoder().encode(value).length > 131072)
+        throw new RangeError("Reconcile progress exceeds 128 KiB.");
+      await adapter.query(
+        statement(`UPDATE ${metaTable} SET value = ?, rev = rev + 1 WHERE key = ? AND rev = ?`),
+        [value, RECONCILE_GATE_META_KEY, asInteger(current.rev, "rev")]
+      );
+      const readback = await adapter.query(
+        statement(`SELECT value FROM ${metaTable} WHERE key = ? LIMIT 1`),
+        [RECONCILE_GATE_META_KEY]
+      );
+      return readback[0]?.value === value;
+    },
+    async listRepairCandidates({ after = "", limit = 100 } = {}) {
+      await assertSupportedSchema();
+      if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+        throw new RangeError("Repair report limit must be between 1 and 200.");
+      const rows = await adapter.query(
+        statement(
+          `SELECT payment_hash, reference, status, status_reason, updated_at, expires_at, checkout_data, swap_data IS NOT NULL AS has_swap FROM ${table} WHERE status IN ('expired', 'attention') AND paid_at IS NULL AND payment_hash > ? ORDER BY payment_hash LIMIT ?`
+        ),
+        [after, limit]
+      );
+      return {
+        candidates: rows.map(repairCandidate).filter((row) => row !== null),
+        nextCursor: rows.length === limit ? asString(rows.at(-1).payment_hash, "payment_hash") : null
+      };
+    },
+    async requeueAttempt(input) {
+      await assertSupportedSchema();
+      if (!input.reason.trim() || input.reason.length > 500)
+        throw new TypeError("A reviewed repair reason of 1\u2013500 characters is required.");
+      return adapter.transaction(async (tx) => {
+        const hash = input.paymentHash.toLowerCase();
+        const preliminary = await tx.query(
+          statement(`SELECT reference FROM ${table} WHERE payment_hash = ?`),
+          [hash]
+        );
+        if (preliminary[0] === void 0) return false;
+        await lockReference(tx, asString(preliminary[0].reference, "reference"));
+        const rows = await tx.query(
+          statement(
+            `SELECT payment_hash, reference, status, status_reason, updated_at, expires_at, checkout_data, swap_data IS NOT NULL AS has_swap FROM ${table} WHERE payment_hash = ? AND paid_at IS NULL`
+          ),
+          [hash]
+        );
+        const row = rows[0];
+        if (row === void 0 || row.status !== input.expectedStatus || asInteger(row.updated_at, "updated_at") !== input.expectedUpdatedAt)
+          return false;
+        const candidate = repairCandidate(row);
+        if (candidate === null) return false;
+        const auditKey = `payment_repair:${hash}:${input.expectedStatus}:${input.expectedUpdatedAt}`;
+        const prior = await tx.query(statement(`SELECT key FROM ${metaTable} WHERE key = ?`), [
+          auditKey
+        ]);
+        if (prior.length > 0) return false;
+        const now = clock();
+        await tx.query(
+          statement(
+            `UPDATE ${table} SET status = 'pending', status_reason = 'operator_requeued', updated_at = ? WHERE payment_hash = ? AND status = ? AND updated_at = ?`
+          ),
+          [now, hash, input.expectedStatus, input.expectedUpdatedAt]
+        );
+        await tx.query(statement(`INSERT INTO ${metaTable} (key, value, rev) VALUES (?, ?, 0)`), [
+          auditKey,
+          JSON.stringify({ ...candidate, reviewedAt: now, reason: redactSecrets(input.reason) })
+        ]);
+        return true;
+      });
     },
     async commitAttempt(input) {
       await assertSupportedSchema();
@@ -654,6 +782,7 @@ function createSqlPayments(db, options = {}) {
       });
     },
     async countAttemptsFromIp(clientIp, sinceUnixSeconds) {
+      await assertSupportedSchema();
       const rows = await adapter.query(
         statement(`SELECT COUNT(*) AS n FROM ${table} WHERE client_ip = ? AND inserted_at >= ?`),
         [clientIp, sinceUnixSeconds]
@@ -663,6 +792,12 @@ function createSqlPayments(db, options = {}) {
     async recordReconciliation(transition) {
       await assertSupportedSchema();
       await adapter.transaction(async (tx) => {
+        const rows = await tx.query(
+          statement(`SELECT reference FROM ${table} WHERE payment_hash = ?`),
+          [transition.paymentHash.toLowerCase()]
+        );
+        if (rows[0] === void 0) return;
+        await lockReference(tx, asString(rows[0].reference, "reference"));
         await tx.query(
           statement(
             `UPDATE ${table} SET status = ?, status_reason = ?, updated_at = ? WHERE payment_hash = ? AND status = 'pending'`
@@ -676,10 +811,10 @@ function createSqlPayments(db, options = {}) {
         );
       });
     },
-    // Same write-once claim as markPaidOnce, without a fulfillment hook: in
-    // custom-repository mode the host's own handler runs outside this
-    // transaction, so it is handed no transactional query.
-    recordSettlement: (settlement) => markPaidOnce(settlement, () => void 0),
+    recordSettlementWithFulfillment: (settlement, fulfill) => markPaidOnce(
+      settlement,
+      ({ query, ...context }) => fulfill({ ...context, transaction: { query } })
+    ),
     markPaidOnce
   };
   async function markPaidOnce(input, fulfill) {
@@ -695,7 +830,7 @@ function createSqlPayments(db, options = {}) {
       await lockReference(tx, asString(reference, "reference"));
       const rows = await rowsForReference(tx, asString(reference, "reference"));
       const row = rows.find((candidate) => candidate.paymentHash === paymentHash);
-      if (row === void 0 || row.status === "settled") return false;
+      if (row === void 0 || row.status !== "pending") return false;
       const firstForReference = !rows.some((candidate) => candidate.status === "settled");
       const now = clock();
       await tx.query(
@@ -741,6 +876,50 @@ function recordFromRow(row) {
     swapData: swapData === null || swapData === void 0 ? null : parseRowJson(asString(swapData, "swap_data"), "swap_data", paymentHash)
   };
 }
+function savedCheckout(row) {
+  const hash = asString(row.payment_hash, "payment_hash");
+  const checkout = parseRowJson(
+    asString(row.checkout_data, "checkout_data"),
+    "checkout_data",
+    hash
+  );
+  if (typeof checkout === "object" && checkout !== null) {
+    const saved = checkout;
+    const value = saved.expiresAt ?? saved.expires_at;
+    if (typeof value === "number" && Number.isSafeInteger(value) && value > 0)
+      return {
+        expiresAt: value,
+        createdAtSource: (saved.createdAtSource ?? saved.created_at_source) === "wallet" ? "wallet" : "host"
+      };
+  }
+  throw new TypeError(
+    `Invalid checkout_data invoice expiry on openreceive payment attempt ${hash}.`
+  );
+}
+function settlementExpiresAt(row) {
+  return savedCheckout(row).expiresAt;
+}
+function repairCandidate(row) {
+  if (row.status !== "expired" && row.status !== "attention") return null;
+  const expires = settlementExpiresAt(row);
+  const instruction = asInteger(row.expires_at, "expires_at");
+  const updated = asInteger(row.updated_at, "updated_at");
+  const reason = row.status_reason == null ? null : asString(row.status_reason, "status_reason");
+  const early = Boolean(row.has_swap) && expires > instruction && updated >= instruction + OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS2 && updated < expires + OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS2 && ["not_found_after_expiry", "no_finality_after_expiry", "unsettled_after_expiry"].includes(
+    reason ?? ""
+  );
+  if (!early && row.status !== "attention") return null;
+  return {
+    paymentHash: asString(row.payment_hash, "payment_hash"),
+    reference: asString(row.reference, "reference"),
+    status: row.status,
+    statusReason: reason,
+    updatedAt: updated,
+    instructionExpiresAt: instruction,
+    settlementExpiresAt: expires,
+    category: early ? "early_swap_closure" : "attention"
+  };
+}
 function parseRowJson(value, column, paymentHash) {
   try {
     return JSON.parse(value);
@@ -802,7 +981,7 @@ function createHost(options) {
   }
   if (options.onPaid === void 0) {
     throw new TypeError(
-      "OpenReceive host requires onPaid (per-reference settlement context in db mode; the raw settlement event in custom repository mode). Pass onPaid to fulfill the order \u2014 it runs exactly once per reference. https://openreceive.org/guides/api-reference.md#onpaid"
+      "OpenReceive host requires onPaid (per-reference settlement context in db mode; the raw transaction context in custom repository mode). Pass onPaid to write fulfillment atomically for the first settled attempt per reference. https://openreceive.org/guides/api-reference.md#onpaid"
     );
   }
   let payments;
@@ -816,6 +995,7 @@ function createHost(options) {
     const fulfill = options.onPaid;
     onPaid = async (input) => {
       await repository.markPaidOnce(input, fulfill);
+      await assertSettlementCommitted(repository, input.paymentHash);
     };
   } else {
     if (options.payments?.listForReference === void 0) {
@@ -838,21 +1018,20 @@ function createHost(options) {
         "OpenReceive host requires payments.recordReconciliation \u2014 how a scan outcome (settled/expired/attention) is written back. Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
       );
     }
-    if (typeof options.payments.recordSettlement !== "function") {
+    if (typeof options.payments.recordSettlementWithFulfillment !== "function") {
       throw new TypeError(
-        "OpenReceive host requires payments.recordSettlement (the write-once settlement claim). Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
+        "OpenReceive host requires payments.recordSettlementWithFulfillment(input, fulfill). Await fulfillment inside the reference settlement transaction; boolean-only repositories are unsupported. Implement it, or pass db to use the built-in SQL repository. https://openreceive.org/guides/storage.md"
       );
     }
+    if (typeof options.payments.findByPaymentHash !== "function")
+      throw new TypeError(
+        "OpenReceive host requires payments.findByPaymentHash to verify durable settlement acknowledgment."
+      );
     payments = options.payments;
     const custom = options.payments;
-    const notify = options.onPaid;
     onPaid = async (settlement) => {
-      const claimed = await custom.recordSettlement({
-        paymentHash: settlement.paymentHash,
-        paidAt: settlement.paidAt,
-        ...settlement.details === void 0 ? {} : { details: settlement.details }
-      });
-      if (claimed) await notify(settlement);
+      await custom.recordSettlementWithFulfillment(settlement, options.onPaid);
+      await assertSettlementCommitted(custom, settlement.paymentHash);
     };
   }
   const clock = options.clock ?? unixSeconds3;
@@ -913,7 +1092,19 @@ function createHost(options) {
   };
   return {
     resolveCheckout,
-    onCheckoutCreated: (input) => payments.commitAttempt(input),
+    onCheckoutCreated: async (input) => {
+      try {
+        await payments.commitAttempt(input);
+      } catch (error) {
+        if (error instanceof HttpError || isServiceErrorShape(error)) throw error;
+        throw new HttpError(
+          503,
+          "INTERNAL",
+          "Payment storage is unavailable; payer instructions were withheld. Please retry.",
+          { retryable: true }
+        );
+      }
+    },
     onPaid,
     payments
   };
@@ -985,6 +1176,16 @@ function storedPaymentHash(value) {
   }
   return normalized;
 }
+async function assertSettlementCommitted(repository, paymentHash) {
+  const committed = await repository.findByPaymentHash(paymentHash);
+  if (committed?.status !== "settled")
+    throw new HttpError(
+      503,
+      "INTERNAL",
+      "The payment settlement is not committed; retry reconciliation.",
+      { retryable: true }
+    );
+}
 
 // src/reconcile-loop.ts
 import { unixSeconds as unixSeconds4 } from "@openreceive/core";
@@ -996,7 +1197,7 @@ async function reconcileHostPayments(input) {
     attempts.map((attempt) => [attempt.paymentHash.toLowerCase(), attempt])
   );
   const scannedAt = clock();
-  const checks = await input.service.reconcilePayments({
+  const checks = input.checks ?? await input.service.reconcilePayments({
     attempts,
     overlapSeconds: input.overlapSeconds,
     ...input.maxPages === void 0 ? {} : { maxPages: input.maxPages }
@@ -1026,7 +1227,7 @@ async function reconcileHostPayments(input) {
       const transition = reconciliationTransition(
         attempt,
         checked.status,
-        scannedAt,
+        checked.coverageStartedAt ?? scannedAt,
         walletTransaction?.state ?? walletTransaction?.transaction_state
       );
       if (transition !== null) {
@@ -1050,9 +1251,9 @@ async function startReconciler(input) {
   if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 250) {
     throw new RangeError("pollIntervalMs must be a safe integer of at least 250");
   }
-  if (typeof input.host.payments.claimReconcileGate !== "function") {
+  if (typeof input.host.payments.claimReconcileGate !== "function" || typeof input.host.payments.checkpointReconcileGate !== "function") {
     throw new TypeError(
-      "The reconciler requires payments.claimReconcileGate (a durable CAS gate shared by every worker); implement it on the repository so all scan entry points stay within one budget."
+      "The reconciler requires payments.claimReconcileGate and checkpointReconcileGate (a durable CAS gate shared by every worker); implement it on the repository so all scan entry points stay within one budget."
     );
   }
   const overlapSeconds = input.overlapSeconds ?? 60;
@@ -1129,9 +1330,9 @@ function intervalForInvoiceAge(elapsedSeconds) {
 }
 async function maybeReconcilePayments(input) {
   const claimReconcileGate = input.host.payments.claimReconcileGate;
-  if (typeof claimReconcileGate !== "function") {
+  if (typeof claimReconcileGate !== "function" || typeof input.host.payments.checkpointReconcileGate !== "function") {
     throw new TypeError(
-      "Opportunistic reconcile requires payments.claimReconcileGate (a durable CAS gate); implement it on the repository or disable with opportunisticReconcile: false."
+      "Opportunistic reconcile requires payments.claimReconcileGate and checkpointReconcileGate (durable lease and progress CAS); implement it on the repository or disable with opportunisticReconcile: false."
     );
   }
   const report = input.onError ?? ((error) => {
@@ -1142,36 +1343,153 @@ async function maybeReconcilePayments(input) {
     );
   });
   try {
-    const attempts = await input.host.payments.listReconcilableAttempts();
-    if (attempts.length === 0) return { reason: "no_pending" };
     const clock = input.clock ?? unixSeconds5;
     const now = clock();
-    const intervalSeconds = reconcileIntervalSeconds(attempts, now, input.minIntervalSeconds);
-    const claimed = await claimReconcileGate.call(input.host.payments, { now, intervalSeconds });
-    if (!claimed) return { reason: "gate_busy" };
-    const checks = await withScanTimeout(
-      reconcileHostPayments({
-        service: input.service,
-        host: input.host,
-        // Already read above to size the gate interval; the pass scans that
-        // exact batch rather than repeating the query on the request path.
-        attempts,
-        overlapSeconds: input.overlapSeconds,
-        maxPages: input.maxPages ?? OPENRECEIVE_RECONCILE_SCAN_MAX_PAGES,
-        ...compact({ clock: input.clock })
-      }),
+    const minInterval = Math.max(2, input.minIntervalSeconds ?? 2);
+    const timeout = Math.min(
+      OPENRECEIVE_RECONCILE_SCAN_TIMEOUT_MS,
       input.scanTimeoutMs ?? OPENRECEIVE_RECONCILE_SCAN_TIMEOUT_MS
     );
-    return { reason: "ran", checks };
+    const claim = await claimReconcileGate.call(input.host.payments, {
+      now,
+      intervalSeconds: minInterval,
+      leaseSeconds: Math.ceil(timeout / 1e3) + 1
+    });
+    if (claim === null) return { reason: "gate_busy" };
+    if (typeof claim !== "object" || typeof claim.token !== "string")
+      throw new TypeError(
+        "claimReconcileGate must return a lease claim or null; boolean gate repositories must upgrade."
+      );
+    const scheduler = structuredClone(claim.scheduler);
+    const queued = new Set(
+      scheduler.windows.flatMap((window2) => window2.attempts.map((attempt) => attempt.payment_hash))
+    );
+    if (scheduler.windows.length < 2) {
+      let candidates = await input.host.payments.listReconcilableAttempts(scheduler.cursor);
+      if (candidates.length === 0 && scheduler.cursor !== null)
+        candidates = await input.host.payments.listReconcilableAttempts(null);
+      const last = candidates.at(-1);
+      scheduler.cursor = last === void 0 || candidates.length < OPENRECEIVE_RECONCILE_BATCH_SIZE ? null : { created_at: last.createdAt, payment_hash: last.paymentHash };
+      const fresh = candidates.filter((attempt) => !queued.has(attempt.paymentHash));
+      if (fresh.length > 0)
+        scheduler.windows.push(
+          createPaymentScanWindow(
+            fresh.map((attempt) => ({
+              payment_hash: attempt.paymentHash,
+              created_at: attempt.createdAt,
+              expires_at: attempt.expiresAt,
+              created_at_source: attempt.createdAtSource ?? "host"
+            })),
+            now,
+            input.overlapSeconds
+          )
+        );
+    }
+    const window = scheduler.windows.shift();
+    if (window === void 0) {
+      await input.host.payments.checkpointReconcileGate({
+        claim,
+        scheduler,
+        now: clock(),
+        release: true
+      });
+      return { reason: "no_pending" };
+    }
+    const attempts = window.attempts.map((attempt) => ({
+      paymentHash: attempt.payment_hash,
+      createdAt: attempt.created_at,
+      expiresAt: attempt.expires_at,
+      createdAtSource: attempt.created_at_source
+    }));
+    const intervalSeconds = reconcileIntervalSeconds(attempts, now, minInterval);
+    if (!await input.host.payments.checkpointReconcileGate({
+      claim,
+      scheduler,
+      now: clock(),
+      intervalSeconds
+    }))
+      return { reason: "gate_busy" };
+    const streamed = /* @__PURE__ */ new Set();
+    const deliveryFailures = [];
+    const deadline = Date.now() + timeout;
+    const controller = new AbortController();
+    const slice = await withScanTimeout(
+      input.service.scanPaymentSlice({
+        window,
+        maxPages: Math.min(
+          OPENRECEIVE_RECONCILE_SCAN_MAX_PAGES,
+          input.maxPages ?? OPENRECEIVE_RECONCILE_SCAN_MAX_PAGES
+        ),
+        deadline,
+        signal: controller.signal,
+        onFinality: async (check) => {
+          if (streamed.has(check.paymentHash) || Date.now() >= deadline) return;
+          if (!await input.host.payments.checkpointReconcileGate({
+            claim,
+            scheduler,
+            now: clock(),
+            intervalSeconds
+          }))
+            throw new Error("Reconciliation lease expired before finality delivery.");
+          streamed.add(check.paymentHash);
+          try {
+            await reconcileHostPayments({
+              service: input.service,
+              host: input.host,
+              attempts,
+              checks: [check],
+              clock
+            });
+          } catch (error) {
+            deliveryFailures.push(error);
+          }
+        }
+      }),
+      timeout,
+      controller
+    );
+    if (slice.outcome === "continued") {
+      const halves = scheduler.windows.length === 0 ? splitWindow(slice.window, clock(), input.overlapSeconds) : void 0;
+      scheduler.windows.push(...halves ?? [slice.window]);
+    }
+    if (slice.outcome === "stalled")
+      report(
+        new Error(
+          "Wallet history made no pagination progress; attempts remain pending and other cohorts will be served."
+        )
+      );
+    if (!await input.host.payments.checkpointReconcileGate({
+      claim,
+      scheduler,
+      now: clock(),
+      release: true,
+      intervalSeconds
+    }))
+      return { reason: "gate_busy" };
+    await reconcileHostPayments({
+      service: input.service,
+      host: input.host,
+      attempts,
+      checks: slice.checks.filter((check) => !streamed.has(check.paymentHash)),
+      clock
+    });
+    if (deliveryFailures.length > 0)
+      throw new AggregateError(
+        deliveryFailures,
+        "One or more settlement transactions failed; pending attempts will be retried."
+      );
+    return { reason: "ran", checks: slice.checks };
   } catch (error) {
     report(error);
     return { reason: "scan_failed" };
   }
 }
-function withScanTimeout(work, timeoutMs) {
+function withScanTimeout(work, timeoutMs, controller) {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-      reject(new Error(`reconcile scan exceeded ${timeoutMs}ms`));
+      const error = new Error(`reconcile scan exceeded ${timeoutMs}ms`);
+      controller.abort(error);
+      reject(error);
     }, timeoutMs);
     work.then(
       (value) => {
@@ -1185,6 +1503,18 @@ function withScanTimeout(work, timeoutMs) {
     );
   });
 }
+function splitWindow(window, now, overlap) {
+  if (!window.attempts.every((attempt) => attempt.created_at_source === "wallet")) return void 0;
+  const timestamps = [...new Set(window.attempts.map((attempt) => attempt.created_at))].sort(
+    (a, b) => a - b
+  );
+  if (timestamps.length < 2) return void 0;
+  const boundary = timestamps[Math.floor(timestamps.length / 2)];
+  return [
+    window.attempts.filter((attempt) => attempt.created_at < boundary),
+    window.attempts.filter((attempt) => attempt.created_at >= boundary)
+  ].map((attempts) => createPaymentScanWindow(attempts, now, overlap));
+}
 
 // src/http-request.ts
 import { isRecord, nonEmptyString } from "@openreceive/core";
@@ -1290,15 +1620,16 @@ function ratesCurrencies(raw) {
   }
   return currencies;
 }
-function optionalCheckoutFields(body) {
-  const memo = trimmedField(body.memo);
-  if (memo !== void 0 && memo.length > MAX_MEMO_LENGTH) {
+function optionalCheckoutFields(body, hostDescription) {
+  const bodyMemo = trimmedField(body.memo);
+  if (bodyMemo !== void 0 && bodyMemo.length > MAX_MEMO_LENGTH) {
     throw new HttpError(
       400,
       "INVALID_REQUEST",
       `memo must be ${MAX_MEMO_LENGTH} characters or fewer.`
     );
   }
+  const memo = bodyMemo ?? hostDescription;
   const metadata = readRecord(body.metadata);
   return {
     ...memo === void 0 ? {} : { memo },
@@ -1564,9 +1895,9 @@ function createHttpHandler(options) {
   }
   const rateLimit = options.rateLimitHook ?? resolveRateLimiting(options);
   const reconcile = options.opportunisticReconcile === false ? void 0 : typeof options.opportunisticReconcile === "object" ? options.opportunisticReconcile : {};
-  if (reconcile !== void 0 && typeof options.host.payments.claimReconcileGate !== "function") {
+  if (reconcile !== void 0 && (typeof options.host.payments.claimReconcileGate !== "function" || typeof options.host.payments.checkpointReconcileGate !== "function")) {
     throw new TypeError(
-      "Opportunistic reconcile (on by default) requires payments.claimReconcileGate \u2014 a durable compare-and-set gate shared by every worker (the built-in SQL repository implements it over openreceive_meta). Implement it on the custom repository, or pass opportunisticReconcile: false and run your own settlement worker. https://openreceive.org/guides/storage.md"
+      "Opportunistic reconcile (on by default) requires payments.claimReconcileGate and checkpointReconcileGate \u2014 a durable compare-and-set gate shared by every worker (the built-in SQL repository implements it over openreceive_meta). Implement it on the custom repository, or pass opportunisticReconcile: false and run your own settlement worker. https://openreceive.org/guides/storage.md"
     );
   }
   const rawExtractClientIp = (typeof options.rateLimiting === "object" ? options.rateLimiting.ip : void 0) ?? resolveClientIp;
@@ -1619,7 +1950,7 @@ async function dispatch(runtime, request, requestId, native) {
     host: runtime.host,
     // `service`/`host` stay outside compact: it is recursive, and they
     // are handles whose identity the reconcile pass relies on.
-    ...compact2({
+    ...compact({
       minIntervalSeconds: runtime.reconcile.minIntervalSeconds,
       clock: runtime.clock
     })
@@ -1671,7 +2002,7 @@ async function dispatch(runtime, request, requestId, native) {
         mint: () => runtime.service.createCheckout({
           reference,
           amount: requireResolvedAmount(resolved2),
-          ...optionalCheckoutFields(body)
+          ...optionalCheckoutFields(body, resolved2.description)
         }),
         recover: () => committedCheckout(reference, resolved2),
         attempt: (minted) => ({ paymentHash: minted.paymentHash, checkout: minted })
@@ -1764,7 +2095,7 @@ async function dispatch(runtime, request, requestId, native) {
           reference,
           amount: requireResolvedAmount(resolved2),
           payInAsset,
-          ...optionalCheckoutFields(body)
+          ...optionalCheckoutFields(body, resolved2.description)
         }),
         recover: () => recoverCommittedSwap(runtime, reference, resolved2),
         attempt: (minted) => ({
@@ -1876,10 +2207,9 @@ async function persistCheckoutAttempt(runtime, input) {
   } catch (error) {
     if (error instanceof HttpError || isServiceErrorShape(error)) throw error;
     throw new HttpError(
-      503,
-      "INTERNAL",
-      "The host could not persist this payment attempt; payer instructions were withheld. Please retry.",
-      { retryable: true }
+      409,
+      "CONFLICT",
+      "The host did not accept this payment attempt; payer instructions were withheld."
     );
   }
 }
@@ -1974,9 +2304,9 @@ async function startNotificationListener(input) {
       retryable: false
     });
   }
-  if (typeof input.host.payments.claimReconcileGate !== "function") {
+  if (typeof input.host.payments.claimReconcileGate !== "function" || typeof input.host.payments.checkpointReconcileGate !== "function") {
     throw new TypeError(
-      "The notification listener requires payments.claimReconcileGate (a durable CAS gate shared by every worker); implement it on the repository so all scan entry points stay within one budget."
+      "The notification listener requires payments.claimReconcileGate and checkpointReconcileGate (a durable CAS gate shared by every worker); implement it on the repository so all scan entry points stay within one budget."
     );
   }
   const reportError = (error) => {
@@ -2125,9 +2455,29 @@ async function startNotificationWorker(input) {
 
 // src/orm-adapters.ts
 function knexDb(knex, dialect) {
+  const connectionOwner = (executor) => {
+    const owner = executor.client;
+    if (typeof owner?.acquireConnection !== "function" || typeof owner.releaseConnection !== "function") {
+      throw new TypeError(
+        "PostgreSQL knexDb requires Knex client.acquireConnection/releaseConnection on both the instance and transaction."
+      );
+    }
+    return owner;
+  };
+  if (dialect === "postgres") connectionOwner(knex);
   const queryOn = (executor) => async (sql, params = []) => {
-    const result = await executor.raw(sql, [...params]);
-    return dialect === "sqlite" ? result : result.rows ?? [];
+    if (dialect === "sqlite")
+      return await executor.raw(sql, [...params]);
+    const owner = connectionOwner(executor);
+    const connection = await owner.acquireConnection();
+    try {
+      const driver = connection;
+      if (typeof driver?.query !== "function")
+        throw new TypeError("PostgreSQL knexDb requires a native pg connection.");
+      return (await driver.query(sql, [...params])).rows ?? [];
+    } finally {
+      await owner.releaseConnection(connection);
+    }
   };
   return {
     dialect,
@@ -2177,14 +2527,14 @@ function sequelizeDb(sequelize, dialect) {
 }
 
 // src/stack.ts
-import { compact as compact3 } from "@openreceive/core";
+import { compact as compact2, redactSecrets as redactSecrets2 } from "@openreceive/core";
 import { createOpenReceive } from "@openreceive/node";
 function createStack(options) {
   const { wallet, storage, amountFor, clock, onBootFailure, ...handlerOptions } = options;
   const host = createHost({
     ...storage,
     amountFor,
-    ...compact3({ clock })
+    ...compact2({ clock })
   });
   const prefix = normalizePrefix(options.prefix ?? "/openreceive");
   let ownedService;
@@ -2193,13 +2543,15 @@ function createStack(options) {
     if (wallet.service === void 0) ownedService = resolved;
     return createHttpHandler({
       ...handlerOptions,
-      ...compact3({ clock }),
+      ...compact2({ clock }),
       service: resolved,
       host
     });
   })();
   boot.catch((error) => {
-    const message = `OpenReceive stack failed to start: ${error instanceof Error ? error.message : String(error)}`;
+    const message = `OpenReceive stack failed to start: ${redactSecrets2(
+      error instanceof Error ? error.message : String(error)
+    )}`;
     if (onBootFailure === void 0) console.error(message);
     else onBootFailure(message);
   });