settld 0.1.0

package/src/core/agent-reputation.js

@@ -0,0 +1,311 @@
+export const AGENT_REPUTATION_SCHEMA_VERSION = "AgentReputation.v1";
+export const AGENT_REPUTATION_V2_SCHEMA_VERSION = "AgentReputation.v2";
+export const AGENT_REPUTATION_WINDOW = Object.freeze({
+  SEVEN_DAYS: "7d",
+  THIRTY_DAYS: "30d",
+  ALL_TIME: "allTime"
+});
+
+const WINDOW_DURATION_MS = Object.freeze({
+  [AGENT_REPUTATION_WINDOW.SEVEN_DAYS]: 7 * 24 * 60 * 60 * 1000,
+  [AGENT_REPUTATION_WINDOW.THIRTY_DAYS]: 30 * 24 * 60 * 60 * 1000,
+  [AGENT_REPUTATION_WINDOW.ALL_TIME]: null
+});
+
+export const AGENT_REPUTATION_RISK_TIER = Object.freeze({
+  LOW: "low",
+  GUARDED: "guarded",
+  ELEVATED: "elevated",
+  HIGH: "high"
+});
+
+const RUN_STATUS = Object.freeze({
+  CREATED: "created",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed"
+});
+
+const SETTLEMENT_STATUS = Object.freeze({
+  LOCKED: "locked",
+  RELEASED: "released",
+  REFUNDED: "refunded"
+});
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function clampInt(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  const rounded = Math.round(value);
+  if (rounded < min) return min;
+  if (rounded > max) return max;
+  return rounded;
+}
+
+function ratioPct(numerator, denominator) {
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator) || denominator <= 0) return null;
+  return clampInt((numerator * 100) / denominator, 0, 100);
+}
+
+function inferRiskTier(trustScore) {
+  if (trustScore >= 90) return AGENT_REPUTATION_RISK_TIER.LOW;
+  if (trustScore >= 75) return AGENT_REPUTATION_RISK_TIER.GUARDED;
+  if (trustScore >= 50) return AGENT_REPUTATION_RISK_TIER.ELEVATED;
+  return AGENT_REPUTATION_RISK_TIER.HIGH;
+}
+
+function parseAtMs(at) {
+  assertIsoDate(at, "at");
+  const ms = Date.parse(at);
+  if (!Number.isFinite(ms)) throw new TypeError("at must be an ISO date string");
+  return ms;
+}
+
+function normalizeWindow(window) {
+  const raw = typeof window === "string" ? window.trim() : "";
+  const value = raw || AGENT_REPUTATION_WINDOW.THIRTY_DAYS;
+  if (!Object.values(AGENT_REPUTATION_WINDOW).includes(value)) {
+    throw new TypeError("window must be one of 7d|30d|allTime");
+  }
+  return value;
+}
+
+function runObservationAtMs(run) {
+  const status = String(run?.status ?? "").toLowerCase();
+  const terminalAt = status === RUN_STATUS.COMPLETED ? run?.completedAt : status === RUN_STATUS.FAILED ? run?.failedAt : null;
+  const candidate = terminalAt ?? run?.updatedAt ?? run?.startedAt ?? run?.createdAt ?? null;
+  const parsed = candidate ? Date.parse(String(candidate)) : NaN;
+  return Number.isFinite(parsed) ? parsed : NaN;
+}
+
+function settlementObservationAtMs(settlement) {
+  const status = String(settlement?.status ?? "").toLowerCase();
+  const candidate = status === SETTLEMENT_STATUS.LOCKED ? settlement?.lockedAt : settlement?.resolvedAt ?? settlement?.lockedAt;
+  const parsed = candidate ? Date.parse(String(candidate)) : NaN;
+  return Number.isFinite(parsed) ? parsed : NaN;
+}
+
+function shouldIncludeByWindow({ observedAtMs, cutoffMs }) {
+  if (cutoffMs === null) return true;
+  if (!Number.isFinite(observedAtMs)) return false;
+  return observedAtMs >= cutoffMs;
+}
+
+function computeReputationSummary({
+  tenantId,
+  agentId,
+  runs = [],
+  settlements = [],
+  cutoffMs = null
+} = {}) {
+  const normalizedTenantId = String(tenantId);
+  const normalizedAgentId = String(agentId);
+  const runRows = Array.isArray(runs) ? runs : [];
+  const settlementRows = Array.isArray(settlements) ? settlements : [];
+
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(agentId, "agentId");
+
+  let totalRuns = 0;
+  let createdRuns = 0;
+  let runningRuns = 0;
+  let completedRuns = 0;
+  let failedRuns = 0;
+  let runsWithEvidence = 0;
+  let durationSumMs = 0;
+  let durationCount = 0;
+
+  for (const row of runRows) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (String(row.tenantId ?? "") !== normalizedTenantId) continue;
+    if (String(row.agentId ?? "") !== normalizedAgentId) continue;
+    const observedAtMs = runObservationAtMs(row);
+    if (!shouldIncludeByWindow({ observedAtMs, cutoffMs })) continue;
+
+    totalRuns += 1;
+    const status = String(row.status ?? "").toLowerCase();
+    if (status === RUN_STATUS.CREATED) createdRuns += 1;
+    else if (status === RUN_STATUS.RUNNING) runningRuns += 1;
+    else if (status === RUN_STATUS.COMPLETED) completedRuns += 1;
+    else if (status === RUN_STATUS.FAILED) failedRuns += 1;
+
+    const evidenceRefs = Array.isArray(row.evidenceRefs) ? row.evidenceRefs.filter((value) => typeof value === "string" && value.trim() !== "") : [];
+    if (evidenceRefs.length > 0) runsWithEvidence += 1;
+
+    const startedMs = row.startedAt ? Date.parse(String(row.startedAt)) : NaN;
+    const endedMs =
+      status === RUN_STATUS.COMPLETED
+        ? Date.parse(String(row.completedAt ?? ""))
+        : status === RUN_STATUS.FAILED
+          ? Date.parse(String(row.failedAt ?? ""))
+          : NaN;
+    if (Number.isFinite(startedMs) && Number.isFinite(endedMs) && endedMs >= startedMs) {
+      durationSumMs += Math.floor(endedMs - startedMs);
+      durationCount += 1;
+    }
+  }
+
+  let lockedSettlements = 0;
+  let releasedSettlements = 0;
+  let refundedSettlements = 0;
+
+  for (const row of settlementRows) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+    if (String(row.tenantId ?? "") !== normalizedTenantId) continue;
+    if (String(row.agentId ?? "") !== normalizedAgentId) continue;
+    const observedAtMs = settlementObservationAtMs(row);
+    if (!shouldIncludeByWindow({ observedAtMs, cutoffMs })) continue;
+
+    const status = String(row.status ?? "").toLowerCase();
+    if (status === SETTLEMENT_STATUS.LOCKED) lockedSettlements += 1;
+    else if (status === SETTLEMENT_STATUS.RELEASED) releasedSettlements += 1;
+    else if (status === SETTLEMENT_STATUS.REFUNDED) refundedSettlements += 1;
+  }
+
+  const terminalRuns = completedRuns + failedRuns;
+  const resolvedSettlements = releasedSettlements + refundedSettlements;
+  const totalSettlements = lockedSettlements + resolvedSettlements;
+
+  const runCompletionRatePct = ratioPct(completedRuns, terminalRuns);
+  const evidenceCoverageRatePct = ratioPct(runsWithEvidence, terminalRuns);
+  const settlementReleaseRatePct = ratioPct(releasedSettlements, resolvedSettlements);
+  const activityScore = clampInt((Math.min(totalRuns, 50) * 100) / 50, 0, 100);
+  const runQuality = runCompletionRatePct ?? 50;
+  const settlementQuality = settlementReleaseRatePct ?? runQuality;
+  const evidenceQuality = evidenceCoverageRatePct ?? 50;
+  const trustScore = clampInt((runQuality * 55 + settlementQuality * 30 + evidenceQuality * 10 + activityScore * 5) / 100, 0, 100);
+
+  return {
+    trustScore,
+    riskTier: inferRiskTier(trustScore),
+    totalRuns,
+    terminalRuns,
+    createdRuns,
+    runningRuns,
+    completedRuns,
+    failedRuns,
+    runsWithEvidence,
+    totalSettlements,
+    lockedSettlements,
+    releasedSettlements,
+    refundedSettlements,
+    runCompletionRatePct,
+    evidenceCoverageRatePct,
+    settlementReleaseRatePct,
+    avgRunDurationMs: durationCount > 0 ? Math.floor(durationSumMs / durationCount) : null,
+    scoreBreakdown: {
+      runQuality,
+      settlementQuality,
+      evidenceQuality,
+      activityScore
+    }
+  };
+}
+
+function createReputationWindowSnapshot({ summary, computedAt }) {
+  return {
+    trustScore: summary.trustScore,
+    riskTier: summary.riskTier,
+    totalRuns: summary.totalRuns,
+    terminalRuns: summary.terminalRuns,
+    createdRuns: summary.createdRuns,
+    runningRuns: summary.runningRuns,
+    completedRuns: summary.completedRuns,
+    failedRuns: summary.failedRuns,
+    runsWithEvidence: summary.runsWithEvidence,
+    totalSettlements: summary.totalSettlements,
+    lockedSettlements: summary.lockedSettlements,
+    releasedSettlements: summary.releasedSettlements,
+    refundedSettlements: summary.refundedSettlements,
+    runCompletionRatePct: summary.runCompletionRatePct,
+    evidenceCoverageRatePct: summary.evidenceCoverageRatePct,
+    settlementReleaseRatePct: summary.settlementReleaseRatePct,
+    avgRunDurationMs: summary.avgRunDurationMs,
+    scoreBreakdown: summary.scoreBreakdown,
+    computedAt
+  };
+}
+
+export function computeAgentReputation({ tenantId, agentId, runs = [], settlements = [], at = new Date().toISOString() } = {}) {
+  assertIsoDate(at, "at");
+  const summary = computeReputationSummary({ tenantId, agentId, runs, settlements, cutoffMs: null });
+  const reputation = {
+    schemaVersion: AGENT_REPUTATION_SCHEMA_VERSION,
+    agentId: String(agentId),
+    tenantId: String(tenantId),
+    trustScore: summary.trustScore,
+    riskTier: summary.riskTier,
+    totalRuns: summary.totalRuns,
+    terminalRuns: summary.terminalRuns,
+    createdRuns: summary.createdRuns,
+    runningRuns: summary.runningRuns,
+    completedRuns: summary.completedRuns,
+    failedRuns: summary.failedRuns,
+    runsWithEvidence: summary.runsWithEvidence,
+    totalSettlements: summary.totalSettlements,
+    lockedSettlements: summary.lockedSettlements,
+    releasedSettlements: summary.releasedSettlements,
+    refundedSettlements: summary.refundedSettlements,
+    runCompletionRatePct: summary.runCompletionRatePct,
+    evidenceCoverageRatePct: summary.evidenceCoverageRatePct,
+    settlementReleaseRatePct: summary.settlementReleaseRatePct,
+    avgRunDurationMs: summary.avgRunDurationMs,
+    scoreBreakdown: summary.scoreBreakdown,
+    computedAt: at
+  };
+  assertPlainObject(reputation, "reputation");
+  return reputation;
+}
+
+export function computeAgentReputationV2({
+  tenantId,
+  agentId,
+  runs = [],
+  settlements = [],
+  at = new Date().toISOString(),
+  primaryWindow = AGENT_REPUTATION_WINDOW.THIRTY_DAYS
+} = {}) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(agentId, "agentId");
+  const nowMs = parseAtMs(at);
+  const resolvedPrimaryWindow = normalizeWindow(primaryWindow);
+
+  const windows = {};
+  for (const [window, durationMs] of Object.entries(WINDOW_DURATION_MS)) {
+    const cutoffMs = durationMs === null ? null : nowMs - durationMs;
+    const summary = computeReputationSummary({ tenantId, agentId, runs, settlements, cutoffMs });
+    windows[window] = createReputationWindowSnapshot({ summary, computedAt: at });
+  }
+
+  const primary = windows[resolvedPrimaryWindow];
+  const reputation = {
+    schemaVersion: AGENT_REPUTATION_V2_SCHEMA_VERSION,
+    agentId: String(agentId),
+    tenantId: String(tenantId),
+    primaryWindow: resolvedPrimaryWindow,
+    trustScore: primary.trustScore,
+    riskTier: primary.riskTier,
+    windows: {
+      [AGENT_REPUTATION_WINDOW.SEVEN_DAYS]: windows[AGENT_REPUTATION_WINDOW.SEVEN_DAYS],
+      [AGENT_REPUTATION_WINDOW.THIRTY_DAYS]: windows[AGENT_REPUTATION_WINDOW.THIRTY_DAYS],
+      [AGENT_REPUTATION_WINDOW.ALL_TIME]: windows[AGENT_REPUTATION_WINDOW.ALL_TIME]
+    },
+    computedAt: at
+  };
+  assertPlainObject(reputation, "reputation");
+  return reputation;
+}

package/src/core/agent-runs.js

@@ -0,0 +1,253 @@
+export const AGENT_RUN_SCHEMA_VERSION = "AgentRun.v1";
+export const AGENT_RUN_EVENT_SCHEMA_VERSION = "AgentEvent.v1";
+
+export const AGENT_RUN_STATUS = Object.freeze({
+  CREATED: "created",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed"
+});
+
+export const AGENT_RUN_EVENT_TYPE = Object.freeze({
+  RUN_CREATED: "RUN_CREATED",
+  RUN_STARTED: "RUN_STARTED",
+  RUN_HEARTBEAT: "RUN_HEARTBEAT",
+  EVIDENCE_ADDED: "EVIDENCE_ADDED",
+  RUN_COMPLETED: "RUN_COMPLETED",
+  RUN_FAILED: "RUN_FAILED"
+});
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function assertOptionalString(value, name) {
+  if (value === undefined || value === null) return;
+  assertNonEmptyString(value, name);
+}
+
+export function validateRunCreatedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  assertNonEmptyString(payload.agentId, "payload.agentId");
+  assertNonEmptyString(payload.tenantId, "payload.tenantId");
+  assertOptionalString(payload.taskType, "payload.taskType");
+  assertOptionalString(payload.inputRef, "payload.inputRef");
+  return payload;
+}
+
+export function validateRunStartedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  assertOptionalString(payload.startedBy, "payload.startedBy");
+  return payload;
+}
+
+export function validateRunHeartbeatPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  if (payload.progressPct !== undefined && payload.progressPct !== null) {
+    if (!Number.isFinite(payload.progressPct)) throw new TypeError("payload.progressPct must be a finite number");
+    if (payload.progressPct < 0 || payload.progressPct > 100) throw new TypeError("payload.progressPct must be within 0..100");
+  }
+  assertOptionalString(payload.stage, "payload.stage");
+  return payload;
+}
+
+export function validateEvidenceAddedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  assertNonEmptyString(payload.evidenceRef, "payload.evidenceRef");
+  return payload;
+}
+
+export function validateRunCompletedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  assertOptionalString(payload.outputRef, "payload.outputRef");
+  if (payload.metrics !== undefined && payload.metrics !== null) assertPlainObject(payload.metrics, "payload.metrics");
+  return payload;
+}
+
+export function validateRunFailedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  assertNonEmptyString(payload.runId, "payload.runId");
+  assertOptionalString(payload.code, "payload.code");
+  assertOptionalString(payload.message, "payload.message");
+  return payload;
+}
+
+function validatePayloadForType(type, payload) {
+  if (type === AGENT_RUN_EVENT_TYPE.RUN_CREATED) return validateRunCreatedPayload(payload);
+  if (type === AGENT_RUN_EVENT_TYPE.RUN_STARTED) return validateRunStartedPayload(payload);
+  if (type === AGENT_RUN_EVENT_TYPE.RUN_HEARTBEAT) return validateRunHeartbeatPayload(payload);
+  if (type === AGENT_RUN_EVENT_TYPE.EVIDENCE_ADDED) return validateEvidenceAddedPayload(payload);
+  if (type === AGENT_RUN_EVENT_TYPE.RUN_COMPLETED) return validateRunCompletedPayload(payload);
+  if (type === AGENT_RUN_EVENT_TYPE.RUN_FAILED) return validateRunFailedPayload(payload);
+  throw new TypeError(`unsupported agent run event type: ${type}`);
+}
+
+function isTerminalStatus(status) {
+  return status === AGENT_RUN_STATUS.COMPLETED || status === AGENT_RUN_STATUS.FAILED;
+}
+
+export function reduceAgentRun(events) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  if (events.length === 0) return null;
+
+  let run = null;
+  let revision = 0;
+
+  for (const event of events) {
+    if (!event || typeof event !== "object" || Array.isArray(event)) throw new TypeError("event must be an object");
+    assertNonEmptyString(event.type, "event.type");
+    assertNonEmptyString(event.streamId, "event.streamId");
+    assertIsoDate(event.at, "event.at");
+    const payload = event.payload ?? {};
+    validatePayloadForType(event.type, payload);
+
+    if (event.type === AGENT_RUN_EVENT_TYPE.RUN_CREATED) {
+      if (run) throw new TypeError("run stream already initialized");
+      if (payload.runId !== event.streamId) throw new TypeError("payload.runId must match streamId");
+      run = {
+        schemaVersion: AGENT_RUN_SCHEMA_VERSION,
+        runId: payload.runId,
+        agentId: payload.agentId,
+        tenantId: payload.tenantId,
+        taskType: payload.taskType ?? null,
+        inputRef: payload.inputRef ?? null,
+        status: AGENT_RUN_STATUS.CREATED,
+        evidenceRefs: [],
+        metrics: null,
+        failure: null,
+        startedAt: null,
+        completedAt: null,
+        failedAt: null,
+        revision,
+        createdAt: event.at,
+        updatedAt: event.at,
+        lastEventId: event.id ?? null,
+        lastChainHash: event.chainHash ?? null
+      };
+      continue;
+    }
+
+    if (!run) throw new TypeError("run stream is missing RUN_CREATED");
+    if (payload.runId && payload.runId !== run.runId) throw new TypeError("payload.runId must match runId");
+
+    if (event.type === AGENT_RUN_EVENT_TYPE.RUN_STARTED) {
+      if (isTerminalStatus(run.status)) throw new TypeError("cannot start a terminal run");
+      run.status = AGENT_RUN_STATUS.RUNNING;
+      run.startedAt = run.startedAt ?? event.at;
+    } else if (event.type === AGENT_RUN_EVENT_TYPE.RUN_HEARTBEAT) {
+      if (run.status === AGENT_RUN_STATUS.CREATED) {
+        run.status = AGENT_RUN_STATUS.RUNNING;
+        run.startedAt = run.startedAt ?? event.at;
+      }
+      if (isTerminalStatus(run.status)) throw new TypeError("cannot heartbeat a terminal run");
+    } else if (event.type === AGENT_RUN_EVENT_TYPE.EVIDENCE_ADDED) {
+      if (isTerminalStatus(run.status)) throw new TypeError("cannot append evidence to a terminal run");
+      const evidenceRef = String(payload.evidenceRef);
+      if (!run.evidenceRefs.includes(evidenceRef)) run.evidenceRefs.push(evidenceRef);
+      run.evidenceRefs.sort((a, b) => a.localeCompare(b));
+    } else if (event.type === AGENT_RUN_EVENT_TYPE.RUN_COMPLETED) {
+      if (isTerminalStatus(run.status)) throw new TypeError("run already terminal");
+      run.status = AGENT_RUN_STATUS.COMPLETED;
+      run.startedAt = run.startedAt ?? event.at;
+      run.completedAt = event.at;
+      run.failedAt = null;
+      run.failure = null;
+      run.metrics = payload.metrics && typeof payload.metrics === "object" && !Array.isArray(payload.metrics) ? { ...payload.metrics } : run.metrics;
+    } else if (event.type === AGENT_RUN_EVENT_TYPE.RUN_FAILED) {
+      if (isTerminalStatus(run.status)) throw new TypeError("run already terminal");
+      run.status = AGENT_RUN_STATUS.FAILED;
+      run.startedAt = run.startedAt ?? event.at;
+      run.failedAt = event.at;
+      run.completedAt = null;
+      run.failure = {
+        code: payload.code ?? null,
+        message: payload.message ?? null
+      };
+    } else {
+      throw new TypeError(`unsupported event type: ${event.type}`);
+    }
+
+    revision += 1;
+    run.revision = revision;
+    run.updatedAt = event.at;
+    run.lastEventId = event.id ?? run.lastEventId ?? null;
+    run.lastChainHash = event.chainHash ?? run.lastChainHash ?? null;
+  }
+
+  return run;
+}
+
+export function computeAgentRunVerification({ run, events = [] } = {}) {
+  if (!run || typeof run !== "object") {
+    return {
+      verificationStatus: "amber",
+      runStatus: null,
+      reasonCodes: ["RUN_NOT_FOUND"],
+      evidenceCount: 0,
+      eventCount: Array.isArray(events) ? events.length : 0,
+      durationMs: null,
+      settlementReleaseRatePct: null
+    };
+  }
+
+  const evidenceCount = Array.isArray(run.evidenceRefs) ? run.evidenceRefs.length : 0;
+  const startedMs = run.startedAt ? Date.parse(run.startedAt) : NaN;
+  const endMs = run.completedAt ? Date.parse(run.completedAt) : run.failedAt ? Date.parse(run.failedAt) : NaN;
+  const durationMs = Number.isFinite(startedMs) && Number.isFinite(endMs) && endMs >= startedMs ? Math.floor(endMs - startedMs) : null;
+
+  let verificationStatus = "amber";
+  const reasonCodes = [];
+  let settlementReleaseRatePct = null;
+  if (run.status === AGENT_RUN_STATUS.COMPLETED) {
+    const metricRateRaw = run?.metrics?.settlementReleaseRatePct;
+    const metricRate = Number(metricRateRaw);
+    const normalizedRate = Number.isSafeInteger(metricRate) && metricRate >= 0 && metricRate <= 100 ? metricRate : 100;
+    settlementReleaseRatePct = normalizedRate;
+    if (normalizedRate >= 100) {
+      verificationStatus = "green";
+    } else if (normalizedRate <= 0) {
+      verificationStatus = "red";
+      reasonCodes.push("RUN_COMPLETED_ZERO_SETTLEMENT");
+    } else {
+      verificationStatus = "amber";
+      reasonCodes.push("RUN_COMPLETED_PARTIAL_SETTLEMENT");
+    }
+  } else if (run.status === AGENT_RUN_STATUS.FAILED) {
+    verificationStatus = "red";
+    reasonCodes.push("RUN_FAILED");
+    if (typeof run.failure?.code === "string" && run.failure.code.trim() !== "") reasonCodes.push(`RUN_FAILED_${run.failure.code}`);
+    settlementReleaseRatePct = 0;
+  } else if (run.status === AGENT_RUN_STATUS.RUNNING) {
+    reasonCodes.push("RUN_IN_PROGRESS");
+  } else {
+    reasonCodes.push("RUN_CREATED_NOT_STARTED");
+  }
+
+  return {
+    verificationStatus,
+    runStatus: run.status ?? null,
+    reasonCodes,
+    evidenceCount,
+    eventCount: Array.isArray(events) ? events.length : 0,
+    durationMs,
+    settlementReleaseRatePct
+  };
+}