@nanobpm/agentic 0.1.0 → 0.5.0

package/dist/session/normalizer/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The `@nanobpm/agentic/session/normalizer` contract — ADR 0062, slice 3 (the
+ * `stream-json`/native-transcript **fallback** ingestion backend).
+ *
+ * Slice 2 speaks ACP directly; this slice covers every harness that does *not*
+ * (yet) speak ACP. ADR 0062 §5 frames `stream-json` as a *transport with N
+ * vendor dialects*, so there is no single "stream-json backend": each harness
+ * gets a small **normalizer** that maps its native/streaming session output onto
+ * Nano's canonical {@link SessionEvent} (slice 1), plus a **resume shim** over
+ * that harness's native `--resume <id>` (or SDK equivalent).
+ *
+ * The three moving parts a harness normalizer exposes:
+ *
+ *  - {@link HarnessNormalizer.toDrafts} — the dialect map: one native record →
+ *    zero-or-more {@link DraftEvent}s (canonical events *minus* the causal-chain
+ *    fields the shared {@link linkDrafts} threads in, so a per-harness dialect
+ *    never re-implements chaining).
+ *  - {@link HarnessNormalizer.resume} — the resume shim: given a native session
+ *    id, the exact native invocation ({@link ResumeShim}) that restores it.
+ *  - {@link HarnessNormalizer.capabilities} — the {@link HarnessCapabilities}
+ *    the {@link capabilityProbe} folds into a `durable-resume` advertisement
+ *    (slice 5's enrolment gate reads this).
+ *
+ * Nothing here interprets a harness schema as *ours*: the native shapes are
+ * ingestion details owned entirely by each dialect module; the union they all
+ * target is the stable slice-1 contract.
+ */
+import type { SessionEvent } from "../events.ts";
+/**
+ * Distributive `Omit` over a discriminated union: applies `Omit` to *each* union
+ * member, preserving the `type` discriminant. A plain `Omit<Union, K>` collapses
+ * to the members' common properties (losing the per-member fields), so we cannot
+ * use it to describe "a session event without its chain fields".
+ */
+export type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+/**
+ * A canonical {@link SessionEvent} as a dialect first produces it — the full
+ * semantic payload (`type` + type-specific fields) but *without* the causal-chain
+ * responsibilities (`parentId`, and an optional-only `id`). The shared
+ * {@link linkDrafts} threads `parentId` in emission order and fills any missing
+ * `id`, so an individual dialect never re-implements chain bookkeeping; it just
+ * says "here is the event this record means". A dialect that already knows a
+ * stable native id (a tool-call id, a provider message id) may supply it as
+ * `id` to preserve correlation across a resume.
+ */
+export type DraftEvent = DistributiveOmit<SessionEvent, "id" | "parentId"> & {
+    readonly id?: string;
+};
+/**
+ * The native resume invocation a harness's shim resolves for a session id. Two
+ * transports cover the fleet:
+ *
+ *  - `cli` — a flag-driven harness: `args` are the argv tail to append to the
+ *    harness command to resume that session (e.g. Claude's `["--resume", id]`,
+ *    Qwen's `["-r", id]`). Nano spawns; it never parses the harness's output
+ *    beyond the dialect map.
+ *  - `sdk` — an in-process harness (Copilot's `copilot-sdk`, the DeepSeek live
+ *    feed): `call` names the SDK method and `args` are its arguments (e.g.
+ *    `resumeSession(id)`), so the host invokes it directly rather than spawning.
+ *
+ * `sessionId` echoes the id the shim resumed, so a caller that only kept the
+ * {@link ResumeShim} still knows which session it targets.
+ */
+export type ResumeShim = {
+    readonly transport: "cli";
+    readonly sessionId: string;
+    readonly args: readonly string[];
+} | {
+    readonly transport: "sdk";
+    readonly sessionId: string;
+    readonly call: string;
+    readonly args: readonly unknown[];
+};
+/**
+ * What a harness can do, from the perspective of durable resume. `streaming` is
+ * "exposes a machine-readable streaming/native mind source we can normalize";
+ * `resumeById` is "can restore a *specific* prior session by id" (not merely
+ * `--continue` the latest). {@link CapabilityAdvertisement.durableResume} is
+ * derived, never declared — see {@link capabilityProbe}.
+ */
+export interface HarnessCapabilities {
+    readonly streaming: boolean;
+    readonly resumeById: boolean;
+}
+/**
+ * The advertisement {@link capabilityProbe} produces: the raw capabilities plus
+ * the single **derived** `durableResume` bit slice 5's enrolment gate consumes.
+ * Keeping `durableResume` derived (never a hand-set field on a normalizer)
+ * eliminates the drift surface where a harness claims durability it can't honour.
+ */
+export interface CapabilityAdvertisement {
+    readonly harness: string;
+    readonly streaming: boolean;
+    readonly resumeById: boolean;
+    /** `true` iff the harness both streams a mind source AND resumes by id. */
+    readonly durableResume: boolean;
+}
+/**
+ * One harness's fallback ingestion adapter: a dialect map, a resume shim, and its
+ * capabilities. Independent per harness (they fan out in parallel), and all
+ * target the one canonical {@link SessionEvent} union.
+ */
+export interface HarnessNormalizer {
+    /** The harness id this normalizer speaks for, e.g. `"@github/copilot"`. */
+    readonly harness: string;
+    /** Raw capabilities; `durable-resume` is derived from these by {@link capabilityProbe}. */
+    readonly capabilities: HarnessCapabilities;
+    /**
+     * Map one native record (a parsed `stream-json` line, an SDK `SessionEvent`, a
+     * live-feed frame) to zero-or-more canonical {@link DraftEvent}s. Returns `[]`
+     * for records that carry no session-log meaning (transport keep-alives, init
+     * frames the canonical model does not represent). Throws
+     * {@link NormalizerDialectError} on a record that *should* map but is
+     * structurally invalid — a corrupt transcript fails loudly, it never
+     * fabricates an event.
+     */
+    toDrafts(record: unknown): readonly DraftEvent[];
+    /** Resolve the native invocation that resumes `sessionId` for this harness. */
+    resume(sessionId: string): ResumeShim;
+}
+/**
+ * Derive a harness's `durable-resume` advertisement from its raw capabilities.
+ * A harness advertises `durable-resume` **iff** it both exposes a streaming mind
+ * source we can normalize AND can restore a specific session by id — either half
+ * alone is insufficient (a stream we can't resume, or a resume with no mind to
+ * replay). This is the single place the bit is computed.
+ */
+export declare function capabilityProbe(normalizer: HarnessNormalizer): CapabilityAdvertisement;
+/**
+ * Raised when a native record that a dialect *should* map is structurally
+ * invalid (a missing tool-call id, a message with no content). Mirrors slice 1's
+ * `SessionEventShapeError` at the ingestion boundary: normalization is a trusted
+ * map, so a malformed native record surfaces loudly rather than silently
+ * dropping or fabricating a canonical event.
+ */
+export declare class NormalizerDialectError extends Error {
+    readonly harness: string;
+    constructor(harness: string, message: string);
+}

package/dist/session/normalizer/types.js

@@ -0,0 +1,31 @@
+/**
+ * Derive a harness's `durable-resume` advertisement from its raw capabilities.
+ * A harness advertises `durable-resume` **iff** it both exposes a streaming mind
+ * source we can normalize AND can restore a specific session by id — either half
+ * alone is insufficient (a stream we can't resume, or a resume with no mind to
+ * replay). This is the single place the bit is computed.
+ */
+export function capabilityProbe(normalizer) {
+    const { streaming, resumeById } = normalizer.capabilities;
+    return {
+        harness: normalizer.harness,
+        streaming,
+        resumeById,
+        durableResume: streaming && resumeById,
+    };
+}
+/**
+ * Raised when a native record that a dialect *should* map is structurally
+ * invalid (a missing tool-call id, a message with no content). Mirrors slice 1's
+ * `SessionEventShapeError` at the ingestion boundary: normalization is a trusted
+ * map, so a malformed native record surfaces loudly rather than silently
+ * dropping or fabricating a canonical event.
+ */
+export class NormalizerDialectError extends Error {
+    harness;
+    constructor(harness, message) {
+        super(`[${harness}] ${message}`);
+        this.name = "NormalizerDialectError";
+        this.harness = harness;
+    }
+}

package/dist/session/schema.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const SESSION_LOG_TABLE = "agentic_session_log";
+/** The durable per-event table name. */
+export declare const SESSION_EVENT_TABLE = "agentic_session_event";
+/** The checkpoint table name. */
+export declare 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 declare const SESSION_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS agentic_session_log (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  incarnation           INTEGER NOT NULL DEFAULT 0,\n  lifecycle             TEXT NOT NULL DEFAULT 'activation',\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  PRIMARY KEY (process_instance_key, element_id)\n);\nCREATE TABLE IF NOT EXISTS agentic_session_event (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  event_offset          INTEGER NOT NULL,\n  incarnation           INTEGER NOT NULL,\n  event_id              TEXT NOT NULL,\n  parent_id             TEXT,\n  event_type            TEXT NOT NULL,\n  payload               TEXT NOT NULL,\n  appended_at           TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key, element_id, event_offset)\n);\nCREATE TABLE IF NOT EXISTS agentic_session_checkpoint (\n  process_instance_key  TEXT NOT NULL,\n  element_id            TEXT NOT NULL,\n  checkpoint_id         TEXT NOT NULL,\n  checkpoint_offset     INTEGER NOT NULL,\n  incarnation           INTEGER NOT NULL,\n  commit_sha            TEXT NOT NULL,\n  effect_ledger         TEXT NOT NULL,\n  created_at            TEXT NOT NULL,\n  PRIMARY KEY (process_instance_key, element_id, checkpoint_id)\n);\nCREATE INDEX IF NOT EXISTS idx_agentic_session_checkpoint_offset ON agentic_session_checkpoint (process_instance_key, element_id, checkpoint_offset);\nCREATE INDEX IF NOT EXISTS idx_agentic_session_log_retention ON agentic_session_log (lifecycle, status, completed_at);";

package/dist/session/schema.js

@@ -0,0 +1,74 @@
+/**
+ * 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/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