settld 0.1.1 → 0.1.5

package/src/db/store-pg.js

@@ -155,6 +155,24 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     store.agentRuns.clear();
     if (!(store.arbitrationCases instanceof Map)) store.arbitrationCases = new Map();
     store.arbitrationCases.clear();
+    if (!(store.agreementDelegations instanceof Map)) store.agreementDelegations = new Map();
+    store.agreementDelegations.clear();
+    if (!(store.x402Gates instanceof Map)) store.x402Gates = new Map();
+    store.x402Gates.clear();
+    if (!(store.x402AgentLifecycles instanceof Map)) store.x402AgentLifecycles = new Map();
+    store.x402AgentLifecycles.clear();
+    if (!(store.x402Receipts instanceof Map)) store.x402Receipts = new Map();
+    store.x402Receipts.clear();
+    if (!(store.x402WalletPolicies instanceof Map)) store.x402WalletPolicies = new Map();
+    store.x402WalletPolicies.clear();
+    if (!(store.x402ZkVerificationKeys instanceof Map)) store.x402ZkVerificationKeys = new Map();
+    store.x402ZkVerificationKeys.clear();
+    if (!(store.x402ReversalEvents instanceof Map)) store.x402ReversalEvents = new Map();
+    store.x402ReversalEvents.clear();
+    if (!(store.x402ReversalNonceUsage instanceof Map)) store.x402ReversalNonceUsage = new Map();
+    store.x402ReversalNonceUsage.clear();
+    if (!(store.x402ReversalCommandUsage instanceof Map)) store.x402ReversalCommandUsage = new Map();
+    store.x402ReversalCommandUsage.clear();
     if (!(store.toolCallHolds instanceof Map)) store.toolCallHolds = new Map();
     store.toolCallHolds.clear();
     if (!(store.settlementAdjustments instanceof Map)) store.settlementAdjustments = new Map();
@@ -180,6 +198,84 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
           caseId: snap?.caseId ?? String(id)
         });
       }
+      if (type === "agreement_delegation") {
+        store.agreementDelegations.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          delegationId: snap?.delegationId ?? String(id)
+        });
+      }
+      if (type === "x402_gate") {
+        store.x402Gates.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          gateId: snap?.gateId ?? String(id)
+        });
+      }
+      if (type === "x402_agent_lifecycle") {
+        store.x402AgentLifecycles.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          agentId: snap?.agentId ?? String(id)
+        });
+      }
+      if (type === "x402_receipt") {
+        store.x402Receipts.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          receiptId: snap?.receiptId ?? String(id),
+          reversal: null,
+          reversalEvents: []
+        });
+      }
+      if (type === "x402_wallet_policy") {
+        const sponsorWalletRef = typeof snap?.sponsorWalletRef === "string" ? snap.sponsorWalletRef : null;
+        const policyRef = typeof snap?.policyRef === "string" ? snap.policyRef : null;
+        const policyVersion = parseSafeIntegerOrNull(snap?.policyVersion);
+        if (sponsorWalletRef && policyRef && policyVersion !== null && policyVersion > 0) {
+          store.x402WalletPolicies.set(makeScopedKey({ tenantId, id: `${sponsorWalletRef}::${policyRef}::${policyVersion}` }), {
+            ...snap,
+            tenantId: snap?.tenantId ?? tenantId,
+            sponsorWalletRef,
+            policyRef,
+            policyVersion
+          });
+        }
+      }
+      if (type === "x402_zk_verification_key") {
+        store.x402ZkVerificationKeys.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          verificationKeyId: snap?.verificationKeyId ?? String(id)
+        });
+      }
+      if (type === "x402_reversal_event") {
+        store.x402ReversalEvents.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          eventId: snap?.eventId ?? String(id)
+        });
+      }
+      if (type === "x402_reversal_nonce") {
+        const sponsorRef = typeof snap?.sponsorRef === "string" ? snap.sponsorRef : null;
+        const nonce = typeof snap?.nonce === "string" ? snap.nonce : null;
+        if (sponsorRef && nonce) {
+          const nonceKey = `${tenantId}\n${sponsorRef}\n${nonce}`;
+          store.x402ReversalNonceUsage.set(nonceKey, {
+            ...snap,
+            tenantId,
+            sponsorRef,
+            nonce
+          });
+        }
+      }
+      if (type === "x402_reversal_command") {
+        store.x402ReversalCommandUsage.set(key, {
+          ...snap,
+          tenantId: snap?.tenantId ?? tenantId,
+          commandId: snap?.commandId ?? String(id)
+        });
+      }
       if (type === "tool_call_hold") {
         store.toolCallHolds.set(key, {
           ...snap,
@@ -1149,6 +1245,341 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     );
   }
 
+  async function persistAgreementDelegation(client, { tenantId, delegationId, delegation }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!delegation || typeof delegation !== "object" || Array.isArray(delegation)) {
+      throw new TypeError("delegation is required");
+    }
+    const normalizedDelegationId =
+      delegationId ? String(delegationId) : delegation.delegationId ? String(delegation.delegationId) : null;
+    if (!normalizedDelegationId) throw new TypeError("delegationId is required");
+
+    const updatedAt = parseIsoOrNull(delegation.updatedAt) ?? new Date().toISOString();
+    const normalizedDelegation = {
+      ...delegation,
+      tenantId,
+      delegationId: normalizedDelegationId,
+      updatedAt
+    };
+
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'agreement_delegation', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, normalizedDelegationId, JSON.stringify(normalizedDelegation), updatedAt]
+    );
+  }
+
+  async function persistX402Gate(client, { tenantId, gateId, gate }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!gate || typeof gate !== "object" || Array.isArray(gate)) {
+      throw new TypeError("gate is required");
+    }
+    const normalizedGateId = gateId ? String(gateId) : gate.gateId ? String(gate.gateId) : gate.id ? String(gate.id) : null;
+    if (!normalizedGateId) throw new TypeError("gateId is required");
+
+    const updatedAt = parseIsoOrNull(gate.updatedAt) ?? new Date().toISOString();
+    const normalizedGate = {
+      ...gate,
+      tenantId,
+      gateId: normalizedGateId,
+      updatedAt
+    };
+
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_gate', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, normalizedGateId, JSON.stringify(normalizedGate), updatedAt]
+    );
+  }
+
+  async function persistX402AgentLifecycle(client, { tenantId, agentId, agentLifecycle }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!agentLifecycle || typeof agentLifecycle !== "object" || Array.isArray(agentLifecycle)) {
+      throw new TypeError("agentLifecycle is required");
+    }
+    const normalizedAgentId =
+      agentId ? String(agentId) : agentLifecycle.agentId ? String(agentLifecycle.agentId) : null;
+    if (!normalizedAgentId) throw new TypeError("agentId is required");
+    const status = String(agentLifecycle.status ?? "").trim().toLowerCase();
+    if (status !== "active" && status !== "frozen" && status !== "archived") {
+      throw new TypeError("agentLifecycle.status must be active|frozen|archived");
+    }
+
+    const updatedAt = parseIsoOrNull(agentLifecycle.updatedAt) ?? new Date().toISOString();
+    const normalizedAgentLifecycle = {
+      ...agentLifecycle,
+      tenantId,
+      agentId: normalizedAgentId,
+      status,
+      updatedAt
+    };
+
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_agent_lifecycle', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, normalizedAgentId, JSON.stringify(normalizedAgentLifecycle), updatedAt]
+    );
+  }
+
+  async function persistX402Receipt(client, { tenantId, receiptId, receipt }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+      throw new TypeError("receipt is required");
+    }
+    const normalizedReceiptId =
+      receiptId ? String(receiptId) : receipt.receiptId ? String(receipt.receiptId) : null;
+    if (!normalizedReceiptId) throw new TypeError("receiptId is required");
+
+    const updatedAt =
+      parseIsoOrNull(receipt.createdAt) ??
+      parseIsoOrNull(receipt.settledAt) ??
+      parseIsoOrNull(receipt.updatedAt) ??
+      new Date().toISOString();
+    const normalizedReceipt = {
+      ...receipt,
+      tenantId,
+      receiptId: normalizedReceiptId,
+      reversal: null,
+      reversalEvents: [],
+      updatedAt
+    };
+
+    const inserted = await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_receipt', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO NOTHING
+        RETURNING aggregate_id
+      `,
+      [tenantId, normalizedReceiptId, JSON.stringify(normalizedReceipt), updatedAt]
+    );
+    if (inserted.rows.length > 0) return;
+
+    const existing = await client.query(
+      `
+        SELECT snapshot_json
+        FROM snapshots
+        WHERE tenant_id = $1 AND aggregate_type = 'x402_receipt' AND aggregate_id = $2
+        LIMIT 1
+      `,
+      [tenantId, normalizedReceiptId]
+    );
+    if (!existing.rows.length) return;
+
+    const existingCanonical = canonicalJsonStringify(existing.rows[0]?.snapshot_json ?? null);
+    const incomingCanonical = canonicalJsonStringify(normalizedReceipt);
+    if (existingCanonical !== incomingCanonical) {
+      const err = new Error("x402 receipt is immutable and cannot be changed");
+      err.code = "X402_RECEIPT_IMMUTABLE";
+      err.receiptId = normalizedReceiptId;
+      throw err;
+    }
+  }
+
+  async function persistX402WalletPolicy(client, { tenantId, policy }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+      throw new TypeError("policy is required");
+    }
+    const sponsorWalletRef =
+      policy.sponsorWalletRef && String(policy.sponsorWalletRef).trim() !== ""
+        ? String(policy.sponsorWalletRef).trim()
+        : null;
+    const policyRef = policy.policyRef && String(policy.policyRef).trim() !== "" ? String(policy.policyRef).trim() : null;
+    const policyVersion = parseSafeIntegerOrNull(policy.policyVersion);
+    if (!sponsorWalletRef) throw new TypeError("policy.sponsorWalletRef is required");
+    if (!policyRef) throw new TypeError("policy.policyRef is required");
+    if (policyVersion === null || policyVersion <= 0) throw new TypeError("policy.policyVersion must be >= 1");
+    const aggregateId = `${sponsorWalletRef}::${policyRef}::${policyVersion}`;
+    const updatedAt = parseIsoOrNull(policy.updatedAt) ?? new Date().toISOString();
+    const normalizedPolicy = {
+      ...policy,
+      tenantId,
+      sponsorWalletRef,
+      policyRef,
+      policyVersion,
+      updatedAt
+    };
+
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_wallet_policy', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, aggregateId, JSON.stringify(normalizedPolicy), updatedAt]
+    );
+  }
+
+  async function persistX402ZkVerificationKey(client, { tenantId, verificationKeyId, verificationKey }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!verificationKey || typeof verificationKey !== "object" || Array.isArray(verificationKey)) {
+      throw new TypeError("verificationKey is required");
+    }
+    const normalizedVerificationKeyId =
+      verificationKeyId && String(verificationKeyId).trim() !== ""
+        ? String(verificationKeyId).trim()
+        : verificationKey.verificationKeyId && String(verificationKey.verificationKeyId).trim() !== ""
+          ? String(verificationKey.verificationKeyId).trim()
+          : null;
+    if (!normalizedVerificationKeyId) throw new TypeError("verificationKeyId is required");
+    const createdAt =
+      parseIsoOrNull(verificationKey.createdAt) ??
+      parseIsoOrNull(verificationKey.updatedAt) ??
+      new Date().toISOString();
+    const normalizedVerificationKey = {
+      ...verificationKey,
+      tenantId,
+      verificationKeyId: normalizedVerificationKeyId,
+      createdAt,
+      updatedAt: createdAt
+    };
+
+    const inserted = await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_zk_verification_key', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO NOTHING
+        RETURNING aggregate_id
+      `,
+      [tenantId, normalizedVerificationKeyId, JSON.stringify(normalizedVerificationKey), createdAt]
+    );
+    if (inserted.rows.length > 0) return;
+
+    const existing = await client.query(
+      `
+        SELECT snapshot_json
+        FROM snapshots
+        WHERE tenant_id = $1 AND aggregate_type = 'x402_zk_verification_key' AND aggregate_id = $2
+        LIMIT 1
+      `,
+      [tenantId, normalizedVerificationKeyId]
+    );
+    if (!existing.rows.length) return;
+
+    const existingCanonical = canonicalJsonStringify(existing.rows[0]?.snapshot_json ?? null);
+    const incomingCanonical = canonicalJsonStringify(normalizedVerificationKey);
+    if (existingCanonical !== incomingCanonical) {
+      const err = new Error("x402 zk verification key is immutable and cannot be changed");
+      err.code = "X402_ZK_VERIFICATION_KEY_IMMUTABLE";
+      err.verificationKeyId = normalizedVerificationKeyId;
+      throw err;
+    }
+  }
+
+  async function persistX402ReversalEvent(client, { tenantId, gateId, eventId, event }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      throw new TypeError("event is required");
+    }
+    const normalizedEventId = eventId ? String(eventId) : event.eventId ? String(event.eventId) : event.id ? String(event.id) : null;
+    if (!normalizedEventId) throw new TypeError("eventId is required");
+    const normalizedGateId = gateId ? String(gateId) : event.gateId ? String(event.gateId) : null;
+    if (!normalizedGateId) throw new TypeError("gateId is required");
+    const updatedAt = parseIsoOrNull(event.occurredAt ?? event.createdAt) ?? new Date().toISOString();
+    const normalizedEvent = {
+      ...event,
+      tenantId,
+      gateId: normalizedGateId,
+      eventId: normalizedEventId,
+      occurredAt: parseIsoOrNull(event.occurredAt) ?? updatedAt
+    };
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_reversal_event', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, normalizedEventId, JSON.stringify(normalizedEvent), updatedAt]
+    );
+  }
+
+  async function persistX402ReversalNonceUsage(client, { tenantId, sponsorRef, nonce, usage }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!usage || typeof usage !== "object" || Array.isArray(usage)) throw new TypeError("usage is required");
+    const normalizedSponsorRef =
+      sponsorRef && String(sponsorRef).trim() !== ""
+        ? String(sponsorRef).trim()
+        : usage.sponsorRef && String(usage.sponsorRef).trim() !== ""
+          ? String(usage.sponsorRef).trim()
+          : null;
+    const normalizedNonce =
+      nonce && String(nonce).trim() !== ""
+        ? String(nonce).trim()
+        : usage.nonce && String(usage.nonce).trim() !== ""
+          ? String(usage.nonce).trim()
+          : null;
+    if (!normalizedSponsorRef) throw new TypeError("sponsorRef is required");
+    if (!normalizedNonce) throw new TypeError("nonce is required");
+    const aggregateId = `${normalizedSponsorRef}::${normalizedNonce}`;
+    const updatedAt = parseIsoOrNull(usage.usedAt) ?? new Date().toISOString();
+    const normalizedUsage = {
+      ...usage,
+      tenantId,
+      sponsorRef: normalizedSponsorRef,
+      nonce: normalizedNonce,
+      usedAt: parseIsoOrNull(usage.usedAt) ?? updatedAt
+    };
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_reversal_nonce', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, aggregateId, JSON.stringify(normalizedUsage), updatedAt]
+    );
+  }
+
+  async function persistX402ReversalCommandUsage(client, { tenantId, commandId, usage }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!usage || typeof usage !== "object" || Array.isArray(usage)) throw new TypeError("usage is required");
+    const normalizedCommandId =
+      commandId && String(commandId).trim() !== ""
+        ? String(commandId).trim()
+        : usage.commandId && String(usage.commandId).trim() !== ""
+          ? String(usage.commandId).trim()
+          : null;
+    if (!normalizedCommandId) throw new TypeError("commandId is required");
+    const updatedAt = parseIsoOrNull(usage.usedAt) ?? new Date().toISOString();
+    const normalizedUsage = {
+      ...usage,
+      tenantId,
+      commandId: normalizedCommandId,
+      usedAt: parseIsoOrNull(usage.usedAt) ?? updatedAt
+    };
+    await client.query(
+      `
+        INSERT INTO snapshots (tenant_id, aggregate_type, aggregate_id, seq, at_chain_hash, snapshot_json, updated_at)
+        VALUES ($1, 'x402_reversal_command', $2, 0, NULL, $3, $4)
+        ON CONFLICT (tenant_id, aggregate_type, aggregate_id) DO UPDATE SET
+          snapshot_json = EXCLUDED.snapshot_json,
+          updated_at = EXCLUDED.updated_at
+      `,
+      [tenantId, normalizedCommandId, JSON.stringify(normalizedUsage), updatedAt]
+    );
+  }
+
   async function persistToolCallHold(client, { tenantId, holdHash, hold }) {
     tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
     if (!hold || typeof hold !== "object" || Array.isArray(hold)) {
@@ -1643,6 +2074,15 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
       "AGENT_RUN_EVENTS_APPENDED",
       "AGENT_RUN_SETTLEMENT_UPSERT",
       "ARBITRATION_CASE_UPSERT",
+      "AGREEMENT_DELEGATION_UPSERT",
+      "X402_GATE_UPSERT",
+      "X402_AGENT_LIFECYCLE_UPSERT",
+      "X402_RECEIPT_PUT",
+      "X402_WALLET_POLICY_UPSERT",
+      "X402_ZK_VERIFICATION_KEY_PUT",
+      "X402_REVERSAL_EVENT_APPEND",
+      "X402_REVERSAL_NONCE_PUT",
+      "X402_REVERSAL_COMMAND_PUT",
       "TOOL_CALL_HOLD_UPSERT",
       "SETTLEMENT_ADJUSTMENT_PUT",
       "MARKETPLACE_RFQ_UPSERT",
@@ -2028,6 +2468,45 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     );
   }
 
+  async function persistReputationEventIndexRow(client, { tenantId, artifactId, artifactHash, artifact }) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) return;
+    if (String(artifact.artifactType ?? artifact.schemaVersion ?? "") !== "ReputationEvent.v1") return;
+
+    const subject = artifact.subject && typeof artifact.subject === "object" && !Array.isArray(artifact.subject) ? artifact.subject : null;
+    const sourceRef = artifact.sourceRef && typeof artifact.sourceRef === "object" && !Array.isArray(artifact.sourceRef) ? artifact.sourceRef : null;
+    const agentId = subject?.agentId ? String(subject.agentId).trim() : "";
+    if (!agentId) return;
+
+    const toolIdRaw = subject?.toolId ? String(subject.toolId).trim() : "";
+    const toolId = toolIdRaw === "" ? null : toolIdRaw;
+    const sourceKindRaw = sourceRef?.kind ? String(sourceRef.kind).trim().toLowerCase() : "";
+    const sourceKind = sourceKindRaw === "" ? "unknown" : sourceKindRaw;
+    const sourceHashRaw = sourceRef?.hash ? String(sourceRef.hash).trim().toLowerCase() : "";
+    const sourceHash = sourceHashRaw === "" ? null : sourceHashRaw;
+    const eventKindRaw = artifact?.eventKind ? String(artifact.eventKind).trim().toLowerCase() : "";
+    const eventKind = eventKindRaw === "" ? "unknown" : eventKindRaw;
+    const occurredAtParsed = Date.parse(String(artifact.occurredAt ?? ""));
+    const occurredAt = Number.isFinite(occurredAtParsed) ? new Date(occurredAtParsed).toISOString() : new Date().toISOString();
+
+    await client.query(
+      `
+        INSERT INTO reputation_event_index (
+          tenant_id, artifact_id, artifact_hash, subject_agent_id, subject_tool_id, occurred_at, event_kind, source_kind, source_hash
+        ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+        ON CONFLICT (tenant_id, artifact_id) DO UPDATE SET
+          artifact_hash = EXCLUDED.artifact_hash,
+          subject_agent_id = EXCLUDED.subject_agent_id,
+          subject_tool_id = EXCLUDED.subject_tool_id,
+          occurred_at = EXCLUDED.occurred_at,
+          event_kind = EXCLUDED.event_kind,
+          source_kind = EXCLUDED.source_kind,
+          source_hash = EXCLUDED.source_hash
+      `,
+      [tenantId, String(artifactId), String(artifactHash), agentId, toolId, occurredAt, eventKind, sourceKind, sourceHash]
+    );
+  }
+
 	  async function persistArtifactRow(client, { tenantId, artifact }) {
 	    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
 	    if (!artifact || typeof artifact !== "object") throw new TypeError("artifact is required");
@@ -2040,9 +2519,12 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     const jobId = String(artifact.jobId ?? "");
     const sourceEventId = typeof artifact.sourceEventId === "string" && artifact.sourceEventId.trim() !== "" ? String(artifact.sourceEventId) : "";
 
-    // Invariant: for artifacts tied to a specific source event, there must be exactly one artifact per
+    // Invariant: for artifacts tied to a specific *job* source event, there must be exactly one artifact per
     // (jobId + artifactType + sourceEventId). This prevents duplicate settlement-backed certificates.
-    if (sourceEventId) {
+    //
+    // Important: many non-job artifacts (month close statements, party statements, payout instructions, etc.) set a
+    // sourceEventId but intentionally do not have a jobId. Do not apply this invariant to those artifacts.
+    if (sourceEventId && jobId) {
       const existingBySource = await client.query(
         "SELECT artifact_id, artifact_hash FROM artifacts WHERE tenant_id = $1 AND job_id = $2 AND artifact_type = $3 AND source_event_id = $4 LIMIT 1",
         [tenantId, jobId, artifactType, sourceEventId]
@@ -2058,80 +2540,89 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
           err.gotArtifactHash = String(artifactHash);
           throw err;
         }
+        await persistReputationEventIndexRow(client, { tenantId, artifactId: currentId, artifactHash: currentHash, artifact });
         return;
       }
     }
 
-    const existing = await client.query("SELECT artifact_hash FROM artifacts WHERE tenant_id = $1 AND artifact_id = $2", [tenantId, artifactId]);
-	    if (existing.rows.length) {
-	      const current = String(existing.rows[0].artifact_hash);
-	      if (current !== String(artifactHash)) {
-	        const err = new Error("artifactId already exists with a different hash");
-	        err.code = "ARTIFACT_HASH_MISMATCH";
-	        err.expectedArtifactHash = current;
-	        err.gotArtifactHash = String(artifactHash);
-	        throw err;
-	      }
-	      return;
-	    }
+		    const existing = await client.query("SELECT artifact_hash FROM artifacts WHERE tenant_id = $1 AND artifact_id = $2", [tenantId, artifactId]);
+		    if (existing.rows.length) {
+		      const current = String(existing.rows[0].artifact_hash);
+		      if (current !== String(artifactHash)) {
+		        const err = new Error("artifactId already exists with a different hash");
+		        err.code = "ARTIFACT_HASH_MISMATCH";
+		        err.expectedArtifactHash = current;
+		        err.gotArtifactHash = String(artifactHash);
+		        throw err;
+		      }
+		      await persistReputationEventIndexRow(client, { tenantId, artifactId, artifactHash: current, artifact });
+		      return;
+		    }
+
+        // Avoid transaction-aborting unique-constraint errors (we run inside explicit transactions).
+        // Handle all unique conflicts by doing nothing and then checking what already exists.
+        const insertRes = await client.query(
+          `
+            INSERT INTO artifacts (tenant_id, artifact_id, artifact_type, job_id, at_chain_hash, source_event_id, artifact_hash, artifact_json)
+            VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
+            ON CONFLICT DO NOTHING
+          `,
+          [
+            tenantId,
+            String(artifactId),
+            artifactType,
+            jobId,
+            String(artifact.atChainHash ?? artifact.eventProof?.lastChainHash ?? ""),
+            sourceEventId,
+            String(artifactHash),
+            JSON.stringify(artifact)
+          ]
+        );
+        if (Number(insertRes?.rowCount ?? 0) > 0) {
+          await persistReputationEventIndexRow(client, { tenantId, artifactId, artifactHash, artifact });
+          return;
+        }
 
-	    try {
-	      await client.query(
-	        `
-	          INSERT INTO artifacts (tenant_id, artifact_id, artifact_type, job_id, at_chain_hash, source_event_id, artifact_hash, artifact_json)
-	          VALUES ($1,$2,$3,$4,$5,$6,$7,$8)
-	        `,
-	        [
-	          tenantId,
-	          String(artifactId),
-	          artifactType,
-	          jobId,
-	          String(artifact.atChainHash ?? artifact.eventProof?.lastChainHash ?? ""),
-	          sourceEventId,
-	          String(artifactHash),
-	          JSON.stringify(artifact)
-	        ]
-	      );
-	    } catch (err) {
-	      // Under concurrency, two workers may attempt to persist the same artifact at the same time. Treat this as
-	      // idempotent when the existing row's hash matches, and retryable otherwise.
-	      if (err?.code === "23505") {
-	        if (sourceEventId) {
-	          const bySource = await client.query(
-	            "SELECT artifact_id, artifact_hash FROM artifacts WHERE tenant_id = $1 AND job_id = $2 AND artifact_type = $3 AND source_event_id = $4 LIMIT 1",
-	            [tenantId, jobId, artifactType, sourceEventId]
-	          );
-	          if (bySource.rows.length) {
-	            const currentId = String(bySource.rows[0].artifact_id);
-	            const currentHash = String(bySource.rows[0].artifact_hash);
-	            if (currentHash === String(artifactHash)) return;
-	            const conflict = new Error("artifact already exists for this job/type/sourceEventId with a different hash");
-	            conflict.code = "ARTIFACT_SOURCE_EVENT_CONFLICT";
-	            conflict.existingArtifactId = currentId;
-	            conflict.existingArtifactHash = currentHash;
-	            conflict.gotArtifactHash = String(artifactHash);
-	            throw conflict;
-	          }
-	        }
+        // Someone else inserted a conflicting row under a unique constraint. Determine if it's idempotent.
+        const byId = await client.query("SELECT artifact_hash FROM artifacts WHERE tenant_id = $1 AND artifact_id = $2", [tenantId, artifactId]);
+        if (byId.rows.length) {
+          const current = String(byId.rows[0].artifact_hash);
+          if (current === String(artifactHash)) {
+            await persistReputationEventIndexRow(client, { tenantId, artifactId, artifactHash: current, artifact });
+            return;
+          }
+          const mismatch = new Error("artifactId already exists with a different hash");
+          mismatch.code = "ARTIFACT_HASH_MISMATCH";
+          mismatch.expectedArtifactHash = current;
+          mismatch.gotArtifactHash = String(artifactHash);
+          throw mismatch;
+        }
 
-	        const byId = await client.query("SELECT artifact_hash FROM artifacts WHERE tenant_id = $1 AND artifact_id = $2", [tenantId, artifactId]);
-	        if (byId.rows.length) {
-	          const current = String(byId.rows[0].artifact_hash);
-	          if (current === String(artifactHash)) return;
-	          const mismatch = new Error("artifactId already exists with a different hash");
-	          mismatch.code = "ARTIFACT_HASH_MISMATCH";
-	          mismatch.expectedArtifactHash = current;
-	          mismatch.gotArtifactHash = String(artifactHash);
-	          throw mismatch;
-	        }
+        if (sourceEventId && jobId) {
+          const bySource = await client.query(
+            "SELECT artifact_id, artifact_hash FROM artifacts WHERE tenant_id = $1 AND job_id = $2 AND artifact_type = $3 AND source_event_id = $4 LIMIT 1",
+            [tenantId, jobId, artifactType, sourceEventId]
+          );
+          if (bySource.rows.length) {
+            const currentId = String(bySource.rows[0].artifact_id);
+            const currentHash = String(bySource.rows[0].artifact_hash);
+            if (currentHash === String(artifactHash)) {
+              await persistReputationEventIndexRow(client, { tenantId, artifactId: currentId, artifactHash: currentHash, artifact });
+              return;
+            }
+            const conflict = new Error("artifact already exists for this job/type/sourceEventId with a different hash");
+            conflict.code = "ARTIFACT_SOURCE_EVENT_CONFLICT";
+            conflict.existingArtifactId = currentId;
+            conflict.existingArtifactHash = currentHash;
+            conflict.gotArtifactHash = String(artifactHash);
+            throw conflict;
+          }
+        }
 
-	        const raced = new Error("artifact insert raced with another transaction");
-	        raced.code = "ARTIFACT_INSERT_RACE";
-	        throw raced;
-	      }
-	      throw err;
-	    }
-	  }
+        const raced = new Error("artifact insert raced with another transaction");
+        raced.code = "ARTIFACT_INSERT_RACE";
+        throw raced;
+		  }
 
   async function insertDeliveryRow(client, { tenantId, delivery }) {
     tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
@@ -2415,6 +2906,60 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
           const tenantId = normalizeTenantId(op.tenantId ?? op.arbitrationCase?.tenantId ?? DEFAULT_TENANT_ID);
           await persistArbitrationCase(client, { tenantId, caseId: op.caseId, arbitrationCase: op.arbitrationCase });
         }
+        if (op.kind === "AGREEMENT_DELEGATION_UPSERT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.delegation?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistAgreementDelegation(client, { tenantId, delegationId: op.delegationId, delegation: op.delegation });
+        }
+        if (op.kind === "X402_GATE_UPSERT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.gate?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402Gate(client, { tenantId, gateId: op.gateId, gate: op.gate });
+        }
+        if (op.kind === "X402_AGENT_LIFECYCLE_UPSERT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.agentLifecycle?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402AgentLifecycle(client, { tenantId, agentId: op.agentId, agentLifecycle: op.agentLifecycle });
+        }
+        if (op.kind === "X402_RECEIPT_PUT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.receipt?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402Receipt(client, { tenantId, receiptId: op.receiptId, receipt: op.receipt });
+        }
+        if (op.kind === "X402_WALLET_POLICY_UPSERT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.policy?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402WalletPolicy(client, { tenantId, policy: op.policy });
+        }
+        if (op.kind === "X402_ZK_VERIFICATION_KEY_PUT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.verificationKey?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402ZkVerificationKey(client, {
+            tenantId,
+            verificationKeyId: op.verificationKeyId,
+            verificationKey: op.verificationKey
+          });
+        }
+        if (op.kind === "X402_REVERSAL_EVENT_APPEND") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.event?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402ReversalEvent(client, {
+            tenantId,
+            gateId: op.gateId,
+            eventId: op.eventId,
+            event: op.event
+          });
+        }
+        if (op.kind === "X402_REVERSAL_NONCE_PUT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.usage?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402ReversalNonceUsage(client, {
+            tenantId,
+            sponsorRef: op.sponsorRef,
+            nonce: op.nonce,
+            usage: op.usage
+          });
+        }
+        if (op.kind === "X402_REVERSAL_COMMAND_PUT") {
+          const tenantId = normalizeTenantId(op.tenantId ?? op.usage?.tenantId ?? DEFAULT_TENANT_ID);
+          await persistX402ReversalCommandUsage(client, {
+            tenantId,
+            commandId: op.commandId,
+            usage: op.usage
+          });
+        }
         if (op.kind === "TOOL_CALL_HOLD_UPSERT") {
           const tenantId = normalizeTenantId(op.tenantId ?? op.hold?.tenantId ?? DEFAULT_TENANT_ID);
           await persistToolCallHold(client, { tenantId, holdHash: op.holdHash, hold: op.hold });
@@ -2758,6 +3303,88 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     }
   };
 
+  store.sumWalletPolicySpendCentsForDay = async function sumWalletPolicySpendCentsForDay({
+    tenantId = DEFAULT_TENANT_ID,
+    agentId,
+    dayStartIso,
+    dayEndIso
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    assertNonEmptyString(agentId, "agentId");
+    assertNonEmptyString(dayStartIso, "dayStartIso");
+    assertNonEmptyString(dayEndIso, "dayEndIso");
+    const startMs = Date.parse(dayStartIso);
+    const endMs = Date.parse(dayEndIso);
+    if (!Number.isFinite(startMs)) throw new TypeError("dayStartIso must be an ISO date string");
+    if (!Number.isFinite(endMs)) throw new TypeError("dayEndIso must be an ISO date string");
+    if (!(endMs > startMs)) throw new TypeError("dayEndIso must be after dayStartIso");
+
+    let runSum = 0;
+    try {
+      const res = await pool.query(
+        `
+          SELECT COALESCE(SUM(amount_cents), 0)::bigint AS c
+          FROM agent_run_settlements
+          WHERE tenant_id = $1
+            AND payer_agent_id = $2
+            AND locked_at >= $3
+            AND locked_at < $4
+        `,
+        [tenantId, String(agentId), String(dayStartIso), String(dayEndIso)]
+      );
+      const n = Number(res.rows[0]?.c ?? 0);
+      runSum = Number.isSafeInteger(n) && n >= 0 ? n : 0;
+    } catch (err) {
+      if (err?.code !== "42P01") throw err;
+      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)) continue;
+        if (lockedMs < startMs || lockedMs >= endMs) continue;
+        const amountCents = Number(row.amountCents ?? 0);
+        if (!Number.isSafeInteger(amountCents) || amountCents <= 0) continue;
+        runSum += amountCents;
+      }
+    }
+
+    let holdSum = 0;
+    try {
+      const res = await pool.query(
+        `
+          SELECT COALESCE(SUM((snapshot_json->>'heldAmountCents')::bigint), 0)::bigint AS c
+          FROM snapshots
+          WHERE tenant_id = $1
+            AND aggregate_type = 'tool_call_hold'
+            AND snapshot_json->>'payerAgentId' = $2
+            AND (snapshot_json->>'createdAt')::timestamptz >= $3::timestamptz
+            AND (snapshot_json->>'createdAt')::timestamptz < $4::timestamptz
+        `,
+        [tenantId, String(agentId), String(dayStartIso), String(dayEndIso)]
+      );
+      const n = Number(res.rows[0]?.c ?? 0);
+      holdSum = Number.isSafeInteger(n) && n >= 0 ? n : 0;
+    } catch (err) {
+      if (err?.code !== "42P01") throw err;
+      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)) continue;
+        if (createdMs < startMs || createdMs >= endMs) continue;
+        const heldAmountCents = Number(row.heldAmountCents ?? 0);
+        if (!Number.isSafeInteger(heldAmountCents) || heldAmountCents <= 0) continue;
+        holdSum += heldAmountCents;
+      }
+    }
+
+    return runSum + holdSum;
+  };
+
   function arbitrationCaseSnapshotRowToRecord(row) {
     const arbitrationCase = row?.snapshot_json ?? null;
     if (!arbitrationCase || typeof arbitrationCase !== "object" || Array.isArray(arbitrationCase)) return null;
@@ -4734,6 +5361,58 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     return res.rows.map((r) => r.artifact_json);
   };
 
+  store.listReputationEvents = async function listReputationEvents({
+    tenantId = DEFAULT_TENANT_ID,
+    agentId,
+    toolId = null,
+    occurredAtGte = null,
+    occurredAtLte = null,
+    limit = 1000,
+    offset = 0
+  } = {}) {
+    tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+    assertNonEmptyString(agentId, "agentId");
+    if (toolId !== null && toolId !== undefined) assertNonEmptyString(toolId, "toolId");
+    if (occurredAtGte !== null && occurredAtGte !== undefined) assertNonEmptyString(occurredAtGte, "occurredAtGte");
+    if (occurredAtLte !== null && occurredAtLte !== undefined) assertNonEmptyString(occurredAtLte, "occurredAtLte");
+    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 params = [tenantId, String(agentId)];
+    const where = ["idx.tenant_id = $1", "idx.subject_agent_id = $2"];
+    if (toolId !== null && toolId !== undefined) {
+      params.push(String(toolId));
+      where.push(`idx.subject_tool_id = $${params.length}`);
+    }
+    if (occurredAtGte !== null && occurredAtGte !== undefined) {
+      params.push(String(occurredAtGte));
+      where.push(`idx.occurred_at >= $${params.length}::timestamptz`);
+    }
+    if (occurredAtLte !== null && occurredAtLte !== undefined) {
+      params.push(String(occurredAtLte));
+      where.push(`idx.occurred_at <= $${params.length}::timestamptz`);
+    }
+    const safeLimit = Math.min(5000, limit);
+    params.push(safeLimit);
+    params.push(offset);
+
+    const res = await pool.query(
+      `
+        SELECT a.artifact_json
+        FROM reputation_event_index idx
+        INNER JOIN artifacts a
+          ON a.tenant_id = idx.tenant_id
+         AND a.artifact_id = idx.artifact_id
+        WHERE ${where.join(" AND ")}
+        ORDER BY idx.occurred_at ASC, idx.artifact_id ASC
+        LIMIT $${params.length - 1}
+        OFFSET $${params.length}
+      `,
+      params
+    );
+    return res.rows.map((row) => row.artifact_json);
+  };
+
   store.createDelivery = async function createDelivery({ tenantId = DEFAULT_TENANT_ID, delivery }) {
     tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
     if (!delivery || typeof delivery !== "object") throw new TypeError("delivery is required");
@@ -5596,7 +6275,10 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
               `,
               [tenantId, periodStart, periodEnd]
             );
-            const jobIds = settledIdsRes.rows.map((r) => String(r.aggregate_id)).filter((id) => id && id.trim() !== "");
+            const jobIds = settledIdsRes.rows
+              .map((r) => String(r.aggregate_id))
+              .filter((id) => id && id.trim() !== "")
+              .sort((a, b) => a.localeCompare(b));
 
             const jobs = [];
             if (jobIds.length) {
@@ -5604,7 +6286,11 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
                 "SELECT aggregate_id, snapshot_json FROM snapshots WHERE tenant_id = $1 AND aggregate_type = 'job' AND aggregate_id = ANY($2::text[])",
                 [tenantId, jobIds]
               );
-              for (const r of snapRes.rows) {
+              // Determinism: DB may return rows in arbitrary order for ANY($2), but artifacts must be hash-stable.
+              const ordered = snapRes.rows
+                .slice()
+                .sort((a, b) => String(a.aggregate_id ?? "").localeCompare(String(b.aggregate_id ?? "")));
+              for (const r of ordered) {
                 jobs.push(r.snapshot_json);
               }
             }
@@ -6395,13 +7081,93 @@ export async function createPgStore({ databaseUrl, schema = "public", dropSchema
     return { processed, worker };
   }
 
+  async function processNoopOutboxTopic({ topic, worker, maxMessages = Number.MAX_SAFE_INTEGER } = {}) {
+    if (typeof topic !== "string" || topic.trim() === "") throw new TypeError("topic is required");
+    if (typeof worker !== "string" || worker.trim() === "") throw new TypeError("worker is required");
+    if (!Number.isSafeInteger(maxMessages) || maxMessages < 0) throw new TypeError("maxMessages must be a non-negative safe integer");
+
+    const processed = [];
+
+    // These topics are informational today (no worker consumes them in pg mode).
+    // Drain them deterministically so ops / hosted-baseline checks don't wedge.
+    while (processed.length < maxMessages) {
+      const claimed = await store.claimOutbox({ topic, maxMessages: Math.min(1000, maxMessages - processed.length), worker });
+      if (!claimed.length) break;
+      const ids = claimed.map((r) => r.id);
+      await store.markOutboxProcessed({ ids, lastError: "ok:noop" });
+      for (const id of ids) processed.push({ id, status: "noop" });
+    }
+
+    return { processed, worker };
+  }
+
   store.processOutbox = async function processOutbox({ maxMessages = 1000 } = {}) {
     const ledger = await processLedgerOutbox({ maxMessages });
     const notifications = await processNotificationsOutbox({ maxMessages });
     const correlations = await processCorrelationsOutbox({ maxMessages });
+    const jobStatusChanged = await processNoopOutboxTopic({ topic: "JOB_STATUS_CHANGED", worker: "job_status_changed_v0", maxMessages });
+    const jobSettled = await processNoopOutboxTopic({ topic: "JOB_SETTLED", worker: "job_settled_v0", maxMessages });
     const monthClose = await processMonthCloseOutbox({ maxMessages });
     const financePack = await processFinancePackOutbox({ maxMessages });
-    return { ledger, notifications, correlations, monthClose, financePack };
+    return { ledger, notifications, correlations, jobStatusChanged, jobSettled, monthClose, financePack };
+  };
+
+  // Read-only ops debugging helper (used by /ops/debug/outbox).
+  // Intentionally narrow: surfaces enough to diagnose stuck/DLQ outbox without direct DB access.
+  store.listOutboxDebug = async function listOutboxDebug({
+    topic = null,
+    tenantId = null,
+    includeProcessed = false,
+    state = null,
+    limit = 50
+  } = {}) {
+    const safeLimit = Number.isSafeInteger(Number(limit)) ? Number(limit) : 50;
+    if (safeLimit <= 0 || safeLimit > 500) throw new TypeError("limit must be a safe integer between 1 and 500");
+    const t = typeof topic === "string" && topic.trim() ? topic.trim() : null;
+    const tenant = typeof tenantId === "string" && tenantId.trim() ? normalizeTenantId(tenantId) : null;
+    const normalizedState = typeof state === "string" && state.trim() ? state.trim().toLowerCase() : null;
+    if (
+      normalizedState !== null &&
+      normalizedState !== "pending" &&
+      normalizedState !== "processed" &&
+      normalizedState !== "dlq" &&
+      normalizedState !== "all"
+    ) {
+      throw new TypeError("state must be one of pending|processed|dlq|all");
+    }
+
+    return await withTx({ statementTimeoutMs: workerStatementTimeoutMs }, async (client) => {
+      const params = [];
+      let where = `WHERE 1=1`;
+      if (normalizedState === "pending") {
+        where += ` AND processed_at IS NULL`;
+      } else if (normalizedState === "processed") {
+        where += ` AND processed_at IS NOT NULL AND (last_error IS NULL OR last_error NOT LIKE 'DLQ:%')`;
+      } else if (normalizedState === "dlq") {
+        where += ` AND processed_at IS NOT NULL AND last_error LIKE 'DLQ:%'`;
+      } else if (normalizedState !== "all" && !includeProcessed) {
+        // Backward compatibility when state is omitted.
+        where += ` AND processed_at IS NULL`;
+      }
+      if (t) {
+        params.push(String(t));
+        where += ` AND topic = $${params.length}`;
+      }
+      if (tenant) {
+        params.push(String(tenant));
+        where += ` AND tenant_id = $${params.length}`;
+      }
+      params.push(safeLimit);
+      const sql = `
+        SELECT id, tenant_id, topic, aggregate_type, aggregate_id, attempts, claimed_at, processed_at, last_error, payload_json
+        FROM outbox
+        ${where}
+        ORDER BY id DESC
+        LIMIT $${params.length}
+      `;
+      const res = await client.query(sql, params);
+      return res.rows;
+    });
   };
 
   store.close = async function close() {