@datakable/core 1.0.0 → 1.1.0

package/dist/diagnostics/redact.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/redact.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from './catalog'\nimport type { Location } from './types'\n\ndeclare module './catalog' {\n  interface DiagnosticCatalog {\n    DK_UNSAFE_REDACTION: { level: 'full' }\n  }\n}\n\n/**\n * Redaction levels (§8.2). `'safe'`: paths, indices, counts, value types, hashed row keys\n * (production default). `'keys'`: + raw row keys (development default). `'full'`: + row values.\n */\nexport type RedactLevel = 'safe' | 'keys' | 'full'\n\n/**\n * Custom rule: return a string to log instead of `value`, or `undefined` for the built-in policy.\n * `path` names the field, e.g. `where.key`, `details.value`, `details.keys.2`, `details.issues.0`.\n * Sensitive columns never reach it.\n */\nexport type RedactFn = (path: string, value: unknown) => string | undefined\n\nexport interface RedactionOptions {\n  /** Default `'keys'` in development, `'safe'` in production. */\n  level?: RedactLevel\n  redact?: RedactFn\n  /** Ids / keys of `sensitive: true` columns: never logged at any level. */\n  sensitiveColumns?: () => Iterable<string>\n  /** The `rowKey` column is sensitive: row keys are hashed at every level. */\n  rowKeySensitive?: () => boolean\n}\n\n/**\n * Which detail fields of a diagnostic carry user data, declared on its `defineDiagnostic` entry.\n * Undeclared fields are logged as-is, so they must hold only DataKable-safe data (paths, ids,\n * indices, counts). Text builders receive the redacted values: treat these fields as opaque and\n * only interpolate them.\n *\n * - `rowKey` / `rowKeys`: a row key / an array of them (hashed under `'safe'`).\n * - `value` / `values`: a cell value / an array of them (type summary unless `'full'`). The column\n *   is `details.column` when it is a string, else the `where` column id.\n * - `schemaIssues`: one Standard Schema issue or an array of them (`scrubSchemaIssue`).\n * - `error`: a thrown value, e.g. a fetcher error (`scrubError`).\n */\nexport type RedactField = 'rowKey' | 'rowKeys' | 'value' | 'values' | 'schemaIssues' | 'error'\n\n/** A resolved policy, built once per emit. */\nexport interface Redactor {\n  level: RedactLevel\n  custom: RedactFn | undefined\n  sensitive: ReadonlySet<string>\n  rowKeySensitive: boolean\n  /** Called when the custom rule throws; the value is logged as `[redacted]`. */\n  onError?: (error: unknown) => void\n}\n\nexport const SENSITIVE = '[sensitive]'\nexport const REDACTED = '[redacted]'\n\nconst LEVELS: readonly string[] = ['safe', 'keys', 'full']\nconst EMPTY: ReadonlySet<string> = new Set()\n\nexport function resolveRedaction(\n  option: RedactLevel | RedactionOptions | undefined,\n  dev: boolean,\n): Redactor {\n  const o: RedactionOptions = typeof option === 'string' ? { level: option } : (option ?? {})\n  const level = o.level ?? (dev ? 'keys' : 'safe')\n  const cols = o.sensitiveColumns?.()\n  return {\n    // An unknown level gets the strictest policy; validating the option is optionValidator's job.\n    level: LEVELS.includes(level) ? level : 'safe',\n    custom: o.redact,\n    sensitive: cols ? new Set(cols) : EMPTY,\n    rowKeySensitive: o.rowKeySensitive?.() ?? false,\n  }\n}\n\n/** Short 32-bit FNV-1a hash of `String(key)` (UTF-16 code units), as `h:xxxxxxxx`. */\nexport function hashRowKey(key: unknown): string {\n  const s = String(key)\n  let h = 0x811c9dc5\n  for (let i = 0; i < s.length; i++) {\n    h ^= s.charCodeAt(i)\n    h = Math.imul(h, 0x01000193)\n  }\n  return `h:${(h >>> 0).toString(16).padStart(8, '0')}`\n}\n\n/** The value's type, never its contents: `string(12)`, `number`, `array(3)`, `date`, … */\nexport function describeValue(v: unknown): string {\n  if (v === null) return 'null'\n  if (typeof v === 'string') return `string(${v.length})`\n  if (typeof v === 'number') return Number.isNaN(v) ? 'number(NaN)' : 'number'\n  if (Array.isArray(v)) return `array(${v.length})`\n  if (v instanceof Date) return 'date'\n  return typeof v\n}\n\nfunction custom(r: Redactor, path: string, value: unknown): string | undefined {\n  if (!r.custom) return undefined\n  try {\n    return r.custom(path, value)\n  } catch (e) {\n    r.onError?.(e)\n    return REDACTED\n  }\n}\n\nfunction redactKey(r: Redactor, path: string, key: unknown): unknown {\n  // A sensitive rowKey column wins over the custom rule and the level.\n  if (r.rowKeySensitive) return hashRowKey(key)\n  const c = custom(r, path, key)\n  if (c !== undefined) return c\n  return r.level === 'safe' ? hashRowKey(key) : key\n}\n\nfunction redactValue(r: Redactor, path: string, value: unknown, column?: string): unknown {\n  if (column !== undefined && r.sensitive.has(column)) return SENSITIVE\n  const c = custom(r, path, value)\n  if (c !== undefined) return c\n  return r.level === 'full' ? value : describeValue(value)\n}\n\ntype IssuePath = ReadonlyArray<PropertyKey | { key: PropertyKey }>\n\n/** Joins a Standard Schema issue path: `['user', 0, { key: 'email' }]` → `user.0.email`. */\nfunction issuePath(path: IssuePath | undefined): string {\n  if (!path) return ''\n  return path.map((s) => String(typeof s === 'object' && s !== null ? s.key : s)).join('.')\n}\n\nfunction underSensitive(r: Redactor, path: string): boolean {\n  if (r.sensitive.size === 0) return false\n  for (const col of r.sensitive) if (path === col || path.startsWith(`${col}.`)) return true\n  return false\n}\n\n/**\n * A schema issue as `{ path, message }`. Validators embed received values in their messages, so\n * under `'safe'` / `'keys'` (and for sensitive columns) the message is DataKable's own text.\n */\nexport function scrubSchemaIssue(\n  issue: unknown,\n  r: Redactor,\n  fieldPath = 'issue',\n): { path: string; message: string } {\n  const i = (typeof issue === 'object' && issue !== null ? issue : {}) as {\n    message?: unknown\n    path?: IssuePath\n  }\n  let path: string\n  try {\n    path = issuePath(i.path)\n  } catch {\n    path = ''\n  }\n  const own = `invalid value at ${path || '(root)'}`\n  if (underSensitive(r, path)) return { path, message: own }\n  const c = custom(r, fieldPath, i.message)\n  if (c !== undefined) return { path, message: c }\n  return { path, message: r.level === 'full' && typeof i.message === 'string' ? i.message : own }\n}\n\n/**\n * A thrown value as `error.name` + `code` only (fetcher errors embed URLs, tokens, payloads). The\n * full error belongs in `context.cause`, which reaches `onDiagnostic` only.\n */\nexport function scrubError(e: unknown): string {\n  if (typeof e !== 'object' || e === null) return typeof e\n  try {\n    const { name, code } = e as { name?: unknown; code?: unknown }\n    const n = typeof name === 'string' && name ? name : 'object'\n    return typeof code === 'string' || typeof code === 'number' ? `${n} (${code})` : n\n  } catch {\n    return 'object'\n  }\n}\n\n/** Hashes / passes through `where.key` per the policy; other locations hold no user data. */\nexport function redactLocation(where: Location, r: Redactor): Location {\n  if (where.kind !== 'row' || where.key === undefined) return where\n  const key = redactKey(r, 'where.key', where.key)\n  return { kind: 'row', index: where.index, key: typeof key === 'string' ? key : String(key) }\n}\n\n/** A shallow copy of `details` with the declared fields redacted; the input is never mutated. */\nexport function redactDetails(\n  details: Record<string, unknown>,\n  fields: Readonly<Record<string, RedactField | undefined>> | undefined,\n  where: Location,\n  r: Redactor,\n): Record<string, unknown> {\n  if (!fields) return details\n  const out: Record<string, unknown> = { ...details }\n  const column =\n    typeof details.column === 'string'\n      ? details.column\n      : where.kind === 'column'\n        ? where.id\n        : undefined\n  for (const name of Object.keys(fields)) {\n    const kind = fields[name]\n    if (kind === undefined || !(name in details)) continue\n    const v = details[name]\n    const p = `details.${name}`\n    const each = (f: (x: unknown, path: string) => unknown) =>\n      Array.isArray(v) ? v.map((x, i) => f(x, `${p}.${i}`)) : f(v, p)\n    switch (kind) {\n      case 'rowKey':\n        out[name] = redactKey(r, p, v)\n        break\n      case 'rowKeys':\n        out[name] = each((x, path) => redactKey(r, path, x))\n        break\n      case 'value':\n        out[name] = redactValue(r, p, v, column)\n        break\n      case 'values':\n        out[name] = each((x, path) => redactValue(r, path, x, column))\n        break\n      case 'schemaIssues':\n        out[name] = each((x, path) => scrubSchemaIssue(x, r, path))\n        break\n      case 'error':\n        out[name] = custom(r, p, v) ?? scrubError(v)\n        break\n    }\n  }\n  return out\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const redactionMessages: DiagnosticMessages<'DK_UNSAFE_REDACTION'> = {\n  DK_UNSAFE_REDACTION: {\n    problem: (d) => `diagnostics.redact is '${d.level}' in a production build`,\n    impact: () =>\n      'raw row keys and cell values (except sensitive columns) reach onDiagnostic, ' +\n      'getDiagnostics() and the console',\n    fix: () => [\n      \"remove diagnostics.redact in production (the default is 'safe')\",\n      \"or use 'keys' to log raw row keys without cell values\",\n      'mark personal-data columns with sensitive: true so they are never logged',\n    ],\n  },\n}\n\n/** `'full'` in a production build (§8.2: \"warns if enabled in production\"). Emitted by the hub. */\nexport const DK_UNSAFE_REDACTION = defineDiagnostic(\n  {\n    code: 'DK_UNSAFE_REDACTION',\n    level: 'warn',\n    where: () => ({ kind: 'option', path: 'diagnostics.redact' }),\n  },\n  (process.env.NODE_ENV !== \"production\") && redactionMessages.DK_UNSAFE_REDACTION,\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA0D;AAwDnD,IAAM,YAAY;AAClB,IAAM,WAAW;AAExB,IAAM,SAA4B,CAAC,QAAQ,QAAQ,MAAM;AACzD,IAAM,QAA6B,oBAAI,IAAI;AAEpC,SAAS,iBACd,QACA,KACU;AACV,QAAM,IAAsB,OAAO,WAAW,WAAW,EAAE,OAAO,OAAO,IAAK,UAAU,CAAC;AACzF,QAAM,QAAQ,EAAE,UAAU,MAAM,SAAS;AACzC,QAAM,OAAO,EAAE,mBAAmB;AAClC,SAAO;AAAA;AAAA,IAEL,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;AAAA,IACxC,QAAQ,EAAE;AAAA,IACV,WAAW,OAAO,IAAI,IAAI,IAAI,IAAI;AAAA,IAClC,iBAAiB,EAAE,kBAAkB,KAAK;AAAA,EAC5C;AACF;AAGO,SAAS,WAAW,KAAsB;AAC/C,QAAM,IAAI,OAAO,GAAG;AACpB,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,SAAK,EAAE,WAAW,CAAC;AACnB,QAAI,KAAK,KAAK,GAAG,QAAU;AAAA,EAC7B;AACA,SAAO,MAAM,MAAM,GAAG,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC;AACrD;AAGO,SAAS,cAAc,GAAoB;AAChD,MAAI,MAAM,KAAM,QAAO;AACvB,MAAI,OAAO,MAAM,SAAU,QAAO,UAAU,EAAE,MAAM;AACpD,MAAI,OAAO,MAAM,SAAU,QAAO,OAAO,MAAM,CAAC,IAAI,gBAAgB;AACpE,MAAI,MAAM,QAAQ,CAAC,EAAG,QAAO,SAAS,EAAE,MAAM;AAC9C,MAAI,aAAa,KAAM,QAAO;AAC9B,SAAO,OAAO;AAChB;AAEA,SAAS,OAAO,GAAa,MAAc,OAAoC;AAC7E,MAAI,CAAC,EAAE,OAAQ,QAAO;AACtB,MAAI;AACF,WAAO,EAAE,OAAO,MAAM,KAAK;AAAA,EAC7B,SAAS,GAAG;AACV,MAAE,UAAU,CAAC;AACb,WAAO;AAAA,EACT;AACF;AAEA,SAAS,UAAU,GAAa,MAAc,KAAuB;AAEnE,MAAI,EAAE,gBAAiB,QAAO,WAAW,GAAG;AAC5C,QAAM,IAAI,OAAO,GAAG,MAAM,GAAG;AAC7B,MAAI,MAAM,OAAW,QAAO;AAC5B,SAAO,EAAE,UAAU,SAAS,WAAW,GAAG,IAAI;AAChD;AAEA,SAAS,YAAY,GAAa,MAAc,OAAgB,QAA0B;AACxF,MAAI,WAAW,UAAa,EAAE,UAAU,IAAI,MAAM,EAAG,QAAO;AAC5D,QAAM,IAAI,OAAO,GAAG,MAAM,KAAK;AAC/B,MAAI,MAAM,OAAW,QAAO;AAC5B,SAAO,EAAE,UAAU,SAAS,QAAQ,cAAc,KAAK;AACzD;AAKA,SAAS,UAAU,MAAqC;AACtD,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO,KAAK,IAAI,CAAC,MAAM,OAAO,OAAO,MAAM,YAAY,MAAM,OAAO,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG;AAC1F;AAEA,SAAS,eAAe,GAAa,MAAuB;AAC1D,MAAI,EAAE,UAAU,SAAS,EAAG,QAAO;AACnC,aAAW,OAAO,EAAE,UAAW,KAAI,SAAS,OAAO,KAAK,WAAW,GAAG,GAAG,GAAG,EAAG,QAAO;AACtF,SAAO;AACT;AAMO,SAAS,iBACd,OACA,GACA,YAAY,SACuB;AACnC,QAAM,IAAK,OAAO,UAAU,YAAY,UAAU,OAAO,QAAQ,CAAC;AAIlE,MAAI;AACJ,MAAI;AACF,WAAO,UAAU,EAAE,IAAI;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM,oBAAoB,QAAQ,QAAQ;AAChD,MAAI,eAAe,GAAG,IAAI,EAAG,QAAO,EAAE,MAAM,SAAS,IAAI;AACzD,QAAM,IAAI,OAAO,GAAG,WAAW,EAAE,OAAO;AACxC,MAAI,MAAM,OAAW,QAAO,EAAE,MAAM,SAAS,EAAE;AAC/C,SAAO,EAAE,MAAM,SAAS,EAAE,UAAU,UAAU,OAAO,EAAE,YAAY,WAAW,EAAE,UAAU,IAAI;AAChG;AAMO,SAAS,WAAW,GAAoB;AAC7C,MAAI,OAAO,MAAM,YAAY,MAAM,KAAM,QAAO,OAAO;AACvD,MAAI;AACF,UAAM,EAAE,MAAM,KAAK,IAAI;AACvB,UAAM,IAAI,OAAO,SAAS,YAAY,OAAO,OAAO;AACpD,WAAO,OAAO,SAAS,YAAY,OAAO,SAAS,WAAW,GAAG,CAAC,KAAK,IAAI,MAAM;AAAA,EACnF,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGO,SAAS,eAAe,OAAiB,GAAuB;AACrE,MAAI,MAAM,SAAS,SAAS,MAAM,QAAQ,OAAW,QAAO;AAC5D,QAAM,MAAM,UAAU,GAAG,aAAa,MAAM,GAAG;AAC/C,SAAO,EAAE,MAAM,OAAO,OAAO,MAAM,OAAO,KAAK,OAAO,QAAQ,WAAW,MAAM,OAAO,GAAG,EAAE;AAC7F;AAGO,SAAS,cACd,SACA,QACA,OACA,GACyB;AACzB,MAAI,CAAC,OAAQ,QAAO;AACpB,QAAM,MAA+B,EAAE,GAAG,QAAQ;AAClD,QAAM,SACJ,OAAO,QAAQ,WAAW,WACtB,QAAQ,SACR,MAAM,SAAS,WACb,MAAM,KACN;AACR,aAAW,QAAQ,OAAO,KAAK,MAAM,GAAG;AACtC,UAAM,OAAO,OAAO,IAAI;AACxB,QAAI,SAAS,UAAa,EAAE,QAAQ,SAAU;AAC9C,UAAM,IAAI,QAAQ,IAAI;AACtB,UAAM,IAAI,WAAW,IAAI;AACzB,UAAM,OAAO,CAAC,MACZ,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC;AAChE,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,YAAI,IAAI,IAAI,UAAU,GAAG,GAAG,CAAC;AAC7B;AAAA,MACF,KAAK;AACH,YAAI,IAAI,IAAI,KAAK,CAAC,GAAG,SAAS,UAAU,GAAG,MAAM,CAAC,CAAC;AACnD;AAAA,MACF,KAAK;AACH,YAAI,IAAI,IAAI,YAAY,GAAG,GAAG,GAAG,MAAM;AACvC;AAAA,MACF,KAAK;AACH,YAAI,IAAI,IAAI,KAAK,CAAC,GAAG,SAAS,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAC7D;AAAA,MACF,KAAK;AACH,YAAI,IAAI,IAAI,KAAK,CAAC,GAAG,SAAS,iBAAiB,GAAG,GAAG,IAAI,CAAC;AAC1D;AAAA,MACF,KAAK;AACH,YAAI,IAAI,IAAI,OAAO,GAAG,GAAG,CAAC,KAAK,WAAW,CAAC;AAC3C;AAAA,IACJ;AAAA,EACF;AACA,SAAO;AACT;AAGO,IAAM,oBAA+D;AAAA,EAC1E,qBAAqB;AAAA,IACnB,SAAS,CAAC,MAAM,0BAA0B,EAAE,KAAK;AAAA,IACjD,QAAQ,MACN;AAAA,IAEF,KAAK,MAAM;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;AAGO,IAAM,0BAAsB;AAAA,EACjC;AAAA,IACE,MAAM;AAAA,IACN,OAAO;AAAA,IACP,OAAO,OAAO,EAAE,MAAM,UAAU,MAAM,qBAAqB;AAAA,EAC7D;AAAA,EACC,QAAQ,IAAI,aAAa,gBAAiB,kBAAkB;AAC/D;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/redact.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from './catalog'\nimport './process-guard'\nimport type { Location } from './types'\n\ndeclare module './catalog' {\n  interface DiagnosticCatalog {\n    DK_UNSAFE_REDACTION: { level: 'full' }\n  }\n}\n\n/**\n * Redaction levels (§8.2). `'safe'`: paths, indices, counts, value types, hashed row keys\n * (production default). `'keys'`: + raw row keys (development default). `'full'`: + row values.\n */\nexport type RedactLevel = 'safe' | 'keys' | 'full'\n\n/**\n * Custom rule: return a string to log instead of `value`, or `undefined` for the built-in policy.\n * `path` names the field, e.g. `where.key`, `details.value`, `details.keys.2`, `details.issues.0`.\n * Sensitive columns never reach it.\n */\nexport type RedactFn = (path: string, value: unknown) => string | undefined\n\nexport interface RedactionOptions {\n  /** Default `'keys'` in development, `'safe'` in production. */\n  level?: RedactLevel\n  redact?: RedactFn\n  /** Ids / keys of `sensitive: true` columns: never logged at any level. */\n  sensitiveColumns?: () => Iterable<string>\n  /** The `rowKey` path is, is inside or contains a sensitive column: keys hashed at every level. */\n  rowKeySensitive?: () => boolean\n}\n\n/**\n * Which detail fields of a diagnostic carry user data, declared on its `defineDiagnostic` entry.\n * Undeclared fields are logged as-is, so they must hold only DataKable-safe data (paths, ids,\n * indices, counts). Text builders receive the redacted values: treat these fields as opaque and\n * only interpolate them.\n *\n * - `rowKey` / `rowKeys`: a row key / an array of them (hashed under `'safe'`).\n * - `value` / `values`: a cell value / an array of them (type summary unless `'full'`). The column\n *   is `details.column` when it is a string, else the `where` column id.\n * - `schemaIssues`: one Standard Schema issue or an array of them (`scrubSchemaIssue`).\n * - `error`: a thrown value, e.g. a fetcher error (`scrubError`).\n */\nexport type RedactField = 'rowKey' | 'rowKeys' | 'value' | 'values' | 'schemaIssues' | 'error'\n\n/** A resolved policy, built once per emit. */\nexport interface Redactor {\n  level: RedactLevel\n  custom: RedactFn | undefined\n  sensitive: ReadonlySet<string>\n  rowKeySensitive: boolean\n  /** Called when the custom rule throws; the value is logged as `[redacted]`. */\n  onError?: (error: unknown) => void\n}\n\nexport const SENSITIVE = '[sensitive]'\nexport const REDACTED = '[redacted]'\n\nconst LEVELS: readonly string[] = ['safe', 'keys', 'full']\nconst EMPTY: ReadonlySet<string> = new Set()\n\nexport function resolveRedaction(\n  option: RedactLevel | RedactionOptions | undefined,\n  dev: boolean,\n): Redactor {\n  const o: RedactionOptions = typeof option === 'string' ? { level: option } : (option ?? {})\n  const level = o.level ?? (dev ? 'keys' : 'safe')\n  const cols = o.sensitiveColumns?.()\n  return {\n    // An unknown level gets the strictest policy; validating the option is optionValidator's job.\n    level: LEVELS.includes(level) ? level : 'safe',\n    custom: o.redact,\n    sensitive: cols ? new Set(cols) : EMPTY,\n    rowKeySensitive: o.rowKeySensitive?.() ?? false,\n  }\n}\n\n/** Short 32-bit FNV-1a hash of `String(key)` (UTF-16 code units), as `h:xxxxxxxx`. */\nexport function hashRowKey(key: unknown): string {\n  const s = String(key)\n  let h = 0x811c9dc5\n  for (let i = 0; i < s.length; i++) {\n    h ^= s.charCodeAt(i)\n    h = Math.imul(h, 0x01000193)\n  }\n  return `h:${(h >>> 0).toString(16).padStart(8, '0')}`\n}\n\n/** The value's type, never its contents: `string(12)`, `number`, `array(3)`, `date`, … */\nexport function describeValue(v: unknown): string {\n  if (v === null) return 'null'\n  if (typeof v === 'string') return `string(${v.length})`\n  if (typeof v === 'number') return Number.isNaN(v) ? 'number(NaN)' : 'number'\n  if (Array.isArray(v)) return `array(${v.length})`\n  if (v instanceof Date) return 'date'\n  return typeof v\n}\n\nfunction custom(r: Redactor, path: string, value: unknown): string | undefined {\n  if (!r.custom) return undefined\n  try {\n    return r.custom(path, value)\n  } catch (e) {\n    r.onError?.(e)\n    return REDACTED\n  }\n}\n\nfunction redactKey(r: Redactor, path: string, key: unknown): unknown {\n  // A sensitive rowKey column wins over the custom rule and the level.\n  if (r.rowKeySensitive) return hashRowKey(key)\n  const c = custom(r, path, key)\n  if (c !== undefined) return c\n  return r.level === 'safe' ? hashRowKey(key) : key\n}\n\nfunction redactValue(r: Redactor, path: string, value: unknown, column?: string): unknown {\n  if (column !== undefined && underSensitive(r, column)) return SENSITIVE\n  const c = custom(r, path, value)\n  if (c !== undefined) return c\n  return r.level === 'full' ? value : describeValue(value)\n}\n\ntype IssuePath = ReadonlyArray<PropertyKey | { key: PropertyKey }>\n\n/** Joins a Standard Schema issue path: `['user', 0, { key: 'email' }]` → `user.0.email`. */\nfunction issuePath(path: IssuePath | undefined): string {\n  if (!path) return ''\n  return path.map((s) => String(typeof s === 'object' && s !== null ? s.key : s)).join('.')\n}\n\n/** `a` and `b` are the same path or one is inside the other (`contact` ↔ `contact.email`). */\nexport const pathsOverlap = (a: string, b: string): boolean =>\n  a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`)\n\n/** `path` is, is inside or contains a sensitive column (#45). */\nfunction underSensitive(r: Redactor, path: string): boolean {\n  for (const col of r.sensitive) if (pathsOverlap(path, col)) return true\n  return false\n}\n\n/**\n * A schema issue as `{ path, message }`. Validators embed received values in their messages, so\n * under `'safe'` / `'keys'` the message is DataKable's own text. So it is at every level when the\n * table has a sensitive column: any message (a root-level refinement, another field's) may embed\n * its value (#46).\n */\nexport function scrubSchemaIssue(\n  issue: unknown,\n  r: Redactor,\n  fieldPath = 'issue',\n): { path: string; message: string } {\n  const i = (typeof issue === 'object' && issue !== null ? issue : {}) as {\n    message?: unknown\n    path?: IssuePath\n  }\n  let path: string\n  try {\n    path = issuePath(i.path)\n  } catch {\n    path = ''\n  }\n  const own = `invalid value at ${path || '(root)'}`\n  if (r.sensitive.size > 0) return { path, message: own }\n  const c = custom(r, fieldPath, i.message)\n  if (c !== undefined) return { path, message: c }\n  return { path, message: r.level === 'full' && typeof i.message === 'string' ? i.message : own }\n}\n\n/**\n * A thrown value as `error.name` + `code` only (fetcher errors embed URLs, tokens, payloads). The\n * full error belongs in `context.cause`, which reaches `onDiagnostic` only.\n */\nexport function scrubError(e: unknown): string {\n  if (typeof e !== 'object' || e === null) return typeof e\n  try {\n    const { name, code } = e as { name?: unknown; code?: unknown }\n    const n = typeof name === 'string' && name ? name : 'object'\n    return typeof code === 'string' || typeof code === 'number' ? `${n} (${code})` : n\n  } catch {\n    return 'object'\n  }\n}\n\n/** Hashes / passes through `where.key` per the policy; other locations hold no user data. */\nexport function redactLocation(where: Location, r: Redactor): Location {\n  if (where.kind !== 'row' || where.key === undefined) return where\n  const key = redactKey(r, 'where.key', where.key)\n  return { kind: 'row', index: where.index, key: typeof key === 'string' ? key : String(key) }\n}\n\n/** A shallow copy of `details` with the declared fields redacted; the input is never mutated. */\nexport function redactDetails(\n  details: Record<string, unknown>,\n  fields: Readonly<Record<string, RedactField | undefined>> | undefined,\n  where: Location,\n  r: Redactor,\n): Record<string, unknown> {\n  if (!fields) return details\n  const out: Record<string, unknown> = { ...details }\n  const column =\n    typeof details.column === 'string'\n      ? details.column\n      : where.kind === 'column'\n        ? where.id\n        : undefined\n  for (const name of Object.keys(fields)) {\n    const kind = fields[name]\n    if (kind === undefined || !(name in details)) continue\n    const v = details[name]\n    const p = `details.${name}`\n    const each = (f: (x: unknown, path: string) => unknown) =>\n      Array.isArray(v) ? v.map((x, i) => f(x, `${p}.${i}`)) : f(v, p)\n    switch (kind) {\n      case 'rowKey':\n        out[name] = redactKey(r, p, v)\n        break\n      case 'rowKeys':\n        out[name] = each((x, path) => redactKey(r, path, x))\n        break\n      case 'value':\n        out[name] = redactValue(r, p, v, column)\n        break\n      case 'values':\n        out[name] = each((x, path) => redactValue(r, path, x, column))\n        break\n      case 'schemaIssues':\n        out[name] = each((x, path) => scrubSchemaIssue(x, r, path))\n        break\n      case 'error':\n        out[name] = custom(r, p, v) ?? scrubError(v)\n        break\n    }\n  }\n  return out\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const redactionMessages: DiagnosticMessages<'DK_UNSAFE_REDACTION'> = {\n  DK_UNSAFE_REDACTION: {\n    problem: (d) => `diagnostics.redact is '${d.level}' in a production build`,\n    impact: () =>\n      'raw row keys and cell values (except sensitive columns) reach onDiagnostic, ' +\n      'getDiagnostics() and the console',\n    fix: () => [\n      \"remove diagnostics.redact in production (the default is 'safe')\",\n      \"or use 'keys' to log raw row keys without cell values\",\n      'mark personal-data columns with sensitive: true so they are never logged',\n    ],\n  },\n}\n\n/** `'full'` in a production build (§8.2: \"warns if enabled in production\"). Emitted by the hub. */\nexport const DK_UNSAFE_REDACTION = defineDiagnostic(\n  {\n    code: 'DK_UNSAFE_REDACTION',\n    level: 'warn',\n    where: () => ({ kind: 'option', path: 'diagnostics.redact' }),\n  },\n  (process.env.NODE_ENV !== \"production\") && redactionMessages.DK_UNSAFE_REDACTION,\n)\n"],"mappings":"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","names":[]}

package/dist/diagnostics/redact.js

@@ -1,5 +1,6 @@
 // src/diagnostics/redact.ts
 import { defineDiagnostic } from "./catalog.js";
+import "./process-guard.js";
 var SENSITIVE = "[sensitive]";
 var REDACTED = "[redacted]";
 var LEVELS = ["safe", "keys", "full"];
@@ -49,7 +50,7 @@ function redactKey(r, path, key) {
   return r.level === "safe" ? hashRowKey(key) : key;
 }
 function redactValue(r, path, value, column) {
-  if (column !== void 0 && r.sensitive.has(column)) return SENSITIVE;
+  if (column !== void 0 && underSensitive(r, column)) return SENSITIVE;
   const c = custom(r, path, value);
   if (c !== void 0) return c;
   return r.level === "full" ? value : describeValue(value);
@@ -58,9 +59,9 @@ function issuePath(path) {
   if (!path) return "";
   return path.map((s) => String(typeof s === "object" && s !== null ? s.key : s)).join(".");
 }
+var pathsOverlap = (a, b) => a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`);
 function underSensitive(r, path) {
-  if (r.sensitive.size === 0) return false;
-  for (const col of r.sensitive) if (path === col || path.startsWith(`${col}.`)) return true;
+  for (const col of r.sensitive) if (pathsOverlap(path, col)) return true;
   return false;
 }
 function scrubSchemaIssue(issue, r, fieldPath = "issue") {
@@ -72,7 +73,7 @@ function scrubSchemaIssue(issue, r, fieldPath = "issue") {
     path = "";
   }
   const own = `invalid value at ${path || "(root)"}`;
-  if (underSensitive(r, path)) return { path, message: own };
+  if (r.sensitive.size > 0) return { path, message: own };
   const c = custom(r, fieldPath, i.message);
   if (c !== void 0) return { path, message: c };
   return { path, message: r.level === "full" && typeof i.message === "string" ? i.message : own };
@@ -150,6 +151,7 @@ export {
   SENSITIVE,
   describeValue,
   hashRowKey,
+  pathsOverlap,
   redactDetails,
   redactLocation,
   redactionMessages,

package/dist/diagnostics/redact.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/redact.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from './catalog'\nimport type { Location } from './types'\n\ndeclare module './catalog' {\n  interface DiagnosticCatalog {\n    DK_UNSAFE_REDACTION: { level: 'full' }\n  }\n}\n\n/**\n * Redaction levels (§8.2). `'safe'`: paths, indices, counts, value types, hashed row keys\n * (production default). `'keys'`: + raw row keys (development default). `'full'`: + row values.\n */\nexport type RedactLevel = 'safe' | 'keys' | 'full'\n\n/**\n * Custom rule: return a string to log instead of `value`, or `undefined` for the built-in policy.\n * `path` names the field, e.g. `where.key`, `details.value`, `details.keys.2`, `details.issues.0`.\n * Sensitive columns never reach it.\n */\nexport type RedactFn = (path: string, value: unknown) => string | undefined\n\nexport interface RedactionOptions {\n  /** Default `'keys'` in development, `'safe'` in production. */\n  level?: RedactLevel\n  redact?: RedactFn\n  /** Ids / keys of `sensitive: true` columns: never logged at any level. */\n  sensitiveColumns?: () => Iterable<string>\n  /** The `rowKey` column is sensitive: row keys are hashed at every level. */\n  rowKeySensitive?: () => boolean\n}\n\n/**\n * Which detail fields of a diagnostic carry user data, declared on its `defineDiagnostic` entry.\n * Undeclared fields are logged as-is, so they must hold only DataKable-safe data (paths, ids,\n * indices, counts). Text builders receive the redacted values: treat these fields as opaque and\n * only interpolate them.\n *\n * - `rowKey` / `rowKeys`: a row key / an array of them (hashed under `'safe'`).\n * - `value` / `values`: a cell value / an array of them (type summary unless `'full'`). The column\n *   is `details.column` when it is a string, else the `where` column id.\n * - `schemaIssues`: one Standard Schema issue or an array of them (`scrubSchemaIssue`).\n * - `error`: a thrown value, e.g. a fetcher error (`scrubError`).\n */\nexport type RedactField = 'rowKey' | 'rowKeys' | 'value' | 'values' | 'schemaIssues' | 'error'\n\n/** A resolved policy, built once per emit. */\nexport interface Redactor {\n  level: RedactLevel\n  custom: RedactFn | undefined\n  sensitive: ReadonlySet<string>\n  rowKeySensitive: boolean\n  /** Called when the custom rule throws; the value is logged as `[redacted]`. */\n  onError?: (error: unknown) => void\n}\n\nexport const SENSITIVE = '[sensitive]'\nexport const REDACTED = '[redacted]'\n\nconst LEVELS: readonly string[] = ['safe', 'keys', 'full']\nconst EMPTY: ReadonlySet<string> = new Set()\n\nexport function resolveRedaction(\n  option: RedactLevel | RedactionOptions | undefined,\n  dev: boolean,\n): Redactor {\n  const o: RedactionOptions = typeof option === 'string' ? { level: option } : (option ?? {})\n  const level = o.level ?? (dev ? 'keys' : 'safe')\n  const cols = o.sensitiveColumns?.()\n  return {\n    // An unknown level gets the strictest policy; validating the option is optionValidator's job.\n    level: LEVELS.includes(level) ? level : 'safe',\n    custom: o.redact,\n    sensitive: cols ? new Set(cols) : EMPTY,\n    rowKeySensitive: o.rowKeySensitive?.() ?? false,\n  }\n}\n\n/** Short 32-bit FNV-1a hash of `String(key)` (UTF-16 code units), as `h:xxxxxxxx`. */\nexport function hashRowKey(key: unknown): string {\n  const s = String(key)\n  let h = 0x811c9dc5\n  for (let i = 0; i < s.length; i++) {\n    h ^= s.charCodeAt(i)\n    h = Math.imul(h, 0x01000193)\n  }\n  return `h:${(h >>> 0).toString(16).padStart(8, '0')}`\n}\n\n/** The value's type, never its contents: `string(12)`, `number`, `array(3)`, `date`, … */\nexport function describeValue(v: unknown): string {\n  if (v === null) return 'null'\n  if (typeof v === 'string') return `string(${v.length})`\n  if (typeof v === 'number') return Number.isNaN(v) ? 'number(NaN)' : 'number'\n  if (Array.isArray(v)) return `array(${v.length})`\n  if (v instanceof Date) return 'date'\n  return typeof v\n}\n\nfunction custom(r: Redactor, path: string, value: unknown): string | undefined {\n  if (!r.custom) return undefined\n  try {\n    return r.custom(path, value)\n  } catch (e) {\n    r.onError?.(e)\n    return REDACTED\n  }\n}\n\nfunction redactKey(r: Redactor, path: string, key: unknown): unknown {\n  // A sensitive rowKey column wins over the custom rule and the level.\n  if (r.rowKeySensitive) return hashRowKey(key)\n  const c = custom(r, path, key)\n  if (c !== undefined) return c\n  return r.level === 'safe' ? hashRowKey(key) : key\n}\n\nfunction redactValue(r: Redactor, path: string, value: unknown, column?: string): unknown {\n  if (column !== undefined && r.sensitive.has(column)) return SENSITIVE\n  const c = custom(r, path, value)\n  if (c !== undefined) return c\n  return r.level === 'full' ? value : describeValue(value)\n}\n\ntype IssuePath = ReadonlyArray<PropertyKey | { key: PropertyKey }>\n\n/** Joins a Standard Schema issue path: `['user', 0, { key: 'email' }]` → `user.0.email`. */\nfunction issuePath(path: IssuePath | undefined): string {\n  if (!path) return ''\n  return path.map((s) => String(typeof s === 'object' && s !== null ? s.key : s)).join('.')\n}\n\nfunction underSensitive(r: Redactor, path: string): boolean {\n  if (r.sensitive.size === 0) return false\n  for (const col of r.sensitive) if (path === col || path.startsWith(`${col}.`)) return true\n  return false\n}\n\n/**\n * A schema issue as `{ path, message }`. Validators embed received values in their messages, so\n * under `'safe'` / `'keys'` (and for sensitive columns) the message is DataKable's own text.\n */\nexport function scrubSchemaIssue(\n  issue: unknown,\n  r: Redactor,\n  fieldPath = 'issue',\n): { path: string; message: string } {\n  const i = (typeof issue === 'object' && issue !== null ? issue : {}) as {\n    message?: unknown\n    path?: IssuePath\n  }\n  let path: string\n  try {\n    path = issuePath(i.path)\n  } catch {\n    path = ''\n  }\n  const own = `invalid value at ${path || '(root)'}`\n  if (underSensitive(r, path)) return { path, message: own }\n  const c = custom(r, fieldPath, i.message)\n  if (c !== undefined) return { path, message: c }\n  return { path, message: r.level === 'full' && typeof i.message === 'string' ? i.message : own }\n}\n\n/**\n * A thrown value as `error.name` + `code` only (fetcher errors embed URLs, tokens, payloads). The\n * full error belongs in `context.cause`, which reaches `onDiagnostic` only.\n */\nexport function scrubError(e: unknown): string {\n  if (typeof e !== 'object' || e === null) return typeof e\n  try {\n    const { name, code } = e as { name?: unknown; code?: unknown }\n    const n = typeof name === 'string' && name ? name : 'object'\n    return typeof code === 'string' || typeof code === 'number' ? `${n} (${code})` : n\n  } catch {\n    return 'object'\n  }\n}\n\n/** Hashes / passes through `where.key` per the policy; other locations hold no user data. */\nexport function redactLocation(where: Location, r: Redactor): Location {\n  if (where.kind !== 'row' || where.key === undefined) return where\n  const key = redactKey(r, 'where.key', where.key)\n  return { kind: 'row', index: where.index, key: typeof key === 'string' ? key : String(key) }\n}\n\n/** A shallow copy of `details` with the declared fields redacted; the input is never mutated. */\nexport function redactDetails(\n  details: Record<string, unknown>,\n  fields: Readonly<Record<string, RedactField | undefined>> | undefined,\n  where: Location,\n  r: Redactor,\n): Record<string, unknown> {\n  if (!fields) return details\n  const out: Record<string, unknown> = { ...details }\n  const column =\n    typeof details.column === 'string'\n      ? details.column\n      : where.kind === 'column'\n        ? where.id\n        : undefined\n  for (const name of Object.keys(fields)) {\n    const kind = fields[name]\n    if (kind === undefined || !(name in details)) continue\n    const v = details[name]\n    const p = `details.${name}`\n    const each = (f: (x: unknown, path: string) => unknown) =>\n      Array.isArray(v) ? v.map((x, i) => f(x, `${p}.${i}`)) : f(v, p)\n    switch (kind) {\n      case 'rowKey':\n        out[name] = redactKey(r, p, v)\n        break\n      case 'rowKeys':\n        out[name] = each((x, path) => redactKey(r, path, x))\n        break\n      case 'value':\n        out[name] = redactValue(r, p, v, column)\n        break\n      case 'values':\n        out[name] = each((x, path) => redactValue(r, path, x, column))\n        break\n      case 'schemaIssues':\n        out[name] = each((x, path) => scrubSchemaIssue(x, r, path))\n        break\n      case 'error':\n        out[name] = custom(r, p, v) ?? scrubError(v)\n        break\n    }\n  }\n  return out\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const redactionMessages: DiagnosticMessages<'DK_UNSAFE_REDACTION'> = {\n  DK_UNSAFE_REDACTION: {\n    problem: (d) => `diagnostics.redact is '${d.level}' in a production build`,\n    impact: () =>\n      'raw row keys and cell values (except sensitive columns) reach onDiagnostic, ' +\n      'getDiagnostics() and the console',\n    fix: () => [\n      \"remove diagnostics.redact in production (the default is 'safe')\",\n      \"or use 'keys' to log raw row keys without cell values\",\n      'mark personal-data columns with sensitive: true so they are never logged',\n    ],\n  },\n}\n\n/** `'full'` in a production build (§8.2: \"warns if enabled in production\"). Emitted by the hub. */\nexport const DK_UNSAFE_REDACTION = defineDiagnostic(\n  {\n    code: 'DK_UNSAFE_REDACTION',\n    level: 'warn',\n    where: () => ({ kind: 'option', path: 'diagnostics.redact' }),\n  },\n  (process.env.NODE_ENV !== \"production\") && redactionMessages.DK_UNSAFE_REDACTION,\n)\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/diagnostics/redact.ts"],"sourcesContent":["import { type DiagnosticMessages, defineDiagnostic } from './catalog'\nimport './process-guard'\nimport type { Location } from './types'\n\ndeclare module './catalog' {\n  interface DiagnosticCatalog {\n    DK_UNSAFE_REDACTION: { level: 'full' }\n  }\n}\n\n/**\n * Redaction levels (§8.2). `'safe'`: paths, indices, counts, value types, hashed row keys\n * (production default). `'keys'`: + raw row keys (development default). `'full'`: + row values.\n */\nexport type RedactLevel = 'safe' | 'keys' | 'full'\n\n/**\n * Custom rule: return a string to log instead of `value`, or `undefined` for the built-in policy.\n * `path` names the field, e.g. `where.key`, `details.value`, `details.keys.2`, `details.issues.0`.\n * Sensitive columns never reach it.\n */\nexport type RedactFn = (path: string, value: unknown) => string | undefined\n\nexport interface RedactionOptions {\n  /** Default `'keys'` in development, `'safe'` in production. */\n  level?: RedactLevel\n  redact?: RedactFn\n  /** Ids / keys of `sensitive: true` columns: never logged at any level. */\n  sensitiveColumns?: () => Iterable<string>\n  /** The `rowKey` path is, is inside or contains a sensitive column: keys hashed at every level. */\n  rowKeySensitive?: () => boolean\n}\n\n/**\n * Which detail fields of a diagnostic carry user data, declared on its `defineDiagnostic` entry.\n * Undeclared fields are logged as-is, so they must hold only DataKable-safe data (paths, ids,\n * indices, counts). Text builders receive the redacted values: treat these fields as opaque and\n * only interpolate them.\n *\n * - `rowKey` / `rowKeys`: a row key / an array of them (hashed under `'safe'`).\n * - `value` / `values`: a cell value / an array of them (type summary unless `'full'`). The column\n *   is `details.column` when it is a string, else the `where` column id.\n * - `schemaIssues`: one Standard Schema issue or an array of them (`scrubSchemaIssue`).\n * - `error`: a thrown value, e.g. a fetcher error (`scrubError`).\n */\nexport type RedactField = 'rowKey' | 'rowKeys' | 'value' | 'values' | 'schemaIssues' | 'error'\n\n/** A resolved policy, built once per emit. */\nexport interface Redactor {\n  level: RedactLevel\n  custom: RedactFn | undefined\n  sensitive: ReadonlySet<string>\n  rowKeySensitive: boolean\n  /** Called when the custom rule throws; the value is logged as `[redacted]`. */\n  onError?: (error: unknown) => void\n}\n\nexport const SENSITIVE = '[sensitive]'\nexport const REDACTED = '[redacted]'\n\nconst LEVELS: readonly string[] = ['safe', 'keys', 'full']\nconst EMPTY: ReadonlySet<string> = new Set()\n\nexport function resolveRedaction(\n  option: RedactLevel | RedactionOptions | undefined,\n  dev: boolean,\n): Redactor {\n  const o: RedactionOptions = typeof option === 'string' ? { level: option } : (option ?? {})\n  const level = o.level ?? (dev ? 'keys' : 'safe')\n  const cols = o.sensitiveColumns?.()\n  return {\n    // An unknown level gets the strictest policy; validating the option is optionValidator's job.\n    level: LEVELS.includes(level) ? level : 'safe',\n    custom: o.redact,\n    sensitive: cols ? new Set(cols) : EMPTY,\n    rowKeySensitive: o.rowKeySensitive?.() ?? false,\n  }\n}\n\n/** Short 32-bit FNV-1a hash of `String(key)` (UTF-16 code units), as `h:xxxxxxxx`. */\nexport function hashRowKey(key: unknown): string {\n  const s = String(key)\n  let h = 0x811c9dc5\n  for (let i = 0; i < s.length; i++) {\n    h ^= s.charCodeAt(i)\n    h = Math.imul(h, 0x01000193)\n  }\n  return `h:${(h >>> 0).toString(16).padStart(8, '0')}`\n}\n\n/** The value's type, never its contents: `string(12)`, `number`, `array(3)`, `date`, … */\nexport function describeValue(v: unknown): string {\n  if (v === null) return 'null'\n  if (typeof v === 'string') return `string(${v.length})`\n  if (typeof v === 'number') return Number.isNaN(v) ? 'number(NaN)' : 'number'\n  if (Array.isArray(v)) return `array(${v.length})`\n  if (v instanceof Date) return 'date'\n  return typeof v\n}\n\nfunction custom(r: Redactor, path: string, value: unknown): string | undefined {\n  if (!r.custom) return undefined\n  try {\n    return r.custom(path, value)\n  } catch (e) {\n    r.onError?.(e)\n    return REDACTED\n  }\n}\n\nfunction redactKey(r: Redactor, path: string, key: unknown): unknown {\n  // A sensitive rowKey column wins over the custom rule and the level.\n  if (r.rowKeySensitive) return hashRowKey(key)\n  const c = custom(r, path, key)\n  if (c !== undefined) return c\n  return r.level === 'safe' ? hashRowKey(key) : key\n}\n\nfunction redactValue(r: Redactor, path: string, value: unknown, column?: string): unknown {\n  if (column !== undefined && underSensitive(r, column)) return SENSITIVE\n  const c = custom(r, path, value)\n  if (c !== undefined) return c\n  return r.level === 'full' ? value : describeValue(value)\n}\n\ntype IssuePath = ReadonlyArray<PropertyKey | { key: PropertyKey }>\n\n/** Joins a Standard Schema issue path: `['user', 0, { key: 'email' }]` → `user.0.email`. */\nfunction issuePath(path: IssuePath | undefined): string {\n  if (!path) return ''\n  return path.map((s) => String(typeof s === 'object' && s !== null ? s.key : s)).join('.')\n}\n\n/** `a` and `b` are the same path or one is inside the other (`contact` ↔ `contact.email`). */\nexport const pathsOverlap = (a: string, b: string): boolean =>\n  a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`)\n\n/** `path` is, is inside or contains a sensitive column (#45). */\nfunction underSensitive(r: Redactor, path: string): boolean {\n  for (const col of r.sensitive) if (pathsOverlap(path, col)) return true\n  return false\n}\n\n/**\n * A schema issue as `{ path, message }`. Validators embed received values in their messages, so\n * under `'safe'` / `'keys'` the message is DataKable's own text. So it is at every level when the\n * table has a sensitive column: any message (a root-level refinement, another field's) may embed\n * its value (#46).\n */\nexport function scrubSchemaIssue(\n  issue: unknown,\n  r: Redactor,\n  fieldPath = 'issue',\n): { path: string; message: string } {\n  const i = (typeof issue === 'object' && issue !== null ? issue : {}) as {\n    message?: unknown\n    path?: IssuePath\n  }\n  let path: string\n  try {\n    path = issuePath(i.path)\n  } catch {\n    path = ''\n  }\n  const own = `invalid value at ${path || '(root)'}`\n  if (r.sensitive.size > 0) return { path, message: own }\n  const c = custom(r, fieldPath, i.message)\n  if (c !== undefined) return { path, message: c }\n  return { path, message: r.level === 'full' && typeof i.message === 'string' ? i.message : own }\n}\n\n/**\n * A thrown value as `error.name` + `code` only (fetcher errors embed URLs, tokens, payloads). The\n * full error belongs in `context.cause`, which reaches `onDiagnostic` only.\n */\nexport function scrubError(e: unknown): string {\n  if (typeof e !== 'object' || e === null) return typeof e\n  try {\n    const { name, code } = e as { name?: unknown; code?: unknown }\n    const n = typeof name === 'string' && name ? name : 'object'\n    return typeof code === 'string' || typeof code === 'number' ? `${n} (${code})` : n\n  } catch {\n    return 'object'\n  }\n}\n\n/** Hashes / passes through `where.key` per the policy; other locations hold no user data. */\nexport function redactLocation(where: Location, r: Redactor): Location {\n  if (where.kind !== 'row' || where.key === undefined) return where\n  const key = redactKey(r, 'where.key', where.key)\n  return { kind: 'row', index: where.index, key: typeof key === 'string' ? key : String(key) }\n}\n\n/** A shallow copy of `details` with the declared fields redacted; the input is never mutated. */\nexport function redactDetails(\n  details: Record<string, unknown>,\n  fields: Readonly<Record<string, RedactField | undefined>> | undefined,\n  where: Location,\n  r: Redactor,\n): Record<string, unknown> {\n  if (!fields) return details\n  const out: Record<string, unknown> = { ...details }\n  const column =\n    typeof details.column === 'string'\n      ? details.column\n      : where.kind === 'column'\n        ? where.id\n        : undefined\n  for (const name of Object.keys(fields)) {\n    const kind = fields[name]\n    if (kind === undefined || !(name in details)) continue\n    const v = details[name]\n    const p = `details.${name}`\n    const each = (f: (x: unknown, path: string) => unknown) =>\n      Array.isArray(v) ? v.map((x, i) => f(x, `${p}.${i}`)) : f(v, p)\n    switch (kind) {\n      case 'rowKey':\n        out[name] = redactKey(r, p, v)\n        break\n      case 'rowKeys':\n        out[name] = each((x, path) => redactKey(r, path, x))\n        break\n      case 'value':\n        out[name] = redactValue(r, p, v, column)\n        break\n      case 'values':\n        out[name] = each((x, path) => redactValue(r, path, x, column))\n        break\n      case 'schemaIssues':\n        out[name] = each((x, path) => scrubSchemaIssue(x, r, path))\n        break\n      case 'error':\n        out[name] = custom(r, p, v) ?? scrubError(v)\n        break\n    }\n  }\n  return out\n}\n\n/** Message text (§8.2): development builds, or production via `@datakable/core/messages`. */\nexport const redactionMessages: DiagnosticMessages<'DK_UNSAFE_REDACTION'> = {\n  DK_UNSAFE_REDACTION: {\n    problem: (d) => `diagnostics.redact is '${d.level}' in a production build`,\n    impact: () =>\n      'raw row keys and cell values (except sensitive columns) reach onDiagnostic, ' +\n      'getDiagnostics() and the console',\n    fix: () => [\n      \"remove diagnostics.redact in production (the default is 'safe')\",\n      \"or use 'keys' to log raw row keys without cell values\",\n      'mark personal-data columns with sensitive: true so they are never logged',\n    ],\n  },\n}\n\n/** `'full'` in a production build (§8.2: \"warns if enabled in production\"). Emitted by the hub. */\nexport const DK_UNSAFE_REDACTION = defineDiagnostic(\n  {\n    code: 'DK_UNSAFE_REDACTION',\n    level: 'warn',\n    where: () => ({ kind: 'option', path: 'diagnostics.redact' }),\n  },\n  (process.env.NODE_ENV !== \"production\") && redactionMessages.DK_UNSAFE_REDACTION,\n)\n"],"mappings":"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","names":[]}

package/dist/diagnostics/trace-store.cjs

@@ -20,10 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/diagnostics/trace-store.ts
 var trace_store_exports = {};
 __export(trace_store_exports, {
+  SLICED: () => SLICED,
   readTrace: () => readTrace,
+  sliceTimer: () => sliceTimer,
   writeTrace: () => writeTrace
 });
 module.exports = __toCommonJS(trace_store_exports);
+var SLICED = "sliced";
+var sliceTimer = {};
 var traces = /* @__PURE__ */ new WeakMap();
 var readTrace = (table) => traces.get(table);
 var writeTrace = (table, trace) => {
@@ -31,7 +35,9 @@ var writeTrace = (table, trace) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SLICED,
   readTrace,
+  sliceTimer,
   writeTrace
 });
 //# sourceMappingURL=trace-store.cjs.map

package/dist/diagnostics/trace-store.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/trace-store.ts"],"sourcesContent":["import type { Trigger } from './types'\n\n/** One step of the traced run: counts (never rows) and its duration (§9.1: bounded). */\nexport interface TraceStep {\n  readonly input: number\n  readonly output: number\n  readonly ms: number\n}\n\n/** What the tracer kept of the last `pipeline:run` of a table (the last run only). */\nexport interface Trace {\n  readonly run: number\n  readonly trigger: Trigger\n  /** Duration of the whole run; `undefined` while it is in progress. */\n  ms: number | undefined\n  /** Steps that ran (a step served from its memo is absent), by feature name. */\n  readonly steps: Map<string, TraceStep>\n  /** The last `state:dispatch` (its `where`: a method / feature name) and its duration. */\n  dispatch: { where: string; ms: number } | undefined\n}\n\n/** Kept apart from the tracer so `explain()` reads traces without bundling the tracer itself. */\nconst traces = new WeakMap<object, Trace>()\n\n/** The last traced run of `table`, if a tracer is installed. */\nexport const readTrace = (table: object): Trace | undefined => traces.get(table)\n\nexport const writeTrace = (table: object, trace: Trace): void => {\n  traces.set(table, trace)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBA,IAAM,SAAS,oBAAI,QAAuB;AAGnC,IAAM,YAAY,CAAC,UAAqC,OAAO,IAAI,KAAK;AAExE,IAAM,aAAa,CAAC,OAAe,UAAuB;AAC/D,SAAO,IAAI,OAAO,KAAK;AACzB;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/trace-store.ts"],"sourcesContent":["import type { ContextBase } from '../intercept/context'\nimport type { Trigger } from './types'\n\n/** One step of the traced run: counts (never rows) and its duration (§9.1: bounded). */\nexport interface TraceStep {\n  readonly input: number\n  readonly output: number\n  /** With time-sliced work (#61): the runs that waited on it, this one, and the slices between. */\n  readonly ms: number\n  /** Time-sliced work (#61): the runs {@link ms} spans (absent when the step ran in one). */\n  readonly runs?: number\n}\n\n/** What the tracer kept of the last `pipeline:run` of a table (the last run only). */\nexport interface Trace {\n  readonly run: number\n  readonly trigger: Trigger\n  /** Duration of the whole run; `undefined` while it is in progress. */\n  ms: number | undefined\n  /** Steps that ran (a step served from its memo is absent), by feature name. */\n  readonly steps: Map<string, TraceStep>\n  /** The last `state:dispatch` (its `where`: a method / feature name) and its duration. */\n  dispatch: { where: string; ms: number } | undefined\n}\n\n/**\n * Set on the `pipeline:step` ctx's `meta` by the runner when the step waits on time-sliced work\n * (its result comes in a later run).\n */\nexport const SLICED = 'sliced'\n\n/**\n * The tracer's (#61): the runner reports each slice of time-sliced work run between pipeline runs\n * (no step is timing it). Unset until a tracer is created.\n */\nexport const sliceTimer: {\n  current?: ((base: ContextBase, feature: string, ms: number) => void) | undefined\n} = {}\n\n/** Kept apart from the tracer so `explain()` reads traces without bundling the tracer itself. */\nconst traces = new WeakMap<object, Trace>()\n\n/** The last traced run of `table`, if a tracer is installed. */\nexport const readTrace = (table: object): Trace | undefined => traces.get(table)\n\nexport const writeTrace = (table: object, trace: Trace): void => {\n  traces.set(table, trace)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA6BO,IAAM,SAAS;AAMf,IAAM,aAET,CAAC;AAGL,IAAM,SAAS,oBAAI,QAAuB;AAGnC,IAAM,YAAY,CAAC,UAAqC,OAAO,IAAI,KAAK;AAExE,IAAM,aAAa,CAAC,OAAe,UAAuB;AAC/D,SAAO,IAAI,OAAO,KAAK;AACzB;","names":[]}

package/dist/diagnostics/trace-store.js

@@ -1,11 +1,15 @@
 // src/diagnostics/trace-store.ts
+var SLICED = "sliced";
+var sliceTimer = {};
 var traces = /* @__PURE__ */ new WeakMap();
 var readTrace = (table) => traces.get(table);
 var writeTrace = (table, trace) => {
   traces.set(table, trace);
 };
 export {
+  SLICED,
   readTrace,
+  sliceTimer,
   writeTrace
 };
 //# sourceMappingURL=trace-store.js.map

package/dist/diagnostics/trace-store.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/trace-store.ts"],"sourcesContent":["import type { Trigger } from './types'\n\n/** One step of the traced run: counts (never rows) and its duration (§9.1: bounded). */\nexport interface TraceStep {\n  readonly input: number\n  readonly output: number\n  readonly ms: number\n}\n\n/** What the tracer kept of the last `pipeline:run` of a table (the last run only). */\nexport interface Trace {\n  readonly run: number\n  readonly trigger: Trigger\n  /** Duration of the whole run; `undefined` while it is in progress. */\n  ms: number | undefined\n  /** Steps that ran (a step served from its memo is absent), by feature name. */\n  readonly steps: Map<string, TraceStep>\n  /** The last `state:dispatch` (its `where`: a method / feature name) and its duration. */\n  dispatch: { where: string; ms: number } | undefined\n}\n\n/** Kept apart from the tracer so `explain()` reads traces without bundling the tracer itself. */\nconst traces = new WeakMap<object, Trace>()\n\n/** The last traced run of `table`, if a tracer is installed. */\nexport const readTrace = (table: object): Trace | undefined => traces.get(table)\n\nexport const writeTrace = (table: object, trace: Trace): void => {\n  traces.set(table, trace)\n}\n"],"mappings":";AAsBA,IAAM,SAAS,oBAAI,QAAuB;AAGnC,IAAM,YAAY,CAAC,UAAqC,OAAO,IAAI,KAAK;AAExE,IAAM,aAAa,CAAC,OAAe,UAAuB;AAC/D,SAAO,IAAI,OAAO,KAAK;AACzB;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/trace-store.ts"],"sourcesContent":["import type { ContextBase } from '../intercept/context'\nimport type { Trigger } from './types'\n\n/** One step of the traced run: counts (never rows) and its duration (§9.1: bounded). */\nexport interface TraceStep {\n  readonly input: number\n  readonly output: number\n  /** With time-sliced work (#61): the runs that waited on it, this one, and the slices between. */\n  readonly ms: number\n  /** Time-sliced work (#61): the runs {@link ms} spans (absent when the step ran in one). */\n  readonly runs?: number\n}\n\n/** What the tracer kept of the last `pipeline:run` of a table (the last run only). */\nexport interface Trace {\n  readonly run: number\n  readonly trigger: Trigger\n  /** Duration of the whole run; `undefined` while it is in progress. */\n  ms: number | undefined\n  /** Steps that ran (a step served from its memo is absent), by feature name. */\n  readonly steps: Map<string, TraceStep>\n  /** The last `state:dispatch` (its `where`: a method / feature name) and its duration. */\n  dispatch: { where: string; ms: number } | undefined\n}\n\n/**\n * Set on the `pipeline:step` ctx's `meta` by the runner when the step waits on time-sliced work\n * (its result comes in a later run).\n */\nexport const SLICED = 'sliced'\n\n/**\n * The tracer's (#61): the runner reports each slice of time-sliced work run between pipeline runs\n * (no step is timing it). Unset until a tracer is created.\n */\nexport const sliceTimer: {\n  current?: ((base: ContextBase, feature: string, ms: number) => void) | undefined\n} = {}\n\n/** Kept apart from the tracer so `explain()` reads traces without bundling the tracer itself. */\nconst traces = new WeakMap<object, Trace>()\n\n/** The last traced run of `table`, if a tracer is installed. */\nexport const readTrace = (table: object): Trace | undefined => traces.get(table)\n\nexport const writeTrace = (table: object, trace: Trace): void => {\n  traces.set(table, trace)\n}\n"],"mappings":";AA6BO,IAAM,SAAS;AAMf,IAAM,aAET,CAAC;AAGL,IAAM,SAAS,oBAAI,QAAuB;AAGnC,IAAM,YAAY,CAAC,UAAqC,OAAO,IAAI,KAAK;AAExE,IAAM,aAAa,CAAC,OAAe,UAAuB;AAC/D,SAAO,IAAI,OAAO,KAAK;AACzB;","names":[]}

package/dist/diagnostics/tracer.cjs

@@ -30,16 +30,70 @@ var import_trace_store = require("./trace-store.cjs");
 var STEP_BUDGET_MS = 50;
 var now = () => typeof performance === "object" && typeof performance?.now === "function" ? performance.now() : Date.now();
 var SEEN = "tracer";
+var work = /* @__PURE__ */ new WeakMap();
+function workOf(table) {
+  let w = work.get(table);
+  if (!w) {
+    w = { jobs: /* @__PURE__ */ new Map(), slots: /* @__PURE__ */ new Map() };
+    work.set(table, w);
+  }
+  return w;
+}
+function hint(emit, w, feature, stage, ms, rows, sliced) {
+  let slot;
+  let top = ["", 0];
+  for (const [where, t] of w.slots) {
+    if (t[1] > top[1]) {
+      slot = where;
+      top = t;
+    }
+  }
+  w.slots.clear();
+  if (ms <= STEP_BUDGET_MS) return;
+  emit("DK_PERF_HINT", {
+    feature,
+    stage,
+    ms,
+    rows,
+    budget: STEP_BUDGET_MS,
+    ...sliced ? { sliced } : {},
+    // Named when it took at least half of the time.
+    ...slot && top[1] * 2 >= ms ? { slot, column: top[0], share: Math.min(1, top[1] / ms) } : {}
+  });
+}
+function onSlice(base, feature, ms) {
+  const table = base.table;
+  const trace = (0, import_trace_store.readTrace)(table);
+  if (!trace) return;
+  const w = workOf(table);
+  const job = w.jobs.get(feature);
+  if (job) job.ms += ms;
+  hint(base.emit, w, feature, job?.stage ?? "", ms, trace.steps.get(feature)?.input ?? 0, true);
+}
 function tracer() {
   (0, import_catalog.keepDiagnostics)(import_perf_codes.perfDiagnostics);
+  import_trace_store.sliceTimer.current = onSlice;
   return {
     name: "tracer",
-    on: ["pipeline:run", "pipeline:step", "state:dispatch"],
+    on: ["pipeline:run", "pipeline:step", "state:dispatch", "column:batch"],
+    // column:batch: one timing per batch of a column, never per cell (§3.4).
+    hot: true,
     intercept(ctx, next) {
       const table = ctx.table;
       if (ctx.meta.has(SEEN) || typeof table !== "object" || table === null) return next();
       ctx.meta.set(SEEN, true);
       const start = now();
+      if (ctx.op === "column:batch") {
+        try {
+          return next();
+        } finally {
+          const slots = workOf(table).slots;
+          const t = slots.get(ctx.where);
+          const ms = now() - start;
+          if (t) t[1] += ms;
+          else slots.set(ctx.where, [ctx.input.column, ms]);
+        }
+      }
       if (ctx.op === "pipeline:run") {
         const trace = {
           run: ctx.run,
@@ -56,25 +110,32 @@ function tracer() {
         }
       }
       if (ctx.op === "pipeline:step") {
+        const w = workOf(table);
+        w.slots.clear();
         const out = next();
-        const ms = now() - start;
+        const own = now() - start;
+        const { feature, stage, indices } = ctx.input;
+        const pending = w.jobs;
+        const job = pending.get(feature);
+        let ms = own;
+        let runs;
+        if (ctx.meta.has(import_trace_store.SLICED)) {
+          pending.set(feature, { stage, ms: (job?.ms ?? 0) + own, runs: (job?.runs ?? 0) + 1 });
+        } else if (job) {
+          pending.delete(feature);
+          ms += job.ms;
+          runs = job.runs + 1;
+        }
         const trace = (0, import_trace_store.readTrace)(table);
         if (trace?.run === ctx.run) {
-          trace.steps.set(ctx.input.feature, {
-            input: ctx.input.indices.length,
+          trace.steps.set(feature, {
+            input: indices.length,
             output: out.length,
-            ms
-          });
-        }
-        if (ms > STEP_BUDGET_MS) {
-          ctx.emit("DK_PERF_HINT", {
-            feature: ctx.input.feature,
-            stage: ctx.input.stage,
             ms,
-            rows: ctx.input.indices.length,
-            budget: STEP_BUDGET_MS
+            ...runs ? { runs } : {}
           });
         }
+        hint(ctx.emit, w, feature, stage, own, indices.length, false);
         return out;
       }
       try {

package/dist/diagnostics/tracer.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/tracer.ts"],"sourcesContent":["import type { Interceptor } from '../intercept/define'\nimport { perfDiagnostics } from '../pipeline/perf-codes'\nimport { keepDiagnostics } from './catalog'\nimport { readTrace, type Trace, writeTrace } from './trace-store'\n\n/**\n * The longest a single step may take (ms): §9.3's longest-task budget. A traced step over it\n * reports `DK_PERF_HINT` (§8.3) with its numbers.\n */\nexport const STEP_BUDGET_MS = 50\n\ntype Traced = 'pipeline:run' | 'pipeline:step' | 'state:dispatch'\n\nconst now = (): number =>\n  typeof performance === 'object' && typeof performance?.now === 'function'\n    ? performance.now()\n    : Date.now()\n\n/** Set on the ctx by the first tracer of a chain: a second one (user + built-in) only passes on. */\nconst SEEN = 'tracer'\n\n/**\n * The `tracer` interceptor (§3.4): timings and per-step counts of the last pipeline run, read by\n * `table.explain()`. `createTable` installs it in development; in production it is off (§8.2) and\n * opt-in with `createTable({ interceptors: [tracer()] })`. Keeps the last run only: counts, never\n * rows.\n */\nexport function tracer(): Interceptor<Traced> {\n  // Inside the factory: a bundle that never creates a tracer drops the definition (§9.1).\n  keepDiagnostics(perfDiagnostics)\n  return {\n    name: 'tracer',\n    on: ['pipeline:run', 'pipeline:step', 'state:dispatch'],\n    intercept(ctx, next) {\n      const table = ctx.table\n      if (ctx.meta.has(SEEN) || typeof table !== 'object' || table === null) return next()\n      ctx.meta.set(SEEN, true)\n      const start = now()\n      if (ctx.op === 'pipeline:run') {\n        const trace: Trace = {\n          run: ctx.run,\n          trigger: ctx.trigger,\n          ms: undefined,\n          steps: new Map(),\n          dispatch: readTrace(table)?.dispatch,\n        }\n        writeTrace(table, trace)\n        try {\n          return next()\n        } finally {\n          trace.ms = now() - start\n        }\n      }\n      if (ctx.op === 'pipeline:step') {\n        const out = next() as Uint32Array\n        const ms = now() - start\n        const trace = readTrace(table)\n        if (trace?.run === ctx.run) {\n          trace.steps.set(ctx.input.feature, {\n            input: ctx.input.indices.length,\n            output: out.length,\n            ms,\n          })\n        }\n        if (ms > STEP_BUDGET_MS) {\n          ctx.emit('DK_PERF_HINT', {\n            feature: ctx.input.feature,\n            stage: ctx.input.stage,\n            ms,\n            rows: ctx.input.indices.length,\n            budget: STEP_BUDGET_MS,\n          })\n        }\n        return out\n      }\n      try {\n        return next()\n      } finally {\n        const dispatch = { where: ctx.where, ms: now() - start }\n        const trace = readTrace(table)\n        // Before the first (lazy) run: kept on an empty trace until a run carries it over.\n        if (trace) trace.dispatch = dispatch\n        else {\n          writeTrace(table, {\n            run: ctx.run,\n            trigger: ctx.trigger,\n            ms: undefined,\n            steps: new Map(),\n            dispatch,\n          })\n        }\n      }\n    },\n  } as Interceptor<Traced>\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AACA,wBAAgC;AAChC,qBAAgC;AAChC,yBAAkD;AAM3C,IAAM,iBAAiB;AAI9B,IAAM,MAAM,MACV,OAAO,gBAAgB,YAAY,OAAO,aAAa,QAAQ,aAC3D,YAAY,IAAI,IAChB,KAAK,IAAI;AAGf,IAAM,OAAO;AAQN,SAAS,SAA8B;AAE5C,sCAAgB,iCAAe;AAC/B,SAAO;AAAA,IACL,MAAM;AAAA,IACN,IAAI,CAAC,gBAAgB,iBAAiB,gBAAgB;AAAA,IACtD,UAAU,KAAK,MAAM;AACnB,YAAM,QAAQ,IAAI;AAClB,UAAI,IAAI,KAAK,IAAI,IAAI,KAAK,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO,KAAK;AACnF,UAAI,KAAK,IAAI,MAAM,IAAI;AACvB,YAAM,QAAQ,IAAI;AAClB,UAAI,IAAI,OAAO,gBAAgB;AAC7B,cAAM,QAAe;AAAA,UACnB,KAAK,IAAI;AAAA,UACT,SAAS,IAAI;AAAA,UACb,IAAI;AAAA,UACJ,OAAO,oBAAI,IAAI;AAAA,UACf,cAAU,8BAAU,KAAK,GAAG;AAAA,QAC9B;AACA,2CAAW,OAAO,KAAK;AACvB,YAAI;AACF,iBAAO,KAAK;AAAA,QACd,UAAE;AACA,gBAAM,KAAK,IAAI,IAAI;AAAA,QACrB;AAAA,MACF;AACA,UAAI,IAAI,OAAO,iBAAiB;AAC9B,cAAM,MAAM,KAAK;AACjB,cAAM,KAAK,IAAI,IAAI;AACnB,cAAM,YAAQ,8BAAU,KAAK;AAC7B,YAAI,OAAO,QAAQ,IAAI,KAAK;AAC1B,gBAAM,MAAM,IAAI,IAAI,MAAM,SAAS;AAAA,YACjC,OAAO,IAAI,MAAM,QAAQ;AAAA,YACzB,QAAQ,IAAI;AAAA,YACZ;AAAA,UACF,CAAC;AAAA,QACH;AACA,YAAI,KAAK,gBAAgB;AACvB,cAAI,KAAK,gBAAgB;AAAA,YACvB,SAAS,IAAI,MAAM;AAAA,YACnB,OAAO,IAAI,MAAM;AAAA,YACjB;AAAA,YACA,MAAM,IAAI,MAAM,QAAQ;AAAA,YACxB,QAAQ;AAAA,UACV,CAAC;AAAA,QACH;AACA,eAAO;AAAA,MACT;AACA,UAAI;AACF,eAAO,KAAK;AAAA,MACd,UAAE;AACA,cAAM,WAAW,EAAE,OAAO,IAAI,OAAO,IAAI,IAAI,IAAI,MAAM;AACvD,cAAM,YAAQ,8BAAU,KAAK;AAE7B,YAAI,MAAO,OAAM,WAAW;AAAA,aACvB;AACH,6CAAW,OAAO;AAAA,YAChB,KAAK,IAAI;AAAA,YACT,SAAS,IAAI;AAAA,YACb,IAAI;AAAA,YACJ,OAAO,oBAAI,IAAI;AAAA,YACf;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/tracer.ts"],"sourcesContent":["import type { ContextBase } from '../intercept/context'\nimport type { Interceptor } from '../intercept/define'\nimport { perfDiagnostics } from '../pipeline/perf-codes'\nimport { keepDiagnostics } from './catalog'\nimport { readTrace, SLICED, sliceTimer, type Trace, writeTrace } from './trace-store'\nimport type { Emit } from './types'\n\n/**\n * The longest a single step may take (ms): §9.3's longest-task budget. A traced step over it\n * reports `DK_PERF_HINT` (§8.3) with its numbers.\n */\nexport const STEP_BUDGET_MS = 50\n\ntype Traced = 'pipeline:run' | 'pipeline:step' | 'state:dispatch' | 'column:batch'\n\nconst now = (): number =>\n  typeof performance === 'object' && typeof performance?.now === 'function'\n    ? performance.now()\n    : Date.now()\n\n/** Set on the ctx by the first tracer of a chain: a second one (user + built-in) only passes on. */\nconst SEEN = 'tracer'\n\n/**\n * Per table, across runs (#61): a step waiting on time-sliced work, by feature: its stage, the\n * time of its runs so far plus the slices since, and how many runs. The run that gets the result\n * adds its own time and shows the total.\n */\ntype Job = { stage: string; ms: number; runs: number }\n\n/**\n * Per table: its steps waiting on sliced work, and the time of each `column:batch` slot\n * (`columns[0].format` → column id, ms) since the current step or slice began (#62).\n */\ntype Work = { jobs: Map<string, Job>; slots: Map<string, [string, number]> }\nconst work = new WeakMap<object, Work>()\n\nfunction workOf(table: object): Work {\n  let w = work.get(table)\n  if (!w) {\n    w = { jobs: new Map(), slots: new Map() }\n    work.set(table, w)\n  }\n  return w\n}\n\n/** DK_PERF_HINT for a task over the budget, with the slot most of its time went to (#62). */\nfunction hint(\n  emit: Emit,\n  w: Work,\n  feature: string,\n  stage: string,\n  ms: number,\n  rows: number,\n  sliced: boolean,\n) {\n  let slot: string | undefined\n  let top: [string, number] = ['', 0]\n  for (const [where, t] of w.slots) {\n    if (t[1] > top[1]) {\n      slot = where\n      top = t\n    }\n  }\n  w.slots.clear()\n  if (ms <= STEP_BUDGET_MS) return\n  emit('DK_PERF_HINT', {\n    feature,\n    stage,\n    ms,\n    rows,\n    budget: STEP_BUDGET_MS,\n    ...(sliced ? { sliced } : {}),\n    // Named when it took at least half of the time.\n    ...(slot && top[1] * 2 >= ms ? { slot, column: top[0], share: Math.min(1, top[1] / ms) } : {}),\n  })\n}\n\n/** A slice of time-sliced work, run between pipeline runs (#61): its own task. */\nfunction onSlice(base: ContextBase, feature: string, ms: number) {\n  const table = base.table as object\n  const trace = readTrace(table)\n  // Only for tables this tracer (or another) traces.\n  if (!trace) return\n  const w = workOf(table)\n  const job = w.jobs.get(feature)\n  if (job) job.ms += ms\n  hint(base.emit, w, feature, job?.stage ?? '', ms, trace.steps.get(feature)?.input ?? 0, true)\n}\n\n/**\n * The `tracer` interceptor (§3.4): timings and per-step counts of the last pipeline run, read by\n * `table.explain()`. `createTable` installs it in development; in production it is off (§8.2) and\n * opt-in with `createTable({ interceptors: [tracer()] })`. Keeps the last run only: counts, never\n * rows. Time-sliced work (§9.1) is added to the step that waited on it (#61).\n */\nexport function tracer(): Interceptor<Traced> {\n  // Inside the factory: a bundle that never creates a tracer drops the definition (§9.1).\n  keepDiagnostics(perfDiagnostics)\n  sliceTimer.current = onSlice\n  return {\n    name: 'tracer',\n    on: ['pipeline:run', 'pipeline:step', 'state:dispatch', 'column:batch'],\n    // column:batch: one timing per batch of a column, never per cell (§3.4).\n    hot: true,\n    intercept(ctx, next) {\n      const table = ctx.table\n      if (ctx.meta.has(SEEN) || typeof table !== 'object' || table === null) return next()\n      ctx.meta.set(SEEN, true)\n      const start = now()\n      if (ctx.op === 'column:batch') {\n        try {\n          return next()\n        } finally {\n          const slots = workOf(table).slots\n          const t = slots.get(ctx.where)\n          const ms = now() - start\n          if (t) t[1] += ms\n          else slots.set(ctx.where, [ctx.input.column, ms])\n        }\n      }\n      if (ctx.op === 'pipeline:run') {\n        const trace: Trace = {\n          run: ctx.run,\n          trigger: ctx.trigger,\n          ms: undefined,\n          steps: new Map(),\n          dispatch: readTrace(table)?.dispatch,\n        }\n        writeTrace(table, trace)\n        try {\n          return next()\n        } finally {\n          trace.ms = now() - start\n        }\n      }\n      if (ctx.op === 'pipeline:step') {\n        const w = workOf(table)\n        w.slots.clear()\n        const out = next() as Uint32Array\n        const own = now() - start\n        const { feature, stage, indices } = ctx.input\n        const pending = w.jobs\n        const job = pending.get(feature)\n        let ms = own\n        let runs: number | undefined\n        if (ctx.meta.has(SLICED)) {\n          // Its result comes in a later run: that run shows the total.\n          pending.set(feature, { stage, ms: (job?.ms ?? 0) + own, runs: (job?.runs ?? 0) + 1 })\n        } else if (job) {\n          pending.delete(feature)\n          ms += job.ms\n          runs = job.runs + 1\n        }\n        const trace = readTrace(table)\n        if (trace?.run === ctx.run) {\n          trace.steps.set(feature, {\n            input: indices.length,\n            output: out.length,\n            ms,\n            ...(runs ? { runs } : {}),\n          })\n        }\n        // One task: the step's own time.\n        hint(ctx.emit, w, feature, stage, own, indices.length, false)\n        return out\n      }\n      try {\n        return next()\n      } finally {\n        const dispatch = { where: ctx.where, ms: now() - start }\n        const trace = readTrace(table)\n        // Before the first (lazy) run: kept on an empty trace until a run carries it over.\n        if (trace) trace.dispatch = dispatch\n        else {\n          writeTrace(table, {\n            run: ctx.run,\n            trigger: ctx.trigger,\n            ms: undefined,\n            steps: new Map(),\n            dispatch,\n          })\n        }\n      }\n    },\n  } as Interceptor<Traced>\n}\n"],"mappings":"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","names":[]}

package/dist/diagnostics/tracer.js

@@ -1,20 +1,74 @@
 // src/diagnostics/tracer.ts
 import { perfDiagnostics } from "../pipeline/perf-codes.js";
 import { keepDiagnostics } from "./catalog.js";
-import { readTrace, writeTrace } from "./trace-store.js";
+import { readTrace, SLICED, sliceTimer, writeTrace } from "./trace-store.js";
 var STEP_BUDGET_MS = 50;
 var now = () => typeof performance === "object" && typeof performance?.now === "function" ? performance.now() : Date.now();
 var SEEN = "tracer";
+var work = /* @__PURE__ */ new WeakMap();
+function workOf(table) {
+  let w = work.get(table);
+  if (!w) {
+    w = { jobs: /* @__PURE__ */ new Map(), slots: /* @__PURE__ */ new Map() };
+    work.set(table, w);
+  }
+  return w;
+}
+function hint(emit, w, feature, stage, ms, rows, sliced) {
+  let slot;
+  let top = ["", 0];
+  for (const [where, t] of w.slots) {
+    if (t[1] > top[1]) {
+      slot = where;
+      top = t;
+    }
+  }
+  w.slots.clear();
+  if (ms <= STEP_BUDGET_MS) return;
+  emit("DK_PERF_HINT", {
+    feature,
+    stage,
+    ms,
+    rows,
+    budget: STEP_BUDGET_MS,
+    ...sliced ? { sliced } : {},
+    // Named when it took at least half of the time.
+    ...slot && top[1] * 2 >= ms ? { slot, column: top[0], share: Math.min(1, top[1] / ms) } : {}
+  });
+}
+function onSlice(base, feature, ms) {
+  const table = base.table;
+  const trace = readTrace(table);
+  if (!trace) return;
+  const w = workOf(table);
+  const job = w.jobs.get(feature);
+  if (job) job.ms += ms;
+  hint(base.emit, w, feature, job?.stage ?? "", ms, trace.steps.get(feature)?.input ?? 0, true);
+}
 function tracer() {
   keepDiagnostics(perfDiagnostics);
+  sliceTimer.current = onSlice;
   return {
     name: "tracer",
-    on: ["pipeline:run", "pipeline:step", "state:dispatch"],
+    on: ["pipeline:run", "pipeline:step", "state:dispatch", "column:batch"],
+    // column:batch: one timing per batch of a column, never per cell (§3.4).
+    hot: true,
     intercept(ctx, next) {
       const table = ctx.table;
       if (ctx.meta.has(SEEN) || typeof table !== "object" || table === null) return next();
       ctx.meta.set(SEEN, true);
       const start = now();
+      if (ctx.op === "column:batch") {
+        try {
+          return next();
+        } finally {
+          const slots = workOf(table).slots;
+          const t = slots.get(ctx.where);
+          const ms = now() - start;
+          if (t) t[1] += ms;
+          else slots.set(ctx.where, [ctx.input.column, ms]);
+        }
+      }
       if (ctx.op === "pipeline:run") {
         const trace = {
           run: ctx.run,
@@ -31,25 +85,32 @@ function tracer() {
         }
       }
       if (ctx.op === "pipeline:step") {
+        const w = workOf(table);
+        w.slots.clear();
         const out = next();
-        const ms = now() - start;
+        const own = now() - start;
+        const { feature, stage, indices } = ctx.input;
+        const pending = w.jobs;
+        const job = pending.get(feature);
+        let ms = own;
+        let runs;
+        if (ctx.meta.has(SLICED)) {
+          pending.set(feature, { stage, ms: (job?.ms ?? 0) + own, runs: (job?.runs ?? 0) + 1 });
+        } else if (job) {
+          pending.delete(feature);
+          ms += job.ms;
+          runs = job.runs + 1;
+        }
         const trace = readTrace(table);
         if (trace?.run === ctx.run) {
-          trace.steps.set(ctx.input.feature, {
-            input: ctx.input.indices.length,
+          trace.steps.set(feature, {
+            input: indices.length,
             output: out.length,
-            ms
-          });
-        }
-        if (ms > STEP_BUDGET_MS) {
-          ctx.emit("DK_PERF_HINT", {
-            feature: ctx.input.feature,
-            stage: ctx.input.stage,
             ms,
-            rows: ctx.input.indices.length,
-            budget: STEP_BUDGET_MS
+            ...runs ? { runs } : {}
           });
         }
+        hint(ctx.emit, w, feature, stage, own, indices.length, false);
         return out;
       }
       try {

package/dist/diagnostics/tracer.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/tracer.ts"],"sourcesContent":["import type { Interceptor } from '../intercept/define'\nimport { perfDiagnostics } from '../pipeline/perf-codes'\nimport { keepDiagnostics } from './catalog'\nimport { readTrace, type Trace, writeTrace } from './trace-store'\n\n/**\n * The longest a single step may take (ms): §9.3's longest-task budget. A traced step over it\n * reports `DK_PERF_HINT` (§8.3) with its numbers.\n */\nexport const STEP_BUDGET_MS = 50\n\ntype Traced = 'pipeline:run' | 'pipeline:step' | 'state:dispatch'\n\nconst now = (): number =>\n  typeof performance === 'object' && typeof performance?.now === 'function'\n    ? performance.now()\n    : Date.now()\n\n/** Set on the ctx by the first tracer of a chain: a second one (user + built-in) only passes on. */\nconst SEEN = 'tracer'\n\n/**\n * The `tracer` interceptor (§3.4): timings and per-step counts of the last pipeline run, read by\n * `table.explain()`. `createTable` installs it in development; in production it is off (§8.2) and\n * opt-in with `createTable({ interceptors: [tracer()] })`. Keeps the last run only: counts, never\n * rows.\n */\nexport function tracer(): Interceptor<Traced> {\n  // Inside the factory: a bundle that never creates a tracer drops the definition (§9.1).\n  keepDiagnostics(perfDiagnostics)\n  return {\n    name: 'tracer',\n    on: ['pipeline:run', 'pipeline:step', 'state:dispatch'],\n    intercept(ctx, next) {\n      const table = ctx.table\n      if (ctx.meta.has(SEEN) || typeof table !== 'object' || table === null) return next()\n      ctx.meta.set(SEEN, true)\n      const start = now()\n      if (ctx.op === 'pipeline:run') {\n        const trace: Trace = {\n          run: ctx.run,\n          trigger: ctx.trigger,\n          ms: undefined,\n          steps: new Map(),\n          dispatch: readTrace(table)?.dispatch,\n        }\n        writeTrace(table, trace)\n        try {\n          return next()\n        } finally {\n          trace.ms = now() - start\n        }\n      }\n      if (ctx.op === 'pipeline:step') {\n        const out = next() as Uint32Array\n        const ms = now() - start\n        const trace = readTrace(table)\n        if (trace?.run === ctx.run) {\n          trace.steps.set(ctx.input.feature, {\n            input: ctx.input.indices.length,\n            output: out.length,\n            ms,\n          })\n        }\n        if (ms > STEP_BUDGET_MS) {\n          ctx.emit('DK_PERF_HINT', {\n            feature: ctx.input.feature,\n            stage: ctx.input.stage,\n            ms,\n            rows: ctx.input.indices.length,\n            budget: STEP_BUDGET_MS,\n          })\n        }\n        return out\n      }\n      try {\n        return next()\n      } finally {\n        const dispatch = { where: ctx.where, ms: now() - start }\n        const trace = readTrace(table)\n        // Before the first (lazy) run: kept on an empty trace until a run carries it over.\n        if (trace) trace.dispatch = dispatch\n        else {\n          writeTrace(table, {\n            run: ctx.run,\n            trigger: ctx.trigger,\n            ms: undefined,\n            steps: new Map(),\n            dispatch,\n          })\n        }\n      }\n    },\n  } as Interceptor<Traced>\n}\n"],"mappings":";AACA,SAAS,uBAAuB;AAChC,SAAS,uBAAuB;AAChC,SAAS,WAAuB,kBAAkB;AAM3C,IAAM,iBAAiB;AAI9B,IAAM,MAAM,MACV,OAAO,gBAAgB,YAAY,OAAO,aAAa,QAAQ,aAC3D,YAAY,IAAI,IAChB,KAAK,IAAI;AAGf,IAAM,OAAO;AAQN,SAAS,SAA8B;AAE5C,kBAAgB,eAAe;AAC/B,SAAO;AAAA,IACL,MAAM;AAAA,IACN,IAAI,CAAC,gBAAgB,iBAAiB,gBAAgB;AAAA,IACtD,UAAU,KAAK,MAAM;AACnB,YAAM,QAAQ,IAAI;AAClB,UAAI,IAAI,KAAK,IAAI,IAAI,KAAK,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO,KAAK;AACnF,UAAI,KAAK,IAAI,MAAM,IAAI;AACvB,YAAM,QAAQ,IAAI;AAClB,UAAI,IAAI,OAAO,gBAAgB;AAC7B,cAAM,QAAe;AAAA,UACnB,KAAK,IAAI;AAAA,UACT,SAAS,IAAI;AAAA,UACb,IAAI;AAAA,UACJ,OAAO,oBAAI,IAAI;AAAA,UACf,UAAU,UAAU,KAAK,GAAG;AAAA,QAC9B;AACA,mBAAW,OAAO,KAAK;AACvB,YAAI;AACF,iBAAO,KAAK;AAAA,QACd,UAAE;AACA,gBAAM,KAAK,IAAI,IAAI;AAAA,QACrB;AAAA,MACF;AACA,UAAI,IAAI,OAAO,iBAAiB;AAC9B,cAAM,MAAM,KAAK;AACjB,cAAM,KAAK,IAAI,IAAI;AACnB,cAAM,QAAQ,UAAU,KAAK;AAC7B,YAAI,OAAO,QAAQ,IAAI,KAAK;AAC1B,gBAAM,MAAM,IAAI,IAAI,MAAM,SAAS;AAAA,YACjC,OAAO,IAAI,MAAM,QAAQ;AAAA,YACzB,QAAQ,IAAI;AAAA,YACZ;AAAA,UACF,CAAC;AAAA,QACH;AACA,YAAI,KAAK,gBAAgB;AACvB,cAAI,KAAK,gBAAgB;AAAA,YACvB,SAAS,IAAI,MAAM;AAAA,YACnB,OAAO,IAAI,MAAM;AAAA,YACjB;AAAA,YACA,MAAM,IAAI,MAAM,QAAQ;AAAA,YACxB,QAAQ;AAAA,UACV,CAAC;AAAA,QACH;AACA,eAAO;AAAA,MACT;AACA,UAAI;AACF,eAAO,KAAK;AAAA,MACd,UAAE;AACA,cAAM,WAAW,EAAE,OAAO,IAAI,OAAO,IAAI,IAAI,IAAI,MAAM;AACvD,cAAM,QAAQ,UAAU,KAAK;AAE7B,YAAI,MAAO,OAAM,WAAW;AAAA,aACvB;AACH,qBAAW,OAAO;AAAA,YAChB,KAAK,IAAI;AAAA,YACT,SAAS,IAAI;AAAA,YACb,IAAI;AAAA,YACJ,OAAO,oBAAI,IAAI;AAAA,YACf;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/tracer.ts"],"sourcesContent":["import type { ContextBase } from '../intercept/context'\nimport type { Interceptor } from '../intercept/define'\nimport { perfDiagnostics } from '../pipeline/perf-codes'\nimport { keepDiagnostics } from './catalog'\nimport { readTrace, SLICED, sliceTimer, type Trace, writeTrace } from './trace-store'\nimport type { Emit } from './types'\n\n/**\n * The longest a single step may take (ms): §9.3's longest-task budget. A traced step over it\n * reports `DK_PERF_HINT` (§8.3) with its numbers.\n */\nexport const STEP_BUDGET_MS = 50\n\ntype Traced = 'pipeline:run' | 'pipeline:step' | 'state:dispatch' | 'column:batch'\n\nconst now = (): number =>\n  typeof performance === 'object' && typeof performance?.now === 'function'\n    ? performance.now()\n    : Date.now()\n\n/** Set on the ctx by the first tracer of a chain: a second one (user + built-in) only passes on. */\nconst SEEN = 'tracer'\n\n/**\n * Per table, across runs (#61): a step waiting on time-sliced work, by feature: its stage, the\n * time of its runs so far plus the slices since, and how many runs. The run that gets the result\n * adds its own time and shows the total.\n */\ntype Job = { stage: string; ms: number; runs: number }\n\n/**\n * Per table: its steps waiting on sliced work, and the time of each `column:batch` slot\n * (`columns[0].format` → column id, ms) since the current step or slice began (#62).\n */\ntype Work = { jobs: Map<string, Job>; slots: Map<string, [string, number]> }\nconst work = new WeakMap<object, Work>()\n\nfunction workOf(table: object): Work {\n  let w = work.get(table)\n  if (!w) {\n    w = { jobs: new Map(), slots: new Map() }\n    work.set(table, w)\n  }\n  return w\n}\n\n/** DK_PERF_HINT for a task over the budget, with the slot most of its time went to (#62). */\nfunction hint(\n  emit: Emit,\n  w: Work,\n  feature: string,\n  stage: string,\n  ms: number,\n  rows: number,\n  sliced: boolean,\n) {\n  let slot: string | undefined\n  let top: [string, number] = ['', 0]\n  for (const [where, t] of w.slots) {\n    if (t[1] > top[1]) {\n      slot = where\n      top = t\n    }\n  }\n  w.slots.clear()\n  if (ms <= STEP_BUDGET_MS) return\n  emit('DK_PERF_HINT', {\n    feature,\n    stage,\n    ms,\n    rows,\n    budget: STEP_BUDGET_MS,\n    ...(sliced ? { sliced } : {}),\n    // Named when it took at least half of the time.\n    ...(slot && top[1] * 2 >= ms ? { slot, column: top[0], share: Math.min(1, top[1] / ms) } : {}),\n  })\n}\n\n/** A slice of time-sliced work, run between pipeline runs (#61): its own task. */\nfunction onSlice(base: ContextBase, feature: string, ms: number) {\n  const table = base.table as object\n  const trace = readTrace(table)\n  // Only for tables this tracer (or another) traces.\n  if (!trace) return\n  const w = workOf(table)\n  const job = w.jobs.get(feature)\n  if (job) job.ms += ms\n  hint(base.emit, w, feature, job?.stage ?? '', ms, trace.steps.get(feature)?.input ?? 0, true)\n}\n\n/**\n * The `tracer` interceptor (§3.4): timings and per-step counts of the last pipeline run, read by\n * `table.explain()`. `createTable` installs it in development; in production it is off (§8.2) and\n * opt-in with `createTable({ interceptors: [tracer()] })`. Keeps the last run only: counts, never\n * rows. Time-sliced work (§9.1) is added to the step that waited on it (#61).\n */\nexport function tracer(): Interceptor<Traced> {\n  // Inside the factory: a bundle that never creates a tracer drops the definition (§9.1).\n  keepDiagnostics(perfDiagnostics)\n  sliceTimer.current = onSlice\n  return {\n    name: 'tracer',\n    on: ['pipeline:run', 'pipeline:step', 'state:dispatch', 'column:batch'],\n    // column:batch: one timing per batch of a column, never per cell (§3.4).\n    hot: true,\n    intercept(ctx, next) {\n      const table = ctx.table\n      if (ctx.meta.has(SEEN) || typeof table !== 'object' || table === null) return next()\n      ctx.meta.set(SEEN, true)\n      const start = now()\n      if (ctx.op === 'column:batch') {\n        try {\n          return next()\n        } finally {\n          const slots = workOf(table).slots\n          const t = slots.get(ctx.where)\n          const ms = now() - start\n          if (t) t[1] += ms\n          else slots.set(ctx.where, [ctx.input.column, ms])\n        }\n      }\n      if (ctx.op === 'pipeline:run') {\n        const trace: Trace = {\n          run: ctx.run,\n          trigger: ctx.trigger,\n          ms: undefined,\n          steps: new Map(),\n          dispatch: readTrace(table)?.dispatch,\n        }\n        writeTrace(table, trace)\n        try {\n          return next()\n        } finally {\n          trace.ms = now() - start\n        }\n      }\n      if (ctx.op === 'pipeline:step') {\n        const w = workOf(table)\n        w.slots.clear()\n        const out = next() as Uint32Array\n        const own = now() - start\n        const { feature, stage, indices } = ctx.input\n        const pending = w.jobs\n        const job = pending.get(feature)\n        let ms = own\n        let runs: number | undefined\n        if (ctx.meta.has(SLICED)) {\n          // Its result comes in a later run: that run shows the total.\n          pending.set(feature, { stage, ms: (job?.ms ?? 0) + own, runs: (job?.runs ?? 0) + 1 })\n        } else if (job) {\n          pending.delete(feature)\n          ms += job.ms\n          runs = job.runs + 1\n        }\n        const trace = readTrace(table)\n        if (trace?.run === ctx.run) {\n          trace.steps.set(feature, {\n            input: indices.length,\n            output: out.length,\n            ms,\n            ...(runs ? { runs } : {}),\n          })\n        }\n        // One task: the step's own time.\n        hint(ctx.emit, w, feature, stage, own, indices.length, false)\n        return out\n      }\n      try {\n        return next()\n      } finally {\n        const dispatch = { where: ctx.where, ms: now() - start }\n        const trace = readTrace(table)\n        // Before the first (lazy) run: kept on an empty trace until a run carries it over.\n        if (trace) trace.dispatch = dispatch\n        else {\n          writeTrace(table, {\n            run: ctx.run,\n            trigger: ctx.trigger,\n            ms: undefined,\n            steps: new Map(),\n            dispatch,\n          })\n        }\n      }\n    },\n  } as Interceptor<Traced>\n}\n"],"mappings":"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","names":[]}

package/dist/diagnostics/types.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/diagnostics/types.ts"],"sourcesContent":["import type { DiagnosticCode, DiagnosticDetails } from './catalog'\n\nexport type { DiagnosticCode, DiagnosticDetails } from './catalog'\n\nexport type DiagnosticLevel = 'error' | 'warn' | 'info'\n\nexport type Trigger = 'init' | 'data-change' | 'setOptions' | 'hydrate' | 'fetch' | `api:${string}`\n\nexport type Phase = 'ssr' | 'hydrate' | 'client'\n\n/**\n * Where in the developer's code or data (§8.1). `interceptor` and `operation` are additions for\n * plugin-level codes the spec table does not locate (interceptors, op registry).\n */\nexport type Location =\n  | { kind: 'column'; index: number; id: string }\n  | { kind: 'feature'; name: string }\n  | { kind: 'option'; path: string }\n  | { kind: 'row'; index: number; key?: string }\n  | { kind: 'interceptor'; name: string; op: string }\n  | { kind: 'operation'; op: string; slot?: string }\n\n/** A summary of table state — never raw input (§8.1). */\nexport interface DiagnosticStateSummary {\n  searchLength: number\n  activeFilters: string[]\n  sort: string[]\n  page: number\n}\n\nexport interface DiagnosticContext {\n  /** `options.name`, else `table#n`. */\n  table: string\n  /** Dev: creation site, e.g. `UsersPage.tsx:42`. */\n  createdAt?: string\n  /** `@datakable/core@x.y.z` */\n  package: string\n  trigger: Trigger\n  /** Pipeline run id — joins explain() and other diagnostics. */\n  run: number\n  phase: Phase\n  mode: Record<string, 'client' | 'server'>\n  state: DiagnosticStateSummary\n  occurrences: { count: number; first: number; last: number }\n  /** e.g. `DK_SCHEMA_INVALID_ROW#run57` */\n  causedBy?: string\n  /** Original error (ES2022 cause). Reaches `onDiagnostic` only; `toJSON` and the console leave it out. */\n  cause?: unknown\n}\n\nexport interface Diagnostic {\n  /** Stable public API; never reused or redefined. */\n  code: DiagnosticCode\n  level: DiagnosticLevel\n  /** What happened, instance-specific. Empty in production unless messages are opted in. */\n  problem: string\n  where: Location\n  /** Consequence + the fallback the system applied. */\n  impact: string\n  /** Concrete fixes, best first. */\n  fix: string[]\n  /** `docs/errors.md#<code>` (+ query params in production). */\n  docs: string\n  /** The catalog details. Redaction (T26) rewrites them before any sink sees them. */\n  details: Record<string, unknown>\n  context: DiagnosticContext\n  /** `code@where` — grouping key (dedupe, Sentry). */\n  fingerprint: string\n  /** Safe serializer: bigint, cycles and Errors never throw; `context.cause` is left out. */\n  toJSON(): object\n}\n\n/** Per-call additions to the live context. */\nexport interface EmitOptions {\n  cause?: unknown\n  causedBy?: string\n  run?: number\n  trigger?: Trigger\n  phase?: Phase\n}\n\n/** Emits a catalog diagnostic; `details` is typed by `code` (see `DiagnosticCatalog`). */\nexport type Emit = <C extends DiagnosticCode>(\n  code: C,\n  details: DiagnosticDetails<C>,\n  options?: EmitOptions,\n) => void\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/diagnostics/types.ts"],"sourcesContent":["import type { DiagnosticCode, DiagnosticDetails } from './catalog'\n\nexport type { DiagnosticCode, DiagnosticDetails } from './catalog'\n\nexport type DiagnosticLevel = 'error' | 'warn' | 'info'\n\nexport type Trigger = 'init' | 'data-change' | 'setOptions' | 'hydrate' | 'fetch' | `api:${string}`\n\nexport type Phase = 'ssr' | 'hydrate' | 'client'\n\n/**\n * Where in the developer's code or data (§8.1). `interceptor` and `operation` are additions for\n * plugin-level codes the spec table does not locate (interceptors, op registry).\n */\nexport type Location =\n  | { kind: 'column'; index: number; id: string }\n  | { kind: 'feature'; name: string }\n  | { kind: 'option'; path: string }\n  | { kind: 'row'; index: number; key?: string }\n  | { kind: 'interceptor'; name: string; op: string }\n  | { kind: 'operation'; op: string; slot?: string }\n\n/** A summary of table state — never raw input (§8.1). */\nexport interface DiagnosticStateSummary {\n  searchLength: number\n  activeFilters: string[]\n  sort: string[]\n  page: number\n}\n\nexport interface DiagnosticContext {\n  /** `options.name`, else `table#n`. */\n  table: string\n  /** Dev: creation site, e.g. `UsersPage.tsx:42`. */\n  createdAt?: string\n  /** `@datakable/core@x.y.z` */\n  package: string\n  trigger: Trigger\n  /** Pipeline run id — joins explain() and other diagnostics. */\n  run: number\n  phase: Phase\n  mode: Record<string, 'client' | 'server'>\n  state: DiagnosticStateSummary\n  occurrences: { count: number; first: number; last: number }\n  /** e.g. `DK_SCHEMA_INVALID_ROW#run57` */\n  causedBy?: string\n  /** Original error (ES2022 cause). Reaches `onDiagnostic` only; `toJSON` and the console leave it out. */\n  cause?: unknown\n}\n\nexport interface Diagnostic {\n  /** Stable public API; never reused or redefined. */\n  code: DiagnosticCode\n  level: DiagnosticLevel\n  /** What happened, instance-specific. Empty in production unless messages are opted in. */\n  problem: string\n  where: Location\n  /** Consequence + the fallback the system applied. */\n  impact: string\n  /** Concrete fixes, best first. */\n  fix: string[]\n  /** `docs/errors.md#<code>` (+ query params in production). */\n  docs: string\n  /** The catalog details. Redaction (T26) rewrites them before any sink sees them. */\n  details: Record<string, unknown>\n  context: DiagnosticContext\n  /** `code@where` — grouping key (dedupe, Sentry). */\n  fingerprint: string\n  /** Safe serializer: bigint, cycles and Errors never throw; `context.cause` is left out. */\n  toJSON(): object\n}\n\n/** Per-call additions to the live context. */\nexport interface EmitOptions {\n  cause?: unknown\n  causedBy?: string\n  run?: number\n  trigger?: Trigger\n  phase?: Phase\n  /**\n   * Not printed by the default console sink (another table printed it in this process, #38). Still\n   * stored and delivered to `onDiagnostic`.\n   */\n  quiet?: boolean\n}\n\n/** Emits a catalog diagnostic; `details` is typed by `code` (see `DiagnosticCatalog`). */\nexport type Emit = <C extends DiagnosticCode>(\n  code: C,\n  details: DiagnosticDetails<C>,\n  options?: EmitOptions,\n) => void\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}