@insiderfinance/totalfinance 0.1.0

package/modules/core/src/artifacts/content-hash.ts

@@ -0,0 +1,183 @@
+/**
+ * Content hashing for the artifact spine (Gate B) — SHA-256 over the canonical JSON bytes.
+ *
+ * Why THIS algorithm, and why implemented here:
+ *
+ * - **SHA-256** because a content hash is an IDENTITY — dedup keys, replay comparison, and
+ *   provenance chains all assume two different artifacts never share a hash. A fast non-crypto
+ *   hash (FNV, xxHash) trades exactly that guarantee away for speed the spine does not need:
+ *   large tables travel by {@link TableHandle} reference, so hashed payloads are envelopes, which
+ *   are small by design. It also matches the repo's existing convention — every tooling hash
+ *   (manifest enforcement, MCP contracts) is already SHA-256.
+ * - **Pure TypeScript** because the library is browser-safe: `node:crypto`'s `createHash` exists
+ *   only in Node (today it appears solely under `tools/`, never in a package), and
+ *   `crypto.subtle.digest` is async — an awaitable constructor would poison every create/read
+ *   call with promises to hash a few hundred bytes. FIPS 180-4 SHA-256 is ~60 lines, synchronous,
+ *   and dependency-free.
+ *
+ * The digest string carries its algorithm — `sha256:<64 hex>` — so a future algorithm change is a
+ * visible new prefix, never a silent re-keying.
+ */
+
+import { ErrorCode, InputError } from '../errors.js';
+import { canonicalJsonOf } from '../canonical-json.js';
+
+/** The hash-string grammar: algorithm prefix + lowercase hex digest. */
+export const CONTENT_HASH_PREFIX = 'sha256:';
+
+/** Exact shape test for a spine hash string (used by handle/artifact validation). */
+export function isContentHashString(value: unknown): value is string {
+  return typeof value === 'string' && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+
+// FIPS 180-4 round constants: first 32 bits of the fractional parts of the cube roots of the
+// first 64 primes.
+// prettier-ignore
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotr(x: number, n: number): number {
+  return (x >>> n) | (x << (32 - n));
+}
+
+/**
+ * UTF-8 encode without `TextEncoder` — the compile target is pure ES2022 (no DOM/Node lib), and a
+ * hand-rolled encoder is also the most explicit statement of the byte contract the hash covers:
+ * well-formed code points encode per RFC 3629; a LONE SURROGATE encodes as U+FFFD (the same
+ * replacement `TextEncoder` performs), so an ill-formed string still has ONE deterministic hash.
+ */
+function utf8Bytes(text: string): Uint8Array {
+  const bytes: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const low = i + 1 < text.length ? text.charCodeAt(i + 1) : 0;
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        i++;
+      } else {
+        code = 0xfffd; // unpaired high surrogate
+      }
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      code = 0xfffd; // unpaired low surrogate
+    }
+    if (code < 0x80) bytes.push(code);
+    else if (code < 0x800) bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    else if (code < 0x10000)
+      bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    else
+      bytes.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+  }
+  return new Uint8Array(bytes);
+}
+
+/** FIPS 180-4 SHA-256 of a byte array, as 8 big-endian words. */
+function sha256Words(bytes: Uint8Array): Uint32Array {
+  // Message length in bits, split into two 32-bit halves. `bytes.length` is a safe integer well
+  // below 2^53, so the high word is exact.
+  const bitLengthLow = (bytes.length << 3) >>> 0;
+  const bitLengthHigh = Math.floor(bytes.length / 0x20000000);
+
+  // Padded length: message + 0x80 + zeros to 56 mod 64, + 8 length bytes.
+  const paddedLength = (((bytes.length + 8) >> 6) + 1) << 6;
+  const padded = new Uint8Array(paddedLength);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(paddedLength - 8, bitLengthHigh);
+  view.setUint32(paddedLength - 4, bitLengthLow);
+
+  // Initial hash: first 32 bits of the fractional parts of the square roots of the first 8 primes.
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const w = new Uint32Array(64);
+
+  for (let offset = 0; offset < paddedLength; offset += 64) {
+    for (let t = 0; t < 16; t++) w[t] = view.getUint32(offset + t * 4);
+    for (let t = 16; t < 64; t++) {
+      const w15 = w[t - 15]!;
+      const w2 = w[t - 2]!;
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      w[t] = (w[t - 16]! + s0 + w[t - 7]! + s1) >>> 0;
+    }
+    let a = h[0]!;
+    let b = h[1]!;
+    let c = h[2]!;
+    let d = h[3]!;
+    let e = h[4]!;
+    let f = h[5]!;
+    let g = h[6]!;
+    let hh = h[7]!;
+    for (let t = 0; t < 64; t++) {
+      const bigSigma1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const choose = (e & f) ^ (~e & g);
+      const t1 = (hh + bigSigma1 + choose + K[t]! + w[t]!) >>> 0;
+      const bigSigma0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const majority = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (bigSigma0 + majority) >>> 0;
+      hh = g;
+      g = f;
+      f = e;
+      e = (d + t1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0]! + a) >>> 0;
+    h[1] = (h[1]! + b) >>> 0;
+    h[2] = (h[2]! + c) >>> 0;
+    h[3] = (h[3]! + d) >>> 0;
+    h[4] = (h[4]! + e) >>> 0;
+    h[5] = (h[5]! + f) >>> 0;
+    h[6] = (h[6]! + g) >>> 0;
+    h[7] = (h[7]! + hh) >>> 0;
+  }
+  return h;
+}
+
+/**
+ * SHA-256 of a UTF-8 string, as 64 lowercase hex characters. The raw primitive under
+ * {@link contentHash}, exported so golden vectors and external comparisons (`echo -n … |
+ * shasum -a 256`, Python's `hashlib`) can target it directly.
+ */
+export function sha256Hex(text: string): string {
+  if (typeof text !== 'string') {
+    throw new InputError(
+      `sha256Hex: text must be a string, got ${text === null ? 'null' : typeof text}.`,
+      {
+        code: ErrorCode.InputWrongType,
+        context: { received: text === null ? 'null' : typeof text },
+      },
+    );
+  }
+  const words = sha256Words(utf8Bytes(text));
+  let hex = '';
+  for (let i = 0; i < 8; i++) hex += words[i]!.toString(16).padStart(8, '0');
+  return hex;
+}
+
+/**
+ * The spine's content identity: `sha256:` + SHA-256 of the value's canonical JSON. Same logical
+ * value → same hash, regardless of key order or `-0`; any covered field change → a different hash.
+ * What a given envelope's hash COVERS (and that provenance labels are excluded) is decided by that
+ * envelope's own `…ContentHash` function, not here — this is the mechanism, not the policy.
+ */
+export function contentHash(value: unknown): string {
+  return CONTENT_HASH_PREFIX + sha256Hex(canonicalJsonOf(value));
+}

package/modules/core/src/artifacts/deep-freeze.ts

@@ -0,0 +1,15 @@
+/**
+ * Recursive freeze for spine envelopes. `Object.freeze` is shallow — a "frozen" snapshot whose
+ * nested observation could still be mutated would break hash stability the moment a caller edited
+ * a row after hashing. Internal to `@insiderfinance/totalfinance/core/artifacts`; envelopes are frozen on the
+ * canonical COPY the constructors build, never on caller input.
+ */
+export function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object') {
+    for (const member of Object.values(value as Record<string, unknown>)) {
+      deepFreeze(member);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}

package/modules/core/src/artifacts/fitted-model-kit.ts

@@ -0,0 +1,402 @@
+/**
+ * The structural mechanics every fitted-model / research-run adapter shares (Stage 4.5, Decisions
+ * 5, 6, 9) — ONE engine for the parts that are not domain semantics:
+ *
+ * - {@link ARTIFACT_WORK_LIMITS} — Decision 9's bounded-work table (defaults a caller may lower,
+ *   hard maxima never passed) and {@link requireWorkLimit}, its count-safe validator;
+ * - {@link requireComparisonTolerance} — the explicit two-sided tolerance law (never defaulted);
+ * - {@link applyReportMigrations} — Gate B's migration policy applied a SECOND time at the report
+ *   level: a newer stored version refuses, an older one restores only through the caller's
+ *   registry under the family-scoped kind, every step echoed, a missing link refused with the
+ *   registration teaching (Decision 5);
+ * - {@link verifyReferencedRows} — caller-supplied rows for a referenced table must hash to the
+ *   stored handle, or replay would be a replay of a different run;
+ * - {@link flattenSummaryParameters} and {@link residualStatistics} — the summary's flat parameter
+ *   view and the residual statistic every projection reports.
+ *
+ * Domain packages (`@insiderfinance/totalfinance/volatility/artifacts`, `@insiderfinance/totalfinance/fixed-income/artifacts`,
+ * `@insiderfinance/totalfinance/research/artifacts`) call these; none re-implements them.
+ */
+
+import { ErrorCode, InputError, isQuantError } from '../errors.js';
+import { ensureKnownKeys, requireArgumentArray, requireArgumentObject } from '../invariants.js';
+import type { ComparisonTolerance } from './comparison.js';
+import { createArtifactMigrationRegistry } from './migration.js';
+import type { AppliedMigration, ArtifactMigrationRegistry } from './migration.js';
+import { requireFittedModelSummary, type FittedModelSummary } from './fitted-model-summary.js';
+import { requireTableHandle, tableHandleForRows } from './table-handle.js';
+import type { TableHandle } from './table-handle.js';
+
+/** Decision 9's bounded-work table: what a caller may lower, and the hard maxima never passed. */
+export const ARTIFACT_WORK_LIMITS = Object.freeze({
+  maximumEmbeddedBytes: Object.freeze({ default: 1_048_576, maximum: 8_388_608 }),
+  embeddedRowLimit: Object.freeze({ default: 5_000, maximum: 50_000 }),
+  maximumDifferences: Object.freeze({ default: 1_000, maximum: 100_000 }),
+  maximumLeaves: Object.freeze({ default: 2_000_000, maximum: 2_000_000 }),
+  gridPoints: Object.freeze({ default: 256, maximum: 4_096 }),
+  restarts: Object.freeze({ maximum: 64 }),
+  holdoutEvaluations: Object.freeze({ maximum: 100_000 }),
+  listedIds: Object.freeze({ default: 200, maximum: 10_000 }),
+});
+
+export interface WorkLimitLaw {
+  default?: number;
+  maximum: number;
+}
+
+function describe(value: unknown): string {
+  return typeof value === 'number' ? String(value) : value === null ? 'null' : typeof value;
+}
+
+/** The kit's own door: every helper is public, so its request is closed and typed like any other. */
+function requireKitRequest(
+  functionName: string,
+  input: unknown,
+  keys: readonly string[],
+  strings: readonly string[],
+): Record<string, unknown> {
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input as object, keys);
+  const record = input as Record<string, unknown>;
+  for (const field of strings) {
+    const value = record[field];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new InputError(
+        `${functionName}: input.${field} must be a non-empty string. Received ${describe(value)}.`,
+        {
+          code: value === undefined ? ErrorCode.InputMissingField : ErrorCode.InputWrongType,
+          context: { function: functionName, field: `input.${field}` },
+        },
+      );
+    }
+  }
+  return record;
+}
+
+/** Structural check for the registry (a function-membered class instance, so no closed-keys walk). */
+function isMigrationRegistry(value: unknown): value is ArtifactMigrationRegistry {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as { upgrade?: unknown }).upgrade === 'function' &&
+    typeof (value as { register?: unknown }).register === 'function'
+  );
+}
+
+function requireFiniteNumber(functionName: string, field: string, value: unknown): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new InputError(
+      `${functionName}: ${field} must be a finite number. Received ${describe(value)}.`,
+      {
+        code: value === undefined ? ErrorCode.InputMissingField : ErrorCode.InputWrongType,
+        context: { function: functionName, field },
+      },
+    );
+  }
+  return value;
+}
+
+/**
+ * Validate one work limit: a safe integer at or above `floor` (default 1), at or below the law's
+ * hard maximum; `undefined` takes the law's default when it has one and refuses when it has none.
+ */
+export function requireWorkLimit(input: {
+  functionName: string;
+  field: string;
+  /** The caller's raw value; omitted (undefined) takes the law's default. */
+  value?: unknown;
+  law: WorkLimitLaw;
+  floor?: number;
+}): number {
+  const record = requireKitRequest(
+    'requireWorkLimit',
+    input,
+    ['functionName', 'field', 'value', 'law', 'floor'],
+    ['functionName', 'field'],
+  );
+  const functionName = record['functionName'] as string;
+  const field = record['field'] as string;
+  const value = record['value'];
+  requireArgumentObject('requireWorkLimit', 'input.law', record['law']);
+  ensureKnownKeys('requireWorkLimit', 'input.law', record['law'] as object, ['default', 'maximum']);
+  const lawRecord = record['law'] as Record<string, unknown>;
+  const law: WorkLimitLaw = {
+    maximum: requireFiniteNumber('requireWorkLimit', 'input.law.maximum', lawRecord['maximum']),
+    ...(lawRecord['default'] === undefined
+      ? {}
+      : {
+          default: requireFiniteNumber(
+            'requireWorkLimit',
+            'input.law.default',
+            lawRecord['default'],
+          ),
+        }),
+  };
+  const floor =
+    record['floor'] === undefined
+      ? 1
+      : requireFiniteNumber('requireWorkLimit', 'input.floor', record['floor']);
+  if (value === undefined) {
+    if (law.default === undefined) {
+      throw new InputError(`${functionName}: ${field} is required.`, {
+        code: ErrorCode.InputMissingField,
+        context: { function: functionName, field },
+      });
+    }
+    return law.default;
+  }
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < floor) {
+    throw new InputError(
+      `${functionName}: ${field} must be a safe integer ≥ ${floor} (${law.default !== undefined ? `default ${law.default}, ` : ''}maximum ${law.maximum}). Received ${describe(value)}.`,
+      { code: ErrorCode.InputOutOfRange, context: { function: functionName, field } },
+    );
+  }
+  if (value > law.maximum) {
+    throw new InputError(
+      `${functionName}: ${field} is ${value}, above the hard maximum ${law.maximum} — a caller may lower a limit or opt up to the maximum, never past it.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { function: functionName, field, maximum: law.maximum },
+      },
+    );
+  }
+  return value;
+}
+
+/** The explicit two-sided tolerance law: both members finite and ≥ 0, or no tolerance at all. */
+export function requireComparisonTolerance(input: {
+  functionName: string;
+  /** The caller's raw tolerance; omitted (undefined) means no tolerance — exact comparison. */
+  tolerance?: unknown;
+}): ComparisonTolerance | null {
+  const request = requireKitRequest(
+    'requireComparisonTolerance',
+    input,
+    ['functionName', 'tolerance'],
+    ['functionName'],
+  );
+  const functionName = request['functionName'] as string;
+  const tolerance = request['tolerance'];
+  if (tolerance === undefined) return null;
+  requireArgumentObject(functionName, 'tolerance', tolerance);
+  ensureKnownKeys(functionName, 'tolerance', tolerance as object, ['absolute', 'relative']);
+  const record = tolerance as Record<string, unknown>;
+  for (const field of ['absolute', 'relative'] as const) {
+    const value = record[field];
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+      throw new InputError(
+        `${functionName}: tolerance.${field} must be a finite number ≥ 0 — a tolerance is two-sided and explicit ({ absolute, relative }), never defaulted. Received ${describe(value)}.`,
+        {
+          code: ErrorCode.InputOutOfRange,
+          context: { function: functionName, field: `tolerance.${field}` },
+        },
+      );
+    }
+  }
+  return { absolute: record['absolute'] as number, relative: record['relative'] as number };
+}
+
+/**
+ * Gate B's migration policy at the REPORT level (Decision 5). The report is presented to the
+ * caller's registry through the envelope view `{ kind, schemaVersion: <stored version>, report }`,
+ * so the one registry runs its one policy; the migrated `report` is returned with the target
+ * version stamped and every applied step echoed.
+ */
+export function applyReportMigrations(input: {
+  functionName: string;
+  /** The family-scoped kind, e.g. `'volatility.fitted-model:ssvi'` or `'research.run:screen'`. */
+  kind: string;
+  report: Record<string, unknown>;
+  storedVersion: unknown;
+  currentVersion: number;
+  /** The report's version field name (`'modelVersion'` or `'runVersion'`). */
+  versionField: string;
+  migrations?: ArtifactMigrationRegistry;
+  /** What the stored report describes, for the teachings: `'ssvi report'`. */
+  subject: string;
+}): { report: Record<string, unknown>; modelMigrationsApplied: AppliedMigration[] } {
+  const record = requireKitRequest(
+    'applyReportMigrations',
+    input,
+    [
+      'functionName',
+      'kind',
+      'report',
+      'storedVersion',
+      'currentVersion',
+      'versionField',
+      'migrations',
+      'subject',
+    ],
+    ['functionName', 'kind', 'versionField', 'subject'],
+  );
+  const functionName = record['functionName'] as string;
+  const kind = record['kind'] as string;
+  const versionField = record['versionField'] as string;
+  const subject = record['subject'] as string;
+  requireArgumentObject('applyReportMigrations', 'input.report', record['report']);
+  const report = record['report'] as Record<string, unknown>;
+  const storedVersion = record['storedVersion'];
+  const currentVersion = record['currentVersion'];
+  if (
+    typeof currentVersion !== 'number' ||
+    !Number.isSafeInteger(currentVersion) ||
+    currentVersion < 0
+  ) {
+    throw new InputError(
+      `applyReportMigrations: input.currentVersion must be a non-negative integer (this build's ${versionField}). Received ${describe(currentVersion)}.`,
+      {
+        code:
+          currentVersion === undefined ? ErrorCode.InputMissingField : ErrorCode.InputOutOfRange,
+        context: { function: 'applyReportMigrations', field: 'input.currentVersion' },
+      },
+    );
+  }
+  if (record['migrations'] !== undefined && !isMigrationRegistry(record['migrations'])) {
+    throw new InputError(
+      'applyReportMigrations: input.migrations must be an ArtifactMigrationRegistry (createArtifactMigrationRegistry()).',
+      {
+        code: ErrorCode.InputWrongType,
+        context: { function: 'applyReportMigrations', field: 'input.migrations' },
+      },
+    );
+  }
+  if (
+    typeof storedVersion !== 'number' ||
+    !Number.isSafeInteger(storedVersion) ||
+    storedVersion < 0
+  ) {
+    throw new InputError(
+      `${functionName}: the stored ${subject}'s ${versionField} must be a non-negative integer. Received ${describe(storedVersion)}.`,
+      { code: ErrorCode.InputOutOfRange, context: { function: functionName, field: versionField } },
+    );
+  }
+  if (storedVersion > currentVersion) {
+    throw new InputError(
+      `${functionName}: the stored ${subject} is version ${storedVersion}, newer than this build's ${currentVersion} — reading it under different semantics would be a silent wrong number. Upgrade the package to restore it.`,
+      {
+        code: ErrorCode.ArtifactModelVersionUnsupported,
+        context: { function: functionName, kind, stored: storedVersion, current: currentVersion },
+      },
+    );
+  }
+  if (storedVersion === currentVersion) return { report, modelMigrationsApplied: [] };
+  const registry =
+    (record['migrations'] as ArtifactMigrationRegistry | undefined) ??
+    createArtifactMigrationRegistry();
+  try {
+    const upgraded = registry.upgrade({
+      envelope: { kind, schemaVersion: storedVersion, report },
+      targetVersion: currentVersion,
+    });
+    const migrated = upgraded.envelope['report'];
+    requireArgumentObject(functionName, `migrated ${subject}`, migrated);
+    return {
+      report: { ...(migrated as Record<string, unknown>), [versionField]: currentVersion },
+      modelMigrationsApplied: upgraded.migrationsApplied,
+    };
+  } catch (error) {
+    if (isQuantError(error, ErrorCode.ArtifactMigrationMissing)) {
+      throw new InputError(
+        `${functionName}: the stored ${subject} is version ${storedVersion} and this build reads ${currentVersion}; no report migration is registered under kind '${kind}' — register one (registry.register({ kind: '${kind}', fromVersion: ${storedVersion}, toVersion: ${storedVersion + 1}, description, migrate })) or recompute from the stored inputs. A migration rewrites shape; it never computes results.`,
+        {
+          code: ErrorCode.ArtifactModelVersionUnsupported,
+          context: { function: functionName, kind, stored: storedVersion, current: currentVersion },
+          cause: error,
+        },
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Prove caller-supplied rows are the referenced table: they must be an array whose canonical
+ * content hash equals the stored handle's. Returns the rows (as given) on success.
+ */
+export function verifyReferencedRows(input: {
+  functionName: string;
+  label: string;
+  handle: TableHandle;
+  rows: unknown;
+}): unknown[] {
+  const record = requireKitRequest(
+    'verifyReferencedRows',
+    input,
+    ['functionName', 'label', 'handle', 'rows'],
+    ['functionName', 'label'],
+  );
+  const functionName = record['functionName'] as string;
+  const label = record['label'] as string;
+  const handle = requireTableHandle('verifyReferencedRows', 'input.handle', record['handle']);
+  const rows = record['rows'];
+  requireArgumentArray(functionName, `referencedData.${label}`, rows);
+  const minted = tableHandleForRows({ rows: rows as unknown[] });
+  if (minted.rowCount !== handle.rowCount) {
+    throw new InputError(
+      `${functionName}: referencedData.${label} has ${minted.rowCount} rows but the artifact's table handle records ${handle.rowCount} — the handle does not describe these rows.`,
+      {
+        code: ErrorCode.ArtifactReferencedDataMismatch,
+        context: {
+          function: functionName,
+          rowSet: label,
+          supplied: minted.rowCount,
+          stored: handle.rowCount,
+        },
+      },
+    );
+  }
+  if (minted.contentHash !== handle.contentHash) {
+    throw new InputError(
+      `${functionName}: referencedData.${label} does not hash to the artifact's table handle (supplied ${minted.contentHash.slice(0, 18)}… over ${(rows as unknown[]).length} rows, stored ${handle.contentHash.slice(0, 18)}… over ${handle.rowCount} rows) — a replay over different data would be a replay of a different run.`,
+      {
+        code: ErrorCode.ArtifactReferencedDataMismatch,
+        context: {
+          function: functionName,
+          rowSet: label,
+          supplied: minted.contentHash,
+          stored: handle.contentHash,
+        },
+      },
+    );
+  }
+  return rows as unknown[];
+}
+
+/**
+ * A validated summary's flat parameter view: arrays become indexed keys (`thetaTerm.theta[2]`).
+ * Takes the whole summary (validated here, like every door) rather than a bare record, so the
+ * parameters it flattens are the ones `requireFittedModelSummary` admits.
+ */
+export function flattenSummaryParameters(
+  summary: FittedModelSummary,
+): Record<string, number | string> {
+  const { parameters } = requireFittedModelSummary('flattenSummaryParameters', 'summary', summary);
+  const out: Record<string, number | string> = {};
+  for (const [key, value] of Object.entries(parameters)) {
+    if (Array.isArray(value))
+      value.forEach((element, index) => (out[`${key}[${index}]`] = element));
+    else out[key] = value;
+  }
+  return out;
+}
+
+/** Count, root-mean-square, and maximum absolute value of a residual list (null statistics when empty). */
+export function residualStatistics(residuals: readonly number[]): {
+  count: number;
+  rootMeanSquare: number | null;
+  maximumAbsolute: number | null;
+} {
+  if (residuals.length === 0) return { count: 0, rootMeanSquare: null, maximumAbsolute: null };
+  let sumSquares = 0;
+  let maximumAbsolute = 0;
+  for (const residual of residuals) {
+    sumSquares += residual * residual;
+    if (Math.abs(residual) > maximumAbsolute) maximumAbsolute = Math.abs(residual);
+  }
+  return {
+    count: residuals.length,
+    rootMeanSquare: Math.sqrt(sumSquares / residuals.length),
+    maximumAbsolute,
+  };
+}