@nanobpm/agentic 0.4.0 → 0.6.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/protocol/conformance/control.d.ts

@@ -0,0 +1,32 @@
+import { type InboundControlErrorCode, type InboundControlFrame } from "../control.ts";
+/**
+ * Shared corpus for the INBOUND control vocabulary (steer-in). These vectors are
+ * exported so cross-repo consumers (the c8ctl harness) decode the SAME frames.
+ *
+ * `chunk` is the raw inbound steer string a peer sends; `frame` is the typed
+ * {@link InboundControlFrame} it must decode to; `structured` records whether it
+ * is a recognised control envelope (`true`) or the legacy bare-string-as-prompt
+ * fall-back (`false`). A `roundTrips: false` vector decodes to `frame` but does
+ * NOT re-encode to the same `chunk` (a legacy bare string, or an envelope with
+ * extra tolerated fields), so the round-trip test skips re-encoding it.
+ */
+export interface ValidControlFrame {
+    readonly name: string;
+    readonly chunk: string;
+    readonly frame: InboundControlFrame;
+    readonly structured: boolean;
+    readonly roundTrips: boolean;
+}
+export declare const VALID_CONTROL_FRAMES: readonly ValidControlFrame[];
+/**
+ * Adversarial inbound control vectors: a chunk TAGGED as a control envelope but
+ * malformed. Each MUST be rejected with the exact {@link InboundControlErrorCode}.
+ * A missing tag is NOT here — an untagged chunk is a valid legacy prompt (see
+ * {@link VALID_CONTROL_FRAMES}), never an error.
+ */
+export interface MalformedControlFrame {
+    readonly name: string;
+    readonly chunk: string;
+    readonly expected: InboundControlErrorCode;
+}
+export declare const MALFORMED_CONTROL_FRAMES: readonly MalformedControlFrame[];

package/dist/protocol/conformance/control.js

@@ -0,0 +1,113 @@
+import { CONTROL_FRAME_MARKER, CONTROL_FRAME_VERSION, } from "../control.js";
+const MARKER = { [CONTROL_FRAME_MARKER]: CONTROL_FRAME_VERSION };
+export const VALID_CONTROL_FRAMES = [
+    {
+        name: "prompt-structured",
+        chunk: JSON.stringify({ ...MARKER, kind: "prompt", text: "run the tests" }),
+        frame: { kind: "prompt", text: "run the tests" },
+        structured: true,
+        roundTrips: true,
+    },
+    {
+        name: "prompt-structured-empty-text",
+        chunk: JSON.stringify({ ...MARKER, kind: "prompt", text: "" }),
+        frame: { kind: "prompt", text: "" },
+        structured: true,
+        roundTrips: true,
+    },
+    {
+        name: "cancel-structured",
+        chunk: JSON.stringify({ ...MARKER, kind: "cancel" }),
+        frame: { kind: "cancel" },
+        structured: true,
+        roundTrips: true,
+    },
+    {
+        name: "cancel-structured-with-reason",
+        chunk: JSON.stringify({ ...MARKER, kind: "cancel", reason: "operator interrupt" }),
+        frame: { kind: "cancel", reason: "operator interrupt" },
+        structured: true,
+        roundTrips: true,
+    },
+    {
+        name: "permission-granted",
+        chunk: JSON.stringify({ ...MARKER, kind: "permission", requestId: "req-7", outcome: "granted" }),
+        frame: { kind: "permission", requestId: "req-7", outcome: "granted" },
+        structured: true,
+        roundTrips: true,
+    },
+    {
+        name: "permission-denied",
+        chunk: JSON.stringify({ ...MARKER, kind: "permission", requestId: "req-8", outcome: "denied" }),
+        frame: { kind: "permission", requestId: "req-8", outcome: "denied" },
+        structured: true,
+        roundTrips: true,
+    },
+    // Legacy raw-byte steer: a bare keystroke/line is NOT a control envelope and
+    // must decode as a prompt carrying the chunk verbatim — the no-regression path.
+    {
+        name: "legacy-keystroke-line",
+        chunk: "ls -la\n",
+        frame: { kind: "prompt", text: "ls -la\n" },
+        structured: false,
+        roundTrips: false,
+    },
+    {
+        name: "legacy-control-c",
+        chunk: "\u0003",
+        frame: { kind: "prompt", text: "\u0003" },
+        structured: false,
+        roundTrips: false,
+    },
+    {
+        name: "legacy-json-number-is-not-a-frame",
+        chunk: "42",
+        frame: { kind: "prompt", text: "42" },
+        structured: false,
+        roundTrips: false,
+    },
+    {
+        name: "legacy-untagged-json-object",
+        chunk: JSON.stringify({ kind: "prompt", text: "not tagged" }),
+        frame: { kind: "prompt", text: JSON.stringify({ kind: "prompt", text: "not tagged" }) },
+        structured: false,
+        roundTrips: false,
+    },
+];
+export const MALFORMED_CONTROL_FRAMES = [
+    {
+        name: "tagged-missing-kind",
+        chunk: JSON.stringify({ ...MARKER, text: "no kind" }),
+        expected: "bad-kind",
+    },
+    {
+        name: "tagged-unknown-kind",
+        chunk: JSON.stringify({ ...MARKER, kind: "explode" }),
+        expected: "bad-kind",
+    },
+    {
+        name: "prompt-missing-text",
+        chunk: JSON.stringify({ ...MARKER, kind: "prompt" }),
+        expected: "bad-prompt-text",
+    },
+    {
+        name: "prompt-non-string-text",
+        chunk: JSON.stringify({ ...MARKER, kind: "prompt", text: 123 }),
+        expected: "bad-prompt-text",
+    },
+    {
+        name: "cancel-non-string-reason",
+        chunk: JSON.stringify({ ...MARKER, kind: "cancel", reason: 5 }),
+        expected: "bad-cancel-reason",
+    },
+    {
+        name: "permission-missing-request-id",
+        chunk: JSON.stringify({ ...MARKER, kind: "permission", outcome: "granted" }),
+        expected: "bad-permission-request-id",
+    },
+    {
+        name: "permission-bad-outcome",
+        chunk: JSON.stringify({ ...MARKER, kind: "permission", requestId: "req-9", outcome: "maybe" }),
+        expected: "bad-permission-outcome",
+    },
+];

package/dist/protocol/conformance/index.d.ts

@@ -11,3 +11,4 @@ export { GOLDEN_FRAMES, type GoldenFrame, } from "./frames.ts";
 export { MALFORMED_FRAMES, type MalformedFrame, } from "./malformed.ts";
 export { VALID_VOCABS, INVALID_VOCABS, type ValidVocab, type InvalidVocab, } from "./vocab.ts";
 export { VALID_TOKENS, INVALID_TOKENS, type ValidToken, type InvalidToken, } from "./tokens.ts";
+export { VALID_CONTROL_FRAMES, MALFORMED_CONTROL_FRAMES, type ValidControlFrame, type MalformedControlFrame, } from "./control.ts";

package/dist/protocol/conformance/index.js

@@ -11,3 +11,4 @@ export { GOLDEN_FRAMES, } from "./frames.js";
 export { MALFORMED_FRAMES, } from "./malformed.js";
 export { VALID_VOCABS, INVALID_VOCABS, } from "./vocab.js";
 export { VALID_TOKENS, INVALID_TOKENS, } from "./tokens.js";
+export { VALID_CONTROL_FRAMES, MALFORMED_CONTROL_FRAMES, } from "./control.js";

package/dist/protocol/control.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Typed INBOUND control vocabulary for the `relay` family (ADR 0056, ACP steer).
+ *
+ * The relay data frame ({@link RelayPayload} `{ stream, offset, chunk }`) is the
+ * OUTBOUND (hub → consumer) byte lane and is left untouched. This module adds an
+ * ADDITIVE vocabulary for the INBOUND (consumer → agent) steer lane, where a
+ * peer historically sent a bare `chunk` string that a PTY role fed straight to
+ * the terminal as keystrokes. ACP steering must now distinguish three intents:
+ *
+ *  - `prompt`     — start a new turn (carries the prompt text);
+ *  - `cancel`     — interrupt the current turn (optionally with a reason);
+ *  - `permission` — answer/release a blocked `session/request_permission`
+ *                   (carries the request id being answered + the outcome).
+ *
+ * ## Backward compatibility (raw-byte steer)
+ *
+ * The vocabulary is a STRICT superset of the legacy raw-byte path. A structured
+ * frame is a JSON envelope TAGGED with {@link CONTROL_FRAME_MARKER}; a bare
+ * inbound string that is NOT such a tagged envelope (a keystroke, a shell line,
+ * unrelated JSON) continues to decode as a `prompt` whose `text` is the original
+ * chunk verbatim. Existing raw-byte producers and consumers need not change.
+ *
+ * ## Decode order (see {@link parseInboundRelayChunk})
+ *
+ *  1. If the chunk parses as a control envelope (a JSON object tagged with the
+ *     marker at the current version) → validate it and return the typed frame;
+ *     a tagged-but-malformed envelope is an ERROR, never a silent prompt.
+ *  2. Otherwise → legacy fall-back: `{ kind: "prompt", text: <chunk> }`.
+ *
+ * This is purely the inbound control vocabulary at the protocol seam: it changes
+ * neither the relay transport (ring, QoS, offsets, stream routing) nor the
+ * outbound `{ stream, offset, chunk }` data-frame shape.
+ */
+/**
+ * The marker key that tags a chunk as a structured inbound control envelope.
+ * Its value is the {@link CONTROL_FRAME_VERSION}. A chunk without this key is a
+ * legacy bare-string steer and decodes as a `prompt`.
+ */
+export declare const CONTROL_FRAME_MARKER: "nanoControlFrame";
+/** The schema version carried by the {@link CONTROL_FRAME_MARKER}. */
+export declare const CONTROL_FRAME_VERSION: 1;
+/** The three inbound steer intents. */
+export type InboundControlKind = "prompt" | "cancel" | "permission";
+/** How a blocked `session/request_permission` was answered. */
+export type PermissionOutcome = "granted" | "denied";
+/** Start a new turn with the given prompt text. */
+export interface PromptControlFrame {
+    readonly kind: "prompt";
+    readonly text: string;
+}
+/** Interrupt the current turn. `reason` is advisory, for telemetry/audit. */
+export interface CancelControlFrame {
+    readonly kind: "cancel";
+    readonly reason?: string;
+}
+/** Answer a blocked `session/request_permission` identified by `requestId`. */
+export interface PermissionControlFrame {
+    readonly kind: "permission";
+    readonly requestId: string;
+    readonly outcome: PermissionOutcome;
+}
+/** The typed inbound control vocabulary — a discriminated union on `kind`. */
+export type InboundControlFrame = PromptControlFrame | CancelControlFrame | PermissionControlFrame;
+export interface InboundControlError {
+    readonly code: InboundControlErrorCode;
+    readonly message: string;
+}
+/**
+ * The closed set of validation-error codes a tagged-but-malformed control
+ * envelope can raise. The conformance corpus derives its coverage from this
+ * union, so a new code cannot be added without a covering malformed vector.
+ */
+export type InboundControlErrorCode = "bad-kind" | "bad-prompt-text" | "bad-cancel-reason" | "bad-permission-request-id" | "bad-permission-outcome";
+/**
+ * The result of decoding an inbound steer chunk. `structured` distinguishes a
+ * recognised control envelope from the legacy bare-string-as-prompt fall-back,
+ * so a consumer can tell an explicit `prompt` frame from a raw keystroke.
+ */
+export type InboundControlDecodeResult = {
+    readonly ok: true;
+    readonly frame: InboundControlFrame;
+    readonly structured: boolean;
+} | {
+    readonly ok: false;
+    readonly errors: readonly InboundControlError[];
+};
+/**
+ * Is `value` a structured inbound control envelope (a plain object tagged with
+ * the marker at the current version)? This is the discriminator the decoder uses
+ * to choose the structured path over the legacy bare-string fall-back — it does
+ * NOT assert the envelope's `kind`-specific fields are well-formed.
+ */
+export declare function isInboundControlEnvelope(value: unknown): value is Record<string, unknown>;
+/**
+ * Decode a raw inbound steer chunk into a typed {@link InboundControlFrame}.
+ *
+ * A chunk tagged as a control envelope is validated and returned as its typed
+ * frame (`structured: true`); a tagged-but-malformed envelope (bad/missing
+ * discriminant, missing/ill-typed field) is a validation ERROR. Any other chunk
+ * — a bare keystroke, a shell line, unrelated JSON — is treated as the legacy
+ * raw-byte steer and returned as a `prompt` whose `text` is the chunk verbatim
+ * (`structured: false`). See the module header for the full decode order.
+ */
+export declare function parseInboundRelayChunk(chunk: string): InboundControlDecodeResult;
+/**
+ * Encode a typed {@link InboundControlFrame} as its canonical wire chunk — a
+ * JSON envelope tagged with {@link CONTROL_FRAME_MARKER}. The result round-trips
+ * back through {@link parseInboundRelayChunk} to an equal frame.
+ */
+export declare function encodeInboundControlFrame(frame: InboundControlFrame): string;

package/dist/protocol/control.js

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

package/dist/protocol/index.d.ts

@@ -20,4 +20,5 @@ export { encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, FRAME_MAG
 export { parseToken, formatToken, isValidToken, isSegmentName, isSeatLabel, TokenParseError, type RoutingToken, type TokenParseErrorCode, } from "./token.ts";
 export { validateVocabDocument, type VocabDocument, type VocabNetwork, type VocabRole, type VocabError, type VocabValidationResult, } from "./vocab/schema.ts";
 export { validatePayload, type Capability, type RegisterPayload, type HeartbeatPayload, type DeregisterPayload, type ServePayload, type DemandPayload, type BlackboardPayload, type BlackboardOp, type RelayPayload, type RelayProducePayload, type RelaySubscribePayload, type RelayCreditPayload, type RelaySubscribedPayload, type PayloadError, type PayloadValidationResult, } from "./payloads.ts";
+export { CONTROL_FRAME_MARKER, CONTROL_FRAME_VERSION, isInboundControlEnvelope, parseInboundRelayChunk, encodeInboundControlFrame, type InboundControlKind, type PermissionOutcome, type PromptControlFrame, type CancelControlFrame, type PermissionControlFrame, type InboundControlFrame, type InboundControlError, type InboundControlErrorCode, type InboundControlDecodeResult, } from "./control.ts";
 export { bytesToHex, hexToBytes } from "./hex.ts";

package/dist/protocol/index.js

@@ -20,4 +20,5 @@ export { encodeFrame, decodeFrame, FrameDecodeError, FrameEncodeError, FRAME_MAG
 export { parseToken, formatToken, isValidToken, isSegmentName, isSeatLabel, TokenParseError, } from "./token.js";
 export { validateVocabDocument, } from "./vocab/schema.js";
 export { validatePayload, } from "./payloads.js";
+export { CONTROL_FRAME_MARKER, CONTROL_FRAME_VERSION, isInboundControlEnvelope, parseInboundRelayChunk, encodeInboundControlFrame, } from "./control.js";
 export { bytesToHex, hexToBytes } from "./hex.js";

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