@nanobpm/agentic 0.6.0 → 0.8.0

package/src/cockpit/terminal-session.ts

@@ -19,9 +19,25 @@
  *  - inbound  `{ op: "subscribed", stream, gap, nextOffset }` — the resume ack
  *             (`gap: boolean` — the S5 wire flags whether chunks aged out),
  *  - inbound  {@link RelayPayload} `{ stream, offset, chunk }` — a data chunk.
+ *
+ * ## Structured (ACP) vs. raw streams
+ *
+ * A relay stream is either a **raw** byte stream (PTY output — arbitrary bytes) or
+ * a **structured** ACP stream whose chunks are {@link TRANSCRIPT_EVENT_MARKER}-tagged
+ * JSON envelopes (the transcript-event vocabulary) riding the *same*
+ * `{ stream, offset, chunk }` frames. The session classifies **each chunk** through
+ * the one canonical {@link parseTranscriptEvent} — detection is on the marker tag,
+ * never a guess — and routes a decoded structured event to the {@link StructuredSink}
+ * (the derived structured renderer) while writing a raw chunk verbatim to the byte
+ * {@link TerminalSink}. A mixed stream that starts raw and only later carries tagged
+ * chunks is handled per-chunk, so each chunk lands on the right surface. Routing does
+ * not touch the resume machinery: `nextOffset` advances identically whichever surface
+ * a chunk is applied to, so resume-from-offset neither loses nor double-applies
+ * structured events across a reconnect exactly as for raw output.
  */
 import type { RelayPayload } from "../protocol/index.ts";
 import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.ts";
+import { type TranscriptEvent, parseTranscriptEvent } from "../transcript/index.ts";
 
 /** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
 export interface TerminalSink {
@@ -31,6 +47,20 @@ export interface TerminalSink {
   dispose?(): void;
 }
 
+/**
+ * The structured sink a session routes decoded transcript events to when the stream
+ * is a structured ACP stream (marker-tagged chunks). It receives the offset-keyed,
+ * immutable {@link TranscriptEvent} the one canonical {@link parseTranscriptEvent}
+ * derived from the chunk — never raw JSON — so the derived structured renderer folds
+ * over typed events rather than pretty-printing bytes.
+ */
+export interface StructuredSink {
+  /** Apply one decoded structured transcript event (in offset order). */
+  event(event: TranscriptEvent): void;
+  /** Tear down the underlying structured widget and its listeners, if any. */
+  dispose?(): void;
+}
+
 /** An outbound relay message the session asks its transport to send. */
 export type RelayOutbound =
   | { readonly op: "subscribe"; readonly stream: string; readonly from: number; readonly credit: number }
@@ -47,8 +77,15 @@ export type RelaySend = (message: RelayOutbound) => void;
 export interface TerminalSessionOptions {
   /** The relay stream id (one worker's terminal). */
   readonly stream: string;
-  /** Where decoded output is written. */
+  /** Where decoded raw output is written. */
   readonly sink: TerminalSink;
+  /**
+   * Where decoded structured transcript events are routed when the stream is a
+   * structured ACP stream (marker-tagged chunks). Omit for a pure byte-terminal:
+   * without it every chunk — even a marker-tagged one — is written verbatim to
+   * {@link sink}, preserving the legacy raw-only behaviour.
+   */
+  readonly structured?: StructuredSink;
   /** Emits outbound relay messages. */
   readonly send: RelaySend;
   /** Bulk credit requested on each (re)subscribe. Default 1024. */
@@ -73,6 +110,7 @@ function isRelayData(message: RelayInbound): message is RelayPayload {
 export class TerminalSession {
   readonly #stream: string;
   readonly #sink: TerminalSink;
+  readonly #structured: StructuredSink | undefined;
   readonly #send: RelaySend;
   readonly #credit: number;
   readonly #onGap: TerminalSessionOptions["onGap"];
@@ -84,6 +122,7 @@ export class TerminalSession {
   constructor(options: TerminalSessionOptions) {
     this.#stream = options.stream;
     this.#sink = options.sink;
+    this.#structured = options.structured;
     this.#send = options.send;
     this.#credit = options.credit ?? DEFAULT_CREDIT;
     if (!isPosInt(this.#credit)) {
@@ -152,19 +191,41 @@ export class TerminalSession {
     // Idempotent apply: a reconnect resubscribes from nextOffset, so the hub may
     // re-deliver the boundary chunk; anything we have already applied is dropped.
     if (data.offset < this.#nextOffset) return;
-    // Compute the next resume point BEFORE writing so the apply is atomic: a
+    // Compute the next resume point BEFORE applying so the apply is atomic: a
     // chunk at Number.MAX_SAFE_INTEGER makes addSafeInt throw, and it must throw
-    // before we touch the sink — otherwise the chunk is written but #nextOffset
+    // before we touch either sink — otherwise the chunk is applied but #nextOffset
     // is not advanced, leaving a partially-applied state that re-delivers (and
     // so duplicates) the chunk on reconnect. Advancing via addSafeInt also fails
     // fast rather than overflowing into an unsafe nextOffset — that value would
     // later be echoed in subscribe.from and lose precision on any JSON
     // round-trip, silently corrupting resume semantics.
     const nextOffset = addSafeInt(data.offset, 1, "nextOffset");
-    this.#sink.write(data.chunk);
+    this.#apply(data);
     this.#nextOffset = nextOffset;
   }
 
+  /**
+   * Route one already-de-duplicated data chunk to the right surface. Classify it
+   * through the ONE canonical {@link parseTranscriptEvent}: a marker-tagged, known
+   * envelope decodes to a typed event and (when a {@link StructuredSink} is wired)
+   * is routed there — the derived structured renderer — instead of dumping raw JSON
+   * into the byte-terminal; anything else (raw bytes, non-JSON, an untagged or
+   * malformed envelope) falls back to `stream-chunk` and is written verbatim to the
+   * byte {@link TerminalSink}, so a legacy/raw or mixed stream renders exactly as
+   * before. With no structured sink the parse is skipped entirely, keeping the
+   * raw-only path byte-identical to a pure byte-terminal.
+   */
+  #apply(data: RelayPayload): void {
+    if (this.#structured !== undefined) {
+      const event = parseTranscriptEvent({ offset: data.offset, chunk: data.chunk });
+      if (event.kind !== "stream-chunk") {
+        this.#structured.event(event);
+        return;
+      }
+    }
+    this.#sink.write(data.chunk);
+  }
+
   #onSubscribed(gap: boolean, nextOffset: number): void {
     // Validate the ack's resume point exactly as the constructor validates
     // `from`: `nextOffset` is echoed back into subscribe.from on the next

package/src/transcript/events.drift.test.ts

@@ -0,0 +1,68 @@
+// Drift-guard: exactly ONE parser of the transcript log (ADR 0056, #251).
+//
+// This enforces structurally — by scanning the package source — that the raw-chunk → typed-event
+// classification lives in exactly one module (`transcript/events.ts`), so a second, divergent parser of
+// the same bytes cannot creep in. The whole point of the event-sourced model is "the log IS the state":
+// every view derives from the one fold, none re-parses the bytes itself. A sibling cockpit task imports
+// the `TRANSCRIPT_EVENT_MARKER` IDENTIFIER (never the string literal), so this guard stays satisfied as
+// consumers grow.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TRANSCRIPT_EVENT_MARKER } from "./events.ts";
+
+const TRANSCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const SRC_DIR = dirname(TRANSCRIPT_DIR);
+
+/** Every non-test `.ts` source file under a directory, recursively. */
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...sourceFiles(path));
+    else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) out.push(path);
+  }
+  return out;
+}
+
+const PARSER_MODULE = join(TRANSCRIPT_DIR, "events.ts");
+const STORE_MODULE = join(TRANSCRIPT_DIR, "store.ts");
+
+test("the transcript-event marker literal is DEFINED in exactly one module (no second parser)", () => {
+  // Consumers reference the marker via the imported `TRANSCRIPT_EVENT_MARKER` identifier; only the ONE
+  // parser embeds the marker's string literal. A second module hardcoding it would be a second parser.
+  // Match every quote form (double, single, backtick) so a second parser can't bypass the guard by
+  // hardcoding the marker in a different literal style. Scan the WHOLE package src so no module anywhere
+  // (cockpit, protocol, …) can inline a private copy of the marker.
+  const quotedMarkerForms = ['"', "'", "`"].map((q) => `${q}${TRANSCRIPT_EVENT_MARKER}${q}`);
+  const owners = sourceFiles(SRC_DIR).filter((path) => {
+    const src = readFileSync(path, "utf8");
+    return quotedMarkerForms.some((literal) => src.includes(literal));
+  });
+  assert.deepEqual(
+    owners,
+    [PARSER_MODULE],
+    `the marker literal must be defined only in ${relative(SRC_DIR, PARSER_MODULE)}; found in: ${owners
+      .map((p) => relative(SRC_DIR, p))
+      .join(", ")}`,
+  );
+});
+
+test("no transcript consumer re-parses raw chunks — JSON.parse of the log lives only in the parser", () => {
+  // Every projection must fold through the single parser, never JSON.parse a chunk itself. Scan every
+  // non-test transcript module EXCEPT the parser (which owns the one JSON.parse) and the store (whose
+  // JSON handling is DB rows, not the log), and assert none of them contains a raw JSON.parse. Scanning
+  // the whole plane (not a name pattern) means a future consumer module is guarded the moment it is added.
+  const consumers = sourceFiles(TRANSCRIPT_DIR).filter(
+    (path) => path !== PARSER_MODULE && path !== STORE_MODULE,
+  );
+  for (const path of consumers) {
+    const src = readFileSync(path, "utf8");
+    assert.ok(
+      !src.includes("JSON.parse"),
+      `${relative(SRC_DIR, path)} must derive through parseTranscriptEvent, not re-parse the log itself`,
+    );
+  }
+});

package/src/transcript/events.test.ts

@@ -0,0 +1,308 @@
+// Unit tests for the typed transcript-event vocabulary + the single derive() fold (#251).
+//
+// Pins: the ONE parser classifies raw bytes vs typed envelopes (raw fidelity preserved), the core
+// vocabulary decodes each kind, merge-extensibility adds/overrides kinds without a second parser
+// (including the downstream `permission` extension point), encode↔parse round-trips, and deriveView
+// folds the log into per-turn structure / message history / tool cards / raw-byte accounting /
+// lifecycle — "the log IS the state".
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CORE_TRANSCRIPT_EVENT_KINDS,
+  CORE_TRANSCRIPT_VOCAB,
+  deriveView,
+  deriveViewFromChunks,
+  encodeTranscriptEvent,
+  mergeTranscriptVocab,
+  parseTranscriptEvent,
+  type TranscriptEvent,
+  type TranscriptVocab,
+  TRANSCRIPT_EVENT_MARKER,
+  TRANSCRIPT_EVENT_VERSION,
+  utf8ByteLength,
+} from "./events.ts";
+
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+test("marker + version constants are the canonical values (single source of truth)", () => {
+  assert.equal(TRANSCRIPT_EVENT_MARKER, "nwfTranscriptEvent");
+  assert.equal(TRANSCRIPT_EVENT_VERSION, 1);
+});
+
+test("utf8ByteLength counts UTF-8 bytes without depending on Buffer", () => {
+  assert.equal(utf8ByteLength("abc"), 3);
+  assert.equal(utf8ByteLength("é"), 2);
+  assert.equal(utf8ByteLength("😀"), 4);
+  assert.equal(utf8ByteLength(""), 0);
+});
+
+test("parseTranscriptEvent: raw terminal bytes are retained verbatim as a stream-chunk", () => {
+  const event = parseTranscriptEvent({ offset: 3, chunk: "\u001b[32mok\u001b[0m\r\n" });
+  assert.deepEqual(event, { kind: "stream-chunk", offset: 3, chunk: "\u001b[32mok\u001b[0m\r\n" });
+});
+
+test("parseTranscriptEvent: JSON without the marker is NOT mis-classified — stays a raw chunk", () => {
+  const chunk = JSON.stringify({ kind: "message", text: "hi" }); // no marker → raw
+  const event = parseTranscriptEvent({ offset: 0, chunk });
+  assert.equal(event.kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: a marker envelope with an unknown kind falls back to raw", () => {
+  const event = parseTranscriptEvent({ offset: 0, chunk: env("no-such-kind", { foo: 1 }) });
+  assert.equal(event.kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: malformed JSON carrying the marker text falls back to raw", () => {
+  const event = parseTranscriptEvent({ offset: 0, chunk: `{"${TRANSCRIPT_EVENT_MARKER}":1, broken` });
+  assert.equal(event.kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: a marker at the wrong version falls back to raw", () => {
+  const chunk = JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: 999, kind: "message", text: "hi" });
+  assert.equal(parseTranscriptEvent({ offset: 0, chunk }).kind, "stream-chunk");
+});
+
+test("parseTranscriptEvent: an inherited-property kind never resolves a prototype decoder", () => {
+  // A hostile chunk whose `kind` names an Object.prototype member ("constructor", "toString",
+  // "__proto__", …) must NOT resolve `vocab[kind]` up the prototype chain to a non-decoder
+  // function and call it — that either throws (DoS) or returns a non-TranscriptEvent value. The
+  // vocab is a plain map, so only OWN kinds decode; every prototype key falls back to raw.
+  for (const kind of ["constructor", "toString", "hasOwnProperty", "valueOf", "__proto__"]) {
+    const event = parseTranscriptEvent({ offset: 0, chunk: env(kind, { foo: 1 }) });
+    assert.equal(event.kind, "stream-chunk", `kind=${kind} must fall back to a raw stream-chunk`);
+  }
+});
+
+test("core vocab decodes message with role (default assistant)", () => {
+  assert.deepEqual(parseTranscriptEvent({ offset: 1, chunk: env("message", { text: "hello" }) }), {
+    kind: "message",
+    offset: 1,
+    role: "assistant",
+    text: "hello",
+  });
+  assert.deepEqual(parseTranscriptEvent({ offset: 2, chunk: env("message", { role: "user", text: "hi" }) }), {
+    kind: "message",
+    offset: 2,
+    role: "user",
+    text: "hi",
+  });
+});
+
+test("core vocab: a message envelope missing text is rejected → raw fallback", () => {
+  assert.equal(parseTranscriptEvent({ offset: 0, chunk: env("message", { role: "user" }) }).kind, "stream-chunk");
+});
+
+test("core vocab decodes tool-call / tool-result / turn / step / lifecycle", () => {
+  assert.deepEqual(parseTranscriptEvent({ offset: 1, chunk: env("tool-call", { name: "grep", callId: "c1", args: { q: "x" } }) }), {
+    kind: "tool-call",
+    offset: 1,
+    name: "grep",
+    callId: "c1",
+    args: { q: "x" },
+  });
+  assert.deepEqual(parseTranscriptEvent({ offset: 2, chunk: env("tool-result", { callId: "c1", ok: true, content: "found" }) }), {
+    kind: "tool-result",
+    offset: 2,
+    ok: true,
+    callId: "c1",
+    content: "found",
+  });
+  assert.deepEqual(parseTranscriptEvent({ offset: 3, chunk: env("turn", { index: 4 }) }), { kind: "turn", offset: 3, index: 4 });
+  assert.deepEqual(parseTranscriptEvent({ offset: 4, chunk: env("step", { label: "loop" }) }), { kind: "step", offset: 4, label: "loop" });
+  assert.deepEqual(parseTranscriptEvent({ offset: 5, chunk: env("lifecycle", { phase: "completed" }) }), {
+    kind: "lifecycle",
+    offset: 5,
+    phase: "completed",
+  });
+});
+
+test("mergeTranscriptVocab: adds a new kind without forking the parser, and can override a core one", () => {
+  const vocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    // A brand new merge-extensible kind, decoded into a message so deriveView still folds it.
+    reasoning: (body, offset) => ({ kind: "message", offset, role: "system", text: String(body.text ?? "") }),
+  });
+  const event = parseTranscriptEvent({ offset: 7, chunk: env("reasoning", { text: "thinking" }) }, vocab);
+  assert.deepEqual(event, { kind: "message", offset: 7, role: "system", text: "thinking" });
+  // The core vocab is unchanged (merge returns a new object).
+  assert.equal(parseTranscriptEvent({ offset: 7, chunk: env("reasoning", { text: "thinking" }) }).kind, "stream-chunk");
+});
+
+test("vocab maps are null-prototype so inherited keys never leak into `in` / Object.keys", () => {
+  // A prototype-bearing vocab (`Object.assign({}, …)`) makes `"toString" in vocab` true and surfaces
+  // inherited Object.prototype keys to any consumer doing `kind in vocab` / `Object.keys(vocab)`,
+  // classifying a hostile `kind` off the prototype chain. Both the core vocab AND every merge result
+  // must be null-prototype so only OWN kinds exist — this guards the whole class, not one bad key.
+  const merged = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    custom: (_body, offset) => ({ kind: "step", offset }),
+  });
+  const vocabs: readonly (readonly [string, TranscriptVocab])[] = [
+    ["core", CORE_TRANSCRIPT_VOCAB],
+    ["merged", merged],
+  ];
+  for (const [name, vocab] of vocabs) {
+    assert.equal(Object.getPrototypeOf(vocab), null, `${name} vocab must have a null prototype`);
+    for (const inherited of ["toString", "constructor", "hasOwnProperty", "valueOf", "__proto__"]) {
+      assert.equal(inherited in vocab, false, `${name} vocab must not expose inherited key ${inherited}`);
+    }
+  }
+});
+
+test("EXTENSION POINT: a downstream app registers its own `permission` kind via mergeTranscriptVocab", () => {
+  // Mirrors nano-workforce#559: an app adds a `permission` kind + parse handler WITHOUT editing this
+  // package. The synthetic extra kind is decoded (here into a message the core fold understands) and
+  // parses through the one parser; the core vocab stays untouched.
+  const appVocab: TranscriptVocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+    permission: (body, offset) => {
+      const requestId = typeof body.requestId === "string" ? body.requestId : undefined;
+      if (requestId === undefined) return undefined; // reject malformed → raw fallback
+      const granted = body.granted === true;
+      return { kind: "message", offset, role: "system", text: `permission(${requestId}):${granted ? "granted" : "denied"}` };
+    },
+  });
+
+  const granted = parseTranscriptEvent({ offset: 10, chunk: env("permission", { requestId: "req-1", granted: true }) }, appVocab);
+  assert.deepEqual(granted, { kind: "message", offset: 10, role: "system", text: "permission(req-1):granted" });
+
+  // A malformed extension envelope (missing requestId) still falls back to raw — no throw, no crash.
+  assert.equal(
+    parseTranscriptEvent({ offset: 11, chunk: env("permission", { granted: false }) }, appVocab).kind,
+    "stream-chunk",
+  );
+
+  // The package's core vocab never learned `permission` — the extension did not fork or mutate it.
+  assert.equal(parseTranscriptEvent({ offset: 10, chunk: env("permission", { requestId: "req-1", granted: true }) }).kind, "stream-chunk");
+  assert.equal(CORE_TRANSCRIPT_VOCAB.permission, undefined);
+});
+
+test("encodeTranscriptEvent round-trips every non-raw kind through the one parser", () => {
+  const events: TranscriptEvent[] = [
+    { kind: "message", offset: 0, role: "assistant", text: "hi" },
+    { kind: "tool-call", offset: 1, name: "ls", callId: "c1" },
+    { kind: "tool-result", offset: 2, ok: false, callId: "c1", content: "boom" },
+    { kind: "turn", offset: 3, index: 1 },
+    { kind: "step", offset: 4, label: "s" },
+    { kind: "lifecycle", offset: 5, phase: "exited" },
+  ];
+  for (const original of events) {
+    const chunk = encodeTranscriptEvent(original);
+    assert.deepEqual(parseTranscriptEvent({ offset: original.offset, chunk }), original);
+  }
+});
+
+test("encodeTranscriptEvent returns raw bytes verbatim for a stream-chunk", () => {
+  assert.equal(encodeTranscriptEvent({ kind: "stream-chunk", offset: 0, chunk: "raw" }), "raw");
+});
+
+test("deriveView: folds messages + tool cards into per-turn structure with lifecycle", () => {
+  const events: TranscriptEvent[] = [
+    { kind: "turn", offset: 0, index: 0 },
+    { kind: "message", offset: 1, role: "user", text: "do it" },
+    { kind: "step", offset: 2 },
+    { kind: "tool-call", offset: 3, name: "grep", callId: "c1" },
+    { kind: "tool-result", offset: 4, ok: true, callId: "c1", content: "hit" },
+    { kind: "message", offset: 5, role: "assistant", text: "done" },
+    { kind: "turn", offset: 6, index: 1 },
+    { kind: "message", offset: 7, role: "assistant", text: "next" },
+    { kind: "stream-chunk", offset: 8, chunk: "raw-bytes" },
+    { kind: "lifecycle", offset: 9, phase: "completed" },
+  ];
+  const view = deriveView(events);
+  assert.equal(view.turns.length, 2);
+  assert.deepEqual(view.turns[0]?.messages.map((m) => m.text), ["do it", "done"]);
+  assert.equal(view.turns[0]?.steps, 1);
+  assert.equal(view.turns[0]?.tools.length, 1);
+  assert.deepEqual(view.turns[0]?.tools[0]?.result, { ok: true, offset: 4, content: "hit" });
+  assert.deepEqual(view.turns[1]?.messages.map((m) => m.text), ["next"]);
+  assert.equal(view.messages.length, 3);
+  assert.equal(view.tools.length, 1);
+  assert.equal(view.lifecycle, "completed");
+  assert.equal(view.rawChunkCount, 1);
+  assert.equal(view.rawByteLength, utf8ByteLength("raw-bytes"));
+  assert.equal(view.eventCount, 10);
+});
+
+test("deriveView: content before any turn event opens an implicit turn 0", () => {
+  const view = deriveView([
+    { kind: "message", offset: 0, role: "assistant", text: "hello" },
+    { kind: "tool-call", offset: 1, name: "ls" },
+  ]);
+  assert.equal(view.turns.length, 1);
+  assert.equal(view.turns[0]?.index, 0);
+  assert.equal(view.turns[0]?.messages.length, 1);
+  assert.equal(view.turns[0]?.tools.length, 1);
+});
+
+test("deriveView: an anonymous tool-result pairs with the most recent open anonymous call", () => {
+  const view = deriveView([
+    { kind: "tool-call", offset: 0, name: "a" },
+    { kind: "tool-result", offset: 1, ok: false, content: "nope" },
+  ]);
+  assert.deepEqual(view.tools[0]?.result, { ok: false, offset: 1, content: "nope" });
+});
+
+test("deriveView: results pair into the correct turn's tool with interleaved, out-of-order calls across turns", () => {
+  // Two turns, each with two tools; results arrive interleaved and out of call order. Each result must
+  // land on its own call's card in BOTH the flat list and the owning turn — guarding the O(1) position
+  // tracking against pairing into the wrong turn/index.
+  const view = deriveView([
+    { kind: "turn", offset: 0, index: 0 },
+    { kind: "tool-call", offset: 1, name: "t0a", callId: "a" },
+    { kind: "tool-call", offset: 2, name: "t0b", callId: "b" },
+    { kind: "turn", offset: 3, index: 1 },
+    { kind: "tool-call", offset: 4, name: "t1c", callId: "c" },
+    { kind: "tool-call", offset: 5, name: "t1d", callId: "d" },
+    { kind: "tool-result", offset: 6, ok: true, callId: "c", content: "C" },
+    { kind: "tool-result", offset: 7, ok: false, callId: "a", content: "A" },
+    { kind: "tool-result", offset: 8, ok: true, callId: "d", content: "D" },
+    { kind: "tool-result", offset: 9, ok: false, callId: "b", content: "B" },
+  ]);
+  // Flat list keeps call order, each with its own result.
+  assert.deepEqual(
+    view.tools.map((t) => [t.name, t.result?.content]),
+    [["t0a", "A"], ["t0b", "B"], ["t1c", "C"], ["t1d", "D"]],
+  );
+  // Each result also lands on the matching card inside its OWN turn (not another turn's).
+  assert.deepEqual(
+    view.turns[0]?.tools.map((t) => [t.name, t.result?.ok]),
+    [["t0a", false], ["t0b", false]],
+  );
+  assert.deepEqual(
+    view.turns[1]?.tools.map((t) => [t.name, t.result?.ok]),
+    [["t1c", true], ["t1d", true]],
+  );
+});
+
+test("deriveViewFromChunks: an all-raw log derives no structure but full raw fidelity accounting", () => {
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: "line-1\n" },
+    { offset: 1, chunk: "line-2\n" },
+  ]);
+  assert.equal(view.turns.length, 0);
+  assert.equal(view.messages.length, 0);
+  assert.equal(view.rawChunkCount, 2);
+  assert.ok(view.rawByteLength > 0);
+});
+
+test("deriveViewFromChunks: a mixed log derives typed structure while retaining raw chunks", () => {
+  const view = deriveViewFromChunks([
+    { offset: 0, chunk: env("turn", { index: 0 }) },
+    { offset: 1, chunk: "\u001b[2Jraw frame" },
+    { offset: 2, chunk: env("message", { role: "assistant", text: "hi" }) },
+  ]);
+  assert.equal(view.turns.length, 1);
+  assert.deepEqual(view.messages.map((m) => m.text), ["hi"]);
+  assert.equal(view.rawChunkCount, 1);
+});
+
+test("ONE-PARSER guard: every declared core kind is handled by the single parseTranscriptEvent fold", () => {
+  // Port of the app-side drift guard: there is exactly one fold, and it decodes every core kind. If a
+  // kind were added to the union but not to CORE_TRANSCRIPT_VOCAB (or vice versa), this fails — no
+  // second parser and no undecoded kind can creep in.
+  const vocabKinds = Object.keys(CORE_TRANSCRIPT_VOCAB).sort();
+  assert.deepEqual(vocabKinds, [...CORE_TRANSCRIPT_EVENT_KINDS].sort());
+  for (const kind of CORE_TRANSCRIPT_EVENT_KINDS) {
+    assert.equal(typeof CORE_TRANSCRIPT_VOCAB[kind], "function", `core kind ${kind} must be handled by the one parser`);
+  }
+});