@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/payments/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Decision API payments (payments spec §4, §13.4; Go Prod §11): the x402 `ixo-pay` gate the router
+ * calls (S3), settle on receipt the workflows call, and the payment crons.
+ */
+export { type ExtendOutcome, extendForReview, reservationExpiry } from "./extend.js";
+export type { FacilitatorDeps } from "./facilitator.js";
+export { createPaymentGate, decodeHeader, encodeHeader, type GateDeps } from "./gate.js";
+export { publishedPrice } from "./price.js";
+export { type ReconcileReport, reconcilePayments, watchBalances } from "./reconcile.js";
+export { type RefundOutcome, refreshRefund } from "./refund.js";
+export { paymentResponse, type SettleDeps, settleClaim } from "./settle.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/payments/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/payments/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,KAAK,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClF,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,KAAK,eAAe,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/payments/index.js

@@ -0,0 +1,11 @@
+/**
+ * Decision API payments (payments spec §4, §13.4; Go Prod §11): the x402 `ixo-pay` gate the router
+ * calls (S3), settle on receipt the workflows call, and the payment crons.
+ */
+export { extendForReview, reservationExpiry } from "./extend.js";
+export { createPaymentGate, decodeHeader, encodeHeader } from "./gate.js";
+export { publishedPrice } from "./price.js";
+export { reconcilePayments, watchBalances } from "./reconcile.js";
+export { refreshRefund } from "./refund.js";
+export { paymentResponse, settleClaim } from "./settle.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/payments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/payments/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAsB,eAAe,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAElF,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAiB,MAAM,QAAQ,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAwB,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAsB,aAAa,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAmB,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/payments/price.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The price this oracle PUBLISHES per protocol (payments spec §3.1, Go Prod §11.1): what every offer
+ * charges and what `GET /v1/api/protocols/:did` serves. The facilitator refuses an offer whose
+ * per-claim amount differs from the published one (`/offers` 422 `price_mismatch`), and the public
+ * route cannot see a source — so the charged price is a function of the protocol ALONE. There are
+ * no per-source prices (contracts v1.1): a partner who should not pay gets `billingMode: none`.
+ *
+ * 1 PAY = 1 USD = 1,000,000 upay, so one cent is 10,000 upay and 1 upay is 1 micro-USD.
+ */
+import type { Config } from "../../config.js";
+import type { Price } from "../../contracts/index.js";
+export declare const UPAY_PER_CENT = 10000;
+/**
+ * The published price of one decision under `protocolDid` (§3.1), or null when this oracle
+ * publishes none for it — the route then serves `price: null`, which the facilitator reads as "not
+ * published", and the gate offers nothing (`gate.ts`). Resolution, protocol alone: the config's
+ * `pricing.api.byProtocol[protocolDid]`, then `pricing.api.amountMicroUsd`, then the
+ * `API_PRICE_USD_CENTS` var (× 10 000). `amountMicroUsd` and `amount` are the exact price;
+ * `amountCents` is the same price in cents — exact, because every price is a whole number of
+ * cents (`MicroUsdPrice` in oracle.ts; the var is whole cents by type).
+ */
+export declare function publishedPrice(config: Pick<Config, "API_PRICE_USD_CENTS">, protocolDid: string): Price | null;
+/** upay base units → whole cents, rounded DOWN (a balance is never shown as more than it is). */
+export declare const upayToCents: (upay: string) => number;
+//# sourceMappingURL=price.d.ts.map

package/dist/lib/payments/price.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.d.ts","sourceRoot":"","sources":["../../../src/lib/payments/price.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAG7C,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAC3C,WAAW,EAAE,MAAM,GAClB,KAAK,GAAG,IAAI,CAkBd;AAED,iGAAiG;AACjG,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,MAAsD,CAAC"}

package/dist/lib/payments/price.js

@@ -0,0 +1,43 @@
+/**
+ * The price this oracle PUBLISHES per protocol (payments spec §3.1, Go Prod §11.1): what every offer
+ * charges and what `GET /v1/api/protocols/:did` serves. The facilitator refuses an offer whose
+ * per-claim amount differs from the published one (`/offers` 422 `price_mismatch`), and the public
+ * route cannot see a source — so the charged price is a function of the protocol ALONE. There are
+ * no per-source prices (contracts v1.1): a partner who should not pay gets `billingMode: none`.
+ *
+ * 1 PAY = 1 USD = 1,000,000 upay, so one cent is 10,000 upay and 1 upay is 1 micro-USD.
+ */
+import { getOracle } from "../../oracle.js";
+export const UPAY_PER_CENT = 10_000;
+/**
+ * The published price of one decision under `protocolDid` (§3.1), or null when this oracle
+ * publishes none for it — the route then serves `price: null`, which the facilitator reads as "not
+ * published", and the gate offers nothing (`gate.ts`). Resolution, protocol alone: the config's
+ * `pricing.api.byProtocol[protocolDid]`, then `pricing.api.amountMicroUsd`, then the
+ * `API_PRICE_USD_CENTS` var (× 10 000). `amountMicroUsd` and `amount` are the exact price;
+ * `amountCents` is the same price in cents — exact, because every price is a whole number of
+ * cents (`MicroUsdPrice` in oracle.ts; the var is whole cents by type).
+ */
+export function publishedPrice(config, protocolDid) {
+    const api = getOracle().config.pricing.api;
+    const cents = config.API_PRICE_USD_CENTS;
+    const amountMicroUsd = 
+    // Own keys only: an inherited name ("constructor") is not a protocol with a price.
+    (api?.byProtocol && Object.hasOwn(api.byProtocol, protocolDid)
+        ? api.byProtocol[protocolDid]
+        : undefined) ??
+        api?.amountMicroUsd ??
+        (cents === undefined ? null : cents * UPAY_PER_CENT);
+    if (amountMicroUsd === null)
+        return null;
+    return {
+        amountMicroUsd,
+        amountCents: amountMicroUsd / UPAY_PER_CENT,
+        currency: "USD",
+        amount: String(amountMicroUsd),
+        asset: "upay",
+    };
+}
+/** upay base units → whole cents, rounded DOWN (a balance is never shown as more than it is). */
+export const upayToCents = (upay) => Number(BigInt(upay) / BigInt(UPAY_PER_CENT));
+//# sourceMappingURL=price.js.map

package/dist/lib/payments/price.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"price.js","sourceRoot":"","sources":["../../../src/lib/payments/price.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,MAA2C,EAC3C,WAAmB;IAEnB,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACzC,MAAM,cAAc;IAClB,mFAAmF;IACnF,CAAC,GAAG,EAAE,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC;QAC5D,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC;QAC7B,CAAC,CAAC,SAAS,CAAC;QACd,GAAG,EAAE,cAAc;QACnB,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,aAAa,CAAC,CAAC;IACvD,IAAI,cAAc,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO;QACL,cAAc;QACd,WAAW,EAAE,cAAc,GAAG,aAAa;QAC3C,QAAQ,EAAE,KAAK;QACf,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;QAC9B,KAAK,EAAE,MAAM;KACd,CAAC;AACJ,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC"}

package/dist/lib/payments/reconcile.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The payment crons (Go Prod §7.3; payments spec §4 steps 6–7, §12), run from the API lane's
+ * five-minute tier (cron/api-lane.ts) whenever a facilitator is configured — NOT only while
+ * `API_PAYMENTS` is on: switching payments off stops new paid submits at the router, and must never
+ * strand a claim that is already reserved.
+ *
+ * `reconcilePayments` — every 5 minutes, bounded, idempotent, in this order:
+ *   (c) first — a charge still `reserved` past its reservation's expiry whose claim has no receipt
+ *       (it failed, or its review outlived the hold) ⇒ `released` (`reservation_expired`): the
+ *       facilitator released it and nothing moved. The expiry is `reservationExpiresAt` once a
+ *       review extended it (extend.ts), else the facilitator's TTL (24 h) — either + 10 min of
+ *       slack. One bounded statement. It is our reckoning, not the facilitator's word: a receipt that comes
+ *       later is still settled, and the facilitator's answer wins (settle.ts).
+ *   (d) a charge `reserved`, never extended, whose claim waits on a review (`pending_review`) —
+ *       the workflow's extend was lost ⇒ `extendForReview` again, while the 24 h hold still
+ *       stands. A refusal leaves the row to its 24 h (a 422 marks it `extend_refused`, never asked
+ *       again); every attempt touches the row, so a backlog rotates.
+ *   (a) a charge `reserved` whose claim is still `queued` 2 minutes after accept — verified and
+ *       recorded, but the start never happened (the request died, a start failed) ⇒
+ *       `startApiClaims`, which is idempotent. Only while the reservation is surely alive
+ *       (younger than 24 h − 10 min): a claim must never start on a lapsed reservation.
+ *   (b) a decided claim with a receipt whose charge is still `reserved` (the workflow's settle was
+ *       lost), `settled` (the minute's transfer has not paid it yet) or `released` by (c) ⇒
+ *       `/settle` again with the IDENTICAL body (settle.ts) until `paid` with the transaction;
+ *       `reservation_released` ⇒ `released`, a refused receipt ⇒ `failed`, neither retried.
+ *       Oldest attempt first: every attempt — a skip included — touches the row, so a backlog
+ *       rotates instead of starving. A `reserved` charge whose verified payment is gone (no header
+ *       on the row nor in KV) ⇒ `failed` (`settlement_lost`), loudly, once past its reservation's
+ *       expiry (24 h, or the review's extended one); a `settled` one is resolved by `GET /settlements/:id`, never failed.
+ *   One `payments.reconcile.report` line with the counts.
+ *
+ * `watchBalances` — every 5 minutes: active sources with a refill floor, a page at a time (a KV
+ * cursor by sourceId, wrapping around), each owner's `upay` available against the floor; one
+ * `balance.low` webhook per crossing (`api_sources.balanceLowAt`), and an email to the source's
+ * `contactEmail` once per UTC day while the balance stays under the floor (member-emails.ts).
+ *
+ * Failures: per-call failures are logged and skipped, up to `FAILURE_BUDGET` per job per run; the
+ * balance watch stops at once on an unreachable facilitator (network, its did.json).
+ */
+import type { Database } from "../../db/client.js";
+import type { OracleEnv } from "../../env.js";
+import type { Metrics } from "../metrics.js";
+import { type FacilitatorDeps } from "./facilitator.js";
+export interface PaymentCronDeps extends FacilitatorDeps {
+    db: Database;
+    env: OracleEnv;
+}
+/** Charges per arm per run — the tick stays short whatever the backlog. */
+export declare const RECONCILE_BATCH = 200;
+export interface ReconcileReport {
+    /** (a) reserved claims started. */
+    restarted: number;
+    /** (b) `/settle` calls made, and what they came to. */
+    resettled: number;
+    paid: number;
+    pending: number;
+    released: number;
+    failed: number;
+    /** The verified payment gone: marked `failed` (`settlement_lost`). */
+    lost: number;
+    /** (c) reserved past the TTL with no receipt: marked `released`. */
+    expired: number;
+    /** (d) reviews whose lost extend was retried and held. */
+    extended: number;
+    /** (e) card charges asked about their refund (refund.ts), and how many are refunded. */
+    refundChecked: number;
+    refunded: number;
+}
+export declare function reconcilePayments(deps: PaymentCronDeps, now?: Date, opts?: {
+    batch?: number;
+}): Promise<ReconcileReport>;
+export declare function watchBalances(deps: FacilitatorDeps & {
+    db: Database;
+    metrics: Metrics;
+    email?: SendEmail;
+}, now?: Date): Promise<void>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/lib/payments/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/lib/payments/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAM3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AAKvB,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,EAAE,EAAE,QAAQ,CAAC;IACb,GAAG,EAAE,SAAS,CAAC;CAChB;AAED,2EAA2E;AAC3E,eAAO,MAAM,eAAe,MAAM,CAAC;AAYnC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAcD,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,eAAe,EACrB,GAAG,OAAa,EAChB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5B,OAAO,CAAC,eAAe,CAAC,CAwB1B;AAiND,wBAAsB,aAAa,CACjC,IAAI,EAAE,eAAe,GAAG;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,EAC7E,GAAG,OAAa,GACf,OAAO,CAAC,IAAI,CAAC,CAyEf"}

package/dist/lib/payments/reconcile.js

@@ -0,0 +1,317 @@
+/**
+ * The payment crons (Go Prod §7.3; payments spec §4 steps 6–7, §12), run from the API lane's
+ * five-minute tier (cron/api-lane.ts) whenever a facilitator is configured — NOT only while
+ * `API_PAYMENTS` is on: switching payments off stops new paid submits at the router, and must never
+ * strand a claim that is already reserved.
+ *
+ * `reconcilePayments` — every 5 minutes, bounded, idempotent, in this order:
+ *   (c) first — a charge still `reserved` past its reservation's expiry whose claim has no receipt
+ *       (it failed, or its review outlived the hold) ⇒ `released` (`reservation_expired`): the
+ *       facilitator released it and nothing moved. The expiry is `reservationExpiresAt` once a
+ *       review extended it (extend.ts), else the facilitator's TTL (24 h) — either + 10 min of
+ *       slack. One bounded statement. It is our reckoning, not the facilitator's word: a receipt that comes
+ *       later is still settled, and the facilitator's answer wins (settle.ts).
+ *   (d) a charge `reserved`, never extended, whose claim waits on a review (`pending_review`) —
+ *       the workflow's extend was lost ⇒ `extendForReview` again, while the 24 h hold still
+ *       stands. A refusal leaves the row to its 24 h (a 422 marks it `extend_refused`, never asked
+ *       again); every attempt touches the row, so a backlog rotates.
+ *   (a) a charge `reserved` whose claim is still `queued` 2 minutes after accept — verified and
+ *       recorded, but the start never happened (the request died, a start failed) ⇒
+ *       `startApiClaims`, which is idempotent. Only while the reservation is surely alive
+ *       (younger than 24 h − 10 min): a claim must never start on a lapsed reservation.
+ *   (b) a decided claim with a receipt whose charge is still `reserved` (the workflow's settle was
+ *       lost), `settled` (the minute's transfer has not paid it yet) or `released` by (c) ⇒
+ *       `/settle` again with the IDENTICAL body (settle.ts) until `paid` with the transaction;
+ *       `reservation_released` ⇒ `released`, a refused receipt ⇒ `failed`, neither retried.
+ *       Oldest attempt first: every attempt — a skip included — touches the row, so a backlog
+ *       rotates instead of starving. A `reserved` charge whose verified payment is gone (no header
+ *       on the row nor in KV) ⇒ `failed` (`settlement_lost`), loudly, once past its reservation's
+ *       expiry (24 h, or the review's extended one); a `settled` one is resolved by `GET /settlements/:id`, never failed.
+ *   One `payments.reconcile.report` line with the counts.
+ *
+ * `watchBalances` — every 5 minutes: active sources with a refill floor, a page at a time (a KV
+ * cursor by sourceId, wrapping around), each owner's `upay` available against the floor; one
+ * `balance.low` webhook per crossing (`api_sources.balanceLowAt`), and an email to the source's
+ * `contactEmail` once per UTC day while the balance stays under the floor (member-emails.ts).
+ *
+ * Failures: per-call failures are logged and skipped, up to `FAILURE_BUDGET` per job per run; the
+ * balance watch stops at once on an unreachable facilitator (network, its did.json).
+ */
+import { and, asc, eq, exists, gt, inArray, isNotNull, isNull, lt, ne, not, or } from "drizzle-orm";
+import { apiCharges, apiSources, claimIngests, decisions } from "../../db/schema.js";
+import { startApiClaims } from "../api-lane/accept.js";
+import { emailBalanceLow } from "../api-lane/member-emails.js";
+import { DAY_MS } from "../api-lane/retention.js";
+import { emitBalanceLow } from "../api-lane/webhooks.js";
+import { reportAlert, reportError } from "../sentry.js";
+import { EXTEND_REFUSED, extendForReview, reservationExpiry } from "./extend.js";
+import { createFacilitatorClient, FacilitatorUnreachable, } from "./facilitator.js";
+import { upayToCents } from "./price.js";
+import { refreshRefunds } from "./refund.js";
+import { EXPIRED, settleClaim } from "./settle.js";
+/** Charges per arm per run — the tick stays short whatever the backlog. */
+export const RECONCILE_BATCH = 200;
+const WATCH_BATCH = 200;
+const FAILURE_BUDGET = 5;
+/** A start or a settle this young may still be in flight on its request or its workflow. */
+const SETTLE_GRACE_MS = 2 * 60_000;
+/** The facilitator's RESERVATION_TTL (24 h) ± slack: past the upper bound we call a reservation
+ *  released; past the lower one we no longer start its claim. */
+const RESERVATION_SLACK_MS = 10 * 60_000;
+const RESERVATION_EXPIRED_MS = DAY_MS + RESERVATION_SLACK_MS;
+const RESERVATION_ALIVE_MS = DAY_MS - RESERVATION_SLACK_MS;
+const WATCH_CURSOR = "x402-balance-cursor";
+/** A run's tolerance for per-call failures; false ⇒ stop the run. */
+function failureBudget(logger, what) {
+    let left = FAILURE_BUDGET;
+    return (err, fields) => {
+        logger.warn(`payments.${what}-failed`, { ...fields, detail: String(err) });
+        reportError(err, { lane: "payments", step: what });
+        if (err instanceof FacilitatorUnreachable)
+            return false;
+        left -= 1;
+        return left > 0;
+    };
+}
+export async function reconcilePayments(deps, now = new Date(), opts = {}) {
+    const report = {
+        restarted: 0,
+        resettled: 0,
+        paid: 0,
+        pending: 0,
+        released: 0,
+        failed: 0,
+        lost: 0,
+        expired: 0,
+        extended: 0,
+        refundChecked: 0,
+        refunded: 0,
+    };
+    const batch = opts.batch ?? RECONCILE_BATCH;
+    await expireReservations(deps, now, report, batch);
+    await extendReviews(deps, now, report, batch);
+    await restartReserved(deps, now, report, batch);
+    await resettle(deps, now, report, batch);
+    const refunds = await refreshRefunds(deps, now);
+    report.refundChecked = refunds.checked;
+    report.refunded = refunds.refunded;
+    deps.logger.info("payments.reconcile.report", { ...report });
+    return report;
+}
+async function restartReserved(deps, now, report, batch) {
+    const rows = await deps.db
+        .select({ claimId: apiCharges.claimId })
+        .from(apiCharges)
+        .innerJoin(claimIngests, eq(claimIngests.claimId, apiCharges.claimId))
+        .where(and(eq(apiCharges.status, "reserved"), eq(claimIngests.status, "queued"), 
+    // An API claim's: a chain claim (review billing) reserves inside its own run, and must
+    // never be started on the API lane.
+    eq(claimIngests.lane, "api"), lt(apiCharges.createdAt, new Date(now.getTime() - SETTLE_GRACE_MS)), gt(apiCharges.createdAt, new Date(now.getTime() - RESERVATION_ALIVE_MS))))
+        .orderBy(asc(apiCharges.createdAt))
+        .limit(batch);
+    if (rows.length === 0)
+        return;
+    const claimIds = rows.map((r) => r.claimId);
+    try {
+        await startApiClaims(deps.env, claimIds);
+        report.restarted += claimIds.length;
+    }
+    catch (err) {
+        // Retried by the next run: the rows are still reserved and queued.
+        deps.logger.error("payments.reconcile.start-failed", { claimIds, detail: String(err) });
+        // Paid for and not running: the next run retries it, but a start that keeps failing is a
+        // customer's money doing nothing — worth an issue, not only a log line.
+        reportError(err, {
+            lane: "payments",
+            step: "reconcile-start",
+            context: { claims: claimIds.length },
+        });
+    }
+}
+async function expireReservations(deps, now, report, batch) {
+    const { db } = deps;
+    const expired = await db
+        .update(apiCharges)
+        .set({ status: "released", error: EXPIRED })
+        .where(and(eq(apiCharges.status, "reserved"), inArray(apiCharges.claimId, db
+        .select({ claimId: apiCharges.claimId })
+        .from(apiCharges)
+        .where(and(eq(apiCharges.status, "reserved"), or(and(isNull(apiCharges.reservationExpiresAt), lt(apiCharges.createdAt, new Date(now.getTime() - RESERVATION_EXPIRED_MS))), lt(apiCharges.reservationExpiresAt, new Date(now.getTime() - RESERVATION_SLACK_MS))), not(exists(db
+        .select({ claimId: decisions.claimId })
+        .from(decisions)
+        .where(and(eq(decisions.claimId, apiCharges.claimId), isNotNull(decisions.receiptJws)))))))
+        .orderBy(asc(apiCharges.createdAt))
+        .limit(batch))))
+        .returning({ claimId: apiCharges.claimId });
+    report.expired += expired.length;
+}
+async function extendReviews(deps, now, report, batch) {
+    const { db } = deps;
+    const rows = await db
+        .select({ claimId: apiCharges.claimId })
+        .from(apiCharges)
+        .innerJoin(decisions, eq(decisions.claimId, apiCharges.claimId))
+        .where(and(eq(apiCharges.status, "reserved"), isNull(apiCharges.reservationExpiresAt), 
+    // A 422 marked it (extend.ts): asking again changes nothing.
+    or(isNull(apiCharges.error), ne(apiCharges.error, EXTEND_REFUSED)), eq(decisions.status, "pending_review"), 
+    // The workflow's own extend, right after the decision row: give it its moment.
+    lt(decisions.updatedAt, new Date(now.getTime() - SETTLE_GRACE_MS)), 
+    // Past 24 h the facilitator has released it: nothing left to hold.
+    gt(apiCharges.createdAt, new Date(now.getTime() - DAY_MS))))
+        .orderBy(asc(apiCharges.updatedAt))
+        .limit(batch);
+    let left = FAILURE_BUDGET;
+    for (const { claimId } of rows) {
+        const out = await extendForReview(deps, claimId);
+        if (out.status === "extended") {
+            report.extended += 1;
+            continue;
+        }
+        // A refusal or an outage (extend.ts logged it): touched, so the walk moves past it.
+        await db.update(apiCharges).set({ updatedAt: now }).where(eq(apiCharges.claimId, claimId));
+        if (out.status === "skipped" && out.reason === "unavailable") {
+            left -= 1;
+            if (left <= 0)
+                break;
+        }
+    }
+}
+async function resettle(deps, now, report, batch) {
+    const { db, logger } = deps;
+    const rows = await db
+        .select({
+        claimId: apiCharges.claimId,
+        createdAt: apiCharges.createdAt,
+        reservationExpiresAt: apiCharges.reservationExpiresAt,
+        receiptJws: decisions.receiptJws,
+    })
+        .from(apiCharges)
+        .innerJoin(decisions, eq(decisions.claimId, apiCharges.claimId))
+        .where(and(or(inArray(apiCharges.status, ["reserved", "settled"]), and(eq(apiCharges.status, "released"), eq(apiCharges.error, EXPIRED))), isNotNull(decisions.receiptJws), 
+    // The workflow's own settle, right after the decision row: give it its moment.
+    lt(decisions.updatedAt, new Date(now.getTime() - SETTLE_GRACE_MS))))
+        .orderBy(asc(apiCharges.updatedAt))
+        .limit(batch);
+    let left = FAILURE_BUDGET;
+    // A skipped row is touched, so the oldest-first walk moves past it next run.
+    const touch = (claimId) => db.update(apiCharges).set({ updatedAt: now }).where(eq(apiCharges.claimId, claimId));
+    for (const row of rows) {
+        const out = await settleClaim(deps, row.claimId, row.receiptJws);
+        if (out.status === "skipped" && out.reason === "no_payment") {
+            // KV may lag or blip: only a reservation past its expiry (an extended one's) is truly lost. (A `settled` row is
+            // never here: settle.ts resolves it through `GET /settlements/:id`.)
+            if (reservationExpiry(row).getTime() > now.getTime()) {
+                await touch(row.claimId);
+                continue;
+            }
+            const lost = await db
+                .update(apiCharges)
+                .set({ status: "failed", error: "settlement_lost" })
+                .where(and(eq(apiCharges.claimId, row.claimId), eq(apiCharges.status, "reserved")))
+                .returning({ claimId: apiCharges.claimId });
+            if (lost.length > 0) {
+                logger.error("payments.settlement-lost", { claimId: row.claimId });
+                // A paid-for claim whose payment is gone (header above): a person has to look.
+                await reportAlert(deps, "payments.settlement-lost", { claimId: row.claimId });
+                report.lost += 1;
+            }
+            else {
+                await touch(row.claimId);
+            }
+            continue;
+        }
+        if (out.status === "skipped") {
+            // An outage or an unexpected answer: settle.ts logged it.
+            await touch(row.claimId);
+            left -= 1;
+            if (left <= 0)
+                break;
+            continue;
+        }
+        report.resettled += 1;
+        if (out.status === "paid")
+            report.paid += 1;
+        else if (out.status === "settled")
+            report.pending += 1;
+        else if (out.status === "released")
+            report.released += 1;
+        else
+            report.failed += 1;
+    }
+}
+export async function watchBalances(deps, now = new Date()) {
+    const { db, logger, cache } = deps;
+    const after = await cache.get(WATCH_CURSOR);
+    const sources = await db
+        .select({
+        sourceId: apiSources.sourceId,
+        name: apiSources.name,
+        contactEmail: apiSources.contactEmail,
+        ownerDid: apiSources.ownerDid,
+        floorCents: apiSources.refillFloorCents,
+        balanceLowAt: apiSources.balanceLowAt,
+    })
+        .from(apiSources)
+        .where(and(eq(apiSources.status, "active"), isNotNull(apiSources.refillFloorCents), after ? gt(apiSources.sourceId, after) : undefined))
+        .orderBy(asc(apiSources.sourceId))
+        .limit(WATCH_BATCH);
+    const facilitator = createFacilitatorClient(deps);
+    const keepGoing = failureBudget(logger, "balance");
+    for (const s of sources) {
+        const floorCents = s.floorCents;
+        let balanceCents;
+        try {
+            const available = await facilitator.availableUpay(s.ownerDid);
+            // Not yet a payer of this oracle: nothing to watch until its first paid claim.
+            if (available === null)
+                continue;
+            balanceCents = upayToCents(available);
+        }
+        catch (err) {
+            // Unreachable: this page again next run (the cursor has not moved).
+            if (!keepGoing(err, { sourceId: s.sourceId }))
+                return;
+            continue;
+        }
+        if (balanceCents < floorCents) {
+            const low = { balanceCents, floorCents, at: now };
+            if (s.balanceLowAt) {
+                // Still low: only the email repeats — today's key makes it one a UTC day, and a send that
+                // failed earlier today is taken over here. The webhook stays once per crossing.
+                if (s.contactEmail)
+                    await emailBalanceLow(deps, s, low);
+                continue;
+            }
+            // The NULL guard makes the crossing one write, whoever else is watching.
+            const crossed = await db
+                .update(apiSources)
+                .set({ balanceLowAt: now })
+                .where(and(eq(apiSources.sourceId, s.sourceId), isNull(apiSources.balanceLowAt)))
+                .returning({ sourceId: apiSources.sourceId });
+            if (crossed.length > 0) {
+                await emitBalanceLow(db, {
+                    sourceId: s.sourceId,
+                    balanceCents,
+                    floorCents,
+                    crossedAt: now,
+                });
+                // Fail-soft (never throws): an email that did not land never holds up the watch.
+                await emailBalanceLow(deps, s, low);
+                logger.info("payments.balance-low", { sourceId: s.sourceId, balanceCents, floorCents });
+            }
+        }
+        else if (s.balanceLowAt) {
+            await db
+                .update(apiSources)
+                .set({ balanceLowAt: null })
+                .where(eq(apiSources.sourceId, s.sourceId));
+        }
+    }
+    // A short page wraps around to the first source next run.
+    const last = sources.at(-1);
+    if (last && sources.length === WATCH_BATCH)
+        await cache.put(WATCH_CURSOR, last.sourceId);
+    else
+        await cache.delete(WATCH_CURSOR);
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/lib/payments/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../src/lib/payments/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/lib/payments/refund.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A card payment's refund on the claim's charge row (S3/S6: the console must not offer Refund
+ * twice). Read from the facilitator — `GET /v1/card/refunds/:claimId`, the Stripe refunds it has
+ * for the claim — never on the console's word. PAY has no refund: its transfer is final.
+ *
+ *   - `refreshRefund`: one claim, now (S3's refresh route).
+ *   - `refreshRefunds`: the reconcile's arm — card charges paid in the last REFUND_WINDOW_DAYS,
+ *     each asked again at most every REFUND_RECHECK_MS, REFUND_BATCH per run; so a refund made
+ *     anywhere (the console, the operator's Stripe dashboard, a dispute) lands unasked.
+ *
+ * `refunded` when what was refunded (succeeded + pending) covers the claim's own cents, else
+ * `partially_refunded`; nothing refunded (none, or a refund canceled or failed) is `paid` again.
+ */
+import type { SettleDeps } from "./settle.js";
+/** A card payment can be refunded or disputed for months: Stripe's dispute window is 120 days. */
+export declare const REFUND_WINDOW_DAYS = 120;
+export declare const REFUND_RECHECK_MS: number;
+export declare const REFUND_BATCH = 25;
+export type RefundOutcome = {
+    status: "refunded" | "partially_refunded";
+    refundedAmountCents: number;
+} | {
+    status: "paid";
+} | {
+    status: "skipped";
+    reason: "no_charge" | "not_card" | "not_paid" | "unknown_to_facilitator";
+};
+export declare function refreshRefund(deps: SettleDeps, claimId: string, now?: Date): Promise<RefundOutcome>;
+/** The reconcile's refund arm (see the top). Returns how many charges it asked about. */
+export declare function refreshRefunds(deps: SettleDeps, now?: Date, batch?: number): Promise<{
+    checked: number;
+    refunded: number;
+}>;
+//# sourceMappingURL=refund.d.ts.map

package/dist/lib/payments/refund.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../../src/lib/payments/refund.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAG3C,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAC7C,eAAO,MAAM,YAAY,KAAK,CAAC;AAK/B,MAAM,MAAM,aAAa,GACrB;IAAE,MAAM,EAAE,UAAU,GAAG,oBAAoB,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,wBAAwB,CAAA;CAAE,CAAC;AAEpG,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,EACf,GAAG,OAAa,GACf,OAAO,CAAC,aAAa,CAAC,CAiExB;AAED,yFAAyF;AACzF,wBAAsB,cAAc,CAClC,IAAI,EAAE,UAAU,EAChB,GAAG,OAAa,EAChB,KAAK,SAAe,GACnB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA2ChD"}