tapimo 0.14.0 → 0.15.1

package/dist/internal/{funding → routes}/Reconciliation.js

@@ -1,31 +1,37 @@
 import { Hex } from 'ox';
+import * as z from 'zod/mini';
 import * as Db from '../../db/Db.js';
-import * as FundingDepositAddresses from '../../db/tables/fundingDepositAddresses.js';
-import * as FundingDepositRequestObservations from '../../db/tables/fundingDepositRequestObservations.js';
-import * as FundingDeposits from '../../db/tables/fundingDeposits.js';
+import * as RoutesDepositAddresses from '../../db/tables/routesDepositAddresses.js';
+import * as RoutesDepositRequestObservations from '../../db/tables/routesDepositRequestObservations.js';
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js';
+import * as MetricSink from '../MetricSink.js';
 import * as Value from '../Value.js';
 import * as Deposit from './Deposit.js';
 import * as DepositWebhook from './DepositWebhook.js';
+import * as Observability from './Observability.js';
 import * as Provider from './Provider.js';
 import * as Subsidy from './Subsidy.js';
 const defaultBatchSize = 25;
 const defaultLeaseMs = 2 * 60_000;
 const defaultPollIntervalMs = 60_000;
-const chainProviderFollowUpDelaySeconds = 1;
-const chainProviderMaximumFollowUpAttempts = 30;
+const chainCatchUpFollowUpDelaySeconds = 1;
+const chainCatchUpMaximumFollowUpAttempts = 30;
 const followUpDelaySeconds = { delivery: 1, provider: 5, settlement: 2 };
 const maximumPages = 100;
 const maximumFollowUpAttempts = 6;
+const providerMaximumFollowUpAttempts = 24;
 const providerFailureStatuses = ['failure'];
 const providerRefundStatuses = ['refund', 'refunded'];
+const unattributedBatchSize = 25;
 /** Creates a reusable-address reconciliation tracker. */
 export function createTracker(options) {
     const now = options.now ?? (() => new Date());
     const batchSize = options.batchSize ?? defaultBatchSize;
     const leaseMs = options.leaseMs ?? defaultLeaseMs;
     const pollIntervalMs = options.pollIntervalMs ?? defaultPollIntervalMs;
+    const recordProviderOperation = MetricSink.routesProviderOperations(options.metrics);
     const record = (outcome, providerId, trigger) => {
-        options.metrics?.count('funding_deposit_reconciliation_count', 1, {
+        options.metrics?.count('routes_deposit_reconciliation_count', 1, {
             outcome,
             provider: providerId,
             trigger,
@@ -60,11 +66,22 @@ export function createTracker(options) {
                 await heartbeat.ready();
                 const requests = await listRequests(provider, {
                     address: claimed,
+                    onAttempt: recordProviderOperation,
                     requestId: message.requestId,
                     signal: options.signal,
+                }).catch(async () => {
+                    // The durable poll owns provider retries; queue redelivery must not advance its backoff again.
+                    const leaseFailure = await heartbeat.stop();
+                    if (leaseFailure !== undefined)
+                        throw leaseFailure;
+                    await fail(database, claimed, now(), pollIntervalMs);
+                    record('provider_unavailable', claimed.providerId, trigger);
+                    return undefined;
                 });
+                if (!requests)
+                    return { type: 'provider_unavailable' };
                 if (trigger === 'poll')
-                    await FundingDepositRequestObservations.observePoll(database, {
+                    await RoutesDepositRequestObservations.observePoll(database, {
                         depositAddressId: claimed.id,
                         observedAt: now().toISOString(),
                         providerRequestIds: requests.requests.map((request) => request.id),
@@ -90,6 +107,7 @@ export function createTracker(options) {
                     ...requests.pendingRequestIds,
                     ...(message.requestId ? [message.requestId] : []),
                 ]);
+                const sourceRoutesIntervals = [];
                 let followUpKind;
                 for (const request of requests.requests) {
                     const result = await reconcileRequest(database, {
@@ -97,6 +115,13 @@ export function createTracker(options) {
                         metrics: options.metrics,
                         onDeposit,
                         provider,
+                        ...(options.recordLifecycleInterval
+                            ? {
+                                recordLifecycleInterval: async (interval) => {
+                                    sourceRoutesIntervals.push(interval);
+                                },
+                            }
+                            : {}),
                         request,
                         signal: options.signal,
                         subsidies: options.subsidies,
@@ -113,8 +138,14 @@ export function createTracker(options) {
                         followUpKind = result.followUp ?? followUpKind ?? 'provider';
                     }
                 }
+                const sourceRoutes = sourceRoutesIntervals.toSorted((left, right) => left.endedAt.localeCompare(right.endedAt))[0];
+                if (sourceRoutes)
+                    await options.recordLifecycleInterval?.(sourceRoutes);
+                const page = await checkpointUnattributed(database, { address: claimed, now: startedAt });
+                heartbeat.assert();
                 const unattributed = await reconcileUnattributed(database, {
                     address: claimed,
+                    deposits: page.deposits,
                     metrics: options.metrics,
                     onDeposit,
                     provider,
@@ -126,38 +157,40 @@ export function createTracker(options) {
                 updated += unattributed.updatedIds.size;
                 if (!unattributed.terminal)
                     followUpKind = unattributed.followUp ?? followUpKind ?? 'provider';
-                const awaitsProvider = await FundingDeposits.hasUnattributed(database, claimed.id);
+                const awaitsProvider = await RoutesDeposits.hasUnattributed(database, claimed.id);
                 if (message.requestId && message.webhookTiming && !webhookUpdateObserved)
                     pendingRequestIds.add(message.requestId);
                 if (created > 0)
-                    options.metrics?.count('funding_deposit_detection_count', created, {
+                    options.metrics?.count('routes_deposit_detection_count', created, {
                         provider: claimed.providerId,
                         trigger,
                     });
                 if (options.dispatchDepositUpdates && depositWebhookReferences.size > 0) {
                     const references = [...depositWebhookReferences.values()];
-                    await options.dispatchDepositUpdates(references).then((count) => options.metrics?.count('funding_deposit_webhook_enqueue_count', count, {
+                    await options.dispatchDepositUpdates(references).then((count) => options.metrics?.count('routes_deposit_webhook_enqueue_count', count, {
                         outcome: 'succeeded',
                         provider: claimed.providerId,
                     }), (cause) => {
-                        options.metrics?.count('funding_deposit_webhook_enqueue_count', references.length, {
+                        options.metrics?.count('routes_deposit_webhook_enqueue_count', references.length, {
                             outcome: 'failed',
                             provider: claimed.providerId,
                         });
                         throw cause;
                     });
                 }
+                if (unattributed.errors.length > 0)
+                    throw new AggregateError(unattributed.errors, 'Unattributed deposit reconciliation failed.');
                 const leaseFailure = await heartbeat.stop();
                 if (leaseFailure !== undefined)
                     throw leaseFailure;
                 const completedAt = now();
-                const stored = await FundingDepositAddresses.completePoll(database, {
+                const stored = await RoutesDepositAddresses.completePoll(database, {
                     id: claimed.id,
                     lastPolledAt: completedAt.toISOString(),
                     nextPollAt: new Date(completedAt.getTime() + pollIntervalMs).toISOString(),
                     pollLeaseVersion: claimed.pollLeaseVersion,
                     providerRequestIds: claimed.providerRequestIds,
-                    providerState: reconciliationState(claimed.providerState, {
+                    providerState: reconciliationState(page.address.providerState, {
                         pendingRequestIds: [...pendingRequestIds],
                         requests,
                         ...(message.webhookTiming && message.requestId && webhookUpdateObserved
@@ -182,7 +215,7 @@ export function createTracker(options) {
                             followUp: followUp.state,
                             ...(message.requestId ? { requestId: message.requestId } : {}),
                             trigger,
-                            type: 'funding:deposit-address:reconcile',
+                            type: 'routes:deposit-address:reconcile',
                             ...(message.webhookTiming && !webhookUpdateObserved
                                 ? { webhookTiming: message.webhookTiming }
                                 : {}),
@@ -200,7 +233,7 @@ export function createTracker(options) {
                         timing: message.webhookTiming,
                     });
                 record('completed', claimed.providerId, trigger);
-                options.metrics?.histogram('funding_deposit_reconciliation_duration_ms', completedAt.getTime() - startedAt.getTime(), { provider: claimed.providerId, trigger });
+                options.metrics?.histogram('routes_deposit_reconciliation_duration_ms', completedAt.getTime() - startedAt.getTime(), { provider: claimed.providerId, trigger });
                 return { created, type: 'completed', updated };
             }
             catch (cause) {
@@ -222,7 +255,7 @@ export function createTracker(options) {
             for (const provider of options.providers) {
                 if (!Provider.canListDepositAddressRequests(provider))
                     continue;
-                const records = await FundingDepositAddresses.claimDue(database, {
+                const records = await RoutesDepositAddresses.claimDue(database, {
                     leaseUntil,
                     limit: Math.max(0, batchSize - claimed),
                     now: startedAt.toISOString(),
@@ -230,13 +263,13 @@ export function createTracker(options) {
                 });
                 for (const address of records) {
                     claimed += 1;
-                    options.metrics?.histogram('funding_deposit_poll_lag_ms', Math.max(0, startedAt.getTime() - new Date(address.nextPollAt).getTime()), { provider: provider.id });
+                    options.metrics?.histogram('routes_deposit_poll_lag_ms', Math.max(0, startedAt.getTime() - new Date(address.nextPollAt).getTime()), { provider: provider.id });
                     try {
                         await options.dispatch({
                             addressId: address.id,
                             pollLeaseVersion: address.pollLeaseVersion,
                             trigger: 'poll',
-                            type: 'funding:deposit-address:reconcile',
+                            type: 'routes:deposit-address:reconcile',
                         });
                         record('enqueued', provider.id, 'poll');
                     }
@@ -256,12 +289,12 @@ export function createTracker(options) {
 }
 async function claim(db, message, options) {
     if (message.pollLeaseVersion === undefined)
-        return FundingDepositAddresses.claim(db, {
+        return RoutesDepositAddresses.claim(db, {
             id: message.addressId,
             leaseUntil: options.leaseUntil,
             now: options.now,
         });
-    const current = await FundingDepositAddresses.get(db, message.addressId);
+    const current = await RoutesDepositAddresses.get(db, message.addressId);
     if (!current?.pollLeaseUntil ||
         current.pollLeaseUntil <= options.now ||
         current.pollLeaseVersion !== message.pollLeaseVersion)
@@ -270,7 +303,7 @@ async function claim(db, message, options) {
 }
 async function fail(db, address, now, pollIntervalMs) {
     const delay = Math.min(pollIntervalMs * 2 ** address.pollFailureCount, 15 * 60_000);
-    return FundingDepositAddresses.failPoll(db, {
+    return RoutesDepositAddresses.failPoll(db, {
         id: address.id,
         nextPollAt: new Date(now.getTime() + delay).toISOString(),
         pollLeaseVersion: address.pollLeaseVersion,
@@ -282,7 +315,7 @@ function maintainLease(db, address, options) {
     const extend = async () => {
         if (stopped || failure !== undefined)
             return;
-        const renewed = await FundingDepositAddresses.renewPoll(db, {
+        const renewed = await RoutesDepositAddresses.renewPoll(db, {
             id: address.id,
             leaseUntil: new Date(options.now().getTime() + options.leaseMs).toISOString(),
             pollLeaseVersion: address.pollLeaseVersion,
@@ -324,7 +357,12 @@ async function listRequests(provider, options) {
     const requests = [];
     let continuation;
     for (let page = 0; page < maximumPages; page++) {
-        const result = await provider.listDepositAddressRequests({ address: options.address.address, ...(continuation ? { continuation } : {}) }, options.signal ?? new AbortController().signal);
+        const result = await Provider.observe(provider, () => provider.listDepositAddressRequests({
+            address: options.address.address,
+            ...(continuation ? { continuation } : {}),
+            destinationToken: options.address.snapshot.destinationToken,
+            sourceToken: options.address.snapshot.sourceToken,
+        }, options.signal ?? new AbortController().signal), { onAttempt: options.onAttempt, operation: 'listDepositAddressRequests' });
         requests.push(...result.requests.filter((request) => !highWater.updatedAt ||
             request.updatedAt > highWater.updatedAt ||
             (request.updatedAt === highWater.updatedAt &&
@@ -343,7 +381,12 @@ async function listRequests(provider, options) {
     ])) {
         if (observed.has(requestId))
             continue;
-        const result = await provider.listDepositAddressRequests({ address: options.address.address, requestId }, options.signal ?? new AbortController().signal);
+        const result = await Provider.observe(provider, () => provider.listDepositAddressRequests({
+            address: options.address.address,
+            destinationToken: options.address.snapshot.destinationToken,
+            requestId,
+            sourceToken: options.address.snapshot.sourceToken,
+        }, options.signal ?? new AbortController().signal), { onAttempt: options.onAttempt, operation: 'listDepositAddressRequests' });
         requests.push(...result.requests);
     }
     const addressRequests = requests.filter((request) => !highWater.pendingRequestIds.includes(request.id));
@@ -416,8 +459,9 @@ async function observeProviderDelivery(options) {
         !options.provider ||
         !Provider.canObserveDepositAddressRequest(options.provider))
         return undefined;
-    const result = await options.provider
-        .observeDepositAddressRequest({
+    const provider = options.provider;
+    const recordProviderOperation = MetricSink.routesProviderOperations(options.metrics);
+    const result = await Provider.observe(provider, () => provider.observeDepositAddressRequest({
         address: options.address.address,
         destinationChain: options.address.snapshot.destinationChain,
         destinationToken: options.address.providerOutputToken,
@@ -428,23 +472,52 @@ async function observeProviderDelivery(options) {
         source: entry.source,
         sourceChain: options.address.snapshot.sourceChain,
         sourceToken: options.address.snapshot.sourceToken,
-    }, options.signal ?? new AbortController().signal)
-        .catch((cause) => {
+    }, options.signal ?? new AbortController().signal), { onAttempt: recordProviderOperation, operation: 'observeDepositAddressRequest' }).catch((cause) => {
         if (options.signal?.aborted)
             throw cause;
         return undefined;
     });
-    options.metrics?.count('funding_deposit_delivery_observation_count', 1, {
+    options.metrics?.count('routes_deposit_delivery_observation_count', 1, {
         outcome: result?.type ?? 'failed',
         provider: options.address.providerId,
     });
     return result;
 }
+async function checkpointUnattributed(db, options) {
+    const parsed = z.safeParse(z.object({
+        before: z.iso.datetime(),
+        cursor: z.object({ createdAt: z.iso.datetime(), id: z.string() }),
+    }), options.address.providerState?.['unattributed']);
+    const before = parsed.success ? parsed.data.before : options.now.toISOString();
+    const deposits = await RoutesDeposits.listUnattributed(db, {
+        before,
+        cursor: parsed.success ? parsed.data.cursor : undefined,
+        depositAddressId: options.address.id,
+        limit: unattributedBatchSize,
+    });
+    if (!parsed.success && deposits.length < unattributedBatchSize)
+        return { address: options.address, deposits };
+    const last = deposits.at(-1);
+    // Checkpoint attempts before RPC work so failures cannot pin a page. A fixed boundary lets old rows recur despite new arrivals.
+    const address = await RoutesDepositAddresses.checkpointPoll(db, {
+        id: options.address.id,
+        pollLeaseVersion: options.address.pollLeaseVersion,
+        providerState: {
+            ...options.address.providerState,
+            unattributed: deposits.length === unattributedBatchSize && last
+                ? { before, cursor: { createdAt: last.createdAt, id: last.id } }
+                : undefined,
+        },
+    });
+    if (!address)
+        throw new StaleLeaseError();
+    return { address, deposits };
+}
 async function reconcileUnattributed(db, options) {
-    const deposits = await FundingDeposits.listUnattributed(db, options.address.id);
+    const { deposits } = options;
     if (deposits.length === 0)
-        return { terminal: true, updatedIds: new Set() };
-    const transfersByTransaction = new Map(await Promise.all(unique(deposits.map((deposit) => deposit.sourceTransactionHash)).map(async (transactionHash) => [
+        return { errors: [], terminal: true, updatedIds: new Set() };
+    const sources = await Promise.allSettled(unique(deposits.map((deposit) => deposit.sourceTransactionHash)).map(async (transactionHash) => [
         transactionHash,
         await options.verifyTransfers({
             chain: options.address.snapshot.sourceChain,
@@ -452,7 +525,14 @@ async function reconcileUnattributed(db, options) {
             token: options.address.snapshot.sourceToken,
             transactionHash,
         }),
-    ])));
+    ]));
+    const errors = [];
+    const transfersByTransaction = new Map();
+    for (const result of sources)
+        if (result.status === 'fulfilled')
+            transfersByTransaction.set(...result.value);
+        else
+            errors.push(result.reason);
     let followUp;
     let terminal = true;
     const updatedIds = new Set();
@@ -474,7 +554,14 @@ async function reconcileUnattributed(db, options) {
                     sourceAmount: BigInt(source.amount),
                 },
             ],
+        }).catch((cause) => {
+            errors.push(cause);
+            return undefined;
         });
+        if (!delivery) {
+            terminal = false;
+            continue;
+        }
         if (delivery.followUp === 'delivery' || !followUp)
             followUp = delivery.followUp;
         if (!delivery.terminal)
@@ -484,6 +571,7 @@ async function reconcileUnattributed(db, options) {
     }
     return {
         ...(followUp ? { followUp } : {}),
+        errors,
         terminal,
         updatedIds,
     };
@@ -491,12 +579,12 @@ async function reconcileUnattributed(db, options) {
 /** Reconciles one provider request against verified chain evidence. */
 export async function reconcileRequest(db, options) {
     const trigger = options.trigger ?? 'poll';
-    const observation = await FundingDepositRequestObservations.get(db, {
+    const observation = await RoutesDepositRequestObservations.get(db, {
         depositAddressId: options.address.id,
         providerRequestId: options.request.id,
     });
     if (observation)
-        await FundingDeposits.recordRequestObservation(db, {
+        await RoutesDeposits.recordRequestObservation(db, {
             depositAddressId: observation.depositAddressId,
             ...(observation.pollObservedAt ? { pollObservedAt: observation.pollObservedAt } : {}),
             providerRequestId: observation.providerRequestId,
@@ -508,16 +596,17 @@ export async function reconcileRequest(db, options) {
     const observed = [];
     // Persist provider observations first so transient chain failures do not hide acknowledged deposits.
     for (const transactionHash of unique(options.request.sourceTransactionHashes)) {
-        const deposits = await FundingDeposits.withSourceTransaction(db, {
+        const createdBefore = created;
+        const deposits = await RoutesDeposits.withSourceTransaction(db, {
             depositAddressId: options.address.id,
             fn: async (tx) => {
-                let records = await FundingDeposits.listByProviderObservation(tx, {
+                let records = await RoutesDeposits.listByProviderObservation(tx, {
                     depositAddressId: options.address.id,
                     providerRequestId: options.request.id,
                     sourceTransactionHash: transactionHash,
                 });
                 if (records.length === 0)
-                    records = await FundingDeposits.listBySourceTransaction(tx, {
+                    records = await RoutesDeposits.listBySourceTransaction(tx, {
                         depositAddressId: options.address.id,
                         sourceTransactionHash: transactionHash,
                     });
@@ -550,6 +639,8 @@ export async function reconcileRequest(db, options) {
             },
             sourceTransactionHash: transactionHash,
         });
+        if (created > createdBefore)
+            Observability.recordDeposit(options.metrics, { record: deposits[0] });
         observed.push({ deposits, transactionHash, transfers: [] });
     }
     const sources = await Promise.all(observed.map(async (source) => ({
@@ -609,6 +700,7 @@ export async function reconcileRequest(db, options) {
                         ? { webhookReceivedAt: observation.webhookReceivedAt }
                         : {}),
                 });
+                Observability.recordDeposit(options.metrics, { record: deposit });
                 source.deposits.push(deposit);
                 created += 1;
             }
@@ -616,20 +708,25 @@ export async function reconcileRequest(db, options) {
                 deposit.providerRequestId === null ||
                 !deposit.providerRequestIds.includes(options.request.id)) {
                 const result = await transitionDeposit(db, {
-                    expectedVersion: deposit.version,
-                    id: deposit.id,
-                    providerRequestId: options.request.id,
-                    providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
-                    providerTransferIndex,
-                    snapshot: {
-                        ...deposit.snapshot,
-                        ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
-                        ...(transfer.sender ? { sender: transfer.sender } : {}),
-                        sourceAmount,
+                    current: deposit,
+                    metrics: options.metrics,
+                    onDeposit: options.onDeposit,
+                    transition: {
+                        expectedVersion: deposit.version,
+                        id: deposit.id,
+                        providerRequestId: options.request.id,
+                        providerRequestIds: unique([...deposit.providerRequestIds, options.request.id]),
+                        providerTransferIndex,
+                        snapshot: {
+                            ...deposit.snapshot,
+                            ...(options.address.snapshot.subsidize ? { destinationAmountRequired } : {}),
+                            ...(transfer.sender ? { sender: transfer.sender } : {}),
+                            sourceAmount,
+                        },
+                        sourceTransferIndex: transfer.transferIndex,
+                        status: deposit.status === 'detected' ? 'bridging' : deposit.status,
                     },
-                    sourceTransferIndex: transfer.transferIndex,
-                    status: deposit.status === 'detected' ? 'bridging' : deposit.status,
-                }, options.onDeposit);
+                });
                 if (result.type === 'applied') {
                     deposit = result.record;
                     updatedIds.add(deposit.id);
@@ -643,6 +740,14 @@ export async function reconcileRequest(db, options) {
     if (!sourceEvidenceComplete) {
         return { created, terminal: false, updated: updatedIds.size };
     }
+    if (options.recordLifecycleInterval) {
+        const first = await RoutesDeposits.getFirstByAddress(db, options.address.id);
+        if (first &&
+            first.providerRequestId === options.request.id &&
+            updatedIds.has(first.id) &&
+            verified.some(({ deposit }) => deposit.id === first.id))
+            await options.recordLifecycleInterval(Observability.depositAddressSourceRoutesInterval(options));
+    }
     const recovery = await reconcileProviderRecovery(db, { ...options, verified });
     if (recovery) {
         for (const id of recovery.updatedIds)
@@ -664,10 +769,19 @@ export async function reconcileRequest(db, options) {
         updated: updatedIds.size,
     };
 }
-async function transitionDeposit(db, options, onDeposit) {
-    const committed = await DepositWebhook.transition(db, options);
-    if (committed.result.type === 'applied')
-        onDeposit?.(committed.result.record, committed.references);
+async function transitionDeposit(db, options) {
+    const committed = await DepositWebhook.transition(db, {
+        ...options.transition,
+        ...(options.providerEvidenceComplete ? { providerDeliveredAt: new Date().toISOString() } : {}),
+    });
+    if (committed.result.type === 'applied') {
+        Observability.recordDeposit(options.metrics, {
+            previous: options.current,
+            ...(options.providerEvidenceComplete ? { providerEvidenceComplete: true } : {}),
+            record: committed.result.record,
+        });
+        options.onDeposit?.(committed.result.record, committed.references);
+    }
     return committed.result;
 }
 async function reconcileProviderRecovery(db, options) {
@@ -725,14 +839,19 @@ async function reconcileProviderRecovery(db, options) {
         let deposit = entry.deposit;
         if (deposit.status !== 'refunding') {
             const result = await transitionDeposit(db, {
-                expectedVersion: deposit.version,
-                id: deposit.id,
-                providerTransactionHashes: unique([
-                    ...deposit.providerTransactionHashes,
-                    ...providerRefundTransactionHashes,
-                ]),
-                status: 'refunding',
-            }, options.onDeposit);
+                current: deposit,
+                metrics: options.metrics,
+                onDeposit: options.onDeposit,
+                transition: {
+                    expectedVersion: deposit.version,
+                    id: deposit.id,
+                    providerTransactionHashes: unique([
+                        ...deposit.providerTransactionHashes,
+                        ...providerRefundTransactionHashes,
+                    ]),
+                    status: 'refunding',
+                },
+            });
             if (result.type === 'applied') {
                 deposit = result.record;
                 updatedIds.add(deposit.id);
@@ -749,19 +868,24 @@ async function reconcileProviderRecovery(db, options) {
             continue;
         }
         const result = await transitionDeposit(db, {
-            expectedVersion: deposit.version,
-            id: deposit.id,
-            snapshot: {
-                ...deposit.snapshot,
-                refundAmount: Value.tokenAmount({
-                    baseUnits: amount,
-                    currency: options.address.snapshot.sourceToken.currency,
-                    decimals: options.address.snapshot.sourceToken.decimals,
-                }),
-                refundTransactionHashes,
+            current: deposit,
+            metrics: options.metrics,
+            onDeposit: options.onDeposit,
+            transition: {
+                expectedVersion: deposit.version,
+                id: deposit.id,
+                snapshot: {
+                    ...deposit.snapshot,
+                    refundAmount: Value.tokenAmount({
+                        baseUnits: amount,
+                        currency: options.address.snapshot.sourceToken.currency,
+                        decimals: options.address.snapshot.sourceToken.decimals,
+                    }),
+                    refundTransactionHashes,
+                },
+                status: 'refunded',
             },
-            status: 'refunded',
-        }, options.onDeposit);
+        });
         if (result.type === 'applied')
             updatedIds.add(deposit.id);
         else if (result.type !== 'stale' || !Deposit.isTerminal(result.current.status))
@@ -775,7 +899,7 @@ async function reconcileProviderRecovery(db, options) {
             return 'provider_failed';
         return 'pending';
     })();
-    options.metrics?.count('funding_deposit_refund_count', 1, {
+    options.metrics?.count('routes_deposit_refund_count', 1, {
         outcome,
         provider: options.address.providerId,
     });
@@ -789,7 +913,12 @@ async function reconcileDelivery(db, options) {
     let followUp;
     let terminal = true;
     const updatedIds = new Set();
-    if (options.verified.every((entry) => Deposit.isTerminal(entry.deposit.status)))
+    const allTerminal = options.verified.every((entry) => Deposit.isTerminal(entry.deposit.status));
+    // Providers can publish sponsorship after destination finality, so terminal rows
+    // remain eligible for a bounded metadata follow-up.
+    if (allTerminal &&
+        (!options.address.snapshot.subsidize ||
+            options.verified.some((entry) => entry.deposit.providerSubsidy)))
         return { terminal, updatedIds };
     const deliveryObservation = await observeProviderDelivery(options);
     if (deliveryObservation?.type === 'pending')
@@ -813,6 +942,35 @@ async function reconcileDelivery(db, options) {
         destinationEvidence.every((transfers) => transfers.length > 0);
     const providerOutput = destinationTransfers.reduce((total, transfer) => total + BigInt(transfer.amount), 0n);
     const totalRequired = options.verified.reduce((total, entry) => total + entry.required, 0n);
+    const providerSubsidy = options.request?.subsidy ??
+        (providerEvidenceComplete && deliveryObservation?.type === 'verified'
+            ? deliveryObservation.subsidy
+            : undefined);
+    // Providers report one subsidy per request, so attribute it to the first verified transfer.
+    const providerSubsidyDepositId = providerSubsidy ? options.verified[0]?.deposit.id : undefined;
+    if (allTerminal) {
+        if (!providerEvidenceComplete || !providerSubsidy)
+            return { ...(followUp ? { followUp } : {}), terminal: false, updatedIds };
+        const deposit = options.verified.find((entry) => entry.deposit.id === providerSubsidyDepositId)?.deposit;
+        if (!deposit || deposit.providerSubsidy)
+            return { terminal, updatedIds };
+        const result = await transitionDeposit(db, {
+            current: deposit,
+            metrics: options.metrics,
+            onDeposit: options.onDeposit,
+            transition: {
+                expectedVersion: deposit.version,
+                id: deposit.id,
+                providerSubsidy,
+            },
+        });
+        if (result.type === 'applied')
+            updatedIds.add(deposit.id);
+        return {
+            terminal: result.type !== 'stale' || Boolean(result.current.providerSubsidy),
+            updatedIds,
+        };
+    }
     let allocated = 0n;
     let cumulativeRequired = 0n;
     for (const entry of options.verified) {
@@ -824,92 +982,144 @@ async function reconcileDelivery(db, options) {
         const { deposit } = entry;
         if (Deposit.isTerminal(deposit.status))
             continue;
-        const settlement = await reconcileSubsidy({
-            address: options.address,
-            delivered,
-            deposit,
-            providerEvidenceComplete,
-            required,
-            sourceAmount,
-            subsidies: options.subsidies,
-            verifyTransfers: options.verifyTransfers,
-        });
+        const prepare = async (database) => {
+            const settlement = await reconcileSubsidy(database, {
+                address: options.address,
+                delivered,
+                deposit,
+                providerEvidenceComplete,
+                required,
+                sourceAmount,
+                subsidies: options.subsidies,
+                verifyTransfers: options.verifyTransfers,
+            });
+            const destinationAmount = Value.tokenAmount({
+                baseUnits: delivered + settlement.delivered,
+                currency: options.address.snapshot.destinationToken.currency,
+                decimals: options.address.snapshot.destinationToken.decimals,
+            });
+            const destinationAmountRequired = (() => {
+                if (options.address.snapshot.subsidize)
+                    return Value.tokenAmount({
+                        baseUnits: required,
+                        currency: options.address.snapshot.destinationToken.currency,
+                        decimals: options.address.snapshot.destinationToken.decimals,
+                    });
+                if (settlement.status === 'completed')
+                    return destinationAmount;
+                return undefined;
+            })();
+            return {
+                settlement,
+                transition: {
+                    expectedVersion: deposit.version,
+                    id: deposit.id,
+                    ...(delivered > 0n
+                        ? {
+                            providerOutputAmount: Value.tokenAmount({
+                                baseUnits: delivered,
+                                currency: options.address.providerOutputToken.currency,
+                                decimals: options.address.providerOutputToken.decimals,
+                            }),
+                        }
+                        : {}),
+                    ...(providerEvidenceComplete ? { providerDeliveredAt: new Date().toISOString() } : {}),
+                    ...(providerSubsidy && deposit.id === providerSubsidyDepositId
+                        ? { providerSubsidy }
+                        : {}),
+                    providerRequestIds: options.request
+                        ? unique([...deposit.providerRequestIds, options.request.id])
+                        : deposit.providerRequestIds,
+                    ...(deliveryObservation?.providerState
+                        ? {
+                            providerState: {
+                                ...deposit.providerState,
+                                ...deliveryObservation.providerState,
+                            },
+                        }
+                        : {}),
+                    providerTransactionHashes: unique([
+                        ...deposit.providerTransactionHashes,
+                        ...providerTransactionHashes,
+                        ...(deliveryObservation?.providerTransactionHashes ?? []),
+                    ]),
+                    ...(settlement.settlementTransaction
+                        ? { settlementTransaction: settlement.settlementTransaction }
+                        : {}),
+                    ...(settlement.settlementTransactionHash
+                        ? { settlementTransactionHash: settlement.settlementTransactionHash }
+                        : {}),
+                    snapshot: {
+                        ...deposit.snapshot,
+                        ...(delivered + settlement.delivered > 0n ? { destinationAmount } : {}),
+                        ...(destinationAmountRequired ? { destinationAmountRequired } : {}),
+                        destinationTransactionHashes: unique([
+                            ...(deposit.snapshot.destinationTransactionHashes ?? []),
+                            ...destinationTransfers.map((evidence) => evidence.transactionHash),
+                            ...settlement.destinationTransactionHashes,
+                        ]),
+                    },
+                    status: settlement.status,
+                    ...(settlement.statusReason ? { statusReason: settlement.statusReason } : {}),
+                    ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
+                    ...(settlement.tempoGasPaid ? { tempoGasPaid: settlement.tempoGasPaid } : {}),
+                },
+            };
+        };
+        const { committed, settlement } = await (async () => {
+            if (!options.address.snapshot.subsidize) {
+                const prepared = await prepare(db);
+                return {
+                    committed: await DepositWebhook.transition(db, prepared.transition),
+                    settlement: prepared.settlement,
+                };
+            }
+            return RoutesDeposits.withSubsidySettlement(db, {
+                fn: async (tx) => {
+                    const prepared = await prepare(tx);
+                    const result = await Deposit.transition(tx, prepared.transition);
+                    const staged = result.type === 'applied'
+                        ? await DepositWebhook.stage(tx, { records: [result.record] })
+                        : undefined;
+                    return {
+                        committed: { references: staged?.references ?? [], result },
+                        settlement: prepared.settlement,
+                    };
+                },
+                orgId: options.address.orgId,
+            });
+        })();
         if (settlement.outcome)
-            options.metrics?.count('funding_deposit_subsidy_count', 1, {
+            options.metrics?.count('routes_deposit_subsidy_count', 1, {
                 outcome: settlement.outcome,
                 provider: options.address.providerId,
             });
-        if (settlement.status === 'bridging' || settlement.status === 'settling')
+        const policyPending = settlement.outcome === 'routes_subsidy_limit_exceeded' ||
+            (settlement.outcome !== undefined && settlement.outcome in Subsidy.denialMessages);
+        if (settlement.status === 'bridging' || settlement.status === 'settling' || policyPending)
             terminal = false;
         if (settlement.status === 'settling')
             followUp = 'settlement';
-        const destinationAmount = Value.tokenAmount({
-            baseUnits: delivered + settlement.delivered,
-            currency: options.address.snapshot.destinationToken.currency,
-            decimals: options.address.snapshot.destinationToken.decimals,
-        });
-        const result = await transitionDeposit(db, {
-            expectedVersion: deposit.version,
-            id: deposit.id,
-            ...(delivered > 0n
-                ? {
-                    providerOutputAmount: Value.tokenAmount({
-                        baseUnits: delivered,
-                        currency: options.address.providerOutputToken.currency,
-                        decimals: options.address.providerOutputToken.decimals,
-                    }),
-                }
-                : {}),
-            providerRequestIds: options.request
-                ? unique([...deposit.providerRequestIds, options.request.id])
-                : deposit.providerRequestIds,
-            ...(deliveryObservation?.providerState
-                ? {
-                    providerState: {
-                        ...deposit.providerState,
-                        ...deliveryObservation.providerState,
-                    },
-                }
-                : {}),
-            providerTransactionHashes: unique([
-                ...deposit.providerTransactionHashes,
-                ...providerTransactionHashes,
-                ...(deliveryObservation?.providerTransactionHashes ?? []),
-            ]),
-            ...(settlement.settlementTransaction
-                ? { settlementTransaction: settlement.settlementTransaction }
-                : {}),
-            ...(settlement.settlementTransactionHash
-                ? { settlementTransactionHash: settlement.settlementTransactionHash }
-                : {}),
-            snapshot: {
-                ...deposit.snapshot,
-                ...(delivered + settlement.delivered > 0n ? { destinationAmount } : {}),
-                ...(settlement.status === 'completed' && !options.address.snapshot.subsidize
-                    ? { destinationAmountRequired: destinationAmount }
-                    : {}),
-                destinationTransactionHashes: unique([
-                    ...(deposit.snapshot.destinationTransactionHashes ?? []),
-                    ...destinationTransfers.map((evidence) => evidence.transactionHash),
-                    ...settlement.destinationTransactionHashes,
-                ]),
-            },
-            status: settlement.status,
-            ...(settlement.statusReason ? { statusReason: settlement.statusReason } : {}),
-            ...(settlement.subsidyAmount ? { subsidyAmount: settlement.subsidyAmount } : {}),
-            ...(settlement.tempoGasPaid ? { tempoGasPaid: settlement.tempoGasPaid } : {}),
-        }, options.onDeposit);
+        const { result } = committed;
         if (result.type === 'applied') {
+            Observability.recordDeposit(options.metrics, {
+                previous: deposit,
+                ...(providerEvidenceComplete ? { providerEvidenceComplete: true } : {}),
+                record: result.record,
+            });
+            options.onDeposit?.(result.record, committed.references);
             updatedIds.add(deposit.id);
+        }
+        if (result.type === 'applied' || result.type === 'unchanged') {
             if (settlement.broadcast && options.subsidies) {
                 await options.subsidies.broadcast(settlement.broadcast).catch((cause) => {
-                    options.metrics?.count('funding_deposit_subsidy_count', 1, {
+                    options.metrics?.count('routes_deposit_subsidy_count', 1, {
                         outcome: 'broadcast_failed',
                         provider: options.address.providerId,
                     });
                     throw cause;
                 });
-                options.metrics?.count('funding_deposit_subsidy_count', 1, {
+                options.metrics?.count('routes_deposit_subsidy_count', 1, {
                     outcome: 'broadcast',
                     provider: options.address.providerId,
                 });
@@ -918,7 +1128,7 @@ async function reconcileDelivery(db, options) {
     }
     return { ...(followUp ? { followUp } : {}), terminal, updatedIds };
 }
-async function reconcileSubsidy(options) {
+async function reconcileSubsidy(db, options) {
     const empty = { delivered: 0n, destinationTransactionHashes: [] };
     if (options.required === 0n)
         return {
@@ -959,7 +1169,11 @@ async function reconcileSubsidy(options) {
                     code: 'subsidy_failed',
                     message: 'Tempo could not deliver the required subsidy.',
                 },
-                subsidyAmount,
+                subsidyAmount: Value.tokenAmount({
+                    baseUnits: 0n,
+                    currency: options.address.snapshot.destinationToken.currency,
+                    decimals: options.address.snapshot.destinationToken.decimals,
+                }),
                 tempoGasPaid: status.tempoGasPaid,
             };
         if (status.type === 'pending')
@@ -985,7 +1199,11 @@ async function reconcileSubsidy(options) {
             destinationTransactionHashes: transfers.map((transfer) => transfer.transactionHash),
             outcome: options.delivered + delivered >= options.required ? 'completed' : 'underfilled',
             status: options.delivered + delivered >= options.required ? 'completed' : 'settling',
-            subsidyAmount,
+            subsidyAmount: Value.tokenAmount({
+                baseUnits: delivered,
+                currency: options.address.snapshot.destinationToken.currency,
+                decimals: options.address.snapshot.destinationToken.decimals,
+            }),
             tempoGasPaid: status.tempoGasPaid,
         };
     }
@@ -1007,6 +1225,33 @@ async function reconcileSubsidy(options) {
     }
     if (!options.providerEvidenceComplete)
         return { ...empty, status: 'bridging' };
+    const policy = await Subsidy.check(db, {
+        environment: options.address.environment,
+        orgId: options.address.orgId,
+    });
+    if (policy.type === 'denied')
+        return {
+            ...empty,
+            outcome: policy.reason,
+            status: 'action-required',
+            statusReason: {
+                code: policy.reason,
+                message: Subsidy.denialMessages[policy.reason],
+            },
+        };
+    if (!Subsidy.supportsGap(policy, {
+        amount: deficit,
+        destinationToken: options.address.snapshot.destinationToken,
+    }))
+        return {
+            ...empty,
+            outcome: 'routes_subsidy_limit_exceeded',
+            status: 'action-required',
+            statusReason: {
+                code: 'routes_subsidy_limit_exceeded',
+                message: 'The required subsidy exceeds the per-transaction limit.',
+            },
+        };
     if (!options.subsidies)
         return {
             ...empty,
@@ -1086,14 +1331,19 @@ function unique(values) {
 }
 function nextFollowUp(message, kind) {
     const attempt = message.followUp?.kind === kind ? message.followUp.attempt + 1 : 0;
-    const chainProvider = kind === 'provider' && message.trigger === 'chain';
-    const maximumAttempts = chainProvider
-        ? chainProviderMaximumFollowUpAttempts
-        : maximumFollowUpAttempts;
+    // Provider fee metadata can arrive after delivery, so its slower retry window outlives chain catch-up.
+    const chainCatchUp = kind === 'delivery' && message.trigger === 'chain';
+    const maximumAttempts = (() => {
+        if (chainCatchUp)
+            return chainCatchUpMaximumFollowUpAttempts;
+        if (kind === 'provider')
+            return providerMaximumFollowUpAttempts;
+        return maximumFollowUpAttempts;
+    })();
     if (attempt >= maximumAttempts)
         return undefined;
     return {
-        delaySeconds: chainProvider ? chainProviderFollowUpDelaySeconds : followUpDelaySeconds[kind],
+        delaySeconds: chainCatchUp ? chainCatchUpFollowUpDelaySeconds : followUpDelaySeconds[kind],
         state: { attempt, kind },
     };
 }
@@ -1113,7 +1363,7 @@ function recordWebhookLatency(metrics, options) {
         { from: providerUpdatedAt, segment: 'provider_to_reconciled', to: completedAt },
     ];
     for (const segment of segments)
-        metrics.histogram('funding_deposit_webhook_latency_ms', Math.max(0, segment.to - segment.from), {
+        metrics.histogram('routes_deposit_webhook_latency_ms', Math.max(0, segment.to - segment.from), {
             provider: options.providerId,
             segment: segment.segment,
             status: options.timing.providerStatus,
@@ -1121,10 +1371,10 @@ function recordWebhookLatency(metrics, options) {
 }
 /** Provider pagination exceeded the bounded reconciliation limit. */
 export class PaginationLimitError extends Error {
-    name = 'Funding.Reconciliation.PaginationLimitError';
+    name = 'Routes.Reconciliation.PaginationLimitError';
 }
 /** The reconciliation lease was claimed by another worker. */
 export class StaleLeaseError extends Error {
-    name = 'Funding.Reconciliation.StaleLeaseError';
+    name = 'Routes.Reconciliation.StaleLeaseError';
 }
 //# sourceMappingURL=Reconciliation.js.map