@nanobpm/agentic 0.4.0 → 0.6.0

package/src/protocol/conformance/corpus.test.ts

@@ -6,6 +6,13 @@ import { GOLDEN_FRAMES } from "./frames.ts";
 import type { FrameDirection } from "./frames.ts";
 import { MALFORMED_FRAMES } from "./malformed.ts";
 import type { FrameDecodeErrorCode } from "../frame.ts";
+import {
+  parseInboundRelayChunk,
+  encodeInboundControlFrame,
+  type InboundControlErrorCode,
+  type InboundControlKind,
+} from "../control.ts";
+import { VALID_CONTROL_FRAMES, MALFORMED_CONTROL_FRAMES } from "./control.ts";
 
 // The corpus is only a defence against drift if it is exhaustive. These tests
 // fail if a new family, lane, or decode-error code is added without a covering
@@ -64,3 +71,72 @@ test("golden frame names are unique", () => {
   const names = GOLDEN_FRAMES.map((g) => g.name);
   assert.equal(new Set(names).size, names.length);
 });
+
+// --- Inbound control vocabulary (steer-in) -------------------------------
+
+test("valid control corpus decodes to its declared frame", () => {
+  for (const v of VALID_CONTROL_FRAMES) {
+    const result = parseInboundRelayChunk(v.chunk);
+    assert.ok(result.ok, `${v.name}: ${result.ok ? "" : JSON.stringify(result.errors)}`);
+    assert.deepEqual(result.frame, v.frame, v.name);
+    assert.equal(result.structured, v.structured, `${v.name}: structured flag`);
+  }
+});
+
+test("structured control frames round-trip through the encoder", () => {
+  for (const v of VALID_CONTROL_FRAMES) {
+    if (!v.roundTrips) continue;
+    const encoded = encodeInboundControlFrame(v.frame);
+    const back = parseInboundRelayChunk(encoded);
+    assert.ok(back.ok, `${v.name}: re-decode failed`);
+    assert.deepEqual(back.frame, v.frame, `${v.name}: round-trip frame`);
+    assert.equal(back.structured, true, `${v.name}: round-trip is structured`);
+  }
+});
+
+test("valid control corpus covers every control kind", () => {
+  const ALL_KINDS: Record<InboundControlKind, true> = {
+    prompt: true,
+    cancel: true,
+    permission: true,
+  };
+  const covered = new Set<string>(VALID_CONTROL_FRAMES.map((v) => v.frame.kind));
+  for (const kind of Object.keys(ALL_KINDS)) {
+    assert.ok(covered.has(kind), `no valid control vector covers kind: ${kind}`);
+  }
+});
+
+test("legacy bare-string steer still decodes as a prompt (no regression)", () => {
+  const legacy = VALID_CONTROL_FRAMES.filter((v) => !v.structured);
+  assert.ok(legacy.length > 0, "corpus must retain legacy bare-string vectors");
+  for (const v of legacy) {
+    const result = parseInboundRelayChunk(v.chunk);
+    assert.ok(result.ok && result.frame.kind === "prompt", v.name);
+    assert.equal(result.ok && result.frame.kind === "prompt" && result.frame.text, v.chunk, v.name);
+  }
+});
+
+test("malformed control corpus is rejected with the expected code", () => {
+  for (const m of MALFORMED_CONTROL_FRAMES) {
+    const result = parseInboundRelayChunk(m.chunk);
+    assert.ok(!result.ok, `${m.name}: expected rejection`);
+    assert.ok(
+      !result.ok && result.errors.some((e) => e.code === m.expected),
+      `${m.name}: expected code ${m.expected}, got ${result.ok ? "ok" : JSON.stringify(result.errors)}`,
+    );
+  }
+});
+
+test("malformed control corpus covers every control error code", () => {
+  const ALL_CODES: Record<InboundControlErrorCode, true> = {
+    "bad-kind": true,
+    "bad-prompt-text": true,
+    "bad-cancel-reason": true,
+    "bad-permission-request-id": true,
+    "bad-permission-outcome": true,
+  };
+  const covered = new Set<string>(MALFORMED_CONTROL_FRAMES.map((m) => m.expected));
+  for (const code of Object.keys(ALL_CODES)) {
+    assert.ok(covered.has(code), `no malformed control vector covers code: ${code}`);
+  }
+});

package/src/protocol/conformance/index.ts

@@ -27,3 +27,9 @@ export {
   type ValidToken,
   type InvalidToken,
 } from "./tokens.ts";
+export {
+  VALID_CONTROL_FRAMES,
+  MALFORMED_CONTROL_FRAMES,
+  type ValidControlFrame,
+  type MalformedControlFrame,
+} from "./control.ts";

package/src/protocol/control.test.ts

@@ -0,0 +1,131 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CONTROL_FRAME_MARKER,
+  CONTROL_FRAME_VERSION,
+  isInboundControlEnvelope,
+  parseInboundRelayChunk,
+  encodeInboundControlFrame,
+  type InboundControlFrame,
+} from "./control.ts";
+
+test("marker + version are the canonical tag", () => {
+  assert.equal(CONTROL_FRAME_MARKER, "nanoControlFrame");
+  assert.equal(CONTROL_FRAME_VERSION, 1);
+});
+
+test("isInboundControlEnvelope only accepts the tagged object at the current version", () => {
+  assert.ok(isInboundControlEnvelope({ [CONTROL_FRAME_MARKER]: 1, kind: "cancel" }));
+  assert.ok(!isInboundControlEnvelope({ [CONTROL_FRAME_MARKER]: 2, kind: "cancel" }));
+  assert.ok(!isInboundControlEnvelope({ kind: "cancel" }));
+  assert.ok(!isInboundControlEnvelope("cancel"));
+  assert.ok(!isInboundControlEnvelope(null));
+  assert.ok(!isInboundControlEnvelope([{ [CONTROL_FRAME_MARKER]: 1 }]));
+});
+
+test("prompt frame decodes with its text", () => {
+  const chunk = encodeInboundControlFrame({ kind: "prompt", text: "hello" });
+  const result = parseInboundRelayChunk(chunk);
+  assert.ok(result.ok);
+  assert.equal(result.structured, true);
+  assert.deepEqual(result.frame, { kind: "prompt", text: "hello" });
+});
+
+test("cancel frame decodes with and without a reason", () => {
+  const bare = parseInboundRelayChunk(encodeInboundControlFrame({ kind: "cancel" }));
+  assert.ok(bare.ok && bare.frame.kind === "cancel");
+  assert.equal(bare.ok && "reason" in bare.frame, false);
+
+  const withReason = parseInboundRelayChunk(
+    encodeInboundControlFrame({ kind: "cancel", reason: "stop" }),
+  );
+  assert.ok(withReason.ok);
+  assert.deepEqual(withReason.frame, { kind: "cancel", reason: "stop" });
+});
+
+test("permission frame carries the request id and outcome", () => {
+  for (const outcome of ["granted", "denied"] as const) {
+    const chunk = encodeInboundControlFrame({ kind: "permission", requestId: "r1", outcome });
+    const result = parseInboundRelayChunk(chunk);
+    assert.ok(result.ok);
+    assert.deepEqual(result.frame, { kind: "permission", requestId: "r1", outcome });
+  }
+});
+
+test("a bare keystroke string decodes as a prompt verbatim (legacy raw-byte steer)", () => {
+  for (const raw of ["ls -la\n", "\u0003", "y", "{not json", "42", "true"]) {
+    const result = parseInboundRelayChunk(raw);
+    assert.ok(result.ok, raw);
+    assert.equal(result.structured, false, raw);
+    assert.deepEqual(result.frame, { kind: "prompt", text: raw }, raw);
+  }
+});
+
+test("an untagged JSON object is a legacy prompt, not a control frame", () => {
+  const chunk = JSON.stringify({ kind: "cancel" });
+  const result = parseInboundRelayChunk(chunk);
+  assert.ok(result.ok);
+  assert.equal(result.structured, false);
+  assert.deepEqual(result.frame, { kind: "prompt", text: chunk });
+});
+
+test("a tagged-but-malformed envelope is an error, never a silent prompt", () => {
+  const cases: Array<{ chunk: string; code: string }> = [
+    { chunk: JSON.stringify({ [CONTROL_FRAME_MARKER]: 1 }), code: "bad-kind" },
+    { chunk: JSON.stringify({ [CONTROL_FRAME_MARKER]: 1, kind: "nope" }), code: "bad-kind" },
+    { chunk: JSON.stringify({ [CONTROL_FRAME_MARKER]: 1, kind: "prompt" }), code: "bad-prompt-text" },
+    {
+      chunk: JSON.stringify({ [CONTROL_FRAME_MARKER]: 1, kind: "permission", outcome: "granted" }),
+      code: "bad-permission-request-id",
+    },
+    {
+      chunk: JSON.stringify({
+        [CONTROL_FRAME_MARKER]: 1,
+        kind: "permission",
+        requestId: "r",
+        outcome: "meh",
+      }),
+      code: "bad-permission-outcome",
+    },
+  ];
+  for (const c of cases) {
+    const result = parseInboundRelayChunk(c.chunk);
+    assert.ok(!result.ok, c.chunk);
+    assert.ok(!result.ok && result.errors.some((e) => e.code === c.code), c.chunk);
+  }
+});
+
+test("a control envelope with leading whitespace still decodes structured (fast-path scans past whitespace)", () => {
+  const envelope = encodeInboundControlFrame({ kind: "cancel", reason: "stop" });
+  for (const prefix of [" ", "\t", "\n", "\r\n", "  \t\n "]) {
+    const result = parseInboundRelayChunk(prefix + envelope);
+    assert.ok(result.ok, prefix);
+    assert.equal(result.structured, true, prefix);
+    assert.deepEqual(result.frame, { kind: "cancel", reason: "stop" }, prefix);
+  }
+});
+
+test("chunks whose first non-whitespace char is not { stay legacy prompts verbatim", () => {
+  // Includes valid non-object JSON (number/array/string) that must NOT be
+  // mistaken for a control envelope by the JSON.parse fast-path gate.
+  for (const raw of ["  ls\n", "\t\ty", "42", "  3.14", "[1,2,3]", '"quoted"', "", "   "]) {
+    const result = parseInboundRelayChunk(raw);
+    assert.ok(result.ok, raw);
+    assert.equal(result.structured, false, raw);
+    assert.deepEqual(result.frame, { kind: "prompt", text: raw }, raw);
+  }
+});
+
+test("every frame kind round-trips through encode/parse", () => {
+  const frames: InboundControlFrame[] = [
+    { kind: "prompt", text: "多 bytes ✓" },
+    { kind: "cancel" },
+    { kind: "cancel", reason: "why" },
+    { kind: "permission", requestId: "req-42", outcome: "denied" },
+  ];
+  for (const frame of frames) {
+    const back = parseInboundRelayChunk(encodeInboundControlFrame(frame));
+    assert.ok(back.ok);
+    assert.deepEqual(back.frame, frame);
+  }
+});

package/src/protocol/control.ts

@@ -0,0 +1,258 @@
+/**
+ * Typed INBOUND control vocabulary for the `relay` family (ADR 0056, ACP steer).
+ *
+ * The relay data frame ({@link RelayPayload} `{ stream, offset, chunk }`) is the
+ * OUTBOUND (hub → consumer) byte lane and is left untouched. This module adds an
+ * ADDITIVE vocabulary for the INBOUND (consumer → agent) steer lane, where a
+ * peer historically sent a bare `chunk` string that a PTY role fed straight to
+ * the terminal as keystrokes. ACP steering must now distinguish three intents:
+ *
+ *  - `prompt`     — start a new turn (carries the prompt text);
+ *  - `cancel`     — interrupt the current turn (optionally with a reason);
+ *  - `permission` — answer/release a blocked `session/request_permission`
+ *                   (carries the request id being answered + the outcome).
+ *
+ * ## Backward compatibility (raw-byte steer)
+ *
+ * The vocabulary is a STRICT superset of the legacy raw-byte path. A structured
+ * frame is a JSON envelope TAGGED with {@link CONTROL_FRAME_MARKER}; a bare
+ * inbound string that is NOT such a tagged envelope (a keystroke, a shell line,
+ * unrelated JSON) continues to decode as a `prompt` whose `text` is the original
+ * chunk verbatim. Existing raw-byte producers and consumers need not change.
+ *
+ * ## Decode order (see {@link parseInboundRelayChunk})
+ *
+ *  1. If the chunk parses as a control envelope (a JSON object tagged with the
+ *     marker at the current version) → validate it and return the typed frame;
+ *     a tagged-but-malformed envelope is an ERROR, never a silent prompt.
+ *  2. Otherwise → legacy fall-back: `{ kind: "prompt", text: <chunk> }`.
+ *
+ * This is purely the inbound control vocabulary at the protocol seam: it changes
+ * neither the relay transport (ring, QoS, offsets, stream routing) nor the
+ * outbound `{ stream, offset, chunk }` data-frame shape.
+ */
+
+/**
+ * The marker key that tags a chunk as a structured inbound control envelope.
+ * Its value is the {@link CONTROL_FRAME_VERSION}. A chunk without this key is a
+ * legacy bare-string steer and decodes as a `prompt`.
+ */
+export const CONTROL_FRAME_MARKER = "nanoControlFrame" as const;
+
+/** The schema version carried by the {@link CONTROL_FRAME_MARKER}. */
+export const CONTROL_FRAME_VERSION = 1 as const;
+
+/** The three inbound steer intents. */
+export type InboundControlKind = "prompt" | "cancel" | "permission";
+
+/** How a blocked `session/request_permission` was answered. */
+export type PermissionOutcome = "granted" | "denied";
+
+/** Start a new turn with the given prompt text. */
+export interface PromptControlFrame {
+  readonly kind: "prompt";
+  readonly text: string;
+}
+
+/** Interrupt the current turn. `reason` is advisory, for telemetry/audit. */
+export interface CancelControlFrame {
+  readonly kind: "cancel";
+  readonly reason?: string;
+}
+
+/** Answer a blocked `session/request_permission` identified by `requestId`. */
+export interface PermissionControlFrame {
+  readonly kind: "permission";
+  readonly requestId: string;
+  readonly outcome: PermissionOutcome;
+}
+
+/** The typed inbound control vocabulary — a discriminated union on `kind`. */
+export type InboundControlFrame =
+  | PromptControlFrame
+  | CancelControlFrame
+  | PermissionControlFrame;
+
+export interface InboundControlError {
+  readonly code: InboundControlErrorCode;
+  readonly message: string;
+}
+
+/**
+ * The closed set of validation-error codes a tagged-but-malformed control
+ * envelope can raise. The conformance corpus derives its coverage from this
+ * union, so a new code cannot be added without a covering malformed vector.
+ */
+export type InboundControlErrorCode =
+  | "bad-kind"
+  | "bad-prompt-text"
+  | "bad-cancel-reason"
+  | "bad-permission-request-id"
+  | "bad-permission-outcome";
+
+/**
+ * The result of decoding an inbound steer chunk. `structured` distinguishes a
+ * recognised control envelope from the legacy bare-string-as-prompt fall-back,
+ * so a consumer can tell an explicit `prompt` frame from a raw keystroke.
+ */
+export type InboundControlDecodeResult =
+  | { readonly ok: true; readonly frame: InboundControlFrame; readonly structured: boolean }
+  | { readonly ok: false; readonly errors: readonly InboundControlError[] };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Is `value` a structured inbound control envelope (a plain object tagged with
+ * the marker at the current version)? This is the discriminator the decoder uses
+ * to choose the structured path over the legacy bare-string fall-back — it does
+ * NOT assert the envelope's `kind`-specific fields are well-formed.
+ */
+export function isInboundControlEnvelope(value: unknown): value is Record<string, unknown> {
+  return isPlainObject(value) && value[CONTROL_FRAME_MARKER] === CONTROL_FRAME_VERSION;
+}
+
+function validateEnvelope(env: Record<string, unknown>): InboundControlDecodeResult {
+  const errors: InboundControlError[] = [];
+  const kind = env.kind;
+  switch (kind) {
+    case "prompt": {
+      const text = env.text;
+      if (typeof text !== "string") {
+        errors.push({ code: "bad-prompt-text", message: "control.prompt.text must be a string" });
+        return { ok: false, errors };
+      }
+      return { ok: true, structured: true, frame: { kind: "prompt", text } };
+    }
+    case "cancel": {
+      if ("reason" in env && typeof env.reason !== "string") {
+        errors.push({ code: "bad-cancel-reason", message: "control.cancel.reason must be a string when present" });
+      }
+      if (errors.length > 0) return { ok: false, errors };
+      const frame: CancelControlFrame =
+        typeof env.reason === "string" ? { kind: "cancel", reason: env.reason } : { kind: "cancel" };
+      return { ok: true, structured: true, frame };
+    }
+    case "permission": {
+      const requestId = env.requestId;
+      const outcome = env.outcome;
+      const validRequestId = typeof requestId === "string" && requestId.length > 0 ? requestId : undefined;
+      if (validRequestId === undefined) {
+        errors.push({
+          code: "bad-permission-request-id",
+          message: "control.permission.requestId must be a non-empty string",
+        });
+      }
+      const validOutcome: PermissionOutcome | undefined =
+        outcome === "granted" || outcome === "denied" ? outcome : undefined;
+      if (validOutcome === undefined) {
+        errors.push({
+          code: "bad-permission-outcome",
+          message: "control.permission.outcome must be 'granted' or 'denied'",
+        });
+      }
+      if (errors.length > 0 || validRequestId === undefined || validOutcome === undefined) {
+        return { ok: false, errors };
+      }
+      return {
+        ok: true,
+        structured: true,
+        frame: {
+          kind: "permission",
+          requestId: validRequestId,
+          outcome: validOutcome,
+        },
+      };
+    }
+    default: {
+      const seen = kind === undefined ? "<missing>" : JSON.stringify(kind);
+      return {
+        ok: false,
+        errors: [
+          {
+            code: "bad-kind",
+            message: `control.kind must be one of prompt|cancel|permission, got ${seen}`,
+          },
+        ],
+      };
+    }
+  }
+}
+
+/**
+ * Whether `chunk` begins with a JSON object — i.e. its first character that is
+ * not JSON-insignificant whitespace (space, tab, LF, CR) is `{`. Used as a
+ * cheap, allocation-free gate before attempting a full `JSON.parse`: only a
+ * chunk that starts a JSON object can possibly be a tagged control envelope.
+ */
+function startsWithJsonObject(chunk: string): boolean {
+  for (let i = 0; i < chunk.length; i++) {
+    const code = chunk.charCodeAt(i);
+    // JSON insignificant whitespace: space (0x20), tab (0x09), LF (0x0a), CR (0x0d).
+    if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) {
+      continue;
+    }
+    return code === 0x7b; // '{'
+  }
+  return false;
+}
+
+/**
+ * Decode a raw inbound steer chunk into a typed {@link InboundControlFrame}.
+ *
+ * A chunk tagged as a control envelope is validated and returned as its typed
+ * frame (`structured: true`); a tagged-but-malformed envelope (bad/missing
+ * discriminant, missing/ill-typed field) is a validation ERROR. Any other chunk
+ * — a bare keystroke, a shell line, unrelated JSON — is treated as the legacy
+ * raw-byte steer and returned as a `prompt` whose `text` is the chunk verbatim
+ * (`structured: false`). See the module header for the full decode order.
+ */
+export function parseInboundRelayChunk(chunk: string): InboundControlDecodeResult {
+  // Fast path for the common per-keystroke steer: a control envelope is always a
+  // JSON *object*, so it must begin with `{` after any insignificant leading
+  // whitespace. Any chunk that does not is (and always was) a legacy bare-string
+  // prompt carrying the chunk verbatim, so skip the JSON.parse attempt entirely.
+  if (!startsWithJsonObject(chunk)) {
+    return { ok: true, structured: false, frame: { kind: "prompt", text: chunk } };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(chunk);
+  } catch {
+    // Started with `{` but is not valid JSON. Legacy bare-string prompt.
+    return { ok: true, structured: false, frame: { kind: "prompt", text: chunk } };
+  }
+  if (!isInboundControlEnvelope(parsed)) {
+    // Valid JSON but not a control envelope (unrelated JSON, or a plain string
+    // like "ls\n"): still a legacy bare-string prompt carrying the chunk as-is.
+    return { ok: true, structured: false, frame: { kind: "prompt", text: chunk } };
+  }
+  return validateEnvelope(parsed);
+}
+
+/**
+ * Encode a typed {@link InboundControlFrame} as its canonical wire chunk — a
+ * JSON envelope tagged with {@link CONTROL_FRAME_MARKER}. The result round-trips
+ * back through {@link parseInboundRelayChunk} to an equal frame.
+ */
+export function encodeInboundControlFrame(frame: InboundControlFrame): string {
+  const marker = { [CONTROL_FRAME_MARKER]: CONTROL_FRAME_VERSION } as const;
+  switch (frame.kind) {
+    case "prompt":
+      return JSON.stringify({ ...marker, kind: "prompt", text: frame.text });
+    case "cancel":
+      return JSON.stringify(
+        frame.reason === undefined
+          ? { ...marker, kind: "cancel" }
+          : { ...marker, kind: "cancel", reason: frame.reason },
+      );
+    case "permission":
+      return JSON.stringify({
+        ...marker,
+        kind: "permission",
+        requestId: frame.requestId,
+        outcome: frame.outcome,
+      });
+  }
+}

package/src/protocol/index.ts

@@ -85,4 +85,21 @@ export {
   type PayloadValidationResult,
 } from "./payloads.ts";
 
+export {
+  CONTROL_FRAME_MARKER,
+  CONTROL_FRAME_VERSION,
+  isInboundControlEnvelope,
+  parseInboundRelayChunk,
+  encodeInboundControlFrame,
+  type InboundControlKind,
+  type PermissionOutcome,
+  type PromptControlFrame,
+  type CancelControlFrame,
+  type PermissionControlFrame,
+  type InboundControlFrame,
+  type InboundControlError,
+  type InboundControlErrorCode,
+  type InboundControlDecodeResult,
+} from "./control.ts";
+
 export { bytesToHex, hexToBytes } from "./hex.ts";

package/src/transcript/index.ts

@@ -18,16 +18,24 @@ export type {
   Clock,
   SqliteDb,
   TranscriptChunk,
+  TranscriptContentBlock,
+  TranscriptContentType,
   TranscriptLifecycle,
   TranscriptRing,
   TranscriptSlice,
   TranscriptStatus,
   TranscriptStoreOptions,
   TranscriptStream,
+  TranscriptToolCall,
+  TranscriptTurn,
+  TranscriptTurnMetrics,
+  TranscriptTurnRole,
 } from "./store.ts";
 
 export {
   TRANSCRIPT_CHUNK_TABLE,
   TRANSCRIPT_SCHEMA_SQL,
   TRANSCRIPT_STREAM_TABLE,
+  TRANSCRIPT_TURN_SCHEMA_SQL,
+  TRANSCRIPT_TURN_TABLE,
 } from "./schema.ts";

package/src/transcript/schema.test.ts

@@ -6,6 +6,8 @@ import {
   TRANSCRIPT_CHUNK_TABLE,
   TRANSCRIPT_SCHEMA_SQL,
   TRANSCRIPT_STREAM_TABLE,
+  TRANSCRIPT_TURN_SCHEMA_SQL,
+  TRANSCRIPT_TURN_TABLE,
 } from "./schema.ts";
 import { TranscriptStore } from "./store.ts";
 import { openTestDb } from "./test-db.ts";
@@ -29,6 +31,10 @@ const migrationPath = fileURLToPath(
   new URL("../../../../db/migrations/002_agentic_transcript.sql", import.meta.url),
 );
 
+const turnMigrationPath = fileURLToPath(
+  new URL("../../../../db/migrations/008_agentic_transcript_turns.sql", import.meta.url),
+);
+
 test("the boot migration and TranscriptStore's DDL do not drift", () => {
   const migrationSql = readFileSync(migrationPath, "utf8");
   assert.equal(
@@ -53,17 +59,38 @@ test("the migration takes prefix 002, after S2's 001 and before S7", () => {
   assert.match(stream, /\/002_agentic_transcript\.sql$/);
 });
 
-test("ensureSchema creates both transcript tables idempotently", () => {
+test("the turn-view boot migration and TranscriptStore's turn DDL do not drift", () => {
+  const migrationSql = readFileSync(turnMigrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(TRANSCRIPT_TURN_SCHEMA_SQL),
+    "db/migrations/008_agentic_transcript_turns.sql must match TRANSCRIPT_TURN_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the turn-view boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(turnMigrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_transcript_turn/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+});
+
+test("the turn-view migration takes prefix 008 (next free after 007)", () => {
+  const stream = new URL("../../../../db/migrations/008_agentic_transcript_turns.sql", import.meta.url).pathname;
+  assert.match(stream, /\/008_agentic_transcript_turns\.sql$/);
+});
+
+test("ensureSchema creates all three transcript tables idempotently", () => {
   const db = openTestDb();
   const store = new TranscriptStore(db);
   store.ensureSchema();
   store.ensureSchema();
   const tables = db
     .all<{ name: string }>(
-      "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?) ORDER BY name",
-      [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE],
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?, ?) ORDER BY name",
+      [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE, TRANSCRIPT_TURN_TABLE],
     )
     .map((r) => r.name);
-  assert.deepEqual(tables, [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE]);
+  assert.deepEqual(tables, [TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_STREAM_TABLE, TRANSCRIPT_TURN_TABLE]);
   db.close();
 });

package/src/transcript/schema.ts

@@ -9,12 +9,15 @@
  * statement-for-statement identical — divergence is a red test, not a silent
  * production/boot mismatch.
  *
- * Two tables back the store:
+ * Three tables back the store:
  *  - `agentic_transcript_stream` — one row per relay stream: its retention
  *    lifecycle (`ephemeral` vs `long-lived`), its status (`open`/`completed`),
  *    and the offset window (`first_offset` … `next_offset`) currently retained.
  *  - `agentic_transcript_chunk` — the durable chunks, keyed `(stream, chunk_offset)`
  *    so a flush/append is idempotent and reattach can slice from any offset.
+ *  - `agentic_transcript_turn` — the additive turn-structured view (Camunda
+ *    `AgentHistoryRecordValue` parity, issue #475), keyed `(stream, turn_sequence)`.
+ *    It is layered over — never a replacement for — the raw chunk stream.
  *
  * `chunk_offset` (not `offset`) is deliberate: `OFFSET` is a SQLite keyword, so
  * the column is named to avoid quoting it in every statement.
@@ -26,6 +29,9 @@ export const TRANSCRIPT_STREAM_TABLE = "agentic_transcript_stream";
 /** The durable per-chunk table name. */
 export const TRANSCRIPT_CHUNK_TABLE = "agentic_transcript_chunk";
 
+/** The durable per-turn (structured-view) table name. */
+export const TRANSCRIPT_TURN_TABLE = "agentic_transcript_turn";
+
 /**
  * The canonical transcript-store DDL. Forward-only and additive; every column
  * added here must also be added to the boot migration (the drift guard enforces
@@ -49,3 +55,32 @@ CREATE TABLE IF NOT EXISTS ${TRANSCRIPT_CHUNK_TABLE} (
   PRIMARY KEY (stream, chunk_offset)
 );
 CREATE INDEX IF NOT EXISTS idx_${TRANSCRIPT_STREAM_TABLE}_retention ON ${TRANSCRIPT_STREAM_TABLE} (lifecycle, status, completed_at);`;
+
+/**
+ * The turn-structured transcript DDL — the additive, Camunda-`AgentHistoryRecordValue`
+ * parity view layered over the raw chunk stream (issue #475). It ships as its own
+ * forward-only migration `db/migrations/008_agentic_transcript_turns.sql` (the raw
+ * chunk stream in {@link TRANSCRIPT_SCHEMA_SQL} is untouched — additive, no regression
+ * to existing readers), mirrored here as the single source of truth applied by
+ * {@link TranscriptStore.ensureSchema} and kept in lockstep by a drift-guard test.
+ *
+ * One row per structured turn, keyed `(stream, turn_sequence)` so an append/re-record
+ * is idempotent (exactly the `(stream, chunk_offset)` discipline of the chunk table).
+ * `turn_sequence` is the stream-local append order and idempotency key;
+ * `loop_iteration` is the agent-loop turn counter carried as data (Camunda allows
+ * several role-split records — e.g. ASSISTANT then TOOL_RESULT — within one iteration).
+ * `content`, `tool_calls` and `metrics` hold the typed content blocks, tool calls and
+ * per-turn metrics as JSON.
+ */
+export const TRANSCRIPT_TURN_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${TRANSCRIPT_TURN_TABLE} (
+  stream         TEXT NOT NULL,
+  turn_sequence  INTEGER NOT NULL,
+  loop_iteration INTEGER NOT NULL,
+  role           TEXT NOT NULL,
+  content        TEXT NOT NULL,
+  tool_calls     TEXT NOT NULL,
+  metrics        TEXT,
+  produced_at    INTEGER,
+  recorded_at    TEXT NOT NULL,
+  PRIMARY KEY (stream, turn_sequence)
+);`;