@nanobpm/agentic 0.1.0 → 0.4.0

package/src/session/normalizer/claude.ts

@@ -0,0 +1,136 @@
+/**
+ * Claude Code normalizer — ADR 0062 slice 3, reference dialect B.
+ *
+ * Driven with `claude -p --output-format stream-json` (paired with
+ * `--input-format stream-json` to feed it), Claude Code streams one JSON object
+ * per line. A turn arrives as an `assistant` frame whose `message.content` is an
+ * array of typed parts — `text`, `thinking` (with an encrypted `signature`),
+ * `tool_use` — and tool outputs come back as a `user` frame carrying
+ * `tool_result` parts. Restore is the native `--resume <id>` (`-c` continues the
+ * latest, `--from-pr` seeds from a PR — both resume-by-latest, not by-id, so the
+ * id-restore shim is `--resume`). Streaming + resume-by-id → `durable-resume`.
+ *
+ * ## Resume-critical fidelity: `thinking.signature`
+ *
+ * Claude's `thinking` parts carry a `signature`: the provider's opaque, encrypted
+ * reasoning-continuation token that must be replayed verbatim to continue
+ * extended thinking across a resume (ADR 0062 §5). We map it to the canonical
+ * `ReasoningEvent.providerContinuation`, so the native transcript remains the
+ * authoritative restore path for Claude just as it does for Copilot.
+ */
+import { type DraftEvent, type HarnessNormalizer, NormalizerDialectError, type ResumeShim } from "./types.ts";
+import { asArray, asRecord, isRecord, optNumber, optString, reqString } from "./record.ts";
+
+const HARNESS = "claude-code";
+
+function messageContent(obj: Record<string, unknown>): readonly unknown[] {
+  const message = obj.message;
+  if (!isRecord(message)) {
+    throw new NormalizerDialectError(HARNESS, `${String(obj.type)} frame must carry a "message" object`);
+  }
+  const content = message.content;
+  // Claude also permits a bare-string message content for a plain text turn.
+  if (typeof content === "string") return [{ type: "text", text: content }];
+  return asArray(HARNESS, content, "message.content");
+}
+
+function usageDrafts(usage: unknown, model: string | undefined): DraftEvent[] {
+  if (!isRecord(usage)) return [];
+  return [
+    {
+      type: "usage",
+      inputTokens: optNumber(HARNESS, usage, "input_tokens") ?? 0,
+      outputTokens: optNumber(HARNESS, usage, "output_tokens") ?? 0,
+      ...(model !== undefined ? { model } : {}),
+    },
+  ];
+}
+
+function toDrafts(record: unknown): readonly DraftEvent[] {
+  const obj = asRecord(HARNESS, record);
+  switch (obj.type) {
+    case "system":
+      // The `init` system frame is session metadata (tools, model, cwd), not a
+      // conversational system turn — it carries no canonical text.
+      return [];
+    case "assistant": {
+      const message = isRecord(obj.message) ? obj.message : {};
+      const model = optString(HARNESS, message, "model");
+      const drafts: DraftEvent[] = [];
+      for (const part of messageContent(obj)) {
+        if (!isRecord(part)) continue;
+        switch (part.type) {
+          case "text": {
+            const text = optString(HARNESS, part, "text");
+            if (text !== undefined && text.length > 0) drafts.push({ type: "assistant", text });
+            break;
+          }
+          case "thinking": {
+            const text = optString(HARNESS, part, "thinking");
+            const signature = optString(HARNESS, part, "signature");
+            drafts.push({
+              type: "reasoning",
+              ...(text !== undefined ? { text } : {}),
+              ...(signature !== undefined ? { providerContinuation: signature } : {}),
+            });
+            break;
+          }
+          case "tool_use": {
+            const callId = reqString(HARNESS, part, "id");
+            drafts.push({
+              type: "tool-call",
+              id: `call:${callId}`,
+              callId,
+              name: reqString(HARNESS, part, "name"),
+              args: part.input,
+            });
+            break;
+          }
+          default:
+            break;
+        }
+      }
+      // A turn's usage rides on its assistant message.
+      drafts.push(...usageDrafts(message.usage, model));
+      return drafts;
+    }
+    case "user": {
+      const drafts: DraftEvent[] = [];
+      for (const part of messageContent(obj)) {
+        if (!isRecord(part)) continue;
+        if (part.type === "tool_result") {
+          const callId = reqString(HARNESS, part, "tool_use_id");
+          drafts.push({
+            type: "tool-result",
+            id: `result:${callId}`,
+            callId,
+            ok: part.is_error !== true,
+            result: part.content,
+          });
+        } else if (part.type === "text") {
+          const text = optString(HARNESS, part, "text");
+          if (text !== undefined && text.length > 0) drafts.push({ type: "user", text });
+        }
+      }
+      return drafts;
+    }
+    case "result":
+      // Terminal accounting frame: fold its top-level usage in whenever present.
+      // Like every other frame's usage (and every other normalizer), this maps to
+      // its own canonical `usage` event — assistant frames emit their own
+      // per-message usage and the linker never dedupes; consumers aggregate.
+      return usageDrafts(obj.usage, optString(HARNESS, obj, "model"));
+    default:
+      return [];
+  }
+}
+
+/** The Claude Code fallback normalizer. Streaming + resume-by-id → durable. */
+export const claudeNormalizer: HarnessNormalizer = {
+  harness: HARNESS,
+  capabilities: { streaming: true, resumeById: true },
+  toDrafts,
+  resume(sessionId: string): ResumeShim {
+    return { transport: "cli", sessionId, args: ["--resume", sessionId] };
+  },
+};

package/src/session/normalizer/copilot.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { copilotNormalizer } from "./copilot.ts";
+import { normalizeSession } from "./link.ts";
+import { NormalizerDialectError } from "./types.ts";
+
+test("copilot maps turn boundaries, system, and usage frames", () => {
+  const events = normalizeSession(copilotNormalizer, [
+    { type: "system_message", text: "you are a coding agent" },
+    { type: "turn_started", turn: 0 },
+    { type: "assistant_message", text: "done" },
+    { type: "turn_completed", turn: 0 },
+    { type: "usage", input_tokens: 10, output_tokens: 3, model: "gpt" },
+  ]);
+  assert.deepEqual(events.map((e) => e.type), ["system", "turn-start", "assistant", "turn-end", "usage"]);
+});
+
+test("copilot lifts a failed tool result (isError) to ok:false", () => {
+  const [call, result] = normalizeSession(copilotNormalizer, [
+    { type: "tool_call", id: "c9", name: "run", arguments: { cmd: "ls" } },
+    { type: "tool_result", id: "c9", isError: true, output: "boom" },
+  ]);
+  assert.equal(call.type, "tool-call");
+  assert.equal(result.type, "tool-result");
+  if (result.type === "tool-result") {
+    assert.equal(result.ok, false);
+    assert.equal(result.result, "boom");
+    assert.equal(result.callId, "c9");
+  }
+});
+
+test("copilot correlates a tool call and its result by callId across generated ids", () => {
+  const events = normalizeSession(copilotNormalizer, [
+    { type: "tool_call", id: "abc", name: "write", arguments: {} },
+    { type: "tool_result", id: "abc", output: "ok" },
+  ]);
+  assert.equal(events[0].type === "tool-call" && events[0].callId, "abc");
+  assert.equal(events[1].type === "tool-result" && events[1].callId, "abc");
+});
+
+test("copilot preserves reasoningOpaque as the canonical providerContinuation", () => {
+  const [reasoning] = normalizeSession(copilotNormalizer, [
+    { type: "reasoning", text: "thinking", reasoningOpaque: "ENCRYPTED-BLOB" },
+  ]);
+  assert.ok(reasoning.type === "reasoning");
+  if (reasoning.type === "reasoning") {
+    assert.equal(reasoning.text, "thinking");
+    assert.equal(reasoning.providerContinuation, "ENCRYPTED-BLOB");
+  }
+});
+
+test("copilot ignores transport frames it does not model", () => {
+  assert.deepEqual(normalizeSession(copilotNormalizer, [{ type: "heartbeat" }, { type: "session_ready" }]), []);
+});
+
+test("a structurally invalid record fails loudly with a dialect error", () => {
+  assert.throws(() => copilotNormalizer.toDrafts({ type: "tool_call", name: "no-id" }), NormalizerDialectError);
+  assert.throws(() => copilotNormalizer.toDrafts(42), NormalizerDialectError);
+});

package/src/session/normalizer/copilot.ts

@@ -0,0 +1,133 @@
+/**
+ * `@github/copilot` normalizer — ADR 0062 slice 3, reference dialect A.
+ *
+ * Copilot runs in-process through `copilot-sdk`: the mind source is its own
+ * `SessionEvent` stream (`session.on(...)`, or the `events.jsonl` transcript it
+ * writes), and restore is the SDK's `resumeSession(id)` (the `sessionFsProvider`
+ * seam is the same call under a different persistence root, so the resume shim is
+ * identical). Copilot both streams and resumes-by-id → it advertises
+ * `durable-resume`.
+ *
+ * ## Resume-critical fidelity: `reasoningOpaque`
+ *
+ * ADR 0062 §5 lets a native adapter *prefer the native transcript for restore*
+ * when it carries more than the ACP models. Copilot's reasoning events carry a
+ * `reasoningOpaque` blob — the provider reasoning-continuation handle that must
+ * be replayed verbatim to continue the model's reasoning across a resume. The
+ * canonical `ReasoningEvent` has a home for exactly this (`providerContinuation`),
+ * so we map it straight through, untouched. Dropping it (as a lossy ACP
+ * projection might) would silently break reasoning continuation on resume — so
+ * this dialect is the authoritative ingestion path for Copilot.
+ */
+import type { DraftEvent, HarnessNormalizer, ResumeShim } from "./types.ts";
+import { asRecord, contentText, optNumber, optString, reqString } from "./record.ts";
+
+const HARNESS = "@github/copilot";
+
+/**
+ * Map one `copilot-sdk` `SessionEvent` to canonical drafts. Copilot's event
+ * `type`s are close to ours but not identical (`assistant_message` vs
+ * `assistant`, `reasoningOpaque` vs `providerContinuation`, `turn_started` vs
+ * `turn-start`); this is exactly the per-dialect translation the slice exists to
+ * own.
+ */
+function toDrafts(record: unknown): readonly DraftEvent[] {
+  const obj = asRecord(HARNESS, record);
+  switch (obj.type) {
+    case "system":
+    case "system_message":
+      return [{ type: "system", text: reqString(HARNESS, obj, "text") }];
+    case "user":
+    case "user_message":
+      return [{ type: "user", text: reqString(HARNESS, obj, "text") }];
+    case "assistant":
+    case "assistant_message": {
+      const text = contentText(obj.text ?? obj.content);
+      return text === undefined ? [] : [{ type: "assistant", text }];
+    }
+    case "reasoning": {
+      const text = optString(HARNESS, obj, "text");
+      // Copilot names the continuation blob `reasoningOpaque`; accept the
+      // canonical spelling too so a pre-normalized feed round-trips.
+      const providerContinuation =
+        optString(HARNESS, obj, "reasoningOpaque") ?? optString(HARNESS, obj, "providerContinuation");
+      return [
+        {
+          type: "reasoning",
+          ...(text !== undefined ? { text } : {}),
+          ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+        },
+      ];
+    }
+    case "tool_call": {
+      const callId = reqString(HARNESS, obj, "id");
+      return [
+        {
+          type: "tool-call",
+          id: `call:${callId}`,
+          callId,
+          name: reqString(HARNESS, obj, "name"),
+          args: obj.arguments ?? obj.args,
+        },
+      ];
+    }
+    case "tool_result": {
+      const callId = reqString(HARNESS, obj, "id");
+      // Copilot marks failure with an `isError` flag; the payload lives in
+      // `output` either way.
+      const ok = obj.isError === true ? false : obj.error == null;
+      return [
+        {
+          type: "tool-result",
+          id: `result:${callId}`,
+          callId,
+          ok,
+          result: obj.output ?? obj.result ?? obj.error,
+        },
+      ];
+    }
+    case "turn_started":
+      return [{ type: "turn-start", turn: turnIndex(obj) }];
+    case "turn_completed":
+    case "turn_ended":
+      return [{ type: "turn-end", turn: turnIndex(obj) }];
+    case "usage": {
+      const model = optString(HARNESS, obj, "model");
+      return [
+        {
+          type: "usage",
+          inputTokens: usageCount(obj, "inputTokens", "input_tokens"),
+          outputTokens: usageCount(obj, "outputTokens", "output_tokens"),
+          ...(model !== undefined ? { model } : {}),
+        },
+      ];
+    }
+    default:
+      // Transport frames Copilot emits that carry no session-log meaning
+      // (heartbeats, session-ready acks) normalize to nothing.
+      return [];
+  }
+}
+
+function turnIndex(obj: Record<string, unknown>): number {
+  return optNumber(HARNESS, obj, "turn") ?? 0;
+}
+
+function usageCount(obj: Record<string, unknown>, camel: string, snake: string): number {
+  return optNumber(HARNESS, obj, camel) ?? optNumber(HARNESS, obj, snake) ?? 0;
+}
+
+/**
+ * The `@github/copilot` fallback normalizer. `streaming`/`resumeById` are both
+ * true, so {@link capabilityProbe} derives `durable-resume: true`.
+ */
+export const copilotNormalizer: HarnessNormalizer = {
+  harness: HARNESS,
+  capabilities: { streaming: true, resumeById: true },
+  toDrafts,
+  resume(sessionId: string): ResumeShim {
+    // In-process SDK restore: `resumeSession(id)` (the sessionFsProvider seam is
+    // the same call under a different persistence root).
+    return { transport: "sdk", sessionId, call: "resumeSession", args: [sessionId] };
+  },
+};

package/src/session/normalizer/deepseek.ts

@@ -0,0 +1,80 @@
+/**
+ * DeepSeek Harness normalizer — ADR 0062 slice 3.
+ *
+ * The DeepSeek Harness exposes a live `SessionEvent` feed rather than a spawned
+ * `stream-json` transport: its frames are already event-shaped (`kind`-tagged),
+ * so the dialect is a thin renaming onto the canonical union. Restore is the
+ * harness's in-process `seed`/`restore` pair, so the resume shim is the SDK
+ * `restore(id)` call. Streaming + resume-by-id → `durable-resume`.
+ */
+import type { DraftEvent, HarnessNormalizer, ResumeShim } from "./types.ts";
+import { asRecord, optNumber, optString, reqString } from "./record.ts";
+
+const HARNESS = "deepseek";
+
+function toDrafts(record: unknown): readonly DraftEvent[] {
+  const obj = asRecord(HARNESS, record);
+  switch (obj.kind) {
+    case "message": {
+      const text = optString(HARNESS, obj, "content") ?? optString(HARNESS, obj, "text");
+      if (text === undefined || text.length === 0) return [];
+      const role = optString(HARNESS, obj, "role");
+      return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+    }
+    case "reasoning": {
+      const text = optString(HARNESS, obj, "content") ?? optString(HARNESS, obj, "text");
+      const providerContinuation = optString(HARNESS, obj, "continuation");
+      return [
+        {
+          type: "reasoning",
+          ...(text !== undefined ? { text } : {}),
+          ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+        },
+      ];
+    }
+    case "tool": {
+      const callId = reqString(HARNESS, obj, "id");
+      return [
+        {
+          type: "tool-call",
+          id: `call:${callId}`,
+          callId,
+          name: reqString(HARNESS, obj, "name"),
+          args: obj.arguments ?? obj.args,
+        },
+      ];
+    }
+    case "tool_result": {
+      const callId = reqString(HARNESS, obj, "id");
+      return [
+        {
+          type: "tool-result",
+          id: `result:${callId}`,
+          callId,
+          ok: obj.ok !== false,
+          result: obj.output ?? obj.result,
+        },
+      ];
+    }
+    case "usage":
+      return [
+        {
+          type: "usage",
+          inputTokens: optNumber(HARNESS, obj, "input") ?? optNumber(HARNESS, obj, "inputTokens") ?? 0,
+          outputTokens: optNumber(HARNESS, obj, "output") ?? optNumber(HARNESS, obj, "outputTokens") ?? 0,
+          ...(typeof obj.model === "string" ? { model: obj.model } : {}),
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+export const deepseekNormalizer: HarnessNormalizer = {
+  harness: HARNESS,
+  capabilities: { streaming: true, resumeById: true },
+  toDrafts,
+  resume(sessionId: string): ResumeShim {
+    return { transport: "sdk", sessionId, call: "restore", args: [sessionId] };
+  },
+};

package/src/session/normalizer/index.ts

@@ -0,0 +1,61 @@
+/**
+ * `@nanobpm/agentic/session/normalizer` — ADR 0062 slice 3 public surface.
+ *
+ * The `stream-json`/native-transcript fallback ingestion backend: the per-harness
+ * {@link HarnessNormalizer} contract, the shared causal-chain linker
+ * ({@link normalizeSession}/{@link linkDrafts}), the capability probe
+ * ({@link capabilityProbe}), and the current-fleet registry that enumerates the
+ * harnesses this slice ships an adapter for. A caller (the ingestion boundary,
+ * slice 5's enrolment gate) looks a harness up by id and gets its normalizer;
+ * {@link probeFleet} folds the whole registry into `durable-resume`
+ * advertisements in one call.
+ *
+ * The registry is derived from the normalizer modules themselves (each is keyed
+ * by its own `harness` id), so there is no second hand-maintained list of harness
+ * names to drift against.
+ */
+export type {
+  CapabilityAdvertisement,
+  DistributiveOmit,
+  DraftEvent,
+  HarnessCapabilities,
+  HarnessNormalizer,
+  ResumeShim,
+} from "./types.ts";
+export { capabilityProbe, NormalizerDialectError } from "./types.ts";
+export type { LinkOptions } from "./link.ts";
+export { linkDrafts, normalizeSession } from "./link.ts";
+import { claudeNormalizer } from "./claude.ts";
+import { copilotNormalizer } from "./copilot.ts";
+import { deepseekNormalizer } from "./deepseek.ts";
+import { kimiNormalizer } from "./kimi.ts";
+import { piNormalizer } from "./pi.ts";
+import { qwenNormalizer } from "./qwen.ts";
+import { type CapabilityAdvertisement, capabilityProbe, type HarnessNormalizer } from "./types.ts";
+
+export { claudeNormalizer, copilotNormalizer, deepseekNormalizer, kimiNormalizer, piNormalizer, qwenNormalizer };
+
+/** Every fallback normalizer in the current fleet, in reference-dialect order. */
+export const FLEET_NORMALIZERS: readonly HarnessNormalizer[] = [
+  copilotNormalizer,
+  claudeNormalizer,
+  qwenNormalizer,
+  kimiNormalizer,
+  piNormalizer,
+  deepseekNormalizer,
+];
+
+/** Registry keyed by `harness` id, derived from {@link FLEET_NORMALIZERS}. */
+export const NORMALIZER_REGISTRY: ReadonlyMap<string, HarnessNormalizer> = new Map(
+  FLEET_NORMALIZERS.map((n) => [n.harness, n]),
+);
+
+/** Look a harness's normalizer up by id, or `undefined` when it is not in the fleet. */
+export function normalizerFor(harness: string): HarnessNormalizer | undefined {
+  return NORMALIZER_REGISTRY.get(harness);
+}
+
+/** Probe every harness in the fleet for its derived `durable-resume` advertisement. */
+export function probeFleet(): readonly CapabilityAdvertisement[] {
+  return FLEET_NORMALIZERS.map(capabilityProbe);
+}

package/src/session/normalizer/kimi.ts

@@ -0,0 +1,82 @@
+/**
+ * Kimi normalizer — ADR 0062 slice 3.
+ *
+ * Driven with `kimi -p --output-format stream-json`. Kimi tags each frame with an
+ * `event` discriminator and folds a tool call and its result under one `tool`
+ * event distinguished by `phase`. Restore is `-S [id]` (`-c` continues the
+ * latest). Streaming + resume-by-id → `durable-resume`.
+ */
+import { type DraftEvent, type HarnessNormalizer, NormalizerDialectError, type ResumeShim } from "./types.ts";
+import { asRecord, optNumber, optString, reqString } from "./record.ts";
+
+const HARNESS = "kimi";
+
+function toDrafts(record: unknown): readonly DraftEvent[] {
+  const obj = asRecord(HARNESS, record);
+  switch (obj.event) {
+    case "text": {
+      const text = optString(HARNESS, obj, "text");
+      if (text === undefined || text.length === 0) return [];
+      const role = optString(HARNESS, obj, "role");
+      return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+    }
+    case "reasoning": {
+      const text = optString(HARNESS, obj, "text");
+      const providerContinuation = optString(HARNESS, obj, "continuation");
+      return [
+        {
+          type: "reasoning",
+          ...(text !== undefined ? { text } : {}),
+          ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+        },
+      ];
+    }
+    case "tool": {
+      const callId = reqString(HARNESS, obj, "id");
+      const phase = optString(HARNESS, obj, "phase");
+      if (phase === "result") {
+        return [
+          {
+            type: "tool-result",
+            id: `result:${callId}`,
+            callId,
+            ok: obj.ok !== false,
+            result: obj.output ?? obj.result,
+          },
+        ];
+      }
+      if (phase === "call" || phase === undefined) {
+        return [
+          {
+            type: "tool-call",
+            id: `call:${callId}`,
+            callId,
+            name: reqString(HARNESS, obj, "name"),
+            args: obj.arguments ?? obj.args,
+          },
+        ];
+      }
+      throw new NormalizerDialectError(HARNESS, `unknown tool phase ${JSON.stringify(phase)}`);
+    }
+    case "usage":
+      return [
+        {
+          type: "usage",
+          inputTokens: optNumber(HARNESS, obj, "prompt_tokens") ?? 0,
+          outputTokens: optNumber(HARNESS, obj, "completion_tokens") ?? 0,
+          ...(typeof obj.model === "string" ? { model: obj.model } : {}),
+        },
+      ];
+    default:
+      return [];
+  }
+}
+
+export const kimiNormalizer: HarnessNormalizer = {
+  harness: HARNESS,
+  capabilities: { streaming: true, resumeById: true },
+  toDrafts,
+  resume(sessionId: string): ResumeShim {
+    return { transport: "cli", sessionId, args: ["-S", sessionId] };
+  },
+};

package/src/session/normalizer/link.test.ts

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { normalizeSession } from "./link.ts";
+import { qwenNormalizer } from "./qwen.ts";
+
+test("the default newId is unique across repeated normalizeSession calls for one session", () => {
+  const records = [
+    { type: "content", role: "user", text: "one" },
+    { type: "content", role: "model", text: "two" },
+  ];
+  const first = normalizeSession(qwenNormalizer, records);
+  const second = normalizeSession(qwenNormalizer, records);
+  const ids = new Set([...first, ...second].map((e) => e.id));
+  assert.equal(ids.size, first.length + second.length, "ids do not collide across calls");
+});
+
+test("an injected newId still overrides the default for deterministic tests", () => {
+  const events = normalizeSession(
+    qwenNormalizer,
+    [{ type: "content", role: "user", text: "hi" }],
+    { newId: (() => { let n = 0; return () => `d-${n++}`; })() },
+  );
+  assert.equal(events[0].id, "d-0");
+});

package/src/session/normalizer/link.ts

@@ -0,0 +1,81 @@
+/**
+ * The shared causal-chain linker + stream driver every dialect reuses — ADR 0062
+ * slice 3.
+ *
+ * A {@link HarnessNormalizer} produces {@link DraftEvent}s (semantics only); the
+ * *chaining* — assigning each event a stable `id` and stamping `parentId` as the
+ * id of its predecessor — is identical across every harness dialect, so it lives
+ * here exactly once (derivation over duplication, AGENTS.md). {@link normalizeSession}
+ * is the one entry point a caller uses: it maps a whole native transcript through
+ * a normalizer, links the drafts into a causal chain, and validates every result
+ * against the slice-1 boundary ({@link parseSessionEvent}) so a dialect can never
+ * emit a shape that is not a canonical {@link SessionEvent}.
+ */
+import { randomUUID } from "node:crypto";
+import { parseSessionEvent, type SessionEvent } from "../events.ts";
+import type { DraftEvent, HarnessNormalizer } from "./types.ts";
+
+export interface LinkOptions {
+  /**
+   * Id generator for drafts that do not carry a native id. Default is
+   * `crypto.randomUUID`, which is unique-safe across repeated
+   * `normalizeSession()` calls for one session (e.g. per chunk / per resume
+   * leg); inject a deterministic generator in tests when stable ids are needed.
+   * It is only consulted when a draft omits `id`.
+   */
+  newId?: () => string;
+  /**
+   * The `parentId` the first linked event points at — the causal predecessor
+   * this transcript continues from. `null` (default) starts a fresh chain; on a
+   * resume the caller passes the last restored event's id so the new events
+   * continue the same chain across the resume boundary.
+   */
+  parentId?: string | null;
+}
+
+/**
+ * Thread a flat list of {@link DraftEvent}s into a causal chain of canonical
+ * {@link SessionEvent}s: each event's `id` is its native id when it supplied one
+ * else a freshly generated id, and its `parentId` is the id of the event before
+ * it (or {@link LinkOptions.parentId} for the first). Offsets are *not* assigned
+ * here — the authoritative log owns those on `emit` (slice 1); this only records
+ * causality (`parentId`), which survives compaction.
+ */
+export function linkDrafts(drafts: readonly DraftEvent[], options: LinkOptions = {}): SessionEvent[] {
+  const newId = options.newId ?? randomUUID;
+  let parentId: string | null = options.parentId ?? null;
+  const linked: SessionEvent[] = [];
+  for (const draft of drafts) {
+    const { id: nativeId, ...rest } = draft;
+    const id = nativeId ?? newId();
+    // Re-validate the fully-formed event at the slice-1 boundary: `rest` carries
+    // the discriminant + payload, and we add the chain fields. parseSessionEvent
+    // *builds* the union member field-by-field (never an as-cast), so a dialect
+    // bug surfaces here as a loud SessionEventShapeError instead of a bad row.
+    const event = parseSessionEvent({ ...rest, id, parentId });
+    linked.push(event);
+    parentId = id;
+  }
+  return linked;
+}
+
+/**
+ * Normalize a whole native transcript through a harness normalizer: map every
+ * record to drafts, then {@link linkDrafts} the concatenation into one canonical
+ * causal chain. This is the fallback backend's public ingestion call — the
+ * mirror of the ACP backend's `session/update` stream, producing the same
+ * {@link SessionEvent}s a caller feeds to a slice-1 `SessionAdapter.emit`.
+ */
+export function normalizeSession(
+  normalizer: HarnessNormalizer,
+  records: Iterable<unknown>,
+  options: LinkOptions = {},
+): SessionEvent[] {
+  const drafts: DraftEvent[] = [];
+  for (const record of records) {
+    for (const draft of normalizer.toDrafts(record)) {
+      drafts.push(draft);
+    }
+  }
+  return linkDrafts(drafts, options);
+}