open-agentpay 0.1.0 → 0.2.5

package/dist/state/guards.js

@@ -0,0 +1,211 @@
+/**
+ * State Transition Guards and Multi-Entity Validation Rules for AgentPay.
+ *
+ * Enforces:
+ *   - Transition guard matrices for Intent, Settlement, Fulfillment, and Ledger
+ *   - Strict Anti-Overspend invariant: SIGNATURE_SENT/RECOVERY_HOLD cannot release
+ *   - Strict Anti-Rollback invariant: Upstream 5xx cannot void Settlement
+ *   - Legal composite state whitelist
+ */
+import { BudgetLedgerState, FulfillmentState, PaymentIntentState, SettlementState, } from '../core/state.js';
+import { IllegalStateTransitionError, InvalidCompositeStateError, OrphanedSettlementRollbackForbiddenError, SignatureSentReleaseForbiddenError, } from './errors.js';
+// ---------------------------------------------------------------------------
+// 1. Individual Entity Transition Matrices
+// ---------------------------------------------------------------------------
+export const LEGAL_INTENT_TRANSITIONS = Object.freeze({
+    [PaymentIntentState.CREATED]: new Set([
+        PaymentIntentState.PROCESSING,
+        PaymentIntentState.AUTHORIZED,
+        PaymentIntentState.REJECTED,
+        PaymentIntentState.EXPIRED,
+        PaymentIntentState.CANCELLED,
+    ]),
+    [PaymentIntentState.AUTHORIZED]: new Set([
+        PaymentIntentState.PROCESSING,
+        PaymentIntentState.SIGNATURE_SENT,
+        PaymentIntentState.CANCELLED,
+    ]),
+    [PaymentIntentState.PROCESSING]: new Set([
+        PaymentIntentState.SIGNATURE_SENT,
+        PaymentIntentState.SUCCEEDED,
+        PaymentIntentState.COMPLETED,
+        PaymentIntentState.RECOVERY_HOLD,
+        PaymentIntentState.CANCELLED,
+    ]),
+    [PaymentIntentState.SIGNATURE_SENT]: new Set([
+        PaymentIntentState.SUCCEEDED,
+        PaymentIntentState.COMPLETED,
+        PaymentIntentState.RECOVERY_HOLD,
+    ]),
+    [PaymentIntentState.RECOVERY_HOLD]: new Set([
+        PaymentIntentState.SUCCEEDED,
+        PaymentIntentState.COMPLETED,
+        PaymentIntentState.REJECTED, // Permitted ONLY after reconciler proves nonce unspent
+    ]),
+    // Terminal states
+    [PaymentIntentState.COMPLETED]: new Set(),
+    [PaymentIntentState.SUCCEEDED]: new Set(),
+    [PaymentIntentState.REJECTED]: new Set(),
+    [PaymentIntentState.EXPIRED]: new Set(),
+    [PaymentIntentState.CANCELLED]: new Set(),
+});
+export const LEGAL_SETTLEMENT_TRANSITIONS = Object.freeze({
+    [SettlementState.NOT_STARTED]: new Set([
+        SettlementState.SUBMITTED,
+        SettlementState.PENDING,
+        SettlementState.FAILED,
+    ]),
+    [SettlementState.NOT_SUBMITTED]: new Set([
+        SettlementState.SUBMITTED,
+        SettlementState.PENDING,
+        SettlementState.FAILED,
+    ]),
+    [SettlementState.SUBMITTED]: new Set([
+        SettlementState.PENDING,
+        SettlementState.CONFIRMED,
+        SettlementState.SUCCESS,
+        SettlementState.FAILED,
+        SettlementState.UNKNOWN,
+    ]),
+    [SettlementState.PENDING]: new Set([
+        SettlementState.CONFIRMED,
+        SettlementState.SUCCESS,
+        SettlementState.FAILED,
+        SettlementState.REORGED,
+        SettlementState.UNKNOWN,
+    ]),
+    [SettlementState.REORGED]: new Set([
+        SettlementState.SUBMITTED,
+        SettlementState.FAILED,
+    ]),
+    [SettlementState.UNKNOWN]: new Set([
+        SettlementState.CONFIRMED,
+        SettlementState.SUCCESS,
+        SettlementState.PENDING,
+        SettlementState.FAILED,
+    ]),
+    // Terminal states
+    [SettlementState.CONFIRMED]: new Set(),
+    [SettlementState.SUCCESS]: new Set(),
+    [SettlementState.FAILED]: new Set(),
+});
+export const LEGAL_FULFILLMENT_TRANSITIONS = Object.freeze({
+    [FulfillmentState.NOT_STARTED]: new Set([
+        FulfillmentState.PROCESSING,
+        FulfillmentState.DELIVERING,
+        FulfillmentState.FAILED,
+    ]),
+    [FulfillmentState.NOT_DELIVERED]: new Set([
+        FulfillmentState.PROCESSING,
+        FulfillmentState.DELIVERING,
+        FulfillmentState.FAILED,
+    ]),
+    [FulfillmentState.PROCESSING]: new Set([
+        FulfillmentState.DELIVERED,
+        FulfillmentState.FAILED,
+        FulfillmentState.RECOVERY_REQUIRED,
+    ]),
+    [FulfillmentState.DELIVERING]: new Set([
+        FulfillmentState.DELIVERED,
+        FulfillmentState.FAILED,
+        FulfillmentState.RECOVERY_REQUIRED,
+    ]),
+    [FulfillmentState.RECOVERY_REQUIRED]: new Set([
+        FulfillmentState.PROCESSING,
+        FulfillmentState.DELIVERING,
+        FulfillmentState.DELIVERED,
+        FulfillmentState.FAILED,
+    ]),
+    // Terminal states
+    [FulfillmentState.DELIVERED]: new Set(),
+    [FulfillmentState.FAILED]: new Set(),
+});
+export const LEGAL_LEDGER_TRANSITIONS = Object.freeze({
+    [BudgetLedgerState.RESERVED]: new Set([
+        BudgetLedgerState.COMMITTED,
+        BudgetLedgerState.RELEASED,
+    ]),
+    // Terminal states
+    [BudgetLedgerState.COMMITTED]: new Set(),
+    [BudgetLedgerState.RELEASED]: new Set(),
+});
+// ---------------------------------------------------------------------------
+// 2. Guard Functions
+// ---------------------------------------------------------------------------
+export function validateIntentTransition(fromState, toState, options) {
+    if (fromState === toState) {
+        return;
+    }
+    // Guardrail: Once SIGNATURE_SENT or RECOVERY_HOLD, never transition to CANCELLED
+    if ((fromState === PaymentIntentState.SIGNATURE_SENT || fromState === PaymentIntentState.RECOVERY_HOLD) &&
+        toState === PaymentIntentState.CANCELLED) {
+        throw new SignatureSentReleaseForbiddenError(options?.intentId ?? '', fromState);
+    }
+    const allowed = LEGAL_INTENT_TRANSITIONS[fromState] || new Set();
+    if (!allowed.has(toState)) {
+        throw new IllegalStateTransitionError('PaymentIntent', fromState, toState, `Allowed transitions from '${fromState}': ${Array.from(allowed).join(', ')}`);
+    }
+}
+export function validateSettlementTransition(fromState, toState, options) {
+    if (fromState === toState) {
+        return;
+    }
+    // Guardrail: Active settlements cannot be reset to NOT_STARTED / NOT_SUBMITTED
+    if ((fromState === SettlementState.SUBMITTED ||
+        fromState === SettlementState.PENDING ||
+        fromState === SettlementState.CONFIRMED ||
+        fromState === SettlementState.SUCCESS) &&
+        (toState === SettlementState.NOT_STARTED || toState === SettlementState.NOT_SUBMITTED)) {
+        throw new OrphanedSettlementRollbackForbiddenError(options?.settlementId ?? '', fromState);
+    }
+    const allowed = LEGAL_SETTLEMENT_TRANSITIONS[fromState] || new Set();
+    if (!allowed.has(toState)) {
+        throw new IllegalStateTransitionError('Settlement', fromState, toState, `Allowed transitions from '${fromState}': ${Array.from(allowed).join(', ')}`);
+    }
+}
+export function validateFulfillmentTransition(fromState, toState) {
+    if (fromState === toState) {
+        return;
+    }
+    const allowed = LEGAL_FULFILLMENT_TRANSITIONS[fromState] || new Set();
+    if (!allowed.has(toState)) {
+        throw new IllegalStateTransitionError('Fulfillment', fromState, toState, `Allowed transitions from '${fromState}': ${Array.from(allowed).join(', ')}`);
+    }
+}
+export function validateLedgerTransition(fromState, toState) {
+    if (fromState === toState) {
+        return;
+    }
+    const allowed = LEGAL_LEDGER_TRANSITIONS[fromState] || new Set();
+    if (!allowed.has(toState)) {
+        throw new IllegalStateTransitionError('BudgetLedger', fromState, toState, `Ledger entry is already finalized in '${fromState}'.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// 3. Composite State Whitelist Validation
+// ---------------------------------------------------------------------------
+export function validateCompositeState(intentState, settlementState, fulfillmentState, ledgerState) {
+    // Invariant 1: Anti-Overspend Rule
+    if ((intentState === PaymentIntentState.SIGNATURE_SENT || intentState === PaymentIntentState.RECOVERY_HOLD) &&
+        ledgerState === BudgetLedgerState.RELEASED) {
+        throw new InvalidCompositeStateError(intentState, settlementState, fulfillmentState, ledgerState ?? null, 'Anti-Overspend Violation: Budget cannot be RELEASED while intent is in-flight or held.');
+    }
+    // Invariant 2: Success Alignment Rule
+    if (intentState === PaymentIntentState.SUCCEEDED || intentState === PaymentIntentState.COMPLETED) {
+        if (fulfillmentState !== FulfillmentState.DELIVERED) {
+            throw new InvalidCompositeStateError(intentState, settlementState, fulfillmentState, ledgerState ?? null, 'Intent cannot be SUCCEEDED if resource was not DELIVERED.');
+        }
+        if (ledgerState !== undefined && ledgerState !== null && ledgerState !== BudgetLedgerState.COMMITTED) {
+            throw new InvalidCompositeStateError(intentState, settlementState, fulfillmentState, ledgerState, 'Intent cannot be SUCCEEDED unless budget quota is COMMITTED.');
+        }
+    }
+    // Invariant 3: Delivered Resource Settlement Requirement
+    if (fulfillmentState === FulfillmentState.DELIVERED &&
+        settlementState !== SettlementState.SUBMITTED &&
+        settlementState !== SettlementState.PENDING &&
+        settlementState !== SettlementState.CONFIRMED &&
+        settlementState !== SettlementState.SUCCESS) {
+        throw new InvalidCompositeStateError(intentState, settlementState, fulfillmentState, ledgerState ?? null, 'Fulfillment cannot be DELIVERED if settlement was never submitted or succeeded.');
+    }
+}
+//# sourceMappingURL=guards.js.map

package/dist/state/guards.js.map

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

package/dist/state/index.d.ts

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './guards.js';
+export * from './buyer-coordinator.js';
+export * from './reconciliation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,5 @@
+export * from './errors.js';
+export * from './guards.js';
+export * from './buyer-coordinator.js';
+export * from './reconciliation.js';
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC"}

package/dist/state/reconciliation.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Reconciliation Engine for AgentPay State Coordination.
+ *
+ * Adheres strictly to:
+ *   - CLAUDE.md §6: Nonce verification, fail-closed reconciliation, and validBefore window safety
+ *   - P0-6 Invariant: Quota release permitted ONLY if nonce is proven unspent after (validBefore + safeBuffer)
+ *   - Anti-Rollback Invariant: Upstream delivery failure never rolls back valid settlement
+ */
+import { BudgetLedgerState, PaymentIntentState, SettlementState } from '../core/state.js';
+import type { Clock } from '../policy/interfaces.js';
+import type { BuyerStateCoordinator } from './buyer-coordinator.js';
+export declare enum NonceStatus {
+    UNUSED = "UNUSED",
+    USED = "USED",
+    CANCELED = "CANCELED",
+    UNKNOWN = "UNKNOWN"
+}
+export interface NonceProbeResult {
+    readonly status: NonceStatus;
+    readonly txHash?: string | null;
+    readonly detail?: string | null;
+}
+export interface SettlementProbeResult {
+    readonly status: SettlementState;
+    readonly txHash?: string | null;
+    readonly error?: string | null;
+}
+export interface ISettlementProbe {
+    probeSettlement(settlementId: string): Promise<SettlementProbeResult> | SettlementProbeResult;
+    probeNonce(networkId: string, assetAddress: string, payerAddress: string, nonce: string): Promise<NonceProbeResult> | NonceProbeResult;
+}
+export declare class MockSettlementProbe implements ISettlementProbe {
+    #private;
+    raiseOnProbe: boolean;
+    setSettlement(settlementId: string, status: SettlementState, options?: {
+        txHash?: string | null;
+        error?: string | null;
+    }): void;
+    setNonce(networkId: string, assetAddress: string, payerAddress: string, nonce: string, status: NonceStatus, options?: {
+        txHash?: string | null;
+        detail?: string | null;
+    }): void;
+    probeSettlement(settlementId: string): SettlementProbeResult;
+    probeNonce(networkId: string, assetAddress: string, payerAddress: string, nonce: string): NonceProbeResult;
+}
+export interface FacilitatorClientLike {
+    getSettlement?(settlementId: string): Promise<{
+        status: SettlementState | string;
+        txHash?: string | null;
+        error?: string | null;
+    }>;
+    isNonceUsed?(params: {
+        network: string;
+        asset: string;
+        payer: string;
+        nonce: string;
+    }): Promise<boolean>;
+}
+export interface FacilitatorSettlementProbeOptions {
+    client?: FacilitatorClientLike;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class FacilitatorSettlementProbe implements ISettlementProbe {
+    #private;
+    constructor(options?: FacilitatorSettlementProbeOptions);
+    probeSettlement(settlementId: string): Promise<SettlementProbeResult>;
+    probeNonce(networkId: string, assetAddress: string, payerAddress: string, nonce: string): Promise<NonceProbeResult>;
+}
+export declare enum BuyerReconciliationOutcome {
+    COMMITTED = "COMMITTED",
+    RELEASED = "RELEASED",
+    HELD = "HELD",
+    SKIPPED_UNKNOWN = "SKIPPED_UNKNOWN"
+}
+export declare class BuyerReconciliationReport {
+    readonly intentId: string;
+    readonly previousIntentStatus: PaymentIntentState;
+    readonly newIntentStatus: PaymentIntentState;
+    readonly ledgerState: BudgetLedgerState;
+    readonly outcome: BuyerReconciliationOutcome;
+    readonly reason: string;
+    constructor(data: {
+        intentId: string;
+        previousIntentStatus: PaymentIntentState;
+        newIntentStatus: PaymentIntentState;
+        ledgerState: BudgetLedgerState;
+        outcome: BuyerReconciliationOutcome;
+        reason: string;
+    });
+}
+export declare class BuyerReconciler {
+    #private;
+    readonly safeBufferSeconds: number;
+    readonly inFlightTimeoutSeconds: number;
+    constructor(coordinator: BuyerStateCoordinator, probe: ISettlementProbe, options?: {
+        clock?: Clock;
+        safeBufferSeconds?: number;
+        inFlightTimeoutSeconds?: number;
+    });
+    getTime(): number;
+    reconcileIntent(intentId: string): Promise<BuyerReconciliationReport>;
+    reconcileAllHeld(): Promise<BuyerReconciliationReport[]>;
+}
+//# sourceMappingURL=reconciliation.d.ts.map

package/dist/state/reconciliation.d.ts.map

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

package/dist/state/reconciliation.js

@@ -0,0 +1,297 @@
+/**
+ * Reconciliation Engine for AgentPay State Coordination.
+ *
+ * Adheres strictly to:
+ *   - CLAUDE.md §6: Nonce verification, fail-closed reconciliation, and validBefore window safety
+ *   - P0-6 Invariant: Quota release permitted ONLY if nonce is proven unspent after (validBefore + safeBuffer)
+ *   - Anti-Rollback Invariant: Upstream delivery failure never rolls back valid settlement
+ */
+import { BudgetLedgerState, PaymentIntentState, SettlementState, } from '../core/state.js';
+export var NonceStatus;
+(function (NonceStatus) {
+    NonceStatus["UNUSED"] = "UNUSED";
+    NonceStatus["USED"] = "USED";
+    NonceStatus["CANCELED"] = "CANCELED";
+    NonceStatus["UNKNOWN"] = "UNKNOWN";
+})(NonceStatus || (NonceStatus = {}));
+export class MockSettlementProbe {
+    #settlements = new Map();
+    #nonces = new Map();
+    raiseOnProbe = false;
+    setSettlement(settlementId, status, options) {
+        this.#settlements.set(settlementId, {
+            status,
+            txHash: options?.txHash ?? null,
+            error: options?.error ?? null,
+        });
+    }
+    setNonce(networkId, assetAddress, payerAddress, nonce, status, options) {
+        const key = `${networkId.toLowerCase()}:${assetAddress.toLowerCase()}:${payerAddress.toLowerCase()}:${nonce.toLowerCase()}`;
+        this.#nonces.set(key, {
+            status,
+            txHash: options?.txHash ?? null,
+            detail: options?.detail ?? null,
+        });
+    }
+    probeSettlement(settlementId) {
+        if (this.raiseOnProbe) {
+            return {
+                status: SettlementState.UNKNOWN,
+                error: 'Simulated network failure in probe',
+            };
+        }
+        return (this.#settlements.get(settlementId) ?? {
+            status: SettlementState.FAILED,
+            error: 'Settlement not found',
+        });
+    }
+    probeNonce(networkId, assetAddress, payerAddress, nonce) {
+        if (this.raiseOnProbe) {
+            return {
+                status: NonceStatus.UNKNOWN,
+                detail: 'Simulated network failure in probe',
+            };
+        }
+        const key = `${networkId.toLowerCase()}:${assetAddress.toLowerCase()}:${payerAddress.toLowerCase()}:${nonce.toLowerCase()}`;
+        return this.#nonces.get(key) ?? { status: NonceStatus.UNUSED };
+    }
+}
+export class FacilitatorSettlementProbe {
+    #client;
+    #baseUrl;
+    #fetch;
+    constructor(options) {
+        this.#client = options?.client;
+        this.#baseUrl = options?.baseUrl?.replace(/\/+$/, '');
+        this.#fetch = options?.fetch ?? globalThis.fetch;
+    }
+    async probeSettlement(settlementId) {
+        if (this.#client?.getSettlement) {
+            try {
+                const res = await this.#client.getSettlement(settlementId);
+                return {
+                    status: res.status || SettlementState.UNKNOWN,
+                    txHash: res.txHash ?? null,
+                    error: res.error ?? null,
+                };
+            }
+            catch (err) {
+                if (err?.status === 404 || String(err?.message).includes('not found')) {
+                    return { status: SettlementState.FAILED, error: 'Settlement not found' };
+                }
+                return { status: SettlementState.UNKNOWN, error: String(err?.message || err) };
+            }
+        }
+        if (this.#baseUrl) {
+            try {
+                const resp = await this.#fetch(`${this.#baseUrl}/v1/settlements/${encodeURIComponent(settlementId)}`);
+                if (resp.status === 404) {
+                    return { status: SettlementState.FAILED, error: 'Settlement not found' };
+                }
+                if (!resp.ok) {
+                    return { status: SettlementState.UNKNOWN, error: `HTTP ${resp.status}` };
+                }
+                const data = (await resp.json());
+                return {
+                    status: data.status || SettlementState.UNKNOWN,
+                    txHash: data.txHash || data.tx_hash || null,
+                    error: data.error || null,
+                };
+            }
+            catch (err) {
+                return { status: SettlementState.UNKNOWN, error: String(err?.message || err) };
+            }
+        }
+        return { status: SettlementState.UNKNOWN, error: 'No client or baseUrl configured for Facilitator probe' };
+    }
+    async probeNonce(networkId, assetAddress, payerAddress, nonce) {
+        if (this.#client?.isNonceUsed) {
+            try {
+                const isUsed = await this.#client.isNonceUsed({
+                    network: networkId,
+                    asset: assetAddress,
+                    payer: payerAddress,
+                    nonce,
+                });
+                return { status: isUsed ? NonceStatus.USED : NonceStatus.UNUSED };
+            }
+            catch (err) {
+                return { status: NonceStatus.UNKNOWN, detail: String(err?.message || err) };
+            }
+        }
+        if (this.#baseUrl) {
+            try {
+                const query = new URLSearchParams({
+                    network: networkId,
+                    asset: assetAddress,
+                    payer: payerAddress,
+                    nonce,
+                });
+                const resp = await this.#fetch(`${this.#baseUrl}/v1/nonces/status?${query.toString()}`);
+                if (!resp.ok) {
+                    return { status: NonceStatus.UNKNOWN, detail: `HTTP ${resp.status}` };
+                }
+                const data = (await resp.json());
+                const status = data.used || data.status === 'USED' ? NonceStatus.USED : NonceStatus.UNUSED;
+                return { status, txHash: data.txHash || data.tx_hash || null };
+            }
+            catch (err) {
+                return { status: NonceStatus.UNKNOWN, detail: String(err?.message || err) };
+            }
+        }
+        return { status: NonceStatus.UNKNOWN, detail: 'No client or baseUrl configured for Facilitator probe' };
+    }
+}
+export var BuyerReconciliationOutcome;
+(function (BuyerReconciliationOutcome) {
+    BuyerReconciliationOutcome["COMMITTED"] = "COMMITTED";
+    BuyerReconciliationOutcome["RELEASED"] = "RELEASED";
+    BuyerReconciliationOutcome["HELD"] = "HELD";
+    BuyerReconciliationOutcome["SKIPPED_UNKNOWN"] = "SKIPPED_UNKNOWN";
+})(BuyerReconciliationOutcome || (BuyerReconciliationOutcome = {}));
+export class BuyerReconciliationReport {
+    intentId;
+    previousIntentStatus;
+    newIntentStatus;
+    ledgerState;
+    outcome;
+    reason;
+    constructor(data) {
+        this.intentId = data.intentId;
+        this.previousIntentStatus = data.previousIntentStatus;
+        this.newIntentStatus = data.newIntentStatus;
+        this.ledgerState = data.ledgerState;
+        this.outcome = data.outcome;
+        this.reason = data.reason;
+        Object.freeze(this);
+    }
+}
+export class BuyerReconciler {
+    #coordinator;
+    #probe;
+    #clock;
+    safeBufferSeconds;
+    inFlightTimeoutSeconds;
+    constructor(coordinator, probe, options) {
+        this.#coordinator = coordinator;
+        this.#probe = probe;
+        this.#clock = options?.clock ?? (() => coordinator.getTime());
+        this.safeBufferSeconds = options?.safeBufferSeconds ?? 60;
+        this.inFlightTimeoutSeconds = options?.inFlightTimeoutSeconds ?? 30;
+    }
+    getTime() {
+        return this.#clock();
+    }
+    async reconcileIntent(intentId) {
+        const now = this.getTime();
+        let record = this.#coordinator.getIntent(intentId);
+        if (!record) {
+            throw new Error(`Buyer intent '${intentId}' not found.`);
+        }
+        let prevStatus = record.status;
+        const ledgerState = this.#coordinator.getLedgerState(intentId) || BudgetLedgerState.RELEASED;
+        // Pre-check: If intent is still in SIGNATURE_SENT but timed out, transition to RECOVERY_HOLD
+        if (prevStatus === PaymentIntentState.SIGNATURE_SENT) {
+            if (now - record.updatedAt >= this.inFlightTimeoutSeconds) {
+                this.#coordinator.holdIntent(intentId);
+                record = this.#coordinator.getIntent(intentId);
+                prevStatus = record.status;
+            }
+            else {
+                return new BuyerReconciliationReport({
+                    intentId,
+                    previousIntentStatus: prevStatus,
+                    newIntentStatus: prevStatus,
+                    ledgerState,
+                    outcome: BuyerReconciliationOutcome.HELD,
+                    reason: 'In-flight dispatch still active; waiting for response',
+                });
+            }
+        }
+        if (record.status !== PaymentIntentState.RECOVERY_HOLD) {
+            return new BuyerReconciliationReport({
+                intentId,
+                previousIntentStatus: prevStatus,
+                newIntentStatus: record.status,
+                ledgerState,
+                outcome: BuyerReconciliationOutcome.HELD,
+                reason: `Intent status '${record.status}' is not held for recovery`,
+            });
+        }
+        if (!record.nonce) {
+            return new BuyerReconciliationReport({
+                intentId,
+                previousIntentStatus: prevStatus,
+                newIntentStatus: record.status,
+                ledgerState,
+                outcome: BuyerReconciliationOutcome.SKIPPED_UNKNOWN,
+                reason: 'Intent has no recorded nonce',
+            });
+        }
+        const probeRes = await this.#probe.probeNonce(record.networkId, record.assetAddress, record.payerAddress, record.nonce);
+        // Case 1: Nonce was confirmed used on-chain / Facilitator
+        if (probeRes.status === NonceStatus.USED) {
+            this.#coordinator.completeIntent(intentId);
+            const updatedIntent = this.#coordinator.getIntent(intentId);
+            const updatedLedger = this.#coordinator.getLedgerState(intentId) || BudgetLedgerState.COMMITTED;
+            return new BuyerReconciliationReport({
+                intentId,
+                previousIntentStatus: prevStatus,
+                newIntentStatus: updatedIntent.status,
+                ledgerState: updatedLedger,
+                outcome: BuyerReconciliationOutcome.COMMITTED,
+                reason: 'Nonce was settled on-chain; quota permanently committed',
+            });
+        }
+        // Case 2: Nonce is UNUSED (or CANCELED)
+        if (probeRes.status === NonceStatus.UNUSED || probeRes.status === NonceStatus.CANCELED) {
+            const validBefore = record.validBefore || 0;
+            const safeExpiry = validBefore + this.safeBufferSeconds;
+            if (now > safeExpiry) {
+                // Authorization window safely expired and nonce unspent -> safe to release!
+                this.#coordinator.reconcileRelease(intentId, `Nonce confirmed unspent and validBefore expired (${now} > ${safeExpiry})`);
+                const updatedIntent = this.#coordinator.getIntent(intentId);
+                const updatedLedger = this.#coordinator.getLedgerState(intentId) || BudgetLedgerState.RELEASED;
+                return new BuyerReconciliationReport({
+                    intentId,
+                    previousIntentStatus: prevStatus,
+                    newIntentStatus: updatedIntent.status,
+                    ledgerState: updatedLedger,
+                    outcome: BuyerReconciliationOutcome.RELEASED,
+                    reason: `Authorization expired (${now} > ${safeExpiry}) with unspent nonce; quota released`,
+                });
+            }
+            // Anti-Double-Spend Guard: validBefore has NOT expired yet!
+            return new BuyerReconciliationReport({
+                intentId,
+                previousIntentStatus: prevStatus,
+                newIntentStatus: record.status,
+                ledgerState,
+                outcome: BuyerReconciliationOutcome.HELD,
+                reason: `Authorization still within validBefore window (${now} <= ${safeExpiry}); preserving RESERVED`,
+            });
+        }
+        // Case 3: Probe status is UNKNOWN (network error, timeout, RPC split) -> fail-closed
+        return new BuyerReconciliationReport({
+            intentId,
+            previousIntentStatus: prevStatus,
+            newIntentStatus: record.status,
+            ledgerState,
+            outcome: BuyerReconciliationOutcome.SKIPPED_UNKNOWN,
+            reason: `Probe returned UNKNOWN (${probeRes.detail || 'no detail'}); fail-closed preserve RESERVED`,
+        });
+    }
+    async reconcileAllHeld() {
+        const intents = this.#coordinator.listIntents([
+            PaymentIntentState.RECOVERY_HOLD,
+            PaymentIntentState.SIGNATURE_SENT,
+        ]);
+        const reports = [];
+        for (const it of intents) {
+            const rep = await this.reconcileIntent(it.intentId);
+            reports.push(rep);
+        }
+        return reports;
+    }
+}
+//# sourceMappingURL=reconciliation.js.map