settld 0.1.0

package/src/core/assist.js

@@ -0,0 +1,106 @@
+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`);
+}
+
+const ASSIST_PRIORITIES = new Set(["LOW", "NORMAL", "HIGH", "CRITICAL"]);
+
+export function validateAssistRequestedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "robotId", "requestedAt", "reason", "priority"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.robotId, "payload.robotId");
+  assertIsoDate(payload.requestedAt, "payload.requestedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  if (payload.priority !== undefined && payload.priority !== null) {
+    assertNonEmptyString(payload.priority, "payload.priority");
+    if (!ASSIST_PRIORITIES.has(payload.priority)) throw new TypeError("payload.priority is not supported");
+  }
+  return payload;
+}
+
+export function validateAssistQueuedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "queueId", "queuedAt", "reason", "priority"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.queueId, "payload.queueId");
+  assertIsoDate(payload.queuedAt, "payload.queuedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  if (payload.priority !== undefined && payload.priority !== null) {
+    assertNonEmptyString(payload.priority, "payload.priority");
+    if (!ASSIST_PRIORITIES.has(payload.priority)) throw new TypeError("payload.priority is not supported");
+  }
+  return payload;
+}
+
+export function validateAssistAssignedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "queueId", "operatorId", "assignedAt"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.queueId, "payload.queueId");
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  assertIsoDate(payload.assignedAt, "payload.assignedAt");
+  return payload;
+}
+
+export function validateAssistAcceptedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "queueId", "operatorId", "acceptedAt"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.queueId, "payload.queueId");
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  assertIsoDate(payload.acceptedAt, "payload.acceptedAt");
+  return payload;
+}
+
+export function validateAssistDeclinedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "queueId", "operatorId", "declinedAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.queueId, "payload.queueId");
+  assertNonEmptyString(payload.operatorId, "payload.operatorId");
+  assertIsoDate(payload.declinedAt, "payload.declinedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return payload;
+}
+
+export function validateAssistTimeoutPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "queueId", "timedOutAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.queueId, "payload.queueId");
+  assertIsoDate(payload.timedOutAt, "payload.timedOutAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return payload;
+}
+

package/src/core/audit-export.js

@@ -0,0 +1,68 @@
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+
+function deepRedact(value, { removeKeys }) {
+  if (Array.isArray(value)) return value.map((v) => deepRedact(v, { removeKeys }));
+  if (!isPlainObject(value)) return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (removeKeys.has(k)) continue;
+    out[k] = deepRedact(v, { removeKeys });
+  }
+  return out;
+}
+
+const COMMON_REMOVE_KEYS = new Set(["paymentHoldId"]);
+const AUDIT_REMOVE_KEYS = new Set([...COMMON_REMOVE_KEYS, "credentialRef", "evidenceRef"]);
+const EVIDENCE_REMOVE_KEYS = new Set([...COMMON_REMOVE_KEYS, "credentialRef"]);
+
+export function buildAuditExport({ job, events }) {
+  if (!job || typeof job !== "object") throw new TypeError("job is required");
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+
+  const accessPlan = job.accessPlan ? deepRedact(job.accessPlan, { removeKeys: AUDIT_REMOVE_KEYS }) : null;
+  const booking = job.booking ? deepRedact(job.booking, { removeKeys: AUDIT_REMOVE_KEYS }) : null;
+
+  const timeline = events.map((e) => ({
+    id: e?.id ?? null,
+    at: e?.at ?? null,
+    type: e?.type ?? null,
+    actor: e?.actor ?? null,
+    payload: e?.payload ? deepRedact(e.payload, { removeKeys: AUDIT_REMOVE_KEYS }) : null
+  }));
+
+  return {
+    job: {
+      id: job.id ?? null,
+      templateId: job.templateId ?? null,
+      status: job.status ?? null,
+      zoneId: job.booking?.zoneId ?? job.constraints?.zoneId ?? null,
+      environmentTier: job.booking?.environmentTier ?? null,
+      booking,
+      cancellation: job.cancellation ? deepRedact(job.cancellation, { removeKeys: AUDIT_REMOVE_KEYS }) : null,
+      match: job.match ?? null,
+      reservation: job.reservation ?? null,
+      operatorCoverage: job.operatorCoverage ?? null,
+      assist: job.assist ?? null,
+      accessPlan,
+      access: job.access ?? null,
+      execution: job.execution ?? null,
+      operatorCosts: job.operatorCosts ?? [],
+      slaBreaches: job.slaBreaches ?? [],
+      slaCredits: job.slaCredits ?? [],
+      incidents: job.incidents ?? [],
+      claims: job.claims ?? [],
+      lastEventId: job.lastEventId ?? null,
+      lastChainHash: job.lastChainHash ?? null
+    },
+    timeline
+  };
+}
+
+export function buildEvidenceExport({ job }) {
+  if (!job || typeof job !== "object") throw new TypeError("job is required");
+  const evidence = Array.isArray(job.evidence) ? job.evidence.map((e) => deepRedact(e, { removeKeys: EVIDENCE_REMOVE_KEYS })) : [];
+  return { jobId: job.id ?? null, evidence };
+}
+

package/src/core/auth.js

@@ -0,0 +1,189 @@
+import crypto from "node:crypto";
+
+import { createId } from "./ids.js";
+
+export const AUTH_KEY_STATUS = Object.freeze({
+  ACTIVE: "active",
+  ROTATED: "rotated",
+  REVOKED: "revoked"
+});
+
+const AUTH_KEY_STATUSES = new Set(Object.values(AUTH_KEY_STATUS));
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export function normalizeAuthKeyStatus(status) {
+  assertNonEmptyString(status, "status");
+  const normalized = String(status).trim().toLowerCase();
+  if (!AUTH_KEY_STATUSES.has(normalized)) throw new TypeError("status is not supported");
+  return normalized;
+}
+
+export function normalizeScopes(scopes) {
+  if (scopes === null || scopes === undefined) return [];
+  if (!Array.isArray(scopes)) throw new TypeError("scopes must be an array");
+  const out = [];
+  const seen = new Set();
+  for (const s of scopes) {
+    if (typeof s !== "string" || s.trim() === "") continue;
+    const v = s.trim();
+    if (seen.has(v)) continue;
+    seen.add(v);
+    out.push(v);
+  }
+  out.sort();
+  return out;
+}
+
+export function hasScope(scopes, requiredScope) {
+  if (!requiredScope) return false;
+  const s = scopes instanceof Set ? scopes : new Set(Array.isArray(scopes) ? scopes : []);
+  if (s.has(requiredScope)) return true;
+
+  // Write implies read for `*_read` scopes (e.g., ops_write -> ops_read).
+  if (requiredScope.endsWith("_read")) {
+    const implied = `${requiredScope.slice(0, -"_read".length)}_write`;
+    if (s.has(implied)) return true;
+  }
+
+  return false;
+}
+
+export function authKeyId() {
+  const nodeEnv = typeof process !== "undefined" && process.env ? String(process.env.NODE_ENV ?? "") : "";
+  const prefix = nodeEnv === "production" ? "sk_live" : "sk_test";
+  return createId(prefix);
+}
+
+export function authKeySecret({ bytes = 32 } = {}) {
+  if (!Number.isSafeInteger(bytes) || bytes <= 0) throw new TypeError("bytes must be a positive integer");
+  return crypto.randomBytes(bytes).toString("base64url");
+}
+
+export function sha256HexUtf8(value) {
+  assertNonEmptyString(value, "value");
+  return crypto.createHash("sha256").update(value, "utf8").digest("hex");
+}
+
+export function hashAuthKeySecret(secret) {
+  return hashAuthKeySecretScrypt(secret);
+}
+
+export function timingSafeEqualHex(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  const ax = a.trim();
+  const bx = b.trim();
+  if (ax.length !== bx.length) return false;
+  try {
+    return crypto.timingSafeEqual(Buffer.from(ax, "utf8"), Buffer.from(bx, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+export function parseBearerAuthorizationHeader(headerValue) {
+  if (typeof headerValue !== "string" || headerValue.trim() === "") return null;
+  const v = headerValue.trim();
+  if (!v.toLowerCase().startsWith("bearer ")) return null;
+  const token = v.slice("bearer ".length).trim();
+  return token ? token : null;
+}
+
+export function parseApiKeyToken(token) {
+  if (typeof token !== "string" || token.trim() === "") return null;
+  const raw = token.trim();
+  const idx = raw.indexOf(".");
+  if (idx === -1) return null;
+  const keyId = raw.slice(0, idx).trim();
+  const secret = raw.slice(idx + 1).trim();
+  if (!keyId || !secret) return null;
+  if (keyId.includes(" ") || secret.includes(" ")) return null;
+  return { keyId, secret };
+}
+
+export function hashAuthKeySecretLegacy(secret) {
+  assertNonEmptyString(secret, "secret");
+  return sha256HexUtf8(`settld_auth_key_secret_v1:${secret}`);
+}
+
+function scryptParamsFromEnv() {
+  const defaults = { N: 16384, r: 8, p: 1, keyLen: 32, saltBytes: 16 };
+  if (typeof process === "undefined" || !process.env) return defaults;
+  const rawN = process.env.PROXY_AUTH_KEY_SCRYPT_N;
+  const rawR = process.env.PROXY_AUTH_KEY_SCRYPT_R;
+  const rawP = process.env.PROXY_AUTH_KEY_SCRYPT_P;
+  const rawKeyLen = process.env.PROXY_AUTH_KEY_SCRYPT_KEYLEN;
+  const rawSaltBytes = process.env.PROXY_AUTH_KEY_SCRYPT_SALT_BYTES;
+
+  const next = { ...defaults };
+  if (rawN && String(rawN).trim() !== "") next.N = Number(rawN);
+  if (rawR && String(rawR).trim() !== "") next.r = Number(rawR);
+  if (rawP && String(rawP).trim() !== "") next.p = Number(rawP);
+  if (rawKeyLen && String(rawKeyLen).trim() !== "") next.keyLen = Number(rawKeyLen);
+  if (rawSaltBytes && String(rawSaltBytes).trim() !== "") next.saltBytes = Number(rawSaltBytes);
+
+  if (!Number.isSafeInteger(next.N) || next.N < 1024) throw new TypeError("PROXY_AUTH_KEY_SCRYPT_N must be a safe integer >= 1024");
+  if (!Number.isSafeInteger(next.r) || next.r <= 0) throw new TypeError("PROXY_AUTH_KEY_SCRYPT_R must be a positive safe integer");
+  if (!Number.isSafeInteger(next.p) || next.p <= 0) throw new TypeError("PROXY_AUTH_KEY_SCRYPT_P must be a positive safe integer");
+  if (!Number.isSafeInteger(next.keyLen) || next.keyLen <= 0) throw new TypeError("PROXY_AUTH_KEY_SCRYPT_KEYLEN must be a positive safe integer");
+  if (!Number.isSafeInteger(next.saltBytes) || next.saltBytes <= 0) throw new TypeError("PROXY_AUTH_KEY_SCRYPT_SALT_BYTES must be a positive safe integer");
+
+  return next;
+}
+
+export function hashAuthKeySecretScrypt(secret) {
+  assertNonEmptyString(secret, "secret");
+  const { N, r, p, keyLen, saltBytes } = scryptParamsFromEnv();
+  const salt = crypto.randomBytes(saltBytes);
+  const maxmem = 32 * 1024 * 1024; // prevent pathological settings from exhausting memory
+  const derived = crypto.scryptSync(`settld_auth_key_secret_v2:${secret}`, salt, keyLen, { N, r, p, maxmem });
+  return `scrypt$${N}$${r}$${p}$${salt.toString("base64url")}$${derived.toString("base64url")}`;
+}
+
+export function verifyAuthKeySecret({ secret, secretHash }) {
+  assertNonEmptyString(secret, "secret");
+  if (typeof secretHash !== "string" || secretHash.trim() === "") return { ok: false, scheme: null, needsRehash: false };
+  const stored = secretHash.trim();
+
+  if (stored.startsWith("scrypt$")) {
+    const parts = stored.split("$");
+    if (parts.length !== 6) return { ok: false, scheme: "scrypt", needsRehash: false };
+    const N = Number(parts[1]);
+    const r = Number(parts[2]);
+    const p = Number(parts[3]);
+    const saltB64 = parts[4];
+    const hashB64 = parts[5];
+    if (!Number.isSafeInteger(N) || N <= 0) return { ok: false, scheme: "scrypt", needsRehash: false };
+    if (!Number.isSafeInteger(r) || r <= 0) return { ok: false, scheme: "scrypt", needsRehash: false };
+    if (!Number.isSafeInteger(p) || p <= 0) return { ok: false, scheme: "scrypt", needsRehash: false };
+    let salt;
+    let expected;
+    try {
+      salt = Buffer.from(String(saltB64), "base64url");
+      expected = Buffer.from(String(hashB64), "base64url");
+    } catch {
+      return { ok: false, scheme: "scrypt", needsRehash: false };
+    }
+    if (!salt.length || !expected.length) return { ok: false, scheme: "scrypt", needsRehash: false };
+
+    try {
+      const maxmem = 32 * 1024 * 1024;
+      const got = crypto.scryptSync(`settld_auth_key_secret_v2:${secret}`, salt, expected.length, { N, r, p, maxmem });
+      const ok = expected.length === got.length && crypto.timingSafeEqual(expected, got);
+      return { ok, scheme: "scrypt", needsRehash: false };
+    } catch {
+      return { ok: false, scheme: "scrypt", needsRehash: false };
+    }
+  }
+
+  // Legacy v1: sha256HexUtf8(`settld_auth_key_secret_v1:${secret}`)
+  if (/^[0-9a-f]{64}$/i.test(stored)) {
+    const presented = hashAuthKeySecretLegacy(secret);
+    const ok = timingSafeEqualHex(presented, stored);
+    return { ok, scheme: "sha256", needsRehash: ok };
+  }
+
+  return { ok: false, scheme: null, needsRehash: false };
+}

package/src/core/billing-plans.js

@@ -0,0 +1,187 @@
+export const BILLING_PLAN_ID = Object.freeze({
+  FREE: "free",
+  BUILDER: "builder",
+  GROWTH: "growth",
+  ENTERPRISE: "enterprise"
+});
+
+const BILLING_PLAN_CATALOG = Object.freeze({
+  [BILLING_PLAN_ID.FREE]: Object.freeze({
+    planId: BILLING_PLAN_ID.FREE,
+    displayName: "Free",
+    subscriptionCents: 0,
+    includedVerifiedRunsPerMonth: 1000,
+    verifiedRunOverageCents: 0,
+    settledVolumeFeeBps: 0,
+    arbitrationCaseFeeCents: 0,
+    hardLimitVerifiedRunsPerMonth: 1000
+  }),
+  [BILLING_PLAN_ID.BUILDER]: Object.freeze({
+    planId: BILLING_PLAN_ID.BUILDER,
+    displayName: "Builder",
+    subscriptionCents: 9900,
+    includedVerifiedRunsPerMonth: 10_000,
+    verifiedRunOverageCents: 1,
+    settledVolumeFeeBps: 75,
+    arbitrationCaseFeeCents: 200,
+    hardLimitVerifiedRunsPerMonth: 0
+  }),
+  [BILLING_PLAN_ID.GROWTH]: Object.freeze({
+    planId: BILLING_PLAN_ID.GROWTH,
+    displayName: "Growth",
+    subscriptionCents: 59_900,
+    includedVerifiedRunsPerMonth: 100_000,
+    verifiedRunOverageCents: 1,
+    settledVolumeFeeBps: 45,
+    arbitrationCaseFeeCents: 100,
+    hardLimitVerifiedRunsPerMonth: 0
+  }),
+  [BILLING_PLAN_ID.ENTERPRISE]: Object.freeze({
+    planId: BILLING_PLAN_ID.ENTERPRISE,
+    displayName: "Enterprise",
+    subscriptionCents: 0,
+    includedVerifiedRunsPerMonth: 0,
+    verifiedRunOverageCents: 0,
+    settledVolumeFeeBps: 35,
+    arbitrationCaseFeeCents: 0,
+    hardLimitVerifiedRunsPerMonth: 0
+  })
+});
+
+function assertNonNegativeSafeInt(value, fieldName) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) {
+    throw new TypeError(`${fieldName} must be a non-negative safe integer`);
+  }
+  return n;
+}
+
+export function normalizeBillingPlanId(value, { allowNull = false, defaultPlan = BILLING_PLAN_ID.FREE } = {}) {
+  if (value === null || value === undefined || String(value).trim() === "") {
+    if (allowNull) return null;
+    return normalizeBillingPlanId(defaultPlan, { allowNull: false, defaultPlan: BILLING_PLAN_ID.FREE });
+  }
+  const normalized = String(value).trim().toLowerCase();
+  if (!(normalized in BILLING_PLAN_CATALOG)) {
+    const known = Object.keys(BILLING_PLAN_CATALOG).join("|");
+    throw new TypeError(`billing plan must be one of ${known}`);
+  }
+  return normalized;
+}
+
+export function getBillingPlanCatalog() {
+  return JSON.parse(JSON.stringify(BILLING_PLAN_CATALOG));
+}
+
+export function getBillingPlanById(planId) {
+  const normalizedPlanId = normalizeBillingPlanId(planId, { allowNull: false });
+  return BILLING_PLAN_CATALOG[normalizedPlanId];
+}
+
+export function normalizeBillingPlanOverrides(input, { allowNull = true } = {}) {
+  if (input === undefined) return undefined;
+  if (input === null) return allowNull ? null : {};
+  if (typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("billing plan overrides must be an object or null");
+  }
+
+  const out = {};
+  if (Object.prototype.hasOwnProperty.call(input, "subscriptionCents")) {
+    out.subscriptionCents = assertNonNegativeSafeInt(input.subscriptionCents, "billing.overrides.subscriptionCents");
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "includedVerifiedRunsPerMonth")) {
+    out.includedVerifiedRunsPerMonth = assertNonNegativeSafeInt(
+      input.includedVerifiedRunsPerMonth,
+      "billing.overrides.includedVerifiedRunsPerMonth"
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "verifiedRunOverageCents")) {
+    out.verifiedRunOverageCents = assertNonNegativeSafeInt(
+      input.verifiedRunOverageCents,
+      "billing.overrides.verifiedRunOverageCents"
+    );
+  }
+  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");
+    out.settledVolumeFeeBps = bps;
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "arbitrationCaseFeeCents")) {
+    out.arbitrationCaseFeeCents = assertNonNegativeSafeInt(
+      input.arbitrationCaseFeeCents,
+      "billing.overrides.arbitrationCaseFeeCents"
+    );
+  }
+  if (Object.prototype.hasOwnProperty.call(input, "hardLimitVerifiedRunsPerMonth")) {
+    out.hardLimitVerifiedRunsPerMonth = assertNonNegativeSafeInt(
+      input.hardLimitVerifiedRunsPerMonth,
+      "billing.overrides.hardLimitVerifiedRunsPerMonth"
+    );
+  }
+  return out;
+}
+
+export function resolveBillingPlan({ planId, overrides = null, hardLimitEnforced = true } = {}) {
+  const base = getBillingPlanById(planId);
+  const normalizedOverrides = normalizeBillingPlanOverrides(overrides, { allowNull: true });
+  const merged = normalizedOverrides ? { ...base, ...normalizedOverrides } : { ...base };
+  return {
+    ...merged,
+    hardLimitEnforced: hardLimitEnforced !== false
+  };
+}
+
+export function computeBillingEstimate({
+  plan,
+  usage = null
+} = {}) {
+  const normalizedPlan = resolveBillingPlan({
+    planId: plan?.planId ?? BILLING_PLAN_ID.FREE,
+    overrides: null,
+    hardLimitEnforced: plan?.hardLimitEnforced !== false
+  });
+  const includedVerifiedRunsPerMonth = assertNonNegativeSafeInt(
+    plan?.includedVerifiedRunsPerMonth ?? normalizedPlan.includedVerifiedRunsPerMonth ?? 0,
+    "plan.includedVerifiedRunsPerMonth"
+  );
+  const verifiedRunOverageCentsPerUnit = assertNonNegativeSafeInt(
+    plan?.verifiedRunOverageCents ?? normalizedPlan.verifiedRunOverageCents ?? 0,
+    "plan.verifiedRunOverageCents"
+  );
+  const settledVolumeFeeBps = assertNonNegativeSafeInt(
+    plan?.settledVolumeFeeBps ?? normalizedPlan.settledVolumeFeeBps ?? 0,
+    "plan.settledVolumeFeeBps"
+  );
+  const arbitrationCaseFeeCents = assertNonNegativeSafeInt(
+    plan?.arbitrationCaseFeeCents ?? normalizedPlan.arbitrationCaseFeeCents ?? 0,
+    "plan.arbitrationCaseFeeCents"
+  );
+  const subscriptionCents = assertNonNegativeSafeInt(
+    plan?.subscriptionCents ?? normalizedPlan.subscriptionCents ?? 0,
+    "plan.subscriptionCents"
+  );
+
+  const verifiedRuns = assertNonNegativeSafeInt(usage?.verifiedRuns ?? 0, "usage.verifiedRuns");
+  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 settledVolumeFeeCents = Math.floor((settledVolumeCents * settledVolumeFeeBps) / 10_000);
+  const arbitrationFeeCents = arbitrationCases * arbitrationCaseFeeCents;
+  const totalEstimatedCents = subscriptionCents + verifiedRunOverageCents + settledVolumeFeeCents + arbitrationFeeCents;
+
+  return {
+    subscriptionCents,
+    includedVerifiedRunsPerMonth,
+    verifiedRunOverageUnits,
+    verifiedRunOverageCents,
+    verifiedRunOverageCentsPerUnit,
+    settledVolumeFeeBps,
+    settledVolumeFeeCents,
+    arbitrationCaseFeeCents,
+    arbitrationFeeCents,
+    totalEstimatedCents
+  };
+}