@sanqianx/claude-ai-workbench 0.13.2 → 0.13.3

package/src/backend/lib/native-task-messages.js

@@ -1,457 +1,457 @@
-'use strict';
-
-// Pure normalization of public SDK SessionMessage snapshots into redacted,
-// deterministic candidate records for native task messages. The module has
-// no I/O and no authority: it never reads transcripts, never persists,
-// never allocates journal dedup keys or TaskRefs, and never fabricates
-// fields the public SDK types do not promise. Every string destined for the
-// output — text values, tool-input object KEYS, tool names, model labels,
-// and free-form diagnostic details — must pass the caller-supplied redaction
-// callback; a missing, throwing, or malformed callback fails the whole
-// normalization closed with a fixed safe message that never echoes callback
-// or snapshot content. Linkage identifiers (entry uuid, tool call id, model
-// message id) are kept only when they match a strict identifier pattern AND
-// the caller's own redaction callback leaves them untouched — an identifier
-// the redaction boundary wants to change (an embedded credential, private
-// text) is rejected with a diagnostic, never published raw and never
-// published in redacted form (a changed identifier could not be paired
-// honestly). Raw tool names needed for internal conflict comparison live
-// only in a module WeakMap; no returned object carries them.
-
-const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-const IDENTIFIER_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
-const USAGE_TOKEN_FIELDS = ['input_tokens', 'output_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens'];
-// Unredacted tool names are comparison state, not output: they live only in
-// this WeakMap keyed by the published block/step objects and never travel on
-// any returned DTO.
-const rawToolNames = new WeakMap();
-
-const FAILURES = {
-  inputInvalid: ['NATIVE_TASK_MESSAGES_INPUT_INVALID', 'native task message normalization refused: messages must be an array'],
-  redactRequired: ['NATIVE_TASK_MESSAGES_REDACT_REQUIRED', 'native task message normalization refused: no redaction callback was provided'],
-  redactFailed: ['NATIVE_TASK_MESSAGES_REDACT_FAILED', 'native task message normalization refused: the redaction callback failed'],
-};
-
-function fail(kind) {
-  const error = new Error(FAILURES[kind][1]);
-  error.code = FAILURES[kind][0];
-  throw error;
-}
-
-// Diagnostics carry only codes, pattern-safe identifiers, counts, and
-// redacted free-form details — never raw snapshot text. Occurrence counts
-// reflect the raw input stream (duplicates included); the structural stats
-// in the result reflect the deduplicated snapshot.
-function createDiagnostics() {
-  const counts = new Map();
-  return {
-    add(code, detail) {
-      const key = detail ? code + '|' + detail : code;
-      counts.set(key, (counts.get(key) || 0) + 1);
-    },
-    list() {
-      const rows = [];
-      for (const [key, count] of counts) {
-        const sep = key.indexOf('|');
-        rows.push(sep === -1 ? { code: key, detail: null, count } : { code: key.slice(0, sep), detail: key.slice(sep + 1), count });
-      }
-      rows.sort((a, b) => {
-        if (a.code !== b.code) return a.code < b.code ? -1 : 1;
-        const x = a.detail === null ? '' : a.detail;
-        const y = b.detail === null ? '' : b.detail;
-        return x < y ? -1 : x > y ? 1 : 0;
-      });
-      return rows;
-    },
-  };
-}
-
-function redactText(redact, text, field) {
-  let value;
-  try {
-    value = redact(text, { field });
-  } catch {
-    fail('redactFailed');
-  }
-  if (typeof value !== 'string') fail('redactFailed');
-  return value;
-}
-
-// A linkage identifier is publishable only when the pattern accepts it AND
-// the redaction boundary leaves it byte-identical. A changed value means the
-// identifier itself carries content the caller classifies as sensitive: it
-// is dropped with the existing invalid-identifier diagnostic (no detail, so
-// the offending value never reaches the diagnostics surface) while the rest
-// of the snapshot keeps normalizing. A throwing or non-string callback still
-// fails the whole normalization closed, exactly like every other redaction.
-function publishableIdentifier(redact, value, missingCode, invalidCode, diagnostics) {
-  if (typeof value !== 'string' || value.length === 0) { diagnostics.add(missingCode); return null; }
-  if (!IDENTIFIER_PATTERN.test(value)) { diagnostics.add(invalidCode); return null; }
-  let safe;
-  try {
-    safe = redact(value, { field: 'identifier' });
-  } catch {
-    fail('redactFailed');
-  }
-  if (typeof safe !== 'string') fail('redactFailed');
-  if (safe !== value) { diagnostics.add(invalidCode); return null; }
-  return value;
-}
-
-// Object keys are publishable strings too, so they cross the same redaction
-// boundary as values. When two distinct source keys redact to the same
-// output key, the collision is reported and the later key (in sorted source
-// order) is dropped — a collision never silently overwrites a key.
-function redactValue(redact, value, field, diagnostics) {
-  if (typeof value === 'string') return redactText(redact, value, field);
-  if (Array.isArray(value)) return value.map(item => redactValue(redact, item, field, diagnostics));
-  if (value !== null && typeof value === 'object') {
-    const out = {};
-    for (const key of Object.keys(value).sort()) {
-      const safeKey = redactText(redact, key, field);
-      if (Object.prototype.hasOwnProperty.call(out, safeKey)) diagnostics.add('redact-key-collision', field);
-      else out[safeKey] = redactValue(redact, value[key], field, diagnostics);
-    }
-    return out;
-  }
-  return value;
-}
-
-// The public SessionMessage type promises no timestamp. Accept only real
-// calendar dates in the exact ISO shape observed in recorded snapshots:
-// positional digit/separator checks plus month/day (leap-aware), hour,
-// minute and second range validation. Anything else becomes a diagnostic;
-// absence is normal and never an error, and no timestamp is ever invented.
-function observedTimestamp(value) {
-  if (value === undefined || value === null) return { state: 'absent' };
-  if (typeof value !== 'string') return { state: 'invalid' };
-  const digit = i => { const c = value.charAt(i); return c >= '0' && c <= '9'; };
-  const digits = (from, to) => { for (let i = from; i < to; i += 1) if (!digit(i)) return false; return true; };
-  let ok = digits(0, 4) && value.charAt(4) === '-'
-    && digits(5, 7) && value.charAt(7) === '-'
-    && digits(8, 10) && value.charAt(10) === 'T'
-    && digits(11, 13) && value.charAt(13) === ':'
-    && digits(14, 16) && value.charAt(16) === ':'
-    && digits(17, 19);
-  if (ok) {
-    const dot = value.indexOf('.');
-    if (dot === -1) ok = value.length === 20 && value.charAt(19) === 'Z';
-    else ok = dot === 19 && value.length >= 22 && value.endsWith('Z') && digits(20, value.length - 1);
-  }
-  if (ok) {
-    const year = Number(value.slice(0, 4));
-    const month = Number(value.slice(5, 7));
-    const day = Number(value.slice(8, 10));
-    const hour = Number(value.slice(11, 13));
-    const minute = Number(value.slice(14, 16));
-    const second = Number(value.slice(17, 19));
-    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
-    const monthDays = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-    ok = year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= monthDays[month - 1]
-      && hour <= 23 && minute <= 59 && second <= 59;
-  }
-  return ok ? { state: 'observed', value } : { state: 'invalid' };
-}
-
-function extractUsage(raw) {
-  if (raw === undefined || raw === null) return { kind: 'absent' };
-  if (typeof raw !== 'object' || Array.isArray(raw)) return { kind: 'invalid' };
-  const usage = {};
-  for (const field of USAGE_TOKEN_FIELDS) {
-    if (!Object.prototype.hasOwnProperty.call(raw, field)) continue;
-    const value = raw[field];
-    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) return { kind: 'invalid' };
-    usage[field] = value;
-  }
-  return Object.keys(usage).length > 0 ? { kind: 'valid', usage } : { kind: 'invalid' };
-}
-
-const isPlaceholderUsage = usage => USAGE_TOKEN_FIELDS.every(field => usage[field] === undefined || usage[field] === 0);
-const usageSignature = usage => JSON.stringify(USAGE_TOKEN_FIELDS.filter(field => usage[field] !== undefined).map(field => [field, usage[field]]));
-
-function normalizeBlocks(entry, redact, diagnostics) {
-  const message = entry.message;
-  const content = message === null || typeof message !== 'object' ? undefined : message.content;
-  const textField = entry.type === 'assistant' ? 'assistant-text' : 'user-text';
-  const blocks = [];
-  const dropped = { thinking: 0, unknown: 0 };
-  if (content === undefined || content === null) {
-    diagnostics.add('content-missing', entry.type);
-    return { blocks, dropped };
-  }
-  if (typeof content === 'string') {
-    blocks.push({ kind: 'text', text: redactText(redact, content, textField) });
-    return { blocks, dropped };
-  }
-  if (!Array.isArray(content)) {
-    diagnostics.add('content-invalid', entry.type);
-    return { blocks, dropped };
-  }
-  for (const item of content) {
-    if (item === null || typeof item !== 'object' || typeof item.type !== 'string') {
-      diagnostics.add('block-invalid', item === null || typeof item !== 'object' ? 'non-object' : 'type-missing');
-      continue;
-    }
-    if (item.type === 'thinking') { dropped.thinking += 1; continue; }
-    if (item.type === 'text') {
-      if (typeof item.text !== 'string') { diagnostics.add('block-invalid', 'text'); continue; }
-      blocks.push({ kind: 'text', text: redactText(redact, item.text, textField) });
-      continue;
-    }
-    if (item.type === 'tool_use') {
-      const toolUseId = publishableIdentifier(redact, item.id, 'tool-use-id-missing', 'tool-call-id-invalid', diagnostics);
-      if (toolUseId === null) continue;
-      if (typeof item.name !== 'string' || item.name.length === 0) { diagnostics.add('tool-use-name-missing'); continue; }
-      const block = { kind: 'tool_use', toolUseId, name: redactText(redact, item.name, 'tool-name'), input: redactValue(redact, item.input === undefined ? null : item.input, 'tool-use-input', diagnostics) };
-      rawToolNames.set(block, item.name);
-      blocks.push(block);
-      continue;
-    }
-    if (item.type === 'tool_result') {
-      const toolUseId = publishableIdentifier(redact, item.tool_use_id, 'tool-result-id-missing', 'tool-call-id-invalid', diagnostics);
-      if (toolUseId === null) continue;
-      const block = { kind: 'tool_result', toolUseId };
-      if (item.is_error !== undefined) {
-        if (typeof item.is_error === 'boolean') block.isError = item.is_error;
-        else diagnostics.add('tool-result-field-invalid', 'is_error');
-      }
-      const texts = [];
-      if (typeof item.content === 'string') texts.push(redactText(redact, item.content, 'tool-result-text'));
-      else if (Array.isArray(item.content)) {
-        for (const part of item.content) {
-          if (part !== null && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string') texts.push(redactText(redact, part.text, 'tool-result-text'));
-          else diagnostics.add('tool-result-item-unsupported', part !== null && typeof part === 'object' && typeof part.type === 'string' ? redactText(redact, part.type, 'diagnostic-text') : 'non-text');
-        }
-      } else if (item.content !== undefined && item.content !== null) diagnostics.add('tool-result-content-invalid', typeof item.content);
-      block.texts = texts;
-      blocks.push(block);
-      continue;
-    }
-    dropped.unknown += 1;
-    diagnostics.add('unknown-block-type', redactText(redact, item.type, 'diagnostic-text'));
-  }
-  return { blocks, dropped };
-}
-
-function normalizeEntry(entry, redact, diagnostics, stats) {
-  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) { diagnostics.add('entry-invalid', entry === null || typeof entry !== 'object' ? 'non-object' : 'array'); return null; }
-  if (entry.type === 'system') { stats.systemEntriesSkipped += 1; return null; }
-  if (entry.type !== 'user' && entry.type !== 'assistant') { diagnostics.add('entry-type-unknown', typeof entry.type === 'string' ? redactText(redact, entry.type, 'diagnostic-text') : 'non-string'); return null; }
-  if (typeof entry.uuid !== 'string' || !UUID_PATTERN.test(entry.uuid)) { diagnostics.add('entry-uuid-invalid'); return null; }
-  const timestamp = observedTimestamp(entry.timestamp);
-  if (timestamp.state === 'invalid') { diagnostics.add('timestamp-invalid'); stats.invalidTimestamps += 1; }
-  const messageOk = entry.message !== null && typeof entry.message === 'object' && !Array.isArray(entry.message);
-  if (!messageOk) diagnostics.add('message-invalid', entry.type);
-  const normalized = { uuid: entry.uuid, role: entry.type };
-  if (timestamp.state === 'observed') normalized.timestamp = timestamp.value;
-  let usageExtract = { kind: 'absent' };
-  if (messageOk) {
-    const message = entry.message;
-    if (entry.type === 'assistant') {
-      const modelMessageId = publishableIdentifier(redact, message.id, 'model-id-missing', 'model-id-invalid', diagnostics);
-      if (modelMessageId !== null) normalized.modelMessageId = modelMessageId;
-      if (typeof message.model === 'string' && message.model.length > 0) normalized.model = redactText(redact, message.model, 'model');
-      usageExtract = extractUsage(message.usage);
-      if (usageExtract.kind === 'invalid') diagnostics.add('usage-invalid-value');
-    }
-  }
-  const blockResult = messageOk ? normalizeBlocks(entry, redact, diagnostics) : { blocks: [], dropped: { thinking: 0, unknown: 0 } };
-  normalized.blocks = blockResult.blocks;
-  stats.thinkingBlocksDropped += blockResult.dropped.thinking;
-  stats.unknownBlocksDropped += blockResult.dropped.unknown;
-  return { normalized, usageExtract };
-}
-
-function normalizeTaskMessages(messages, options) {
-  if (!Array.isArray(messages)) fail('inputInvalid');
-  const redact = options !== null && typeof options === 'object' ? options.redact : undefined;
-  if (typeof redact !== 'function') fail('redactRequired');
-  const diagnostics = createDiagnostics();
-  const stats = {
-    inputEntries: messages.length, entries: 0, duplicatesCollapsed: 0, uuidConflicts: 0,
-    byRole: { user: 0, assistant: 0 },
-    textBlocks: 0, toolUseBlocks: 0, toolResultBlocks: 0,
-    thinkingBlocksDropped: 0, unknownBlocksDropped: 0,
-    systemEntriesSkipped: 0, invalidTimestamps: 0,
-  };
-  // Idempotency is per entry uuid inside one snapshot: identical re-reads
-  // collapse, and one uuid carrying two different payloads is a conflict
-  // that is reported, never silently overwritten.
-  const byUuid = new Map();
-  for (const raw of messages) {
-    const item = normalizeEntry(raw, redact, diagnostics, stats);
-    if (item === null) continue;
-    const key = JSON.stringify({ entry: item.normalized, usage: item.usageExtract.kind === 'valid' ? item.usageExtract.usage : item.usageExtract.kind });
-    const existing = byUuid.get(item.normalized.uuid);
-    if (existing === undefined) { byUuid.set(item.normalized.uuid, { normalized: item.normalized, usageExtract: item.usageExtract, key, count: 1, conflict: false }); continue; }
-    if (existing.key === key) { existing.count += 1; diagnostics.add('duplicate-entry', item.normalized.uuid); continue; }
-    existing.conflict = true;
-    diagnostics.add('uuid-conflict', item.normalized.uuid);
-  }
-  const survivors = [];
-  for (const record of byUuid.values()) {
-    if (record.conflict) { stats.uuidConflicts += 1; continue; }
-    stats.duplicatesCollapsed += record.count - 1;
-    stats.entries += 1;
-    stats.byRole[record.normalized.role] += 1;
-    for (const block of record.normalized.blocks) {
-      if (block.kind === 'text') stats.textBlocks += 1;
-      else if (block.kind === 'tool_use') stats.toolUseBlocks += 1;
-      else stats.toolResultBlocks += 1;
-    }
-    survivors.push(record);
-  }
-  // Tool identity is the tool_use/tool_result id: chunked or re-read copies
-  // of the same call merge into one step and never create a second step.
-  // Name conflicts compare the raw tool names held in the module WeakMap;
-  // only the redacted name is ever published.
-  const steps = new Map();
-  const stepRawNames = new Map();
-  for (const record of survivors) {
-    const uuid = record.normalized.uuid;
-    for (const block of record.normalized.blocks) {
-      if (block.kind === 'tool_use') {
-        let step = steps.get(block.toolUseId);
-        if (step === undefined) {
-          step = { toolUseId: block.toolUseId, name: block.name, useEntryUuids: [uuid], resultEntryUuid: null, isError: undefined, resultTextCount: undefined, duplicateUseCount: 0, duplicateResultCount: 0, nameConflict: false };
-          steps.set(block.toolUseId, step);
-          stepRawNames.set(step, rawToolNames.get(block));
-        } else if (!stepRawNames.has(step)) {
-          stepRawNames.set(step, rawToolNames.get(block));
-          step.name = block.name;
-          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
-        } else if (stepRawNames.get(step) !== rawToolNames.get(block)) {
-          step.nameConflict = true;
-          diagnostics.add('tool-use-id-conflict', block.toolUseId);
-          step.duplicateUseCount += 1;
-          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
-        } else {
-          step.duplicateUseCount += 1;
-          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
-        }
-      } else if (block.kind === 'tool_result') {
-        let step = steps.get(block.toolUseId);
-        if (step === undefined) {
-          step = { toolUseId: block.toolUseId, name: null, useEntryUuids: [], resultEntryUuid: null, isError: undefined, resultTextCount: undefined, duplicateUseCount: 0, duplicateResultCount: 0, nameConflict: false };
-          steps.set(block.toolUseId, step);
-        }
-        if (step.resultEntryUuid === null) {
-          step.resultEntryUuid = uuid;
-          step.isError = block.isError;
-          step.resultTextCount = block.texts.length;
-        } else {
-          step.duplicateResultCount += 1;
-        }
-      }
-    }
-  }
-  stats.unpairedToolUse = 0;
-  stats.unpairedToolResult = 0;
-  for (const step of steps.values()) {
-    step.paired = step.useEntryUuids.length > 0 && step.resultEntryUuid !== null;
-    if (step.useEntryUuids.length === 0) { stats.unpairedToolResult += 1; diagnostics.add('unpaired-tool-result', step.toolUseId); }
-    else if (step.resultEntryUuid === null) { stats.unpairedToolUse += 1; diagnostics.add('unpaired-tool-use', step.toolUseId); }
-  }
-  // Usage is attributed to the model response (message.id), never summed
-  // per entry uuid. All-zero usages are placeholders distinguishable from a
-  // response's actual non-zero usage; identical repeated actual usage counts
-  // once; distinct actual usages for one id are a conflict that is reported
-  // and excluded, never averaged. Usage observed on an entry with no valid
-  // message id is unattributable: it contributes no numbers anywhere.
-  const assistantSurvivors = survivors.filter(r => r.normalized.role === 'assistant');
-  const groups = [];
-  const byGroupKey = new Map();
-  for (const record of assistantSurvivors) {
-    const hasId = Object.prototype.hasOwnProperty.call(record.normalized, 'modelMessageId');
-    const key = hasId ? 'id::' + record.normalized.modelMessageId : 'noid::' + record.normalized.uuid;
-    let group = byGroupKey.get(key);
-    if (group === undefined) { group = { modelMessageId: hasId ? record.normalized.modelMessageId : null, records: [] }; byGroupKey.set(key, group); groups.push(group); }
-    group.records.push(record);
-  }
-  const usageRecords = [];
-  let zero = 0, conflict = 0, missing = 0, placeholderUsages = 0, duplicateIdenticalUsages = 0;
-  for (const group of groups) {
-    const valid = group.records.filter(r => r.usageExtract.kind === 'valid').map(r => r.usageExtract.usage);
-    if (group.modelMessageId === null) {
-      if (valid.length > 0) for (const r of group.records) if (r.usageExtract.kind === 'valid') diagnostics.add('usage-without-model-id');
-      continue;
-    }
-    const placeholders = valid.filter(isPlaceholderUsage);
-    const substantive = valid.filter(u => !isPlaceholderUsage(u));
-    let status, usage = null, placeholderCount = 0, duplicateIdenticalCount = 0;
-    if (substantive.length > 0) {
-      const signatures = new Set(substantive.map(usageSignature));
-      if (signatures.size === 1) {
-        status = 'resolved';
-        usage = substantive[0];
-        placeholderCount = placeholders.length;
-        duplicateIdenticalCount = substantive.length - 1;
-        placeholderUsages += placeholderCount;
-        duplicateIdenticalUsages += duplicateIdenticalCount;
-      } else {
-        status = 'conflict';
-        conflict += 1;
-        placeholderUsages += placeholders.length;
-        diagnostics.add('usage-conflict', group.modelMessageId);
-      }
-    } else if (placeholders.length > 0) {
-      status = 'zero';
-      usage = placeholders[0];
-      zero += 1;
-    } else {
-      status = 'missing';
-      missing += 1;
-    }
-    usageRecords.push({
-      modelMessageId: group.modelMessageId,
-      entryUuids: group.records.map(r => r.normalized.uuid),
-      status,
-      usage,
-      placeholderCount,
-      duplicateIdenticalCount,
-      conflictDetail: status === 'conflict' ? 'distinct non-zero usage payloads observed for one model message id' : null,
-    });
-  }
-  // Totals are complete only when every assistant survivor carried a valid
-  // model message id and every one of those responses resolved to exactly
-  // one usage observation (actual or an explicit SDK zero). Anything less —
-  // missing usage, a conflict, or an unattributable response — makes the
-  // grand totals explicitly unknown (null per field) instead of a silently
-  // fabricated 0. The same honesty applies per field: a token field the
-  // resolved responses never reported is unknown (null), never summed as 0 —
-  // only a field every contributing response explicitly provided (zero
-  // included) earns a numeric total. The knownTotals subtotal follows the
-  // same per-field rule over the fully resolved responses only.
-  const completeRecords = usageRecords.filter(r => r.status === 'resolved' || r.status === 'zero');
-  const knownTotals = { responses: completeRecords.length, totals: {} };
-  for (const field of USAGE_TOKEN_FIELDS) {
-    const fieldObserved = completeRecords.every(r => r.usage[field] !== undefined);
-    knownTotals.totals[field] = fieldObserved ? completeRecords.reduce((sum, r) => sum + r.usage[field], 0) : null;
-  }
-  const allAttributed = assistantSurvivors.every(r => Object.prototype.hasOwnProperty.call(r.normalized, 'modelMessageId'));
-  const totalsComplete = assistantSurvivors.length > 0 && allAttributed && completeRecords.length === usageRecords.length;
-  const totals = {};
-  for (const field of USAGE_TOKEN_FIELDS) totals[field] = totalsComplete ? knownTotals.totals[field] : null;
-  const usageSummary = {
-    modelResponses: usageRecords.length,
-    resolved: completeRecords.filter(r => r.status === 'resolved').length,
-    zero,
-    conflict,
-    missing,
-    placeholderUsages,
-    duplicateIdenticalUsages,
-    totalsComplete,
-    totals,
-    knownTotals,
-  };
-  return {
-    entries: survivors.map(r => r.normalized),
-    toolSteps: [...steps.values()],
-    usageRecords,
-    usageSummary,
-    stats,
-    diagnostics: diagnostics.list(),
-  };
-}
-
-module.exports = { normalizeTaskMessages };
+'use strict';
+
+// Pure normalization of public SDK SessionMessage snapshots into redacted,
+// deterministic candidate records for native task messages. The module has
+// no I/O and no authority: it never reads transcripts, never persists,
+// never allocates journal dedup keys or TaskRefs, and never fabricates
+// fields the public SDK types do not promise. Every string destined for the
+// output — text values, tool-input object KEYS, tool names, model labels,
+// and free-form diagnostic details — must pass the caller-supplied redaction
+// callback; a missing, throwing, or malformed callback fails the whole
+// normalization closed with a fixed safe message that never echoes callback
+// or snapshot content. Linkage identifiers (entry uuid, tool call id, model
+// message id) are kept only when they match a strict identifier pattern AND
+// the caller's own redaction callback leaves them untouched — an identifier
+// the redaction boundary wants to change (an embedded credential, private
+// text) is rejected with a diagnostic, never published raw and never
+// published in redacted form (a changed identifier could not be paired
+// honestly). Raw tool names needed for internal conflict comparison live
+// only in a module WeakMap; no returned object carries them.
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const IDENTIFIER_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+const USAGE_TOKEN_FIELDS = ['input_tokens', 'output_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens'];
+// Unredacted tool names are comparison state, not output: they live only in
+// this WeakMap keyed by the published block/step objects and never travel on
+// any returned DTO.
+const rawToolNames = new WeakMap();
+
+const FAILURES = {
+  inputInvalid: ['NATIVE_TASK_MESSAGES_INPUT_INVALID', 'native task message normalization refused: messages must be an array'],
+  redactRequired: ['NATIVE_TASK_MESSAGES_REDACT_REQUIRED', 'native task message normalization refused: no redaction callback was provided'],
+  redactFailed: ['NATIVE_TASK_MESSAGES_REDACT_FAILED', 'native task message normalization refused: the redaction callback failed'],
+};
+
+function fail(kind) {
+  const error = new Error(FAILURES[kind][1]);
+  error.code = FAILURES[kind][0];
+  throw error;
+}
+
+// Diagnostics carry only codes, pattern-safe identifiers, counts, and
+// redacted free-form details — never raw snapshot text. Occurrence counts
+// reflect the raw input stream (duplicates included); the structural stats
+// in the result reflect the deduplicated snapshot.
+function createDiagnostics() {
+  const counts = new Map();
+  return {
+    add(code, detail) {
+      const key = detail ? code + '|' + detail : code;
+      counts.set(key, (counts.get(key) || 0) + 1);
+    },
+    list() {
+      const rows = [];
+      for (const [key, count] of counts) {
+        const sep = key.indexOf('|');
+        rows.push(sep === -1 ? { code: key, detail: null, count } : { code: key.slice(0, sep), detail: key.slice(sep + 1), count });
+      }
+      rows.sort((a, b) => {
+        if (a.code !== b.code) return a.code < b.code ? -1 : 1;
+        const x = a.detail === null ? '' : a.detail;
+        const y = b.detail === null ? '' : b.detail;
+        return x < y ? -1 : x > y ? 1 : 0;
+      });
+      return rows;
+    },
+  };
+}
+
+function redactText(redact, text, field) {
+  let value;
+  try {
+    value = redact(text, { field });
+  } catch {
+    fail('redactFailed');
+  }
+  if (typeof value !== 'string') fail('redactFailed');
+  return value;
+}
+
+// A linkage identifier is publishable only when the pattern accepts it AND
+// the redaction boundary leaves it byte-identical. A changed value means the
+// identifier itself carries content the caller classifies as sensitive: it
+// is dropped with the existing invalid-identifier diagnostic (no detail, so
+// the offending value never reaches the diagnostics surface) while the rest
+// of the snapshot keeps normalizing. A throwing or non-string callback still
+// fails the whole normalization closed, exactly like every other redaction.
+function publishableIdentifier(redact, value, missingCode, invalidCode, diagnostics) {
+  if (typeof value !== 'string' || value.length === 0) { diagnostics.add(missingCode); return null; }
+  if (!IDENTIFIER_PATTERN.test(value)) { diagnostics.add(invalidCode); return null; }
+  let safe;
+  try {
+    safe = redact(value, { field: 'identifier' });
+  } catch {
+    fail('redactFailed');
+  }
+  if (typeof safe !== 'string') fail('redactFailed');
+  if (safe !== value) { diagnostics.add(invalidCode); return null; }
+  return value;
+}
+
+// Object keys are publishable strings too, so they cross the same redaction
+// boundary as values. When two distinct source keys redact to the same
+// output key, the collision is reported and the later key (in sorted source
+// order) is dropped — a collision never silently overwrites a key.
+function redactValue(redact, value, field, diagnostics) {
+  if (typeof value === 'string') return redactText(redact, value, field);
+  if (Array.isArray(value)) return value.map(item => redactValue(redact, item, field, diagnostics));
+  if (value !== null && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      const safeKey = redactText(redact, key, field);
+      if (Object.prototype.hasOwnProperty.call(out, safeKey)) diagnostics.add('redact-key-collision', field);
+      else out[safeKey] = redactValue(redact, value[key], field, diagnostics);
+    }
+    return out;
+  }
+  return value;
+}
+
+// The public SessionMessage type promises no timestamp. Accept only real
+// calendar dates in the exact ISO shape observed in recorded snapshots:
+// positional digit/separator checks plus month/day (leap-aware), hour,
+// minute and second range validation. Anything else becomes a diagnostic;
+// absence is normal and never an error, and no timestamp is ever invented.
+function observedTimestamp(value) {
+  if (value === undefined || value === null) return { state: 'absent' };
+  if (typeof value !== 'string') return { state: 'invalid' };
+  const digit = i => { const c = value.charAt(i); return c >= '0' && c <= '9'; };
+  const digits = (from, to) => { for (let i = from; i < to; i += 1) if (!digit(i)) return false; return true; };
+  let ok = digits(0, 4) && value.charAt(4) === '-'
+    && digits(5, 7) && value.charAt(7) === '-'
+    && digits(8, 10) && value.charAt(10) === 'T'
+    && digits(11, 13) && value.charAt(13) === ':'
+    && digits(14, 16) && value.charAt(16) === ':'
+    && digits(17, 19);
+  if (ok) {
+    const dot = value.indexOf('.');
+    if (dot === -1) ok = value.length === 20 && value.charAt(19) === 'Z';
+    else ok = dot === 19 && value.length >= 22 && value.endsWith('Z') && digits(20, value.length - 1);
+  }
+  if (ok) {
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    const hour = Number(value.slice(11, 13));
+    const minute = Number(value.slice(14, 16));
+    const second = Number(value.slice(17, 19));
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const monthDays = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    ok = year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= monthDays[month - 1]
+      && hour <= 23 && minute <= 59 && second <= 59;
+  }
+  return ok ? { state: 'observed', value } : { state: 'invalid' };
+}
+
+function extractUsage(raw) {
+  if (raw === undefined || raw === null) return { kind: 'absent' };
+  if (typeof raw !== 'object' || Array.isArray(raw)) return { kind: 'invalid' };
+  const usage = {};
+  for (const field of USAGE_TOKEN_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(raw, field)) continue;
+    const value = raw[field];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) return { kind: 'invalid' };
+    usage[field] = value;
+  }
+  return Object.keys(usage).length > 0 ? { kind: 'valid', usage } : { kind: 'invalid' };
+}
+
+const isPlaceholderUsage = usage => USAGE_TOKEN_FIELDS.every(field => usage[field] === undefined || usage[field] === 0);
+const usageSignature = usage => JSON.stringify(USAGE_TOKEN_FIELDS.filter(field => usage[field] !== undefined).map(field => [field, usage[field]]));
+
+function normalizeBlocks(entry, redact, diagnostics) {
+  const message = entry.message;
+  const content = message === null || typeof message !== 'object' ? undefined : message.content;
+  const textField = entry.type === 'assistant' ? 'assistant-text' : 'user-text';
+  const blocks = [];
+  const dropped = { thinking: 0, unknown: 0 };
+  if (content === undefined || content === null) {
+    diagnostics.add('content-missing', entry.type);
+    return { blocks, dropped };
+  }
+  if (typeof content === 'string') {
+    blocks.push({ kind: 'text', text: redactText(redact, content, textField) });
+    return { blocks, dropped };
+  }
+  if (!Array.isArray(content)) {
+    diagnostics.add('content-invalid', entry.type);
+    return { blocks, dropped };
+  }
+  for (const item of content) {
+    if (item === null || typeof item !== 'object' || typeof item.type !== 'string') {
+      diagnostics.add('block-invalid', item === null || typeof item !== 'object' ? 'non-object' : 'type-missing');
+      continue;
+    }
+    if (item.type === 'thinking') { dropped.thinking += 1; continue; }
+    if (item.type === 'text') {
+      if (typeof item.text !== 'string') { diagnostics.add('block-invalid', 'text'); continue; }
+      blocks.push({ kind: 'text', text: redactText(redact, item.text, textField) });
+      continue;
+    }
+    if (item.type === 'tool_use') {
+      const toolUseId = publishableIdentifier(redact, item.id, 'tool-use-id-missing', 'tool-call-id-invalid', diagnostics);
+      if (toolUseId === null) continue;
+      if (typeof item.name !== 'string' || item.name.length === 0) { diagnostics.add('tool-use-name-missing'); continue; }
+      const block = { kind: 'tool_use', toolUseId, name: redactText(redact, item.name, 'tool-name'), input: redactValue(redact, item.input === undefined ? null : item.input, 'tool-use-input', diagnostics) };
+      rawToolNames.set(block, item.name);
+      blocks.push(block);
+      continue;
+    }
+    if (item.type === 'tool_result') {
+      const toolUseId = publishableIdentifier(redact, item.tool_use_id, 'tool-result-id-missing', 'tool-call-id-invalid', diagnostics);
+      if (toolUseId === null) continue;
+      const block = { kind: 'tool_result', toolUseId };
+      if (item.is_error !== undefined) {
+        if (typeof item.is_error === 'boolean') block.isError = item.is_error;
+        else diagnostics.add('tool-result-field-invalid', 'is_error');
+      }
+      const texts = [];
+      if (typeof item.content === 'string') texts.push(redactText(redact, item.content, 'tool-result-text'));
+      else if (Array.isArray(item.content)) {
+        for (const part of item.content) {
+          if (part !== null && typeof part === 'object' && part.type === 'text' && typeof part.text === 'string') texts.push(redactText(redact, part.text, 'tool-result-text'));
+          else diagnostics.add('tool-result-item-unsupported', part !== null && typeof part === 'object' && typeof part.type === 'string' ? redactText(redact, part.type, 'diagnostic-text') : 'non-text');
+        }
+      } else if (item.content !== undefined && item.content !== null) diagnostics.add('tool-result-content-invalid', typeof item.content);
+      block.texts = texts;
+      blocks.push(block);
+      continue;
+    }
+    dropped.unknown += 1;
+    diagnostics.add('unknown-block-type', redactText(redact, item.type, 'diagnostic-text'));
+  }
+  return { blocks, dropped };
+}
+
+function normalizeEntry(entry, redact, diagnostics, stats) {
+  if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) { diagnostics.add('entry-invalid', entry === null || typeof entry !== 'object' ? 'non-object' : 'array'); return null; }
+  if (entry.type === 'system') { stats.systemEntriesSkipped += 1; return null; }
+  if (entry.type !== 'user' && entry.type !== 'assistant') { diagnostics.add('entry-type-unknown', typeof entry.type === 'string' ? redactText(redact, entry.type, 'diagnostic-text') : 'non-string'); return null; }
+  if (typeof entry.uuid !== 'string' || !UUID_PATTERN.test(entry.uuid)) { diagnostics.add('entry-uuid-invalid'); return null; }
+  const timestamp = observedTimestamp(entry.timestamp);
+  if (timestamp.state === 'invalid') { diagnostics.add('timestamp-invalid'); stats.invalidTimestamps += 1; }
+  const messageOk = entry.message !== null && typeof entry.message === 'object' && !Array.isArray(entry.message);
+  if (!messageOk) diagnostics.add('message-invalid', entry.type);
+  const normalized = { uuid: entry.uuid, role: entry.type };
+  if (timestamp.state === 'observed') normalized.timestamp = timestamp.value;
+  let usageExtract = { kind: 'absent' };
+  if (messageOk) {
+    const message = entry.message;
+    if (entry.type === 'assistant') {
+      const modelMessageId = publishableIdentifier(redact, message.id, 'model-id-missing', 'model-id-invalid', diagnostics);
+      if (modelMessageId !== null) normalized.modelMessageId = modelMessageId;
+      if (typeof message.model === 'string' && message.model.length > 0) normalized.model = redactText(redact, message.model, 'model');
+      usageExtract = extractUsage(message.usage);
+      if (usageExtract.kind === 'invalid') diagnostics.add('usage-invalid-value');
+    }
+  }
+  const blockResult = messageOk ? normalizeBlocks(entry, redact, diagnostics) : { blocks: [], dropped: { thinking: 0, unknown: 0 } };
+  normalized.blocks = blockResult.blocks;
+  stats.thinkingBlocksDropped += blockResult.dropped.thinking;
+  stats.unknownBlocksDropped += blockResult.dropped.unknown;
+  return { normalized, usageExtract };
+}
+
+function normalizeTaskMessages(messages, options) {
+  if (!Array.isArray(messages)) fail('inputInvalid');
+  const redact = options !== null && typeof options === 'object' ? options.redact : undefined;
+  if (typeof redact !== 'function') fail('redactRequired');
+  const diagnostics = createDiagnostics();
+  const stats = {
+    inputEntries: messages.length, entries: 0, duplicatesCollapsed: 0, uuidConflicts: 0,
+    byRole: { user: 0, assistant: 0 },
+    textBlocks: 0, toolUseBlocks: 0, toolResultBlocks: 0,
+    thinkingBlocksDropped: 0, unknownBlocksDropped: 0,
+    systemEntriesSkipped: 0, invalidTimestamps: 0,
+  };
+  // Idempotency is per entry uuid inside one snapshot: identical re-reads
+  // collapse, and one uuid carrying two different payloads is a conflict
+  // that is reported, never silently overwritten.
+  const byUuid = new Map();
+  for (const raw of messages) {
+    const item = normalizeEntry(raw, redact, diagnostics, stats);
+    if (item === null) continue;
+    const key = JSON.stringify({ entry: item.normalized, usage: item.usageExtract.kind === 'valid' ? item.usageExtract.usage : item.usageExtract.kind });
+    const existing = byUuid.get(item.normalized.uuid);
+    if (existing === undefined) { byUuid.set(item.normalized.uuid, { normalized: item.normalized, usageExtract: item.usageExtract, key, count: 1, conflict: false }); continue; }
+    if (existing.key === key) { existing.count += 1; diagnostics.add('duplicate-entry', item.normalized.uuid); continue; }
+    existing.conflict = true;
+    diagnostics.add('uuid-conflict', item.normalized.uuid);
+  }
+  const survivors = [];
+  for (const record of byUuid.values()) {
+    if (record.conflict) { stats.uuidConflicts += 1; continue; }
+    stats.duplicatesCollapsed += record.count - 1;
+    stats.entries += 1;
+    stats.byRole[record.normalized.role] += 1;
+    for (const block of record.normalized.blocks) {
+      if (block.kind === 'text') stats.textBlocks += 1;
+      else if (block.kind === 'tool_use') stats.toolUseBlocks += 1;
+      else stats.toolResultBlocks += 1;
+    }
+    survivors.push(record);
+  }
+  // Tool identity is the tool_use/tool_result id: chunked or re-read copies
+  // of the same call merge into one step and never create a second step.
+  // Name conflicts compare the raw tool names held in the module WeakMap;
+  // only the redacted name is ever published.
+  const steps = new Map();
+  const stepRawNames = new Map();
+  for (const record of survivors) {
+    const uuid = record.normalized.uuid;
+    for (const block of record.normalized.blocks) {
+      if (block.kind === 'tool_use') {
+        let step = steps.get(block.toolUseId);
+        if (step === undefined) {
+          step = { toolUseId: block.toolUseId, name: block.name, useEntryUuids: [uuid], resultEntryUuid: null, isError: undefined, resultTextCount: undefined, duplicateUseCount: 0, duplicateResultCount: 0, nameConflict: false };
+          steps.set(block.toolUseId, step);
+          stepRawNames.set(step, rawToolNames.get(block));
+        } else if (!stepRawNames.has(step)) {
+          stepRawNames.set(step, rawToolNames.get(block));
+          step.name = block.name;
+          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
+        } else if (stepRawNames.get(step) !== rawToolNames.get(block)) {
+          step.nameConflict = true;
+          diagnostics.add('tool-use-id-conflict', block.toolUseId);
+          step.duplicateUseCount += 1;
+          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
+        } else {
+          step.duplicateUseCount += 1;
+          if (!step.useEntryUuids.includes(uuid)) step.useEntryUuids.push(uuid);
+        }
+      } else if (block.kind === 'tool_result') {
+        let step = steps.get(block.toolUseId);
+        if (step === undefined) {
+          step = { toolUseId: block.toolUseId, name: null, useEntryUuids: [], resultEntryUuid: null, isError: undefined, resultTextCount: undefined, duplicateUseCount: 0, duplicateResultCount: 0, nameConflict: false };
+          steps.set(block.toolUseId, step);
+        }
+        if (step.resultEntryUuid === null) {
+          step.resultEntryUuid = uuid;
+          step.isError = block.isError;
+          step.resultTextCount = block.texts.length;
+        } else {
+          step.duplicateResultCount += 1;
+        }
+      }
+    }
+  }
+  stats.unpairedToolUse = 0;
+  stats.unpairedToolResult = 0;
+  for (const step of steps.values()) {
+    step.paired = step.useEntryUuids.length > 0 && step.resultEntryUuid !== null;
+    if (step.useEntryUuids.length === 0) { stats.unpairedToolResult += 1; diagnostics.add('unpaired-tool-result', step.toolUseId); }
+    else if (step.resultEntryUuid === null) { stats.unpairedToolUse += 1; diagnostics.add('unpaired-tool-use', step.toolUseId); }
+  }
+  // Usage is attributed to the model response (message.id), never summed
+  // per entry uuid. All-zero usages are placeholders distinguishable from a
+  // response's actual non-zero usage; identical repeated actual usage counts
+  // once; distinct actual usages for one id are a conflict that is reported
+  // and excluded, never averaged. Usage observed on an entry with no valid
+  // message id is unattributable: it contributes no numbers anywhere.
+  const assistantSurvivors = survivors.filter(r => r.normalized.role === 'assistant');
+  const groups = [];
+  const byGroupKey = new Map();
+  for (const record of assistantSurvivors) {
+    const hasId = Object.prototype.hasOwnProperty.call(record.normalized, 'modelMessageId');
+    const key = hasId ? 'id::' + record.normalized.modelMessageId : 'noid::' + record.normalized.uuid;
+    let group = byGroupKey.get(key);
+    if (group === undefined) { group = { modelMessageId: hasId ? record.normalized.modelMessageId : null, records: [] }; byGroupKey.set(key, group); groups.push(group); }
+    group.records.push(record);
+  }
+  const usageRecords = [];
+  let zero = 0, conflict = 0, missing = 0, placeholderUsages = 0, duplicateIdenticalUsages = 0;
+  for (const group of groups) {
+    const valid = group.records.filter(r => r.usageExtract.kind === 'valid').map(r => r.usageExtract.usage);
+    if (group.modelMessageId === null) {
+      if (valid.length > 0) for (const r of group.records) if (r.usageExtract.kind === 'valid') diagnostics.add('usage-without-model-id');
+      continue;
+    }
+    const placeholders = valid.filter(isPlaceholderUsage);
+    const substantive = valid.filter(u => !isPlaceholderUsage(u));
+    let status, usage = null, placeholderCount = 0, duplicateIdenticalCount = 0;
+    if (substantive.length > 0) {
+      const signatures = new Set(substantive.map(usageSignature));
+      if (signatures.size === 1) {
+        status = 'resolved';
+        usage = substantive[0];
+        placeholderCount = placeholders.length;
+        duplicateIdenticalCount = substantive.length - 1;
+        placeholderUsages += placeholderCount;
+        duplicateIdenticalUsages += duplicateIdenticalCount;
+      } else {
+        status = 'conflict';
+        conflict += 1;
+        placeholderUsages += placeholders.length;
+        diagnostics.add('usage-conflict', group.modelMessageId);
+      }
+    } else if (placeholders.length > 0) {
+      status = 'zero';
+      usage = placeholders[0];
+      zero += 1;
+    } else {
+      status = 'missing';
+      missing += 1;
+    }
+    usageRecords.push({
+      modelMessageId: group.modelMessageId,
+      entryUuids: group.records.map(r => r.normalized.uuid),
+      status,
+      usage,
+      placeholderCount,
+      duplicateIdenticalCount,
+      conflictDetail: status === 'conflict' ? 'distinct non-zero usage payloads observed for one model message id' : null,
+    });
+  }
+  // Totals are complete only when every assistant survivor carried a valid
+  // model message id and every one of those responses resolved to exactly
+  // one usage observation (actual or an explicit SDK zero). Anything less —
+  // missing usage, a conflict, or an unattributable response — makes the
+  // grand totals explicitly unknown (null per field) instead of a silently
+  // fabricated 0. The same honesty applies per field: a token field the
+  // resolved responses never reported is unknown (null), never summed as 0 —
+  // only a field every contributing response explicitly provided (zero
+  // included) earns a numeric total. The knownTotals subtotal follows the
+  // same per-field rule over the fully resolved responses only.
+  const completeRecords = usageRecords.filter(r => r.status === 'resolved' || r.status === 'zero');
+  const knownTotals = { responses: completeRecords.length, totals: {} };
+  for (const field of USAGE_TOKEN_FIELDS) {
+    const fieldObserved = completeRecords.every(r => r.usage[field] !== undefined);
+    knownTotals.totals[field] = fieldObserved ? completeRecords.reduce((sum, r) => sum + r.usage[field], 0) : null;
+  }
+  const allAttributed = assistantSurvivors.every(r => Object.prototype.hasOwnProperty.call(r.normalized, 'modelMessageId'));
+  const totalsComplete = assistantSurvivors.length > 0 && allAttributed && completeRecords.length === usageRecords.length;
+  const totals = {};
+  for (const field of USAGE_TOKEN_FIELDS) totals[field] = totalsComplete ? knownTotals.totals[field] : null;
+  const usageSummary = {
+    modelResponses: usageRecords.length,
+    resolved: completeRecords.filter(r => r.status === 'resolved').length,
+    zero,
+    conflict,
+    missing,
+    placeholderUsages,
+    duplicateIdenticalUsages,
+    totalsComplete,
+    totals,
+    knownTotals,
+  };
+  return {
+    entries: survivors.map(r => r.normalized),
+    toolSteps: [...steps.values()],
+    usageRecords,
+    usageSummary,
+    stats,
+    diagnostics: diagnostics.list(),
+  };
+}
+
+module.exports = { normalizeTaskMessages };