@fantastic.dev/better-stripe 0.21.0 → 0.23.0

package/dist/component/schema.d.ts

@@ -26,8 +26,10 @@ declare const _default: import("convex/server").SchemaDefinition<{
         currency: string;
         debitFee?: number | undefined;
         debitTransactionId?: string | undefined;
+        destinationId?: string | undefined;
         expectedRevision: number;
         feeRevision?: number | undefined;
+        historical?: boolean | undefined;
         observations: {
             currency: string;
             ledgerFingerprint: string;
@@ -50,10 +52,12 @@ declare const _default: import("convex/server").SchemaDefinition<{
     }, {
         accountId: import("convex/values").VString<string, "required">;
         ownerKey: import("convex/values").VString<string, "required">;
+        historical: import("convex/values").VBoolean<boolean | undefined, "optional">;
         operationKey: import("convex/values").VString<string, "required">;
         expectedRevision: import("convex/values").VFloat64<number, "required">;
         currency: import("convex/values").VString<string, "required">;
         amount: import("convex/values").VFloat64<number, "required">;
+        destinationId: import("convex/values").VString<string | undefined, "optional">;
         allocations: import("convex/values").VArray<{
             amount: number;
             role?: "affiliate" | "other" | "store" | undefined;
@@ -107,7 +111,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
             requestId: import("convex/values").VString<string, "required">;
             code: import("convex/values").VUnion<"amount_too_small" | "balance_insufficient", [import("convex/values").VLiteral<"balance_insufficient", "required">, import("convex/values").VLiteral<"amount_too_small", "required">], "required", never>;
         }, "optional", "code" | "requestId">;
-    }, "required", "accountId" | "allocations" | "amount" | "attemptedAt" | "currency" | "debitFee" | "debitTransactionId" | "expectedRevision" | "feeRevision" | "observations" | "operationKey" | "ownerKey" | "providerFee" | "rejection" | "rejection.code" | "rejection.requestId" | "returnTransactionId" | "status" | "stripePayoutId">, {
+    }, "required", "accountId" | "allocations" | "amount" | "attemptedAt" | "currency" | "debitFee" | "debitTransactionId" | "destinationId" | "expectedRevision" | "feeRevision" | "historical" | "observations" | "operationKey" | "ownerKey" | "providerFee" | "rejection" | "rejection.code" | "rejection.requestId" | "returnTransactionId" | "status" | "stripePayoutId">, {
         by_account_status: ["accountId", "status", "_creationTime"];
         by_debit_receipt: ["debitTransactionId", "_creationTime"];
         by_operation: ["operationKey", "_creationTime"];
@@ -185,6 +189,22 @@ declare const _default: import("convex/server").SchemaDefinition<{
     }, {}, {}>;
     payoutPolicyOperations: import("convex/server").TableDefinition<import("convex/values").VObject<{
         accountId: string;
+        adoption?: {
+            claims: {
+                fingerprint: string;
+                operationKey: string;
+            }[];
+            observations: {
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: string[];
+            }[];
+            oldestHeldAt?: number | undefined;
+        } | undefined;
         attempted?: boolean | undefined;
         country: string;
         expectedRevision: number;
@@ -216,6 +236,59 @@ declare const _default: import("convex/server").SchemaDefinition<{
     }, {
         accountId: import("convex/values").VString<string, "required">;
         ownerKey: import("convex/values").VString<string, "required">;
+        adoption: import("convex/values").VObject<{
+            claims: {
+                fingerprint: string;
+                operationKey: string;
+            }[];
+            observations: {
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: string[];
+            }[];
+            oldestHeldAt?: number | undefined;
+        } | undefined, {
+            observations: import("convex/values").VArray<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: string[];
+            }[], import("convex/values").VObject<{
+                currency: string;
+                ledgerFingerprint: string;
+                matureNet: number;
+                observedAt: number;
+                pendingCredits: number;
+                stripeTransferId: string;
+                transactionIds: string[];
+            }, {
+                stripeTransferId: import("convex/values").VString<string, "required">;
+                currency: import("convex/values").VString<string, "required">;
+                matureNet: import("convex/values").VFloat64<number, "required">;
+                pendingCredits: import("convex/values").VFloat64<number, "required">;
+                ledgerFingerprint: import("convex/values").VString<string, "required">;
+                observedAt: import("convex/values").VFloat64<number, "required">;
+                transactionIds: import("convex/values").VArray<string[], import("convex/values").VString<string, "required">, "required">;
+            }, "required", "currency" | "ledgerFingerprint" | "matureNet" | "observedAt" | "pendingCredits" | "stripeTransferId" | "transactionIds">, "required">;
+            claims: import("convex/values").VArray<{
+                fingerprint: string;
+                operationKey: string;
+            }[], import("convex/values").VObject<{
+                fingerprint: string;
+                operationKey: string;
+            }, {
+                operationKey: import("convex/values").VString<string, "required">;
+                fingerprint: import("convex/values").VString<string, "required">;
+            }, "required", "fingerprint" | "operationKey">, "required">;
+            oldestHeldAt: import("convex/values").VFloat64<number | undefined, "optional">;
+        }, "optional", "claims" | "observations" | "oldestHeldAt">;
         operationKey: import("convex/values").VString<string, "required">;
         expectedRevision: import("convex/values").VFloat64<number, "required">;
         mode: import("convex/values").VUnion<"custom" | "stripe_managed", [import("convex/values").VLiteral<"stripe_managed", "required">, import("convex/values").VLiteral<"custom", "required">], "required", never>;
@@ -261,7 +334,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
         }, "required", "interval" | "monthlyDays" | "weeklyDays">;
         status: import("convex/values").VUnion<"canceled" | "complete" | "pending", [import("convex/values").VLiteral<"pending", "required">, import("convex/values").VLiteral<"complete", "required">, import("convex/values").VLiteral<"canceled", "required">], "required", never>;
         attempted: import("convex/values").VBoolean<boolean | undefined, "optional">;
-    }, "required", "accountId" | "attempted" | "country" | "expectedRevision" | "mode" | "observedAt" | "observedSchedule" | "observedSchedule.interval" | "observedSchedule.monthlyDays" | "observedSchedule.weeklyDays" | "operationKey" | "ownerKey" | "previousSchedule" | "previousSchedule.interval" | "previousSchedule.monthlyDays" | "previousSchedule.weeklyDays" | "revision" | "status" | "targetSchedule" | "targetSchedule.interval" | "targetSchedule.monthlyDays" | "targetSchedule.weeklyDays" | "thresholds">, {
+    }, "required", "accountId" | "adoption" | "adoption.claims" | "adoption.observations" | "adoption.oldestHeldAt" | "attempted" | "country" | "expectedRevision" | "mode" | "observedAt" | "observedSchedule" | "observedSchedule.interval" | "observedSchedule.monthlyDays" | "observedSchedule.weeklyDays" | "operationKey" | "ownerKey" | "previousSchedule" | "previousSchedule.interval" | "previousSchedule.monthlyDays" | "previousSchedule.weeklyDays" | "revision" | "status" | "targetSchedule" | "targetSchedule.interval" | "targetSchedule.monthlyDays" | "targetSchedule.weeklyDays" | "thresholds">, {
         by_operation: ["operationKey", "_creationTime"];
     }, {}, {}>;
     currencyTotals: import("convex/server").TableDefinition<import("convex/values").VObject<{

package/docs/settlement.md

@@ -135,14 +135,10 @@ Balance Settings API does not expose a numeric payout-floor field; this package
 does not invent one. `minimum_balance_by_currency` is a retained reserve after a
 payout, **not a minimum payout trigger**. [Stripe reserve documentation](https://docs.stripe.com/payouts/minimum-balances-for-automatic-payouts).
 
-Custom application thresholds need a separately controlled release boundary:
-
-- Before transfer: retain funds on the platform and maintain a durable payable
-  ledger, maturity, adjustments, and release claims. This changes settlement timing
-  and must account for existing transferred balances.
-- Before bank payout: use a manual payout schedule where the platform has
-  permission, and run an automatic application job. Otherwise provider automatic
-  sweeps can bypass the application threshold. A retained reserve cannot fix that.
+For a custom threshold, BetterStripe holds funds in the recipient's Stripe
+balance and controls the bank-payout schedule. Verified manual controls and a
+host automatic job prevent provider sweeps from bypassing the threshold. A
+retained reserve cannot serve as the trigger.
 
 Manual holding limits depend on country: Thailand 10 days, US 2 years, other
 countries generally 90 days. Schedule permissions depend on account controls and
@@ -152,7 +148,7 @@ See [payout schedule permissions](https://docs.stripe.com/connect/manage-payout-
 and [manual payout restrictions](https://docs.stripe.com/connect/manual-payouts).
 
 Custom threshold enforcement is not provided by the snapshot or settlement APIs.
-It requires a selected retention boundary and migration policy. Applications must
+Use the recipient-held policy, adoption and release APIs below. Applications must
 not describe a displayed threshold as enforced while Stripe controls automatic
 payouts. A numeric below/exact/above provider-floor demonstration is unavailable
 without a supported provider floor read; surface this capability limitation.
@@ -183,15 +179,15 @@ obtain control. Stripe also validates update permissions. Before each subsequent
 payout attempt, `verify` must confirm live manual settings, unchanged country,
 and an unexpired policy; stored `ready` state alone is insufficient.
 
-Initial activation rejects existing nonzero available or pending balances,
-in-flight payouts, and existing manual schedules with `migration_required`.
-The preflight is repeated before an initial schedule update; a delayed activation
-with newly arrived funds is canceled before changing Stripe. This is a bounded
-preflight, not an ownership inference or automatic adoption.
-Already-mixed funds need a reconciled source ledger and explicit adoption before
-custom release can be enabled. Zero-balance activation does not classify later
-unrelated deposits as earnings. Payout claims must use that source ledger and a
-fresh provider balance when the separate release boundary is integrated.
+Ordinary initial activation requires zero available/pending balances, no past or
+in-flight payouts, and an automatic schedule. Existing balances, payout history
+or a manual schedule return `migration_required`. The ordinary preflight repeats
+before a delayed initial write. For an owned funded account, use the explicit
+[historical import and funded activation flow](#historical-import-and-funded-activation)
+below. Unknown money is never classified as earnings merely because it is
+available. Existing manual schedules still require an authorized migration to a
+known automatic schedule before custom activation; the package does not guess
+which schedule should be restored later.
 
 The host must schedule a recurring server job that pages `due(ctx,
 { cursor: null, numItems: 100 })`, follows its cursor, and calls `expire` for each
@@ -208,10 +204,9 @@ For opt-out, prepare a new operation with the latest revision,
 available after Dashboard control is lost, subject to Stripe permissions. It
 restores only the captured schedule; other balance settings remain untouched.
 
-This is the durable policy/control boundary. Automatic combined payout execution,
-adoption of existing balances, and its UI integration are separate work and are
-not supplied by these schedule APIs. Do not expose a custom minimum as fully
-enforced until those boundaries and the recurring expiry job are installed.
+The policy/control APIs compose with historical adoption and combined release.
+Install recurring release and expiry jobs before exposing custom scheduling.
+React/example job integration and larger-account collection remain separate work.
 `verify.providerMinimum` is `null`: the Balance Settings API does not expose a
 numeric payout-floor field, and retained balance reserves are not payout triggers.
 
@@ -219,14 +214,13 @@ Sources: [payout schedules](https://docs.stripe.com/connect/manage-payout-schedu
 [manual payout holding limits](https://docs.stripe.com/connect/manual-payouts), and
 [Dashboard control limits](https://docs.stripe.com/connect/platform-controls-for-stripe-dashboard-accounts#control-payout-timing).
 
-### Transactional claim ledger implementation status
+### Transactional source allocations
 
-The component contains `payoutRelease` claim and source-allocation tables. These
-are server-side building blocks for the release boundary, with no automatic
-payout-creation or scheduled bank-payout integration yet. Do not call the claim
-mutation with UI totals or a transfer receipt alone. Its trusted upstream caller
-must establish complete provider history, still-unpaid ownership, adoption of
-prior payouts, independent liabilities, and live payout controls first.
+The package release method owns provider verification and payout creation over
+`payoutRelease` claim and source-allocation tables. Use that method rather than
+calling trusted component mutations with UI totals or an isolated transfer
+receipt. Complete provider history, still-unpaid ownership, prior payouts,
+independent liabilities and live controls must be established together.
 
 A claim combines mature creator and affiliate entitlement within one currency.
 It deducts persisted paid and reserved allocations, keeps negative entitlement
@@ -242,13 +236,11 @@ release an unaccepted claim within a conservative 23-hour window. It requires
 its own unique Stripe request receipt; ambiguous errors and older attempts stay
 held. This window stays below Stripe's [24-hour v1 idempotency retention minimum](https://docs.stripe.com/api/idempotent_requests).
 
-The current claim snapshot is deliberately bounded to 100 account transfer rows
-and 1,000 receipt IDs per source. Larger or incomplete histories reject the whole
-claim, without using partial totals. A resumable reconciliation/adoption process,
-provider payout creation and receipt verification, historical fee adoption, other account debit allocation, and
-recurring release/expiry integration remain required before custom payout
-minimums can be presented as an operational feature. In-memory claim tests are
-not evidence of a completed Stripe bank payout.
+Current atomic snapshots support 100 account transfers, 100 historical claims and
+1,000 receipt IDs per source. Larger/incomplete histories hold the whole operation
+without partial totals. Resumable larger-account collection, other provider-debit
+allocation and recurring/UI integration remain required. The package does not
+claim that component tests alone demonstrate a Stripe bank payout.
 
 ## Verified recipient funding receipts
 
@@ -366,7 +358,156 @@ require explicit allocation. Original debit receipts and their fees remain
 immutable. Older returned claims can receive verified fee evidence without
 releasing their principal again.
 
-These APIs reconcile existing claims; full automatic qualification/creation,
-historical source adoption, large-history collection, other account debit
-allocation and recurring/UI integration remain separate work. Do not expose a
-custom minimum as fully enforced solely because reconciliation is available.
+These receipt APIs reconcile existing claims. Use the release API below for
+qualification and creation; receipt reconciliation by itself does not enforce a
+minimum.
+
+## Combined recipient release
+
+After authorized custom policy activation, a host scheduled action can call:
+
+```ts
+const result = await stripe.payoutPolicy.release(ctx, {
+  accountId,
+  ownerKey,
+  operationKey, // stable unique identity for this scheduled operation
+  currency: "usd",
+  independentLiabilities, // authorized outstanding off-provider debts/reserves
+  maxPages: 10,
+});
+```
+
+Authenticate the recipient and policy, and read all known off-provider debts and
+reserves before invoking this server-only method. Never pass an untrusted client
+amount or assume that an omitted debt is zero. Provider source refunds and payout
+fees are already reconciled by the package and must not be counted again in
+`independentLiabilities`. The host must install the recurring release and expiry
+jobs before offering custom scheduling. This method does not install a cron.
+
+The package verifies live manual schedule controls, reads every account source,
+retrieves transfer and payout receipts, and compares the complete settlement
+currency balance history with those verified receipts. Unknown credits, refunds,
+fees and prior payouts return `held/unallocated_history`. A current balance is
+never treated as proof of unpaid ownership. History must reconcile to the live
+available and pending balance; changing or incomplete snapshots stay held.
+
+Mature unpaid creator and affiliate sources qualify together in integer minor
+units. Pending credits do not qualify. Outstanding source reservations, prior
+paid allocations, actual refunds, payout fees and supplied independent liabilities
+reduce eligibility. The cap uses the available card-source balance, since the
+immutable provider request explicitly selects `source_type: "card"` and a
+standard bank payout. The complete bank-account listing must identify one
+default bank for the settlement currency. Its ID is persisted with the claim,
+passed explicitly to Stripe, and checked again in the payout receipt. Other rails and currencies cannot increase that cap.
+
+A qualifying operation reserves its exact source allocations in a component
+transaction, verifies live controls again, and records the attempted marker before
+calling Stripe. The provider idempotency key and request are fixed by the durable
+claim. Concurrent callers therefore share one financial operation. Subsequent
+calls to an attempted operation only reconcile provider receipts, including when
+the original call timed out. They never blindly recreate an unidentified payout.
+A verified no-object `balance_insufficient` or `amount_too_small` rejection releases
+reservations; unknown errors keep them held. An interrupted unattempted operation
+is canceled on replay, and a new scheduled operation can collect fresh receipts.
+Below-threshold money remains owed. The numeric provider floor remains `null`
+unless a supported provider contract exposes it.
+
+Current atomic collection accepts up to 100 account transfers and 100 historical
+claims. Larger accounts return `held/snapshot_limit`, without paying a partial
+page. Provider history uses a 1–100 page budget, default 10; exhaustion stays held.
+Use the historical import and funded activation flow below for known old funds.
+Resumable larger-account collection, independent provider-debit allocation,
+recurring example jobs and React controls remain integration work. Unknown funds
+and unsupported accounts keep explicit migration holds.
+
+Sources: [payout creation and source balance selection](https://docs.stripe.com/api/payouts/create),
+[complete balance history and automatic-only payout filtering](https://docs.stripe.com/api/balance_transactions/list).
+
+## Historical import and funded activation
+
+The host authenticates one recipient account and owner, authorizes historical
+source mappings, and records consent before custom scheduling. Start with an
+owned `stripe_managed` policy at its current revision. If no policy exists,
+prepare/apply a default policy with `expectedRevision: -1`,
+`mode: "stripe_managed"`, and `thresholds: []`. This records ownership and keeps
+the current automatic schedule.
+
+Import past payouts whose allocations are not already recorded by BetterStripe:
+
+```ts
+const imported = await stripe.payoutPolicy.adoptPayouts(ctx, {
+  accountId,
+  ownerKey,
+  expectedRevision: policy.revision,
+  currency: "usd",
+  payouts: [
+    {
+      stripePayoutId: historicalPayoutId,
+      allocations: [
+        { stripeTransferId: creatorTransferId, amount: 600 },
+        { stripeTransferId: affiliateTransferId, amount: 400 },
+      ],
+    },
+  ],
+});
+```
+
+Amounts use integer settlement-currency minor units. The package does not infer
+manual-payout ownership from a present balance or Stripe's automatic-only payout
+filter. Supply authorized accounting for every unrecorded historical payout in
+the currency. Existing package claims supply their immutable allocations on
+subsequent calls; use `payouts: []` to verify/reconcile already imported history.
+The same flow supports explicit accounting for automatic historical payouts.
+
+The package retrieves actual recipient funding and payout receipts, verifies
+full history against live available/pending cash, and validates each allocation
+against source maturity at the historical payout date. Future credits and
+not-yet-mature bank returns cannot fund an earlier payout. Terminal paid and
+verified returned payouts are supported; pending or ambiguous outcomes stay
+held. Unknown credits, debits, fees or unallocated payouts require further
+reconciliation. All unknown historical payouts import as one component
+transaction, including fees and source allocations. Changed mappings and stale
+competing snapshots reject without mixing their writes. Replays never create a
+payout. Historical paid principal remains paid after later refunds, so debt
+reduces later qualifying funds rather than making the old commission payable
+again. An adopted payout can reconcile a subsequent bank failure without
+requiring a package marker that was absent from its original Stripe object.
+
+After successful import, explicitly request funded-account adoption during
+preparation, using the latest owned policy revision:
+
+```ts
+const prepared = await stripe.payoutPolicy.prepare(ctx, {
+  accountId,
+  ownerKey,
+  operationKey,
+  expectedRevision: policy.revision,
+  mode: "custom",
+  thresholds: [{ currency: "usd", amount: 1000 }],
+  consent: true,
+  adoptExistingBalance: true,
+});
+if (prepared.status === "prepared") {
+  await stripe.payoutPolicy.apply(ctx, { accountId, ownerKey, operationKey });
+}
+```
+
+Preparation verifies all settlement currencies, full source membership and prior
+payouts. It repeats provider-history and balance checks before a delayed initial
+attempt, then checks local financial fingerprints under OCC before recording
+the attempt marker. New unallocated history cancels an unattempted activation
+while preserving the automatic schedule. Refresh the policy revision and use a
+new operation key after cancellation. If a manual schedule appears without the
+package's attempt marker, the operation reports schedule drift rather than
+pretending the package performed the change. Provider timeouts retain the
+persisted attempt and immutable schedule request for reconciliation.
+
+Holding age follows the unpaid funds. Paid original credits do not age newer
+funds; source debt and verified payout fees consume older ownership first.
+Verified bank-return cash starts a new holding age when it becomes available.
+Preparation cannot restart an expired holding period, and later checks can only
+shorten the pending operation's deadline. `migration_required.adoptionReason`
+explains unknown history or an expired holding period. This flow does not enable
+Dashboard accounts with withdrawal bypasses, Global Payouts, unsupported source
+rails, unknown numeric provider floors or accounts beyond the current atomic
+snapshot bounds. It installs no host cron or UI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fantastic.dev/better-stripe",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "A Convex component for Stripe V2 Accounts API integration.",
   "keywords": [
     "stripe",

package/src/client/connect/payoutActivationProof.ts

@@ -0,0 +1,101 @@
+import type Stripe from "stripe";
+import type { Infer } from "convex/values";
+import type { Component, RunCtx } from "../helpers.js";
+import type { adoptionProof } from "../../component/payoutPolicy/schema.js";
+import type { claimDoc } from "../../component/payoutRelease/schema.js";
+import { payoutClaimFingerprint } from "../../component/payoutRelease/helpers.js";
+import { componentRef } from "../webhooks/helpers.js";
+import { adoptRecipientPayouts } from "./payoutAdoption.js";
+function balanceIdentity(b: Stripe.Balance) {
+  return JSON.stringify(
+    [b.available, b.pending].map((rows) =>
+      rows
+        .map((t) => [
+          t.currency,
+          t.amount,
+          Object.entries(t.source_types ?? {}).sort(),
+        ])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0]))),
+    ),
+  );
+}
+function transactionIdentity(t?: Stripe.BalanceTransaction) {
+  return t
+    ? JSON.stringify([
+        t.id,
+        t.source,
+        t.amount,
+        t.net,
+        t.currency,
+        t.status,
+        t.available_on,
+      ])
+    : "none";
+}
+/** Complete read/reconcile proof. Unknown historical payouts require explicit import first. */
+export async function collectAdoptionProof(
+  stripe: Stripe,
+  component: Component,
+  ctx: RunCtx,
+  scope: { accountId: string; ownerKey: string },
+  expectedRevision: number,
+  configuredCurrencies: string[],
+): Promise<
+  | { status: "verified"; proof: Infer<typeof adoptionProof> }
+  | { status: "held"; reason: string }
+> {
+  const request = { stripeAccount: scope.accountId };
+  const initial = await stripe.balance.retrieve(undefined, request);
+  const first = await stripe.balanceTransactions.list({ limit: 1 }, request);
+  const queue = new Set([
+    ...configuredCurrencies,
+    ...initial.available.map((t) => t.currency),
+    ...initial.pending.map((t) => t.currency),
+    ...(first.data[0] ? [first.data[0].currency] : []),
+  ]);
+  const completed = new Set<string>();
+  let observations: Infer<typeof adoptionProof>["observations"] = [],
+    oldestHeldAt: number | undefined;
+  for (const currency of queue) {
+    if (completed.size >= 50)
+      return { status: "held", reason: "currency_history_incomplete" };
+    const result = await adoptRecipientPayouts(
+      stripe,
+      component,
+      ctx,
+      { ...scope, currency, expectedRevision, payouts: [] },
+      true,
+    );
+    if (result.status !== "adopted") return result;
+    completed.add(currency);
+    for (const c of result.historyCurrencies) queue.add(c);
+    observations = result.observations;
+    if (result.oldestHeldAt !== undefined)
+      oldestHeldAt = Math.min(oldestHeldAt ?? Infinity, result.oldestHeldAt);
+  }
+  const balance = await stripe.balance.retrieve(undefined, request);
+  const latest = await stripe.balanceTransactions.list({ limit: 1 }, request);
+  if (
+    balanceIdentity(initial) !== balanceIdentity(balance) ||
+    transactionIdentity(first.data[0]) !== transactionIdentity(latest.data[0])
+  )
+    return { status: "held", reason: "provider_changed" };
+  const snapshot = (await ctx.runQuery(
+    componentRef(component, "payoutRelease/queries/snapshot"),
+    { accountId: scope.accountId, ownerKey: scope.ownerKey },
+  )) as
+    | { status: "ready"; claims: Infer<typeof claimDoc>[] }
+    | { status: "held"; reason: string };
+  if (snapshot.status !== "ready") return snapshot;
+  return {
+    status: "verified",
+    proof: {
+      observations,
+      claims: snapshot.claims.map((c) => ({
+        operationKey: c.operationKey,
+        fingerprint: payoutClaimFingerprint(c),
+      })),
+      ...(oldestHeldAt !== undefined ? { oldestHeldAt } : {}),
+    },
+  };
+}