@playola-radio/slipstream 0.1.0

package/dist/swift-parse.js

@@ -0,0 +1,134 @@
+/**
+ * Runner + corpus helpers for the Swift-parse feasibility harness. Everything
+ * that must load the grammar goes through `runSwiftParseChild`, which spawns the
+ * isolated `--liftoff-only` host (src/swift-parse-host.ts), so the calling
+ * process (checker, test runner, acceptance) never loads Swift itself and can
+ * never be aborted by the OOM. The runner owns the child's deadline, abort
+ * wiring, and abnormal-exit reporting.
+ */
+import { spawn } from 'node:child_process';
+import { siblingModuleUrl } from "./sibling-module.js";
+import { readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { SWIFT_UNISOLATED_ENV } from "./swift-grammar.js";
+import { emitProjectionPhase, emitProjectionTrace, traceProcessId } from "./projection-trace.js";
+export const SWIFT_CORPUS_DIR = fileURLToPath(new URL('../contracts/swift-syntax/v1/', import.meta.url));
+const HOST_PATH = fileURLToPath(siblingModuleUrl('swift-parse-host', import.meta.url));
+const CASE_NAME = /^[a-z0-9][a-z0-9-]*$/;
+export class SwiftFixtureError extends Error {
+}
+export function swiftFixturePath(name, file = 'input.swift') {
+    if (!CASE_NAME.test(name))
+        throw new SwiftFixtureError(`invalid fixture name '${name}'`);
+    return join(SWIFT_CORPUS_DIR, name, file);
+}
+export async function listSwiftFixtures() {
+    const entries = await readdir(SWIFT_CORPUS_DIR, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory() && CASE_NAME.test(e.name)).map((e) => e.name).sort();
+}
+/** A child that exited abnormally (non-zero, killed by the deadline, or aborted).
+ * Carries the exit code/signal and captured stderr for an honest report. */
+export class SwiftChildError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'SwiftChildError';
+        this.detail = detail;
+    }
+}
+const DEFAULT_DEADLINE_MS = 30_000;
+/** Spawn the isolated host, feed it `request` on stdin, and resolve with its one
+ * JSON result. Rejects with SwiftChildError on any abnormal exit. */
+export async function runSwiftParseChild(request, opts = {}) {
+    return runSwiftHost([], JSON.stringify(request), opts);
+}
+/** Parse a named file in the isolated host. The checker passes only the path,
+ * so it never builds a second full source string or JSON copy in its process. */
+export async function runSwiftParseFile(path, opts = {}) {
+    return runSwiftHost(['--parse-file', path], '', opts);
+}
+/** Forward stdin bytes directly to the isolated host. This keeps the checker's
+ * one input buffer out of JSON serialization and decoding. */
+export async function runSwiftParseStdin(source, opts = {}) {
+    return runSwiftHost(['--parse-stdin'], source, opts);
+}
+async function runSwiftHost(hostArgs, input, opts) {
+    // An already-aborted signal must never launch work (the abort listener below
+    // only fires on FUTURE aborts).
+    if (opts.signal?.aborted) {
+        throw new SwiftChildError('swift-parse child aborted before start', { code: null, signal: null, stderr: '' });
+    }
+    const deadlineMs = opts.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    const unisolated = opts.liftoffOnly === false;
+    const execArgv = unisolated ? [] : ['--liftoff-only'];
+    const env = unisolated ? { ...process.env, [SWIFT_UNISOLATED_ENV]: '1' } : process.env;
+    const startedAtNs = opts.trace ? process.hrtime.bigint() : undefined;
+    const child = spawn(process.execPath, [...execArgv, HOST_PATH, ...(opts.trace ? ['--fd5-trace-startup'] : []), ...hostArgs], { stdio: ['pipe', 'pipe', 'pipe'], env });
+    const processId = opts.trace ? traceProcessId() : undefined;
+    if (processId !== undefined) {
+        let spawned = false;
+        child.once('spawn', () => {
+            spawned = true;
+            emitProjectionTrace(opts.trace, { kind: 'process-start', processId, process: 'swift-child',
+                ...(opts.traceUnitId === undefined ? {} : { unitId: opts.traceUnitId }), atNs: process.hrtime.bigint() });
+            emitProjectionPhase(opts.trace, 'child-spawn', startedAtNs, { scope: 'swift', processId, unitId: opts.traceUnitId });
+        });
+        child.once('error', () => {
+            if (!spawned)
+                emitProjectionTrace(opts.trace, { kind: 'process-spawn-failed', processId,
+                    ...(opts.traceUnitId === undefined ? {} : { unitId: opts.traceUnitId }), atNs: process.hrtime.bigint() });
+        });
+        child.once('close', (code, signal) => {
+            if (spawned) {
+                emitProjectionPhase(opts.trace, 'child-lifecycle', startedAtNs, { scope: 'swift', processId, unitId: opts.traceUnitId });
+                emitProjectionTrace(opts.trace, { kind: 'process-exit', processId,
+                    code, signal, atNs: process.hrtime.bigint() });
+            }
+        });
+    }
+    let stdout = '';
+    let stderr = '';
+    let startupObserved = false;
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (d) => {
+        stdout += d;
+        if (!startupObserved && processId !== undefined && stdout.includes('FD5_CHILD_READY\n')) {
+            startupObserved = true;
+            emitProjectionPhase(opts.trace, 'child-startup', startedAtNs, { scope: 'swift', processId, unitId: opts.traceUnitId });
+        }
+    });
+    child.stderr.on('data', (d) => { stderr += d; });
+    // Terminating the child while its stdin still holds buffered input emits EPIPE
+    // on the write side; swallow it so a cancellation never escapes the
+    // SwiftChildError contract as an uncaught error. The real cause is reported
+    // from the close/deadline path below.
+    child.stdin.on('error', () => { });
+    const timer = setTimeout(() => { killed = 'deadline'; child.kill('SIGKILL'); }, deadlineMs);
+    let killed = null;
+    const onAbort = () => { killed = 'abort'; child.kill('SIGKILL'); };
+    opts.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        child.stdin.end(input);
+        const [code, signal] = await new Promise((resolve, reject) => {
+            child.on('error', reject);
+            child.on('close', (c, s) => resolve([c, s]));
+        });
+        if (killed === 'deadline')
+            throw new SwiftChildError(`swift-parse child exceeded ${deadlineMs}ms deadline`, { code, signal, stderr });
+        if (killed === 'abort')
+            throw new SwiftChildError('swift-parse child aborted by signal', { code, signal, stderr });
+        if (code !== 0 || signal !== null) {
+            throw new SwiftChildError(`swift-parse child exited abnormally (code=${code}, signal=${signal})`, { code, signal, stderr });
+        }
+        const line = stdout.trimEnd().split('\n').at(-1) ?? '';
+        if (!line)
+            throw new SwiftChildError('swift-parse child produced no result line', { code, signal, stderr });
+        return JSON.parse(line);
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', onAbort);
+    }
+}

package/dist/swift-spans.js

@@ -0,0 +1,62 @@
+/**
+ * web-tree-sitter, given a JS string, reports node `startIndex`/`endIndex` in
+ * UTF-16 code units — not UTF-8 bytes. The interface contract (STAGE-T-PREREQS
+ * D10) requires whole-declaration spans as UTF-8-byte, half-open ranges, so
+ * every parser index must be converted. This module owns that conversion and
+ * nothing else: it never touches the WASM runtime, so it is verified by fast
+ * pure unit tests whose expected byte offsets are hand-derived from the UTF-8
+ * encoding rules, independent of the code here.
+ */
+/** Thrown when a UTF-16 index falls between the two units of a surrogate pair —
+ * i.e. inside a single astral code point, where there is no UTF-8 byte boundary.
+ * Parser node boundaries never land there; if one does, that is a defect we
+ * surface loudly rather than silently rounding to a neighbouring byte. */
+export class SurrogateBoundaryError extends Error {
+}
+/** Build the conversion table in a single code-point pass. */
+export function buildUtf16ToByteTable(source) {
+    const length = source.length; // UTF-16 code units
+    const bytes = new Uint32Array(length + 1);
+    const valid = new Uint8Array(length + 1).fill(1);
+    let byte = 0;
+    let i = 0;
+    while (i < length) {
+        bytes[i] = byte;
+        const code = source.charCodeAt(i);
+        const low = i + 1 < length ? source.charCodeAt(i + 1) : 0;
+        if (code >= 0xd800 && code <= 0xdbff && low >= 0xdc00 && low <= 0xdfff) {
+            // Astral code point: two UTF-16 units, four UTF-8 bytes. The boundary
+            // between the two units (index i+1) is inside the code point — no byte.
+            valid[i + 1] = 0;
+            bytes[i + 1] = byte;
+            byte += 4;
+            i += 2;
+        }
+        else {
+            // Single UTF-16 unit (BMP scalar, or a lone surrogate). A lone surrogate
+            // cannot be UTF-8-encoded; fatal UTF-8 decoding upstream rejects such
+            // input before it reaches here, so we size it as a 3-byte BMP scalar.
+            byte += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : 3;
+            i += 1;
+        }
+    }
+    bytes[length] = byte;
+    return { bytes, valid, length };
+}
+/** Convert one UTF-16 code-unit index to its UTF-8 byte offset. */
+export function utf16IndexToByte(table, index) {
+    if (index < 0 || index > table.length) {
+        throw new RangeError(`UTF-16 index ${index} out of range [0, ${table.length}]`);
+    }
+    if (table.valid[index] === 0) {
+        throw new SurrogateBoundaryError(`UTF-16 index ${index} falls inside a surrogate pair`);
+    }
+    return table.bytes[index];
+}
+/** Convert a half-open UTF-16 range to a half-open UTF-8 byte range. */
+export function utf16RangeToByteRange(table, startIndex, endIndex) {
+    return {
+        byteStart: utf16IndexToByte(table, startIndex),
+        byteEnd: utf16IndexToByte(table, endIndex),
+    };
+}

package/dist/task-forwarder.js

@@ -0,0 +1,152 @@
+/**
+ * begin_task orchestration for the MCP forwarder.
+ *
+ * The forwarder is a control client that emits exactly one mutation — begin_task —
+ * and must never lie to the agent about whether it committed. Two rules from the
+ * locked design (Codex consult) drive this file:
+ *
+ *  1. Post-send ambiguity is real. The control client throws {@link
+ *     OutcomeUnknownError} when a request reached the wire but its outcome is
+ *     unknowable. Because `session.beginTask` idempotency is durable and anchored
+ *     on `request_id` (the daemon rebuilds `committedTasks` from the log), we can
+ *     safely auto-resend the BYTE-IDENTICAL payload EXACTLY once — within one
+ *     capture session a same-UUID resend resolves idempotently, never double-
+ *     committing. Only a begin_task with a nonempty request_id qualifies (see
+ *     {@link shouldAutoResend}); a generic ambiguous request is never blindly
+ *     retried.
+ *
+ *     KNOWN LIMIT (at-least-once): the forwarder omits session_id (it never
+ *     attaches, so it cannot know the capture UUID), so idempotency is scoped to
+ *     the selected capture session. If the SAME identity triple is detached and
+ *     reattached between the first send and the resend, the resend lands in a NEW
+ *     capture session whose `committedTasks` does not yet hold this request_id,
+ *     and the task is recorded a second time (in the new session). The success we
+ *     then report is truthful — a task WAS declared — but the intent is recorded
+ *     twice across the two sessions. This is the accepted cost of the locked
+ *     at-least-once auto-resend; closing it needs store-level request_id dedup
+ *     (P3 idempotency scope), which is a design decision, not a forwarder fix.
+ *
+ *  2. When the resend cannot definitively resolve the first send, we must not
+ *     imply "nothing committed." A structurally-rejected resend (INVALID_TITLE /
+ *     IDENTITY_UNRESOLVED) proves nothing durable happened, so it replaces the
+ *     unknown honestly. A SESSION_NOT_SELECTED resend is reported as
+ *     selection-unavailable with the prior commit status explicitly UNKNOWN
+ *     (the daemon may have committed before it lost the session). Anything else
+ *     still ambiguous — a second OutcomeUnknown, or a transient daemon/storage
+ *     error — collapses to OUTCOME_UNKNOWN, which tells the agent NOT to
+ *     re-declare (a fresh declaration would be a new task, never a retry).
+ */
+import { randomUUID } from 'node:crypto';
+import { OutcomeUnknownError } from "./control-client.js";
+import { isResolved } from "./harness-context.js";
+/** Only a begin_task carrying a nonempty request_id is safe to auto-resend: the
+ * request_id is the durable idempotency key that makes an identical resend commit
+ * at most once. Any other verb, or a missing key, must never be blindly retried. */
+export function shouldAutoResend(envelope) {
+    return envelope.verb === 'begin_task' && typeof envelope.request_id === 'string' && envelope.request_id.length > 0;
+}
+function nonEmptyString(v) {
+    return typeof v === 'string' && v.length > 0;
+}
+/** A control ack proves a durable commit only if it carries all four task-commit
+ * identifiers. The control-client envelope validator accepts any `ok:true` shape,
+ * so an ack missing (or mistyping) these fields is NOT a confirmed commit — it is
+ * post-send ambiguity, handled exactly like an {@link OutcomeUnknownError}. */
+function isCommittedAck(res) {
+    return (res.ok === true &&
+        nonEmptyString(res.session_id) &&
+        nonEmptyString(res.task_id) &&
+        nonEmptyString(res.event_id) &&
+        nonEmptyString(res.seq));
+}
+function successResult(res) {
+    const structured = {
+        session_id: res.session_id,
+        task_id: res.task_id,
+        event_id: res.event_id,
+        seq: res.seq,
+    };
+    return {
+        text: `Task declared. session=${String(res.session_id)} task=${String(res.task_id)} seq=${String(res.seq)}`,
+        isError: false,
+        structured,
+    };
+}
+function errorResult(code, text, requestId) {
+    const structured = { code };
+    if (requestId !== undefined)
+        structured.request_id = requestId;
+    return { text, isError: true, structured };
+}
+function outcomeUnknown(requestId) {
+    return errorResult('OUTCOME_UNKNOWN', `OUTCOME_UNKNOWN: the declaration reached the daemon but its outcome could not be confirmed for request_id ${requestId}; do not re-declare — a fresh declaration would create a second task.`, requestId);
+}
+/** Map the RESEND response while resolving an earlier OutcomeUnknown. */
+function mapResendResponse(res, requestId) {
+    if (res.ok)
+        return isCommittedAck(res) ? successResult(res) : outcomeUnknown(requestId);
+    switch (res.code) {
+        case 'INVALID_TITLE':
+        case 'IDENTITY_UNRESOLVED':
+            // Structurally rejected — a durable commit was impossible either time, so
+            // this cleanly replaces the unknown.
+            return errorResult(res.code, `${res.code}: ${res.message}`, requestId);
+        case 'SESSION_NOT_SELECTED':
+            // The daemon may have committed on the first send before it lost selection;
+            // report selection-unavailable WITHOUT claiming "not committed".
+            return errorResult('SESSION_NOT_SELECTED', `SESSION_NOT_SELECTED: selection unavailable; prior commit status unknown for request_id ${requestId}`, requestId);
+        default:
+            // DAEMON_UNAVAILABLE / CAPTURE_NOT_READY / STORAGE_UNAVAILABLE / PROTOCOL:
+            // transient or ambiguous, and does not prove the first send failed to
+            // commit. Reporting the transient code would imply "safe to retry" — a lie.
+            return outcomeUnknown(requestId);
+    }
+}
+export async function forwardBeginTask(deps) {
+    if (!isResolved(deps.identity)) {
+        // Fail closed before any round trip: we cannot ship a verified triple.
+        return errorResult('IDENTITY_UNRESOLVED', `IDENTITY_UNRESOLVED: ${deps.identity.unresolved}`);
+    }
+    const requestId = deps.requestId ?? randomUUID();
+    // The optional session_id guard is intentionally omitted: the forwarder never
+    // attaches and so does not know the capture UUID, and carrying one forward from
+    // a prior task would wrongly reject a legitimate later task. Selection rests on
+    // the identity triple, which the daemon compares atomically.
+    const envelope = {
+        v: 1,
+        verb: 'begin_task',
+        title: deps.title,
+        request_id: requestId,
+        harness: deps.identity.harness,
+        harness_session_id: deps.identity.harness_session_id,
+        worktree: deps.identity.worktree,
+    };
+    try {
+        const res = await deps.send(envelope);
+        if (res.ok) {
+            // A well-formed commit ack is the only definitive success. A malformed
+            // `ok:true` proves nothing durable, so it falls through to the one resend
+            // exactly like a post-send OutcomeUnknown.
+            if (isCommittedAck(res))
+                return successResult(res);
+        }
+        else {
+            return errorResult(res.code, `${res.code}: ${res.message}`, requestId);
+        }
+    }
+    catch (err) {
+        if (!(err instanceof OutcomeUnknownError))
+            throw err;
+        // fall through to the single byte-identical resend
+    }
+    if (!shouldAutoResend(envelope))
+        return outcomeUnknown(requestId);
+    try {
+        return mapResendResponse(await deps.send(envelope), requestId);
+    }
+    catch (err) {
+        if (err instanceof OutcomeUnknownError)
+            return outcomeUnknown(requestId);
+        throw err;
+    }
+}

package/dist/transcript/claude.js

@@ -0,0 +1,199 @@
+import { isAbsolute } from 'node:path';
+import { scopeFromPaths } from "./types.js";
+/**
+ * Pure Claude Code transcript adapter.
+ *
+ * A Claude transcript is one JSON object per line. An `assistant` record carries
+ * `message.content[]` blocks; each `tool_use` block is one logical invocation
+ * whose native id is `tool_use.id` (`toolu_…`) — that id, namespaced by the
+ * harness session, is the evidence `record_id`. The tool RESULT arrives later as
+ * a `user` record with a `tool_result` block referencing `tool_use_id`; it
+ * carries no tool name or scope, so we remember the start's tool/scope and emit
+ * the end record under the SAME key/tool/scope (a time span for the invocation),
+ * never a provisional record we would later have to "correct".
+ *
+ * Tool taxonomy (A2 adapter knowledge): known write tools expose paths; known
+ * read-only tools emit nothing; everything else — Bash, unrecognized names —
+ * emits an explicit unknown scope (a possible writer we cannot map), because
+ * silently dropping an unknown effect would be dishonest.
+ */
+const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+// Deliberately excludes `Task`: a subagent it launches can edit files, so a Task
+// is a possible writer whose paths we cannot see — it must fall through to
+// unknown scope, not be silenced as read-only.
+const READONLY_TOOLS = new Set([
+    'Read',
+    'NotebookRead',
+    'Grep',
+    'Glob',
+    'LS',
+    'TodoWrite',
+    'WebFetch',
+    'WebSearch',
+    'BashOutput',
+    'KillShell',
+]);
+export function initialClaudeState() {
+    return { pending: new Map() };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function parseMs(record) {
+    const ts = record.timestamp;
+    if (typeof ts !== 'string')
+        return undefined;
+    const ms = Date.parse(ts);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/** The write path a known write tool declared, or undefined if it is missing. */
+function writePath(toolName, input) {
+    const field = toolName === 'NotebookEdit' ? 'notebook_path' : 'file_path';
+    const value = input[field];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function scopeForTool(toolName, input, ctx) {
+    if (READONLY_TOOLS.has(toolName))
+        return 'skip';
+    if (WRITE_TOOLS.has(toolName)) {
+        const path = isObject(input) ? writePath(toolName, input) : undefined;
+        if (path === undefined) {
+            return {
+                scope: { kind: 'unknown', reason: `${toolName} record declared no file path` },
+                diagnostics: [{ kind: 'malformed', detail: `${toolName} without a file path` }],
+            };
+        }
+        // Claude's write tools declare absolute paths by design. A relative path can
+        // only be resolved against the recorded cwd, which for a session's early
+        // records may still be provisional (bound to the root while the transcript was
+        // empty) or an alias of the root — resolving against it risks crediting the
+        // wrong file. Rather than guess, disclose it as an unmapped possible writer.
+        if (!isAbsolute(path)) {
+            return {
+                scope: { kind: 'unknown', reason: `${toolName} declared a non-absolute path` },
+                diagnostics: [],
+            };
+        }
+        const scope = scopeFromPaths([path], ctx);
+        // A write outside the capture root is out of scope for this session.
+        if (!scope)
+            return 'skip';
+        return { scope, diagnostics: [] };
+    }
+    // Bash or an unrecognized tool: a possible writer we cannot scope.
+    return {
+        scope: { kind: 'unknown', reason: `unmapped tool ${toolName}` },
+        diagnostics: [],
+    };
+}
+function makeEvidence(ctx, harnessSessionId, recordId, toolName, scope, atMs, basis) {
+    return {
+        evidence_key: {
+            harness: ctx.harness,
+            harness_session_id: harnessSessionId,
+            record_id: recordId,
+        },
+        adapter_version: ctx.adapterVersion,
+        tool_name: toolName,
+        timestamp: { at_ms: atMs, basis },
+        file_scope: scope,
+    };
+}
+function stepAssistant(state, record, ctx) {
+    const evidence = [];
+    const diagnostics = [];
+    const message = record.message;
+    const content = isObject(message) ? message.content : undefined;
+    if (!Array.isArray(content)) {
+        // Every Claude assistant record carries a `message.content` array of blocks.
+        // Anything else — a string, a null/absent message, a missing content — is a
+        // malformed envelope, not a clean read: disclose it so coverage degrades and
+        // stays distinct from a successfully-read record with no tool evidence. (User
+        // records, whose content is legitimately a string, are handled separately.)
+        diagnostics.push({ kind: 'malformed', detail: 'assistant record has no content block array' });
+        return { state, evidence, diagnostics };
+    }
+    const atMs = parseMs(record);
+    // The harness session is the record's own `sessionId` (the native session), so
+    // a copied/renamed transcript keeps one identity instead of splitting into
+    // filename-derived candidates; the bound file name is only a fallback.
+    const rawSession = record.sessionId;
+    const sessionId = typeof rawSession === 'string' && rawSession.length > 0 ? rawSession : ctx.harnessSessionId;
+    for (const block of content) {
+        if (!isObject(block) || block.type !== 'tool_use')
+            continue;
+        const id = block.id;
+        const toolName = block.name;
+        // A missing/empty invocation id is not a stable identity we can key: report it
+        // unsupported (never a fabricated or empty key that would collide).
+        if (typeof id !== 'string' || id.length === 0) {
+            diagnostics.push({ kind: 'unsupported', detail: 'tool_use without a stable id' });
+            continue;
+        }
+        if (typeof toolName !== 'string' || toolName.length === 0) {
+            diagnostics.push({ kind: 'malformed', detail: `tool_use ${id} without a tool name` });
+            continue;
+        }
+        const resolved = scopeForTool(toolName, block.input, ctx);
+        if (resolved === 'skip')
+            continue;
+        diagnostics.push(...resolved.diagnostics);
+        if (atMs === undefined) {
+            diagnostics.push({ kind: 'malformed', detail: `tool_use ${id} has no usable timestamp` });
+            continue;
+        }
+        state.pending.set(id, { sessionId, toolName, scope: resolved.scope });
+        evidence.push(makeEvidence(ctx, sessionId, id, toolName, resolved.scope, atMs, 'tool-start'));
+    }
+    return { state, evidence, diagnostics };
+}
+function stepUser(state, record, ctx) {
+    const evidence = [];
+    const diagnostics = [];
+    const message = record.message;
+    if (!isObject(message)) {
+        diagnostics.push({ kind: 'malformed', detail: 'user record has no message object' });
+        return { state, evidence, diagnostics };
+    }
+    const content = message.content;
+    // A user record legitimately carries plain string content (typed text) with no
+    // tool results to fold; that is a clean read, not a malformed one.
+    if (typeof content === 'string')
+        return { state, evidence, diagnostics };
+    if (!Array.isArray(content)) {
+        diagnostics.push({ kind: 'malformed', detail: 'user record content is neither text nor a block array' });
+        return { state, evidence, diagnostics };
+    }
+    const atMs = parseMs(record);
+    for (const block of content) {
+        if (!isObject(block) || block.type !== 'tool_result')
+            continue;
+        const id = block.tool_use_id;
+        if (typeof id !== 'string')
+            continue;
+        const memo = state.pending.get(id);
+        // An orphan result (start never seen) carries no tool/scope to emit honestly;
+        // the start, if it is ever read, records the invocation on its own.
+        if (!memo)
+            continue;
+        // A matched result with an unusable timestamp is a malformed record, not a clean
+        // read: disclose it (as the start side does) rather than silently drop the endpoint.
+        if (atMs === undefined) {
+            diagnostics.push({ kind: 'malformed', detail: `tool_result ${id} has no usable timestamp` });
+            continue;
+        }
+        evidence.push(makeEvidence(ctx, memo.sessionId, id, memo.toolName, memo.scope, atMs, 'tool-end'));
+    }
+    return { state, evidence, diagnostics };
+}
+/** Fold one parsed Claude transcript record into the running adapter state. */
+export function claudeStep(state, record, ctx) {
+    if (!isObject(record)) {
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: 'record is not an object' }] };
+    }
+    if (record.type === 'assistant')
+        return stepAssistant(state, record, ctx);
+    if (record.type === 'user')
+        return stepUser(state, record, ctx);
+    return { state, evidence: [], diagnostics: [] };
+}