settld 0.1.1 → 0.1.5

package/src/api/store.js

@@ -18,23 +18,100 @@ import { computeFinanceAccountMapHash, validateFinanceAccountMapV1 } from "../co
 import { appendChainedEvent, createChainedEvent } from "../core/event-chain.js";
 import { normalizeBillingPlanId } from "../core/billing-plans.js";
 
+const SERVER_SIGNER_FILENAME = "server-signer.json";
+const SETTLD_PAY_KEYSET_STORE_FILENAME = "settld-pay-keyset-store.json";
+
+function readJsonFileSafe(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, "utf8");
+  return JSON.parse(raw);
+}
+
+function normalizeSettldPayPreviousRows(rows) {
+  const out = [];
+  const list = Array.isArray(rows) ? rows : [];
+  const seen = new Set();
+  for (const row of list) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    const publicKeyPem = typeof row.publicKeyPem === "string" ? row.publicKeyPem : "";
+    if (!publicKeyPem.trim()) continue;
+    const derivedKeyId = keyIdFromPublicKeyPem(publicKeyPem);
+    const keyId = typeof row.keyId === "string" && row.keyId.trim() !== "" ? row.keyId.trim() : derivedKeyId;
+    if (keyId !== derivedKeyId) throw new Error("invalid settld-pay-keyset-store.json: previous[].keyId mismatch");
+    if (seen.has(keyId)) continue;
+    seen.add(keyId);
+    const rotatedAt = typeof row.rotatedAt === "string" && row.rotatedAt.trim() !== "" ? row.rotatedAt.trim() : null;
+    out.push({ keyId, publicKeyPem, rotatedAt });
+  }
+  return out;
+}
+
+function normalizeSettldPayKeysetStore(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("invalid settld-pay-keyset-store.json: object expected");
+  }
+  const active = payload.active;
+  if (!active || typeof active !== "object" || Array.isArray(active)) {
+    throw new Error("invalid settld-pay-keyset-store.json: active key missing");
+  }
+  const activePublicKeyPem = typeof active.publicKeyPem === "string" ? active.publicKeyPem : "";
+  const activePrivateKeyPem = typeof active.privateKeyPem === "string" ? active.privateKeyPem : "";
+  if (!activePublicKeyPem.trim() || !activePrivateKeyPem.trim()) {
+    throw new Error("invalid settld-pay-keyset-store.json: active keypair missing");
+  }
+  const activeDerivedKeyId = keyIdFromPublicKeyPem(activePublicKeyPem);
+  const activeKeyId = typeof active.keyId === "string" && active.keyId.trim() !== "" ? active.keyId.trim() : activeDerivedKeyId;
+  if (activeKeyId !== activeDerivedKeyId) throw new Error("invalid settld-pay-keyset-store.json: active.keyId mismatch");
+
+  const previous = normalizeSettldPayPreviousRows(payload.previous);
+  return {
+    active: {
+      keyId: activeKeyId,
+      publicKeyPem: activePublicKeyPem,
+      privateKeyPem: activePrivateKeyPem
+    },
+    previous
+  };
+}
+
 function loadOrCreateServerSigner({ persistenceDir }) {
   if (!persistenceDir) {
     const { publicKeyPem, privateKeyPem } = createEd25519Keypair();
-    return { publicKeyPem, privateKeyPem };
+    return { active: { publicKeyPem, privateKeyPem }, previous: [], source: "generated-ephemeral" };
   }
 
   fs.mkdirSync(persistenceDir, { recursive: true });
-  const signerPath = path.join(persistenceDir, "server-signer.json");
+  const keysetStorePath = path.join(persistenceDir, SETTLD_PAY_KEYSET_STORE_FILENAME);
+  const signerPath = path.join(persistenceDir, SERVER_SIGNER_FILENAME);
+  if (fs.existsSync(keysetStorePath)) {
+    const parsed = readJsonFileSafe(keysetStorePath);
+    const normalized = normalizeSettldPayKeysetStore(parsed);
+    // Keep legacy signer file in sync for compatibility with existing tooling.
+    fs.writeFileSync(
+      signerPath,
+      JSON.stringify({ publicKeyPem: normalized.active.publicKeyPem, privateKeyPem: normalized.active.privateKeyPem }, null, 2),
+      "utf8"
+    );
+    return {
+      active: { publicKeyPem: normalized.active.publicKeyPem, privateKeyPem: normalized.active.privateKeyPem },
+      previous: normalized.previous,
+      source: "keyset-store"
+    };
+  }
+
   if (fs.existsSync(signerPath)) {
     const parsed = JSON.parse(fs.readFileSync(signerPath, "utf8"));
     if (!parsed?.publicKeyPem || !parsed?.privateKeyPem) throw new Error("invalid server-signer.json");
-    return { publicKeyPem: parsed.publicKeyPem, privateKeyPem: parsed.privateKeyPem };
+    return {
+      active: { publicKeyPem: parsed.publicKeyPem, privateKeyPem: parsed.privateKeyPem },
+      previous: [],
+      source: "legacy-signer"
+    };
   }
 
   const { publicKeyPem, privateKeyPem } = createEd25519Keypair();
   fs.writeFileSync(signerPath, JSON.stringify({ publicKeyPem, privateKeyPem }, null, 2), "utf8");
-  return { publicKeyPem, privateKeyPem };
+  return { active: { publicKeyPem, privateKeyPem }, previous: [], source: "generated-persistent" };
 }
 
 export function createStore({ persistenceDir = null, serverSignerKeypair = null } = {}) {
@@ -49,8 +126,18 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     throw new Error("invalid serverSignerKeypair");
   }
 
-  const { publicKeyPem: serverPublicKeyPem, privateKeyPem: serverPrivateKeyPem } =
-    resolvedServerSignerKeypair ?? loadOrCreateServerSigner({ persistenceDir });
+  const loadedServerSigner =
+    resolvedServerSignerKeypair === null
+      ? loadOrCreateServerSigner({ persistenceDir })
+      : {
+          active: {
+            publicKeyPem: resolvedServerSignerKeypair.publicKeyPem,
+            privateKeyPem: resolvedServerSignerKeypair.privateKeyPem
+          },
+          previous: [],
+          source: "explicit-override"
+        };
+  const { publicKeyPem: serverPublicKeyPem, privateKeyPem: serverPrivateKeyPem } = loadedServerSigner.active;
   const serverKeyId = keyIdFromPublicKeyPem(serverPublicKeyPem);
 
   function parseEvidenceRetentionMaxDaysByTenant() {
@@ -222,6 +309,19 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     agentRunEvents: new Map(), // `${tenantId}\n${runId}` -> AgentEvent.v1[]
     agentRunSettlements: new Map(), // `${tenantId}\n${runId}` -> AgentRunSettlement.v1
     arbitrationCases: new Map(), // `${tenantId}\n${caseId}` -> ArbitrationCase.v1 snapshot
+    agreementDelegations: new Map(), // `${tenantId}\n${delegationId}` -> AgreementDelegation.v1
+    x402Gates: new Map(), // `${tenantId}\n${gateId}` -> X402 gate record (internal API surface)
+    x402Receipts: new Map(), // `${tenantId}\n${receiptId}` -> immutable X402ReceiptRecord.v1 base record
+    x402WalletPolicies: new Map(), // `${tenantId}\n${sponsorWalletRef}::${policyRef}::${policyVersion}` -> X402WalletPolicy.v1
+    x402ZkVerificationKeys: new Map(), // `${tenantId}\n${verificationKeyId}` -> X402ZkVerificationKey.v1
+    x402ReversalEvents: new Map(), // `${tenantId}\n${eventId}` -> X402GateReversalEvent.v1
+    x402ReversalNonceUsage: new Map(), // `${tenantId}\n${sponsorRef}\n${nonce}` -> X402ReversalNonceUsage.v1
+    x402ReversalCommandUsage: new Map(), // `${tenantId}\n${commandId}` -> X402ReversalCommandUsage.v1
+    x402Escalations: new Map(), // `${tenantId}\n${escalationId}` -> X402AuthorizationEscalation.v1
+    x402EscalationEvents: new Map(), // `${tenantId}\n${eventId}` -> X402AuthorizationEscalationEvent.v1
+    x402EscalationOverrideUsage: new Map(), // `${tenantId}\n${overrideId}` -> X402EscalationOverrideUsage.v1
+    x402AgentLifecycles: new Map(), // `${tenantId}\n${agentId}` -> X402AgentLifecycle.v1
+    x402WebhookEndpoints: new Map(), // `${tenantId}\n${endpointId}` -> X402WebhookEndpoint.v1
     toolCallHolds: new Map(), // `${tenantId}\n${holdHash}` -> FundingHold.v1 snapshot
     settlementAdjustments: new Map(), // `${tenantId}\n${adjustmentId}` -> SettlementAdjustment.v1 snapshot
     moneyRailOperations: new Map(), // `${tenantId}\n${providerId}\n${operationId}` -> MoneyRailOperation.v1
@@ -230,12 +330,14 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     financeReconciliationTriages: new Map(), // `${tenantId}\n${triageKey}` -> FinanceReconciliationTriage.v1
     marketplaceRfqs: new Map(), // `${tenantId}\n${rfqId}` -> MarketplaceRfq.v1
     marketplaceRfqBids: new Map(), // `${tenantId}\n${rfqId}` -> MarketplaceBid.v1[]
+    marketplaceProviderPublications: new Map(), // `${tenantId}\n${providerRef}` -> MarketplaceProviderPublication.v1
     tenantSettlementPolicies: new Map(), // `${tenantId}\n${policyId}\n${policyVersion}` -> TenantSettlementPolicy.v1
     tenantSettlementPolicyRollouts: new Map(), // `${tenantId}\nrollout` -> TenantSettlementPolicyRollout.v1
 	    contracts: new Map(), // `${tenantId}\n${contractId}` -> contract
 	    idempotency: new Map(),
 	    publicKeyByKeyId,
 	    serverSigner: { keyId: serverKeyId, publicKeyPem: serverPublicKeyPem, privateKeyPem: serverPrivateKeyPem },
+      settldPayFallbackKeys: loadedServerSigner.previous.map((row) => ({ keyId: row.keyId, publicKeyPem: row.publicKeyPem })),
 	    ledgerByTenant,
 	    // Back-compat: keep store.ledger and store.config as the default tenant's objects.
 	    ledger: ledgerByTenant.get(DEFAULT_TENANT_ID),
@@ -254,6 +356,7 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     monthCloseCursor: 0,
     artifactCursor: 0,
     deliveryCursor: 0,
+    x402WinddownReversalCursor: 0,
     persistence: persistenceDir ? createFileTxLog({ dir: persistenceDir }) : null
   };
 
@@ -782,12 +885,1102 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     return store.agentRunSettlements.get(makeScopedKey({ tenantId, id: String(runId) })) ?? null;
   };
 
+  store.sumWalletPolicySpendCentsForDay = async function sumWalletPolicySpendCentsForDay({
+    tenantId = DEFAULT_TENANT_ID,
+    agentId,
+    dayStartIso,
+    dayEndIso
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof agentId !== "string" || agentId.trim() === "") throw new TypeError("agentId is required");
+    if (typeof dayStartIso !== "string" || dayStartIso.trim() === "" || !Number.isFinite(Date.parse(dayStartIso))) {
+      throw new TypeError("dayStartIso must be an ISO date string");
+    }
+    if (typeof dayEndIso !== "string" || dayEndIso.trim() === "" || !Number.isFinite(Date.parse(dayEndIso))) {
+      throw new TypeError("dayEndIso must be an ISO date string");
+    }
+    const startMs = Date.parse(dayStartIso);
+    const endMs = Date.parse(dayEndIso);
+    if (!(endMs > startMs)) throw new TypeError("dayEndIso must be after dayStartIso");
+
+    let total = 0;
+
+    // Agent run settlements lock escrow for the full settlement amount.
+    for (const row of store.agentRunSettlements.values()) {
+      if (!row || typeof row !== "object") continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (String(row.payerAgentId ?? "") !== String(agentId)) continue;
+      const lockedAt = row.lockedAt ?? null;
+      const lockedMs = typeof lockedAt === "string" ? Date.parse(lockedAt) : NaN;
+      if (!Number.isFinite(lockedMs) || lockedMs < startMs || lockedMs >= endMs) continue;
+      const amountCents = Number(row.amountCents ?? 0);
+      if (!Number.isSafeInteger(amountCents) || amountCents <= 0) continue;
+      total += amountCents;
+    }
+
+    // Tool-call holds lock escrow for the holdback amount only.
+    for (const row of store.toolCallHolds.values()) {
+      if (!row || typeof row !== "object") continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (String(row.payerAgentId ?? "") !== String(agentId)) continue;
+      const createdAt = row.createdAt ?? null;
+      const createdMs = typeof createdAt === "string" ? Date.parse(createdAt) : NaN;
+      if (!Number.isFinite(createdMs) || createdMs < startMs || createdMs >= endMs) continue;
+      const heldAmountCents = Number(row.heldAmountCents ?? 0);
+      if (!Number.isSafeInteger(heldAmountCents) || heldAmountCents <= 0) continue;
+      total += heldAmountCents;
+    }
+
+    return total;
+  };
+
   store.getArbitrationCase = async function getArbitrationCase({ tenantId = DEFAULT_TENANT_ID, caseId } = {}) {
     tenantId = normalizeTenantId(tenantId);
     if (typeof caseId !== "string" || caseId.trim() === "") throw new TypeError("caseId is required");
     return store.arbitrationCases.get(makeScopedKey({ tenantId, id: String(caseId) })) ?? null;
   };
 
+  store.getAgreementDelegation = async function getAgreementDelegation({ tenantId = DEFAULT_TENANT_ID, delegationId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof delegationId !== "string" || delegationId.trim() === "") throw new TypeError("delegationId is required");
+    return store.agreementDelegations.get(makeScopedKey({ tenantId, id: String(delegationId) })) ?? null;
+  };
+
+  store.putAgreementDelegation = async function putAgreementDelegation({ tenantId = DEFAULT_TENANT_ID, delegation, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!delegation || typeof delegation !== "object" || Array.isArray(delegation)) throw new TypeError("delegation is required");
+    const delegationId = delegation.delegationId ?? null;
+    if (typeof delegationId !== "string" || delegationId.trim() === "") throw new TypeError("delegation.delegationId is required");
+    const key = makeScopedKey({ tenantId, id: String(delegationId) });
+    const at = delegation.updatedAt ?? new Date().toISOString();
+    await store.commitTx({ at, ops: [{ kind: "AGREEMENT_DELEGATION_UPSERT", tenantId, delegationId, delegation: { ...delegation, tenantId, delegationId } }], audit });
+    return store.agreementDelegations.get(key) ?? null;
+  };
+
+  store.listAgreementDelegations = async function listAgreementDelegations({
+    tenantId = DEFAULT_TENANT_ID,
+    parentAgreementHash = null,
+    childAgreementHash = null,
+    status = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (parentAgreementHash !== null && (typeof parentAgreementHash !== "string" || parentAgreementHash.trim() === "")) {
+      throw new TypeError("parentAgreementHash must be null or a non-empty string");
+    }
+    if (childAgreementHash !== null && (typeof childAgreementHash !== "string" || childAgreementHash.trim() === "")) {
+      throw new TypeError("childAgreementHash must be null or a non-empty string");
+    }
+    if (status !== null && (typeof status !== "string" || status.trim() === "")) throw new TypeError("status must be null or a non-empty string");
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const statusFilter = status ? String(status).trim().toLowerCase() : null;
+    const parentFilter = parentAgreementHash ? String(parentAgreementHash).trim().toLowerCase() : null;
+    const childFilter = childAgreementHash ? String(childAgreementHash).trim().toLowerCase() : null;
+    const safeLimit = Math.min(1000, limit);
+    const safeOffset = offset;
+    const out = [];
+    for (const row of store.agreementDelegations.values()) {
+      if (!row || typeof row !== "object") continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (parentFilter && String(row.parentAgreementHash ?? "").toLowerCase() !== parentFilter) continue;
+      if (childFilter && String(row.childAgreementHash ?? "").toLowerCase() !== childFilter) continue;
+      if (statusFilter !== null && String(row.status ?? "").toLowerCase() !== statusFilter) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => String(left.delegationId ?? "").localeCompare(String(right.delegationId ?? "")));
+    return out.slice(safeOffset, safeOffset + safeLimit);
+  };
+
+  store.getX402Gate = async function getX402Gate({ tenantId = DEFAULT_TENANT_ID, gateId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof gateId !== "string" || gateId.trim() === "") throw new TypeError("gateId is required");
+    return store.x402Gates.get(makeScopedKey({ tenantId, id: String(gateId) })) ?? null;
+  };
+
+  store.putX402Gate = async function putX402Gate({ tenantId = DEFAULT_TENANT_ID, gate, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!gate || typeof gate !== "object" || Array.isArray(gate)) throw new TypeError("gate is required");
+    const gateId = gate.gateId ?? gate.id ?? null;
+    if (typeof gateId !== "string" || gateId.trim() === "") throw new TypeError("gate.gateId is required");
+    const key = makeScopedKey({ tenantId, id: String(gateId) });
+    const at = gate.updatedAt ?? gate.createdAt ?? new Date().toISOString();
+    await store.commitTx({ at, ops: [{ kind: "X402_GATE_UPSERT", tenantId, gateId, gate: { ...gate, tenantId, gateId: String(gateId) } }], audit });
+    return store.x402Gates.get(key) ?? null;
+  };
+
+  store.putX402AgentLifecycle = async function putX402AgentLifecycle({ tenantId = DEFAULT_TENANT_ID, agentLifecycle, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!agentLifecycle || typeof agentLifecycle !== "object" || Array.isArray(agentLifecycle)) {
+      throw new TypeError("agentLifecycle is required");
+    }
+    const agentId = typeof agentLifecycle.agentId === "string" ? agentLifecycle.agentId.trim() : "";
+    if (!agentId) throw new TypeError("agentLifecycle.agentId is required");
+    const status = typeof agentLifecycle.status === "string" ? agentLifecycle.status.trim().toLowerCase() : "";
+    if (status !== "active" && status !== "frozen" && status !== "archived") {
+      throw new TypeError("agentLifecycle.status must be active|frozen|archived");
+    }
+    const at = agentLifecycle.updatedAt ?? agentLifecycle.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [
+        {
+          kind: "X402_AGENT_LIFECYCLE_UPSERT",
+          tenantId,
+          agentId,
+          agentLifecycle: { ...agentLifecycle, tenantId, agentId, status }
+        }
+      ],
+      audit
+    });
+    return store.x402AgentLifecycles.get(makeScopedKey({ tenantId, id: agentId })) ?? null;
+  };
+
+  store.getX402AgentLifecycle = async function getX402AgentLifecycle({ tenantId = DEFAULT_TENANT_ID, agentId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof agentId !== "string" || agentId.trim() === "") throw new TypeError("agentId is required");
+    return store.x402AgentLifecycles.get(makeScopedKey({ tenantId, id: String(agentId) })) ?? null;
+  };
+
+  function x402WalletPolicyStoreKey({ tenantId, sponsorWalletRef, policyRef, policyVersion }) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedSponsorWalletRef = typeof sponsorWalletRef === "string" ? sponsorWalletRef.trim() : "";
+    const normalizedPolicyRef = typeof policyRef === "string" ? policyRef.trim() : "";
+    const normalizedPolicyVersion = Number(policyVersion);
+    if (!normalizedSponsorWalletRef) throw new TypeError("sponsorWalletRef is required");
+    if (!normalizedPolicyRef) throw new TypeError("policyRef is required");
+    if (!Number.isSafeInteger(normalizedPolicyVersion) || normalizedPolicyVersion <= 0) {
+      throw new TypeError("policyVersion must be a positive safe integer");
+    }
+    return makeScopedKey({
+      tenantId: normalizedTenantId,
+      id: `${normalizedSponsorWalletRef}::${normalizedPolicyRef}::${normalizedPolicyVersion}`
+    });
+  }
+
+  function x402WebhookEndpointStoreKey({ tenantId, endpointId }) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedEndpointId = typeof endpointId === "string" ? endpointId.trim() : "";
+    if (!normalizedEndpointId) throw new TypeError("endpointId is required");
+    return makeScopedKey({ tenantId: normalizedTenantId, id: normalizedEndpointId });
+  }
+
+  function x402ZkVerificationKeyStoreKey({ tenantId, verificationKeyId }) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedVerificationKeyId = typeof verificationKeyId === "string" ? verificationKeyId.trim() : "";
+    if (!normalizedVerificationKeyId) throw new TypeError("verificationKeyId is required");
+    return makeScopedKey({ tenantId: normalizedTenantId, id: normalizedVerificationKeyId });
+  }
+
+  store.putX402WalletPolicy = async function putX402WalletPolicy({ tenantId = DEFAULT_TENANT_ID, policy, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) throw new TypeError("policy is required");
+    const sponsorWalletRef = typeof policy.sponsorWalletRef === "string" ? policy.sponsorWalletRef.trim() : "";
+    const policyRef = typeof policy.policyRef === "string" ? policy.policyRef.trim() : "";
+    const policyVersion = Number(policy.policyVersion);
+    if (!sponsorWalletRef) throw new TypeError("policy.sponsorWalletRef is required");
+    if (!policyRef) throw new TypeError("policy.policyRef is required");
+    if (!Number.isSafeInteger(policyVersion) || policyVersion <= 0) throw new TypeError("policy.policyVersion must be a positive safe integer");
+    const key = x402WalletPolicyStoreKey({ tenantId, sponsorWalletRef, policyRef, policyVersion });
+    const at = policy.updatedAt ?? policy.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [
+        {
+          kind: "X402_WALLET_POLICY_UPSERT",
+          tenantId,
+          policy: { ...policy, tenantId, sponsorWalletRef, policyRef, policyVersion }
+        }
+      ],
+      audit
+    });
+    return store.x402WalletPolicies.get(key) ?? null;
+  };
+
+  store.getX402WalletPolicy = async function getX402WalletPolicy({
+    tenantId = DEFAULT_TENANT_ID,
+    sponsorWalletRef,
+    policyRef,
+    policyVersion
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    const key = x402WalletPolicyStoreKey({ tenantId, sponsorWalletRef, policyRef, policyVersion });
+    return store.x402WalletPolicies.get(key) ?? null;
+  };
+
+  store.listX402WalletPolicies = async function listX402WalletPolicies({
+    tenantId = DEFAULT_TENANT_ID,
+    sponsorWalletRef = null,
+    sponsorRef = null,
+    policyRef = null,
+    status = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (sponsorWalletRef !== null && (typeof sponsorWalletRef !== "string" || sponsorWalletRef.trim() === "")) {
+      throw new TypeError("sponsorWalletRef must be null or a non-empty string");
+    }
+    if (sponsorRef !== null && (typeof sponsorRef !== "string" || sponsorRef.trim() === "")) {
+      throw new TypeError("sponsorRef must be null or a non-empty string");
+    }
+    if (policyRef !== null && (typeof policyRef !== "string" || policyRef.trim() === "")) {
+      throw new TypeError("policyRef must be null or a non-empty string");
+    }
+    if (status !== null && (typeof status !== "string" || status.trim() === "")) {
+      throw new TypeError("status must be null or a non-empty string");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const sponsorWalletFilter = sponsorWalletRef ? sponsorWalletRef.trim() : null;
+    const sponsorFilter = sponsorRef ? sponsorRef.trim() : null;
+    const policyFilter = policyRef ? policyRef.trim() : null;
+    const statusFilter = status ? status.trim().toLowerCase() : null;
+    const out = [];
+    for (const row of store.x402WalletPolicies.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (sponsorWalletFilter && String(row.sponsorWalletRef ?? "") !== sponsorWalletFilter) continue;
+      if (sponsorFilter && String(row.sponsorRef ?? "") !== sponsorFilter) continue;
+      if (policyFilter && String(row.policyRef ?? "") !== policyFilter) continue;
+      if (statusFilter && String(row.status ?? "").toLowerCase() !== statusFilter) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftAt = Number.isFinite(Date.parse(String(left?.updatedAt ?? ""))) ? Date.parse(String(left.updatedAt)) : Number.NaN;
+      const rightAt = Number.isFinite(Date.parse(String(right?.updatedAt ?? ""))) ? Date.parse(String(right.updatedAt)) : Number.NaN;
+      if (Number.isFinite(leftAt) && Number.isFinite(rightAt) && rightAt !== leftAt) return rightAt - leftAt;
+      const sponsorOrder = String(left?.sponsorWalletRef ?? "").localeCompare(String(right?.sponsorWalletRef ?? ""));
+      if (sponsorOrder !== 0) return sponsorOrder;
+      const policyOrder = String(left?.policyRef ?? "").localeCompare(String(right?.policyRef ?? ""));
+      if (policyOrder !== 0) return policyOrder;
+      return Number(right?.policyVersion ?? 0) - Number(left?.policyVersion ?? 0);
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.putX402ZkVerificationKey = async function putX402ZkVerificationKey({
+    tenantId = DEFAULT_TENANT_ID,
+    verificationKey,
+    audit = null
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!verificationKey || typeof verificationKey !== "object" || Array.isArray(verificationKey)) {
+      throw new TypeError("verificationKey is required");
+    }
+    const verificationKeyId = typeof verificationKey.verificationKeyId === "string" ? verificationKey.verificationKeyId.trim() : "";
+    if (!verificationKeyId) throw new TypeError("verificationKey.verificationKeyId is required");
+    const key = x402ZkVerificationKeyStoreKey({ tenantId, verificationKeyId });
+    const at = verificationKey.updatedAt ?? verificationKey.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [
+        {
+          kind: "X402_ZK_VERIFICATION_KEY_PUT",
+          tenantId,
+          verificationKeyId,
+          verificationKey: { ...verificationKey, tenantId, verificationKeyId }
+        }
+      ],
+      audit
+    });
+    return store.x402ZkVerificationKeys.get(key) ?? null;
+  };
+
+  store.getX402ZkVerificationKey = async function getX402ZkVerificationKey({
+    tenantId = DEFAULT_TENANT_ID,
+    verificationKeyId
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    return store.x402ZkVerificationKeys.get(x402ZkVerificationKeyStoreKey({ tenantId, verificationKeyId })) ?? null;
+  };
+
+  store.listX402ZkVerificationKeys = async function listX402ZkVerificationKeys({
+    tenantId = DEFAULT_TENANT_ID,
+    protocol = null,
+    providerRef = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (protocol !== null && (typeof protocol !== "string" || protocol.trim() === "")) {
+      throw new TypeError("protocol must be null or a non-empty string");
+    }
+    if (providerRef !== null && (typeof providerRef !== "string" || providerRef.trim() === "")) {
+      throw new TypeError("providerRef must be null or a non-empty string");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+    const protocolFilter = protocol ? protocol.trim().toLowerCase() : null;
+    const providerRefFilter = providerRef ? providerRef.trim() : null;
+    const out = [];
+    for (const row of store.x402ZkVerificationKeys.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (protocolFilter && String(row.protocol ?? "").trim().toLowerCase() !== protocolFilter) continue;
+      if (providerRefFilter && String(row.providerRef ?? "") !== providerRefFilter) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftAt = Number.isFinite(Date.parse(String(left?.createdAt ?? ""))) ? Date.parse(String(left.createdAt)) : Number.NaN;
+      const rightAt = Number.isFinite(Date.parse(String(right?.createdAt ?? ""))) ? Date.parse(String(right.createdAt)) : Number.NaN;
+      if (Number.isFinite(leftAt) && Number.isFinite(rightAt) && rightAt !== leftAt) return rightAt - leftAt;
+      return String(left?.verificationKeyId ?? "").localeCompare(String(right?.verificationKeyId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.putX402WebhookEndpoint = async function putX402WebhookEndpoint({ tenantId = DEFAULT_TENANT_ID, endpoint, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!endpoint || typeof endpoint !== "object" || Array.isArray(endpoint)) throw new TypeError("endpoint is required");
+    const endpointId = typeof endpoint.endpointId === "string" ? endpoint.endpointId.trim() : "";
+    if (!endpointId) throw new TypeError("endpoint.endpointId is required");
+    const at = endpoint.updatedAt ?? endpoint.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_WEBHOOK_ENDPOINT_UPSERT", tenantId, endpointId, endpoint: { ...endpoint, tenantId, endpointId } }],
+      audit
+    });
+    return store.x402WebhookEndpoints.get(x402WebhookEndpointStoreKey({ tenantId, endpointId })) ?? null;
+  };
+
+  store.getX402WebhookEndpoint = async function getX402WebhookEndpoint({ tenantId = DEFAULT_TENANT_ID, endpointId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    return store.x402WebhookEndpoints.get(x402WebhookEndpointStoreKey({ tenantId, endpointId })) ?? null;
+  };
+
+  store.listX402WebhookEndpoints = async function listX402WebhookEndpoints({
+    tenantId = DEFAULT_TENANT_ID,
+    endpointId = null,
+    destinationId = null,
+    status = null,
+    event = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (endpointId !== null && (typeof endpointId !== "string" || endpointId.trim() === "")) {
+      throw new TypeError("endpointId must be null or a non-empty string");
+    }
+    if (destinationId !== null && (typeof destinationId !== "string" || destinationId.trim() === "")) {
+      throw new TypeError("destinationId must be null or a non-empty string");
+    }
+    if (status !== null && (typeof status !== "string" || status.trim() === "")) {
+      throw new TypeError("status must be null or a non-empty string");
+    }
+    if (event !== null && (typeof event !== "string" || event.trim() === "")) {
+      throw new TypeError("event must be null or a non-empty string");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const endpointFilter = endpointId ? endpointId.trim() : null;
+    const destinationFilter = destinationId ? destinationId.trim() : null;
+    const statusFilter = status ? status.trim().toLowerCase() : null;
+    const eventFilter = event ? event.trim().toLowerCase() : null;
+    const out = [];
+    for (const row of store.x402WebhookEndpoints.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (endpointFilter && String(row.endpointId ?? "") !== endpointFilter) continue;
+      if (destinationFilter && String(row.destinationId ?? "") !== destinationFilter) continue;
+      if (statusFilter && String(row.status ?? "").toLowerCase() !== statusFilter) continue;
+      if (eventFilter) {
+        const events = Array.isArray(row.events) ? row.events.map((value) => String(value).trim().toLowerCase()) : [];
+        if (!events.includes(eventFilter)) continue;
+      }
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftAt = Number.isFinite(Date.parse(String(left?.updatedAt ?? ""))) ? Date.parse(String(left.updatedAt)) : Number.NaN;
+      const rightAt = Number.isFinite(Date.parse(String(right?.updatedAt ?? ""))) ? Date.parse(String(right.updatedAt)) : Number.NaN;
+      if (Number.isFinite(leftAt) && Number.isFinite(rightAt) && rightAt !== leftAt) return rightAt - leftAt;
+      return String(left?.endpointId ?? "").localeCompare(String(right?.endpointId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.recordX402WebhookEndpointDeliveryResult = async function recordX402WebhookEndpointDeliveryResult({
+    tenantId = DEFAULT_TENANT_ID,
+    destinationId,
+    deliveredAt = new Date().toISOString(),
+    success,
+    failureReason = null,
+    statusCode = null,
+    autoDisableThreshold = null,
+    audit = null
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof destinationId !== "string" || destinationId.trim() === "") throw new TypeError("destinationId is required");
+    const matched = await store.listX402WebhookEndpoints({ tenantId, destinationId: destinationId.trim(), limit: 1, offset: 0 });
+    const endpoint = Array.isArray(matched) && matched.length > 0 ? matched[0] : null;
+    if (!endpoint) return null;
+    if (String(endpoint.status ?? "").toLowerCase() === "revoked") return endpoint;
+    const thresholdRaw = autoDisableThreshold ?? store.x402WebhookAutoDisableFailures ?? 10;
+    const threshold = Number.isSafeInteger(Number(thresholdRaw)) && Number(thresholdRaw) > 0 ? Number(thresholdRaw) : 10;
+    const next = {
+      ...endpoint,
+      updatedAt: deliveredAt,
+      lastDeliveryAt: deliveredAt
+    };
+    if (success) {
+      next.consecutiveFailures = 0;
+      next.lastFailureReason = null;
+      next.lastFailureAt = null;
+      next.lastFailureStatusCode = null;
+    } else {
+      const prevFailures = Number.isSafeInteger(Number(endpoint.consecutiveFailures)) ? Number(endpoint.consecutiveFailures) : 0;
+      next.consecutiveFailures = prevFailures + 1;
+      next.lastFailureReason = failureReason ? String(failureReason) : "delivery_failed";
+      next.lastFailureAt = deliveredAt;
+      next.lastFailureStatusCode = Number.isSafeInteger(Number(statusCode)) ? Number(statusCode) : null;
+      if (String(endpoint.status ?? "").toLowerCase() === "active" && next.consecutiveFailures >= threshold) {
+        next.status = "disabled";
+        next.disabledAt = deliveredAt;
+      }
+    }
+    return store.putX402WebhookEndpoint({ tenantId, endpoint: next, audit });
+  };
+
+  function x402ReversalNonceStoreKey({ tenantId, sponsorRef, nonce }) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedSponsorRef = typeof sponsorRef === "string" ? sponsorRef.trim() : "";
+    const normalizedNonce = typeof nonce === "string" ? nonce.trim() : "";
+    if (!normalizedSponsorRef) throw new TypeError("sponsorRef is required");
+    if (!normalizedNonce) throw new TypeError("nonce is required");
+    return `${normalizedTenantId}\n${normalizedSponsorRef}\n${normalizedNonce}`;
+  }
+
+  store.putX402ReversalEvent = async function putX402ReversalEvent({ tenantId = DEFAULT_TENANT_ID, gateId, event, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof gateId !== "string" || gateId.trim() === "") throw new TypeError("gateId is required");
+    if (!event || typeof event !== "object" || Array.isArray(event)) throw new TypeError("event is required");
+    const eventId = event.eventId ?? event.id ?? null;
+    if (typeof eventId !== "string" || eventId.trim() === "") throw new TypeError("event.eventId is required");
+    const at = event.occurredAt ?? event.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_REVERSAL_EVENT_APPEND", tenantId, gateId: String(gateId), eventId: String(eventId), event: { ...event, tenantId, gateId: String(gateId), eventId: String(eventId) } }],
+      audit
+    });
+    return store.x402ReversalEvents.get(makeScopedKey({ tenantId, id: String(eventId) })) ?? null;
+  };
+
+  store.getX402ReversalEvent = async function getX402ReversalEvent({ tenantId = DEFAULT_TENANT_ID, eventId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof eventId !== "string" || eventId.trim() === "") throw new TypeError("eventId is required");
+    return store.x402ReversalEvents.get(makeScopedKey({ tenantId, id: String(eventId) })) ?? null;
+  };
+
+  store.listX402ReversalEvents = async function listX402ReversalEvents({
+    tenantId = DEFAULT_TENANT_ID,
+    gateId = null,
+    receiptId = null,
+    action = null,
+    from = null,
+    to = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (gateId !== null && (typeof gateId !== "string" || gateId.trim() === "")) throw new TypeError("gateId must be null or a non-empty string");
+    if (receiptId !== null && (typeof receiptId !== "string" || receiptId.trim() === "")) throw new TypeError("receiptId must be null or a non-empty string");
+    if (action !== null && (typeof action !== "string" || action.trim() === "")) throw new TypeError("action must be null or a non-empty string");
+    if (from !== null && !Number.isFinite(Date.parse(String(from)))) throw new TypeError("from must be null or an ISO date-time");
+    if (to !== null && !Number.isFinite(Date.parse(String(to)))) throw new TypeError("to must be null or an ISO date-time");
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const normalizedGateId = gateId ? gateId.trim() : null;
+    const normalizedReceiptId = receiptId ? receiptId.trim() : null;
+    const normalizedAction = action ? action.trim().toLowerCase() : null;
+    const fromMs = from ? Date.parse(String(from)) : null;
+    const toMs = to ? Date.parse(String(to)) : null;
+
+    const out = [];
+    for (const row of store.x402ReversalEvents.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (normalizedGateId && String(row.gateId ?? "") !== normalizedGateId) continue;
+      if (normalizedReceiptId && String(row.receiptId ?? "") !== normalizedReceiptId) continue;
+      if (normalizedAction && String(row.action ?? "").toLowerCase() !== normalizedAction) continue;
+      const occurredAtMs = Number.isFinite(Date.parse(String(row.occurredAt ?? ""))) ? Date.parse(String(row.occurredAt)) : Number.NaN;
+      if (fromMs !== null && (!Number.isFinite(occurredAtMs) || occurredAtMs < fromMs)) continue;
+      if (toMs !== null && (!Number.isFinite(occurredAtMs) || occurredAtMs > toMs)) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftMs = Number.isFinite(Date.parse(String(left?.occurredAt ?? ""))) ? Date.parse(String(left.occurredAt)) : Number.NaN;
+      const rightMs = Number.isFinite(Date.parse(String(right?.occurredAt ?? ""))) ? Date.parse(String(right.occurredAt)) : Number.NaN;
+      if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return rightMs - leftMs;
+      return String(left?.eventId ?? "").localeCompare(String(right?.eventId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.putX402ReversalNonceUsage = async function putX402ReversalNonceUsage({ tenantId = DEFAULT_TENANT_ID, usage, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!usage || typeof usage !== "object" || Array.isArray(usage)) throw new TypeError("usage is required");
+    const sponsorRef = typeof usage.sponsorRef === "string" ? usage.sponsorRef.trim() : "";
+    const nonce = typeof usage.nonce === "string" ? usage.nonce.trim() : "";
+    if (!sponsorRef) throw new TypeError("usage.sponsorRef is required");
+    if (!nonce) throw new TypeError("usage.nonce is required");
+    const at = usage.usedAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_REVERSAL_NONCE_PUT", tenantId, sponsorRef, nonce, usage: { ...usage, tenantId, sponsorRef, nonce } }],
+      audit
+    });
+    return store.x402ReversalNonceUsage.get(x402ReversalNonceStoreKey({ tenantId, sponsorRef, nonce })) ?? null;
+  };
+
+  store.getX402ReversalNonceUsage = async function getX402ReversalNonceUsage({ tenantId = DEFAULT_TENANT_ID, sponsorRef, nonce } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    return store.x402ReversalNonceUsage.get(x402ReversalNonceStoreKey({ tenantId, sponsorRef, nonce })) ?? null;
+  };
+
+  store.putX402ReversalCommandUsage = async function putX402ReversalCommandUsage({ tenantId = DEFAULT_TENANT_ID, usage, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!usage || typeof usage !== "object" || Array.isArray(usage)) throw new TypeError("usage is required");
+    const commandId = typeof usage.commandId === "string" ? usage.commandId.trim() : "";
+    if (!commandId) throw new TypeError("usage.commandId is required");
+    const at = usage.usedAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_REVERSAL_COMMAND_PUT", tenantId, commandId, usage: { ...usage, tenantId, commandId } }],
+      audit
+    });
+    return store.x402ReversalCommandUsage.get(makeScopedKey({ tenantId, id: commandId })) ?? null;
+  };
+
+  store.getX402ReversalCommandUsage = async function getX402ReversalCommandUsage({ tenantId = DEFAULT_TENANT_ID, commandId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof commandId !== "string" || commandId.trim() === "") throw new TypeError("commandId is required");
+    return store.x402ReversalCommandUsage.get(makeScopedKey({ tenantId, id: commandId.trim() })) ?? null;
+  };
+
+  store.putX402Escalation = async function putX402Escalation({ tenantId = DEFAULT_TENANT_ID, escalation, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!escalation || typeof escalation !== "object" || Array.isArray(escalation)) throw new TypeError("escalation is required");
+    const escalationId = typeof escalation.escalationId === "string" ? escalation.escalationId.trim() : "";
+    if (!escalationId) throw new TypeError("escalation.escalationId is required");
+    const at = escalation.updatedAt ?? escalation.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_ESCALATION_UPSERT", tenantId, escalationId, escalation: { ...escalation, tenantId, escalationId } }],
+      audit
+    });
+    return store.x402Escalations.get(makeScopedKey({ tenantId, id: escalationId })) ?? null;
+  };
+
+  store.getX402Escalation = async function getX402Escalation({ tenantId = DEFAULT_TENANT_ID, escalationId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof escalationId !== "string" || escalationId.trim() === "") throw new TypeError("escalationId is required");
+    return store.x402Escalations.get(makeScopedKey({ tenantId, id: escalationId.trim() })) ?? null;
+  };
+
+  store.listX402Escalations = async function listX402Escalations({
+    tenantId = DEFAULT_TENANT_ID,
+    gateId = null,
+    agentId = null,
+    status = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (gateId !== null && (typeof gateId !== "string" || gateId.trim() === "")) throw new TypeError("gateId must be null or a non-empty string");
+    if (agentId !== null && (typeof agentId !== "string" || agentId.trim() === "")) throw new TypeError("agentId must be null or a non-empty string");
+    if (status !== null && (typeof status !== "string" || status.trim() === "")) throw new TypeError("status must be null or a non-empty string");
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const normalizedGateId = gateId ? gateId.trim() : null;
+    const normalizedAgentId = agentId ? agentId.trim() : null;
+    const normalizedStatus = status ? status.trim().toLowerCase() : null;
+    const out = [];
+    for (const row of store.x402Escalations.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (normalizedGateId && String(row.gateId ?? "") !== normalizedGateId) continue;
+      if (
+        normalizedAgentId &&
+        String(
+          row.requesterAgentId ??
+            row.payerAgentId ??
+            null
+        ).trim() !== normalizedAgentId
+      ) {
+        continue;
+      }
+      if (normalizedStatus && String(row.status ?? "").toLowerCase() !== normalizedStatus) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftMs = Number.isFinite(Date.parse(String(left?.updatedAt ?? ""))) ? Date.parse(String(left.updatedAt)) : Number.NaN;
+      const rightMs = Number.isFinite(Date.parse(String(right?.updatedAt ?? ""))) ? Date.parse(String(right.updatedAt)) : Number.NaN;
+      if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return rightMs - leftMs;
+      return String(left?.escalationId ?? "").localeCompare(String(right?.escalationId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.appendX402EscalationEvent = async function appendX402EscalationEvent({ tenantId = DEFAULT_TENANT_ID, event, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!event || typeof event !== "object" || Array.isArray(event)) throw new TypeError("event is required");
+    const eventId = typeof event.eventId === "string" ? event.eventId.trim() : "";
+    const escalationId = typeof event.escalationId === "string" ? event.escalationId.trim() : "";
+    if (!eventId) throw new TypeError("event.eventId is required");
+    if (!escalationId) throw new TypeError("event.escalationId is required");
+    const at = event.occurredAt ?? event.createdAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_ESCALATION_EVENT_APPEND", tenantId, eventId, escalationId, event: { ...event, tenantId, eventId, escalationId } }],
+      audit
+    });
+    return store.x402EscalationEvents.get(makeScopedKey({ tenantId, id: eventId })) ?? null;
+  };
+
+  store.listX402EscalationEvents = async function listX402EscalationEvents({
+    tenantId = DEFAULT_TENANT_ID,
+    escalationId = null,
+    limit = 200,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (escalationId !== null && (typeof escalationId !== "string" || escalationId.trim() === "")) {
+      throw new TypeError("escalationId must be null or a non-empty string");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+    const normalizedEscalationId = escalationId ? escalationId.trim() : null;
+    const out = [];
+    for (const row of store.x402EscalationEvents.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (normalizedEscalationId && String(row.escalationId ?? "") !== normalizedEscalationId) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftMs = Number.isFinite(Date.parse(String(left?.occurredAt ?? ""))) ? Date.parse(String(left.occurredAt)) : Number.NaN;
+      const rightMs = Number.isFinite(Date.parse(String(right?.occurredAt ?? ""))) ? Date.parse(String(right.occurredAt)) : Number.NaN;
+      if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return leftMs - rightMs;
+      return String(left?.eventId ?? "").localeCompare(String(right?.eventId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(1000, limit));
+  };
+
+  store.putX402EscalationOverrideUsage = async function putX402EscalationOverrideUsage({ tenantId = DEFAULT_TENANT_ID, usage, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (!usage || typeof usage !== "object" || Array.isArray(usage)) throw new TypeError("usage is required");
+    const overrideId = typeof usage.overrideId === "string" ? usage.overrideId.trim() : "";
+    if (!overrideId) throw new TypeError("usage.overrideId is required");
+    const at = usage.usedAt ?? new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_ESCALATION_OVERRIDE_USAGE_PUT", tenantId, overrideId, usage: { ...usage, tenantId, overrideId } }],
+      audit
+    });
+    return store.x402EscalationOverrideUsage.get(makeScopedKey({ tenantId, id: overrideId })) ?? null;
+  };
+
+  store.getX402EscalationOverrideUsage = async function getX402EscalationOverrideUsage({
+    tenantId = DEFAULT_TENANT_ID,
+    overrideId
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof overrideId !== "string" || overrideId.trim() === "") throw new TypeError("overrideId is required");
+    return store.x402EscalationOverrideUsage.get(makeScopedKey({ tenantId, id: overrideId.trim() })) ?? null;
+  };
+
+  function x402ReceiptStoreKey({ tenantId, receiptId }) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedReceiptId = typeof receiptId === "string" ? receiptId.trim() : "";
+    if (!normalizedReceiptId) throw new TypeError("receiptId is required");
+    return makeScopedKey({ tenantId: normalizedTenantId, id: normalizedReceiptId });
+  }
+
+  function listX402ReversalEventsForReceiptSync({ tenantId = DEFAULT_TENANT_ID, receiptId } = {}) {
+    const normalizedTenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    const normalizedReceiptId = typeof receiptId === "string" ? receiptId.trim() : "";
+    if (!normalizedReceiptId) return [];
+    const out = [];
+    for (const row of store.x402ReversalEvents.values()) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== normalizedTenantId) continue;
+      if (String(row.receiptId ?? "") !== normalizedReceiptId) continue;
+      out.push(row);
+    }
+    out.sort((left, right) => {
+      const leftMs = Number.isFinite(Date.parse(String(left?.occurredAt ?? ""))) ? Date.parse(String(left.occurredAt)) : Number.NaN;
+      const rightMs = Number.isFinite(Date.parse(String(right?.occurredAt ?? ""))) ? Date.parse(String(right.occurredAt)) : Number.NaN;
+      if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return leftMs - rightMs;
+      return String(left?.eventId ?? "").localeCompare(String(right?.eventId ?? ""));
+    });
+    return out;
+  }
+
+  function toX402ReceiptRecord({ tenantId, gate, settlement: settlementInput = null, includeReversalContext = true } = {}) {
+    if (!gate || typeof gate !== "object" || Array.isArray(gate)) return null;
+    const runId = typeof gate.runId === "string" && gate.runId.trim() !== "" ? gate.runId.trim() : null;
+    const settlement =
+      settlementInput && typeof settlementInput === "object" && !Array.isArray(settlementInput)
+        ? settlementInput
+        : runId && store.agentRunSettlements instanceof Map
+          ? store.agentRunSettlements.get(makeScopedKey({ tenantId, id: runId })) ?? null
+          : null;
+    const decisionTrace =
+      settlement?.decisionTrace && typeof settlement.decisionTrace === "object" && !Array.isArray(settlement.decisionTrace)
+        ? settlement.decisionTrace
+        : gate.decisionTrace && typeof gate.decisionTrace === "object" && !Array.isArray(gate.decisionTrace)
+          ? gate.decisionTrace
+          : null;
+    const settlementReceipt =
+      decisionTrace?.settlementReceipt && typeof decisionTrace.settlementReceipt === "object" && !Array.isArray(decisionTrace.settlementReceipt)
+        ? decisionTrace.settlementReceipt
+        : null;
+    if (!settlementReceipt) return null;
+    const receiptId = typeof settlementReceipt.receiptId === "string" ? settlementReceipt.receiptId.trim() : "";
+    if (!receiptId) return null;
+    const bindings =
+      decisionTrace?.bindings && typeof decisionTrace.bindings === "object" && !Array.isArray(decisionTrace.bindings)
+        ? decisionTrace.bindings
+        : null;
+    const verificationContext =
+      gate?.verificationContext && typeof gate.verificationContext === "object" && !Array.isArray(gate.verificationContext)
+        ? gate.verificationContext
+        : gate?.decision?.verificationContext &&
+            typeof gate.decision.verificationContext === "object" &&
+            !Array.isArray(gate.decision.verificationContext)
+          ? gate.decision.verificationContext
+          : null;
+    const sponsorRef =
+      typeof bindings?.spendAuthorization?.sponsorRef === "string" && bindings.spendAuthorization.sponsorRef.trim() !== ""
+        ? bindings.spendAuthorization.sponsorRef.trim()
+        : null;
+    const sponsorWalletRef =
+      typeof bindings?.spendAuthorization?.sponsorWalletRef === "string" && bindings.spendAuthorization.sponsorWalletRef.trim() !== ""
+        ? bindings.spendAuthorization.sponsorWalletRef.trim()
+        : null;
+    const agentKeyId =
+      typeof bindings?.spendAuthorization?.agentKeyId === "string" && bindings.spendAuthorization.agentKeyId.trim() !== ""
+        ? bindings.spendAuthorization.agentKeyId.trim()
+        : null;
+    const settledAt =
+      typeof settlementReceipt.settledAt === "string" && settlementReceipt.settledAt.trim() !== ""
+        ? settlementReceipt.settledAt.trim()
+        : typeof gate.resolvedAt === "string" && gate.resolvedAt.trim() !== ""
+          ? gate.resolvedAt.trim()
+          : null;
+    const base = {
+      schemaVersion: "X402ReceiptRecord.v1",
+      tenantId,
+      receiptId,
+      gateId: typeof gate.gateId === "string" ? gate.gateId : null,
+      runId,
+      payerAgentId: typeof gate.payerAgentId === "string" ? gate.payerAgentId : null,
+      providerId: typeof gate.payeeAgentId === "string" ? gate.payeeAgentId : null,
+      toolId:
+        typeof gate.toolId === "string" && gate.toolId.trim() !== ""
+          ? gate.toolId.trim()
+          : typeof gate?.quote?.toolId === "string" && gate.quote.toolId.trim() !== ""
+            ? gate.quote.toolId.trim()
+            : null,
+      sponsorRef,
+      sponsorWalletRef,
+      agentKeyId,
+      settlementState:
+        typeof settlementReceipt.status === "string" && settlementReceipt.status.trim() !== ""
+          ? settlementReceipt.status.trim().toLowerCase()
+          : typeof settlement?.status === "string" && settlement.status.trim() !== ""
+            ? settlement.status.trim().toLowerCase()
+            : null,
+      verificationStatus:
+        typeof decisionTrace?.verificationStatus === "string" && decisionTrace.verificationStatus.trim() !== ""
+          ? decisionTrace.verificationStatus.trim().toLowerCase()
+          : null,
+      settledAt,
+      createdAt:
+        typeof settlementReceipt.createdAt === "string" && settlementReceipt.createdAt.trim() !== ""
+          ? settlementReceipt.createdAt.trim()
+          : null,
+      updatedAt:
+        typeof gate.updatedAt === "string" && gate.updatedAt.trim() !== ""
+          ? gate.updatedAt.trim()
+          : typeof settledAt === "string"
+            ? settledAt
+            : null,
+      evidenceRefs: Array.isArray(gate.evidenceRefs) ? gate.evidenceRefs.slice() : [],
+      verificationContext,
+      bindings,
+      providerSignature:
+        gate?.providerSignature && typeof gate.providerSignature === "object" && !Array.isArray(gate.providerSignature)
+          ? gate.providerSignature
+          : null,
+      providerQuoteSignature:
+        gate?.providerQuoteSignature && typeof gate.providerQuoteSignature === "object" && !Array.isArray(gate.providerQuoteSignature)
+          ? gate.providerQuoteSignature
+          : null,
+      providerQuotePayload:
+        gate?.providerQuotePayload && typeof gate.providerQuotePayload === "object" && !Array.isArray(gate.providerQuotePayload)
+          ? gate.providerQuotePayload
+          : null,
+      zkProof:
+        gate?.zkProof && typeof gate.zkProof === "object" && !Array.isArray(gate.zkProof)
+          ? gate.zkProof
+          : null,
+      decisionRecord:
+        decisionTrace?.decisionRecord && typeof decisionTrace.decisionRecord === "object" && !Array.isArray(decisionTrace.decisionRecord)
+          ? decisionTrace.decisionRecord
+          : null,
+      settlementReceipt
+    };
+    if (!includeReversalContext) return base;
+    return {
+      ...base,
+      reversal:
+        gate?.reversal && typeof gate.reversal === "object" && !Array.isArray(gate.reversal)
+          ? gate.reversal
+          : null,
+      reversalEvents: listX402ReversalEventsForReceiptSync({ tenantId, receiptId })
+    };
+  }
+
+  function normalizeX402ReceiptRecordForStorage({ receipt } = {}) {
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return null;
+    const stableUpdatedAt =
+      typeof receipt.createdAt === "string" && receipt.createdAt.trim() !== ""
+        ? receipt.createdAt
+        : typeof receipt.settledAt === "string" && receipt.settledAt.trim() !== ""
+          ? receipt.settledAt
+          : typeof receipt.updatedAt === "string" && receipt.updatedAt.trim() !== ""
+            ? receipt.updatedAt
+            : new Date().toISOString();
+    const normalized = {
+      ...receipt,
+      reversal: null,
+      reversalEvents: [],
+      updatedAt: stableUpdatedAt
+    };
+    return normalized;
+  }
+
+  function projectX402ReceiptRecord({ tenantId, receipt } = {}) {
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) return null;
+    const receiptId = typeof receipt.receiptId === "string" ? receipt.receiptId.trim() : "";
+    if (!receiptId) return null;
+    const gateId = typeof receipt.gateId === "string" ? receipt.gateId.trim() : "";
+    const gate =
+      gateId && store.x402Gates instanceof Map
+        ? store.x402Gates.get(makeScopedKey({ tenantId, id: gateId })) ?? null
+        : null;
+    const reversalEvents = listX402ReversalEventsForReceiptSync({ tenantId, receiptId });
+    const latestEvent = reversalEvents.length > 0 ? reversalEvents[reversalEvents.length - 1] : null;
+    const derivedState =
+      typeof latestEvent?.settlementStatusAfter === "string" && latestEvent.settlementStatusAfter.trim() !== ""
+        ? latestEvent.settlementStatusAfter.trim().toLowerCase()
+        : null;
+    const updatedAtCandidates = [receipt.updatedAt, latestEvent?.occurredAt]
+      .map((value) => (typeof value === "string" && value.trim() !== "" && Number.isFinite(Date.parse(value)) ? new Date(Date.parse(value)).toISOString() : null))
+      .filter(Boolean);
+    const updatedAt = updatedAtCandidates.length > 0 ? updatedAtCandidates.sort((a, b) => Date.parse(a) - Date.parse(b))[updatedAtCandidates.length - 1] : null;
+    return {
+      ...receipt,
+      settlementState: derivedState ?? receipt.settlementState ?? null,
+      updatedAt: updatedAt ?? receipt.updatedAt ?? null,
+      reversal:
+        gate?.reversal && typeof gate.reversal === "object" && !Array.isArray(gate.reversal)
+          ? gate.reversal
+          : receipt?.reversal && typeof receipt.reversal === "object" && !Array.isArray(receipt.reversal)
+            ? receipt.reversal
+            : null,
+      reversalEvents
+    };
+  }
+
+  function compareX402ReceiptRecords(left, right) {
+    const leftMs = Number.isFinite(Date.parse(String(left?.settledAt ?? ""))) ? Date.parse(String(left.settledAt)) : Number.NaN;
+    const rightMs = Number.isFinite(Date.parse(String(right?.settledAt ?? ""))) ? Date.parse(String(right.settledAt)) : Number.NaN;
+    if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return rightMs - leftMs;
+    return String(left?.receiptId ?? "").localeCompare(String(right?.receiptId ?? ""));
+  }
+
+  function encodeX402ReceiptCursor(record) {
+    const settledAt = typeof record?.settledAt === "string" && record.settledAt.trim() !== "" ? new Date(Date.parse(record.settledAt)).toISOString() : null;
+    const receiptId = typeof record?.receiptId === "string" && record.receiptId.trim() !== "" ? record.receiptId.trim() : null;
+    if (!settledAt || !receiptId) return null;
+    return Buffer.from(JSON.stringify({ settledAt, receiptId }), "utf8").toString("base64url");
+  }
+
+  function decodeX402ReceiptCursor(raw) {
+    if (raw === null || raw === undefined || String(raw).trim() === "") return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(Buffer.from(String(raw).trim(), "base64url").toString("utf8"));
+    } catch {
+      throw new TypeError("cursor must be base64url-encoded JSON");
+    }
+    const settledAt = typeof parsed?.settledAt === "string" && Number.isFinite(Date.parse(parsed.settledAt)) ? new Date(Date.parse(parsed.settledAt)).toISOString() : null;
+    const receiptId = typeof parsed?.receiptId === "string" && parsed.receiptId.trim() !== "" ? parsed.receiptId.trim() : null;
+    if (!settledAt || !receiptId) throw new TypeError("cursor is invalid");
+    return { settledAt, receiptId };
+  }
+
+  function isReceiptAfterCursor(record, cursor) {
+    if (!cursor) return true;
+    const recordMs = Number.isFinite(Date.parse(String(record?.settledAt ?? ""))) ? Date.parse(String(record.settledAt)) : Number.NaN;
+    const cursorMs = Date.parse(cursor.settledAt);
+    if (!Number.isFinite(recordMs)) return false;
+    if (recordMs < cursorMs) return true;
+    if (recordMs > cursorMs) return false;
+    return String(record?.receiptId ?? "") > String(cursor.receiptId ?? "");
+  }
+
+  function listX402ReceiptCandidates({ tenantId }) {
+    const byReceiptId = new Map();
+    if (store.x402Receipts instanceof Map) {
+      for (const row of store.x402Receipts.values()) {
+        if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+        if (normalizeTenantId(row.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+        const receiptId = typeof row.receiptId === "string" ? row.receiptId.trim() : "";
+        if (!receiptId) continue;
+        byReceiptId.set(receiptId, projectX402ReceiptRecord({ tenantId, receipt: row }));
+      }
+    }
+    if (byReceiptId.size === 0 && store.x402Gates instanceof Map) {
+      for (const gate of store.x402Gates.values()) {
+        if (!gate || typeof gate !== "object" || Array.isArray(gate)) continue;
+        if (normalizeTenantId(gate.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+        const derived = toX402ReceiptRecord({ tenantId, gate, includeReversalContext: true });
+        if (!derived) continue;
+        const receiptId = typeof derived.receiptId === "string" ? derived.receiptId.trim() : "";
+        if (!receiptId) continue;
+        byReceiptId.set(receiptId, derived);
+      }
+    }
+    return Array.from(byReceiptId.values()).filter(Boolean);
+  }
+
+  store.deriveX402ReceiptRecord = function deriveX402ReceiptRecord({
+    tenantId = DEFAULT_TENANT_ID,
+    gate,
+    settlement = null,
+    includeReversalContext = false
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    const derived = toX402ReceiptRecord({ tenantId, gate, settlement, includeReversalContext });
+    return normalizeX402ReceiptRecordForStorage({ receipt: derived });
+  };
+
+  store.putX402Receipt = async function putX402Receipt({ tenantId = DEFAULT_TENANT_ID, receipt, audit = null } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    const normalized = normalizeX402ReceiptRecordForStorage({ receipt });
+    if (!normalized) throw new TypeError("receipt is required");
+    const receiptId = typeof normalized.receiptId === "string" ? normalized.receiptId.trim() : "";
+    if (!receiptId) throw new TypeError("receipt.receiptId is required");
+    const key = x402ReceiptStoreKey({ tenantId, receiptId });
+    const at =
+      typeof normalized.updatedAt === "string" && normalized.updatedAt.trim() !== ""
+        ? normalized.updatedAt
+        : typeof normalized.createdAt === "string" && normalized.createdAt.trim() !== ""
+          ? normalized.createdAt
+          : new Date().toISOString();
+    await store.commitTx({
+      at,
+      ops: [{ kind: "X402_RECEIPT_PUT", tenantId, receiptId, receipt: { ...normalized, tenantId, receiptId } }],
+      audit
+    });
+    return store.x402Receipts.get(key) ?? null;
+  };
+
+  store.getX402Receipt = async function getX402Receipt({ tenantId = DEFAULT_TENANT_ID, receiptId } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof receiptId !== "string" || receiptId.trim() === "") throw new TypeError("receiptId is required");
+    const wanted = receiptId.trim();
+    const key = x402ReceiptStoreKey({ tenantId, receiptId: wanted });
+    const stored = store.x402Receipts instanceof Map ? store.x402Receipts.get(key) ?? null : null;
+    if (stored) return projectX402ReceiptRecord({ tenantId, receipt: stored });
+    for (const gate of store.x402Gates.values()) {
+      if (!gate || typeof gate !== "object" || Array.isArray(gate)) continue;
+      if (normalizeTenantId(gate.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      const receipt = toX402ReceiptRecord({ tenantId, gate, includeReversalContext: true });
+      if (!receipt) continue;
+      if (String(receipt.receiptId ?? "") === wanted) return receipt;
+    }
+    return null;
+  };
+
+  store.listX402ReceiptsPage = async function listX402ReceiptsPage({
+    tenantId = DEFAULT_TENANT_ID,
+    agentId = null,
+    sponsorId = null,
+    sponsorWalletRef = null,
+    toolId = null,
+    state = null,
+    from = null,
+    to = null,
+    limit = 200,
+    offset = 0,
+    cursor = null
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (agentId !== null && (typeof agentId !== "string" || agentId.trim() === "")) throw new TypeError("agentId must be null or a non-empty string");
+    if (sponsorId !== null && (typeof sponsorId !== "string" || sponsorId.trim() === "")) throw new TypeError("sponsorId must be null or a non-empty string");
+    if (sponsorWalletRef !== null && (typeof sponsorWalletRef !== "string" || sponsorWalletRef.trim() === "")) {
+      throw new TypeError("sponsorWalletRef must be null or a non-empty string");
+    }
+    if (toolId !== null && (typeof toolId !== "string" || toolId.trim() === "")) throw new TypeError("toolId must be null or a non-empty string");
+    if (state !== null && (typeof state !== "string" || state.trim() === "")) throw new TypeError("state must be null or a non-empty string");
+    if (from !== null && !Number.isFinite(Date.parse(String(from)))) throw new TypeError("from must be null or an ISO date-time");
+    if (to !== null && !Number.isFinite(Date.parse(String(to)))) throw new TypeError("to must be null or an ISO date-time");
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const normalizedAgentId = agentId ? agentId.trim() : null;
+    const normalizedSponsorId = sponsorId ? sponsorId.trim() : null;
+    const normalizedSponsorWalletRef = sponsorWalletRef ? sponsorWalletRef.trim() : null;
+    const normalizedToolId = toolId ? toolId.trim() : null;
+    const normalizedState = state ? state.trim().toLowerCase() : null;
+    const fromMs = from ? Date.parse(String(from)) : null;
+    const toMs = to ? Date.parse(String(to)) : null;
+    const decodedCursor = cursor === null ? null : decodeX402ReceiptCursor(cursor);
+
+    const all = listX402ReceiptCandidates({ tenantId });
+    const filtered = all.filter((receipt) => {
+      if (!receipt) return false;
+      if (
+        normalizedAgentId &&
+        String(receipt.payerAgentId ?? "") !== normalizedAgentId &&
+        String(receipt.providerId ?? "") !== normalizedAgentId &&
+        String(receipt.agentKeyId ?? "") !== normalizedAgentId
+      ) {
+        return false;
+      }
+      if (normalizedSponsorId && String(receipt.sponsorRef ?? "") !== normalizedSponsorId) return false;
+      if (normalizedSponsorWalletRef && String(receipt.sponsorWalletRef ?? "") !== normalizedSponsorWalletRef) return false;
+      if (normalizedToolId && String(receipt.toolId ?? "") !== normalizedToolId) return false;
+      if (normalizedState && String(receipt.settlementState ?? "").toLowerCase() !== normalizedState) return false;
+      const settledAtMs = Number.isFinite(Date.parse(String(receipt.settledAt ?? ""))) ? Date.parse(String(receipt.settledAt)) : Number.NaN;
+      if (fromMs !== null && (!Number.isFinite(settledAtMs) || settledAtMs < fromMs)) return false;
+      if (toMs !== null && (!Number.isFinite(settledAtMs) || settledAtMs > toMs)) return false;
+      return true;
+    });
+
+    filtered.sort(compareX402ReceiptRecords);
+    const cursorFiltered = decodedCursor ? filtered.filter((row) => isReceiptAfterCursor(row, decodedCursor)) : filtered;
+    const paged = cursorFiltered.slice(offset, offset + Math.min(1000, limit));
+    const hasMore = cursorFiltered.length > offset + paged.length;
+    const nextCursor = hasMore && paged.length > 0 ? encodeX402ReceiptCursor(paged[paged.length - 1]) : null;
+    return { receipts: paged, nextCursor };
+  };
+
+  store.listX402Receipts = async function listX402Receipts(args = {}) {
+    const page = await store.listX402ReceiptsPage(args);
+    return page.receipts;
+  };
+
   store.listArbitrationCases = async function listArbitrationCases({
     tenantId = DEFAULT_TENANT_ID,
     runId = null,
@@ -1299,6 +2492,55 @@ export function createStore({ persistenceDir = null, serverSignerKeypair = null
     return all;
   };
 
+  store.listReputationEvents = async function listReputationEvents({
+    tenantId = DEFAULT_TENANT_ID,
+    agentId,
+    toolId = null,
+    occurredAtGte = null,
+    occurredAtLte = null,
+    limit = 1000,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId);
+    if (typeof agentId !== "string" || agentId.trim() === "") throw new TypeError("agentId is required");
+    if (toolId !== null && toolId !== undefined && (typeof toolId !== "string" || toolId.trim() === "")) {
+      throw new TypeError("toolId must be null or a non-empty string");
+    }
+    if (occurredAtGte !== null && occurredAtGte !== undefined && !Number.isFinite(Date.parse(String(occurredAtGte)))) {
+      throw new TypeError("occurredAtGte must be an ISO date-time");
+    }
+    if (occurredAtLte !== null && occurredAtLte !== undefined && !Number.isFinite(Date.parse(String(occurredAtLte)))) {
+      throw new TypeError("occurredAtLte must be an ISO date-time");
+    }
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new TypeError("limit must be a positive safe integer");
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new TypeError("offset must be a non-negative safe integer");
+
+    const minMs = occurredAtGte ? Date.parse(String(occurredAtGte)) : Number.NaN;
+    const maxMs = occurredAtLte ? Date.parse(String(occurredAtLte)) : Number.NaN;
+    const out = [];
+    for (const art of store.artifacts.values()) {
+      if (!art || typeof art !== "object" || Array.isArray(art)) continue;
+      if (normalizeTenantId(art.tenantId ?? DEFAULT_TENANT_ID) !== tenantId) continue;
+      if (String(art.schemaVersion ?? "") !== "ReputationEvent.v1") continue;
+      const subject = art.subject && typeof art.subject === "object" && !Array.isArray(art.subject) ? art.subject : null;
+      if (!subject) continue;
+      if (String(subject.agentId ?? "") !== String(agentId)) continue;
+      if (toolId !== null && toolId !== undefined && String(subject.toolId ?? "") !== String(toolId)) continue;
+      const occurredAtMs = Date.parse(String(art.occurredAt ?? ""));
+      if (!Number.isFinite(occurredAtMs)) continue;
+      if (Number.isFinite(minMs) && occurredAtMs < minMs) continue;
+      if (Number.isFinite(maxMs) && occurredAtMs > maxMs) continue;
+      out.push(art);
+    }
+    out.sort((left, right) => {
+      const leftMs = Date.parse(String(left?.occurredAt ?? ""));
+      const rightMs = Date.parse(String(right?.occurredAt ?? ""));
+      if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs) return leftMs - rightMs;
+      return String(left?.eventId ?? "").localeCompare(String(right?.eventId ?? ""));
+    });
+    return out.slice(offset, offset + Math.min(5000, limit));
+  };
+
   store.getArtifact = async function getArtifact({ tenantId = DEFAULT_TENANT_ID, artifactId }) {
     tenantId = normalizeTenantId(tenantId);
     if (typeof artifactId !== "string" || artifactId.trim() === "") throw new TypeError("artifactId is required");