@nanobpm/agentic 0.6.0 → 0.8.0

package/README.md

@@ -13,7 +13,7 @@ The **Nano agentic protocol** (ADR 0056): one app-tier channel carrying agent pr
 | `@nanobpm/agentic/vocab` | Vocab resolver + core vocabulary (S3) |
 | `@nanobpm/agentic/demand` | Demand×supply model (S4) |
 | `@nanobpm/agentic/relay` | Relay ring + QoS scheduler (S5) |
-| `@nanobpm/agentic/transcript` | Transcript store, retention-by-lifecycle (S6) + turn-structured view (Camunda `AgentHistoryRecordValue` parity) |
+| `@nanobpm/agentic/transcript` | Transcript store, retention-by-lifecycle (S6) + turn-structured view (Camunda `AgentHistoryRecordValue` parity) + the typed transcript-event **vocabulary** & single `parseTranscriptEvent` fold |
 | `@nanobpm/agentic/blackboard` | Blackboard channel family (S7) |
 | `@nanobpm/agentic/cockpit` | Operator visibility page — the cockpit (S8) |
 | `@nanobpm/agentic/session` | Canonical `SessionEvent` + authoritative session log for durable agent-session resume (ADR 0062) |
@@ -21,3 +21,60 @@ The **Nano agentic protocol** (ADR 0056): one app-tier channel carrying agent pr
 The barrel `@nanobpm/agentic` re-exports each family as a namespace (`protocol`, `channel`, …). The worker-side client ships separately as `@nanobpm/urban-agent-client`.
 
 The wire contract is the single source of truth; nothing here rides the Camunda-8 engine or its transport.
+
+## Transcript event vocabulary (`@nanobpm/agentic/transcript`)
+
+The transcript subpath now ships the canonical typed transcript-event **vocabulary** alongside the S6
+store, so every Urban app derives ACP-rich transcripts from **one** parser instead of forking its own:
+
+```ts
+import {
+  parseTranscriptEvent,          // THE ONE PARSER: stored chunk → typed TranscriptEvent
+  deriveView,                    // THE ONE FOLD: typed events → per-turn structured view
+  deriveViewFromChunks,          // parse + fold in one call
+  mergeTranscriptVocab,          // additive EXTENSION POINT (register a new kind, never fork)
+  CORE_TRANSCRIPT_VOCAB,
+  encodeTranscriptEvent,
+  utf8ByteLength,                // browser-safe (TextEncoder, no Buffer)
+  TRANSCRIPT_EVENT_MARKER,       // "nwfTranscriptEvent" — canonical single source of truth
+  TRANSCRIPT_EVENT_VERSION,      // 1
+} from "@nanobpm/agentic/transcript";
+```
+
+The vocab/parser modules are **browser-safe** (no `Buffer`, no Node-only imports), so the cockpit derive
+runs in-browser. Kinds: `message`, `tool-call`, `tool-result`, `turn`, `step`, `lifecycle`, plus the
+raw `stream-chunk` fallback that preserves byte-level replay fidelity. A stored chunk is decoded as a
+structured event **only** when it is a JSON object carrying `TRANSCRIPT_EVENT_MARKER` at the current
+version — otherwise it is retained verbatim, so a raw ANSI frame that happens to be JSON is never
+mis-classified. `TRANSCRIPT_EVENT_MARKER` + `parseTranscriptEvent` are the canonical detection surface
+the whole package family (e.g. the cockpit's structured-stream drill-in) imports from here — never a
+private copy.
+
+### Extending the vocabulary (merge, don't fork)
+
+A downstream app adds its own kind + parse handler **without editing this package**:
+
+```ts
+const appVocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+  permission: (body, offset) =>
+    typeof body.requestId === "string"
+      ? { kind: "message", offset, role: "system", text: `permission(${body.requestId})` }
+      : undefined, // reject malformed → raw fallback
+});
+parseTranscriptEvent({ offset, chunk }, appVocab); // the one parser, now aware of `permission`
+```
+
+### Migration for nano-workforce
+
+`nano-workforce` currently forks this vocabulary at `app/agentic/transcript-events.ts`. To consume the
+shared copy:
+
+1. Replace imports of the local `./transcript-events.ts` with `@nanobpm/agentic/transcript`
+   (`parseTranscriptEvent`, `deriveView`, `mergeTranscriptVocab`, `TRANSCRIPT_EVENT_MARKER`,
+   `TRANSCRIPT_EVENT_VERSION`, `utf8ByteLength`, the event types, …). The public API — symbol names,
+   the `"nwfTranscriptEvent"` marker string, and version `1` — is preserved verbatim, so this is a
+   drop-in.
+2. Register nano-workforce's app-specific `permission` kind (nano-workforce#559) via
+   `mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, { permission: … })` instead of editing a forked parser.
+3. **Delete** `app/agentic/transcript-events.ts` (and fold its `transcript-events.drift.test.ts` marker
+   guard into the shared package's guard, already ported here as `events.drift.test.ts`).

package/dist/cockpit/boot.d.ts

@@ -20,9 +20,11 @@
 import type { DemandSupplyReport } from "../demand/index.ts";
 import { type Scheduler, type SocketFactory } from "./relay-client.ts";
 import { type DocumentLike, type ElementLike } from "./render.ts";
-import { type TerminalSink } from "./terminal-session.ts";
+import { type StructuredSink, type TerminalSink } from "./terminal-session.ts";
 /** Mounts a terminal into `host` and returns the sink relay output is written to. */
 export type CreateTerminal = (host: ElementLike) => TerminalSink;
+/** Mounts a structured (ACP) view into `host` and returns the sink decoded transcript events are routed to. */
+export type CreateStructured = (host: ElementLike) => StructuredSink;
 /** An opaque poll-timer handle (a Node `Timeout` or a browser timer id). */
 export type TimerHandle = unknown;
 export interface CockpitEnv {
@@ -36,6 +38,14 @@ export interface CockpitEnv {
     readonly connectRelay: SocketFactory;
     /** Mounts the terminal widget (xterm.js in the browser) and returns its write sink. */
     readonly createTerminal: CreateTerminal;
+    /**
+     * Mounts the structured (ACP) view widget and returns its event sink. Optional:
+     * when omitted the drill-in uses the built-in {@link createStructuredSink} DOM
+     * renderer over {@link doc}, so marker-tagged chunks are decoded and routed to
+     * that structured surface while raw bytes still flow to the {@link createTerminal}
+     * sink. Provide your own to override the built-in renderer.
+     */
+    readonly createStructured?: CreateStructured;
     /** Reconnect scheduler for the relay client. Default `setTimeout(run, 0)`. */
     readonly schedule?: Scheduler;
     /** Poll scheduler. Default `setTimeout`. Injected so tests drive it by hand. Must be paired with {@link clearTimer}. */

package/dist/cockpit/boot.js

@@ -1,6 +1,7 @@
 import { isPosInt } from "../relay/index.js";
 import { RelayChannelClient } from "./relay-client.js";
 import { renderCockpit } from "./render.js";
+import { createStructuredSink } from "./structured-view.js";
 import { TerminalSession } from "./terminal-session.js";
 import { cockpitView } from "./view.js";
 const DEFAULT_REFRESH_MS = 2000;
@@ -8,6 +9,8 @@ class Cockpit {
     #env;
     #matrixRegion;
     #terminalHost;
+    #structuredHost;
+    #createStructured;
     #refreshMs;
     #setTimer;
     #clearTimer;
@@ -20,6 +23,9 @@ class Cockpit {
     // The currently mounted terminal, tracked so switching streams (and dispose)
     // tears down the prior xterm instance instead of leaking it + its listeners.
     #terminal;
+    // The currently mounted structured view, torn down alongside #terminal so a
+    // stream switch / dispose never leaks the prior worker's structured widget.
+    #structured;
     // Bumped by every start()/stop() so an in-flight #tick() from a previous
     // start cycle can't reschedule after a stop→start race and leave two
     // overlapping poll chains running against the same cockpit.
@@ -64,6 +70,10 @@ class Cockpit {
                         this.#timeouts.delete(handle);
                     }
                 });
+        // The structured (ACP) view mounter defaults to the built-in DOM renderer over
+        // the injected document, so a structured stream derives + renders without any
+        // extra wiring; a browser caller may override it (e.g. a richer widget).
+        this.#createStructured = env.createStructured ?? ((host) => createStructuredSink(host, env.doc));
         // Build the stable skeleton once: a volatile matrix region the poll
         // re-renders, and a PERSISTENT terminal region a refresh never touches.
         env.host.replaceChildren();
@@ -81,6 +91,14 @@ class Cockpit {
         this.#terminalHost.className = "cockpit-terminal-host";
         this.#terminalHost.setAttribute("data-terminal", "host");
         terminalPanel.appendChild(this.#terminalHost);
+        // A sibling PERSISTENT region for the derived structured (ACP) view. A raw
+        // stream keeps it in its initial/empty structured state; a structured stream
+        // renders here instead of dumping JSON into the byte-terminal; a mixed stream
+        // feeds both.
+        this.#structuredHost = env.doc.createElement("div");
+        this.#structuredHost.className = "cockpit-structured-host";
+        this.#structuredHost.setAttribute("data-structured", "host");
+        terminalPanel.appendChild(this.#structuredHost);
         shell.appendChild(this.#matrixRegion);
         shell.appendChild(terminalPanel);
         env.host.appendChild(shell);
@@ -157,11 +175,17 @@ class Cockpit {
         // still cleans it up on the next drill or on dispose().
         this.#terminal?.dispose?.();
         this.#terminal = undefined;
+        // The structured view is torn down in lockstep with the terminal.
+        this.#structured?.dispose?.();
+        this.#structured = undefined;
         try {
-            // Fresh terminal for the newly selected worker.
+            // Fresh terminal + structured view for the newly selected worker.
             this.#terminalHost.replaceChildren();
             const sink = this.#env.createTerminal(this.#terminalHost);
             this.#terminal = sink;
+            this.#structuredHost.replaceChildren();
+            const structured = this.#createStructured(this.#structuredHost);
+            this.#structured = structured;
             let session;
             const client = new RelayChannelClient({
                 connect: this.#env.connectRelay,
@@ -175,6 +199,7 @@ class Cockpit {
             session = new TerminalSession({
                 stream,
                 sink,
+                structured,
                 send: (message) => client.sendRelay(message),
                 credit: this.#env.credit,
             });
@@ -194,6 +219,8 @@ class Cockpit {
         this.#drill = undefined;
         this.#terminal?.dispose?.();
         this.#terminal = undefined;
+        this.#structured?.dispose?.();
+        this.#structured = undefined;
     }
 }
 /** Boot the cockpit against an injected environment. Call {@link CockpitHandle.start} to poll. */

package/dist/cockpit/index.d.ts

@@ -21,7 +21,8 @@
  * Nothing here rides the Camunda-8 engine or its transport.
  */
 export { cockpitView, type CockpitLight, type CockpitNetworkRow, type CockpitTokenRow, type CockpitView, type SloStatus, } from "./view.ts";
-export { TerminalSession, type RelayInbound, type RelayOutbound, type RelaySend, type TerminalSessionOptions, type TerminalSink, } from "./terminal-session.ts";
+export { TerminalSession, type RelayInbound, type RelayOutbound, type RelaySend, type StructuredSink, type TerminalSessionOptions, type TerminalSink, } from "./terminal-session.ts";
 export { RelayChannelClient, type RawSocket, type RelayChannelClientOptions, type Scheduler, type SocketFactory, } from "./relay-client.ts";
 export { renderCockpit, type CockpitDom, type DocumentLike, type ElementLike, type RenderOptions, } from "./render.ts";
-export { bootCockpit, type CockpitEnv, type CockpitHandle, type CreateTerminal, type TimerHandle, } from "./boot.ts";
+export { createStructuredSink, renderStructured, type StructuredTerminal, } from "./structured-view.ts";
+export { bootCockpit, type CockpitEnv, type CockpitHandle, type CreateStructured, type CreateTerminal, type TimerHandle, } from "./boot.ts";

package/dist/cockpit/index.js

@@ -24,4 +24,5 @@ export { cockpitView, } from "./view.js";
 export { TerminalSession, } from "./terminal-session.js";
 export { RelayChannelClient, } from "./relay-client.js";
 export { renderCockpit, } from "./render.js";
+export { createStructuredSink, renderStructured, } from "./structured-view.js";
 export { bootCockpit, } from "./boot.js";

package/dist/cockpit/structured-view.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The cockpit's structured-stream renderer — S8's drill-in for an ACP stream.
+ *
+ * When a drilled worker's relay stream is a **structured** ACP stream (its chunks
+ * are {@link TRANSCRIPT_EVENT_MARKER}-tagged transcript-event envelopes rather than
+ * raw PTY bytes), the {@link TerminalSession} routes each decoded event here instead
+ * of the byte-terminal. This renderer does **not** re-parse or pretty-print JSON: it
+ * feeds the accumulated typed events straight through the ONE canonical
+ * {@link deriveView} fold from `@nanobpm/agentic/transcript` and renders the resulting
+ * {@link DerivedView} (turns → messages + tool cards) into the DOM.
+ *
+ * Like {@link renderCockpit} it builds against the structural {@link ElementLike} /
+ * {@link DocumentLike} subset (not lib.dom), so it renders identically embedded and
+ * standalone, is unit-tested on Node with the in-memory fake and no `as` cast, and is
+ * browser-safe — it relies only on the browser-safe transcript vocab (no `Buffer`).
+ *
+ * Events arrive offset-keyed and immutable in offset order, so re-deriving the whole
+ * (idempotent) log on each event is correct across a resume-from-offset reconnect: a
+ * replayed chunk below the resume point never reaches this sink, so no event is
+ * dropped or double-applied.
+ */
+import { type DerivedView } from "../transcript/index.ts";
+import type { DocumentLike, ElementLike } from "./render.ts";
+import type { StructuredSink } from "./terminal-session.ts";
+/**
+ * Render a derived structured view into `host`, replacing whatever was there.
+ * Idempotent: re-call it with the latest {@link DerivedView} on every new event.
+ */
+export declare function renderStructured(host: ElementLike, doc: DocumentLike, view: DerivedView): void;
+/** A structured sink with a `dispose` teardown (mirrors {@link TerminalSink}). */
+export interface StructuredTerminal extends StructuredSink {
+    dispose(): void;
+}
+/**
+ * Build a {@link StructuredSink} that accumulates the offset-ordered transcript
+ * events a structured stream delivers, folds them through the canonical
+ * {@link deriveView}, and renders the derived view into `host` on each event. The
+ * accumulated log is this sink's own state, so constructing one per drill-in gives
+ * each worker its own structured view.
+ */
+export declare function createStructuredSink(host: ElementLike, doc: DocumentLike): StructuredTerminal;

package/dist/cockpit/structured-view.js

@@ -0,0 +1,106 @@
+/**
+ * The cockpit's structured-stream renderer — S8's drill-in for an ACP stream.
+ *
+ * When a drilled worker's relay stream is a **structured** ACP stream (its chunks
+ * are {@link TRANSCRIPT_EVENT_MARKER}-tagged transcript-event envelopes rather than
+ * raw PTY bytes), the {@link TerminalSession} routes each decoded event here instead
+ * of the byte-terminal. This renderer does **not** re-parse or pretty-print JSON: it
+ * feeds the accumulated typed events straight through the ONE canonical
+ * {@link deriveView} fold from `@nanobpm/agentic/transcript` and renders the resulting
+ * {@link DerivedView} (turns → messages + tool cards) into the DOM.
+ *
+ * Like {@link renderCockpit} it builds against the structural {@link ElementLike} /
+ * {@link DocumentLike} subset (not lib.dom), so it renders identically embedded and
+ * standalone, is unit-tested on Node with the in-memory fake and no `as` cast, and is
+ * browser-safe — it relies only on the browser-safe transcript vocab (no `Buffer`).
+ *
+ * Events arrive offset-keyed and immutable in offset order, so re-deriving the whole
+ * (idempotent) log on each event is correct across a resume-from-offset reconnect: a
+ * replayed chunk below the resume point never reaches this sink, so no event is
+ * dropped or double-applied.
+ */
+import { deriveView } from "../transcript/index.js";
+function el(doc, tag, className, text) {
+    const node = doc.createElement(tag);
+    if (className !== undefined)
+        node.className = className;
+    if (text !== undefined)
+        node.textContent = text;
+    return node;
+}
+function toolCard(doc, tool) {
+    const card = el(doc, "div", "cockpit-structured-tool");
+    card.setAttribute("data-tool", tool.name);
+    card.setAttribute("data-offset", String(tool.offset));
+    card.setAttribute("data-state", tool.result === undefined ? "pending" : tool.result.ok ? "ok" : "error");
+    const head = el(doc, "div", "cockpit-structured-tool-head");
+    head.appendChild(el(doc, "span", "cockpit-structured-tool-name", tool.name));
+    if (tool.callId !== undefined)
+        head.appendChild(el(doc, "span", "cockpit-structured-tool-id", tool.callId));
+    card.appendChild(head);
+    if (tool.args !== undefined) {
+        card.appendChild(el(doc, "pre", "cockpit-structured-tool-args", JSON.stringify(tool.args)));
+    }
+    if (tool.result !== undefined) {
+        const result = el(doc, "div", "cockpit-structured-tool-result");
+        result.setAttribute("data-ok", tool.result.ok ? "true" : "false");
+        if (tool.result.content !== undefined)
+            result.textContent = tool.result.content;
+        card.appendChild(result);
+    }
+    return card;
+}
+function turnSection(doc, turn) {
+    const section = el(doc, "section", "cockpit-structured-turn");
+    section.setAttribute("data-turn", String(turn.index));
+    section.setAttribute("data-steps", String(turn.steps));
+    for (const message of turn.messages) {
+        const row = el(doc, "div", "cockpit-structured-message");
+        row.setAttribute("data-role", message.role);
+        row.setAttribute("data-offset", String(message.offset));
+        row.appendChild(el(doc, "span", "cockpit-structured-role", message.role));
+        row.appendChild(el(doc, "span", "cockpit-structured-text", message.text));
+        section.appendChild(row);
+    }
+    for (const tool of turn.tools) {
+        section.appendChild(toolCard(doc, tool));
+    }
+    return section;
+}
+/**
+ * Render a derived structured view into `host`, replacing whatever was there.
+ * Idempotent: re-call it with the latest {@link DerivedView} on every new event.
+ */
+export function renderStructured(host, doc, view) {
+    host.replaceChildren();
+    const root = el(doc, "div", "cockpit-structured");
+    root.setAttribute("data-lifecycle", view.lifecycle);
+    root.setAttribute("data-events", String(view.eventCount));
+    for (const turn of view.turns) {
+        root.appendChild(turnSection(doc, turn));
+    }
+    host.appendChild(root);
+}
+/**
+ * Build a {@link StructuredSink} that accumulates the offset-ordered transcript
+ * events a structured stream delivers, folds them through the canonical
+ * {@link deriveView}, and renders the derived view into `host` on each event. The
+ * accumulated log is this sink's own state, so constructing one per drill-in gives
+ * each worker its own structured view.
+ */
+export function createStructuredSink(host, doc) {
+    const events = [];
+    // Render an empty derived view up-front so the structured region is present and
+    // consistent before the first event lands.
+    renderStructured(host, doc, deriveView(events));
+    return {
+        event(event) {
+            events.push(event);
+            renderStructured(host, doc, deriveView(events));
+        },
+        dispose() {
+            events.length = 0;
+            host.replaceChildren();
+        },
+    };
+}

package/dist/cockpit/terminal-session.d.ts

@@ -19,8 +19,24 @@
  *  - 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 { type TranscriptEvent } from "../transcript/index.ts";
 /** The terminal sink the session writes decoded output to (xterm.js satisfies this). */
 export interface TerminalSink {
     /** Append a chunk of terminal output. */
@@ -28,6 +44,19 @@ export interface TerminalSink {
     /** Tear down the underlying terminal widget and its listeners, if any. */
     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";
@@ -50,8 +79,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. */

package/dist/cockpit/terminal-session.js

@@ -1,4 +1,5 @@
 import { addSafeInt, isNonNegInt, isPosInt } from "../relay/index.js";
+import { parseTranscriptEvent } from "../transcript/index.js";
 const DEFAULT_CREDIT = 1024;
 function isRelayData(message) {
     return !("op" in message);
@@ -11,6 +12,7 @@ function isRelayData(message) {
 export class TerminalSession {
     #stream;
     #sink;
+    #structured;
     #send;
     #credit;
     #onGap;
@@ -21,6 +23,7 @@ export class TerminalSession {
     constructor(options) {
         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)) {
@@ -84,18 +87,39 @@ export class TerminalSession {
         // 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) {
+        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, nextOffset) {
         // Validate the ack's resume point exactly as the constructor validates
         // `from`: `nextOffset` is echoed back into subscribe.from on the next