settld 0.1.2 → 0.2.0

package/src/api/workers/deliveries.js

@@ -40,6 +40,13 @@ function computeBackoffMs({ attempts, baseMs = 1000, maxMs = 60_000, random = Ma
   return Math.max(baseMs, Math.floor(raw * jitter));
 }
 
+function headerSafeValue(value) {
+  // Prevent fetch/undici from throwing on invalid header values (CTL chars, newlines).
+  // `orderKey` is allowed to include newlines internally; for transport we normalize it.
+  const s = String(value ?? "");
+  return s.replaceAll(/[\u0000-\u001F\u007F]/g, " ").trim();
+}
+
 async function fetchWithTimeout(fetchFn, url, options, timeoutMs) {
   if (typeof fetchFn !== "function") throw new TypeError("fetchFn must be a function");
   const ms = Number(timeoutMs);
@@ -105,6 +112,30 @@ export function createDeliveryWorker({
     return list.find((d) => d.destinationId === destinationId) ?? null;
   }
 
+  async function recordWebhookEndpointDeliveryResult({
+    tenantId,
+    destinationId,
+    deliveredAt = nowIso(),
+    success,
+    failureReason = null,
+    statusCode = null
+  } = {}) {
+    if (typeof store.recordX402WebhookEndpointDeliveryResult !== "function") return;
+    if (typeof destinationId !== "string" || destinationId.trim() === "") return;
+    try {
+      await store.recordX402WebhookEndpointDeliveryResult({
+        tenantId,
+        destinationId,
+        deliveredAt,
+        success,
+        failureReason,
+        statusCode
+      });
+    } catch {
+      // best effort; delivery processing should not fail because health tracking failed
+    }
+  }
+
   function safeKeySegment(value) {
     return String(value ?? "")
       .trim()
@@ -236,9 +267,14 @@ export function createDeliveryWorker({
         failureReason: failureReasonForSecretError(err)
       };
     }
+    const previousSecrets = Array.isArray(dest.previousSecrets)
+      ? dest.previousSecrets.filter((value) => typeof value === "string" && value.trim() !== "")
+      : [];
 
     const timestamp = nowIso();
-    const signature = hmacSignArtifact({ secret, timestamp, bodyJson: artifact });
+    const allSecrets = [secret, ...previousSecrets.filter((candidate) => candidate !== secret)];
+    const signatures = allSecrets.map((activeSecret) => hmacSignArtifact({ secret: activeSecret, timestamp, bodyJson: artifact }));
+    const signatureHeader = signatures.length > 1 ? signatures.map((value) => `v1=${value}`).join(",") : signatures[0];
     const body = canonicalJsonStringify(artifact);
 
     let res;
@@ -255,9 +291,11 @@ export function createDeliveryWorker({
             "x-proxy-artifact-type": String(delivery.artifactType ?? ""),
             "x-proxy-artifact-id": String(delivery.artifactId ?? ""),
             "x-proxy-artifact-hash": String(delivery.artifactHash ?? ""),
-            "x-proxy-order-key": String(delivery.orderKey ?? ""),
+            "x-proxy-order-key": headerSafeValue(delivery.orderKey ?? ""),
             "x-proxy-timestamp": timestamp,
-            "x-proxy-signature": signature
+            "x-proxy-signature": signatureHeader,
+            "x-settld-timestamp": timestamp,
+            "x-settld-signature": signatureHeader
           },
           body
         },
@@ -265,7 +303,16 @@ export function createDeliveryWorker({
       );
     } catch (err) {
       const isTimeout = err?.name === "AbortError" || String(err?.message ?? "").toLowerCase().includes("timeout");
-      return { ok: false, status: null, error: isTimeout ? "timeout" : "network error", destinationType: "webhook", failureReason: isTimeout ? "timeout" : "network_error" };
+      const code = typeof err?.cause?.code === "string" ? err.cause.code : typeof err?.code === "string" ? err.code : null;
+      const msg = typeof err?.message === "string" && err.message.trim() ? err.message.trim() : String(err ?? "");
+      const detail = code ? `${code}: ${msg || "fetch failed"}` : msg || "fetch failed";
+      return {
+        ok: false,
+        status: null,
+        error: isTimeout ? "timeout" : `network error: ${detail}`,
+        destinationType: "webhook",
+        failureReason: isTimeout ? "timeout" : "network_error"
+      };
     }
 
     const ok = res.status >= 200 && res.status < 300;
@@ -325,6 +372,14 @@ export function createDeliveryWorker({
                 attempts
               });
               if (result.ok) {
+                await recordWebhookEndpointDeliveryResult({
+                  tenantId: t,
+                  destinationId: String(delivery.destinationId ?? ""),
+                  deliveredAt: nowIso(),
+                  success: true,
+                  failureReason: null,
+                  statusCode: result.status ?? null
+                });
                 const expiresAt = expiresAtForState({ tenantId: t, state: "delivered", at: nowIso() });
                 await store.updateDeliveryAttempt({
                   tenantId: t,
@@ -350,6 +405,14 @@ export function createDeliveryWorker({
                 continue;
               }
 
+              await recordWebhookEndpointDeliveryResult({
+                tenantId: t,
+                destinationId: String(delivery.destinationId ?? ""),
+                deliveredAt: nowIso(),
+                success: false,
+                failureReason: result.failureReason ?? result.error ?? "failed",
+                statusCode: result.status ?? null
+              });
               if (attempts >= maxAttempts) {
                 const expiresAt = expiresAtForState({ tenantId: t, state: "failed", at: nowIso() });
                 await store.updateDeliveryAttempt({
@@ -413,6 +476,14 @@ export function createDeliveryWorker({
               processed.push({ id: delivery.id, status: "retrying", nextAttemptAt });
             } catch (err) {
               const lastError = typeof err?.message === "string" && err.message.trim() ? err.message : String(err ?? "delivery failed");
+              await recordWebhookEndpointDeliveryResult({
+                tenantId: t,
+                destinationId: String(delivery.destinationId ?? ""),
+                deliveredAt: nowIso(),
+                success: false,
+                failureReason: "exception",
+                statusCode: null
+              });
               try {
                 store.metrics?.incCounter?.("delivery_attempt_total", { destinationType: "unknown" }, 1);
               } catch {}
@@ -521,6 +592,14 @@ export function createDeliveryWorker({
 	          attempts
 	        });
 	        if (result.ok) {
+	          await recordWebhookEndpointDeliveryResult({
+	            tenantId: t,
+	            destinationId: String(d.destinationId ?? ""),
+	            deliveredAt: nowIso(),
+	            success: true,
+	            failureReason: null,
+	            statusCode: result.status ?? null
+	          });
 	          d.state = "delivered";
 	          d.deliveredAt = nowIso();
           d.expiresAt = expiresAtForState({ tenantId: t, state: "delivered", at: d.deliveredAt });
@@ -541,6 +620,14 @@ export function createDeliveryWorker({
 	          continue;
 	        }
 
+	        await recordWebhookEndpointDeliveryResult({
+	          tenantId: t,
+	          destinationId: String(d.destinationId ?? ""),
+	          deliveredAt: nowIso(),
+	          success: false,
+	          failureReason: result.failureReason ?? result.error ?? "failed",
+	          statusCode: result.status ?? null
+	        });
 	        d.lastStatus = result.status;
 	        d.lastError = result.error;
 	        if (attempts >= maxAttempts) {
@@ -592,6 +679,14 @@ export function createDeliveryWorker({
 	        store.deliveries.set(key, d);
 	      } catch (err) {
 	        d.lastError = typeof err?.message === "string" ? err.message : String(err);
+	        await recordWebhookEndpointDeliveryResult({
+	          tenantId: t,
+	          destinationId: String(d.destinationId ?? ""),
+	          deliveredAt: nowIso(),
+	          success: false,
+	          failureReason: "exception",
+	          statusCode: null
+	        });
 	        try {
 	          store.metrics?.incCounter?.("delivery_attempt_total", { destinationType: "unknown" }, 1);
 	        } catch {}

package/src/api/workers/insolvency-sweep.js

@@ -0,0 +1,159 @@
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "../../core/tenancy.js";
+
+function assertPositiveSafeInt(value, fieldName) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${fieldName} must be a positive safe integer`);
+  }
+}
+
+function normalizeTenantIds(input) {
+  if (!Array.isArray(input)) return [];
+  const out = [];
+  const seen = new Set();
+  for (const raw of input) {
+    const tenantId = normalizeTenantId(raw ?? DEFAULT_TENANT_ID);
+    if (seen.has(tenantId)) continue;
+    seen.add(tenantId);
+    out.push(tenantId);
+  }
+  out.sort((left, right) => String(left).localeCompare(String(right)));
+  return out;
+}
+
+async function collectActiveAgentsForTenant({
+  tenantId,
+  listActiveAgents,
+  batchSize,
+  maxAgents
+}) {
+  const agents = [];
+  let offset = 0;
+  while (agents.length < maxAgents) {
+    const remaining = maxAgents - agents.length;
+    const pageLimit = Math.max(1, Math.min(batchSize, remaining));
+    const page = await listActiveAgents({
+      tenantId,
+      status: "active",
+      limit: pageLimit,
+      offset
+    });
+    const rows = Array.isArray(page) ? page : [];
+    if (rows.length === 0) break;
+    agents.push(...rows);
+    if (rows.length < pageLimit) break;
+    offset += rows.length;
+  }
+  return agents;
+}
+
+export function createInsolvencySweepWorker({
+  nowIso,
+  listTenantIds,
+  listActiveAgents,
+  evaluateAgent,
+  freezeAgent
+} = {}) {
+  if (typeof nowIso !== "function") throw new TypeError("nowIso is required");
+  if (typeof listTenantIds !== "function") throw new TypeError("listTenantIds is required");
+  if (typeof listActiveAgents !== "function") throw new TypeError("listActiveAgents is required");
+  if (typeof evaluateAgent !== "function") throw new TypeError("evaluateAgent is required");
+  if (typeof freezeAgent !== "function") throw new TypeError("freezeAgent is required");
+
+  async function tickInsolvencySweep({
+    tenantId = null,
+    maxTenants = 50,
+    maxMessages = 100,
+    batchSize = 100
+  } = {}) {
+    assertPositiveSafeInt(maxTenants, "maxTenants");
+    assertPositiveSafeInt(maxMessages, "maxMessages");
+    assertPositiveSafeInt(batchSize, "batchSize");
+
+    const tenantIds = normalizeTenantIds(await listTenantIds({ tenantId, maxTenants }));
+    const startedAt = nowIso();
+    let scanned = 0;
+    let processed = 0;
+    let frozen = 0;
+    let skipped = 0;
+    let failures = 0;
+    const outcomes = [];
+
+    for (const currentTenantId of tenantIds) {
+      if (processed >= maxMessages) break;
+      const remaining = maxMessages - processed;
+      const activeAgents = await collectActiveAgentsForTenant({
+        tenantId: currentTenantId,
+        listActiveAgents,
+        batchSize,
+        maxAgents: remaining
+      });
+
+      for (const identity of activeAgents) {
+        if (processed >= maxMessages) break;
+        const agentId = typeof identity?.agentId === "string" ? identity.agentId.trim() : "";
+        if (!agentId) continue;
+        scanned += 1;
+        processed += 1;
+
+        try {
+          const evaluation = await evaluateAgent({
+            tenantId: currentTenantId,
+            identity,
+            nowAt: startedAt
+          });
+          if (!(evaluation?.insolvent === true)) {
+            skipped += 1;
+            outcomes.push({
+              tenantId: currentTenantId,
+              agentId,
+              action: "skipped",
+              reasonCode: evaluation?.reasonCode ?? null
+            });
+            continue;
+          }
+
+          const freezeResult = await freezeAgent({
+            tenantId: currentTenantId,
+            identity,
+            evaluation,
+            nowAt: startedAt
+          });
+          if (freezeResult?.changed === true) frozen += 1;
+          else skipped += 1;
+          outcomes.push({
+            tenantId: currentTenantId,
+            agentId,
+            action: freezeResult?.changed === true ? "frozen" : "noop",
+            reasonCode: evaluation?.reasonCode ?? null,
+            lifecycleStatus: freezeResult?.lifecycle?.status ?? null
+          });
+        } catch (err) {
+          failures += 1;
+          outcomes.push({
+            tenantId: currentTenantId,
+            agentId,
+            action: "error",
+            code: err?.code ?? null,
+            message: err?.message ?? String(err ?? "")
+          });
+        }
+      }
+    }
+
+    return {
+      ok: true,
+      startedAt,
+      tenantCount: tenantIds.length,
+      scanned,
+      processed,
+      frozen,
+      skipped,
+      failures,
+      outcomes
+    };
+  }
+
+  return {
+    tickInsolvencySweep
+  };
+}

package/src/core/agent-card.js

@@ -0,0 +1,69 @@
+import { normalizeForCanonicalJson } from "./canonical-json.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function normalizeBaseUrl(value) {
+  assertNonEmptyString(value, "baseUrl");
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch {
+    throw new TypeError("baseUrl must be an absolute URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new TypeError("baseUrl must use http or https");
+  }
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+export function buildSettldAgentCard({
+  baseUrl,
+  version = null,
+  protocols = ["SettlementKernel.v1"],
+  bundleTypes = ["InvoiceBundle.v1", "ClosePack.v1", "JobProofBundle.v1", "MonthProofBundle.v1", "FinancePackBundle.v1"],
+  paymentRails = ["internal_escrow", "circle_usdc"],
+  disputeSupport = true,
+  reputationQueries = true
+} = {}) {
+  const url = normalizeBaseUrl(baseUrl);
+  const resolvedVersion = version === null || version === undefined || String(version).trim() === "" ? null : String(version).trim();
+  const resolvedProtocols = Array.isArray(protocols) ? protocols.map((p) => String(p)).filter(Boolean) : [];
+  const resolvedBundles = Array.isArray(bundleTypes) ? bundleTypes.map((b) => String(b)).filter(Boolean) : [];
+  const resolvedRails = Array.isArray(paymentRails) ? paymentRails.map((r) => String(r)).filter(Boolean) : [];
+
+  const card = {
+    name: "settld-settlement-agent",
+    description: "Settlement kernel for autonomous economic agreements (agreement -> evidence -> decision -> receipt -> dispute).",
+    url,
+    version: resolvedVersion,
+    capabilities: {
+      settlement: {
+        protocols: resolvedProtocols,
+        bundleTypes: resolvedBundles,
+        paymentRails: resolvedRails,
+        disputeSupport: disputeSupport === true,
+        reputationQueries: reputationQueries === true
+      }
+    },
+    skills: [
+      { id: "create_agreement", description: "Create an agreement/run for a payable capability call." },
+      { id: "submit_evidence", description: "Append evidence to a run event chain." },
+      { id: "settle_run", description: "Mark a run completed/failed (triggers settlement evaluation)." },
+      { id: "resolve_settlement", description: "Manually resolve a settlement (released/refunded)." },
+      { id: "open_dispute", description: "Open a dispute within the dispute window." },
+      { id: "query_reputation", description: "Query append-only reputation facts for a counterparty." }
+    ],
+    authentication: {
+      schemes: [
+        { type: "api_key", in: "header", name: "x-api-key" },
+        { type: "ops_token", in: "header", name: "x-proxy-ops-token" }
+      ]
+    }
+  };
+
+  // Omit null version for cleaner discovery payloads.
+  if (card.version === null) delete card.version;
+  return normalizeForCanonicalJson(card, { path: "$" });
+}

package/src/core/agent-wallets.js

@@ -188,6 +188,37 @@ function normalizeDisputeResolution(disputeResolution, { name = "settlement.disp
   const closedAtRaw = disputeResolution.closedAt ?? defaultClosedAt ?? null;
   const closedAt = closedAtRaw === null || closedAtRaw === undefined ? null : String(closedAtRaw).trim();
   if (closedAt !== null) assertIsoDate(closedAt, `${name}.closedAt`);
+  const releaseRatePctRaw = disputeResolution.releaseRatePct;
+  const releaseRatePct =
+    releaseRatePctRaw === null || releaseRatePctRaw === undefined || releaseRatePctRaw === ""
+      ? null
+      : Number.isSafeInteger(Number(releaseRatePctRaw))
+        ? Number(releaseRatePctRaw)
+        : Number.NaN;
+  if (releaseRatePct !== null && (!Number.isSafeInteger(releaseRatePct) || releaseRatePct < 0 || releaseRatePct > 100)) {
+    throw new TypeError(`${name}.releaseRatePct must be an integer within 0..100`);
+  }
+  if (outcome === AGENT_RUN_SETTLEMENT_DISPUTE_RESOLUTION_OUTCOME.ACCEPTED && releaseRatePct !== null && releaseRatePct !== 100) {
+    throw new TypeError(`${name}.releaseRatePct must be 100 when outcome=accepted`);
+  }
+  if (outcome === AGENT_RUN_SETTLEMENT_DISPUTE_RESOLUTION_OUTCOME.REJECTED && releaseRatePct !== null && releaseRatePct !== 0) {
+    throw new TypeError(`${name}.releaseRatePct must be 0 when outcome=rejected`);
+  }
+  if (outcome === AGENT_RUN_SETTLEMENT_DISPUTE_RESOLUTION_OUTCOME.PARTIAL) {
+    if (releaseRatePct === null) {
+      throw new TypeError(`${name}.releaseRatePct is required when outcome=partial`);
+    }
+    if (releaseRatePct <= 0 || releaseRatePct >= 100) {
+      throw new TypeError(`${name}.releaseRatePct must be within 1..99 when outcome=partial`);
+    }
+  }
+  if (
+    (outcome === AGENT_RUN_SETTLEMENT_DISPUTE_RESOLUTION_OUTCOME.WITHDRAWN ||
+      outcome === AGENT_RUN_SETTLEMENT_DISPUTE_RESOLUTION_OUTCOME.UNRESOLVED) &&
+    releaseRatePct !== null
+  ) {
+    throw new TypeError(`${name}.releaseRatePct is only allowed for accepted|rejected|partial outcomes`);
+  }
   const evidenceRefs = normalizeDisputeEvidenceRefs(disputeResolution.evidenceRefs, `${name}.evidenceRefs`);
   return {
     outcome,
@@ -195,6 +226,7 @@ function normalizeDisputeResolution(disputeResolution, { name = "settlement.disp
     closedByAgentId,
     summary,
     closedAt,
+    ...(releaseRatePct !== null ? { releaseRatePct } : {}),
     evidenceRefs
   };
 }
@@ -368,6 +400,39 @@ export function refundAgentWalletEscrow({ wallet, amountCents, at = new Date().t
   );
 }
 
+export function transferAgentWalletAvailable({ fromWallet, toWallet, amountCents, at = new Date().toISOString() }) {
+  assertIsoDate(at, "at");
+  assertAmountCents(amountCents, "amountCents");
+  const from = normalizeWalletRecord(fromWallet);
+  const to = normalizeWalletRecord(toWallet);
+  if (from.currency !== to.currency) throw new TypeError("wallet currencies must match");
+  if (from.tenantId !== to.tenantId) throw new TypeError("wallet tenants must match");
+  const debited = withWalletUpdate(
+    from,
+    (base) => {
+      if (base.availableCents < amountCents) {
+        const err = new Error("insufficient wallet balance");
+        err.code = "INSUFFICIENT_WALLET_BALANCE";
+        throw err;
+      }
+      return {
+        availableCents: base.availableCents - amountCents,
+        totalDebitedCents: base.totalDebitedCents + amountCents
+      };
+    },
+    { at }
+  );
+  const credited = withWalletUpdate(
+    to,
+    (base) => ({
+      availableCents: base.availableCents + amountCents,
+      totalCreditedCents: base.totalCreditedCents + amountCents
+    }),
+    { at }
+  );
+  return { fromWallet: debited, toWallet: credited };
+}
+
 export function validateAgentRunSettlementRequest(payload) {
   assertPlainObject(payload, "settlement");
   assertNonEmptyString(payload.payerAgentId, "settlement.payerAgentId");
@@ -704,6 +769,172 @@ export function resolveAgentRunSettlement({
   });
 }
 
+export function refundReleasedAgentRunSettlement({
+  settlement,
+  runStatus = "refunded",
+  decisionStatus = AGENT_RUN_SETTLEMENT_DECISION_STATUS.MANUAL_RESOLVED,
+  decisionMode = AGENT_RUN_SETTLEMENT_DECISION_MODE.MANUAL_REVIEW,
+  decisionPolicyHash = null,
+  decisionReason = "x402_refund_resolved",
+  decisionTrace = null,
+  resolutionEventId = null,
+  at = new Date().toISOString()
+}) {
+  const current = normalizeSettlementRecord(settlement);
+  if (current.status !== AGENT_RUN_SETTLEMENT_STATUS.RELEASED) {
+    throw new TypeError("refundReleasedAgentRunSettlement requires status=released");
+  }
+  assertNonEmptyString(runStatus, "runStatus");
+  assertIsoDate(at, "at");
+  if (resolutionEventId !== null && resolutionEventId !== undefined) assertNonEmptyString(resolutionEventId, "resolutionEventId");
+  const normalizedDecisionStatus = String(decisionStatus ?? AGENT_RUN_SETTLEMENT_DECISION_STATUS.MANUAL_RESOLVED).toLowerCase();
+  if (!Object.values(AGENT_RUN_SETTLEMENT_DECISION_STATUS).includes(normalizedDecisionStatus)) {
+    throw new TypeError("decisionStatus must be pending|auto_resolved|manual_review_required|manual_resolved");
+  }
+  const normalizedDecisionMode = String(decisionMode ?? AGENT_RUN_SETTLEMENT_DECISION_MODE.MANUAL_REVIEW).toLowerCase();
+  if (!Object.values(AGENT_RUN_SETTLEMENT_DECISION_MODE).includes(normalizedDecisionMode)) {
+    throw new TypeError("decisionMode must be automatic|manual-review");
+  }
+  const normalizedDecisionPolicyHash =
+    decisionPolicyHash === null || decisionPolicyHash === undefined ? null : String(decisionPolicyHash).trim();
+  if (normalizedDecisionPolicyHash !== null && normalizedDecisionPolicyHash === "") {
+    throw new TypeError("decisionPolicyHash must be a non-empty string when provided");
+  }
+  const normalizedDecisionReason = decisionReason === null || decisionReason === undefined ? null : String(decisionReason).trim();
+  if (normalizedDecisionReason !== null && normalizedDecisionReason === "") {
+    throw new TypeError("decisionReason must be a non-empty string when provided");
+  }
+  if (decisionTrace !== null && decisionTrace !== undefined) {
+    assertPlainObject(decisionTrace, "decisionTrace");
+  }
+  return normalizeSettlementRecord({
+    ...current,
+    status: AGENT_RUN_SETTLEMENT_STATUS.REFUNDED,
+    runStatus: String(runStatus),
+    releasedAmountCents: 0,
+    refundedAmountCents: current.amountCents,
+    releaseRatePct: 0,
+    disputeStatus: AGENT_RUN_SETTLEMENT_DISPUTE_STATUS.NONE,
+    disputeId: null,
+    disputeOpenedAt: null,
+    disputeClosedAt: null,
+    disputeContext: null,
+    disputeResolution: null,
+    decisionStatus: normalizedDecisionStatus,
+    decisionMode: normalizedDecisionMode,
+    decisionPolicyHash: normalizedDecisionPolicyHash,
+    decisionReason: normalizedDecisionReason,
+    decisionTrace: decisionTrace ?? current.decisionTrace ?? null,
+    decisionUpdatedAt: at,
+    resolvedAt: at,
+    resolutionEventId: resolutionEventId ?? current.resolutionEventId ?? null,
+    revision: current.revision + 1,
+    updatedAt: at
+  });
+}
+
+export function reconcileResolvedAgentRunSettlement({
+  settlement,
+  status,
+  runStatus = null,
+  releasedAmountCents = null,
+  refundedAmountCents = null,
+  releaseRatePct = null,
+  decisionStatus = AGENT_RUN_SETTLEMENT_DECISION_STATUS.MANUAL_RESOLVED,
+  decisionMode = AGENT_RUN_SETTLEMENT_DECISION_MODE.MANUAL_REVIEW,
+  decisionPolicyHash = null,
+  decisionReason = null,
+  decisionTrace = null,
+  resolutionEventId = null,
+  at = new Date().toISOString()
+}) {
+  const current = normalizeSettlementRecord(settlement);
+  if (current.status === AGENT_RUN_SETTLEMENT_STATUS.LOCKED) {
+    throw new TypeError("reconcileResolvedAgentRunSettlement requires a resolved settlement");
+  }
+  const nextStatus = String(status ?? "").toLowerCase();
+  if (nextStatus !== AGENT_RUN_SETTLEMENT_STATUS.RELEASED && nextStatus !== AGENT_RUN_SETTLEMENT_STATUS.REFUNDED) {
+    throw new TypeError("status must be released|refunded");
+  }
+  const nextRunStatusRaw = runStatus === null || runStatus === undefined ? current.runStatus : runStatus;
+  assertNonEmptyString(nextRunStatusRaw, "runStatus");
+  assertIsoDate(at, "at");
+  if (resolutionEventId !== null && resolutionEventId !== undefined) {
+    assertNonEmptyString(resolutionEventId, "resolutionEventId");
+  }
+
+  let nextReleasedAmountCents = releasedAmountCents === null || releasedAmountCents === undefined ? null : Number(releasedAmountCents);
+  let nextRefundedAmountCents = refundedAmountCents === null || refundedAmountCents === undefined ? null : Number(refundedAmountCents);
+  if (nextStatus === AGENT_RUN_SETTLEMENT_STATUS.RELEASED) {
+    if (nextReleasedAmountCents === null) nextReleasedAmountCents = current.amountCents;
+    if (nextRefundedAmountCents === null) nextRefundedAmountCents = current.amountCents - nextReleasedAmountCents;
+  } else {
+    if (nextReleasedAmountCents === null) nextReleasedAmountCents = 0;
+    if (nextRefundedAmountCents === null) nextRefundedAmountCents = current.amountCents;
+  }
+  assertAmountCents(nextReleasedAmountCents, "releasedAmountCents", { allowZero: true });
+  assertAmountCents(nextRefundedAmountCents, "refundedAmountCents", { allowZero: true });
+  if (nextReleasedAmountCents + nextRefundedAmountCents !== current.amountCents) {
+    throw new TypeError("releasedAmountCents + refundedAmountCents must equal settlement.amountCents");
+  }
+
+  const nextReleaseRatePct =
+    releaseRatePct === null || releaseRatePct === undefined
+      ? current.amountCents > 0
+        ? Math.round((nextReleasedAmountCents * 100) / current.amountCents)
+        : 0
+      : Number(releaseRatePct);
+  if (!Number.isSafeInteger(nextReleaseRatePct) || nextReleaseRatePct < 0 || nextReleaseRatePct > 100) {
+    throw new TypeError("releaseRatePct must be an integer within 0..100");
+  }
+
+  const normalizedDecisionStatus = String(decisionStatus ?? AGENT_RUN_SETTLEMENT_DECISION_STATUS.MANUAL_RESOLVED).toLowerCase();
+  if (!Object.values(AGENT_RUN_SETTLEMENT_DECISION_STATUS).includes(normalizedDecisionStatus)) {
+    throw new TypeError("decisionStatus must be pending|auto_resolved|manual_review_required|manual_resolved");
+  }
+  const normalizedDecisionMode = String(decisionMode ?? AGENT_RUN_SETTLEMENT_DECISION_MODE.MANUAL_REVIEW).toLowerCase();
+  if (!Object.values(AGENT_RUN_SETTLEMENT_DECISION_MODE).includes(normalizedDecisionMode)) {
+    throw new TypeError("decisionMode must be automatic|manual-review");
+  }
+  const normalizedDecisionPolicyHash =
+    decisionPolicyHash === null || decisionPolicyHash === undefined ? null : String(decisionPolicyHash).trim();
+  if (normalizedDecisionPolicyHash !== null && normalizedDecisionPolicyHash === "") {
+    throw new TypeError("decisionPolicyHash must be a non-empty string when provided");
+  }
+  const normalizedDecisionReason = decisionReason === null || decisionReason === undefined ? null : String(decisionReason).trim();
+  if (normalizedDecisionReason !== null && normalizedDecisionReason === "") {
+    throw new TypeError("decisionReason must be a non-empty string when provided");
+  }
+  if (decisionTrace !== null && decisionTrace !== undefined) {
+    assertPlainObject(decisionTrace, "decisionTrace");
+  }
+
+  return normalizeSettlementRecord({
+    ...current,
+    status: nextStatus,
+    runStatus: String(nextRunStatusRaw),
+    releasedAmountCents: nextReleasedAmountCents,
+    refundedAmountCents: nextRefundedAmountCents,
+    releaseRatePct: nextReleaseRatePct,
+    disputeStatus: AGENT_RUN_SETTLEMENT_DISPUTE_STATUS.NONE,
+    disputeId: null,
+    disputeOpenedAt: null,
+    disputeClosedAt: null,
+    disputeContext: null,
+    disputeResolution: null,
+    decisionStatus: normalizedDecisionStatus,
+    decisionMode: normalizedDecisionMode,
+    decisionPolicyHash: normalizedDecisionPolicyHash,
+    decisionReason: normalizedDecisionReason,
+    decisionTrace: decisionTrace ?? current.decisionTrace ?? null,
+    decisionUpdatedAt: at,
+    resolvedAt: at,
+    resolutionEventId: resolutionEventId ?? current.resolutionEventId ?? null,
+    revision: current.revision + 1,
+    updatedAt: at
+  });
+}
+
 export function updateAgentRunSettlementDecision({
   settlement,
   decisionStatus = null,