@nanobpm/agentic 0.4.0 → 0.5.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) |
+| `@nanobpm/agentic/transcript` | Transcript store, retention-by-lifecycle (S6) + turn-structured view (Camunda `AgentHistoryRecordValue` parity) |
 | `@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) |

package/dist/transcript/index.d.ts

@@ -14,5 +14,5 @@
  * and kept in lockstep by a drift-guard test.
  */
 export { TranscriptStore, TranscriptCorruptionError, TranscriptLifecycleError, systemClock } from "./store.ts";
-export type { Clock, SqliteDb, TranscriptChunk, TranscriptLifecycle, TranscriptRing, TranscriptSlice, TranscriptStatus, TranscriptStoreOptions, TranscriptStream, } from "./store.ts";
-export { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, } from "./schema.ts";
+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/dist/transcript/index.js

@@ -14,4 +14,4 @@
  * and kept in lockstep by a drift-guard test.
  */
 export { TranscriptStore, TranscriptCorruptionError, TranscriptLifecycleError, systemClock } from "./store.js";
-export { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, } from "./schema.js";
+export { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, TRANSCRIPT_TURN_SCHEMA_SQL, TRANSCRIPT_TURN_TABLE, } from "./schema.js";

package/dist/transcript/schema.d.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.
@@ -23,6 +26,8 @@
 export declare const TRANSCRIPT_STREAM_TABLE = "agentic_transcript_stream";
 /** The durable per-chunk table name. */
 export declare const TRANSCRIPT_CHUNK_TABLE = "agentic_transcript_chunk";
+/** The durable per-turn (structured-view) table name. */
+export declare 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
@@ -30,3 +35,20 @@ export declare const TRANSCRIPT_CHUNK_TABLE = "agentic_transcript_chunk";
  * it never rewrites a chunk.
  */
 export declare const TRANSCRIPT_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_transcript_stream (\n  stream        TEXT PRIMARY KEY,\n  lifecycle     TEXT NOT NULL,\n  status        TEXT NOT NULL DEFAULT 'open',\n  created_at    TEXT NOT NULL,\n  completed_at  TEXT,\n  first_offset  INTEGER,\n  next_offset   INTEGER NOT NULL DEFAULT 0\n);\nCREATE TABLE IF NOT EXISTS agentic_transcript_chunk (\n  stream        TEXT NOT NULL,\n  chunk_offset  INTEGER NOT NULL,\n  chunk         TEXT NOT NULL,\n  appended_at   TEXT NOT NULL,\n  PRIMARY KEY (stream, chunk_offset)\n);\nCREATE INDEX IF NOT EXISTS idx_agentic_transcript_stream_retention ON agentic_transcript_stream (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 declare const TRANSCRIPT_TURN_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_transcript_turn (\n  stream         TEXT NOT NULL,\n  turn_sequence  INTEGER NOT NULL,\n  loop_iteration INTEGER NOT NULL,\n  role           TEXT NOT NULL,\n  content        TEXT NOT NULL,\n  tool_calls     TEXT NOT NULL,\n  metrics        TEXT,\n  produced_at    INTEGER,\n  recorded_at    TEXT NOT NULL,\n  PRIMARY KEY (stream, turn_sequence)\n);";

package/dist/transcript/schema.js

@@ -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.
@@ -23,6 +26,8 @@
 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
@@ -46,3 +51,31 @@ 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)
+);`;

package/dist/transcript/store.d.ts

@@ -34,6 +34,73 @@ export interface TranscriptChunk {
     readonly offset: number;
     readonly chunk: string;
 }
+/**
+ * A structured turn's author role — the additive turn-structured view's parity
+ * with Camunda `AgentHistoryRole` (issue #475). One pass through the agent loop
+ * (model reasons → selects tools → evaluates results) is recorded as one or more
+ * role-tagged turns sharing a `loopIteration`.
+ */
+export type TranscriptTurnRole = "USER" | "ASSISTANT" | "TOOL_RESULT" | "CONFIGURATION" | "UNSPECIFIED";
+/** Parity with Camunda `AgentHistoryContentType`: the type of a content block. */
+export type TranscriptContentType = "TEXT" | "DOCUMENT" | "OBJECT" | "UNSPECIFIED";
+/**
+ * A single typed content block in a turn's message, mirroring Camunda's
+ * `AgentHistoryMessageContentValue`. Exactly one payload is populated per the
+ * `contentType`: `text` for TEXT, `documentReference` for DOCUMENT, `object`
+ * (any JSON value) for OBJECT.
+ */
+export interface TranscriptContentBlock {
+    readonly contentType: TranscriptContentType;
+    /** Text payload; populated when `contentType` is TEXT. */
+    readonly text?: string;
+    /** Document reference; populated when `contentType` is DOCUMENT. */
+    readonly documentReference?: string;
+    /** JSON value payload; populated when `contentType` is OBJECT (any JSON type). */
+    readonly object?: unknown;
+}
+/**
+ * A tool call embedded in a turn, mirroring Camunda's
+ * `AgentHistoryEmbeddedToolCallValue`: `toolCallId`, `toolName`, the tool task's
+ * `elementId`, and the `arguments` passed to it.
+ */
+export interface TranscriptToolCall {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly elementId?: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+/**
+ * Per-turn metrics, mirroring Camunda's `AgentHistoryMetricsValue`: the token
+ * counts consumed/produced by the turn's LLM call and its wall-clock duration.
+ */
+export interface TranscriptTurnMetrics {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokenCount: number;
+    readonly cacheCreationTokenCount: number;
+    readonly cacheReadTokenCount: number;
+    readonly durationMs: number;
+}
+/**
+ * A structured transcript turn — the additive Camunda `AgentHistoryRecordValue`
+ * parity view (issue #475). `sequence` is the stream-local append order and the
+ * idempotency key (mirroring a chunk's `offset`); `loopIteration` is the
+ * agent-loop turn counter carried as data (several role-split turns can share one
+ * iteration). Recording turns never touches the raw chunk stream.
+ */
+export interface TranscriptTurn {
+    /** Stream-local append order + idempotency key (like a chunk's `offset`). */
+    readonly sequence: number;
+    /** The agent-loop turn counter (Camunda `loopIteration`). */
+    readonly loopIteration: number;
+    readonly role: TranscriptTurnRole;
+    readonly content: readonly TranscriptContentBlock[];
+    readonly toolCalls: readonly TranscriptToolCall[];
+    /** Per-turn metrics; undefined when the worker reported none for this turn. */
+    readonly metrics?: TranscriptTurnMetrics;
+    /** Epoch-millis timestamp the turn was produced; undefined when unreported. */
+    readonly producedAt?: number;
+}
 /** Per-stream transcript metadata. */
 export interface TranscriptStream {
     readonly stream: string;
@@ -110,9 +177,11 @@ export declare class TranscriptStore {
     get ephemeralRetentionMs(): number;
     /**
      * Apply the canonical transcript DDL (idempotent). Callers that let the app
-     * DataLayer migration runner apply `db/migrations/002_agentic_transcript.sql`
-     * do not need this — but it is provided so the store is usable against a bare
-     * source too. The DDL is identical to the migration (drift-guarded).
+     * DataLayer migration runner apply the transcript migrations
+     * (`db/migrations/002_agentic_transcript.sql` for the chunk stream and
+     * `db/migrations/008_agentic_transcript_turns.sql` for the turn-structured
+     * view) do not need this — but it is provided so the store is usable against a
+     * bare source too. The DDL is identical to the migrations (drift-guarded).
      */
     ensureSchema(): void;
     /**
@@ -163,6 +232,24 @@ export declare class TranscriptStore {
     since(stream: string, from: number): TranscriptSlice;
     /** Read a stream's whole durable transcript in offset order. */
     read(stream: string): TranscriptChunk[];
+    /**
+     * Record structured turns into a stream's additive turn-structured view — the
+     * Camunda `AgentHistoryRecordValue` parity layer (issue #475). Each turn is
+     * keyed `(stream, sequence)` so re-recording an already-stored sequence (a
+     * retry, a re-emit, an overlapping reattach) is a no-op — never a duplicate,
+     * exactly the idempotency the chunk stream gets from `(stream, offset)`.
+     *
+     * This is purely additive: it never reads or writes the raw chunk stream or the
+     * stream's offset window, so it cannot regress any existing chunk reader. It
+     * auto-opens the stream (default `long-lived`) so the turns hang off a stream
+     * row; a lifecycle mismatch throws a {@link TranscriptLifecycleError} before
+     * writing anything (lifecycle is first-wins). The batch is atomic: an invalid
+     * turn (or any failed write) partway through rolls the whole call back — it
+     * records every turn or none. Returns the number of newly-persisted turns.
+     */
+    recordTurns(stream: string, turns: Iterable<TranscriptTurn>, lifecycle?: TranscriptLifecycle): number;
+    /** Read a stream's whole turn-structured transcript in `sequence` order. */
+    readTurns(stream: string): TranscriptTurn[];
     /**
      * Apply a rolling retention window to a long-lived stream: drop every chunk with
      * `offset < before`. A subsequent {@link since} from an offset older than
@@ -174,8 +261,9 @@ export declare class TranscriptStore {
     /**
      * Retention sweep for completed ephemeral transcripts: drop every stream whose
      * `status = 'completed'` and whose `completed_at` is older than the retention
-     * window, along with its chunks. Long-lived streams are never time-swept (they
-     * are bounded by {@link truncateBefore} instead). Returns the removed stream ids.
+     * window, along with its chunks and structured turns. Long-lived streams are
+     * never time-swept (they are bounded by {@link truncateBefore} instead). Returns
+     * the removed stream ids.
      *
      * The selection and all deletes run inside a single SAVEPOINT (#atomic) so the
      * sweep is all-or-nothing: if any delete throws mid-sweep the whole batch rolls

package/dist/transcript/store.js

@@ -22,9 +22,17 @@
  * ({@link SqliteDb}), so it works against any app DataLayer source without pulling
  * in the whole runtime.
  */
-import { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE } from "./schema.js";
+import { TRANSCRIPT_CHUNK_TABLE, TRANSCRIPT_SCHEMA_SQL, TRANSCRIPT_STREAM_TABLE, TRANSCRIPT_TURN_SCHEMA_SQL, TRANSCRIPT_TURN_TABLE, } from "./schema.js";
 /** The default clock: `Date.now()`. */
 export const systemClock = { now: () => Date.now() };
+const TURN_ROLES = [
+    "USER",
+    "ASSISTANT",
+    "TOOL_RESULT",
+    "CONFIGURATION",
+    "UNSPECIFIED",
+];
+const CONTENT_TYPES = ["TEXT", "DOCUMENT", "OBJECT", "UNSPECIFIED"];
 const DEFAULT_EPHEMERAL_RETENTION_MS = 86_400_000;
 function isNonNegInt(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -63,6 +71,208 @@ function toStream(row) {
         out.firstOffset = row.first_offset;
     return out;
 }
+/**
+ * A plain JSON-shaped object: an ordinary or null-prototype object, never an array or a
+ * class instance (e.g. `Date`, `Map`). Rejecting exotic instances at the boundary stops a
+ * value that would serialise via `toJSON()` into a non-object (making the stored turn
+ * unreadable) from ever being persisted.
+ */
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function toTurnRole(value) {
+    const match = TURN_ROLES.find((role) => role === value);
+    if (match !== undefined)
+        return match;
+    throw new TranscriptCorruptionError(`invalid transcript turn role: ${JSON.stringify(value)}`);
+}
+function toContentType(value) {
+    const match = CONTENT_TYPES.find((type) => type === value);
+    if (match !== undefined)
+        return match;
+    throw new TranscriptCorruptionError(`invalid transcript content type: ${JSON.stringify(value)}`);
+}
+/**
+ * The payload key each content type carries: TEXT→`text`, DOCUMENT→`documentReference`,
+ * OBJECT→`object`; UNSPECIFIED carries none. Drives the per-`contentType` payload
+ * invariant enforced by {@link toContentBlock}.
+ */
+const CONTENT_PAYLOAD_KEYS = ["text", "documentReference", "object"];
+const CONTENT_TYPE_PAYLOAD = {
+    TEXT: "text",
+    DOCUMENT: "documentReference",
+    OBJECT: "object",
+    UNSPECIFIED: null,
+};
+/**
+ * Validate a value into a canonical content block, enforcing the per-`contentType`
+ * payload invariant: a block carries exactly the one payload its type mandates
+ * (TEXT→text, DOCUMENT→documentReference, OBJECT→object) — never a missing, mismatched
+ * or multiple payload — and UNSPECIFIED carries none. This is the single validator both
+ * the write path (record) and the read path (deserialise) run through, so the two can
+ * never drift and a malformed block can neither persist nor round-trip. It emits only
+ * that one payload key, so serialise/deserialise round-trips exactly.
+ */
+function toContentBlock(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript content block must be an object, got ${JSON.stringify(value)}`);
+    }
+    const contentType = toContentType(value.contentType);
+    const present = CONTENT_PAYLOAD_KEYS.filter((key) => key in value && value[key] !== undefined);
+    const expected = CONTENT_TYPE_PAYLOAD[contentType];
+    if (expected === null) {
+        if (present.length > 0) {
+            throw new TranscriptCorruptionError(`${contentType} content block must carry no payload, got ${JSON.stringify(present)}`);
+        }
+        return { contentType };
+    }
+    if (present.length !== 1 || present[0] !== expected) {
+        throw new TranscriptCorruptionError(`${contentType} content block must carry exactly its ${expected} payload, got ${JSON.stringify(present)}`);
+    }
+    if (expected === "text") {
+        const text = value.text;
+        if (typeof text !== "string") {
+            throw new TranscriptCorruptionError(`content block text must be a string, got ${JSON.stringify(text)}`);
+        }
+        return { contentType, text };
+    }
+    if (expected === "documentReference") {
+        const documentReference = value.documentReference;
+        if (typeof documentReference !== "string") {
+            throw new TranscriptCorruptionError(`content block documentReference must be a string, got ${JSON.stringify(documentReference)}`);
+        }
+        return { contentType, documentReference };
+    }
+    return { contentType, object: value.object };
+}
+/**
+ * Validate a value into a canonical tool call — the single validator both the write and
+ * read paths run through. Mirrors Camunda's `AgentHistoryEmbeddedToolCallValue`.
+ */
+function toToolCall(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript tool call must be an object, got ${JSON.stringify(value)}`);
+    }
+    const { toolCallId, toolName, elementId } = value;
+    if (typeof toolCallId !== "string") {
+        throw new TranscriptCorruptionError(`tool call toolCallId must be a string, got ${JSON.stringify(toolCallId)}`);
+    }
+    if (typeof toolName !== "string") {
+        throw new TranscriptCorruptionError(`tool call toolName must be a string, got ${JSON.stringify(toolName)}`);
+    }
+    const args = value.arguments;
+    if (!isPlainObject(args)) {
+        throw new TranscriptCorruptionError(`tool call arguments must be an object, got ${JSON.stringify(args)}`);
+    }
+    const out = {
+        toolCallId,
+        toolName,
+        arguments: args,
+    };
+    if (elementId !== undefined) {
+        if (typeof elementId !== "string") {
+            throw new TranscriptCorruptionError(`tool call elementId must be a string, got ${JSON.stringify(elementId)}`);
+        }
+        out.elementId = elementId;
+    }
+    return out;
+}
+function readMetric(source, key) {
+    const value = source[key];
+    if (!isNonNegInt(value)) {
+        throw new TranscriptCorruptionError(`transcript metric "${key}" must be a non-negative safe integer, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * Validate a value into canonical per-turn metrics — the single validator both the write
+ * and read paths run through. Every field must be a non-negative safe integer: Camunda's
+ * `AgentHistoryMetricsValue` token counts and `durationMs` are integer-valued and cannot be
+ * negative, so an out-of-domain value is treated as corruption rather than round-tripped.
+ */
+function toMetrics(value) {
+    if (!isPlainObject(value)) {
+        throw new TranscriptCorruptionError(`transcript turn metrics must be an object, got ${JSON.stringify(value)}`);
+    }
+    return {
+        inputTokens: readMetric(value, "inputTokens"),
+        outputTokens: readMetric(value, "outputTokens"),
+        reasoningTokenCount: readMetric(value, "reasoningTokenCount"),
+        cacheCreationTokenCount: readMetric(value, "cacheCreationTokenCount"),
+        cacheReadTokenCount: readMetric(value, "cacheReadTokenCount"),
+        durationMs: readMetric(value, "durationMs"),
+    };
+}
+/**
+ * Parse a JSON column, re-raising a malformed-JSON `SyntaxError` as a
+ * {@link TranscriptCorruptionError} so every read-back failure surfaces through the store's
+ * single corruption signal rather than a raw parse error.
+ */
+function parseJsonColumn(json, label) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (err) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Parse a JSON array column, failing with a corruption error on invalid JSON or non-arrays. */
+function parseJsonArray(json, label) {
+    const parsed = parseJsonColumn(json, label);
+    if (!Array.isArray(parsed)) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} must be a JSON array, got ${JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+/**
+ * Serialise a validated turn payload for storage, re-raising a non-serialisable value
+ * (e.g. a `bigint`, which makes `JSON.stringify` throw a `TypeError`) as a
+ * {@link TranscriptCorruptionError} so the untyped write boundary only ever surfaces the
+ * store's own error taxonomy.
+ */
+function stringifyJson(value, label) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch (err) {
+        throw new TranscriptCorruptionError(`transcript turn ${label} is not JSON-serialisable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Reconstruct a structured turn from its DB row, validating every field so a corrupted
+ * or hand-edited row fails fast with a {@link TranscriptCorruptionError} rather than
+ * silently propagating an out-of-domain value. `turn_sequence`, `loop_iteration` and
+ * `produced_at` are held to the same non-negative-safe-integer domain the write path
+ * enforces.
+ */
+function toTurn(row) {
+    if (!isRecordableOffset(row.turn_sequence)) {
+        throw new TranscriptCorruptionError(`transcript turn sequence must be a non-negative safe integer, got ${JSON.stringify(row.turn_sequence)}`);
+    }
+    if (!isNonNegInt(row.loop_iteration)) {
+        throw new TranscriptCorruptionError(`transcript turn loopIteration must be a non-negative safe integer, got ${JSON.stringify(row.loop_iteration)}`);
+    }
+    const out = {
+        sequence: row.turn_sequence,
+        loopIteration: row.loop_iteration,
+        role: toTurnRole(row.role),
+        content: parseJsonArray(row.content, "content").map(toContentBlock),
+        toolCalls: parseJsonArray(row.tool_calls, "toolCalls").map(toToolCall),
+    };
+    if (row.metrics !== null) {
+        out.metrics = toMetrics(parseJsonColumn(row.metrics, "metrics"));
+    }
+    if (row.produced_at !== null) {
+        if (!isNonNegInt(row.produced_at)) {
+            throw new TranscriptCorruptionError(`transcript turn producedAt must be a non-negative safe integer, got ${JSON.stringify(row.produced_at)}`);
+        }
+        out.producedAt = row.produced_at;
+    }
+    return out;
+}
 /**
  * Raised when a transcript row read back from storage holds a value outside its
  * domain (e.g. an unknown `lifecycle`/`status`), signalling schema corruption or a
@@ -106,12 +316,15 @@ export class TranscriptStore {
     }
     /**
      * Apply the canonical transcript DDL (idempotent). Callers that let the app
-     * DataLayer migration runner apply `db/migrations/002_agentic_transcript.sql`
-     * do not need this — but it is provided so the store is usable against a bare
-     * source too. The DDL is identical to the migration (drift-guarded).
+     * DataLayer migration runner apply the transcript migrations
+     * (`db/migrations/002_agentic_transcript.sql` for the chunk stream and
+     * `db/migrations/008_agentic_transcript_turns.sql` for the turn-structured
+     * view) do not need this — but it is provided so the store is usable against a
+     * bare source too. The DDL is identical to the migrations (drift-guarded).
      */
     ensureSchema() {
         this.#db.exec(TRANSCRIPT_SCHEMA_SQL);
+        this.#db.exec(TRANSCRIPT_TURN_SCHEMA_SQL);
     }
     /**
      * Open (or fetch) a stream's transcript with the given lifecycle. Idempotent:
@@ -228,6 +441,72 @@ export class TranscriptStore {
             .all(`SELECT chunk_offset, chunk FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ? ORDER BY chunk_offset`, [stream])
             .map((r) => ({ offset: r.chunk_offset, chunk: r.chunk }));
     }
+    /**
+     * Record structured turns into a stream's additive turn-structured view — the
+     * Camunda `AgentHistoryRecordValue` parity layer (issue #475). Each turn is
+     * keyed `(stream, sequence)` so re-recording an already-stored sequence (a
+     * retry, a re-emit, an overlapping reattach) is a no-op — never a duplicate,
+     * exactly the idempotency the chunk stream gets from `(stream, offset)`.
+     *
+     * This is purely additive: it never reads or writes the raw chunk stream or the
+     * stream's offset window, so it cannot regress any existing chunk reader. It
+     * auto-opens the stream (default `long-lived`) so the turns hang off a stream
+     * row; a lifecycle mismatch throws a {@link TranscriptLifecycleError} before
+     * writing anything (lifecycle is first-wins). The batch is atomic: an invalid
+     * turn (or any failed write) partway through rolls the whole call back — it
+     * records every turn or none. Returns the number of newly-persisted turns.
+     */
+    recordTurns(stream, turns, lifecycle = "long-lived") {
+        const meta = this.open(stream, lifecycle);
+        if (meta.lifecycle !== lifecycle) {
+            throw new TranscriptLifecycleError(stream, `refusing to record turns into "${stream}" with lifecycle=${lifecycle}; the stream is ${meta.lifecycle} (lifecycle is first-wins)`);
+        }
+        const at = new Date(this.#clock.now()).toISOString();
+        return this.#atomic(() => {
+            let written = 0;
+            for (const turn of turns) {
+                if (!isPlainObject(turn)) {
+                    throw new TranscriptCorruptionError(`transcript turn must be an object, got ${JSON.stringify(turn)}`);
+                }
+                if (!isRecordableOffset(turn.sequence)) {
+                    throw new RangeError(`transcript turn sequence must be a non-negative safe integer below Number.MAX_SAFE_INTEGER, got ${turn.sequence}`);
+                }
+                if (!isNonNegInt(turn.loopIteration)) {
+                    throw new RangeError(`transcript turn loopIteration must be a non-negative safe integer, got ${turn.loopIteration}`);
+                }
+                const role = toTurnRole(turn.role);
+                if (!Array.isArray(turn.content)) {
+                    throw new TranscriptCorruptionError(`transcript turn content must be an array, got ${JSON.stringify(turn.content)}`);
+                }
+                if (!Array.isArray(turn.toolCalls)) {
+                    throw new TranscriptCorruptionError(`transcript turn toolCalls must be an array, got ${JSON.stringify(turn.toolCalls)}`);
+                }
+                const content = stringifyJson(turn.content.map(toContentBlock), "content");
+                const toolCalls = stringifyJson(turn.toolCalls.map(toToolCall), "toolCalls");
+                const metrics = turn.metrics === undefined ? null : stringifyJson(toMetrics(turn.metrics), "metrics");
+                let producedAt = null;
+                if (turn.producedAt !== undefined) {
+                    if (!isNonNegInt(turn.producedAt)) {
+                        throw new RangeError(`transcript turn producedAt must be a non-negative safe integer (epoch millis), got ${turn.producedAt}`);
+                    }
+                    producedAt = turn.producedAt;
+                }
+                const { changes } = this.#db.run(`INSERT INTO ${TRANSCRIPT_TURN_TABLE}
+             (stream, turn_sequence, loop_iteration, role, content, tool_calls, metrics, produced_at, recorded_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(stream, turn_sequence) DO NOTHING`, [stream, turn.sequence, turn.loopIteration, role, content, toolCalls, metrics, producedAt, at]);
+                written += changes;
+            }
+            return written;
+        });
+    }
+    /** Read a stream's whole turn-structured transcript in `sequence` order. */
+    readTurns(stream) {
+        return this.#db
+            .all(`SELECT turn_sequence, loop_iteration, role, content, tool_calls, metrics, produced_at
+         FROM ${TRANSCRIPT_TURN_TABLE} WHERE stream = ? ORDER BY turn_sequence`, [stream])
+            .map(toTurn);
+    }
     /**
      * Apply a rolling retention window to a long-lived stream: drop every chunk with
      * `offset < before`. A subsequent {@link since} from an offset older than
@@ -253,8 +532,9 @@ export class TranscriptStore {
     /**
      * Retention sweep for completed ephemeral transcripts: drop every stream whose
      * `status = 'completed'` and whose `completed_at` is older than the retention
-     * window, along with its chunks. Long-lived streams are never time-swept (they
-     * are bounded by {@link truncateBefore} instead). Returns the removed stream ids.
+     * window, along with its chunks and structured turns. Long-lived streams are
+     * never time-swept (they are bounded by {@link truncateBefore} instead). Returns
+     * the removed stream ids.
      *
      * The selection and all deletes run inside a single SAVEPOINT (#atomic) so the
      * sweep is all-or-nothing: if any delete throws mid-sweep the whole batch rolls
@@ -271,6 +551,7 @@ export class TranscriptStore {
                 .map((r) => r.stream);
             for (const stream of removed) {
                 this.#db.run(`DELETE FROM ${TRANSCRIPT_CHUNK_TABLE} WHERE stream = ?`, [stream]);
+                this.#db.run(`DELETE FROM ${TRANSCRIPT_TURN_TABLE} WHERE stream = ?`, [stream]);
                 this.#db.run(`DELETE FROM ${TRANSCRIPT_STREAM_TABLE} WHERE stream = ?`, [stream]);
             }
             return removed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/agentic",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Nano agentic protocol (ADR 0056): one app-tier channel carrying agent presence/registry, demand×supply, a shared blackboard and live terminal relay — with the wire contract, channel/hub, family modules and the operator cockpit, as subpath exports.",
   "license": "Apache-2.0",
   "type": "module",

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";