opencode-feature-factory 0.2.0

package/src/config.js

@@ -0,0 +1,231 @@
+import { readFileSync } from "node:fs";
+import { basename, isAbsolute, win32 } from "node:path";
+import { parse, printParseErrorCode } from "jsonc-parser";
+
+const JSONC_PARSE_OPTIONS = {
+  allowEmptyContent: true,
+  allowTrailingComma: true,
+  disallowComments: false,
+};
+
+export const POST_PR_CI_DEFAULTS = Object.freeze({
+  enabled: false,
+  wait_ms: 3_600_000,
+  initial_poll_ms: 30_000,
+  max_poll_ms: 120_000,
+  check_start_grace_ms: 300_000,
+  max_transient_errors: 12,
+});
+
+const POST_PR_PLUGIN_KEYS = new Set(["enabled", "waitMinutes", "initialPollSeconds", "maxPollSeconds", "checkStartGraceSeconds", "maxTransientErrors"]);
+const POST_PR_DRIVER_KEYS = new Set(["enabled", "wait_ms", "initial_poll_ms", "max_poll_ms", "check_start_grace_ms", "max_transient_errors"]);
+
+/** Strictly normalize the canonical plugin postPrCi object to persisted units. */
+export function normalizePostPrCiConfig(value, { label = "postPrCi", partial = false } = {}) {
+  if (value === undefined || value === null) return partial ? {} : { ...POST_PR_CI_DEFAULTS };
+  assertPlainObject(value, label);
+  assertKnownKeys(value, POST_PR_PLUGIN_KEYS, label);
+  const normalized = {};
+  if (Object.hasOwn(value, "enabled")) normalized.enabled = booleanValue(value.enabled, `${label}.enabled`);
+  normalizeBoundedInteger(normalized, "wait_ms", value.waitMinutes, 30, 1440, 60_000, `${label}.waitMinutes`);
+  normalizeBoundedInteger(normalized, "initial_poll_ms", value.initialPollSeconds, 15, 300, 1000, `${label}.initialPollSeconds`);
+  normalizeBoundedInteger(normalized, "max_poll_ms", value.maxPollSeconds, 15, 600, 1000, `${label}.maxPollSeconds`);
+  normalizeBoundedInteger(normalized, "check_start_grace_ms", value.checkStartGraceSeconds, 60, 900, 1000, `${label}.checkStartGraceSeconds`);
+  normalizeBoundedInteger(normalized, "max_transient_errors", value.maxTransientErrors, 1, 50, 1, `${label}.maxTransientErrors`);
+  const result = partial ? normalized : { ...POST_PR_CI_DEFAULTS, ...normalized };
+  assertPostPrPollOrder(result, label);
+  return result;
+}
+
+/** Normalize an already unit-converted driver override. Missing fields stay absent. */
+export function normalizePostPrCiDriverOverride(value, { label = "driver.post_pr_ci" } = {}) {
+  if (value === undefined || value === null) return null;
+  assertPlainObject(value, label);
+  assertKnownKeys(value, POST_PR_DRIVER_KEYS, label);
+  const normalized = {};
+  if (Object.hasOwn(value, "enabled")) normalized.enabled = booleanValue(value.enabled, `${label}.enabled`);
+  for (const [key, min, max] of [
+    ["wait_ms", 1_800_000, 86_400_000],
+    ["initial_poll_ms", 15_000, 300_000],
+    ["max_poll_ms", 15_000, 600_000],
+    ["check_start_grace_ms", 60_000, 900_000],
+    ["max_transient_errors", 1, 50],
+  ]) {
+    if (!Object.hasOwn(value, key)) continue;
+    const number = value[key];
+    if (!Number.isInteger(number) || number < min || number > max) throw new TypeError(`${label}.${key} must be an integer from ${min} to ${max}`);
+    normalized[key] = number;
+  }
+  return normalized;
+}
+
+/** Resolve each field independently: built-in < plugin < inherited parent < driver. */
+export function resolvePostPrCiPolicy({ plugin, parent, driver, reviewer } = {}) {
+  const pluginPolicy = normalizePostPrCiConfig(plugin, { partial: true });
+  const parentPolicy = normalizePersistedPostPrPolicy(parent, "parent post-PR policy");
+  const driverPolicy = normalizePostPrCiDriverOverride(driver) ?? {};
+  const effective = { ...POST_PR_CI_DEFAULTS, ...pluginPolicy, ...parentPolicy, ...driverPolicy };
+  assertPostPrPollOrder(effective, "effective post-PR policy");
+  const reviewerLogin = reviewer === undefined || reviewer === null || reviewer === "" ? null : String(reviewer).trim();
+  if (reviewerLogin !== null && !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/u.test(reviewerLogin)) throw new TypeError("reviewer must be a valid non-empty GitHub login");
+  return {
+    ...effective,
+    review: reviewerLogin
+      ? { required: true, reviewer_login: reviewerLogin, source: "driver" }
+      : parentPolicy?.review ?? { required: false, reviewer_login: null, source: "none" },
+  };
+}
+
+function normalizePersistedPostPrPolicy(value, label) {
+  if (value === undefined || value === null) return {};
+  assertPlainObject(value, label);
+  const allowed = new Set([...POST_PR_DRIVER_KEYS, "review"]);
+  assertKnownKeys(value, allowed, label);
+  const base = normalizePostPrCiDriverOverride(Object.fromEntries(Object.entries(value).filter(([key]) => key !== "review")), { label }) ?? {};
+  if (value.review !== undefined) base.review = structuredClone(value.review);
+  return base;
+}
+
+function assertPlainObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${label} must be an object`);
+}
+
+function assertKnownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unknown.length) throw new TypeError(`${label} contains unknown key '${unknown[0]}'`);
+}
+
+function booleanValue(value, label) {
+  if (typeof value !== "boolean") throw new TypeError(`${label} must be a boolean`);
+  return value;
+}
+
+function normalizeBoundedInteger(target, key, value, min, max, multiplier, label) {
+  if (value === undefined) return;
+  if (!Number.isInteger(value) || value < min || value > max) throw new TypeError(`${label} must be an integer from ${min} to ${max}`);
+  target[key] = value * multiplier;
+}
+
+function assertPostPrPollOrder(value, label) {
+  if (value.initial_poll_ms !== undefined && value.max_poll_ms !== undefined && value.max_poll_ms < value.initial_poll_ms) {
+    throw new TypeError(`${label}.max poll must be greater than or equal to initial poll`);
+  }
+}
+
+export function parseJsoncConfig(raw, { label = "opencode.jsonc" } = {}) {
+  const errors = [];
+  const input = stripBom(raw);
+  const value = parse(input, errors, JSONC_PARSE_OPTIONS);
+  const safeLabel = sanitizeLabel(label, "opencode.jsonc");
+
+  if (errors.length > 0) {
+    throw new SyntaxError(formatJsoncParseError(input, errors, safeLabel));
+  }
+
+  if (value === undefined) return {};
+  assertConfigObject(value, safeLabel);
+  return value;
+}
+
+export function readJsoncConfig(path, opts = {}) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+
+  return parseJsoncConfig(raw, { ...opts, label: opts.label ?? basename(path) });
+}
+
+export function parseStrictJsonConfig(raw, { label = "opencode.json" } = {}) {
+  const safeLabel = sanitizeLabel(label, "opencode.json");
+  const input = stripBom(raw);
+  let value;
+
+  try {
+    value = JSON.parse(input);
+  } catch (error) {
+    throw new SyntaxError(formatStrictJsonParseError(input, error, safeLabel));
+  }
+
+  assertConfigObject(value, safeLabel);
+  return value;
+}
+
+export function readStrictJsonConfig(path, opts = {}) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw error;
+  }
+
+  return parseStrictJsonConfig(raw, { ...opts, label: opts.label ?? basename(path) });
+}
+
+function assertConfigObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${label}: expected top-level config value to be a non-array object`);
+  }
+}
+
+function formatJsoncParseError(raw, errors, label) {
+  const first = errors[0];
+  const location = lineColumnAt(raw, first.offset);
+  const codeMessage = printParseErrorCode(first.error);
+  const prefix = errors.length === 1 ? "JSONC parse error" : `${errors.length} JSONC parse errors; first error`;
+
+  return `${label}: ${prefix} at line ${location.line}, column ${location.column}: parser ${codeMessage} (${first.error})`;
+}
+
+function formatStrictJsonParseError(raw, error, label) {
+  const offset = strictJsonErrorOffset(error);
+  if (offset == null) return `${label}: JSON parse error: invalid JSON syntax`;
+
+  const location = lineColumnAt(raw, offset);
+  return `${label}: JSON parse error at line ${location.line}, column ${location.column}: invalid JSON syntax`;
+}
+
+function strictJsonErrorOffset(error) {
+  const message = String(error?.message ?? "");
+  const positionMatch = /position (\d+)/u.exec(message);
+  if (positionMatch) return Number(positionMatch[1]);
+
+  const lineColumnMatch = /line (\d+) column (\d+)/iu.exec(message);
+  if (lineColumnMatch) return { line: Number(lineColumnMatch[1]), column: Number(lineColumnMatch[2]) };
+
+  return null;
+}
+
+function lineColumnAt(raw, offsetOrLocation) {
+  if (typeof offsetOrLocation === "object" && offsetOrLocation) return offsetOrLocation;
+
+  const offset = Math.max(0, Number(offsetOrLocation) || 0);
+  let line = 1;
+  let column = 1;
+
+  for (let index = 0; index < raw.length && index < offset; index += 1) {
+    if (raw[index] === "\n") {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { line, column };
+}
+
+function sanitizeLabel(label, fallback) {
+  const raw = String(label ?? fallback);
+  const withoutAbsolutePath = isAbsolute(raw) ? basename(raw) : win32.isAbsolute(raw) ? win32.basename(raw) : raw;
+  return withoutAbsolutePath.replace(/[\r\n\t]+/gu, " ").trim() || fallback;
+}
+
+function stripBom(raw) {
+  const text = String(raw);
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/src/cost-attribution.js

@@ -0,0 +1,327 @@
+import { randomUUID } from "node:crypto";
+
+export const COST_ATTRIBUTION_SCHEMA_VERSION = 1;
+export const MAX_COST_ATTRIBUTION_ENTRIES = 1000;
+export const COST_ATTRIBUTION_STATUSES = Object.freeze(["available", "partial", "unavailable"]);
+export const COST_CURRENCY_PATTERN = /^[A-Z]{3,12}$/u;
+
+export const USAGE_NUMERIC_FIELDS = Object.freeze([
+  "input_tokens",
+  "output_tokens",
+  "total_tokens",
+  "cache_creation_input_tokens",
+  "cache_read_input_tokens",
+  "reasoning_tokens",
+]);
+
+export const COST_NUMERIC_FIELDS = Object.freeze([
+  "cost_total",
+  "cost_input",
+  "cost_output",
+  "cost_cache_creation",
+  "cost_cache_read",
+]);
+
+const OPTIONAL_STRING_FIELDS = Object.freeze(["step", "slice_id", "source", "operation", "provider", "model", "request_id", "cost_currency"]);
+const NUMERIC_FIELDS = Object.freeze([...USAGE_NUMERIC_FIELDS, ...COST_NUMERIC_FIELDS]);
+const STATUS_SET = new Set(COST_ATTRIBUTION_STATUSES);
+const TERMINAL_CONTROL_PATTERN = /[\u0000-\u001F\u007F-\u009F]/gu;
+
+export function normalizeCostUsageEntry(input, options = {}) {
+  if (!isRecord(input)) throw new Error("cost usage entry must be an object");
+  const entry = {};
+
+  entry.id = safeMetadataString(nonEmptyString(input.id) || nonEmptyString(options.id) || randomUUID(), "id");
+  entry.recorded_at = normalizeTimestamp(input.recorded_at ?? input.recordedAt ?? options.now);
+  entry.run_id = nonEmptyString(options.runId) || nonEmptyString(input.run_id ?? input.runId);
+  entry.agent = safeMetadataString(nonEmptyString(input.agent), "agent");
+  if (!entry.run_id) throw new Error("cost usage entry requires run_id");
+  if (!entry.agent) throw new Error("cost usage entry requires agent");
+
+  const aliases = {
+    slice_id: input.slice_id ?? input.sliceId,
+    request_id: input.request_id ?? input.requestId,
+    cost_currency: input.cost_currency ?? input.currency,
+  };
+  for (const field of OPTIONAL_STRING_FIELDS) {
+    const value = Object.prototype.hasOwnProperty.call(aliases, field) ? aliases[field] : input[field];
+    if (field === "cost_currency") {
+      const currency = normalizeCostCurrency(value);
+      if (currency) entry[field] = currency;
+      continue;
+    }
+    const text = nonEmptyString(value);
+    if (text) entry[field] = safeMetadataString(text, field);
+  }
+
+  for (const field of NUMERIC_FIELDS) {
+    if (input[field] === undefined || input[field] === null) continue;
+    entry[field] = normalizeNonNegativeFiniteNumber(input[field], field);
+  }
+
+  let missing = normalizeMissing(input.missing);
+  const hasUsage = USAGE_NUMERIC_FIELDS.some((field) => entry[field] !== undefined);
+  const hasCost = COST_NUMERIC_FIELDS.some((field) => entry[field] !== undefined);
+  const hasCostTotal = entry.cost_total !== undefined;
+  if (hasCost && !entry.cost_currency) missing = addMissing(missing, "cost_currency");
+
+  if (!entry.provider) missing = addMissing(missing, "provider");
+  if (!entry.model) missing = addMissing(missing, "model");
+  if (!hasUsage) missing = addMissing(missing, "usage");
+  if (!hasCostTotal) missing = addMissing(missing, "cost_total");
+  if (!entry.cost_currency) missing = addMissing(missing, "cost_currency");
+
+  const requestedStatus = STATUS_SET.has(input.status) ? input.status : null;
+  if (!hasUsage && !hasCost) {
+    entry.status = "unavailable";
+  } else if (missing.length > 0 || requestedStatus === "partial" || requestedStatus === "unavailable") {
+    entry.status = requestedStatus === "unavailable" && !hasUsage && !hasCost ? "unavailable" : "partial";
+    if (missing.length === 0) missing = ["metadata"];
+  } else {
+    entry.status = "available";
+  }
+  entry.missing = missing;
+
+  return entry;
+}
+
+export function appendCostAttributionEntry(costAttribution, input, options = {}) {
+  const entries = Array.isArray(costAttribution?.entries) ? costAttribution.entries : [];
+  return recomputeCostAttribution({ entries: [...entries, input] }, options);
+}
+
+export function normalizeCostAttribution(value = {}, options = {}) {
+  return recomputeCostAttribution(value, options);
+}
+
+export function recomputeCostAttribution(value = {}, options = {}) {
+  const inputEntries = Array.isArray(value) ? value : Array.isArray(value?.entries) ? value.entries : [];
+  // Dedupe before enforcing the cap so an identical retry at capacity stays a
+  // no-op instead of tripping the entry limit.
+  const entries = dedupeCostEntries(inputEntries.map((entry) => normalizeCostUsageEntry(entry, { ...options, now: entry?.recorded_at ?? entry?.recordedAt ?? options.now, id: entry?.id ?? options.id })));
+  if (entries.length > MAX_COST_ATTRIBUTION_ENTRIES) throw new Error(`cost attribution entries must have at most ${MAX_COST_ATTRIBUTION_ENTRIES} entries`);
+  const updatedAt = normalizeTimestamp(options.now ?? value?.updated_at ?? value?.updatedAt);
+  const totals = rollupEntries(entries);
+  return {
+    schema_version: COST_ATTRIBUTION_SCHEMA_VERSION,
+    updated_at: updatedAt,
+    status: totals.status,
+    totals,
+    by_agent: rollupBy(entries, "agent"),
+    by_slice: rollupBy(entries, "slice_id"),
+    entries,
+  };
+}
+
+export function publicCostAttributionSummary(runOrAttribution) {
+  const attribution = runOrAttribution?.cost_attribution || runOrAttribution;
+  const totals = isRecord(attribution?.totals) ? attribution.totals : rollupEntries(Array.isArray(attribution?.entries) ? attribution.entries : []);
+  const status = safeCostStatus(attribution?.status) || safeCostStatus(totals.status) || "unavailable";
+  const summary = {
+    schema_version: COST_ATTRIBUTION_SCHEMA_VERSION,
+    updated_at: attribution?.updated_at === undefined || attribution?.updated_at === null ? null : sanitizePublicCostText(attribution.updated_at),
+    status,
+    entry_count: totals.entry_count || 0,
+    agent_count: isRecord(attribution?.by_agent) ? Object.keys(attribution.by_agent).length : 0,
+    slice_count: isRecord(attribution?.by_slice) ? Object.keys(attribution.by_slice).length : 0,
+    mixed_currency: totals.mixed_currency === true,
+    missing: Array.isArray(totals.missing) ? totals.missing.map((item) => sanitizePublicCostText(item)).filter(Boolean) : [],
+  };
+  for (const field of USAGE_NUMERIC_FIELDS) if (totals[field] !== undefined) summary[field] = totals[field];
+  if (totals.cost_total !== undefined) summary.cost_total = totals.cost_total;
+  const currency = safeCostCurrency(totals.cost_currency);
+  if (currency) summary.cost_currency = currency;
+  return summary;
+}
+
+export function formatCostAttributionSummary(runOrAttribution) {
+  const summary = publicCostAttributionSummary(runOrAttribution);
+  const parts = [`cost ${summary.status}`, `${summary.entry_count} ${summary.entry_count === 1 ? "entry" : "entries"}`];
+  if (summary.total_tokens !== undefined) parts.push(`${summary.total_tokens} tokens`);
+  else if (summary.input_tokens !== undefined || summary.output_tokens !== undefined) parts.push(`${summary.input_tokens ?? "?"}/${summary.output_tokens ?? "?"} tokens`);
+  if (summary.mixed_currency) parts.push("mixed currency");
+  else if (summary.cost_total !== undefined) parts.push(`${formatCost(summary.cost_total)} ${summary.cost_currency || ""}`.trim());
+  if (summary.missing.length > 0) parts.push(`missing ${summary.missing.join(",")}`);
+  return sanitizePublicCostText(parts.join(" · "));
+}
+
+export function normalizeCostCurrency(value, field = "cost_currency") {
+  const text = nonEmptyString(value);
+  if (!text) return null;
+  if (!COST_CURRENCY_PATTERN.test(text) || hasTerminalControl(text)) {
+    throw new Error(`${field} must be an uppercase currency code (3-12 letters) with no control characters`);
+  }
+  return text;
+}
+
+export function isSafeCostCurrency(value) {
+  return safeCostCurrency(value) !== null;
+}
+
+function safeMetadataString(value, field) {
+  if (value === null || value === undefined) return value;
+  if (hasTerminalControl(value)) throw new Error(`${field} must not contain terminal control characters`);
+  return value;
+}
+
+// Entry ids act as idempotency keys: an exact retry of an already-recorded
+// entry is a no-op, while reusing an id with different content is an error
+// rather than a silent double-count.
+function dedupeCostEntries(entries) {
+  const byId = new Map();
+  const deduped = [];
+  for (const entry of entries) {
+    const existing = byId.get(entry.id);
+    if (existing === undefined) {
+      byId.set(entry.id, entry);
+      deduped.push(entry);
+      continue;
+    }
+    // Same id = same logical event. `recorded_at` is server-generated when the
+    // caller omits --recorded-at, so an identical retry must compare equal
+    // regardless of the retry's timestamp; keep the first entry (its original
+    // timestamp) and treat the retry as a no-op. Only genuinely different
+    // content is a conflict.
+    if (costEntryContentSignature(existing) !== costEntryContentSignature(entry)) {
+      throw new Error(`cost usage entry id '${entry.id}' already recorded with different content`);
+    }
+  }
+  return deduped;
+}
+
+function costEntryContentSignature(entry) {
+  const { recorded_at, ...rest } = entry;
+  void recorded_at;
+  return JSON.stringify(rest);
+}
+
+export function hasTerminalControl(value) {
+  TERMINAL_CONTROL_PATTERN.lastIndex = 0;
+  return typeof value === "string" && TERMINAL_CONTROL_PATTERN.test(value);
+}
+
+export function sanitizePublicCostText(value) {
+  return String(value).replace(/[\t\r\n]+/gu, " ").replace(TERMINAL_CONTROL_PATTERN, "").replace(/\s+/gu, " ").trim();
+}
+
+export function rollupBy(entries, key) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const group = entry[key];
+    if (typeof group !== "string" || group.trim().length === 0) continue;
+    const groupEntries = groups.get(group) || [];
+    groupEntries.push(entry);
+    groups.set(group, groupEntries);
+  }
+  return Object.fromEntries([...groups.entries()].map(([name, groupEntries]) => [name, rollupEntries(groupEntries)]));
+}
+
+export function rollupEntries(entries) {
+  const rollup = {
+    status: "unavailable",
+    entry_count: entries.length,
+    request_count: entries.length,
+  };
+  const missing = new Set();
+  const costCurrencies = new Set();
+  const totalCurrencies = new Set();
+  let availableEntries = 0;
+  let partial = entries.length === 0;
+
+  for (const entry of entries) {
+    if (entry.status === "available") availableEntries += 1;
+    if (entry.status !== "available") partial = true;
+    for (const item of Array.isArray(entry.missing) ? entry.missing : []) missing.add(item);
+
+    for (const field of NUMERIC_FIELDS) {
+      if (entry[field] === undefined || entry[field] === null) continue;
+      const aggregate = (rollup[field] ?? 0) + entry[field];
+      if (!Number.isFinite(aggregate)) throw new Error(`cost attribution aggregate overflow for ${field}`);
+      rollup[field] = aggregate;
+      if (COST_NUMERIC_FIELDS.includes(field)) {
+        const currency = safeCostCurrency(entry.cost_currency);
+        if (currency) {
+          costCurrencies.add(currency);
+          if (field === "cost_total") totalCurrencies.add(currency);
+        } else {
+          missing.add("cost_currency");
+          partial = true;
+        }
+      }
+    }
+  }
+
+  if (totalCurrencies.size === 1) rollup.cost_currency = [...totalCurrencies][0];
+  const hasMixedCurrency = costCurrencies.size > 1;
+  if (hasMixedCurrency) {
+    delete rollup.cost_total;
+    delete rollup.cost_currency;
+    missing.add("mixed_currency");
+    partial = true;
+  }
+
+  if (availableEntries === entries.length && entries.length > 0 && !partial) rollup.status = "available";
+  else if (entries.some((entry) => entry.status === "available" || entry.status === "partial")) rollup.status = "partial";
+  else rollup.status = "unavailable";
+  rollup.mixed_currency = hasMixedCurrency;
+  rollup.missing = entries.length === 0 ? ["entries"] : [...missing].sort();
+  return canonicalRollup(rollup);
+}
+
+function canonicalRollup(rollup) {
+  const ordered = {
+    status: rollup.status,
+    entry_count: rollup.entry_count,
+    request_count: rollup.request_count,
+  };
+  for (const field of NUMERIC_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(rollup, field)) ordered[field] = rollup[field];
+  }
+  if (Object.prototype.hasOwnProperty.call(rollup, "cost_currency")) ordered.cost_currency = rollup.cost_currency;
+  ordered.mixed_currency = rollup.mixed_currency;
+  ordered.missing = rollup.missing;
+  return ordered;
+}
+
+function normalizeMissing(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.map((item) => nonEmptyString(item)).filter(Boolean))].sort();
+}
+
+function addMissing(missing, item) {
+  return [...new Set([...missing, item])].sort();
+}
+
+function normalizeNonNegativeFiniteNumber(value, field) {
+  const number = typeof value === "string" && value.trim() !== "" ? Number(value) : value;
+  if (typeof number !== "number" || !Number.isFinite(number) || number < 0) throw new Error(`${field} must be a finite non-negative number`);
+  return number;
+}
+
+function normalizeTimestamp(value) {
+  if (value === undefined || value === null) return new Date().toISOString();
+  const parsed = typeof value === "number" ? value : value instanceof Date ? value.getTime() : Date.parse(value);
+  if (!Number.isFinite(parsed)) throw new Error("invalid cost attribution timestamp");
+  return new Date(parsed).toISOString();
+}
+
+function formatCost(value) {
+  return Number.isInteger(value) ? String(value) : value.toFixed(6).replace(/0+$/u, "").replace(/\.$/u, "");
+}
+
+function safeCostCurrency(value) {
+  const text = nonEmptyString(value);
+  return text && COST_CURRENCY_PATTERN.test(text) && !hasTerminalControl(text) ? text : null;
+}
+
+function safeCostStatus(value) {
+  return typeof value === "string" && STATUS_SET.has(value) ? value : null;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}