@nanobpm/agentic 0.1.0 → 0.5.0

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

@@ -0,0 +1,180 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { parseSessionEvent, type SessionEvent } from "../events.ts";
+import { normalizeSession } from "./link.ts";
+import { FLEET_NORMALIZERS } from "./index.ts";
+import type { DistributiveOmit, HarnessNormalizer } from "./types.ts";
+import { copilotNormalizer } from "./copilot.ts";
+import { claudeNormalizer } from "./claude.ts";
+import { qwenNormalizer } from "./qwen.ts";
+import { kimiNormalizer } from "./kimi.ts";
+import { piNormalizer } from "./pi.ts";
+import { deepseekNormalizer } from "./deepseek.ts";
+
+/**
+ * The shared canonical scenario every dialect must map onto (ADR 0062 slice 3
+ * acceptance: "shared normalization test vectors validate every dialect maps
+ * onto the same canonical SessionEvent shape"). It is the *semantic* projection —
+ * the canonical union payload minus the causal-chain fields (`id`/`parentId`),
+ * which the shared linker assigns and a separate test checks. A native transcript
+ * from *any* harness in the fleet, when normalized, must equal this exactly.
+ */
+const CANONICAL: readonly DistributiveOmit<SessionEvent, "id" | "parentId">[] = [
+  { type: "user", text: "please refactor the parser" },
+  { type: "reasoning", text: "weighing two approaches", providerContinuation: "OPAQUE-CONT" },
+  { type: "assistant", text: "here is the plan" },
+  { type: "tool-call", callId: "t1", name: "write_file", args: { path: "a.ts" } },
+  { type: "tool-result", callId: "t1", ok: true, result: "written" },
+  { type: "usage", inputTokens: 100, outputTokens: 50, model: "m-1" },
+];
+
+/** One dialect's native transcript that must normalize to {@link CANONICAL}. */
+interface Vector {
+  readonly normalizer: HarnessNormalizer;
+  readonly records: readonly unknown[];
+}
+
+const VECTORS: readonly Vector[] = [
+  {
+    // @github/copilot — copilot-sdk SessionEvent stream. reasoningOpaque is the
+    // provider reasoning-continuation blob (ADR 0062 §5 resume-critical fidelity).
+    normalizer: copilotNormalizer,
+    records: [
+      { type: "user_message", text: "please refactor the parser" },
+      { type: "reasoning", text: "weighing two approaches", reasoningOpaque: "OPAQUE-CONT" },
+      { type: "assistant_message", text: "here is the plan" },
+      { type: "tool_call", id: "t1", name: "write_file", arguments: { path: "a.ts" } },
+      { type: "tool_result", id: "t1", output: "written" },
+      { type: "usage", inputTokens: 100, outputTokens: 50, model: "m-1" },
+    ],
+  },
+  {
+    // Claude Code — `-p --output-format stream-json`. thinking.signature is the
+    // encrypted reasoning-continuation token; usage rides the terminal `result`.
+    normalizer: claudeNormalizer,
+    records: [
+      { type: "user", message: { role: "user", content: [{ type: "text", text: "please refactor the parser" }] } },
+      {
+        type: "assistant",
+        message: {
+          role: "assistant",
+          content: [
+            { type: "thinking", thinking: "weighing two approaches", signature: "OPAQUE-CONT" },
+            { type: "text", text: "here is the plan" },
+            { type: "tool_use", id: "t1", name: "write_file", input: { path: "a.ts" } },
+          ],
+        },
+      },
+      { type: "user", message: { role: "user", content: [{ type: "tool_result", tool_use_id: "t1", content: "written" }] } },
+      { type: "result", subtype: "success", model: "m-1", usage: { input_tokens: 100, output_tokens: 50 } },
+    ],
+  },
+  {
+    // Qwen Code — `-p -o stream-json` (Gemini-CLI lineage).
+    normalizer: qwenNormalizer,
+    records: [
+      { type: "content", role: "user", text: "please refactor the parser" },
+      { type: "thought", description: "weighing two approaches", thoughtSignature: "OPAQUE-CONT" },
+      { type: "content", role: "model", text: "here is the plan" },
+      { type: "tool_call_request", callId: "t1", name: "write_file", args: { path: "a.ts" } },
+      { type: "tool_call_response", callId: "t1", responseParts: "written" },
+      { type: "usage_metadata", promptTokenCount: 100, candidatesTokenCount: 50, model: "m-1" },
+    ],
+  },
+  {
+    // Kimi — `-p --output-format stream-json` (event/phase discriminated).
+    normalizer: kimiNormalizer,
+    records: [
+      { event: "text", role: "user", text: "please refactor the parser" },
+      { event: "reasoning", text: "weighing two approaches", continuation: "OPAQUE-CONT" },
+      { event: "text", role: "assistant", text: "here is the plan" },
+      { event: "tool", phase: "call", id: "t1", name: "write_file", arguments: { path: "a.ts" } },
+      { event: "tool", phase: "result", id: "t1", ok: true, output: "written" },
+      { event: "usage", prompt_tokens: 100, completion_tokens: 50, model: "m-1" },
+    ],
+  },
+  {
+    // pi / little-coder — `-p --mode json` (JSON-RPC notifications).
+    normalizer: piNormalizer,
+    records: [
+      { jsonrpc: "2.0", method: "session/message", params: { role: "user", text: "please refactor the parser" } },
+      { jsonrpc: "2.0", method: "session/reasoning", params: { text: "weighing two approaches", continuation: "OPAQUE-CONT" } },
+      { jsonrpc: "2.0", method: "session/message", params: { role: "assistant", text: "here is the plan" } },
+      { jsonrpc: "2.0", method: "session/toolCall", params: { id: "t1", name: "write_file", args: { path: "a.ts" } } },
+      { jsonrpc: "2.0", method: "session/toolResult", params: { id: "t1", ok: true, result: "written" } },
+      { jsonrpc: "2.0", method: "session/usage", params: { inputTokens: 100, outputTokens: 50, model: "m-1" } },
+    ],
+  },
+  {
+    // DeepSeek Harness — live SessionEvent feed (kind-tagged).
+    normalizer: deepseekNormalizer,
+    records: [
+      { kind: "message", role: "user", content: "please refactor the parser" },
+      { kind: "reasoning", content: "weighing two approaches", continuation: "OPAQUE-CONT" },
+      { kind: "message", role: "assistant", content: "here is the plan" },
+      { kind: "tool", id: "t1", name: "write_file", arguments: { path: "a.ts" } },
+      { kind: "tool_result", id: "t1", ok: true, output: "written" },
+      { kind: "usage", input: 100, output: 50, model: "m-1" },
+    ],
+  },
+];
+
+/** Strip the linker-assigned causal-chain fields to get the semantic projection. */
+function semantic(event: SessionEvent): DistributiveOmit<SessionEvent, "id" | "parentId"> {
+  const { id: _id, parentId: _parentId, ...rest } = event;
+  return rest;
+}
+
+// Every dialect in the fleet has a vector (no harness ships without a test vector).
+// Compare the harness-id *sets* (not just counts) and assert vector uniqueness, so a
+// duplicated vector masking a missing normalizer cannot slip through a length check.
+test("every fleet normalizer has a shared test vector", () => {
+  const vectorHarnesses = VECTORS.map((v) => v.normalizer.harness).sort();
+  const fleetHarnesses = FLEET_NORMALIZERS.map((n) => n.harness).sort();
+  assert.equal(new Set(vectorHarnesses).size, vectorHarnesses.length, "each harness must have a unique shared test vector (no duplicates)");
+  assert.deepEqual(vectorHarnesses, fleetHarnesses, "the set of test-vector harnesses must match the fleet exactly");
+});
+
+for (const { normalizer, records } of VECTORS) {
+  test(`[${normalizer.harness}] native transcript normalizes onto the shared canonical shape`, () => {
+    const events = normalizeSession(normalizer, records);
+    assert.deepEqual(events.map(semantic), CANONICAL, "dialect must map onto the identical canonical SessionEvent shape");
+  });
+
+  test(`[${normalizer.harness}] normalized events form a well-formed causal chain`, () => {
+    const events = normalizeSession(normalizer, records);
+    assert.equal(events[0].parentId, null, "first event starts a fresh chain");
+    const ids = new Set<string>();
+    for (let i = 0; i < events.length; i++) {
+      assert.equal(typeof events[i].id, "string");
+      assert.ok(!ids.has(events[i].id), "ids are unique");
+      ids.add(events[i].id);
+      if (i > 0) assert.equal(events[i].parentId, events[i - 1].id, "parentId links to the prior event");
+      // The whole event re-validates against the slice-1 storage boundary.
+      assert.deepEqual(parseSessionEvent(events[i]), events[i]);
+    }
+  });
+
+  test(`[${normalizer.harness}] preserves the resume-critical provider reasoning continuation`, () => {
+    const events = normalizeSession(normalizer, records);
+    const reasoning = events.find((e) => e.type === "reasoning");
+    assert.ok(reasoning && reasoning.type === "reasoning");
+    assert.equal(reasoning.providerContinuation, "OPAQUE-CONT", "the opaque reasoning blob must survive normalization");
+  });
+}
+
+test("a resume continues the same causal chain across the boundary", () => {
+  // First leg produces a chain; the resumed leg is threaded onto the last id, so
+  // offset-free causality is preserved across the resume (parentId, not offset).
+  const first = normalizeSession(copilotNormalizer, [
+    { type: "user_message", text: "hi" },
+    { type: "assistant_message", text: "hello" },
+  ]);
+  const lastId = first[first.length - 1].id;
+  const resumed = normalizeSession(
+    copilotNormalizer,
+    [{ type: "user_message", text: "continue" }],
+    { parentId: lastId, newId: (() => { let n = 0; return () => `r-${n++}`; })() },
+  );
+  assert.equal(resumed[0].parentId, lastId, "the resumed transcript continues the pre-resume chain");
+});

package/src/session/schema.test.ts

@@ -0,0 +1,84 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import {
+  SESSION_CHECKPOINT_TABLE,
+  SESSION_EVENT_TABLE,
+  SESSION_LOG_TABLE,
+  SESSION_SCHEMA_SQL,
+} from "./schema.ts";
+import { SqliteSessionLog } from "./log.ts";
+import { openTestDb } from "./test-db.ts";
+
+/**
+ * Normalise SQL for a drift comparison: drop `-- …` line comments, collapse
+ * whitespace runs to one space, trim. Two DDL scripts that create the same
+ * objects normalise identically regardless of comments/indentation.
+ */
+function normaliseSql(sql: string): string {
+  return sql
+    .split("\n")
+    .map((line) => line.replace(/--.*$/, ""))
+    .join("\n")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const migrationPath = fileURLToPath(
+  new URL("../../../../db/migrations/005_agentic_session.sql", import.meta.url),
+);
+
+test("the boot migration and SqliteSessionLog's DDL do not drift", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.equal(
+    normaliseSql(migrationSql),
+    normaliseSql(SESSION_SCHEMA_SQL),
+    "db/migrations/005_agentic_session.sql must match SESSION_SCHEMA_SQL — update both together",
+  );
+});
+
+test("the boot migration is forward-only and additive (IF NOT EXISTS, no drops/alters)", () => {
+  const migrationSql = readFileSync(migrationPath, "utf8");
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_session_log/);
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_session_event/);
+  assert.match(migrationSql, /CREATE TABLE IF NOT EXISTS agentic_session_checkpoint/);
+  assert.doesNotMatch(migrationSql, /\bDROP\b/i);
+  assert.doesNotMatch(migrationSql, /\bALTER\b/i);
+});
+
+test("the migration takes prefix 005, after 004_urban_lineage", () => {
+  assert.match(migrationPath, /\/005_agentic_session\.sql$/);
+});
+
+test("ensureSchema creates all three session tables idempotently", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  log.ensureSchema();
+  const tables = db
+    .all<{ name: string }>(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?, ?) ORDER BY name",
+      [SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE],
+    )
+    .map((r) => r.name);
+  assert.deepEqual(tables, [SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE].sort());
+});
+
+test("the production build excludes the test-only sqlite helper (it is never published)", () => {
+  // Guards the failure-mode class the `test-db.ts` header documents: a test-only
+  // helper must not leak into the emitted `dist`. The comment claims exclusion via
+  // `tsconfig.build.json`; this asserts the config actually honours it.
+  const buildTsconfigPath = fileURLToPath(new URL("../../tsconfig.build.json", import.meta.url));
+  const buildTsconfig: unknown = JSON.parse(readFileSync(buildTsconfigPath, "utf8"));
+  assert.ok(
+    buildTsconfig !== null && typeof buildTsconfig === "object" && "exclude" in buildTsconfig,
+    "tsconfig.build.json must declare an exclude list",
+  );
+  const exclude = buildTsconfig.exclude;
+  assert.ok(Array.isArray(exclude), "tsconfig.build.json exclude must be an array");
+  assert.ok(
+    exclude.includes("**/test-db.ts"),
+    "tsconfig.build.json must exclude **/test-db.ts so the test-only helper is not shipped",
+  );
+});

package/src/session/schema.ts

@@ -0,0 +1,78 @@
+/**
+ * The canonical authoritative session-log schema — ADR 0062, slice 1.
+ *
+ * The DDL here is the single source of truth {@link SqliteSessionLog.ensureSchema}
+ * applies, and is mirrored statement-for-statement by the app-boot migration
+ * `db/migrations/005_agentic_session.sql`. `schema.test.ts` normalises both and
+ * asserts they are identical — drift is a red test, not a silent boot mismatch.
+ * This mirrors the S6 transcript store's drift-guard exactly (ADR 0056 §12), the
+ * advisory precedent this authoritative log is promoted from.
+ *
+ * Three tables back the log:
+ *  - `agentic_session_log` — one row per **activation** `(processInstanceKey,
+ *    elementId)`: its fence high-water (`incarnation`), retention lifecycle,
+ *    status, and the retained offset window (`first_offset` … `next_offset`).
+ *  - `agentic_session_event` — the durable, authoritative events, keyed
+ *    `(process_instance_key, element_id, event_offset)` so a re-lease can replay
+ *    from any offset and a resuming incarnation can overwrite an uncommitted tail
+ *    idempotently.
+ *  - `agentic_session_checkpoint` — the mind/world join points, keyed
+ *    `(process_instance_key, element_id, checkpoint_id)` with the pinned offset.
+ *
+ * `event_offset`/`checkpoint_offset` (not `offset`) is deliberate: `OFFSET` is a
+ * SQLite keyword, so the columns are named to avoid quoting it everywhere.
+ */
+
+/** The per-activation metadata + fence table name. */
+export const SESSION_LOG_TABLE = "agentic_session_log";
+
+/** The durable per-event table name. */
+export const SESSION_EVENT_TABLE = "agentic_session_event";
+
+/** The checkpoint table name. */
+export const SESSION_CHECKPOINT_TABLE = "agentic_session_checkpoint";
+
+/**
+ * The canonical session-log DDL. Forward-only and additive; every column added
+ * here must also be added to the boot migration (the drift guard enforces it).
+ * Events are immutable once committed under an incarnation; a resume overwrites
+ * only the *uncommitted* tail past the last checkpoint (a re-key at the same
+ * `(activation, offset)`), never a committed row.
+ */
+export const SESSION_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${SESSION_LOG_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  incarnation           INTEGER NOT NULL DEFAULT 0,
+  lifecycle             TEXT NOT NULL DEFAULT 'activation',
+  status                TEXT NOT NULL DEFAULT 'open',
+  created_at            TEXT NOT NULL,
+  completed_at          TEXT,
+  first_offset          INTEGER,
+  next_offset           INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (process_instance_key, element_id)
+);
+CREATE TABLE IF NOT EXISTS ${SESSION_EVENT_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  event_offset          INTEGER NOT NULL,
+  incarnation           INTEGER NOT NULL,
+  event_id              TEXT NOT NULL,
+  parent_id             TEXT,
+  event_type            TEXT NOT NULL,
+  payload               TEXT NOT NULL,
+  appended_at           TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key, element_id, event_offset)
+);
+CREATE TABLE IF NOT EXISTS ${SESSION_CHECKPOINT_TABLE} (
+  process_instance_key  TEXT NOT NULL,
+  element_id            TEXT NOT NULL,
+  checkpoint_id         TEXT NOT NULL,
+  checkpoint_offset     INTEGER NOT NULL,
+  incarnation           INTEGER NOT NULL,
+  commit_sha            TEXT NOT NULL,
+  effect_ledger         TEXT NOT NULL,
+  created_at            TEXT NOT NULL,
+  PRIMARY KEY (process_instance_key, element_id, checkpoint_id)
+);
+CREATE INDEX IF NOT EXISTS idx_${SESSION_CHECKPOINT_TABLE}_offset ON ${SESSION_CHECKPOINT_TABLE} (process_instance_key, element_id, checkpoint_offset);
+CREATE INDEX IF NOT EXISTS idx_${SESSION_LOG_TABLE}_retention ON ${SESSION_LOG_TABLE} (lifecycle, status, completed_at);`;

package/src/session/test-db.ts

@@ -0,0 +1,56 @@
+/**
+ * Test-only helper: a {@link SqliteDb} backed by an in-memory `node:sqlite`
+ * database, mirroring the Node host adapter's `wrapNodeSqlite` (and the identical
+ * helper in @nanobpm/agentic's presence/transcript families). Kept out of the
+ * published build (see `tsconfig.build.json` exclude) — it exists solely so the
+ * durable-log tests exercise the store against a real SQLite engine, not a mock.
+ */
+import type { TestContext } from "node:test";
+import { DatabaseSync } from "node:sqlite";
+import type { SqliteDb } from "./log.ts";
+
+export interface TestDb extends SqliteDb {
+  close(): void;
+}
+
+function toParams(params: unknown[]): (string | number | bigint | null | Uint8Array)[] {
+  return params.map((p) => {
+    if (p === null) return null;
+    if (typeof p === "string" || typeof p === "number" || typeof p === "bigint" || p instanceof Uint8Array) {
+      return p;
+    }
+    if (typeof p === "boolean") return p ? 1 : 0;
+    throw new TypeError(`unsupported SQLite parameter type: ${typeof p}`);
+  });
+}
+
+/**
+ * Open an in-memory test database. Pass the test's {@link TestContext} to make
+ * the DB close automatically when the test finishes (`t.after`) — the single
+ * canonical cleanup path, so no test can leak an open SQLite handle by forgetting
+ * to call `close()`. `close()` is idempotent, so an explicit call is still safe.
+ */
+export function openTestDb(t?: TestContext): TestDb {
+  const db = new DatabaseSync(":memory:");
+  let closed = false;
+  const close = (): void => {
+    if (closed) return;
+    closed = true;
+    db.close();
+  };
+  t?.after(close);
+  return {
+    exec: (sql) => db.exec(sql),
+    run: (sql, params = []) => {
+      const stmt = db.prepare(sql);
+      const r = stmt.run(...toParams(params));
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid };
+    },
+    all: <T>(sql: string, params: unknown[] = []): T[] => {
+      const stmt = db.prepare(sql);
+      // biome-ignore lint/plugin: Node sqlite returns untyped row objects; SqliteDb.all<T> is the host adapter boundary.
+      return stmt.all(...toParams(params)) as T[];
+    },
+    close,
+  };
+}

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)
+);`;