@datakable/core 1.0.1 → 2.0.0

package/dist/ingest/row-key-codes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/row-key-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_DUPLICATE_ROW_KEY: {\n      /** The `rowKey` path; absent for a `rowKey` function. */\n      path?: string\n      /** The first repeated key value (hashed under `'safe'`). */\n      key: string | number\n      /** A sample of the rows sharing `key` (first few, in order; the first keeps its key). */\n      rows: readonly number[]\n      /** How many rows share `key`. */\n      shared: number\n      /** How many rows got a fallback key (all repeated values). */\n      count: number\n      /** How many distinct key values repeat. */\n      groups: number\n      /** `data.length`. */\n      total: number\n      /** Fields unique across all rows (computed by a scan). */\n      unique: readonly string[]\n      /** No unique field: a field that, with the `rowKey` path, makes a unique composite key. */\n      pair?: string\n    }\n    DK_MISSING_ROW_KEY: {\n      /** The `rowKey` path; absent for a `rowKey` function. */\n      path?: string\n      /** A sample of the rows without a usable key (first few, in order). */\n      rows: readonly number[]\n      count: number\n      /** `data.length`. */\n      total: number\n      /** The type of the first unusable value: `undefined`, `null`, `object`, `number(NaN)`, … */\n      valueType: string\n      /** Fields unique across all rows (computed by a scan). */\n      unique: readonly string[]\n    }\n  }\n}\n\nconst n = (x: number) => x.toLocaleString('en-US')\nconst rowList = (rows: readonly number[], total: number) =>\n  rows.map((r) => `#${r}`).join(', ') + (total > rows.length ? ', …' : '')\nconst uniqueFixes = (unique: readonly string[], total: number) =>\n  unique.map((f) => `rowKey: '${f}' (unique in all ${n(total)} rows)`)\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const rowKeyMessages: DiagnosticMessages<'DK_DUPLICATE_ROW_KEY' | 'DK_MISSING_ROW_KEY'> = {\n  DK_DUPLICATE_ROW_KEY: {\n    problem: (d) => {\n      const head =\n        d.path === undefined\n          ? 'the rowKey function returns repeated keys'\n          : `rowKey \"${d.path}\" is not unique`\n      const more = d.groups > 1 ? `${n(d.groups)} values are repeated; ` : ''\n      const what = d.path === undefined ? `key ${d.key}` : `${d.path} = ${d.key}`\n      return `${head}: ${more}rows ${rowList(d.rows, d.shared)} share ${what}`\n    },\n    impact: (d) => {\n      const shown = Math.min(d.shared - 1, 2)\n      const keys = Array.from({ length: shown }, (_, i) => `${d.key}#${i + 1}`).join(', ')\n      const rows = d.count === 1 ? '1 row renders' : `${n(d.count)} rows render`\n      return `${rows} with fallback keys (${keys}${d.count > shown ? ', …' : ''}) — updates may hit the wrong row`\n    },\n    fix: (d) => {\n      const fixes = uniqueFixes(d.unique, d.total)\n      if (d.pair !== undefined && d.path !== undefined) {\n        fixes.push(\n          `rowKey: (row) => \\`\\${row.${d.path}}-\\${row.${d.pair}}\\` (unique in all ${n(d.total)} rows)`,\n        )\n      }\n      if (fixes.length === 0) {\n        fixes.push(\n          `no field is unique across all ${n(d.total)} rows: add a unique id to each row, ` +\n            'or remove the duplicate rows at the source',\n        )\n      }\n      if (d.path === undefined) fixes.push('or make the rowKey function return a unique value')\n      return fixes\n    },\n  },\n  DK_MISSING_ROW_KEY: {\n    problem: (d) => {\n      const rows = `rows ${rowList(d.rows, d.count)}`\n      if (d.path === undefined) {\n        return (\n          `the rowKey function returned no usable key for ${d.count === 1 ? '1 row' : `${n(d.count)} rows`} ` +\n          `(${rows}; the first is ${d.valueType})`\n        )\n      }\n      const has = d.count === 1 ? '1 row has' : `${n(d.count)} rows have`\n      return `${has} no usable key at \"${d.path}\" (${rows}; the first is ${d.valueType})`\n    },\n    impact: () =>\n      \"those rows use the fallback key '#<index>', which changes when rows are added or removed\",\n    fix: (d) => [\n      ...uniqueFixes(d.unique, d.total),\n      d.path === undefined\n        ? 'return a string or a number for every row from the rowKey function'\n        : `give every row a string or a number at \"${d.path}\"`,\n    ],\n  },\n}\n\n/** Codes owned by row-key resolution (§5.2, §8.3). */\nexport const rowKeyDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_DUPLICATE_ROW_KEY',\n      level: 'error',\n      redact: { key: 'rowKey' },\n      where: (d) => ({ kind: 'row', index: d.rows[1] ?? d.rows[0] ?? 0, key: String(d.key) }),\n    },\n    (process.env.NODE_ENV !== \"production\") && rowKeyMessages.DK_DUPLICATE_ROW_KEY,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_MISSING_ROW_KEY',\n      level: 'error',\n      where: (d) => ({ kind: 'row', index: d.rows[0] ?? 0 }),\n    },\n    (process.env.NODE_ENV !== \"production\") && rowKeyMessages.DK_MISSING_ROW_KEY,\n  ),\n]\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/ingest/row-key-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\nimport '../diagnostics/process-guard'\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_DUPLICATE_ROW_KEY: {\n      /** The `rowKey` path; absent for a `rowKey` function. */\n      path?: string\n      /** The first repeated key value (hashed under `'safe'`). */\n      key: string | number\n      /** A sample of the rows sharing `key` (first few, in order; the first keeps its key). */\n      rows: readonly number[]\n      /** How many rows share `key`. */\n      shared: number\n      /** How many rows got a fallback key (all repeated values). */\n      count: number\n      /** How many distinct key values repeat. */\n      groups: number\n      /** `data.length`. */\n      total: number\n      /** Fields unique across all rows (computed by a scan). */\n      unique: readonly string[]\n      /** No unique field: a field that, with the `rowKey` path, makes a unique composite key. */\n      pair?: string\n    }\n    DK_MISSING_ROW_KEY: {\n      /** The `rowKey` path; absent for a `rowKey` function. */\n      path?: string\n      /** A sample of the rows without a usable key (first few, in order). */\n      rows: readonly number[]\n      count: number\n      /** `data.length`. */\n      total: number\n      /** The type of the first unusable value: `undefined`, `null`, `object`, `number(NaN)`, … */\n      valueType: string\n      /** Fields unique across all rows (computed by a scan). */\n      unique: readonly string[]\n    }\n  }\n}\n\nconst n = (x: number) => x.toLocaleString('en-US')\nconst rowList = (rows: readonly number[], total: number) =>\n  rows.map((r) => `#${r}`).join(', ') + (total > rows.length ? ', …' : '')\nconst uniqueFixes = (unique: readonly string[], total: number) =>\n  unique.map((f) => `rowKey: '${f}' (unique in all ${n(total)} rows)`)\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const rowKeyMessages: DiagnosticMessages<'DK_DUPLICATE_ROW_KEY' | 'DK_MISSING_ROW_KEY'> = {\n  DK_DUPLICATE_ROW_KEY: {\n    problem: (d) => {\n      const head =\n        d.path === undefined\n          ? 'the rowKey function returns repeated keys'\n          : `rowKey \"${d.path}\" is not unique`\n      const more = d.groups > 1 ? `${n(d.groups)} values are repeated; ` : ''\n      const what = d.path === undefined ? `key ${d.key}` : `${d.path} = ${d.key}`\n      return `${head}: ${more}rows ${rowList(d.rows, d.shared)} share ${what}`\n    },\n    impact: (d) => {\n      const shown = Math.min(d.shared - 1, 2)\n      const keys = Array.from({ length: shown }, (_, i) => `${d.key}#${i + 1}`).join(', ')\n      const rows = d.count === 1 ? '1 row renders' : `${n(d.count)} rows render`\n      return `${rows} with fallback keys (${keys}${d.count > shown ? ', …' : ''}) — updates may hit the wrong row`\n    },\n    fix: (d) => {\n      const fixes = uniqueFixes(d.unique, d.total)\n      if (d.pair !== undefined && d.path !== undefined) {\n        fixes.push(\n          `rowKey: (row) => \\`\\${row.${d.path}}-\\${row.${d.pair}}\\` (unique in all ${n(d.total)} rows)`,\n        )\n      }\n      if (fixes.length === 0) {\n        fixes.push(\n          `no field is unique across all ${n(d.total)} rows: add a unique id to each row, ` +\n            'or remove the duplicate rows at the source',\n        )\n      }\n      if (d.path === undefined) fixes.push('or make the rowKey function return a unique value')\n      return fixes\n    },\n  },\n  DK_MISSING_ROW_KEY: {\n    problem: (d) => {\n      const rows = `rows ${rowList(d.rows, d.count)}`\n      if (d.path === undefined) {\n        return (\n          `the rowKey function returned no usable key for ${d.count === 1 ? '1 row' : `${n(d.count)} rows`} ` +\n          `(${rows}; the first is ${d.valueType})`\n        )\n      }\n      const has = d.count === 1 ? '1 row has' : `${n(d.count)} rows have`\n      return `${has} no usable key at \"${d.path}\" (${rows}; the first is ${d.valueType})`\n    },\n    impact: () =>\n      \"those rows use the fallback key '#<index>', which changes when rows are added or removed\",\n    fix: (d) => [\n      ...uniqueFixes(d.unique, d.total),\n      d.path === undefined\n        ? 'return a string or a number for every row from the rowKey function'\n        : `give every row a string or a number at \"${d.path}\"`,\n    ],\n  },\n}\n\n/** Codes owned by row-key resolution (§5.2, §8.3). */\nexport const rowKeyDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_DUPLICATE_ROW_KEY',\n      level: 'error',\n      redact: { key: 'rowKey' },\n      where: (d) => ({ kind: 'row', index: d.rows[1] ?? d.rows[0] ?? 0, key: String(d.key) }),\n    },\n    (process.env.NODE_ENV !== \"production\") && rowKeyMessages.DK_DUPLICATE_ROW_KEY,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_MISSING_ROW_KEY',\n      level: 'error',\n      where: (d) => ({ kind: 'row', index: d.rows[0] ?? 0 }),\n    },\n    (process.env.NODE_ENV !== \"production\") && rowKeyMessages.DK_MISSING_ROW_KEY,\n  ),\n]\n"],"mappings":"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","names":[]}

package/dist/ingest/row-key.cjs

@@ -82,46 +82,49 @@ function keyReader(rowKey, onThrow) {
 function scan(data, rowKey, read, emit) {
   const taken = /* @__PURE__ */ new Map();
   const suffix = /* @__PURE__ */ new Map();
-  let fallbacks;
-  const free = (base, from) => {
-    let s = from;
-    let k = `${base}#${s++}`;
-    while (taken.has(k)) k = `${base}#${s++}`;
-    return [k, s];
-  };
   const missing = { count: 0, rows: [], valueType: "" };
   const dup = { count: 0, key: void 0, rows: [], shared: 0 };
+  const pending = [];
   for (let i = 0; i < data.length; i++) {
     const raw = read(data[i], i);
-    let key;
+    const str = String(raw);
     if (!usable(raw)) {
       if (raw !== THREW) {
         if (missing.count === 0) missing.valueType = typeOf(raw);
         if (missing.rows.length < SAMPLE) missing.rows.push(i);
         missing.count++;
       }
-      key = `#${i}`;
-      if (taken.has(key)) key = free(key, 1)[0];
-    } else if (taken.has(raw)) {
+      pending.push([i, `#${i}`]);
+    } else if (taken.has(str)) {
       dup.count++;
       if (dup.key === void 0) {
         dup.key = raw;
-        dup.rows.push(taken.get(raw));
+        dup.rows.push(taken.get(str));
         dup.shared = 1;
       }
-      if (raw === dup.key) {
+      if (str === String(dup.key)) {
         dup.shared++;
         if (dup.rows.length < SAMPLE) dup.rows.push(i);
       }
-      const [k, next] = free(raw, suffix.get(raw) ?? 1);
-      suffix.set(raw, next);
-      key = k;
+      suffix.set(str, 1);
+      pending.push([i, str]);
     } else {
-      taken.set(raw, i);
-      continue;
+      taken.set(str, i);
+    }
+  }
+  const groups = suffix.size;
+  let fallbacks;
+  for (const [i, base] of pending) {
+    let key = base;
+    if (taken.has(key)) {
+      let n = suffix.get(base) ?? 1;
+      do
+        key = `${base}#${n++}`;
+      while (taken.has(key));
+      suffix.set(base, n);
     }
     taken.set(key, i);
-    if (fallbacks === void 0) fallbacks = /* @__PURE__ */ new Map();
+    fallbacks ??= /* @__PURE__ */ new Map();
     fallbacks.set(i, key);
   }
   if (dup.key !== void 0 || missing.count > 0) {
@@ -135,7 +138,7 @@ function scan(data, rowKey, read, emit) {
         rows: dup.rows,
         shared: dup.shared,
         count: dup.count,
-        groups: suffix.size,
+        groups,
         total: data.length,
         unique: found.unique,
         ...found.pair === void 0 ? {} : { pair: found.pair }

package/dist/ingest/row-key.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/row-key.ts"],"sourcesContent":["import { compilePath, getValue } from '../column/get-value'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport type { Emit } from '../diagnostics/types'\nimport type { RowKey } from '../pipeline/row'\nimport { rowKeyDiagnostics } from './row-key-codes'\nimport { findUniqueFields } from './unique-fields'\n\nkeepDiagnostics(rowKeyDiagnostics)\n\n/** Rows listed in a diagnostic's `rows` sample. */\nconst SAMPLE = 5\n\n/** `(row, index) => key` for the rows the pipeline builds. */\nexport type KeyOf = (row: unknown, index: number) => RowKey\n\nconst usable = (k: unknown): k is RowKey =>\n  typeof k === 'string' || (typeof k === 'number' && !Number.isNaN(k))\n\nconst THREW: unique symbol = Symbol('threw')\n\nconst typeOf = (v: unknown): string => {\n  if (v === null) return 'null'\n  if (Array.isArray(v)) return 'array'\n  return typeof v === 'number' ? 'number(NaN)' : typeof v\n}\n\n/**\n * Resolves `rowKey` (§5.2) over **all** rows, once per (data, rowKey) reference, so keys do not\n * change with filtering, sorting or paging:\n *\n * - a repeated key: the first row keeps it, later rows get `key#1`, `key#2`, …\n *   (`DK_DUPLICATE_ROW_KEY`, whose `fix` names fields that are unique across all rows);\n * - a missing / `null` / non-string-or-number key: `#index` (`DK_MISSING_ROW_KEY`);\n * - a throwing `rowKey` function: `#index`, passed to `onThrow` (reported by the runner as\n *   `DK_CALLBACK_FAILED`, as in T09).\n *\n * Only the rows that need a fallback are remembered; the returned reader re-reads the key of the\n * (visible) rows it is asked for, so a clean data set keeps no per-row memory. Without `rowKey`,\n * the key is the row index.\n */\nexport function resolveRowKeys(\n  data: readonly unknown[],\n  rowKey: unknown,\n  emit: Emit,\n  onThrow: (index: number, error: unknown) => void,\n): KeyOf {\n  const read = keyReader(rowKey, onThrow)\n  if (read === undefined) return (_row, index) => index\n  const fallbacks = scan(data, rowKey, read, emit)\n  return (row, index) => {\n    const f = fallbacks?.get(index)\n    if (f !== undefined) return f\n    const k = read(row, index)\n    return usable(k) ? k : `#${index}`\n  }\n}\n\ntype Read = (row: unknown, index: number) => unknown\n\nfunction keyReader(\n  rowKey: unknown,\n  onThrow: (index: number, error: unknown) => void,\n): Read | undefined {\n  let read: Read\n  if (typeof rowKey === 'function') {\n    const fn = rowKey as (row: unknown) => unknown\n    read = (row, index) => {\n      try {\n        return fn(row)\n      } catch (e) {\n        onThrow(index, e)\n        return THREW\n      }\n    }\n  } else if (typeof rowKey === 'string') {\n    const path = compilePath(rowKey)\n    let cur = 0\n    let threw = false\n    const onError = (e: unknown) => {\n      threw = true\n      onThrow(cur, e)\n    }\n    read = (row, index) => {\n      cur = index\n      const k = getValue(row, path, onError)\n      if (!threw) return k\n      threw = false\n      return THREW\n    }\n  } else {\n    return undefined\n  }\n  return read\n}\n\n/**\n * One pass over every row: returns the fallback keys (only the rows that need one) and emits the\n * key diagnostics. Kept apart from the returned reader so the scan's maps are not captured by it.\n */\nfunction scan(\n  data: readonly unknown[],\n  rowKey: unknown,\n  read: Read,\n  emit: Emit,\n): Map<number, RowKey> | undefined {\n  /** Every key handed out so far (raw keys and fallbacks) → the row that holds it. */\n  const taken = new Map<RowKey, number>()\n  /** Repeated raw key → the next `#n` to try. */\n  const suffix = new Map<RowKey, number>()\n  /** Only the rows that got a fallback key. */\n  let fallbacks: Map<number, RowKey> | undefined\n  /** `base#n` for the first free `n ≥ from` (a fallback can collide with a real key). */\n  const free = (base: RowKey, from: number): [RowKey, number] => {\n    let s = from\n    let k: RowKey = `${base}#${s++}`\n    while (taken.has(k)) k = `${base}#${s++}`\n    return [k, s]\n  }\n\n  const missing = { count: 0, rows: [] as number[], valueType: '' }\n  const dup = { count: 0, key: undefined as RowKey | undefined, rows: [] as number[], shared: 0 }\n\n  for (let i = 0; i < data.length; i++) {\n    const raw = read(data[i], i)\n    let key: RowKey\n    if (!usable(raw)) {\n      if (raw !== THREW) {\n        if (missing.count === 0) missing.valueType = typeOf(raw)\n        if (missing.rows.length < SAMPLE) missing.rows.push(i)\n        missing.count++\n      }\n      key = `#${i}`\n      if (taken.has(key)) key = free(key, 1)[0]\n    } else if (taken.has(raw)) {\n      dup.count++\n      if (dup.key === undefined) {\n        dup.key = raw\n        dup.rows.push(taken.get(raw) as number)\n        dup.shared = 1\n      }\n      if (raw === dup.key) {\n        dup.shared++\n        if (dup.rows.length < SAMPLE) dup.rows.push(i)\n      }\n      const [k, next] = free(raw, suffix.get(raw) ?? 1)\n      suffix.set(raw, next)\n      key = k\n    } else {\n      taken.set(raw, i)\n      continue\n    }\n    taken.set(key, i)\n    if (fallbacks === undefined) fallbacks = new Map()\n    fallbacks.set(i, key)\n  }\n\n  if (dup.key !== undefined || missing.count > 0) {\n    // Error path only: the fix is computed from the data (a scan per candidate field).\n    const path = typeof rowKey === 'string' ? rowKey : undefined\n    const at = path === undefined ? {} : { path }\n    if (dup.key !== undefined) {\n      const found = findUniqueFields(data, path)\n      emit('DK_DUPLICATE_ROW_KEY', {\n        ...at,\n        key: dup.key,\n        rows: dup.rows,\n        shared: dup.shared,\n        count: dup.count,\n        groups: suffix.size,\n        total: data.length,\n        unique: found.unique,\n        ...(found.pair === undefined ? {} : { pair: found.pair }),\n      })\n    }\n    if (missing.count > 0) {\n      emit('DK_MISSING_ROW_KEY', {\n        ...at,\n        rows: missing.rows,\n        count: missing.count,\n        total: data.length,\n        valueType: missing.valueType,\n        unique: findUniqueFields(data, path, undefined).unique,\n      })\n    }\n  }\n\n  return fallbacks\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/ingest/row-key.ts"],"sourcesContent":["import { compilePath, getValue } from '../column/get-value'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport type { Emit } from '../diagnostics/types'\nimport type { RowKey } from '../pipeline/row'\nimport { rowKeyDiagnostics } from './row-key-codes'\nimport { findUniqueFields } from './unique-fields'\n\nkeepDiagnostics(rowKeyDiagnostics)\n\n/** Rows listed in a diagnostic's `rows` sample. */\nconst SAMPLE = 5\n\n/** `(row, index) => key` for the rows the pipeline builds. */\nexport type KeyOf = (row: unknown, index: number) => RowKey\n\nconst usable = (k: unknown): k is RowKey =>\n  typeof k === 'string' || (typeof k === 'number' && !Number.isNaN(k))\n\nconst THREW: unique symbol = Symbol('threw')\n\nconst typeOf = (v: unknown): string => {\n  if (v === null) return 'null'\n  if (Array.isArray(v)) return 'array'\n  return typeof v === 'number' ? 'number(NaN)' : typeof v\n}\n\n/**\n * Resolves `rowKey` (§5.2) over **all** rows, once per (data, rowKey) reference, so keys do not\n * change with filtering, sorting or paging:\n *\n * - a repeated key: the first row keeps it, later rows get `key#1`, `key#2`, …\n *   (`DK_DUPLICATE_ROW_KEY`, whose `fix` names fields that are unique across all rows). Keys are\n *   compared as strings (`1` repeats `'1'`), as React keys and `explainRow` compare them;\n * - a missing / `null` / non-string-or-number key: `#index` (`DK_MISSING_ROW_KEY`);\n * - a throwing `rowKey` function: `#index`, passed to `onThrow` (reported by the runner as\n *   `DK_CALLBACK_FAILED`, as in T09).\n *\n * Only the rows that need a fallback are remembered; the returned reader re-reads the key of the\n * (visible) rows it is asked for, so a clean data set keeps no per-row memory. Without `rowKey`,\n * the key is the row index.\n */\nexport function resolveRowKeys(\n  data: readonly unknown[],\n  rowKey: unknown,\n  emit: Emit,\n  onThrow: (index: number, error: unknown) => void,\n): KeyOf {\n  const read = keyReader(rowKey, onThrow)\n  if (read === undefined) return (_row, index) => index\n  const fallbacks = scan(data, rowKey, read, emit)\n  return (row, index) => {\n    const f = fallbacks?.get(index)\n    if (f !== undefined) return f\n    const k = read(row, index)\n    return usable(k) ? k : `#${index}`\n  }\n}\n\ntype Read = (row: unknown, index: number) => unknown\n\nfunction keyReader(\n  rowKey: unknown,\n  onThrow: (index: number, error: unknown) => void,\n): Read | undefined {\n  let read: Read\n  if (typeof rowKey === 'function') {\n    const fn = rowKey as (row: unknown) => unknown\n    read = (row, index) => {\n      try {\n        return fn(row)\n      } catch (e) {\n        onThrow(index, e)\n        return THREW\n      }\n    }\n  } else if (typeof rowKey === 'string') {\n    const path = compilePath(rowKey)\n    let cur = 0\n    let threw = false\n    const onError = (e: unknown) => {\n      threw = true\n      onThrow(cur, e)\n    }\n    read = (row, index) => {\n      cur = index\n      const k = getValue(row, path, onError)\n      if (!threw) return k\n      threw = false\n      return THREW\n    }\n  } else {\n    return undefined\n  }\n  return read\n}\n\n/**\n * One pass over every row, then one over the rows that need a fallback key: returns those keys\n * and emits the key diagnostics. Kept apart from the returned reader so the scan's maps are not\n * captured by it.\n */\nfunction scan(\n  data: readonly unknown[],\n  rowKey: unknown,\n  read: Read,\n  emit: Emit,\n): Map<number, RowKey> | undefined {\n  /** Every key handed out so far (raw keys and fallbacks), as a string → the row that holds it. */\n  const taken = new Map<string, number>()\n  /** Repeated raw key, as a string → the next `#n` to try. */\n  const suffix = new Map<string, number>()\n  const missing = { count: 0, rows: [] as number[], valueType: '' }\n  const dup = { count: 0, key: undefined as RowKey | undefined, rows: [] as number[], shared: 0 }\n  /** Rows that need a fallback: [index, the base it is built on (`#index` or the repeated key)]. */\n  const pending: [number, string][] = []\n\n  for (let i = 0; i < data.length; i++) {\n    const raw = read(data[i], i)\n    const str = String(raw)\n    if (!usable(raw)) {\n      if (raw !== THREW) {\n        if (missing.count === 0) missing.valueType = typeOf(raw)\n        if (missing.rows.length < SAMPLE) missing.rows.push(i)\n        missing.count++\n      }\n      pending.push([i, `#${i}`])\n    } else if (taken.has(str)) {\n      dup.count++\n      if (dup.key === undefined) {\n        dup.key = raw\n        dup.rows.push(taken.get(str) as number)\n        dup.shared = 1\n      }\n      if (str === String(dup.key)) {\n        dup.shared++\n        if (dup.rows.length < SAMPLE) dup.rows.push(i)\n      }\n      suffix.set(str, 1)\n      pending.push([i, str])\n    } else {\n      taken.set(str, i)\n    }\n  }\n  const groups = suffix.size\n\n  // Fallbacks only once every real key is taken, so none takes the key of a later row: `base#n`\n  // for the first free `n` (a missing row's `#index` itself when free).\n  let fallbacks: Map<number, RowKey> | undefined\n  for (const [i, base] of pending) {\n    let key = base\n    if (taken.has(key)) {\n      let n = suffix.get(base) ?? 1\n      do key = `${base}#${n++}`\n      while (taken.has(key))\n      suffix.set(base, n)\n    }\n    taken.set(key, i)\n    fallbacks ??= new Map()\n    fallbacks.set(i, key)\n  }\n\n  if (dup.key !== undefined || missing.count > 0) {\n    // Error path only: the fix is computed from the data (a scan per candidate field).\n    const path = typeof rowKey === 'string' ? rowKey : undefined\n    const at = path === undefined ? {} : { path }\n    if (dup.key !== undefined) {\n      const found = findUniqueFields(data, path)\n      emit('DK_DUPLICATE_ROW_KEY', {\n        ...at,\n        key: dup.key,\n        rows: dup.rows,\n        shared: dup.shared,\n        count: dup.count,\n        groups,\n        total: data.length,\n        unique: found.unique,\n        ...(found.pair === undefined ? {} : { pair: found.pair }),\n      })\n    }\n    if (missing.count > 0) {\n      emit('DK_MISSING_ROW_KEY', {\n        ...at,\n        rows: missing.rows,\n        count: missing.count,\n        total: data.length,\n        valueType: missing.valueType,\n        unique: findUniqueFields(data, path, undefined).unique,\n      })\n    }\n  }\n\n  return fallbacks\n}\n"],"mappings":"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","names":[]}

package/dist/ingest/row-key.js

@@ -58,46 +58,49 @@ function keyReader(rowKey, onThrow) {
 function scan(data, rowKey, read, emit) {
   const taken = /* @__PURE__ */ new Map();
   const suffix = /* @__PURE__ */ new Map();
-  let fallbacks;
-  const free = (base, from) => {
-    let s = from;
-    let k = `${base}#${s++}`;
-    while (taken.has(k)) k = `${base}#${s++}`;
-    return [k, s];
-  };
   const missing = { count: 0, rows: [], valueType: "" };
   const dup = { count: 0, key: void 0, rows: [], shared: 0 };
+  const pending = [];
   for (let i = 0; i < data.length; i++) {
     const raw = read(data[i], i);
-    let key;
+    const str = String(raw);
     if (!usable(raw)) {
       if (raw !== THREW) {
         if (missing.count === 0) missing.valueType = typeOf(raw);
         if (missing.rows.length < SAMPLE) missing.rows.push(i);
         missing.count++;
       }
-      key = `#${i}`;
-      if (taken.has(key)) key = free(key, 1)[0];
-    } else if (taken.has(raw)) {
+      pending.push([i, `#${i}`]);
+    } else if (taken.has(str)) {
       dup.count++;
       if (dup.key === void 0) {
         dup.key = raw;
-        dup.rows.push(taken.get(raw));
+        dup.rows.push(taken.get(str));
         dup.shared = 1;
       }
-      if (raw === dup.key) {
+      if (str === String(dup.key)) {
         dup.shared++;
         if (dup.rows.length < SAMPLE) dup.rows.push(i);
       }
-      const [k, next] = free(raw, suffix.get(raw) ?? 1);
-      suffix.set(raw, next);
-      key = k;
+      suffix.set(str, 1);
+      pending.push([i, str]);
     } else {
-      taken.set(raw, i);
-      continue;
+      taken.set(str, i);
+    }
+  }
+  const groups = suffix.size;
+  let fallbacks;
+  for (const [i, base] of pending) {
+    let key = base;
+    if (taken.has(key)) {
+      let n = suffix.get(base) ?? 1;
+      do
+        key = `${base}#${n++}`;
+      while (taken.has(key));
+      suffix.set(base, n);
     }
     taken.set(key, i);
-    if (fallbacks === void 0) fallbacks = /* @__PURE__ */ new Map();
+    fallbacks ??= /* @__PURE__ */ new Map();
     fallbacks.set(i, key);
   }
   if (dup.key !== void 0 || missing.count > 0) {
@@ -111,7 +114,7 @@ function scan(data, rowKey, read, emit) {
         rows: dup.rows,
         shared: dup.shared,
         count: dup.count,
-        groups: suffix.size,
+        groups,
         total: data.length,
         unique: found.unique,
         ...found.pair === void 0 ? {} : { pair: found.pair }

package/dist/ingest/row-key.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/row-key.ts"],"sourcesContent":["import { compilePath, getValue } from '../column/get-value'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport type { Emit } from '../diagnostics/types'\nimport type { RowKey } from '../pipeline/row'\nimport { rowKeyDiagnostics } from './row-key-codes'\nimport { findUniqueFields } from './unique-fields'\n\nkeepDiagnostics(rowKeyDiagnostics)\n\n/** Rows listed in a diagnostic's `rows` sample. */\nconst SAMPLE = 5\n\n/** `(row, index) => key` for the rows the pipeline builds. */\nexport type KeyOf = (row: unknown, index: number) => RowKey\n\nconst usable = (k: unknown): k is RowKey =>\n  typeof k === 'string' || (typeof k === 'number' && !Number.isNaN(k))\n\nconst THREW: unique symbol = Symbol('threw')\n\nconst typeOf = (v: unknown): string => {\n  if (v === null) return 'null'\n  if (Array.isArray(v)) return 'array'\n  return typeof v === 'number' ? 'number(NaN)' : typeof v\n}\n\n/**\n * Resolves `rowKey` (§5.2) over **all** rows, once per (data, rowKey) reference, so keys do not\n * change with filtering, sorting or paging:\n *\n * - a repeated key: the first row keeps it, later rows get `key#1`, `key#2`, …\n *   (`DK_DUPLICATE_ROW_KEY`, whose `fix` names fields that are unique across all rows);\n * - a missing / `null` / non-string-or-number key: `#index` (`DK_MISSING_ROW_KEY`);\n * - a throwing `rowKey` function: `#index`, passed to `onThrow` (reported by the runner as\n *   `DK_CALLBACK_FAILED`, as in T09).\n *\n * Only the rows that need a fallback are remembered; the returned reader re-reads the key of the\n * (visible) rows it is asked for, so a clean data set keeps no per-row memory. Without `rowKey`,\n * the key is the row index.\n */\nexport function resolveRowKeys(\n  data: readonly unknown[],\n  rowKey: unknown,\n  emit: Emit,\n  onThrow: (index: number, error: unknown) => void,\n): KeyOf {\n  const read = keyReader(rowKey, onThrow)\n  if (read === undefined) return (_row, index) => index\n  const fallbacks = scan(data, rowKey, read, emit)\n  return (row, index) => {\n    const f = fallbacks?.get(index)\n    if (f !== undefined) return f\n    const k = read(row, index)\n    return usable(k) ? k : `#${index}`\n  }\n}\n\ntype Read = (row: unknown, index: number) => unknown\n\nfunction keyReader(\n  rowKey: unknown,\n  onThrow: (index: number, error: unknown) => void,\n): Read | undefined {\n  let read: Read\n  if (typeof rowKey === 'function') {\n    const fn = rowKey as (row: unknown) => unknown\n    read = (row, index) => {\n      try {\n        return fn(row)\n      } catch (e) {\n        onThrow(index, e)\n        return THREW\n      }\n    }\n  } else if (typeof rowKey === 'string') {\n    const path = compilePath(rowKey)\n    let cur = 0\n    let threw = false\n    const onError = (e: unknown) => {\n      threw = true\n      onThrow(cur, e)\n    }\n    read = (row, index) => {\n      cur = index\n      const k = getValue(row, path, onError)\n      if (!threw) return k\n      threw = false\n      return THREW\n    }\n  } else {\n    return undefined\n  }\n  return read\n}\n\n/**\n * One pass over every row: returns the fallback keys (only the rows that need one) and emits the\n * key diagnostics. Kept apart from the returned reader so the scan's maps are not captured by it.\n */\nfunction scan(\n  data: readonly unknown[],\n  rowKey: unknown,\n  read: Read,\n  emit: Emit,\n): Map<number, RowKey> | undefined {\n  /** Every key handed out so far (raw keys and fallbacks) → the row that holds it. */\n  const taken = new Map<RowKey, number>()\n  /** Repeated raw key → the next `#n` to try. */\n  const suffix = new Map<RowKey, number>()\n  /** Only the rows that got a fallback key. */\n  let fallbacks: Map<number, RowKey> | undefined\n  /** `base#n` for the first free `n ≥ from` (a fallback can collide with a real key). */\n  const free = (base: RowKey, from: number): [RowKey, number] => {\n    let s = from\n    let k: RowKey = `${base}#${s++}`\n    while (taken.has(k)) k = `${base}#${s++}`\n    return [k, s]\n  }\n\n  const missing = { count: 0, rows: [] as number[], valueType: '' }\n  const dup = { count: 0, key: undefined as RowKey | undefined, rows: [] as number[], shared: 0 }\n\n  for (let i = 0; i < data.length; i++) {\n    const raw = read(data[i], i)\n    let key: RowKey\n    if (!usable(raw)) {\n      if (raw !== THREW) {\n        if (missing.count === 0) missing.valueType = typeOf(raw)\n        if (missing.rows.length < SAMPLE) missing.rows.push(i)\n        missing.count++\n      }\n      key = `#${i}`\n      if (taken.has(key)) key = free(key, 1)[0]\n    } else if (taken.has(raw)) {\n      dup.count++\n      if (dup.key === undefined) {\n        dup.key = raw\n        dup.rows.push(taken.get(raw) as number)\n        dup.shared = 1\n      }\n      if (raw === dup.key) {\n        dup.shared++\n        if (dup.rows.length < SAMPLE) dup.rows.push(i)\n      }\n      const [k, next] = free(raw, suffix.get(raw) ?? 1)\n      suffix.set(raw, next)\n      key = k\n    } else {\n      taken.set(raw, i)\n      continue\n    }\n    taken.set(key, i)\n    if (fallbacks === undefined) fallbacks = new Map()\n    fallbacks.set(i, key)\n  }\n\n  if (dup.key !== undefined || missing.count > 0) {\n    // Error path only: the fix is computed from the data (a scan per candidate field).\n    const path = typeof rowKey === 'string' ? rowKey : undefined\n    const at = path === undefined ? {} : { path }\n    if (dup.key !== undefined) {\n      const found = findUniqueFields(data, path)\n      emit('DK_DUPLICATE_ROW_KEY', {\n        ...at,\n        key: dup.key,\n        rows: dup.rows,\n        shared: dup.shared,\n        count: dup.count,\n        groups: suffix.size,\n        total: data.length,\n        unique: found.unique,\n        ...(found.pair === undefined ? {} : { pair: found.pair }),\n      })\n    }\n    if (missing.count > 0) {\n      emit('DK_MISSING_ROW_KEY', {\n        ...at,\n        rows: missing.rows,\n        count: missing.count,\n        total: data.length,\n        valueType: missing.valueType,\n        unique: findUniqueFields(data, path, undefined).unique,\n      })\n    }\n  }\n\n  return fallbacks\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/ingest/row-key.ts"],"sourcesContent":["import { compilePath, getValue } from '../column/get-value'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport type { Emit } from '../diagnostics/types'\nimport type { RowKey } from '../pipeline/row'\nimport { rowKeyDiagnostics } from './row-key-codes'\nimport { findUniqueFields } from './unique-fields'\n\nkeepDiagnostics(rowKeyDiagnostics)\n\n/** Rows listed in a diagnostic's `rows` sample. */\nconst SAMPLE = 5\n\n/** `(row, index) => key` for the rows the pipeline builds. */\nexport type KeyOf = (row: unknown, index: number) => RowKey\n\nconst usable = (k: unknown): k is RowKey =>\n  typeof k === 'string' || (typeof k === 'number' && !Number.isNaN(k))\n\nconst THREW: unique symbol = Symbol('threw')\n\nconst typeOf = (v: unknown): string => {\n  if (v === null) return 'null'\n  if (Array.isArray(v)) return 'array'\n  return typeof v === 'number' ? 'number(NaN)' : typeof v\n}\n\n/**\n * Resolves `rowKey` (§5.2) over **all** rows, once per (data, rowKey) reference, so keys do not\n * change with filtering, sorting or paging:\n *\n * - a repeated key: the first row keeps it, later rows get `key#1`, `key#2`, …\n *   (`DK_DUPLICATE_ROW_KEY`, whose `fix` names fields that are unique across all rows). Keys are\n *   compared as strings (`1` repeats `'1'`), as React keys and `explainRow` compare them;\n * - a missing / `null` / non-string-or-number key: `#index` (`DK_MISSING_ROW_KEY`);\n * - a throwing `rowKey` function: `#index`, passed to `onThrow` (reported by the runner as\n *   `DK_CALLBACK_FAILED`, as in T09).\n *\n * Only the rows that need a fallback are remembered; the returned reader re-reads the key of the\n * (visible) rows it is asked for, so a clean data set keeps no per-row memory. Without `rowKey`,\n * the key is the row index.\n */\nexport function resolveRowKeys(\n  data: readonly unknown[],\n  rowKey: unknown,\n  emit: Emit,\n  onThrow: (index: number, error: unknown) => void,\n): KeyOf {\n  const read = keyReader(rowKey, onThrow)\n  if (read === undefined) return (_row, index) => index\n  const fallbacks = scan(data, rowKey, read, emit)\n  return (row, index) => {\n    const f = fallbacks?.get(index)\n    if (f !== undefined) return f\n    const k = read(row, index)\n    return usable(k) ? k : `#${index}`\n  }\n}\n\ntype Read = (row: unknown, index: number) => unknown\n\nfunction keyReader(\n  rowKey: unknown,\n  onThrow: (index: number, error: unknown) => void,\n): Read | undefined {\n  let read: Read\n  if (typeof rowKey === 'function') {\n    const fn = rowKey as (row: unknown) => unknown\n    read = (row, index) => {\n      try {\n        return fn(row)\n      } catch (e) {\n        onThrow(index, e)\n        return THREW\n      }\n    }\n  } else if (typeof rowKey === 'string') {\n    const path = compilePath(rowKey)\n    let cur = 0\n    let threw = false\n    const onError = (e: unknown) => {\n      threw = true\n      onThrow(cur, e)\n    }\n    read = (row, index) => {\n      cur = index\n      const k = getValue(row, path, onError)\n      if (!threw) return k\n      threw = false\n      return THREW\n    }\n  } else {\n    return undefined\n  }\n  return read\n}\n\n/**\n * One pass over every row, then one over the rows that need a fallback key: returns those keys\n * and emits the key diagnostics. Kept apart from the returned reader so the scan's maps are not\n * captured by it.\n */\nfunction scan(\n  data: readonly unknown[],\n  rowKey: unknown,\n  read: Read,\n  emit: Emit,\n): Map<number, RowKey> | undefined {\n  /** Every key handed out so far (raw keys and fallbacks), as a string → the row that holds it. */\n  const taken = new Map<string, number>()\n  /** Repeated raw key, as a string → the next `#n` to try. */\n  const suffix = new Map<string, number>()\n  const missing = { count: 0, rows: [] as number[], valueType: '' }\n  const dup = { count: 0, key: undefined as RowKey | undefined, rows: [] as number[], shared: 0 }\n  /** Rows that need a fallback: [index, the base it is built on (`#index` or the repeated key)]. */\n  const pending: [number, string][] = []\n\n  for (let i = 0; i < data.length; i++) {\n    const raw = read(data[i], i)\n    const str = String(raw)\n    if (!usable(raw)) {\n      if (raw !== THREW) {\n        if (missing.count === 0) missing.valueType = typeOf(raw)\n        if (missing.rows.length < SAMPLE) missing.rows.push(i)\n        missing.count++\n      }\n      pending.push([i, `#${i}`])\n    } else if (taken.has(str)) {\n      dup.count++\n      if (dup.key === undefined) {\n        dup.key = raw\n        dup.rows.push(taken.get(str) as number)\n        dup.shared = 1\n      }\n      if (str === String(dup.key)) {\n        dup.shared++\n        if (dup.rows.length < SAMPLE) dup.rows.push(i)\n      }\n      suffix.set(str, 1)\n      pending.push([i, str])\n    } else {\n      taken.set(str, i)\n    }\n  }\n  const groups = suffix.size\n\n  // Fallbacks only once every real key is taken, so none takes the key of a later row: `base#n`\n  // for the first free `n` (a missing row's `#index` itself when free).\n  let fallbacks: Map<number, RowKey> | undefined\n  for (const [i, base] of pending) {\n    let key = base\n    if (taken.has(key)) {\n      let n = suffix.get(base) ?? 1\n      do key = `${base}#${n++}`\n      while (taken.has(key))\n      suffix.set(base, n)\n    }\n    taken.set(key, i)\n    fallbacks ??= new Map()\n    fallbacks.set(i, key)\n  }\n\n  if (dup.key !== undefined || missing.count > 0) {\n    // Error path only: the fix is computed from the data (a scan per candidate field).\n    const path = typeof rowKey === 'string' ? rowKey : undefined\n    const at = path === undefined ? {} : { path }\n    if (dup.key !== undefined) {\n      const found = findUniqueFields(data, path)\n      emit('DK_DUPLICATE_ROW_KEY', {\n        ...at,\n        key: dup.key,\n        rows: dup.rows,\n        shared: dup.shared,\n        count: dup.count,\n        groups,\n        total: data.length,\n        unique: found.unique,\n        ...(found.pair === undefined ? {} : { pair: found.pair }),\n      })\n    }\n    if (missing.count > 0) {\n      emit('DK_MISSING_ROW_KEY', {\n        ...at,\n        rows: missing.rows,\n        count: missing.count,\n        total: data.length,\n        valueType: missing.valueType,\n        unique: findUniqueFields(data, path, undefined).unique,\n      })\n    }\n  }\n\n  return fallbacks\n}\n"],"mappings":"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","names":[]}

package/dist/ingest/schema-codes.cjs

@@ -25,6 +25,7 @@ __export(schema_codes_exports, {
 });
 module.exports = __toCommonJS(schema_codes_exports);
 var import_catalog = require("../diagnostics/catalog.cjs");
+var import_process_guard = require("../diagnostics/process-guard.cjs");
 var rowList = (rows, count) => {
   const list = rows.map((r) => `#${r}`).join(", ");
   return count > rows.length ? `${list}, \u2026` : list;

package/dist/ingest/schema-codes.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/schema-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\n\n/** `options.invalidRows` (§5.1). */\nexport type InvalidRowsMode = 'drop' | 'flag' | 'throw'\n\n/** An issue path matched to a column (`DK_SCHEMA_INVALID_ROW.columns`). */\nexport interface SchemaIssueColumn {\n  /** The issue path, dot-joined (`address.city`; `''` for the row itself). */\n  readonly path: string\n  /** The column whose key is or contains the path, if one does. */\n  readonly column?: string\n  /** That column's position in `options.columns`. */\n  readonly index?: number\n  /** Invalid rows with an issue at this path. */\n  readonly count: number\n}\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_SCHEMA_INVALID_ROW: {\n      mode: InvalidRowsMode\n      /** Rows with issues. */\n      count: number\n      /** Rows validated. */\n      total: number\n      /** A sample of the invalid rows' indices in `options.data` (first few, in order). */\n      rows: readonly number[]\n      /** The first issue of each sampled row (redacted: `scrubSchemaIssue`). */\n      issues: readonly unknown[]\n      /** Issue paths with their column, most frequent first (at most a few). */\n      columns: readonly SchemaIssueColumn[]\n    }\n    DK_SCHEMA_CRASHED: {\n      mode: InvalidRowsMode\n      /** Rows for which `validate` threw or rejected. */\n      count: number\n      rows: readonly number[]\n      /** `error.name` of the first failure; the error itself is `context.cause`. */\n      errorName?: string\n    }\n  }\n}\n\nconst rowList = (rows: readonly number[], count: number) => {\n  const list = rows.map((r) => `#${r}`).join(', ')\n  return count > rows.length ? `${list}, …` : list\n}\n\nconst plural = (n: number, one: string) => `${n} ${one}${n === 1 ? '' : 's'}`\n\nconst handled = (mode: InvalidRowsMode, rows: string) => {\n  switch (mode) {\n    case 'drop':\n      return `${rows} removed from the table (getInvalidRows() lists them)`\n    case 'flag':\n      return `${rows} kept with row.valid === false and row.issues (cell / invalidCell must handle them)`\n    case 'throw':\n      return 'DatakableSchemaError was thrown; the previous data was kept'\n  }\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const schemaMessages: DiagnosticMessages<'DK_SCHEMA_INVALID_ROW' | 'DK_SCHEMA_CRASHED'> = {\n  DK_SCHEMA_INVALID_ROW: {\n    problem: (d) =>\n      `${d.count} of ${plural(d.total, 'row')} failed schema validation ` +\n      `(rows ${rowList(d.rows, d.count)})`,\n    impact: (d) => handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: (d) => {\n      const out: string[] = []\n      for (const c of d.columns) {\n        const at = c.path === '' ? 'the row itself' : `\"${c.path}\"`\n        const col =\n          c.column === undefined\n            ? 'no column shows it'\n            : `column \"${c.column}\" (columns[${c.index}])`\n        out.push(\n          `${plural(c.count, 'row')} fail at ${at}, ${col}: fix the data source there, ` +\n            `or relax the schema at ${at}`,\n        )\n      }\n      if (d.mode === 'drop') {\n        out.push(\n          \"use invalidRows: 'flag' to keep and show the invalid rows instead of dropping them\",\n        )\n      }\n      if (d.mode === 'throw') {\n        out.push(\"use invalidRows: 'drop' or 'flag' to keep the table usable with invalid rows\")\n      }\n      out.push('inspect them with table.getInvalidRows() (index, raw value and issues per row)')\n      return out\n    },\n  },\n  DK_SCHEMA_CRASHED: {\n    problem: (d) =>\n      `the schema threw${d.errorName ? ` ${d.errorName}` : ''} instead of returning issues ` +\n      `for ${plural(d.count, 'row')} (rows ${rowList(d.rows, d.count)})`,\n    impact: (d) =>\n      `each such row got a synthetic issue and was treated as invalid: ` +\n      handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: () => [\n      'find the throwing refinement / transform in the schema: the original error is ' +\n        'context.cause (passed to onDiagnostic)',\n      'make custom checks return an issue (e.g. ctx.addIssue / a refine predicate) instead of ' +\n        'throwing on unexpected input',\n    ],\n  },\n}\n\n/** Codes owned by the schema ingest (§5.1, §8.3). */\nexport const schemaDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_INVALID_ROW',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n      redact: { issues: 'schemaIssues' },\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_INVALID_ROW,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_CRASHED',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_CRASHED,\n  ),\n]\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA0D;AA2C1D,IAAM,UAAU,CAAC,MAAyB,UAAkB;AAC1D,QAAM,OAAO,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI;AAC/C,SAAO,QAAQ,KAAK,SAAS,GAAG,IAAI,aAAQ;AAC9C;AAEA,IAAM,SAAS,CAAC,GAAW,QAAgB,GAAG,CAAC,IAAI,GAAG,GAAG,MAAM,IAAI,KAAK,GAAG;AAE3E,IAAM,UAAU,CAAC,MAAuB,SAAiB;AACvD,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAGO,IAAM,iBAAoF;AAAA,EAC/F,uBAAuB;AAAA,IACrB,SAAS,CAAC,MACR,GAAG,EAAE,KAAK,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC,mCAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACnC,QAAQ,CAAC,MAAM,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACjF,KAAK,CAAC,MAAM;AACV,YAAM,MAAgB,CAAC;AACvB,iBAAW,KAAK,EAAE,SAAS;AACzB,cAAM,KAAK,EAAE,SAAS,KAAK,mBAAmB,IAAI,EAAE,IAAI;AACxD,cAAM,MACJ,EAAE,WAAW,SACT,uBACA,WAAW,EAAE,MAAM,cAAc,EAAE,KAAK;AAC9C,YAAI;AAAA,UACF,GAAG,OAAO,EAAE,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,GAAG,uDACnB,EAAE;AAAA,QAChC;AAAA,MACF;AACA,UAAI,EAAE,SAAS,QAAQ;AACrB,YAAI;AAAA,UACF;AAAA,QACF;AAAA,MACF;AACA,UAAI,EAAE,SAAS,SAAS;AACtB,YAAI,KAAK,8EAA8E;AAAA,MACzF;AACA,UAAI,KAAK,gFAAgF;AACzF,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EACA,mBAAmB;AAAA,IACjB,SAAS,CAAC,MACR,mBAAmB,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE,oCAChD,OAAO,EAAE,OAAO,KAAK,CAAC,UAAU,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACjE,QAAQ,CAAC,MACP,qEACA,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACpE,KAAK,MAAM;AAAA,MACT;AAAA,MAEA;AAAA,IAEF;AAAA,EACF;AACF;AAGO,IAAM,oBAAoB;AAAA,MAC/B;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,MAC/C,QAAQ,EAAE,QAAQ,eAAe;AAAA,IACnC;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AAAA,MACA;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,IACjD;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AACF;","names":[]}
+{"version":3,"sources":["../../src/ingest/schema-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\nimport '../diagnostics/process-guard'\n\n/** `options.invalidRows` (§5.1). */\nexport type InvalidRowsMode = 'drop' | 'flag' | 'throw'\n\n/** An issue path matched to a column (`DK_SCHEMA_INVALID_ROW.columns`). */\nexport interface SchemaIssueColumn {\n  /** The issue path, dot-joined (`address.city`; `''` for the row itself). */\n  readonly path: string\n  /** The column whose key is or contains the path, if one does. */\n  readonly column?: string\n  /** That column's position in `options.columns`. */\n  readonly index?: number\n  /** Invalid rows with an issue at this path. */\n  readonly count: number\n}\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_SCHEMA_INVALID_ROW: {\n      mode: InvalidRowsMode\n      /** Rows with issues. */\n      count: number\n      /** Rows validated. */\n      total: number\n      /** A sample of the invalid rows' indices in `options.data` (first few, in order). */\n      rows: readonly number[]\n      /** The first issue of each sampled row (redacted: `scrubSchemaIssue`). */\n      issues: readonly unknown[]\n      /** Issue paths with their column, most frequent first (at most a few). */\n      columns: readonly SchemaIssueColumn[]\n    }\n    DK_SCHEMA_CRASHED: {\n      mode: InvalidRowsMode\n      /** Rows for which `validate` threw or rejected. */\n      count: number\n      rows: readonly number[]\n      /** `error.name` of the first failure; the error itself is `context.cause`. */\n      errorName?: string\n    }\n  }\n}\n\nconst rowList = (rows: readonly number[], count: number) => {\n  const list = rows.map((r) => `#${r}`).join(', ')\n  return count > rows.length ? `${list}, …` : list\n}\n\nconst plural = (n: number, one: string) => `${n} ${one}${n === 1 ? '' : 's'}`\n\nconst handled = (mode: InvalidRowsMode, rows: string) => {\n  switch (mode) {\n    case 'drop':\n      return `${rows} removed from the table (getInvalidRows() lists them)`\n    case 'flag':\n      return `${rows} kept with row.valid === false and row.issues (cell / invalidCell must handle them)`\n    case 'throw':\n      return 'DatakableSchemaError was thrown; the previous data was kept'\n  }\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const schemaMessages: DiagnosticMessages<'DK_SCHEMA_INVALID_ROW' | 'DK_SCHEMA_CRASHED'> = {\n  DK_SCHEMA_INVALID_ROW: {\n    problem: (d) =>\n      `${d.count} of ${plural(d.total, 'row')} failed schema validation ` +\n      `(rows ${rowList(d.rows, d.count)})`,\n    impact: (d) => handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: (d) => {\n      const out: string[] = []\n      for (const c of d.columns) {\n        const at = c.path === '' ? 'the row itself' : `\"${c.path}\"`\n        const col =\n          c.column === undefined\n            ? 'no column shows it'\n            : `column \"${c.column}\" (columns[${c.index}])`\n        out.push(\n          `${plural(c.count, 'row')} fail at ${at}, ${col}: fix the data source there, ` +\n            `or relax the schema at ${at}`,\n        )\n      }\n      if (d.mode === 'drop') {\n        out.push(\n          \"use invalidRows: 'flag' to keep and show the invalid rows instead of dropping them\",\n        )\n      }\n      if (d.mode === 'throw') {\n        out.push(\"use invalidRows: 'drop' or 'flag' to keep the table usable with invalid rows\")\n      }\n      out.push('inspect them with table.getInvalidRows() (index, raw value and issues per row)')\n      return out\n    },\n  },\n  DK_SCHEMA_CRASHED: {\n    problem: (d) =>\n      `the schema threw${d.errorName ? ` ${d.errorName}` : ''} instead of returning issues ` +\n      `for ${plural(d.count, 'row')} (rows ${rowList(d.rows, d.count)})`,\n    impact: (d) =>\n      `each such row got a synthetic issue and was treated as invalid: ` +\n      handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: () => [\n      'find the throwing refinement / transform in the schema: the original error is ' +\n        'context.cause (passed to onDiagnostic)',\n      'make custom checks return an issue (e.g. ctx.addIssue / a refine predicate) instead of ' +\n        'throwing on unexpected input',\n    ],\n  },\n}\n\n/** Codes owned by the schema ingest (§5.1, §8.3). */\nexport const schemaDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_INVALID_ROW',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n      redact: { issues: 'schemaIssues' },\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_INVALID_ROW,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_CRASHED',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_CRASHED,\n  ),\n]\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA0D;AAC1D,2BAAO;AA2CP,IAAM,UAAU,CAAC,MAAyB,UAAkB;AAC1D,QAAM,OAAO,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI;AAC/C,SAAO,QAAQ,KAAK,SAAS,GAAG,IAAI,aAAQ;AAC9C;AAEA,IAAM,SAAS,CAAC,GAAW,QAAgB,GAAG,CAAC,IAAI,GAAG,GAAG,MAAM,IAAI,KAAK,GAAG;AAE3E,IAAM,UAAU,CAAC,MAAuB,SAAiB;AACvD,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAGO,IAAM,iBAAoF;AAAA,EAC/F,uBAAuB;AAAA,IACrB,SAAS,CAAC,MACR,GAAG,EAAE,KAAK,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC,mCAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACnC,QAAQ,CAAC,MAAM,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACjF,KAAK,CAAC,MAAM;AACV,YAAM,MAAgB,CAAC;AACvB,iBAAW,KAAK,EAAE,SAAS;AACzB,cAAM,KAAK,EAAE,SAAS,KAAK,mBAAmB,IAAI,EAAE,IAAI;AACxD,cAAM,MACJ,EAAE,WAAW,SACT,uBACA,WAAW,EAAE,MAAM,cAAc,EAAE,KAAK;AAC9C,YAAI;AAAA,UACF,GAAG,OAAO,EAAE,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,GAAG,uDACnB,EAAE;AAAA,QAChC;AAAA,MACF;AACA,UAAI,EAAE,SAAS,QAAQ;AACrB,YAAI;AAAA,UACF;AAAA,QACF;AAAA,MACF;AACA,UAAI,EAAE,SAAS,SAAS;AACtB,YAAI,KAAK,8EAA8E;AAAA,MACzF;AACA,UAAI,KAAK,gFAAgF;AACzF,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EACA,mBAAmB;AAAA,IACjB,SAAS,CAAC,MACR,mBAAmB,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE,oCAChD,OAAO,EAAE,OAAO,KAAK,CAAC,UAAU,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACjE,QAAQ,CAAC,MACP,qEACA,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACpE,KAAK,MAAM;AAAA,MACT;AAAA,MAEA;AAAA,IAEF;AAAA,EACF;AACF;AAGO,IAAM,oBAAoB;AAAA,MAC/B;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,MAC/C,QAAQ,EAAE,QAAQ,eAAe;AAAA,IACnC;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AAAA,MACA;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,IACjD;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AACF;","names":[]}

package/dist/ingest/schema-codes.js

@@ -1,5 +1,6 @@
 // src/ingest/schema-codes.ts
 import { defineDiagnostic } from "../diagnostics/catalog.js";
+import "../diagnostics/process-guard.js";
 var rowList = (rows, count) => {
   const list = rows.map((r) => `#${r}`).join(", ");
   return count > rows.length ? `${list}, \u2026` : list;

package/dist/ingest/schema-codes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/schema-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\n\n/** `options.invalidRows` (§5.1). */\nexport type InvalidRowsMode = 'drop' | 'flag' | 'throw'\n\n/** An issue path matched to a column (`DK_SCHEMA_INVALID_ROW.columns`). */\nexport interface SchemaIssueColumn {\n  /** The issue path, dot-joined (`address.city`; `''` for the row itself). */\n  readonly path: string\n  /** The column whose key is or contains the path, if one does. */\n  readonly column?: string\n  /** That column's position in `options.columns`. */\n  readonly index?: number\n  /** Invalid rows with an issue at this path. */\n  readonly count: number\n}\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_SCHEMA_INVALID_ROW: {\n      mode: InvalidRowsMode\n      /** Rows with issues. */\n      count: number\n      /** Rows validated. */\n      total: number\n      /** A sample of the invalid rows' indices in `options.data` (first few, in order). */\n      rows: readonly number[]\n      /** The first issue of each sampled row (redacted: `scrubSchemaIssue`). */\n      issues: readonly unknown[]\n      /** Issue paths with their column, most frequent first (at most a few). */\n      columns: readonly SchemaIssueColumn[]\n    }\n    DK_SCHEMA_CRASHED: {\n      mode: InvalidRowsMode\n      /** Rows for which `validate` threw or rejected. */\n      count: number\n      rows: readonly number[]\n      /** `error.name` of the first failure; the error itself is `context.cause`. */\n      errorName?: string\n    }\n  }\n}\n\nconst rowList = (rows: readonly number[], count: number) => {\n  const list = rows.map((r) => `#${r}`).join(', ')\n  return count > rows.length ? `${list}, …` : list\n}\n\nconst plural = (n: number, one: string) => `${n} ${one}${n === 1 ? '' : 's'}`\n\nconst handled = (mode: InvalidRowsMode, rows: string) => {\n  switch (mode) {\n    case 'drop':\n      return `${rows} removed from the table (getInvalidRows() lists them)`\n    case 'flag':\n      return `${rows} kept with row.valid === false and row.issues (cell / invalidCell must handle them)`\n    case 'throw':\n      return 'DatakableSchemaError was thrown; the previous data was kept'\n  }\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const schemaMessages: DiagnosticMessages<'DK_SCHEMA_INVALID_ROW' | 'DK_SCHEMA_CRASHED'> = {\n  DK_SCHEMA_INVALID_ROW: {\n    problem: (d) =>\n      `${d.count} of ${plural(d.total, 'row')} failed schema validation ` +\n      `(rows ${rowList(d.rows, d.count)})`,\n    impact: (d) => handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: (d) => {\n      const out: string[] = []\n      for (const c of d.columns) {\n        const at = c.path === '' ? 'the row itself' : `\"${c.path}\"`\n        const col =\n          c.column === undefined\n            ? 'no column shows it'\n            : `column \"${c.column}\" (columns[${c.index}])`\n        out.push(\n          `${plural(c.count, 'row')} fail at ${at}, ${col}: fix the data source there, ` +\n            `or relax the schema at ${at}`,\n        )\n      }\n      if (d.mode === 'drop') {\n        out.push(\n          \"use invalidRows: 'flag' to keep and show the invalid rows instead of dropping them\",\n        )\n      }\n      if (d.mode === 'throw') {\n        out.push(\"use invalidRows: 'drop' or 'flag' to keep the table usable with invalid rows\")\n      }\n      out.push('inspect them with table.getInvalidRows() (index, raw value and issues per row)')\n      return out\n    },\n  },\n  DK_SCHEMA_CRASHED: {\n    problem: (d) =>\n      `the schema threw${d.errorName ? ` ${d.errorName}` : ''} instead of returning issues ` +\n      `for ${plural(d.count, 'row')} (rows ${rowList(d.rows, d.count)})`,\n    impact: (d) =>\n      `each such row got a synthetic issue and was treated as invalid: ` +\n      handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: () => [\n      'find the throwing refinement / transform in the schema: the original error is ' +\n        'context.cause (passed to onDiagnostic)',\n      'make custom checks return an issue (e.g. ctx.addIssue / a refine predicate) instead of ' +\n        'throwing on unexpected input',\n    ],\n  },\n}\n\n/** Codes owned by the schema ingest (§5.1, §8.3). */\nexport const schemaDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_INVALID_ROW',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n      redact: { issues: 'schemaIssues' },\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_INVALID_ROW,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_CRASHED',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_CRASHED,\n  ),\n]\n"],"mappings":";AAAA,SAAkC,wBAAwB;AA2C1D,IAAM,UAAU,CAAC,MAAyB,UAAkB;AAC1D,QAAM,OAAO,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI;AAC/C,SAAO,QAAQ,KAAK,SAAS,GAAG,IAAI,aAAQ;AAC9C;AAEA,IAAM,SAAS,CAAC,GAAW,QAAgB,GAAG,CAAC,IAAI,GAAG,GAAG,MAAM,IAAI,KAAK,GAAG;AAE3E,IAAM,UAAU,CAAC,MAAuB,SAAiB;AACvD,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAGO,IAAM,iBAAoF;AAAA,EAC/F,uBAAuB;AAAA,IACrB,SAAS,CAAC,MACR,GAAG,EAAE,KAAK,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC,mCAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACnC,QAAQ,CAAC,MAAM,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACjF,KAAK,CAAC,MAAM;AACV,YAAM,MAAgB,CAAC;AACvB,iBAAW,KAAK,EAAE,SAAS;AACzB,cAAM,KAAK,EAAE,SAAS,KAAK,mBAAmB,IAAI,EAAE,IAAI;AACxD,cAAM,MACJ,EAAE,WAAW,SACT,uBACA,WAAW,EAAE,MAAM,cAAc,EAAE,KAAK;AAC9C,YAAI;AAAA,UACF,GAAG,OAAO,EAAE,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,GAAG,uDACnB,EAAE;AAAA,QAChC;AAAA,MACF;AACA,UAAI,EAAE,SAAS,QAAQ;AACrB,YAAI;AAAA,UACF;AAAA,QACF;AAAA,MACF;AACA,UAAI,EAAE,SAAS,SAAS;AACtB,YAAI,KAAK,8EAA8E;AAAA,MACzF;AACA,UAAI,KAAK,gFAAgF;AACzF,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EACA,mBAAmB;AAAA,IACjB,SAAS,CAAC,MACR,mBAAmB,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE,oCAChD,OAAO,EAAE,OAAO,KAAK,CAAC,UAAU,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACjE,QAAQ,CAAC,MACP,qEACA,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACpE,KAAK,MAAM;AAAA,MACT;AAAA,MAEA;AAAA,IAEF;AAAA,EACF;AACF;AAGO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,MAC/C,QAAQ,EAAE,QAAQ,eAAe;AAAA,IACnC;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AAAA,EACA;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,IACjD;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AACF;","names":[]}
+{"version":3,"sources":["../../src/ingest/schema-codes.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from '../diagnostics/catalog'\nimport '../diagnostics/process-guard'\n\n/** `options.invalidRows` (§5.1). */\nexport type InvalidRowsMode = 'drop' | 'flag' | 'throw'\n\n/** An issue path matched to a column (`DK_SCHEMA_INVALID_ROW.columns`). */\nexport interface SchemaIssueColumn {\n  /** The issue path, dot-joined (`address.city`; `''` for the row itself). */\n  readonly path: string\n  /** The column whose key is or contains the path, if one does. */\n  readonly column?: string\n  /** That column's position in `options.columns`. */\n  readonly index?: number\n  /** Invalid rows with an issue at this path. */\n  readonly count: number\n}\n\ndeclare module '../diagnostics/catalog' {\n  interface DiagnosticCatalog {\n    DK_SCHEMA_INVALID_ROW: {\n      mode: InvalidRowsMode\n      /** Rows with issues. */\n      count: number\n      /** Rows validated. */\n      total: number\n      /** A sample of the invalid rows' indices in `options.data` (first few, in order). */\n      rows: readonly number[]\n      /** The first issue of each sampled row (redacted: `scrubSchemaIssue`). */\n      issues: readonly unknown[]\n      /** Issue paths with their column, most frequent first (at most a few). */\n      columns: readonly SchemaIssueColumn[]\n    }\n    DK_SCHEMA_CRASHED: {\n      mode: InvalidRowsMode\n      /** Rows for which `validate` threw or rejected. */\n      count: number\n      rows: readonly number[]\n      /** `error.name` of the first failure; the error itself is `context.cause`. */\n      errorName?: string\n    }\n  }\n}\n\nconst rowList = (rows: readonly number[], count: number) => {\n  const list = rows.map((r) => `#${r}`).join(', ')\n  return count > rows.length ? `${list}, …` : list\n}\n\nconst plural = (n: number, one: string) => `${n} ${one}${n === 1 ? '' : 's'}`\n\nconst handled = (mode: InvalidRowsMode, rows: string) => {\n  switch (mode) {\n    case 'drop':\n      return `${rows} removed from the table (getInvalidRows() lists them)`\n    case 'flag':\n      return `${rows} kept with row.valid === false and row.issues (cell / invalidCell must handle them)`\n    case 'throw':\n      return 'DatakableSchemaError was thrown; the previous data was kept'\n  }\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const schemaMessages: DiagnosticMessages<'DK_SCHEMA_INVALID_ROW' | 'DK_SCHEMA_CRASHED'> = {\n  DK_SCHEMA_INVALID_ROW: {\n    problem: (d) =>\n      `${d.count} of ${plural(d.total, 'row')} failed schema validation ` +\n      `(rows ${rowList(d.rows, d.count)})`,\n    impact: (d) => handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: (d) => {\n      const out: string[] = []\n      for (const c of d.columns) {\n        const at = c.path === '' ? 'the row itself' : `\"${c.path}\"`\n        const col =\n          c.column === undefined\n            ? 'no column shows it'\n            : `column \"${c.column}\" (columns[${c.index}])`\n        out.push(\n          `${plural(c.count, 'row')} fail at ${at}, ${col}: fix the data source there, ` +\n            `or relax the schema at ${at}`,\n        )\n      }\n      if (d.mode === 'drop') {\n        out.push(\n          \"use invalidRows: 'flag' to keep and show the invalid rows instead of dropping them\",\n        )\n      }\n      if (d.mode === 'throw') {\n        out.push(\"use invalidRows: 'drop' or 'flag' to keep the table usable with invalid rows\")\n      }\n      out.push('inspect them with table.getInvalidRows() (index, raw value and issues per row)')\n      return out\n    },\n  },\n  DK_SCHEMA_CRASHED: {\n    problem: (d) =>\n      `the schema threw${d.errorName ? ` ${d.errorName}` : ''} instead of returning issues ` +\n      `for ${plural(d.count, 'row')} (rows ${rowList(d.rows, d.count)})`,\n    impact: (d) =>\n      `each such row got a synthetic issue and was treated as invalid: ` +\n      handled(d.mode, d.count === 1 ? 'that row was' : 'those rows were'),\n    fix: () => [\n      'find the throwing refinement / transform in the schema: the original error is ' +\n        'context.cause (passed to onDiagnostic)',\n      'make custom checks return an issue (e.g. ctx.addIssue / a refine predicate) instead of ' +\n        'throwing on unexpected input',\n    ],\n  },\n}\n\n/** Codes owned by the schema ingest (§5.1, §8.3). */\nexport const schemaDiagnostics = [\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_INVALID_ROW',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n      redact: { issues: 'schemaIssues' },\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_INVALID_ROW,\n  ),\n  defineDiagnostic(\n    {\n      code: 'DK_SCHEMA_CRASHED',\n      level: 'error',\n      where: () => ({ kind: 'option', path: 'schema' }),\n    },\n    (process.env.NODE_ENV !== \"production\") && schemaMessages.DK_SCHEMA_CRASHED,\n  ),\n]\n"],"mappings":";AAAA,SAAkC,wBAAwB;AAC1D,OAAO;AA2CP,IAAM,UAAU,CAAC,MAAyB,UAAkB;AAC1D,QAAM,OAAO,KAAK,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI;AAC/C,SAAO,QAAQ,KAAK,SAAS,GAAG,IAAI,aAAQ;AAC9C;AAEA,IAAM,SAAS,CAAC,GAAW,QAAgB,GAAG,CAAC,IAAI,GAAG,GAAG,MAAM,IAAI,KAAK,GAAG;AAE3E,IAAM,UAAU,CAAC,MAAuB,SAAiB;AACvD,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO,GAAG,IAAI;AAAA,IAChB,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAGO,IAAM,iBAAoF;AAAA,EAC/F,uBAAuB;AAAA,IACrB,SAAS,CAAC,MACR,GAAG,EAAE,KAAK,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC,mCAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACnC,QAAQ,CAAC,MAAM,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACjF,KAAK,CAAC,MAAM;AACV,YAAM,MAAgB,CAAC;AACvB,iBAAW,KAAK,EAAE,SAAS;AACzB,cAAM,KAAK,EAAE,SAAS,KAAK,mBAAmB,IAAI,EAAE,IAAI;AACxD,cAAM,MACJ,EAAE,WAAW,SACT,uBACA,WAAW,EAAE,MAAM,cAAc,EAAE,KAAK;AAC9C,YAAI;AAAA,UACF,GAAG,OAAO,EAAE,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,GAAG,uDACnB,EAAE;AAAA,QAChC;AAAA,MACF;AACA,UAAI,EAAE,SAAS,QAAQ;AACrB,YAAI;AAAA,UACF;AAAA,QACF;AAAA,MACF;AACA,UAAI,EAAE,SAAS,SAAS;AACtB,YAAI,KAAK,8EAA8E;AAAA,MACzF;AACA,UAAI,KAAK,gFAAgF;AACzF,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EACA,mBAAmB;AAAA,IACjB,SAAS,CAAC,MACR,mBAAmB,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK,EAAE,oCAChD,OAAO,EAAE,OAAO,KAAK,CAAC,UAAU,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC;AAAA,IACjE,QAAQ,CAAC,MACP,qEACA,QAAQ,EAAE,MAAM,EAAE,UAAU,IAAI,iBAAiB,iBAAiB;AAAA,IACpE,KAAK,MAAM;AAAA,MACT;AAAA,MAEA;AAAA,IAEF;AAAA,EACF;AACF;AAGO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,MAC/C,QAAQ,EAAE,QAAQ,eAAe;AAAA,IACnC;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AAAA,EACA;AAAA,IACE;AAAA,MACE,MAAM;AAAA,MACN,OAAO;AAAA,MACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,SAAS;AAAA,IACjD;AAAA,IACC,QAAQ,IAAI,aAAa,gBAAiB,eAAe;AAAA,EAC5D;AACF;","names":[]}

package/dist/ingest/unique-fields.cjs

@@ -53,8 +53,8 @@ function allDistinct(n, keyAt) {
   const seen = /* @__PURE__ */ new Set();
   for (let i = 0; i < n; i++) {
     const v = keyAt(i);
-    if (!isKey(v) || seen.has(v)) return false;
-    seen.add(v);
+    if (!isKey(v) || seen.has(String(v))) return false;
+    seen.add(String(v));
   }
   return true;
 }

package/dist/ingest/unique-fields.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/unique-fields.ts"],"sourcesContent":["import { type CompiledPath, compilePath, getValue } from '../column/get-value'\n\n/** Depth cap of a candidate path (as `Path<T>`, §4.1). */\nconst MAX_DEPTH = 4\n/** Bound on the candidates checked (each is one pass over the data). */\nconst MAX_CANDIDATES = 64\n/** Unique fields reported in a `fix`. */\nconst MAX_UNIQUE = 3\n\nexport interface UniqueFields {\n  /** Paths whose value is a string / number in every row, never repeated (row-0 order). */\n  unique: string[]\n  /** With no unique field: a field `f` for which `${row.<rowKey>}-${row.<f>}` is unique. */\n  pair?: string\n}\n\nconst isKey = (v: unknown): v is string | number =>\n  typeof v === 'string' || (typeof v === 'number' && !Number.isNaN(v))\n\nconst isPlain = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date)\n\n/**\n * Primitive leaf paths of `row` (depth ≤ 4; arrays and Dates are not walked). A field must be in\n * every row to be unique, so row 0's paths are the only candidates.\n */\nfunction candidates(row: unknown, skip: string | undefined): string[] {\n  const out: string[] = []\n  const walk = (obj: Record<string, unknown>, prefix: string, depth: number) => {\n    for (const k of Object.keys(obj)) {\n      if (out.length >= MAX_CANDIDATES) return\n      const path = prefix ? `${prefix}.${k}` : k\n      let v: unknown\n      try {\n        v = obj[k]\n      } catch {\n        continue\n      }\n      if (isKey(v)) {\n        if (path !== skip) out.push(path)\n      } else if (isPlain(v) && depth < MAX_DEPTH) walk(v, path, depth + 1)\n    }\n  }\n  if (isPlain(row)) walk(row, '', 1)\n  return out\n}\n\n/** `true` when `keyAt(i)` is a usable key for every row and never repeats. */\nfunction allDistinct(n: number, keyAt: (i: number) => unknown): boolean {\n  const seen = new Set<unknown>()\n  for (let i = 0; i < n; i++) {\n    const v = keyAt(i)\n    if (!isKey(v) || seen.has(v)) return false\n    seen.add(v)\n  }\n  return true\n}\n\n/**\n * The fields that would make a good `rowKey`, computed by scanning every row (§5.2: the `fix` of\n * `DK_DUPLICATE_ROW_KEY` / `DK_MISSING_ROW_KEY`). Runs only when a key problem was found. With\n * `pairWith` (the `rowKey` path) and no unique field, also looks for a composite key, checked with\n * exactly the string the suggested `(row) => \\`${row.a}-${row.b}\\`` builds.\n */\nexport function findUniqueFields(\n  data: readonly unknown[],\n  rowKeyPath: string | undefined,\n  pairWith = rowKeyPath,\n): UniqueFields {\n  if (data.length === 0) return { unique: [] }\n  const paths = candidates(data[0], rowKeyPath)\n  const compiled = paths.map(compilePath)\n  const at = (path: CompiledPath) => (i: number) => getValue(data[i], path)\n  const unique: string[] = []\n  for (let c = 0; c < paths.length && unique.length < MAX_UNIQUE; c++) {\n    if (allDistinct(data.length, at(compiled[c] as CompiledPath))) unique.push(paths[c] as string)\n  }\n  if (unique.length > 0 || pairWith === undefined) return { unique }\n  const key = at(compilePath(pairWith))\n  for (let c = 0; c < paths.length; c++) {\n    const other = at(compiled[c] as CompiledPath)\n    const ok = allDistinct(data.length, (i) => {\n      const a = key(i)\n      const b = other(i)\n      return isKey(a) && isKey(b) ? `${a}-${b}` : undefined\n    })\n    if (ok) return { unique, pair: paths[c] as string }\n  }\n  return { unique }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,uBAAyD;AAGzD,IAAM,YAAY;AAElB,IAAM,iBAAiB;AAEvB,IAAM,aAAa;AASnB,IAAM,QAAQ,CAAC,MACb,OAAO,MAAM,YAAa,OAAO,MAAM,YAAY,CAAC,OAAO,MAAM,CAAC;AAEpE,IAAM,UAAU,CAAC,MACf,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,aAAa;AAM7E,SAAS,WAAW,KAAc,MAAoC;AACpE,QAAM,MAAgB,CAAC;AACvB,QAAM,OAAO,CAAC,KAA8B,QAAgB,UAAkB;AAC5E,eAAW,KAAK,OAAO,KAAK,GAAG,GAAG;AAChC,UAAI,IAAI,UAAU,eAAgB;AAClC,YAAM,OAAO,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK;AACzC,UAAI;AACJ,UAAI;AACF,YAAI,IAAI,CAAC;AAAA,MACX,QAAQ;AACN;AAAA,MACF;AACA,UAAI,MAAM,CAAC,GAAG;AACZ,YAAI,SAAS,KAAM,KAAI,KAAK,IAAI;AAAA,MAClC,WAAW,QAAQ,CAAC,KAAK,QAAQ,UAAW,MAAK,GAAG,MAAM,QAAQ,CAAC;AAAA,IACrE;AAAA,EACF;AACA,MAAI,QAAQ,GAAG,EAAG,MAAK,KAAK,IAAI,CAAC;AACjC,SAAO;AACT;AAGA,SAAS,YAAY,GAAW,OAAwC;AACtE,QAAM,OAAO,oBAAI,IAAa;AAC9B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,IAAI,MAAM,CAAC;AACjB,QAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,EAAG,QAAO;AACrC,SAAK,IAAI,CAAC;AAAA,EACZ;AACA,SAAO;AACT;AAQO,SAAS,iBACd,MACA,YACA,WAAW,YACG;AACd,MAAI,KAAK,WAAW,EAAG,QAAO,EAAE,QAAQ,CAAC,EAAE;AAC3C,QAAM,QAAQ,WAAW,KAAK,CAAC,GAAG,UAAU;AAC5C,QAAM,WAAW,MAAM,IAAI,4BAAW;AACtC,QAAM,KAAK,CAAC,SAAuB,CAAC,UAAc,2BAAS,KAAK,CAAC,GAAG,IAAI;AACxE,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,GAAG,IAAI,MAAM,UAAU,OAAO,SAAS,YAAY,KAAK;AACnE,QAAI,YAAY,KAAK,QAAQ,GAAG,SAAS,CAAC,CAAiB,CAAC,EAAG,QAAO,KAAK,MAAM,CAAC,CAAW;AAAA,EAC/F;AACA,MAAI,OAAO,SAAS,KAAK,aAAa,OAAW,QAAO,EAAE,OAAO;AACjE,QAAM,MAAM,OAAG,8BAAY,QAAQ,CAAC;AACpC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,QAAQ,GAAG,SAAS,CAAC,CAAiB;AAC5C,UAAM,KAAK,YAAY,KAAK,QAAQ,CAAC,MAAM;AACzC,YAAM,IAAI,IAAI,CAAC;AACf,YAAM,IAAI,MAAM,CAAC;AACjB,aAAO,MAAM,CAAC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK;AAAA,IAC9C,CAAC;AACD,QAAI,GAAI,QAAO,EAAE,QAAQ,MAAM,MAAM,CAAC,EAAY;AAAA,EACpD;AACA,SAAO,EAAE,OAAO;AAClB;","names":[]}
+{"version":3,"sources":["../../src/ingest/unique-fields.ts"],"sourcesContent":["import { type CompiledPath, compilePath, getValue } from '../column/get-value'\n\n/** Depth cap of a candidate path (as `Path<T>`, §4.1). */\nconst MAX_DEPTH = 4\n/** Bound on the candidates checked (each is one pass over the data). */\nconst MAX_CANDIDATES = 64\n/** Unique fields reported in a `fix`. */\nconst MAX_UNIQUE = 3\n\nexport interface UniqueFields {\n  /** Paths whose value is a string / number in every row, never repeated (row-0 order). */\n  unique: string[]\n  /** With no unique field: a field `f` for which `${row.<rowKey>}-${row.<f>}` is unique. */\n  pair?: string\n}\n\nconst isKey = (v: unknown): v is string | number =>\n  typeof v === 'string' || (typeof v === 'number' && !Number.isNaN(v))\n\nconst isPlain = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date)\n\n/**\n * Primitive leaf paths of `row` (depth ≤ 4; arrays and Dates are not walked). A field must be in\n * every row to be unique, so row 0's paths are the only candidates.\n */\nfunction candidates(row: unknown, skip: string | undefined): string[] {\n  const out: string[] = []\n  const walk = (obj: Record<string, unknown>, prefix: string, depth: number) => {\n    for (const k of Object.keys(obj)) {\n      if (out.length >= MAX_CANDIDATES) return\n      const path = prefix ? `${prefix}.${k}` : k\n      let v: unknown\n      try {\n        v = obj[k]\n      } catch {\n        continue\n      }\n      if (isKey(v)) {\n        if (path !== skip) out.push(path)\n      } else if (isPlain(v) && depth < MAX_DEPTH) walk(v, path, depth + 1)\n    }\n  }\n  if (isPlain(row)) walk(row, '', 1)\n  return out\n}\n\n/** `true` when `keyAt(i)` is a usable key for every row and never repeats (as a string). */\nfunction allDistinct(n: number, keyAt: (i: number) => unknown): boolean {\n  const seen = new Set<string>()\n  for (let i = 0; i < n; i++) {\n    const v = keyAt(i)\n    if (!isKey(v) || seen.has(String(v))) return false\n    seen.add(String(v))\n  }\n  return true\n}\n\n/**\n * The fields that would make a good `rowKey`, computed by scanning every row (§5.2: the `fix` of\n * `DK_DUPLICATE_ROW_KEY` / `DK_MISSING_ROW_KEY`). Runs only when a key problem was found. With\n * `pairWith` (the `rowKey` path) and no unique field, also looks for a composite key, checked with\n * exactly the string the suggested `(row) => \\`${row.a}-${row.b}\\`` builds.\n */\nexport function findUniqueFields(\n  data: readonly unknown[],\n  rowKeyPath: string | undefined,\n  pairWith = rowKeyPath,\n): UniqueFields {\n  if (data.length === 0) return { unique: [] }\n  const paths = candidates(data[0], rowKeyPath)\n  const compiled = paths.map(compilePath)\n  const at = (path: CompiledPath) => (i: number) => getValue(data[i], path)\n  const unique: string[] = []\n  for (let c = 0; c < paths.length && unique.length < MAX_UNIQUE; c++) {\n    if (allDistinct(data.length, at(compiled[c] as CompiledPath))) unique.push(paths[c] as string)\n  }\n  if (unique.length > 0 || pairWith === undefined) return { unique }\n  const key = at(compilePath(pairWith))\n  for (let c = 0; c < paths.length; c++) {\n    const other = at(compiled[c] as CompiledPath)\n    const ok = allDistinct(data.length, (i) => {\n      const a = key(i)\n      const b = other(i)\n      return isKey(a) && isKey(b) ? `${a}-${b}` : undefined\n    })\n    if (ok) return { unique, pair: paths[c] as string }\n  }\n  return { unique }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,uBAAyD;AAGzD,IAAM,YAAY;AAElB,IAAM,iBAAiB;AAEvB,IAAM,aAAa;AASnB,IAAM,QAAQ,CAAC,MACb,OAAO,MAAM,YAAa,OAAO,MAAM,YAAY,CAAC,OAAO,MAAM,CAAC;AAEpE,IAAM,UAAU,CAAC,MACf,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,aAAa;AAM7E,SAAS,WAAW,KAAc,MAAoC;AACpE,QAAM,MAAgB,CAAC;AACvB,QAAM,OAAO,CAAC,KAA8B,QAAgB,UAAkB;AAC5E,eAAW,KAAK,OAAO,KAAK,GAAG,GAAG;AAChC,UAAI,IAAI,UAAU,eAAgB;AAClC,YAAM,OAAO,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK;AACzC,UAAI;AACJ,UAAI;AACF,YAAI,IAAI,CAAC;AAAA,MACX,QAAQ;AACN;AAAA,MACF;AACA,UAAI,MAAM,CAAC,GAAG;AACZ,YAAI,SAAS,KAAM,KAAI,KAAK,IAAI;AAAA,MAClC,WAAW,QAAQ,CAAC,KAAK,QAAQ,UAAW,MAAK,GAAG,MAAM,QAAQ,CAAC;AAAA,IACrE;AAAA,EACF;AACA,MAAI,QAAQ,GAAG,EAAG,MAAK,KAAK,IAAI,CAAC;AACjC,SAAO;AACT;AAGA,SAAS,YAAY,GAAW,OAAwC;AACtE,QAAM,OAAO,oBAAI,IAAY;AAC7B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,IAAI,MAAM,CAAC;AACjB,QAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,OAAO,CAAC,CAAC,EAAG,QAAO;AAC7C,SAAK,IAAI,OAAO,CAAC,CAAC;AAAA,EACpB;AACA,SAAO;AACT;AAQO,SAAS,iBACd,MACA,YACA,WAAW,YACG;AACd,MAAI,KAAK,WAAW,EAAG,QAAO,EAAE,QAAQ,CAAC,EAAE;AAC3C,QAAM,QAAQ,WAAW,KAAK,CAAC,GAAG,UAAU;AAC5C,QAAM,WAAW,MAAM,IAAI,4BAAW;AACtC,QAAM,KAAK,CAAC,SAAuB,CAAC,UAAc,2BAAS,KAAK,CAAC,GAAG,IAAI;AACxE,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,GAAG,IAAI,MAAM,UAAU,OAAO,SAAS,YAAY,KAAK;AACnE,QAAI,YAAY,KAAK,QAAQ,GAAG,SAAS,CAAC,CAAiB,CAAC,EAAG,QAAO,KAAK,MAAM,CAAC,CAAW;AAAA,EAC/F;AACA,MAAI,OAAO,SAAS,KAAK,aAAa,OAAW,QAAO,EAAE,OAAO;AACjE,QAAM,MAAM,OAAG,8BAAY,QAAQ,CAAC;AACpC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,QAAQ,GAAG,SAAS,CAAC,CAAiB;AAC5C,UAAM,KAAK,YAAY,KAAK,QAAQ,CAAC,MAAM;AACzC,YAAM,IAAI,IAAI,CAAC;AACf,YAAM,IAAI,MAAM,CAAC;AACjB,aAAO,MAAM,CAAC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK;AAAA,IAC9C,CAAC;AACD,QAAI,GAAI,QAAO,EAAE,QAAQ,MAAM,MAAM,CAAC,EAAY;AAAA,EACpD;AACA,SAAO,EAAE,OAAO;AAClB;","names":[]}

package/dist/ingest/unique-fields.js

@@ -29,8 +29,8 @@ function allDistinct(n, keyAt) {
   const seen = /* @__PURE__ */ new Set();
   for (let i = 0; i < n; i++) {
     const v = keyAt(i);
-    if (!isKey(v) || seen.has(v)) return false;
-    seen.add(v);
+    if (!isKey(v) || seen.has(String(v))) return false;
+    seen.add(String(v));
   }
   return true;
 }

package/dist/ingest/unique-fields.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ingest/unique-fields.ts"],"sourcesContent":["import { type CompiledPath, compilePath, getValue } from '../column/get-value'\n\n/** Depth cap of a candidate path (as `Path<T>`, §4.1). */\nconst MAX_DEPTH = 4\n/** Bound on the candidates checked (each is one pass over the data). */\nconst MAX_CANDIDATES = 64\n/** Unique fields reported in a `fix`. */\nconst MAX_UNIQUE = 3\n\nexport interface UniqueFields {\n  /** Paths whose value is a string / number in every row, never repeated (row-0 order). */\n  unique: string[]\n  /** With no unique field: a field `f` for which `${row.<rowKey>}-${row.<f>}` is unique. */\n  pair?: string\n}\n\nconst isKey = (v: unknown): v is string | number =>\n  typeof v === 'string' || (typeof v === 'number' && !Number.isNaN(v))\n\nconst isPlain = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date)\n\n/**\n * Primitive leaf paths of `row` (depth ≤ 4; arrays and Dates are not walked). A field must be in\n * every row to be unique, so row 0's paths are the only candidates.\n */\nfunction candidates(row: unknown, skip: string | undefined): string[] {\n  const out: string[] = []\n  const walk = (obj: Record<string, unknown>, prefix: string, depth: number) => {\n    for (const k of Object.keys(obj)) {\n      if (out.length >= MAX_CANDIDATES) return\n      const path = prefix ? `${prefix}.${k}` : k\n      let v: unknown\n      try {\n        v = obj[k]\n      } catch {\n        continue\n      }\n      if (isKey(v)) {\n        if (path !== skip) out.push(path)\n      } else if (isPlain(v) && depth < MAX_DEPTH) walk(v, path, depth + 1)\n    }\n  }\n  if (isPlain(row)) walk(row, '', 1)\n  return out\n}\n\n/** `true` when `keyAt(i)` is a usable key for every row and never repeats. */\nfunction allDistinct(n: number, keyAt: (i: number) => unknown): boolean {\n  const seen = new Set<unknown>()\n  for (let i = 0; i < n; i++) {\n    const v = keyAt(i)\n    if (!isKey(v) || seen.has(v)) return false\n    seen.add(v)\n  }\n  return true\n}\n\n/**\n * The fields that would make a good `rowKey`, computed by scanning every row (§5.2: the `fix` of\n * `DK_DUPLICATE_ROW_KEY` / `DK_MISSING_ROW_KEY`). Runs only when a key problem was found. With\n * `pairWith` (the `rowKey` path) and no unique field, also looks for a composite key, checked with\n * exactly the string the suggested `(row) => \\`${row.a}-${row.b}\\`` builds.\n */\nexport function findUniqueFields(\n  data: readonly unknown[],\n  rowKeyPath: string | undefined,\n  pairWith = rowKeyPath,\n): UniqueFields {\n  if (data.length === 0) return { unique: [] }\n  const paths = candidates(data[0], rowKeyPath)\n  const compiled = paths.map(compilePath)\n  const at = (path: CompiledPath) => (i: number) => getValue(data[i], path)\n  const unique: string[] = []\n  for (let c = 0; c < paths.length && unique.length < MAX_UNIQUE; c++) {\n    if (allDistinct(data.length, at(compiled[c] as CompiledPath))) unique.push(paths[c] as string)\n  }\n  if (unique.length > 0 || pairWith === undefined) return { unique }\n  const key = at(compilePath(pairWith))\n  for (let c = 0; c < paths.length; c++) {\n    const other = at(compiled[c] as CompiledPath)\n    const ok = allDistinct(data.length, (i) => {\n      const a = key(i)\n      const b = other(i)\n      return isKey(a) && isKey(b) ? `${a}-${b}` : undefined\n    })\n    if (ok) return { unique, pair: paths[c] as string }\n  }\n  return { unique }\n}\n"],"mappings":";AAAA,SAA4B,aAAa,gBAAgB;AAGzD,IAAM,YAAY;AAElB,IAAM,iBAAiB;AAEvB,IAAM,aAAa;AASnB,IAAM,QAAQ,CAAC,MACb,OAAO,MAAM,YAAa,OAAO,MAAM,YAAY,CAAC,OAAO,MAAM,CAAC;AAEpE,IAAM,UAAU,CAAC,MACf,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,aAAa;AAM7E,SAAS,WAAW,KAAc,MAAoC;AACpE,QAAM,MAAgB,CAAC;AACvB,QAAM,OAAO,CAAC,KAA8B,QAAgB,UAAkB;AAC5E,eAAW,KAAK,OAAO,KAAK,GAAG,GAAG;AAChC,UAAI,IAAI,UAAU,eAAgB;AAClC,YAAM,OAAO,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK;AACzC,UAAI;AACJ,UAAI;AACF,YAAI,IAAI,CAAC;AAAA,MACX,QAAQ;AACN;AAAA,MACF;AACA,UAAI,MAAM,CAAC,GAAG;AACZ,YAAI,SAAS,KAAM,KAAI,KAAK,IAAI;AAAA,MAClC,WAAW,QAAQ,CAAC,KAAK,QAAQ,UAAW,MAAK,GAAG,MAAM,QAAQ,CAAC;AAAA,IACrE;AAAA,EACF;AACA,MAAI,QAAQ,GAAG,EAAG,MAAK,KAAK,IAAI,CAAC;AACjC,SAAO;AACT;AAGA,SAAS,YAAY,GAAW,OAAwC;AACtE,QAAM,OAAO,oBAAI,IAAa;AAC9B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,IAAI,MAAM,CAAC;AACjB,QAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,CAAC,EAAG,QAAO;AACrC,SAAK,IAAI,CAAC;AAAA,EACZ;AACA,SAAO;AACT;AAQO,SAAS,iBACd,MACA,YACA,WAAW,YACG;AACd,MAAI,KAAK,WAAW,EAAG,QAAO,EAAE,QAAQ,CAAC,EAAE;AAC3C,QAAM,QAAQ,WAAW,KAAK,CAAC,GAAG,UAAU;AAC5C,QAAM,WAAW,MAAM,IAAI,WAAW;AACtC,QAAM,KAAK,CAAC,SAAuB,CAAC,MAAc,SAAS,KAAK,CAAC,GAAG,IAAI;AACxE,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,GAAG,IAAI,MAAM,UAAU,OAAO,SAAS,YAAY,KAAK;AACnE,QAAI,YAAY,KAAK,QAAQ,GAAG,SAAS,CAAC,CAAiB,CAAC,EAAG,QAAO,KAAK,MAAM,CAAC,CAAW;AAAA,EAC/F;AACA,MAAI,OAAO,SAAS,KAAK,aAAa,OAAW,QAAO,EAAE,OAAO;AACjE,QAAM,MAAM,GAAG,YAAY,QAAQ,CAAC;AACpC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,QAAQ,GAAG,SAAS,CAAC,CAAiB;AAC5C,UAAM,KAAK,YAAY,KAAK,QAAQ,CAAC,MAAM;AACzC,YAAM,IAAI,IAAI,CAAC;AACf,YAAM,IAAI,MAAM,CAAC;AACjB,aAAO,MAAM,CAAC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK;AAAA,IAC9C,CAAC;AACD,QAAI,GAAI,QAAO,EAAE,QAAQ,MAAM,MAAM,CAAC,EAAY;AAAA,EACpD;AACA,SAAO,EAAE,OAAO;AAClB;","names":[]}
+{"version":3,"sources":["../../src/ingest/unique-fields.ts"],"sourcesContent":["import { type CompiledPath, compilePath, getValue } from '../column/get-value'\n\n/** Depth cap of a candidate path (as `Path<T>`, §4.1). */\nconst MAX_DEPTH = 4\n/** Bound on the candidates checked (each is one pass over the data). */\nconst MAX_CANDIDATES = 64\n/** Unique fields reported in a `fix`. */\nconst MAX_UNIQUE = 3\n\nexport interface UniqueFields {\n  /** Paths whose value is a string / number in every row, never repeated (row-0 order). */\n  unique: string[]\n  /** With no unique field: a field `f` for which `${row.<rowKey>}-${row.<f>}` is unique. */\n  pair?: string\n}\n\nconst isKey = (v: unknown): v is string | number =>\n  typeof v === 'string' || (typeof v === 'number' && !Number.isNaN(v))\n\nconst isPlain = (v: unknown): v is Record<string, unknown> =>\n  typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date)\n\n/**\n * Primitive leaf paths of `row` (depth ≤ 4; arrays and Dates are not walked). A field must be in\n * every row to be unique, so row 0's paths are the only candidates.\n */\nfunction candidates(row: unknown, skip: string | undefined): string[] {\n  const out: string[] = []\n  const walk = (obj: Record<string, unknown>, prefix: string, depth: number) => {\n    for (const k of Object.keys(obj)) {\n      if (out.length >= MAX_CANDIDATES) return\n      const path = prefix ? `${prefix}.${k}` : k\n      let v: unknown\n      try {\n        v = obj[k]\n      } catch {\n        continue\n      }\n      if (isKey(v)) {\n        if (path !== skip) out.push(path)\n      } else if (isPlain(v) && depth < MAX_DEPTH) walk(v, path, depth + 1)\n    }\n  }\n  if (isPlain(row)) walk(row, '', 1)\n  return out\n}\n\n/** `true` when `keyAt(i)` is a usable key for every row and never repeats (as a string). */\nfunction allDistinct(n: number, keyAt: (i: number) => unknown): boolean {\n  const seen = new Set<string>()\n  for (let i = 0; i < n; i++) {\n    const v = keyAt(i)\n    if (!isKey(v) || seen.has(String(v))) return false\n    seen.add(String(v))\n  }\n  return true\n}\n\n/**\n * The fields that would make a good `rowKey`, computed by scanning every row (§5.2: the `fix` of\n * `DK_DUPLICATE_ROW_KEY` / `DK_MISSING_ROW_KEY`). Runs only when a key problem was found. With\n * `pairWith` (the `rowKey` path) and no unique field, also looks for a composite key, checked with\n * exactly the string the suggested `(row) => \\`${row.a}-${row.b}\\`` builds.\n */\nexport function findUniqueFields(\n  data: readonly unknown[],\n  rowKeyPath: string | undefined,\n  pairWith = rowKeyPath,\n): UniqueFields {\n  if (data.length === 0) return { unique: [] }\n  const paths = candidates(data[0], rowKeyPath)\n  const compiled = paths.map(compilePath)\n  const at = (path: CompiledPath) => (i: number) => getValue(data[i], path)\n  const unique: string[] = []\n  for (let c = 0; c < paths.length && unique.length < MAX_UNIQUE; c++) {\n    if (allDistinct(data.length, at(compiled[c] as CompiledPath))) unique.push(paths[c] as string)\n  }\n  if (unique.length > 0 || pairWith === undefined) return { unique }\n  const key = at(compilePath(pairWith))\n  for (let c = 0; c < paths.length; c++) {\n    const other = at(compiled[c] as CompiledPath)\n    const ok = allDistinct(data.length, (i) => {\n      const a = key(i)\n      const b = other(i)\n      return isKey(a) && isKey(b) ? `${a}-${b}` : undefined\n    })\n    if (ok) return { unique, pair: paths[c] as string }\n  }\n  return { unique }\n}\n"],"mappings":";AAAA,SAA4B,aAAa,gBAAgB;AAGzD,IAAM,YAAY;AAElB,IAAM,iBAAiB;AAEvB,IAAM,aAAa;AASnB,IAAM,QAAQ,CAAC,MACb,OAAO,MAAM,YAAa,OAAO,MAAM,YAAY,CAAC,OAAO,MAAM,CAAC;AAEpE,IAAM,UAAU,CAAC,MACf,OAAO,MAAM,YAAY,MAAM,QAAQ,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,aAAa;AAM7E,SAAS,WAAW,KAAc,MAAoC;AACpE,QAAM,MAAgB,CAAC;AACvB,QAAM,OAAO,CAAC,KAA8B,QAAgB,UAAkB;AAC5E,eAAW,KAAK,OAAO,KAAK,GAAG,GAAG;AAChC,UAAI,IAAI,UAAU,eAAgB;AAClC,YAAM,OAAO,SAAS,GAAG,MAAM,IAAI,CAAC,KAAK;AACzC,UAAI;AACJ,UAAI;AACF,YAAI,IAAI,CAAC;AAAA,MACX,QAAQ;AACN;AAAA,MACF;AACA,UAAI,MAAM,CAAC,GAAG;AACZ,YAAI,SAAS,KAAM,KAAI,KAAK,IAAI;AAAA,MAClC,WAAW,QAAQ,CAAC,KAAK,QAAQ,UAAW,MAAK,GAAG,MAAM,QAAQ,CAAC;AAAA,IACrE;AAAA,EACF;AACA,MAAI,QAAQ,GAAG,EAAG,MAAK,KAAK,IAAI,CAAC;AACjC,SAAO;AACT;AAGA,SAAS,YAAY,GAAW,OAAwC;AACtE,QAAM,OAAO,oBAAI,IAAY;AAC7B,WAAS,IAAI,GAAG,IAAI,GAAG,KAAK;AAC1B,UAAM,IAAI,MAAM,CAAC;AACjB,QAAI,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI,OAAO,CAAC,CAAC,EAAG,QAAO;AAC7C,SAAK,IAAI,OAAO,CAAC,CAAC;AAAA,EACpB;AACA,SAAO;AACT;AAQO,SAAS,iBACd,MACA,YACA,WAAW,YACG;AACd,MAAI,KAAK,WAAW,EAAG,QAAO,EAAE,QAAQ,CAAC,EAAE;AAC3C,QAAM,QAAQ,WAAW,KAAK,CAAC,GAAG,UAAU;AAC5C,QAAM,WAAW,MAAM,IAAI,WAAW;AACtC,QAAM,KAAK,CAAC,SAAuB,CAAC,MAAc,SAAS,KAAK,CAAC,GAAG,IAAI;AACxE,QAAM,SAAmB,CAAC;AAC1B,WAAS,IAAI,GAAG,IAAI,MAAM,UAAU,OAAO,SAAS,YAAY,KAAK;AACnE,QAAI,YAAY,KAAK,QAAQ,GAAG,SAAS,CAAC,CAAiB,CAAC,EAAG,QAAO,KAAK,MAAM,CAAC,CAAW;AAAA,EAC/F;AACA,MAAI,OAAO,SAAS,KAAK,aAAa,OAAW,QAAO,EAAE,OAAO;AACjE,QAAM,MAAM,GAAG,YAAY,QAAQ,CAAC;AACpC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,UAAM,QAAQ,GAAG,SAAS,CAAC,CAAiB;AAC5C,UAAM,KAAK,YAAY,KAAK,QAAQ,CAAC,MAAM;AACzC,YAAM,IAAI,IAAI,CAAC;AACf,YAAM,IAAI,MAAM,CAAC;AACjB,aAAO,MAAM,CAAC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK;AAAA,IAC9C,CAAC;AACD,QAAI,GAAI,QAAO,EAAE,QAAQ,MAAM,MAAM,CAAC,EAAY;AAAA,EACpD;AACA,SAAO,EAAE,OAAO;AAClB;","names":[]}

package/dist/intercept/boundary.cjs

@@ -25,6 +25,8 @@ __export(boundary_exports, {
 module.exports = __toCommonJS(boundary_exports);
 var import_build = require("../diagnostics/build.cjs");
 var import_catalog = require("../diagnostics/catalog.cjs");
+var import_process_guard = require("../diagnostics/process-guard.cjs");
+var import_prose = require("../diagnostics/prose.cjs");
 var import_redact = require("../diagnostics/redact.cjs");
 var import_classify = require("./classify.cjs");
 var import_codes = require("./codes.cjs");
@@ -40,7 +42,7 @@ function recover(ctx, error) {
     if (!silenced.has(ctx.emit)) {
       silenced.add(ctx.emit);
       console.error(
-        `[DataKable] ${ctx.op} failed; ${fallback.describe}. Later failures are silent.`,
+        `[DataKable] ${ctx.op} failed; ${(0, import_prose.expandProse)(fallback.describe, process.env.NODE_ENV !== "production")}. Later failures are silent.`,
         process.env.NODE_ENV !== "production" ? error : (0, import_redact.scrubError)(error)
       );
     }
@@ -69,7 +71,7 @@ function recover(ctx, error) {
       "DK_INTERNAL",
       {
         op: ctx.op,
-        problem: "an exception escaped DataKable code",
+        problem: "escaped",
         message: error.message,
         ...slot,
         errorName: error.name,

package/dist/intercept/boundary.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/intercept/boundary.ts"],"sourcesContent":["import { DatakableError } from '../diagnostics/build'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport { scrubError } from '../diagnostics/redact'\nimport type { EmitOptions } from '../diagnostics/types'\nimport { type CallbackError, classifyError, errorName } from './classify'\nimport { boundaryDiagnostics } from './codes'\nimport type { InterceptorContext } from './context'\nimport type { Interceptor } from './define'\nimport { FAILED, getFallback } from './fallbacks'\nimport type { OpName } from './operations'\n\nkeepDiagnostics(boundaryDiagnostics)\n\n/** Emitters (one per table) that already printed their silent `diagnostic:emit` failure. */\nconst silenced = new WeakSet<object>()\n\nconst isThenable = (v: unknown): v is PromiseLike<unknown> =>\n  v != null && typeof (v as { then?: unknown }).then === 'function'\n\n/** catch → classify → emit → registry fallback (§3.4). */\nfunction recover(ctx: InterceptorContext, error: unknown): unknown {\n  // Config errors, `strict: true` rethrows and core invariants are meant to reach the caller.\n  if (error instanceof DatakableError) throw error\n  ctx.meta.set(FAILED, error)\n  const fallback = getFallback(ctx.op)\n  if (fallback.silent) {\n    if (!silenced.has(ctx.emit)) {\n      silenced.add(ctx.emit)\n      // Production prints the error name only: its message can embed row values (§8.2).\n      console.error(\n        `[DataKable] ${ctx.op} failed; ${fallback.describe}. Later failures are silent.`,\n        (process.env.NODE_ENV !== \"production\") ? error : scrubError(error),\n      )\n    }\n    return fallback.value(ctx as never)\n  }\n  const opts: EmitOptions = { run: ctx.run, trigger: ctx.trigger, phase: ctx.phase }\n  const slot = ctx.where ? { slot: ctx.where } : {}\n  const code = classifyError(error)\n  if (code === 'DK_CALLBACK_FAILED') {\n    const e = error as CallbackError\n    const name = errorName(e.cause)\n    ctx.emit(\n      'DK_CALLBACK_FAILED',\n      {\n        slot: e.slot,\n        ...(e.op === undefined ? {} : { op: e.op }),\n        ...(e.row === undefined ? {} : { rows: [e.row] }),\n        count: 1,\n        fallback: fallback.describe,\n        ...(name === undefined ? {} : { errorName: name }),\n      },\n      { ...opts, cause: e.cause },\n    )\n  } else if (code === 'DK_INTERNAL') {\n    ctx.emit(\n      'DK_INTERNAL',\n      {\n        op: ctx.op,\n        problem: 'an exception escaped DataKable code',\n        message: (error as Error).message,\n        ...slot,\n        errorName: (error as Error).name,\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  } else {\n    const name = errorName(error)\n    ctx.emit(\n      'DK_UNKNOWN',\n      {\n        op: ctx.op,\n        ...slot,\n        ...(name === undefined ? {} : { errorName: name }),\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  }\n  return fallback.value(ctx as never)\n}\n\n/**\n * The outermost, non-removable interceptor (§3.4, §8.6). Install it once per table with\n * `runtime.installBoundary(errorBoundary)`. Reports through `ctx.emit`, so its sinks are the table's\n * diagnostics sinks. Hot-safe: the success path is one `try` and a thenable check, no allocation.\n */\nexport const errorBoundary: Interceptor<OpName> = {\n  name: 'errorBoundary',\n  on: '*',\n  hot: true,\n  intercept(ctx, next) {\n    let out: unknown\n    try {\n      out = next()\n    } catch (e) {\n      return recover(ctx, e) as never\n    }\n    if (isThenable(out)) {\n      return Promise.resolve(out).then(undefined, (e: unknown) => recover(ctx, e)) as never\n    }\n    return out as never\n  },\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA+B;AAC/B,qBAAgC;AAChC,oBAA2B;AAE3B,sBAA6D;AAC7D,mBAAoC;AAGpC,uBAAoC;AAAA,IAGpC,gCAAgB,gCAAmB;AAGnC,IAAM,WAAW,oBAAI,QAAgB;AAErC,IAAM,aAAa,CAAC,MAClB,KAAK,QAAQ,OAAQ,EAAyB,SAAS;AAGzD,SAAS,QAAQ,KAAyB,OAAyB;AAEjE,MAAI,iBAAiB,4BAAgB,OAAM;AAC3C,MAAI,KAAK,IAAI,yBAAQ,KAAK;AAC1B,QAAM,eAAW,8BAAY,IAAI,EAAE;AACnC,MAAI,SAAS,QAAQ;AACnB,QAAI,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG;AAC3B,eAAS,IAAI,IAAI,IAAI;AAErB,cAAQ;AAAA,QACN,eAAe,IAAI,EAAE,YAAY,SAAS,QAAQ;AAAA,QACjD,QAAQ,IAAI,aAAa,eAAgB,YAAQ,0BAAW,KAAK;AAAA,MACpE;AAAA,IACF;AACA,WAAO,SAAS,MAAM,GAAY;AAAA,EACpC;AACA,QAAM,OAAoB,EAAE,KAAK,IAAI,KAAK,SAAS,IAAI,SAAS,OAAO,IAAI,MAAM;AACjF,QAAM,OAAO,IAAI,QAAQ,EAAE,MAAM,IAAI,MAAM,IAAI,CAAC;AAChD,QAAM,WAAO,+BAAc,KAAK;AAChC,MAAI,SAAS,sBAAsB;AACjC,UAAM,IAAI;AACV,UAAM,WAAO,2BAAU,EAAE,KAAK;AAC9B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,MAAM,EAAE;AAAA,QACR,GAAI,EAAE,OAAO,SAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG;AAAA,QACzC,GAAI,EAAE,QAAQ,SAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE;AAAA,QAC/C,OAAO;AAAA,QACP,UAAU,SAAS;AAAA,QACnB,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,MAClD;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,EAAE,MAAM;AAAA,IAC5B;AAAA,EACF,WAAW,SAAS,eAAe;AACjC,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,SAAS;AAAA,QACT,SAAU,MAAgB;AAAA,QAC1B,GAAG;AAAA,QACH,WAAY,MAAgB;AAAA,QAC5B,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF,OAAO;AACL,UAAM,WAAO,2BAAU,KAAK;AAC5B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,GAAG;AAAA,QACH,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,QAChD,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,SAAO,SAAS,MAAM,GAAY;AACpC;AAOO,IAAM,gBAAqC;AAAA,EAChD,MAAM;AAAA,EACN,IAAI;AAAA,EACJ,KAAK;AAAA,EACL,UAAU,KAAK,MAAM;AACnB,QAAI;AACJ,QAAI;AACF,YAAM,KAAK;AAAA,IACb,SAAS,GAAG;AACV,aAAO,QAAQ,KAAK,CAAC;AAAA,IACvB;AACA,QAAI,WAAW,GAAG,GAAG;AACnB,aAAO,QAAQ,QAAQ,GAAG,EAAE,KAAK,QAAW,CAAC,MAAe,QAAQ,KAAK,CAAC,CAAC;AAAA,IAC7E;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/intercept/boundary.ts"],"sourcesContent":["import { DatakableError } from '../diagnostics/build'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport '../diagnostics/process-guard'\nimport { expandProse } from '../diagnostics/prose'\nimport { scrubError } from '../diagnostics/redact'\nimport type { EmitOptions } from '../diagnostics/types'\nimport { type CallbackError, classifyError, errorName } from './classify'\nimport { boundaryDiagnostics } from './codes'\nimport type { InterceptorContext } from './context'\nimport type { Interceptor } from './define'\nimport { FAILED, getFallback } from './fallbacks'\nimport type { OpName } from './operations'\n\nkeepDiagnostics(boundaryDiagnostics)\n\n/** Emitters (one per table) that already printed their silent `diagnostic:emit` failure. */\nconst silenced = new WeakSet<object>()\n\nconst isThenable = (v: unknown): v is PromiseLike<unknown> =>\n  v != null && typeof (v as { then?: unknown }).then === 'function'\n\n/** catch → classify → emit → registry fallback (§3.4). */\nfunction recover(ctx: InterceptorContext, error: unknown): unknown {\n  // Config errors, `strict: true` rethrows and core invariants are meant to reach the caller.\n  if (error instanceof DatakableError) throw error\n  ctx.meta.set(FAILED, error)\n  const fallback = getFallback(ctx.op)\n  if (fallback.silent) {\n    if (!silenced.has(ctx.emit)) {\n      silenced.add(ctx.emit)\n      // Production prints the error name only: its message can embed row values (§8.2).\n      console.error(\n        `[DataKable] ${ctx.op} failed; ${expandProse(fallback.describe, (process.env.NODE_ENV !== \"production\"))}. Later failures are silent.`,\n        (process.env.NODE_ENV !== \"production\") ? error : scrubError(error),\n      )\n    }\n    return fallback.value(ctx as never)\n  }\n  const opts: EmitOptions = { run: ctx.run, trigger: ctx.trigger, phase: ctx.phase }\n  const slot = ctx.where ? { slot: ctx.where } : {}\n  const code = classifyError(error)\n  if (code === 'DK_CALLBACK_FAILED') {\n    const e = error as CallbackError\n    const name = errorName(e.cause)\n    ctx.emit(\n      'DK_CALLBACK_FAILED',\n      {\n        slot: e.slot,\n        ...(e.op === undefined ? {} : { op: e.op }),\n        ...(e.row === undefined ? {} : { rows: [e.row] }),\n        count: 1,\n        fallback: fallback.describe,\n        ...(name === undefined ? {} : { errorName: name }),\n      },\n      { ...opts, cause: e.cause },\n    )\n  } else if (code === 'DK_INTERNAL') {\n    ctx.emit(\n      'DK_INTERNAL',\n      {\n        op: ctx.op,\n        problem: 'escaped',\n        message: (error as Error).message,\n        ...slot,\n        errorName: (error as Error).name,\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  } else {\n    const name = errorName(error)\n    ctx.emit(\n      'DK_UNKNOWN',\n      {\n        op: ctx.op,\n        ...slot,\n        ...(name === undefined ? {} : { errorName: name }),\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  }\n  return fallback.value(ctx as never)\n}\n\n/**\n * The outermost, non-removable interceptor (§3.4, §8.6). Install it once per table with\n * `runtime.installBoundary(errorBoundary)`. Reports through `ctx.emit`, so its sinks are the table's\n * diagnostics sinks. Hot-safe: the success path is one `try` and a thenable check, no allocation.\n */\nexport const errorBoundary: Interceptor<OpName> = {\n  name: 'errorBoundary',\n  on: '*',\n  hot: true,\n  intercept(ctx, next) {\n    let out: unknown\n    try {\n      out = next()\n    } catch (e) {\n      return recover(ctx, e) as never\n    }\n    if (isThenable(out)) {\n      return Promise.resolve(out).then(undefined, (e: unknown) => recover(ctx, e)) as never\n    }\n    return out as never\n  },\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAA+B;AAC/B,qBAAgC;AAChC,2BAAO;AACP,mBAA4B;AAC5B,oBAA2B;AAE3B,sBAA6D;AAC7D,mBAAoC;AAGpC,uBAAoC;AAAA,IAGpC,gCAAgB,gCAAmB;AAGnC,IAAM,WAAW,oBAAI,QAAgB;AAErC,IAAM,aAAa,CAAC,MAClB,KAAK,QAAQ,OAAQ,EAAyB,SAAS;AAGzD,SAAS,QAAQ,KAAyB,OAAyB;AAEjE,MAAI,iBAAiB,4BAAgB,OAAM;AAC3C,MAAI,KAAK,IAAI,yBAAQ,KAAK;AAC1B,QAAM,eAAW,8BAAY,IAAI,EAAE;AACnC,MAAI,SAAS,QAAQ;AACnB,QAAI,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG;AAC3B,eAAS,IAAI,IAAI,IAAI;AAErB,cAAQ;AAAA,QACN,eAAe,IAAI,EAAE,gBAAY,0BAAY,SAAS,UAAW,QAAQ,IAAI,aAAa,YAAa,CAAC;AAAA,QACvG,QAAQ,IAAI,aAAa,eAAgB,YAAQ,0BAAW,KAAK;AAAA,MACpE;AAAA,IACF;AACA,WAAO,SAAS,MAAM,GAAY;AAAA,EACpC;AACA,QAAM,OAAoB,EAAE,KAAK,IAAI,KAAK,SAAS,IAAI,SAAS,OAAO,IAAI,MAAM;AACjF,QAAM,OAAO,IAAI,QAAQ,EAAE,MAAM,IAAI,MAAM,IAAI,CAAC;AAChD,QAAM,WAAO,+BAAc,KAAK;AAChC,MAAI,SAAS,sBAAsB;AACjC,UAAM,IAAI;AACV,UAAM,WAAO,2BAAU,EAAE,KAAK;AAC9B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,MAAM,EAAE;AAAA,QACR,GAAI,EAAE,OAAO,SAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG;AAAA,QACzC,GAAI,EAAE,QAAQ,SAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE;AAAA,QAC/C,OAAO;AAAA,QACP,UAAU,SAAS;AAAA,QACnB,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,MAClD;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,EAAE,MAAM;AAAA,IAC5B;AAAA,EACF,WAAW,SAAS,eAAe;AACjC,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,SAAS;AAAA,QACT,SAAU,MAAgB;AAAA,QAC1B,GAAG;AAAA,QACH,WAAY,MAAgB;AAAA,QAC5B,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF,OAAO;AACL,UAAM,WAAO,2BAAU,KAAK;AAC5B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,GAAG;AAAA,QACH,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,QAChD,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,SAAO,SAAS,MAAM,GAAY;AACpC;AAOO,IAAM,gBAAqC;AAAA,EAChD,MAAM;AAAA,EACN,IAAI;AAAA,EACJ,KAAK;AAAA,EACL,UAAU,KAAK,MAAM;AACnB,QAAI;AACJ,QAAI;AACF,YAAM,KAAK;AAAA,IACb,SAAS,GAAG;AACV,aAAO,QAAQ,KAAK,CAAC;AAAA,IACvB;AACA,QAAI,WAAW,GAAG,GAAG;AACnB,aAAO,QAAQ,QAAQ,GAAG,EAAE,KAAK,QAAW,CAAC,MAAe,QAAQ,KAAK,CAAC,CAAC;AAAA,IAC7E;AACA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/intercept/boundary.js

@@ -1,6 +1,8 @@
 // src/intercept/boundary.ts
 import { DatakableError } from "../diagnostics/build.js";
 import { keepDiagnostics } from "../diagnostics/catalog.js";
+import "../diagnostics/process-guard.js";
+import { expandProse } from "../diagnostics/prose.js";
 import { scrubError } from "../diagnostics/redact.js";
 import { classifyError, errorName } from "./classify.js";
 import { boundaryDiagnostics } from "./codes.js";
@@ -16,7 +18,7 @@ function recover(ctx, error) {
     if (!silenced.has(ctx.emit)) {
       silenced.add(ctx.emit);
       console.error(
-        `[DataKable] ${ctx.op} failed; ${fallback.describe}. Later failures are silent.`,
+        `[DataKable] ${ctx.op} failed; ${expandProse(fallback.describe, process.env.NODE_ENV !== "production")}. Later failures are silent.`,
         process.env.NODE_ENV !== "production" ? error : scrubError(error)
       );
     }
@@ -45,7 +47,7 @@ function recover(ctx, error) {
       "DK_INTERNAL",
       {
         op: ctx.op,
-        problem: "an exception escaped DataKable code",
+        problem: "escaped",
         message: error.message,
         ...slot,
         errorName: error.name,

package/dist/intercept/boundary.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/intercept/boundary.ts"],"sourcesContent":["import { DatakableError } from '../diagnostics/build'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport { scrubError } from '../diagnostics/redact'\nimport type { EmitOptions } from '../diagnostics/types'\nimport { type CallbackError, classifyError, errorName } from './classify'\nimport { boundaryDiagnostics } from './codes'\nimport type { InterceptorContext } from './context'\nimport type { Interceptor } from './define'\nimport { FAILED, getFallback } from './fallbacks'\nimport type { OpName } from './operations'\n\nkeepDiagnostics(boundaryDiagnostics)\n\n/** Emitters (one per table) that already printed their silent `diagnostic:emit` failure. */\nconst silenced = new WeakSet<object>()\n\nconst isThenable = (v: unknown): v is PromiseLike<unknown> =>\n  v != null && typeof (v as { then?: unknown }).then === 'function'\n\n/** catch → classify → emit → registry fallback (§3.4). */\nfunction recover(ctx: InterceptorContext, error: unknown): unknown {\n  // Config errors, `strict: true` rethrows and core invariants are meant to reach the caller.\n  if (error instanceof DatakableError) throw error\n  ctx.meta.set(FAILED, error)\n  const fallback = getFallback(ctx.op)\n  if (fallback.silent) {\n    if (!silenced.has(ctx.emit)) {\n      silenced.add(ctx.emit)\n      // Production prints the error name only: its message can embed row values (§8.2).\n      console.error(\n        `[DataKable] ${ctx.op} failed; ${fallback.describe}. Later failures are silent.`,\n        (process.env.NODE_ENV !== \"production\") ? error : scrubError(error),\n      )\n    }\n    return fallback.value(ctx as never)\n  }\n  const opts: EmitOptions = { run: ctx.run, trigger: ctx.trigger, phase: ctx.phase }\n  const slot = ctx.where ? { slot: ctx.where } : {}\n  const code = classifyError(error)\n  if (code === 'DK_CALLBACK_FAILED') {\n    const e = error as CallbackError\n    const name = errorName(e.cause)\n    ctx.emit(\n      'DK_CALLBACK_FAILED',\n      {\n        slot: e.slot,\n        ...(e.op === undefined ? {} : { op: e.op }),\n        ...(e.row === undefined ? {} : { rows: [e.row] }),\n        count: 1,\n        fallback: fallback.describe,\n        ...(name === undefined ? {} : { errorName: name }),\n      },\n      { ...opts, cause: e.cause },\n    )\n  } else if (code === 'DK_INTERNAL') {\n    ctx.emit(\n      'DK_INTERNAL',\n      {\n        op: ctx.op,\n        problem: 'an exception escaped DataKable code',\n        message: (error as Error).message,\n        ...slot,\n        errorName: (error as Error).name,\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  } else {\n    const name = errorName(error)\n    ctx.emit(\n      'DK_UNKNOWN',\n      {\n        op: ctx.op,\n        ...slot,\n        ...(name === undefined ? {} : { errorName: name }),\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  }\n  return fallback.value(ctx as never)\n}\n\n/**\n * The outermost, non-removable interceptor (§3.4, §8.6). Install it once per table with\n * `runtime.installBoundary(errorBoundary)`. Reports through `ctx.emit`, so its sinks are the table's\n * diagnostics sinks. Hot-safe: the success path is one `try` and a thenable check, no allocation.\n */\nexport const errorBoundary: Interceptor<OpName> = {\n  name: 'errorBoundary',\n  on: '*',\n  hot: true,\n  intercept(ctx, next) {\n    let out: unknown\n    try {\n      out = next()\n    } catch (e) {\n      return recover(ctx, e) as never\n    }\n    if (isThenable(out)) {\n      return Promise.resolve(out).then(undefined, (e: unknown) => recover(ctx, e)) as never\n    }\n    return out as never\n  },\n}\n"],"mappings":";AAAA,SAAS,sBAAsB;AAC/B,SAAS,uBAAuB;AAChC,SAAS,kBAAkB;AAE3B,SAA6B,eAAe,iBAAiB;AAC7D,SAAS,2BAA2B;AAGpC,SAAS,QAAQ,mBAAmB;AAGpC,gBAAgB,mBAAmB;AAGnC,IAAM,WAAW,oBAAI,QAAgB;AAErC,IAAM,aAAa,CAAC,MAClB,KAAK,QAAQ,OAAQ,EAAyB,SAAS;AAGzD,SAAS,QAAQ,KAAyB,OAAyB;AAEjE,MAAI,iBAAiB,eAAgB,OAAM;AAC3C,MAAI,KAAK,IAAI,QAAQ,KAAK;AAC1B,QAAM,WAAW,YAAY,IAAI,EAAE;AACnC,MAAI,SAAS,QAAQ;AACnB,QAAI,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG;AAC3B,eAAS,IAAI,IAAI,IAAI;AAErB,cAAQ;AAAA,QACN,eAAe,IAAI,EAAE,YAAY,SAAS,QAAQ;AAAA,QACjD,QAAQ,IAAI,aAAa,eAAgB,QAAQ,WAAW,KAAK;AAAA,MACpE;AAAA,IACF;AACA,WAAO,SAAS,MAAM,GAAY;AAAA,EACpC;AACA,QAAM,OAAoB,EAAE,KAAK,IAAI,KAAK,SAAS,IAAI,SAAS,OAAO,IAAI,MAAM;AACjF,QAAM,OAAO,IAAI,QAAQ,EAAE,MAAM,IAAI,MAAM,IAAI,CAAC;AAChD,QAAM,OAAO,cAAc,KAAK;AAChC,MAAI,SAAS,sBAAsB;AACjC,UAAM,IAAI;AACV,UAAM,OAAO,UAAU,EAAE,KAAK;AAC9B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,MAAM,EAAE;AAAA,QACR,GAAI,EAAE,OAAO,SAAY,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG;AAAA,QACzC,GAAI,EAAE,QAAQ,SAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE;AAAA,QAC/C,OAAO;AAAA,QACP,UAAU,SAAS;AAAA,QACnB,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,MAClD;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,EAAE,MAAM;AAAA,IAC5B;AAAA,EACF,WAAW,SAAS,eAAe;AACjC,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,SAAS;AAAA,QACT,SAAU,MAAgB;AAAA,QAC1B,GAAG;AAAA,QACH,WAAY,MAAgB;AAAA,QAC5B,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF,OAAO;AACL,UAAM,OAAO,UAAU,KAAK;AAC5B,QAAI;AAAA,MACF;AAAA,MACA;AAAA,QACE,IAAI,IAAI;AAAA,QACR,GAAG;AAAA,QACH,GAAI,SAAS,SAAY,CAAC,IAAI,EAAE,WAAW,KAAK;AAAA,QAChD,UAAU,SAAS;AAAA,MACrB;AAAA,MACA,EAAE,GAAG,MAAM,OAAO,MAAM;AAAA,IAC1B;AAAA,EACF;AACA,SAAO,SAAS,MAAM,GAAY;AACpC;AAOO,IAAM,gBAAqC;AAAA,EAChD,MAAM;AAAA,EACN,IAAI;AAAA,EACJ,KAAK;AAAA,EACL,UAAU,KAAK,MAAM;AACnB,QAAI;AACJ,QAAI;AACF,YAAM,KAAK;AAAA,IACb,SAAS,GAAG;AACV,aAAO,QAAQ,KAAK,CAAC;AAAA,IACvB;AACA,QAAI,WAAW,GAAG,GAAG;AACnB,aAAO,QAAQ,QAAQ,GAAG,EAAE,KAAK,QAAW,CAAC,MAAe,QAAQ,KAAK,CAAC,CAAC;AAAA,IAC7E;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../../src/intercept/boundary.ts"],"sourcesContent":["import { DatakableError } from '../diagnostics/build'\nimport { keepDiagnostics } from '../diagnostics/catalog'\nimport '../diagnostics/process-guard'\nimport { expandProse } from '../diagnostics/prose'\nimport { scrubError } from '../diagnostics/redact'\nimport type { EmitOptions } from '../diagnostics/types'\nimport { type CallbackError, classifyError, errorName } from './classify'\nimport { boundaryDiagnostics } from './codes'\nimport type { InterceptorContext } from './context'\nimport type { Interceptor } from './define'\nimport { FAILED, getFallback } from './fallbacks'\nimport type { OpName } from './operations'\n\nkeepDiagnostics(boundaryDiagnostics)\n\n/** Emitters (one per table) that already printed their silent `diagnostic:emit` failure. */\nconst silenced = new WeakSet<object>()\n\nconst isThenable = (v: unknown): v is PromiseLike<unknown> =>\n  v != null && typeof (v as { then?: unknown }).then === 'function'\n\n/** catch → classify → emit → registry fallback (§3.4). */\nfunction recover(ctx: InterceptorContext, error: unknown): unknown {\n  // Config errors, `strict: true` rethrows and core invariants are meant to reach the caller.\n  if (error instanceof DatakableError) throw error\n  ctx.meta.set(FAILED, error)\n  const fallback = getFallback(ctx.op)\n  if (fallback.silent) {\n    if (!silenced.has(ctx.emit)) {\n      silenced.add(ctx.emit)\n      // Production prints the error name only: its message can embed row values (§8.2).\n      console.error(\n        `[DataKable] ${ctx.op} failed; ${expandProse(fallback.describe, (process.env.NODE_ENV !== \"production\"))}. Later failures are silent.`,\n        (process.env.NODE_ENV !== \"production\") ? error : scrubError(error),\n      )\n    }\n    return fallback.value(ctx as never)\n  }\n  const opts: EmitOptions = { run: ctx.run, trigger: ctx.trigger, phase: ctx.phase }\n  const slot = ctx.where ? { slot: ctx.where } : {}\n  const code = classifyError(error)\n  if (code === 'DK_CALLBACK_FAILED') {\n    const e = error as CallbackError\n    const name = errorName(e.cause)\n    ctx.emit(\n      'DK_CALLBACK_FAILED',\n      {\n        slot: e.slot,\n        ...(e.op === undefined ? {} : { op: e.op }),\n        ...(e.row === undefined ? {} : { rows: [e.row] }),\n        count: 1,\n        fallback: fallback.describe,\n        ...(name === undefined ? {} : { errorName: name }),\n      },\n      { ...opts, cause: e.cause },\n    )\n  } else if (code === 'DK_INTERNAL') {\n    ctx.emit(\n      'DK_INTERNAL',\n      {\n        op: ctx.op,\n        problem: 'escaped',\n        message: (error as Error).message,\n        ...slot,\n        errorName: (error as Error).name,\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  } else {\n    const name = errorName(error)\n    ctx.emit(\n      'DK_UNKNOWN',\n      {\n        op: ctx.op,\n        ...slot,\n        ...(name === undefined ? {} : { errorName: name }),\n        fallback: fallback.describe,\n      },\n      { ...opts, cause: error },\n    )\n  }\n  return fallback.value(ctx as never)\n}\n\n/**\n * The outermost, non-removable interceptor (§3.4, §8.6). Install it once per table with\n * `runtime.installBoundary(errorBoundary)`. Reports through `ctx.emit`, so its sinks are the table's\n * diagnostics sinks. Hot-safe: the success path is one `try` and a thenable check, no allocation.\n */\nexport const errorBoundary: Interceptor<OpName> = {\n  name: 'errorBoundary',\n  on: '*',\n  hot: true,\n  intercept(ctx, next) {\n    let out: unknown\n    try {\n      out = next()\n    } catch (e) {\n      return recover(ctx, e) as never\n    }\n    if (isThenable(out)) {\n      return Promise.resolve(out).then(undefined, (e: unknown) => recover(ctx, e)) as never\n    }\n    return out as never\n  },\n}\n"],"mappings":"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","names":[]}