settld 0.1.2 → 0.2.0

package/src/core/agreement-delegation.js

@@ -0,0 +1,549 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const AGREEMENT_DELEGATION_SCHEMA_VERSION = "AgreementDelegation.v1";
+
+export const AGREEMENT_DELEGATION_STATUS = Object.freeze({
+  ACTIVE: "active",
+  SETTLED: "settled",
+  REVOKED: "revoked"
+});
+
+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, { allowNull = false } = {}) {
+  if (allowNull && (value === null || value === undefined)) return;
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function normalizeId(value, name, { min = 1, max = 200 } = {}) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim();
+  if (out.length < min || out.length > max) throw new TypeError(`${name} must be length ${min}..${max}`);
+  if (!/^[A-Za-z0-9:_-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:_-]+$`);
+  return out;
+}
+
+function normalizeHexHash(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value : "USD";
+  const out = raw.trim().toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(out)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9_]{2,11}$`);
+  return out;
+}
+
+function assertPositiveSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function assertNonNegativeSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function normalizeStatus(value, name) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!Object.values(AGREEMENT_DELEGATION_STATUS).includes(normalized)) {
+    throw new TypeError(`${name} must be one of: ${Object.values(AGREEMENT_DELEGATION_STATUS).join("|")}`);
+  }
+  return normalized;
+}
+
+function normalizeAncestorChain(value, { name = "ancestorChain", requiredDepth = null, expectedParentHash = null } = {}) {
+  if (value === null || value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new TypeError(`${name} must be an array`);
+  const out = [];
+  const seen = new Set();
+  for (let i = 0; i < value.length; i += 1) {
+    const h = normalizeHexHash(value[i], `${name}[${i}]`);
+    if (seen.has(h)) throw new TypeError(`${name} must not contain duplicates`);
+    seen.add(h);
+    out.push(h);
+  }
+  if (requiredDepth !== null && out.length !== requiredDepth) {
+    throw new TypeError(`${name} length must equal delegationDepth`);
+  }
+  if (expectedParentHash && out.length && out[out.length - 1] !== expectedParentHash) {
+    throw new TypeError(`${name} last element must equal parentAgreementHash`);
+  }
+  return out;
+}
+
+export function computeAgreementDelegationHashV1(delegationCore) {
+  assertPlainObject(delegationCore, "delegationCore");
+  const copy = { ...delegationCore };
+  delete copy.delegationHash;
+  delete copy.status;
+  delete copy.resolvedAt;
+  delete copy.updatedAt;
+  delete copy.revision;
+  delete copy.metadata;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildAgreementDelegationV1({
+  delegationId,
+  tenantId,
+  parentAgreementHash,
+  childAgreementHash,
+  delegatorAgentId,
+  delegateeAgentId,
+  budgetCapCents,
+  currency,
+  delegationDepth,
+  maxDelegationDepth,
+  ancestorChain,
+  createdAt
+} = {}) {
+  const at = createdAt ?? new Date().toISOString();
+  assertIsoDate(at, "createdAt");
+
+  const parentHash = normalizeHexHash(parentAgreementHash, "parentAgreementHash");
+  const depth = assertNonNegativeSafeInt(delegationDepth, "delegationDepth");
+  const normalizedAncestorChain = normalizeAncestorChain(ancestorChain, {
+    name: "ancestorChain",
+    requiredDepth: ancestorChain === undefined || ancestorChain === null ? null : depth,
+    expectedParentHash: parentHash
+  });
+
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: AGREEMENT_DELEGATION_SCHEMA_VERSION,
+      delegationId: normalizeId(delegationId, "delegationId", { min: 3, max: 240 }),
+      tenantId: normalizeId(tenantId, "tenantId", { min: 1, max: 128 }),
+      parentAgreementHash: parentHash,
+      childAgreementHash: normalizeHexHash(childAgreementHash, "childAgreementHash"),
+      delegatorAgentId: normalizeId(delegatorAgentId, "delegatorAgentId", { min: 3, max: 128 }),
+      delegateeAgentId: normalizeId(delegateeAgentId, "delegateeAgentId", { min: 3, max: 128 }),
+      budgetCapCents: assertPositiveSafeInt(budgetCapCents, "budgetCapCents"),
+      currency: normalizeCurrency(currency, "currency"),
+      delegationDepth: depth,
+      maxDelegationDepth: assertNonNegativeSafeInt(maxDelegationDepth, "maxDelegationDepth"),
+      createdAt: at,
+      ...(normalizedAncestorChain ? { ancestorChain: normalizedAncestorChain } : {})
+    },
+    { path: "$" }
+  );
+
+  if (normalized.delegationDepth > normalized.maxDelegationDepth) {
+    throw new TypeError("delegationDepth must be <= maxDelegationDepth");
+  }
+  if (normalized.parentAgreementHash === normalized.childAgreementHash) {
+    throw new TypeError("parentAgreementHash must differ from childAgreementHash");
+  }
+
+  const delegationHash = computeAgreementDelegationHashV1(normalized);
+  return normalizeForCanonicalJson(
+    {
+      ...normalized,
+      delegationHash,
+      status: AGREEMENT_DELEGATION_STATUS.ACTIVE,
+      revision: 0,
+      updatedAt: at
+    },
+    { path: "$" }
+  );
+}
+
+export function validateAgreementDelegationV1(delegation) {
+  assertPlainObject(delegation, "delegation");
+  if (delegation.schemaVersion !== AGREEMENT_DELEGATION_SCHEMA_VERSION) {
+    throw new TypeError(`delegation.schemaVersion must be ${AGREEMENT_DELEGATION_SCHEMA_VERSION}`);
+  }
+  normalizeId(delegation.delegationId, "delegation.delegationId", { min: 3, max: 240 });
+  normalizeId(delegation.tenantId, "delegation.tenantId", { min: 1, max: 128 });
+  const parentHash = normalizeHexHash(delegation.parentAgreementHash, "delegation.parentAgreementHash");
+  const childHash = normalizeHexHash(delegation.childAgreementHash, "delegation.childAgreementHash");
+  if (parentHash === childHash) throw new TypeError("delegation.parentAgreementHash must differ from delegation.childAgreementHash");
+  normalizeId(delegation.delegatorAgentId, "delegation.delegatorAgentId", { min: 3, max: 128 });
+  normalizeId(delegation.delegateeAgentId, "delegation.delegateeAgentId", { min: 3, max: 128 });
+  assertPositiveSafeInt(delegation.budgetCapCents, "delegation.budgetCapCents");
+  normalizeCurrency(delegation.currency, "delegation.currency");
+  const depth = assertNonNegativeSafeInt(delegation.delegationDepth, "delegation.delegationDepth");
+  const maxDepth = assertNonNegativeSafeInt(delegation.maxDelegationDepth, "delegation.maxDelegationDepth");
+  if (depth > maxDepth) throw new TypeError("delegation.delegationDepth must be <= delegation.maxDelegationDepth");
+  assertIsoDate(delegation.createdAt, "delegation.createdAt");
+  if (Object.prototype.hasOwnProperty.call(delegation, "ancestorChain")) {
+    normalizeAncestorChain(delegation.ancestorChain ?? null, {
+      name: "delegation.ancestorChain",
+      requiredDepth: delegation.ancestorChain === null ? null : depth,
+      expectedParentHash: parentHash
+    });
+  }
+  normalizeHexHash(delegation.delegationHash, "delegation.delegationHash");
+  normalizeStatus(delegation.status, "delegation.status");
+  const revision = Number(delegation.revision ?? 0);
+  if (!Number.isSafeInteger(revision) || revision < 0) throw new TypeError("delegation.revision must be a non-negative safe integer");
+  assertIsoDate(delegation.updatedAt, "delegation.updatedAt");
+  if (Object.prototype.hasOwnProperty.call(delegation, "resolvedAt")) {
+    assertIsoDate(delegation.resolvedAt ?? null, "delegation.resolvedAt", { allowNull: true });
+  }
+
+  const computed = computeAgreementDelegationHashV1(delegation);
+  if (computed !== String(delegation.delegationHash).toLowerCase()) throw new TypeError("delegationHash mismatch");
+  return true;
+}
+
+export function resolveAgreementDelegationV1({ delegation, status, resolvedAt = null, metadata = null } = {}) {
+  validateAgreementDelegationV1(delegation);
+  const nextStatus = normalizeStatus(status, "status");
+  const at = resolvedAt ?? new Date().toISOString();
+  assertIsoDate(at, "resolvedAt");
+  if (nextStatus === AGREEMENT_DELEGATION_STATUS.ACTIVE) throw new TypeError("cannot resolve delegation to active");
+  const currentStatus = String(delegation.status ?? "").toLowerCase();
+  if (currentStatus !== AGREEMENT_DELEGATION_STATUS.ACTIVE) return delegation;
+
+  const meta = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : null;
+  const next = {
+    ...delegation,
+    status: nextStatus,
+    resolvedAt: at,
+    revision: Number(delegation.revision ?? 0) + 1,
+    updatedAt: at
+  };
+  if (meta) next.metadata = normalizeForCanonicalJson(meta, { path: "$.metadata" });
+  return normalizeForCanonicalJson(next, { path: "$" });
+}
+
+function indexDelegations(delegations) {
+  const byChild = new Map();
+  const childrenByParent = new Map();
+  for (const d of Array.isArray(delegations) ? delegations : []) {
+    if (!d || typeof d !== "object" || Array.isArray(d)) continue;
+    const status = String(d.status ?? "").toLowerCase();
+    if (status === AGREEMENT_DELEGATION_STATUS.REVOKED) continue;
+    const parent = typeof d.parentAgreementHash === "string" ? d.parentAgreementHash.toLowerCase() : null;
+    const child = typeof d.childAgreementHash === "string" ? d.childAgreementHash.toLowerCase() : null;
+    if (!parent || !child) continue;
+
+    if (byChild.has(child) && byChild.get(child)?.parentAgreementHash !== parent) {
+      const err = new Error("multiple parents found for childAgreementHash");
+      err.code = "AGREEMENT_DELEGATION_MULTIPLE_PARENTS";
+      err.childAgreementHash = child;
+      throw err;
+    }
+    byChild.set(child, { delegationId: d.delegationId ?? null, parentAgreementHash: parent, childAgreementHash: child });
+
+    const list = childrenByParent.get(parent) ?? [];
+    list.push({ delegationId: d.delegationId ?? null, parentAgreementHash: parent, childAgreementHash: child });
+    childrenByParent.set(parent, list);
+  }
+  for (const [p, list] of childrenByParent.entries()) {
+    list.sort((a, b) => String(a.childAgreementHash).localeCompare(String(b.childAgreementHash)));
+    childrenByParent.set(p, list);
+  }
+  return { byChild, childrenByParent };
+}
+
+function indexDelegationsById(delegations) {
+  const byId = new Map();
+  for (const delegation of Array.isArray(delegations) ? delegations : []) {
+    if (!delegation || typeof delegation !== "object" || Array.isArray(delegation)) continue;
+    const delegationId = typeof delegation.delegationId === "string" ? delegation.delegationId.trim() : "";
+    if (!delegationId) continue;
+    if (byId.has(delegationId)) {
+      const err = new Error("duplicate delegationId in input set");
+      err.code = "AGREEMENT_DELEGATION_DUPLICATE_ID";
+      err.delegationId = delegationId;
+      throw err;
+    }
+    byId.set(delegationId, delegation);
+  }
+  return byId;
+}
+
+export function summarizeAgreementDelegationLedgerV1({ delegations } = {}) {
+  const summary = {
+    schemaVersion: "AgreementDelegationLedger.v1",
+    totalDelegations: 0,
+    activeCount: 0,
+    settledCount: 0,
+    revokedCount: 0,
+    terminalCount: 0,
+    unresolvedCount: 0,
+    countsByStatus: {
+      [AGREEMENT_DELEGATION_STATUS.ACTIVE]: 0,
+      [AGREEMENT_DELEGATION_STATUS.SETTLED]: 0,
+      [AGREEMENT_DELEGATION_STATUS.REVOKED]: 0
+    },
+    invariant: {
+      ok: true,
+      code: "AGREEMENT_DELEGATION_LEDGER_INVARIANT_OK",
+      message: "active+settled+revoked equals total"
+    }
+  };
+  for (const delegation of Array.isArray(delegations) ? delegations : []) {
+    if (!delegation || typeof delegation !== "object" || Array.isArray(delegation)) continue;
+    summary.totalDelegations += 1;
+    const status = String(delegation.status ?? "").trim().toLowerCase();
+    if (status === AGREEMENT_DELEGATION_STATUS.ACTIVE) {
+      summary.activeCount += 1;
+      summary.unresolvedCount += 1;
+      summary.countsByStatus[AGREEMENT_DELEGATION_STATUS.ACTIVE] += 1;
+    } else if (status === AGREEMENT_DELEGATION_STATUS.SETTLED) {
+      summary.settledCount += 1;
+      summary.terminalCount += 1;
+      summary.countsByStatus[AGREEMENT_DELEGATION_STATUS.SETTLED] += 1;
+    } else if (status === AGREEMENT_DELEGATION_STATUS.REVOKED) {
+      summary.revokedCount += 1;
+      summary.terminalCount += 1;
+      summary.countsByStatus[AGREEMENT_DELEGATION_STATUS.REVOKED] += 1;
+    } else {
+      summary.invariant = {
+        ok: false,
+        code: "AGREEMENT_DELEGATION_STATUS_UNKNOWN",
+        message: "delegation has unsupported status"
+      };
+    }
+  }
+  if (summary.totalDelegations !== summary.activeCount + summary.settledCount + summary.revokedCount) {
+    summary.invariant = {
+      ok: false,
+      code: "AGREEMENT_DELEGATION_LEDGER_IMBALANCED",
+      message: "active+settled+revoked must equal totalDelegations"
+    };
+  }
+  return normalizeForCanonicalJson(summary, { path: "$" });
+}
+
+function applyDelegationResolutionPlan({
+  delegations,
+  edges,
+  targetStatus,
+  resolvedAt = null,
+  metadata = null,
+  resultKind
+} = {}) {
+  const nextStatus = normalizeStatus(targetStatus, "targetStatus");
+  if (nextStatus === AGREEMENT_DELEGATION_STATUS.ACTIVE) {
+    throw new TypeError("targetStatus must be settled|revoked");
+  }
+  const byId = indexDelegationsById(delegations);
+  const updates = new Map();
+  const operations = [];
+  const at = resolvedAt ?? new Date().toISOString();
+  assertIsoDate(at, "resolvedAt");
+
+  for (const edge of Array.isArray(edges) ? edges : []) {
+    const delegationId = typeof edge?.delegationId === "string" ? edge.delegationId.trim() : "";
+    if (!delegationId) {
+      const err = new Error("delegationId is required on plan edge");
+      err.code = "AGREEMENT_DELEGATION_PLAN_EDGE_ID_REQUIRED";
+      throw err;
+    }
+    const current = updates.get(delegationId) ?? byId.get(delegationId) ?? null;
+    if (!current) {
+      const err = new Error("plan references unknown delegationId");
+      err.code = "AGREEMENT_DELEGATION_PLAN_EDGE_NOT_FOUND";
+      err.delegationId = delegationId;
+      throw err;
+    }
+    const currentStatus = String(current.status ?? "").trim().toLowerCase();
+    if (currentStatus !== AGREEMENT_DELEGATION_STATUS.ACTIVE && currentStatus !== nextStatus) {
+      const err = new Error("delegation already resolved with conflicting terminal status");
+      err.code = "AGREEMENT_DELEGATION_TERMINAL_CONFLICT";
+      err.delegationId = delegationId;
+      err.currentStatus = currentStatus;
+      err.targetStatus = nextStatus;
+      throw err;
+    }
+
+    if (currentStatus === nextStatus) {
+      operations.push({
+        delegationId,
+        result: "noop",
+        fromStatus: currentStatus,
+        toStatus: nextStatus
+      });
+      continue;
+    }
+
+    const nextDelegation = resolveAgreementDelegationV1({
+      delegation: current,
+      status: nextStatus,
+      resolvedAt: at,
+      metadata
+    });
+    updates.set(delegationId, nextDelegation);
+    operations.push({
+      delegationId,
+      result: "applied",
+      fromStatus: currentStatus,
+      toStatus: nextStatus
+    });
+  }
+
+  const nextDelegations = [];
+  for (const delegation of Array.isArray(delegations) ? delegations : []) {
+    if (!delegation || typeof delegation !== "object" || Array.isArray(delegation)) continue;
+    const delegationId = typeof delegation.delegationId === "string" ? delegation.delegationId.trim() : "";
+    if (!delegationId) continue;
+    nextDelegations.push(updates.get(delegationId) ?? delegation);
+  }
+
+  const applied = operations.filter((row) => row.result === "applied").length;
+  const noop = operations.filter((row) => row.result === "noop").length;
+  const ledger = summarizeAgreementDelegationLedgerV1({ delegations: nextDelegations });
+
+  return normalizeForCanonicalJson(
+    {
+      ok: true,
+      kind: resultKind,
+      targetStatus: nextStatus,
+      resolvedAt: at,
+      operations,
+      stats: {
+        attempted: operations.length,
+        applied,
+        noop
+      },
+      ledger,
+      delegations: nextDelegations
+    },
+    { path: "$" }
+  );
+}
+
+// Read-only: returns a deterministic "plan" for the caller to execute.
+export function cascadeSettlementCheck({ delegations, fromChildHash } = {}) {
+  const start = normalizeHexHash(fromChildHash, "fromChildHash");
+  const { byChild } = indexDelegations(delegations);
+  const parents = [];
+  const edges = [];
+  const seen = new Set([start]);
+  let cursor = start;
+  while (true) {
+    const link = byChild.get(cursor) ?? null;
+    if (!link) break;
+    const parent = link.parentAgreementHash;
+    if (seen.has(parent)) {
+      const err = new Error("cycle detected in delegation graph");
+      err.code = "AGREEMENT_DELEGATION_CYCLE";
+      err.agreementHash = parent;
+      throw err;
+    }
+    seen.add(parent);
+    edges.push({ delegationId: link.delegationId ?? null, childAgreementHash: cursor, parentAgreementHash: parent });
+    parents.push(parent);
+    cursor = parent;
+  }
+  return normalizeForCanonicalJson(
+    {
+      ok: true,
+      kind: "cascade_settlement_check_v1",
+      fromChildHash: start,
+      parentAgreementHashes: parents,
+      edges
+    },
+    { path: "$" }
+  );
+}
+
+// Read-only: returns a deterministic "plan" for the caller to execute.
+export function refundUnwindCheck({ delegations, fromParentHash } = {}) {
+  const start = normalizeHexHash(fromParentHash, "fromParentHash");
+  const { childrenByParent } = indexDelegations(delegations);
+  const orderedChildren = [];
+  const edges = [];
+  const seen = new Set([start]);
+  const queue = [start];
+  while (queue.length) {
+    const parent = queue.shift();
+    const children = childrenByParent.get(parent) ?? [];
+    for (const link of children) {
+      const child = link.childAgreementHash;
+      edges.push({ delegationId: link.delegationId ?? null, parentAgreementHash: parent, childAgreementHash: child });
+      if (seen.has(child)) continue;
+      seen.add(child);
+      orderedChildren.push(child);
+      queue.push(child);
+    }
+  }
+  return normalizeForCanonicalJson(
+    {
+      ok: true,
+      kind: "refund_unwind_check_v1",
+      fromParentHash: start,
+      childAgreementHashes: orderedChildren,
+      edges
+    },
+    { path: "$" }
+  );
+}
+
+export function cascadeSettlementExecute({ delegations, fromChildHash, resolvedAt = null, metadata = null } = {}) {
+  const plan = cascadeSettlementCheck({ delegations, fromChildHash });
+  const result = applyDelegationResolutionPlan({
+    delegations,
+    edges: plan.edges,
+    targetStatus: AGREEMENT_DELEGATION_STATUS.SETTLED,
+    resolvedAt,
+    metadata,
+    resultKind: "cascade_settlement_execute_v1"
+  });
+  return normalizeForCanonicalJson(
+    {
+      ...result,
+      plan
+    },
+    { path: "$" }
+  );
+}
+
+export function cascadeUnwindExecute({ delegations, fromChildHash, resolvedAt = null, metadata = null } = {}) {
+  const plan = cascadeSettlementCheck({ delegations, fromChildHash });
+  const result = applyDelegationResolutionPlan({
+    delegations,
+    edges: plan.edges,
+    targetStatus: AGREEMENT_DELEGATION_STATUS.REVOKED,
+    resolvedAt,
+    metadata,
+    resultKind: "cascade_unwind_execute_v1"
+  });
+  return normalizeForCanonicalJson(
+    {
+      ...result,
+      plan
+    },
+    { path: "$" }
+  );
+}
+
+export function refundUnwindExecute({ delegations, fromParentHash, resolvedAt = null, metadata = null } = {}) {
+  const plan = refundUnwindCheck({ delegations, fromParentHash });
+  const result = applyDelegationResolutionPlan({
+    delegations,
+    edges: plan.edges,
+    targetStatus: AGREEMENT_DELEGATION_STATUS.REVOKED,
+    resolvedAt,
+    metadata,
+    resultKind: "refund_unwind_execute_v1"
+  });
+  return normalizeForCanonicalJson(
+    {
+      ...result,
+      plan
+    },
+    { path: "$" }
+  );
+}

package/src/core/billing-plans.js

@@ -12,6 +12,7 @@ const BILLING_PLAN_CATALOG = Object.freeze({
     subscriptionCents: 0,
     includedVerifiedRunsPerMonth: 1000,
     verifiedRunOverageCents: 0,
+    verifiedRunOverageMilliCents: 0,
     settledVolumeFeeBps: 0,
     arbitrationCaseFeeCents: 0,
     hardLimitVerifiedRunsPerMonth: 1000
@@ -22,6 +23,7 @@ const BILLING_PLAN_CATALOG = Object.freeze({
     subscriptionCents: 9900,
     includedVerifiedRunsPerMonth: 10_000,
     verifiedRunOverageCents: 1,
+    verifiedRunOverageMilliCents: 1000,
     settledVolumeFeeBps: 75,
     arbitrationCaseFeeCents: 200,
     hardLimitVerifiedRunsPerMonth: 0
@@ -31,7 +33,8 @@ const BILLING_PLAN_CATALOG = Object.freeze({
     displayName: "Growth",
     subscriptionCents: 59_900,
     includedVerifiedRunsPerMonth: 100_000,
-    verifiedRunOverageCents: 1,
+    verifiedRunOverageCents: 0.7,
+    verifiedRunOverageMilliCents: 700,
     settledVolumeFeeBps: 45,
     arbitrationCaseFeeCents: 100,
     hardLimitVerifiedRunsPerMonth: 0
@@ -42,6 +45,7 @@ const BILLING_PLAN_CATALOG = Object.freeze({
     subscriptionCents: 0,
     includedVerifiedRunsPerMonth: 0,
     verifiedRunOverageCents: 0,
+    verifiedRunOverageMilliCents: 0,
     settledVolumeFeeBps: 35,
     arbitrationCaseFeeCents: 0,
     hardLimitVerifiedRunsPerMonth: 0
@@ -56,6 +60,22 @@ function assertNonNegativeSafeInt(value, fieldName) {
   return n;
 }
 
+function assertNonNegativeCentsRate(value, fieldName) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new TypeError(`${fieldName} must be a non-negative finite number`);
+  }
+  const rounded = Math.round(n * 1000) / 1000;
+  if (Math.abs(rounded - n) > 1e-9) {
+    throw new TypeError(`${fieldName} must use at most 3 decimal places`);
+  }
+  return rounded;
+}
+
+function toMilliCentsFromCentsRate(centsRate) {
+  return Math.round(assertNonNegativeCentsRate(centsRate, "plan.verifiedRunOverageCents") * 1000);
+}
+
 export function normalizeBillingPlanId(value, { allowNull = false, defaultPlan = BILLING_PLAN_ID.FREE } = {}) {
   if (value === null || value === undefined || String(value).trim() === "") {
     if (allowNull) return null;
@@ -96,11 +116,17 @@ export function normalizeBillingPlanOverrides(input, { allowNull = true } = {})
     );
   }
   if (Object.prototype.hasOwnProperty.call(input, "verifiedRunOverageCents")) {
-    out.verifiedRunOverageCents = assertNonNegativeSafeInt(
+    out.verifiedRunOverageCents = assertNonNegativeCentsRate(
       input.verifiedRunOverageCents,
       "billing.overrides.verifiedRunOverageCents"
     );
   }
+  if (Object.prototype.hasOwnProperty.call(input, "verifiedRunOverageMilliCents")) {
+    out.verifiedRunOverageMilliCents = assertNonNegativeSafeInt(
+      input.verifiedRunOverageMilliCents,
+      "billing.overrides.verifiedRunOverageMilliCents"
+    );
+  }
   if (Object.prototype.hasOwnProperty.call(input, "settledVolumeFeeBps")) {
     const bps = assertNonNegativeSafeInt(input.settledVolumeFeeBps, "billing.overrides.settledVolumeFeeBps");
     if (bps > 10_000) throw new TypeError("billing.overrides.settledVolumeFeeBps must be within 0..10000");
@@ -144,10 +170,16 @@ export function computeBillingEstimate({
     plan?.includedVerifiedRunsPerMonth ?? normalizedPlan.includedVerifiedRunsPerMonth ?? 0,
     "plan.includedVerifiedRunsPerMonth"
   );
-  const verifiedRunOverageCentsPerUnit = assertNonNegativeSafeInt(
+  const verifiedRunOverageCentsPerUnit = assertNonNegativeCentsRate(
     plan?.verifiedRunOverageCents ?? normalizedPlan.verifiedRunOverageCents ?? 0,
     "plan.verifiedRunOverageCents"
   );
+  const verifiedRunOverageMilliCentsPerUnit = assertNonNegativeSafeInt(
+    plan?.verifiedRunOverageMilliCents ??
+      normalizedPlan.verifiedRunOverageMilliCents ??
+      toMilliCentsFromCentsRate(verifiedRunOverageCentsPerUnit),
+    "plan.verifiedRunOverageMilliCents"
+  );
   const settledVolumeFeeBps = assertNonNegativeSafeInt(
     plan?.settledVolumeFeeBps ?? normalizedPlan.settledVolumeFeeBps ?? 0,
     "plan.settledVolumeFeeBps"
@@ -165,9 +197,9 @@ export function computeBillingEstimate({
   const settledVolumeCents = assertNonNegativeSafeInt(usage?.settledVolumeCents ?? 0, "usage.settledVolumeCents");
   const arbitrationCases = assertNonNegativeSafeInt(usage?.arbitrationCases ?? 0, "usage.arbitrationCases");
 
-  const verifiedRunOverageUnits =
-    includedVerifiedRunsPerMonth > 0 ? Math.max(0, verifiedRuns - includedVerifiedRunsPerMonth) : 0;
-  const verifiedRunOverageCents = verifiedRunOverageUnits * verifiedRunOverageCentsPerUnit;
+  const verifiedRunOverageUnits = Math.max(0, verifiedRuns - includedVerifiedRunsPerMonth);
+  const verifiedRunOverageMilliCents = verifiedRunOverageUnits * verifiedRunOverageMilliCentsPerUnit;
+  const verifiedRunOverageCents = Math.round(verifiedRunOverageMilliCents / 1000);
   const settledVolumeFeeCents = Math.floor((settledVolumeCents * settledVolumeFeeBps) / 10_000);
   const arbitrationFeeCents = arbitrationCases * arbitrationCaseFeeCents;
   const totalEstimatedCents = subscriptionCents + verifiedRunOverageCents + settledVolumeFeeCents + arbitrationFeeCents;
@@ -177,7 +209,9 @@ export function computeBillingEstimate({
     includedVerifiedRunsPerMonth,
     verifiedRunOverageUnits,
     verifiedRunOverageCents,
+    verifiedRunOverageMilliCents,
     verifiedRunOverageCentsPerUnit,
+    verifiedRunOverageMilliCentsPerUnit,
     settledVolumeFeeBps,
     settledVolumeFeeCents,
     arbitrationCaseFeeCents,