@volter/supercode-interchange 0.1.1 → 0.1.3

package/session-claude-content.mjs

@@ -0,0 +1,209 @@
+import { createMessage, markToolError, markToolOutcomeUnknown } from './message.mjs';
+import { cloneNativeJson, nativeInteger, stringifyNativeJson, stringifyNativeJsonMember } from './native-json.mjs';
+import { field, stringField, functionCall, toolMessage, restoreGrokMessageExtension } from './session-codec-utils.mjs';
+import { nativeTrim } from './text.mjs';
+
+export const UNCONVERTIBLE_IMAGE_MARKER = '[image: source not captured — unsupported/unconvertible image reference]';
+const appendText = (text, part) => typeof part === 'string' ? text + (text === '' ? '' : '\n') + part : text;
+
+export function claudeImagePart(block) {
+  const source = field(block, 'source'), kind = stringField(source, 'type');
+  if (kind === 'base64') {
+    const mime = stringField(source, 'media_type'), data = stringField(source, 'data');
+    return mime != null && mime !== '' && data != null && data !== '' ? { type: 'image_url', image_url: { url: `data:${mime};base64,${data}` } } : null;
+  }
+  const url = stringField(source, 'url');
+  return kind === 'url' && url != null && url !== '' ? { type: 'image_url', image_url: { url } } : null;
+}
+
+function toolResultContent(block, record) {
+  const content = field(block, 'content'), parts = [], images = [];
+  if (typeof content === 'string') { if (content !== '') parts.push(content); }
+  else if (Array.isArray(content)) {
+    for (const item of content) {
+      const kind = stringField(item, 'type');
+      if (kind === 'text') { const text = stringField(item, 'text'); if (text != null) parts.push(text); }
+      else if (kind === 'image') { const image = claudeImagePart(item); if (image != null) images.push(image); else parts.push(UNCONVERTIBLE_IMAGE_MARKER); }
+      else if (kind === 'tool_reference') parts.push(`[tool_reference: ${stringField(item, 'tool_name') ?? '?'}]`);
+      else if (typeof item === 'string') parts.push(item);
+    }
+  } else if (content !== undefined) parts.push(stringifyNativeJsonMember(block, 'content'));
+  const joined = parts.join('\n');
+  if (nativeTrim(joined) !== '' || images.length) return { text: joined, images };
+  const fallback = field(record, 'toolUseResult');
+  return { text: fallback === undefined ? joined : typeof fallback === 'string' ? fallback : stringifyNativeJsonMember(record, 'toolUseResult'), images };
+}
+
+export function claudeUserProvenance(value) {
+  const result = Object.create(null);
+  for (const key of ['promptSource', 'interruptedMessageId', 'sourceToolUseID']) {
+    const text = stringField(value, key); if (text != null) result[key] = text;
+  }
+  for (const key of ['isMeta', 'isCompactSummary', 'isVisibleInTranscriptOnly']) if (field(value, key) === true) result[key] = 'true';
+  const priority = nativeInteger(value, 'queuePriority', { signed: true });
+  if (priority != null) result.queuePriority = String(priority);
+  const origin = stringField(field(value, 'origin'), 'kind'); if (origin != null) result.origin = origin;
+  return result;
+}
+
+export function pushClaudeUser(value, out) {
+  const content = field(field(value, 'message'), 'content'), provenance = claudeUserProvenance(value);
+  if (typeof content === 'string') {
+    if (nativeTrim(content) !== '') { const message = createMessage('user', content); Object.assign(message.metadata, provenance); out.push(message); }
+    return;
+  }
+  if (!Array.isArray(content)) return;
+  let text = '', unconvertible = false;
+  const images = [];
+  for (const block of content) {
+    const kind = stringField(block, 'type');
+    if (kind === 'text') text = appendText(text, stringField(block, 'text'));
+    else if (kind === 'image') {
+      const image = claudeImagePart(block); if (image == null) unconvertible = true; else images.push(image);
+    } else if (kind === 'tool_result') {
+      const result = toolResultContent(block, value), message = toolMessage(stringField(block, 'tool_use_id') ?? '', result.text);
+      if (result.images.length) {
+        message.content_parts = message.content === '' ? [] : [{ type: 'text', text: message.content }];
+        for (const image of result.images) message.content_parts.push(image);
+      }
+      const assistant = stringField(value, 'sourceToolAssistantUUID');
+      if (assistant != null) message.metadata.sourceToolAssistantUUID = assistant;
+      if (field(block, 'is_error') === true) markToolError(message);
+      else if (stringField(value, '_supercode_tool_outcome') === 'unknown') markToolOutcomeUnknown(message);
+      out.push(message);
+    }
+  }
+  if (!images.length && nativeTrim(text) === '' && unconvertible) text = appendText(text, UNCONVERTIBLE_IMAGE_MARKER);
+  if (!images.length && nativeTrim(text) === '') return;
+  const message = createMessage('user', images.length ? null : text);
+  if (images.length) {
+    message.content_parts = nativeTrim(text) === '' ? [] : [{ type: 'text', text }];
+    for (const image of images) message.content_parts.push(image);
+  }
+  Object.assign(message.metadata, provenance);
+  if (unconvertible) message.metadata.image_source_unconvertible = 'true';
+  out.push(message);
+}
+
+export function pushClaudeAssistant(value, out) {
+  const content = field(field(value, 'message'), 'content'), calls = [], images = [], thinkingBlocks = [];
+  let text = '', thinking = '', signature = null, redacted = null, thinkingSeen = false, redactedSeen = false, unconvertible = false;
+  if (typeof content === 'string') text = appendText(text, content);
+  else if (Array.isArray(content)) for (const block of content) {
+    const kind = stringField(block, 'type');
+    if (kind === 'text') text = appendText(text, stringField(block, 'text'));
+    else if (kind === 'tool_use') calls.push(functionCall(stringField(block, 'id') ?? '', stringField(block, 'name') ?? '', field(block, 'input') === undefined ? '{}' : stringifyNativeJsonMember(block, 'input')));
+    else if (kind === 'thinking') {
+      thinkingSeen = true;
+      const part = stringField(block, 'thinking') ?? '', sig = stringField(block, 'signature');
+      if (part !== '') thinking = appendText(thinking, part);
+      const retained = { type: 'thinking', thinking: part };
+      if (sig != null) { signature = sig; retained.signature = sig; }
+      thinkingBlocks.push(retained);
+    } else if (kind === 'redacted_thinking') {
+      redactedSeen = true;
+      const data = stringField(block, 'data'), retained = { type: 'redacted_thinking' };
+      if (data != null) { redacted = data; retained.data = data; }
+      thinkingBlocks.push(retained);
+    } else if (kind === 'image') {
+      const image = claudeImagePart(block); if (image == null) unconvertible = true; else images.push(image);
+    } else if (kind === 'fallback') {
+      text = appendText(text, `[model fallback: ${stringField(field(block, 'from'), 'model') ?? '?'} -> ${stringField(field(block, 'to'), 'model') ?? '?'}]`);
+    }
+  }
+  if (!images.length && nativeTrim(text) === '' && unconvertible) text = appendText(text, UNCONVERTIBLE_IMAGE_MARKER);
+  const hasText = nativeTrim(text) !== '', message = createMessage('assistant', images.length || !hasText ? null : text);
+  message.tool_calls = calls.length ? calls : null;
+  if (images.length) {
+    message.content_parts = hasText ? [{ type: 'text', text }] : [];
+    for (const image of images) message.content_parts.push(image);
+  } else if (!hasText && !calls.length && !thinkingSeen && !redactedSeen) message.metadata.empty_assistant_record = 'true';
+  if (thinkingSeen) message.metadata.thinking = thinking;
+  if (signature != null) message.metadata.thinking_signature = signature;
+  if (redacted != null) message.metadata.redacted_thinking = redacted;
+  if (thinkingBlocks.length) message.metadata.thinking_blocks = stringifyNativeJson(thinkingBlocks);
+  if (unconvertible) message.metadata.image_source_unconvertible = 'true';
+  for (const key of ['attributionSkill', 'attributionAgent', 'attributionMcpServer', 'attributionMcpTool', 'slug']) {
+    const text = stringField(value, key); if (text != null) message.metadata[key] = text;
+  }
+  out.push(message);
+}
+
+export function pushClaudeSystem(value, out) {
+  const subtype = stringField(value, 'subtype'), content = stringField(value, 'content');
+  if (!['scheduled_task_fire', 'local_command', 'away_summary'].includes(subtype) || content == null || nativeTrim(content) === '') return;
+  const message = createMessage('system', content); message.metadata.systemSubtype = subtype; out.push(message);
+}
+
+export function pushClaudeAttachment(value, out) {
+  const attachment = field(value, 'attachment'), kind = stringField(attachment, 'type');
+  let text = null;
+  if (kind === 'queued_command') text = stringField(attachment, 'prompt');
+  else {
+    const spec = { file: ['attached file', 'filename', 'content'], edited_text_file: ['edited file', 'filename', 'snippet'], nested_memory: ['project memory', 'path', 'content'] };
+    const selected = Object.hasOwn(spec, kind ?? '') ? spec[kind] : null;
+    if (selected != null) {
+      const [label, pathKey, bodyKey] = selected, body = stringField(attachment, bodyKey);
+      const path = field(attachment, pathKey) === undefined ? stringField(attachment, 'displayPath') : stringField(attachment, pathKey);
+      if (body != null) text = `[${label}: ${path ?? ''}]\n${body}`;
+    }
+  }
+  if (text == null || nativeTrim(text) === '') return;
+  const message = createMessage('user', text); message.metadata.attachmentType = kind;
+  const mode = stringField(attachment, 'commandMode'); if (mode != null) message.metadata.commandMode = mode;
+  out.push(message);
+}
+
+export function captureClaudeProvenance(value, messages, from = 0) {
+  const facts = [['timestamp', stringField(value, 'timestamp')], ['claude_uuid', stringField(value, 'uuid')], ['model', stringField(field(value, 'message'), 'model')]];
+  for (let index = from; index < messages.length; index++) for (const [key, fact] of facts) {
+    if (fact != null && !Object.hasOwn(messages[index].metadata, key)) messages[index].metadata[key] = fact;
+  }
+  if (messages.length - from === 1) restoreGrokMessageExtension(value, messages[from]);
+}
+
+export function mergeClaudeAssistantChunk(target, chunk) {
+  if (field(target, 'message') === undefined || field(chunk, 'message') === undefined) return;
+  const previous = field(target.message, 'content'), next = field(chunk.message, 'content');
+  const content = Array.isArray(previous) ? cloneNativeJson(previous) : [];
+  if (Array.isArray(next)) for (const block of next) content.push(cloneNativeJson(block));
+  target.message = cloneNativeJson(chunk.message);
+  target.message.content = content;
+}
+
+export function flushClaudeAssistant(value, messages) {
+  if (value == null) return;
+  const content = field(field(value, 'message'), 'content');
+  if (stringField(field(value, 'message'), 'id') != null && Array.isArray(content) && content.length > 0 && content.every((block) => ['thinking', 'redacted_thinking'].includes(stringField(block, 'type')))) return;
+  const from = messages.length; pushClaudeAssistant(value, messages); captureClaudeProvenance(value, messages, from);
+}
+
+/** Preserve every result, relocating only those with a recorded assistant
+ * owner; orphan results keep their position relative to the remaining spine. */
+export function reorderClaudeToolResults(messages) {
+  const owners = new Map();
+  messages.forEach((message, index) => {
+    if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '' && !owners.has(call.id)) owners.set(call.id, index);
+  });
+  let contiguous = null;
+  const needed = messages.some((message, index) => {
+    if (message.role === 'assistant') { contiguous = index; return false; }
+    const owner = message.role === 'tool' ? owners.get(message.tool_call_id) : undefined;
+    if (owner !== undefined) return owner !== contiguous;
+    contiguous = null; return false;
+  });
+  if (!needed) return;
+  const spine = [], results = [], positions = new Map(), buckets = new Map();
+  for (const message of messages) {
+    if (message.role === 'tool' && message.tool_call_id != null && message.tool_call_id !== '' && owners.has(message.tool_call_id)) { results.push(message); continue; }
+    if (message.role === 'assistant') for (const call of message.tool_calls ?? []) if (call.id !== '' && !positions.has(call.id)) positions.set(call.id, spine.length);
+    spine.push(message);
+  }
+  for (const message of results) {
+    const position = positions.get(message.tool_call_id);
+    if (!buckets.has(position)) buckets.set(position, []);
+    buckets.get(position).push(message);
+  }
+  messages.length = 0;
+  spine.forEach((message, index) => { messages.push(message); for (const result of buckets.get(index) ?? []) messages.push(result); });
+}

package/session-claude-files.mjs

@@ -0,0 +1,78 @@
+import { readdir } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+import { withSessionFile } from './file-io.mjs';
+import { sourceStat } from './store-registry.mjs';
+import { decodeSessionUtf8, readSessionText } from './session-file.mjs';
+import { parseNativeJson, stringifyNativeJson } from './native-json.mjs';
+import { fromClaudeCodeStr } from './session-claude.mjs';
+import { nonEmptyLines } from './session-lines.mjs';
+import { field, stringField } from './session-codec-utils.mjs';
+
+function firstAgentId(text) {
+  for (const line of nonEmptyLines(text)) {
+    let value; try { value = parseNativeJson(line); } catch { continue; }
+    const id = stringField(value, 'agentId'); if (id != null) return id;
+  }
+  return null;
+}
+
+function parentToolUseIndex(text, ids) {
+  const result = new Map();
+  if (!ids.length) return result;
+  for (const line of nonEmptyLines(text)) {
+    if (result.size === ids.length) break;
+    if (!line.includes('tool_result')) continue;
+    const missing = ids.filter((id) => !result.has(id));
+    if (!missing.length) break;
+    let value; try { value = parseNativeJson(line); } catch { continue; }
+    const blocks = field(field(value, 'message'), 'content');
+    if (!Array.isArray(blocks)) continue;
+    for (const block of blocks) {
+      if (stringField(block, 'type') !== 'tool_result') continue;
+      const tool = stringField(block, 'tool_use_id'); if (tool == null) continue;
+      const encoded = stringifyNativeJson(block);
+      for (const id of missing) if (!result.has(id) && line.includes(id) && encoded.includes(id)) result.set(id, tool);
+    }
+  }
+  return result;
+}
+
+export async function attachClaudeSubagents(session, mainPath, mainText, fidelity, metrics) {
+  const name = basename(mainPath), extension = extname(name), stem = name.slice(0, name.length - extension.length);
+  const directory = join(dirname(mainPath), stem, 'subagents');
+  if (!(await sourceStat(directory))?.isDirectory()) return;
+  let entries;
+  try { entries = await readdir(directory); }
+  catch (error) { throw new Error(`failed to enumerate Claude subagents at ${directory}: ${error.message}`, { cause: error }); }
+  const files = entries.filter((name) => extname(name) === '.jsonl').map((name) => join(directory, name)).sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+  const collected = [];
+  for (const file of files) {
+    let text;
+    try { text = await readSessionText(file, metrics); }
+    catch (error) { throw new Error(`failed to read Claude subagent ${file}: ${error.message}`, { cause: error }); }
+    let child;
+    try { child = fromClaudeCodeStr(text, { fidelity }); }
+    catch (error) {
+      if (fidelity === 'semantic') { session.load_residue.push(`Claude subagent ${file} could not be reconstructed (${error.message}); it was omitted from this view`); continue; }
+      throw new Error(`failed to reconstruct Claude subagent ${file}: ${error.message}`, { cause: error });
+    }
+    const id = firstAgentId(text) ?? basename(file, '.jsonl').replace(/^(?:agent-)+/, '');
+    collected.push({ child, id });
+  }
+  const parents = parentToolUseIndex(mainText, collected.map(({ id }) => id));
+  for (const { child, id } of collected) {
+    child.meta.agent_id = id; child.meta.parent_tool_use_id = parents.get(id) ?? null;
+    session.subagents.push(child);
+  }
+}
+
+/** Main file and each child are read through verified identities. Child
+ * reconstruction can degrade only in a semantic view, never an export. */
+export async function readClaudeCodeFile(path, { fidelity = 'byte_lossless', metrics } = {}) {
+  return withSessionFile(path, async (reader) => {
+    const text = decodeSessionUtf8(await reader.read(0, reader.size));
+    const session = fromClaudeCodeStr(text, { fidelity });
+    await attachClaudeSubagents(session, path, text, fidelity, metrics);
+    return session;
+  }, metrics);
+}

package/session-claude-graph.mjs

@@ -0,0 +1,285 @@
+import { field, stringField } from './session-codec-utils.mjs';
+
+const conversation = (node) => node.kind === 'user' || node.kind === 'assistant';
+const kinds = new Set(['user', 'assistant', 'attachment', 'system']);
+export function claudeReplayError(message) {
+  return Object.assign(new Error(`cannot reconstruct lossless Claude continuation: ${message}`), { code: 'invalid_session' });
+}
+
+function compactBoundary(value) {
+  const metadata = field(value, 'compactMetadata');
+  const messages = field(metadata, 'preservedMessages'), segment = field(metadata, 'preservedSegment');
+  const head = stringField(segment, 'headUuid'), tail = stringField(segment, 'tailUuid');
+  const uuids = field(messages, 'uuids');
+  return {
+    anchor: stringField(messages, 'anchorUuid') ?? stringField(segment, 'anchorUuid'),
+    preserved: Array.isArray(uuids) ? uuids.filter((uuid) => typeof uuid === 'string') : [],
+    segment: head != null && tail != null ? [head, tail] : null,
+  };
+}
+
+/** Claude's active branch and compaction projection. Semantic reads may name
+ * degraded segments; stricter continuation/export reads never guess a graph. */
+export class ClaudeReplayIndex {
+  nodes = [];
+  byUuid = new Map();
+  segmentAnchors = new Set();
+  lastPrompt = null;
+  linearLines = [];
+
+  clone() {
+    const graph = new ClaudeReplayIndex();
+    graph.nodes = this.nodes.map((node) => ({ ...node, compact: node.compact == null ? null : { ...node.compact,
+      preserved: [...node.compact.preserved], segment: node.compact.segment == null ? null : [...node.compact.segment] } }));
+    graph.byUuid = new Map(this.byUuid); graph.segmentAnchors = new Set(this.segmentAnchors);
+    graph.lastPrompt = this.lastPrompt == null ? null : [...this.lastPrompt]; graph.linearLines = [...this.linearLines];
+    return graph;
+  }
+
+  observe(lineIndex, value) {
+    const kind = stringField(value, 'type');
+    if (kind === 'last-prompt') {
+      const leaf = stringField(value, 'leafUuid');
+      if (leaf != null) this.lastPrompt = [leaf, field(value, 'explicit') === true];
+      return;
+    }
+    if (kind === 'fork-context-ref') {
+      const uuid = stringField(value, 'uuid');
+      if (uuid != null) this.segmentAnchors.add(uuid);
+      return;
+    }
+    if (!kinds.has(kind)) return;
+    this.linearLines.push(lineIndex);
+    const uuid = stringField(value, 'uuid');
+    if (uuid == null) return;
+    if (this.byUuid.has(uuid)) throw claudeReplayError(`duplicate uuid \`${uuid}\` in Claude transcript`);
+    const content = field(field(value, 'message'), 'content');
+    this.byUuid.set(uuid, this.nodes.length);
+    this.nodes.push({
+      lineIndex, uuid, kind, parent: stringField(value, 'parentUuid'),
+      sidechain: field(value, 'isSidechain') === true,
+      messageId: kind === 'assistant' ? stringField(field(value, 'message'), 'id') : null,
+      toolResult: kind === 'user' && Array.isArray(content) && content.some((block) => stringField(block, 'type') === 'tool_result'),
+      compact: kind === 'system' && stringField(value, 'subtype') === 'compact_boundary' ? compactBoundary(value) : null,
+    });
+  }
+
+  selectLines(fidelity) {
+    const lenient = fidelity === 'semantic', residue = [];
+    if (this.nodes.every((node) => !conversation(node))) return { lines: this.linearLines, residue };
+    if (lenient) this.#anchorDanglingParents(residue);
+    try { return { lines: this.#project(lenient, residue), residue }; }
+    catch (error) {
+      if (!lenient) throw error;
+      residue.push(`the Claude record graph could not be projected (${error.message}); every record was stitched in transcript order instead`);
+      return { lines: this.linearLines, residue };
+    }
+  }
+
+  #anchorDanglingParents(residue) {
+    const dangling = [];
+    for (const node of this.nodes) {
+      if (node.parent == null || this.byUuid.has(node.parent) || this.segmentAnchors.has(node.parent)) continue;
+      dangling.push(`\`${node.uuid}\` → \`${node.parent}\``);
+      node.parent = null;
+    }
+    if (dangling.length === 0) return;
+    const listed = dangling.slice(0, 8).join(', ') + (dangling.length > 8 ? `, and ${dangling.length - 8} more` : '');
+    residue.push(`${dangling.length} Claude record(s) reference a parentUuid absent from the transcript and were anchored as segment roots: ${listed}`);
+  }
+
+  #project(lenient, residue) {
+    const retained = this.nodes.map(() => true);
+    const boundary = this.nodes.findLastIndex((node) => node.compact != null);
+    if (boundary !== -1) {
+      const parents = lenient ? this.nodes.map((node) => node.parent) : null;
+      try { this.#applyCompaction(boundary, retained); }
+      catch (error) {
+        if (!lenient) throw error;
+        this.nodes.forEach((node, index) => { node.parent = parents[index]; });
+        retained.fill(true);
+        residue.push(`the latest Claude compact boundary could not be projected (${error.message}); no pre-compaction record was pruned from this view`);
+      }
+    }
+    const sidechainOnly = this.nodes.every((node, index) => !retained[index] || !conversation(node) || node.sidechain);
+    const explicit = this.lastPrompt?.[1] ? this.byUuid.get(this.lastPrompt[0]) : undefined;
+    const nonSidechain = this.nodes.findLastIndex((node, index) => retained[index] && !node.sidechain);
+    const sidechain = this.nodes.findLastIndex((node, index) => retained[index] && node.sidechain && conversation(node));
+    let active = explicit !== undefined && retained[explicit] ? explicit : nonSidechain !== -1 ? nonSidechain : sidechain;
+    if (active === -1) throw claudeReplayError('no Claude record remains after compaction');
+    const seeking = new Set();
+    while (!conversation(this.nodes[active])) {
+      if (seeking.has(active)) throw claudeReplayError('cycle while resolving active Claude leaf');
+      seeking.add(active);
+      active = this.#parentIndex(active, retained);
+    }
+    const children = new Map();
+    this.nodes.forEach((node, index) => {
+      if (node.parent == null) return;
+      if (!children.has(node.parent)) children.set(node.parent, []);
+      children.get(node.parent).push(index);
+    });
+    const segments = [this.#projectSegment(active, retained, sidechainOnly, lenient, children)];
+    if (lenient) {
+      for (const leaf of this.#severedLeaves(active, retained)) segments.push(this.#projectSegment(leaf, retained, sidechainOnly, lenient, children));
+      if (segments.length > 1) residue.push(`${segments.length} conversation segments were stitched in transcript order because the Claude record graph is severed`);
+    }
+    const firstLine = (segment) => segment.reduce((first, index) => Math.min(first, this.nodes[index].lineIndex), Infinity);
+    const ordered = [], placed = new Set();
+    for (const segment of segments.filter((part) => part.length > 0).sort((a, b) => firstLine(a) - firstLine(b))) {
+      for (const index of segment) {
+        if (placed.has(index)) continue;
+        placed.add(index);
+        ordered.push(index);
+      }
+    }
+    return this.#recoverChunks(ordered, retained).map((index) => this.nodes[index].lineIndex);
+  }
+
+  #projectSegment(leaf, retained, sidechainOnly, lenient, children) {
+    const reversed = [], seen = new Set();
+    let cursor = leaf;
+    while (cursor != null) {
+      if (seen.has(cursor)) throw claudeReplayError(`cycle in active Claude parentUuid chain at \`${this.nodes[cursor].uuid}\``);
+      seen.add(cursor);
+      reversed.push(cursor);
+      const node = this.nodes[cursor];
+      if (node.parent == null) cursor = null;
+      else if (this.byUuid.has(node.parent)) cursor = this.byUuid.get(node.parent);
+      else if (this.segmentAnchors.has(node.parent) || sidechainOnly) cursor = null;
+      else throw claudeReplayError(`active Claude record \`${node.uuid}\` has missing parentUuid \`${node.parent}\``);
+      if (cursor != null && !retained[cursor]) {
+        if (lenient) break;
+        throw claudeReplayError(`active Claude chain crosses an excluded compaction record from \`${node.uuid}\``);
+      }
+    }
+    reversed.reverse();
+    const descendants = [], frontier = [leaf];
+    for (let head = 0; head < frontier.length; head++) {
+      const parent = this.nodes[frontier[head]].uuid;
+      for (const index of children.get(parent) ?? []) {
+        const node = this.nodes[index];
+        if (!retained[index] || conversation(node) || seen.has(index) || node.parent !== parent) continue;
+        seen.add(index);
+        descendants.push(index);
+        frontier.push(index);
+      }
+    }
+    descendants.sort((a, b) => this.nodes[a].lineIndex - this.nodes[b].lineIndex);
+    for (const index of descendants) reversed.push(index);
+    return reversed;
+  }
+
+  #componentRoot(index, retained, roots) {
+    const seen = new Set(), path = [];
+    let cursor = index, root;
+    for (;;) {
+      if (roots.has(cursor)) { root = roots.get(cursor); break; }
+      if (seen.has(cursor)) { root = null; break; }
+      seen.add(cursor);
+      path.push(cursor);
+      const parent = this.byUuid.get(this.nodes[cursor].parent);
+      if (parent === undefined || !retained[parent]) { root = cursor; break; }
+      cursor = parent;
+    }
+    for (const member of path) roots.set(member, root);
+    return root;
+  }
+
+  #severedLeaves(active, retained) {
+    const roots = new Map(), activeRoot = this.#componentRoot(active, retained, roots), newest = new Map();
+    for (let index = 0; index < this.nodes.length; index++) {
+      if (!retained[index] || !conversation(this.nodes[index])) continue;
+      const root = this.#componentRoot(index, retained, roots);
+      if (root == null || root === activeRoot) continue;
+      const previous = newest.get(root);
+      if (previous === undefined || this.nodes[index].lineIndex > this.nodes[previous].lineIndex) newest.set(root, index);
+    }
+    return [...newest].sort(([a], [b]) => a - b).map(([, index]) => index);
+  }
+
+  #applyCompaction(boundary, retained) {
+    const compact = this.nodes[boundary].compact;
+    const preserved = compact.preserved.length > 0 ? compact.preserved : compact.segment != null ? this.#preservedSegment(...compact.segment) : [];
+    const preservedSet = new Set(preserved), removed = new Set();
+    for (const uuid of preserved) {
+      if (!this.byUuid.has(uuid)) throw claudeReplayError(`latest compact boundary references missing preserved uuid \`${uuid}\``);
+    }
+    for (let index = 0; index < boundary; index++) {
+      if (preservedSet.has(this.nodes[index].uuid)) continue;
+      removed.add(this.nodes[index].uuid);
+      retained[index] = false;
+    }
+    if (preserved.length === 0) return;
+    if (compact.anchor == null) throw claudeReplayError('preserved compact boundary is missing anchorUuid');
+    if (!this.byUuid.has(compact.anchor)) throw claudeReplayError(`latest compact boundary references missing anchor uuid \`${compact.anchor}\``);
+    const tail = preserved.at(-1);
+    let parent = compact.anchor;
+    for (const uuid of preserved) {
+      this.nodes[this.byUuid.get(uuid)].parent = parent;
+      parent = uuid;
+    }
+    for (const node of this.nodes) {
+      if (node.parent === compact.anchor && node.uuid !== preserved[0]) node.parent = tail;
+    }
+    for (const node of this.nodes) {
+      if (conversation(node) && removed.has(node.parent)) node.parent = tail;
+    }
+  }
+
+  #preservedSegment(head, tail) {
+    const reversed = [], seen = new Set();
+    let cursor = tail;
+    for (;;) {
+      if (seen.has(cursor)) throw claudeReplayError('cycle in compact preservedSegment');
+      seen.add(cursor);
+      const index = this.byUuid.get(cursor);
+      if (index === undefined) throw claudeReplayError(`compact preservedSegment references missing uuid \`${cursor}\``);
+      reversed.push(cursor);
+      if (cursor === head) return reversed.reverse();
+      const parent = this.nodes[index].parent;
+      if (parent == null) throw claudeReplayError(`compact preservedSegment tail \`${tail}\` does not reach head \`${head}\``);
+      cursor = parent;
+    }
+  }
+
+  #parentIndex(index, retained) {
+    const node = this.nodes[index];
+    if (node.parent == null) throw claudeReplayError(`Claude record \`${node.uuid}\` has no conversational ancestor`);
+    const parent = this.byUuid.get(node.parent);
+    if (parent === undefined) throw claudeReplayError(`Claude record \`${node.uuid}\` has missing parentUuid \`${node.parent}\``);
+    if (!retained[parent]) throw claudeReplayError(`Claude record \`${node.uuid}\` points into compacted-out history`);
+    return parent;
+  }
+
+  #recoverChunks(base, retained) {
+    const selected = new Set(base), replacements = new Map(), skipped = new Set(), groups = new Map();
+    base.forEach((index, position) => {
+      const id = this.nodes[index].messageId;
+      if (id == null) return;
+      if (!groups.has(id)) groups.set(id, { positions: [], chunks: [], results: [] });
+      groups.get(id).positions.push(position);
+    });
+    this.nodes.forEach((node, index) => {
+      const group = groups.get(node.messageId);
+      if (group && retained[index]) group.chunks.push(index);
+      if (!retained[index] || selected.has(index) || !node.toolResult) return;
+      const parent = this.byUuid.get(node.parent);
+      if (parent === undefined) return;
+      groups.get(this.nodes[parent].messageId)?.results.push(index);
+    });
+    for (const { positions, chunks, results } of groups.values()) {
+      for (const offset of positions.slice(1)) skipped.add(offset);
+      const byLine = (a, b) => this.nodes[a].lineIndex - this.nodes[b].lineIndex;
+      chunks.sort(byLine);
+      for (const result of results.sort(byLine)) chunks.push(result);
+      replacements.set(positions[0], chunks);
+    }
+    const result = [];
+    base.forEach((index, position) => {
+      if (replacements.has(position)) { for (const replacement of replacements.get(position)) result.push(replacement); }
+      else if (!skipped.has(position)) result.push(index);
+    });
+    return result;
+  }
+}