@agentic-kit/run-log 0.5.0 → 0.7.0

package/esm/projectors/spans.js

@@ -3,7 +3,7 @@
  *
  * The log answers *what* happened and the parts projection answers *in what
  * order*, but a trace view asks "how long did this take, and inside what" —
- * questions pi's entries only answer in pairs. Every entry is timestamped, so a
+ * questions a transcript only answers in pairs. Every entry is timestamped, so a
  * tool call and its result, or an approval request and its answer, bracket an
  * interval; nothing new has to be stored to know it.
  *
@@ -15,7 +15,7 @@
  * `open` with no duration rather than being closed at the last record: a run
  * still in flight must not look like one that finished.
  */
-import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
+import { toEventGroups } from './events';
 import { APPROVAL_REQUEST_TYPE, APPROVAL_RESOLUTION_TYPE, assertGateDecisionDetails, GATE_DECISION_TYPE } from './tool-state';
 const ms = (from, to) => {
     const start = Date.parse(from);
@@ -32,63 +32,67 @@ const close = (span, seq, at) => {
         span.durationMs = duration;
 };
 const detailsOf = (value) => typeof value === 'object' && value !== null ? value : {};
+const firstTimestamp = (events) => events.find((event) => typeof event.at === 'string')?.at;
 /**
  * Project records into spans. Pure, and like the other projectors it ignores what
- * it does not recognise — a log written by a newer pi still traces. A *registered*
- * type that is malformed is another matter and throws: a gate decision naming no
- * tool call is a writer bug, and a trace that quietly omitted a refusal would be
- * worse than one that fails.
+ * it does not recognise — a log written by a newer harness still traces. A
+ * *registered* type that is malformed is another matter and throws: a gate
+ * decision naming no tool call is a writer bug, and a trace that quietly omitted
+ * a refusal would be worse than one that fails.
  */
-export function projectSpans(records) {
+export function projectSpans(records, options = {}) {
     const spans = [];
     const tools = new Map();
     const approvals = new Map();
     /**
      * The end of the previous entry, which is the earliest the next model call
-     * can have begun — pi logs a response, never a request.
+     * can have begun — a transcript logs a response, never a request.
      */
     let previousAt;
-    for (const { entry, seq } of records) {
-        const at = typeof entry.timestamp === 'string' ? entry.timestamp : undefined;
+    for (const { events, seq } of toEventGroups(records, options)) {
+        const at = firstTimestamp(events);
         if (at === undefined)
             continue;
         const previous = previousAt;
         previousAt = at;
-        if (!isPiMessageEntry(entry))
-            continue;
-        const message = entry.message;
-        if (isAssistantMessage(message)) {
-            const span = {
-                id: `model:${entry.id}`,
-                kind: 'model',
-                name: message.model ?? 'model',
-                // The turn began no earlier than the previous entry was written; with no
-                // previous entry the interval is unknown and the span is a point.
-                startedAt: previous ?? at,
-                startSeq: seq,
-                endSeq: seq,
-                endedAt: at,
-                timing: 'bounded',
-                status: message.stopReason === 'error' ? 'error' : 'ok',
-                ...(message.model ? { model: message.model } : {}),
-                ...(message.provider ? { provider: message.provider } : {}),
-                ...(typeof message.responseId === 'string' ? { responseId: message.responseId } : {}),
-                ...(message.stopReason ? { stopReason: message.stopReason } : {}),
-                ...(message.usage ? { usage: message.usage } : {}),
-                ...(message.errorMessage ? { errorMessage: message.errorMessage } : {})
-            };
-            const duration = ms(span.startedAt, at);
-            if (duration !== undefined)
-                span.durationMs = duration;
-            spans.push(span);
-            for (const call of toolCalls(message)) {
+        /** The model call the entry's tool calls belong to. */
+        let modelSpan;
+        for (const event of events) {
+            if (event.kind === 'model-response') {
+                const span = {
+                    id: `model:${event.entryId ?? String(seq)}`,
+                    kind: 'model',
+                    name: event.model ?? 'model',
+                    // The turn began no earlier than the previous entry was written; with
+                    // no previous entry the interval is unknown and the span is a point.
+                    startedAt: previous ?? at,
+                    startSeq: seq,
+                    endSeq: seq,
+                    endedAt: at,
+                    timing: 'bounded',
+                    status: event.stopReason === 'error' ? 'error' : 'ok',
+                    ...(event.model ? { model: event.model } : {}),
+                    ...(event.provider ? { provider: event.provider } : {}),
+                    ...(event.responseId ? { responseId: event.responseId } : {}),
+                    ...(event.stopReason ? { stopReason: event.stopReason } : {}),
+                    ...(event.usage ? { usage: event.usage } : {}),
+                    ...(event.errorMessage ? { errorMessage: event.errorMessage } : {})
+                };
+                const duration = ms(span.startedAt, at);
+                if (duration !== undefined)
+                    span.durationMs = duration;
+                modelSpan = span;
+                spans.push(span);
+                continue;
+            }
+            if (event.kind === 'tool-call') {
                 const tool = {
-                    id: `tool:${call.id}`,
+                    id: `tool:${event.toolCallId}`,
                     kind: 'tool',
-                    name: call.name,
-                    parentId: span.id,
-                    toolCallId: call.id,
-                    arguments: call.arguments ?? {},
+                    name: event.name,
+                    ...(modelSpan ? { parentId: modelSpan.id } : {}),
+                    toolCallId: event.toolCallId,
+                    arguments: event.arguments,
                     startedAt: at,
                     startSeq: seq,
                     // A call and its result are two writes; anything between them —
@@ -96,79 +100,79 @@ export function projectSpans(records) {
                     timing: 'bounded',
                     status: 'open'
                 };
-                tools.set(call.id, tool);
+                tools.set(event.toolCallId, tool);
                 spans.push(tool);
+                continue;
             }
-            continue;
-        }
-        if (isToolResultMessage(message)) {
-            const tool = tools.get(message.toolCallId);
-            if (!tool)
+            if (event.kind === 'tool-result') {
+                const tool = tools.get(event.toolCallId);
+                if (!tool)
+                    continue;
+                close(tool, seq, at);
+                tool.status = event.failed ? 'error' : 'ok';
+                tool.output = event.output;
+                if (event.details !== undefined)
+                    tool.details = event.details;
+                const approval = approvals.get(event.toolCallId);
+                if (approval?.durationMs !== undefined)
+                    tool.approvalWaitMs = approval.durationMs;
                 continue;
-            close(tool, seq, at);
-            tool.status = message.isError ? 'error' : 'ok';
-            tool.output = contentText(message.content);
-            if (message.details !== undefined)
-                tool.details = message.details;
-            const approval = approvals.get(message.toolCallId);
-            if (approval?.durationMs !== undefined)
-                tool.approvalWaitMs = approval.durationMs;
-            continue;
-        }
-        if (message.role !== 'custom')
-            continue;
-        const info = detailsOf(message.details);
-        const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : undefined;
-        if (toolCallId === undefined)
-            continue;
-        if (message.customType === APPROVAL_REQUEST_TYPE) {
-            const tool = tools.get(toolCallId);
-            const approval = {
-                id: `approval:${toolCallId}`,
-                kind: 'approval',
-                name: tool?.name ?? 'approval',
-                ...(tool ? { parentId: tool.id } : {}),
-                toolCallId,
-                prompt: contentText(message.content),
-                startedAt: at,
-                startSeq: seq,
-                // Request and answer are exactly the interval a human held the run.
-                timing: 'measured',
-                status: 'open'
-            };
-            approvals.set(toolCallId, approval);
-            spans.push(approval);
-            continue;
-        }
-        if (message.customType === APPROVAL_RESOLUTION_TYPE) {
-            const approval = approvals.get(toolCallId);
-            if (!approval)
+            }
+            if (event.kind !== 'custom')
                 continue;
-            close(approval, seq, at);
-            const approved = info.decision === 'approved';
-            approval.decision = approved ? 'approved' : 'rejected';
-            approval.status = approved ? 'ok' : 'denied';
-            if (typeof info.actorId === 'string')
-                approval.actorId = info.actorId;
-            const tool = tools.get(toolCallId);
-            if (tool && approval.durationMs !== undefined)
-                tool.approvalWaitMs = approval.durationMs;
-            continue;
-        }
-        if (message.customType === GATE_DECISION_TYPE) {
-            // Throws on a malformed decision — see the note on this function.
-            const decision = assertGateDecisionDetails(message.details, seq);
-            const tool = tools.get(decision.toolCallId);
-            if (!tool)
+            const info = detailsOf(event.details);
+            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : undefined;
+            if (toolCallId === undefined)
                 continue;
-            tool.gateDecision = decision.decision;
-            if (decision.reason !== undefined)
-                tool.gateReason = decision.reason;
-            // A denied call is never executed, so this write is the only thing that
-            // will ever close its span.
-            if (decision.decision === 'deny' && tool.status === 'open') {
-                close(tool, seq, at);
-                tool.status = 'denied';
+            if (event.customType === APPROVAL_REQUEST_TYPE) {
+                const tool = tools.get(toolCallId);
+                const approval = {
+                    id: `approval:${toolCallId}`,
+                    kind: 'approval',
+                    name: tool?.name ?? 'approval',
+                    ...(tool ? { parentId: tool.id } : {}),
+                    toolCallId,
+                    prompt: event.text,
+                    startedAt: at,
+                    startSeq: seq,
+                    // Request and answer are exactly the interval a human held the run.
+                    timing: 'measured',
+                    status: 'open'
+                };
+                approvals.set(toolCallId, approval);
+                spans.push(approval);
+                continue;
+            }
+            if (event.customType === APPROVAL_RESOLUTION_TYPE) {
+                const approval = approvals.get(toolCallId);
+                if (!approval)
+                    continue;
+                close(approval, seq, at);
+                const approved = info.decision === 'approved';
+                approval.decision = approved ? 'approved' : 'rejected';
+                approval.status = approved ? 'ok' : 'denied';
+                if (typeof info.actorId === 'string')
+                    approval.actorId = info.actorId;
+                const tool = tools.get(toolCallId);
+                if (tool && approval.durationMs !== undefined)
+                    tool.approvalWaitMs = approval.durationMs;
+                continue;
+            }
+            if (event.customType === GATE_DECISION_TYPE) {
+                // Throws on a malformed decision — see the note on this function.
+                const decision = assertGateDecisionDetails(event.details, seq);
+                const tool = tools.get(decision.toolCallId);
+                if (!tool)
+                    continue;
+                tool.gateDecision = decision.decision;
+                if (decision.reason !== undefined)
+                    tool.gateReason = decision.reason;
+                // A denied call is never executed, so this write is the only thing that
+                // will ever close its span.
+                if (decision.decision === 'deny' && tool.status === 'open') {
+                    close(tool, seq, at);
+                    tool.status = 'denied';
+                }
             }
         }
     }

package/esm/projectors/tool-state.d.ts

@@ -2,13 +2,14 @@
  * Tool and approval projection: run log records → the state a UI needs to know
  * what is running and what is waiting on a human.
  *
- * Approvals ride in the log as pi `custom` messages rather than a side channel,
- * because "the run is blocked on you" is part of the run's history: a surface
+ * Approvals ride in the log as transcript `custom` entries rather than a side
+ * channel, because "the run is blocked on you" is part of the run's history: a surface
  * that reconnects hours later must be able to see a pending request without
  * having been present when it was raised, and both placements then behave the
  * same — the cloud already treats the conversation as the approval UI.
  */
 import type { RunEventRecord } from '../record';
+import { type ProjectionOptions } from './events';
 /** `customType` of an approval request written by the gate extension. */
 export declare const APPROVAL_REQUEST_TYPE = "constructive.approval.request";
 /** `customType` of the human's answer to a request. */
@@ -63,7 +64,7 @@ export interface ToolStateProjection {
     /** In log order — the oldest unanswered request first. */
     pendingApprovals: ApprovalState[];
 }
-export declare function projectToolState(records: readonly RunEventRecord[]): ToolStateProjection;
+export declare function projectToolState(records: readonly RunEventRecord[], options?: ProjectionOptions): ToolStateProjection;
 /** Narrow the `details` of a `constructive.gate.decision` entry. */
 export declare function assertGateDecisionDetails(value: unknown, seq?: number): GateDecisionDetails;
 /** Narrow the `details` of a `constructive.approval.request` entry. */

package/esm/projectors/tool-state.js

@@ -2,13 +2,13 @@
  * Tool and approval projection: run log records → the state a UI needs to know
  * what is running and what is waiting on a human.
  *
- * Approvals ride in the log as pi `custom` messages rather than a side channel,
- * because "the run is blocked on you" is part of the run's history: a surface
+ * Approvals ride in the log as transcript `custom` entries rather than a side
+ * channel, because "the run is blocked on you" is part of the run's history: a surface
  * that reconnects hours later must be able to see a pending request without
  * having been present when it was raised, and both placements then behave the
  * same — the cloud already treats the conversation as the approval UI.
  */
-import { contentText, isAssistantMessage, isPiMessageEntry, isToolResultMessage, toolCalls } from '../transcripts/pi-entry';
+import { toEvents } from './events';
 /** `customType` of an approval request written by the gate extension. */
 export const APPROVAL_REQUEST_TYPE = 'constructive.approval.request';
 /** `customType` of the human's answer to a request. */
@@ -24,38 +24,33 @@ export const GATE_DECISION_TYPE = 'constructive.gate.decision';
 /** Where a bad entry is, when the caller is projecting a log rather than validating one value. */
 const at = (seq) => (seq === undefined ? '' : ` at seq ${String(seq)}`);
 const details = (value) => typeof value === 'object' && value !== null ? value : {};
-export function projectToolState(records) {
+export function projectToolState(records, options = {}) {
     const tools = {};
     const approvals = new Map();
     const gateDecisions = {};
-    for (const { entry, seq } of records) {
-        if (!isPiMessageEntry(entry))
-            continue;
-        const message = entry.message;
-        if (isAssistantMessage(message)) {
-            for (const call of toolCalls(message)) {
-                tools[call.id] = {
-                    toolCallId: call.id,
-                    name: call.name,
-                    arguments: call.arguments ?? {},
-                    status: 'requested',
-                    requestedSeq: seq
-                };
-            }
+    for (const { seq, event } of toEvents(records, options)) {
+        if (event.kind === 'tool-call') {
+            tools[event.toolCallId] = {
+                toolCallId: event.toolCallId,
+                name: event.name,
+                arguments: event.arguments,
+                status: 'requested',
+                requestedSeq: seq
+            };
             continue;
         }
-        if (isToolResultMessage(message)) {
-            const state = tools[message.toolCallId];
+        if (event.kind === 'tool-result') {
+            const state = tools[event.toolCallId];
             const settled = {
-                status: message.isError ? 'failed' : 'completed',
+                status: event.failed ? 'failed' : 'completed',
                 settledSeq: seq,
-                output: contentText(message.content)
+                output: event.output
             };
-            tools[message.toolCallId] = state
+            tools[event.toolCallId] = state
                 ? { ...state, ...settled }
                 : {
-                    toolCallId: message.toolCallId,
-                    name: message.toolName,
+                    toolCallId: event.toolCallId,
+                    name: event.name,
                     arguments: {},
                     requestedSeq: seq,
                     status: settled.status,
@@ -64,14 +59,14 @@ export function projectToolState(records) {
                 };
             continue;
         }
-        if (message.role !== 'custom')
+        if (event.kind !== 'custom')
             continue;
-        if (message.customType === APPROVAL_REQUEST_TYPE) {
-            const { toolCallId } = assertApprovalRequestDetails(message.details, seq);
+        if (event.customType === APPROVAL_REQUEST_TYPE) {
+            const { toolCallId } = assertApprovalRequestDetails(event.details, seq);
             const approval = {
                 toolCallId,
                 requestedSeq: seq,
-                prompt: contentText(message.content)
+                prompt: event.text
             };
             approvals.set(toolCallId, approval);
             const state = tools[toolCallId];
@@ -79,8 +74,8 @@ export function projectToolState(records) {
                 tools[toolCallId] = { ...state, status: 'awaiting-approval', approval };
             continue;
         }
-        if (message.customType === APPROVAL_RESOLUTION_TYPE) {
-            const info = assertApprovalResolutionDetails(message.details, seq);
+        if (event.customType === APPROVAL_RESOLUTION_TYPE) {
+            const info = assertApprovalResolutionDetails(event.details, seq);
             const toolCallId = info.toolCallId;
             const approved = info.decision === 'approved';
             const existing = approvals.get(toolCallId);
@@ -101,8 +96,8 @@ export function projectToolState(records) {
             }
             continue;
         }
-        if (message.customType === GATE_DECISION_TYPE) {
-            const decision = assertGateDecisionDetails(message.details, seq);
+        if (event.customType === GATE_DECISION_TYPE) {
+            const decision = assertGateDecisionDetails(event.details, seq);
             gateDecisions[decision.toolCallId] = { ...decision, seq };
             const state = tools[decision.toolCallId];
             // A blocked call never produces a tool result, so the gate's `deny` is the

package/esm/projectors/usage.d.ts

@@ -1,7 +1,7 @@
 /**
  * Usage projection: run log records → token and cost totals.
  *
- * Every usage-bearing pi entry counts, not just assistant messages: a tool that
+ * Every usage-bearing event counts, not just model responses: a tool that
  * performed nested LLM work reports `usage` on its result, and compaction and
  * branch summaries are model calls the run paid for. Missing any of those makes
  * a run look cheaper than it was, which is exactly the kind of drift metering
@@ -12,6 +12,7 @@
  * `@agentic-kit/metering`).
  */
 import type { RunEventRecord } from '../record';
+import { type ProjectionOptions } from './events';
 export interface UsageTotals {
     input: number;
     output: number;
@@ -32,4 +33,4 @@ export interface RunUsage extends UsageTotals {
 }
 export declare const modelKey: (provider: string, model: string) => string;
 /** Fold every usage-bearing entry in the records into run totals. */
-export declare function projectUsage(records: readonly RunEventRecord[]): RunUsage;
+export declare function projectUsage(records: readonly RunEventRecord[], options?: ProjectionOptions): RunUsage;

package/esm/projectors/usage.js

@@ -1,7 +1,7 @@
 /**
  * Usage projection: run log records → token and cost totals.
  *
- * Every usage-bearing pi entry counts, not just assistant messages: a tool that
+ * Every usage-bearing event counts, not just model responses: a tool that
  * performed nested LLM work reports `usage` on its result, and compaction and
  * branch summaries are model calls the run paid for. Missing any of those makes
  * a run look cheaper than it was, which is exactly the kind of drift metering
@@ -11,7 +11,7 @@
  * never the billing authority — a gateway-observed record is (see
  * `@agentic-kit/metering`).
  */
-import { isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isToolResultMessage } from '../transcripts/pi-entry';
+import { toEvents } from './events';
 const empty = () => ({
     input: 0,
     output: 0,
@@ -40,7 +40,7 @@ function fold(target, usage) {
 }
 export const modelKey = (provider, model) => `${provider}/${model}`;
 /** Fold every usage-bearing entry in the records into run totals. */
-export function projectUsage(records) {
+export function projectUsage(records, options = {}) {
     const totals = { ...empty(), byModel: {} };
     const add = (usage, provider = 'unknown', model = 'unknown') => {
         if (!usage)
@@ -53,23 +53,17 @@ export function projectUsage(records) {
     };
     let lastProvider = 'unknown';
     let lastModel = 'unknown';
-    for (const { entry } of records) {
-        if (isPiMessageEntry(entry)) {
-            const message = entry.message;
-            if (isAssistantMessage(message)) {
-                lastProvider = message.provider ?? lastProvider;
-                lastModel = message.model ?? lastModel;
-                add(message.usage, message.provider ?? 'unknown', message.model ?? 'unknown');
-            }
-            else if (isToolResultMessage(message)) {
-                // Nested model work inside a tool: attributed to the run's current model,
-                // which is the model that requested the tool.
-                add(message.usage, lastProvider, lastModel);
-            }
+    for (const { event } of toEvents(records, options)) {
+        if (event.kind === 'model-response') {
+            lastProvider = event.provider ?? lastProvider;
+            lastModel = event.model ?? lastModel;
+            add(event.usage, event.provider ?? 'unknown', event.model ?? 'unknown');
             continue;
         }
-        if (isPiCompactionEntry(entry) || isPiBranchSummaryEntry(entry)) {
-            add(entry.usage, lastProvider, lastModel);
+        // Nested model work inside a tool or a summary: attributed to the run's
+        // current model, which is the model that asked for it.
+        if (event.kind === 'tool-result' || event.kind === 'summary') {
+            add(event.usage, lastProvider, lastModel);
         }
     }
     return totals;

package/esm/record.d.ts

@@ -8,8 +8,9 @@
  * which reader can parse the entry, and `transcriptVersion` says which version
  * that reader must migrate from.
  */
+import { type TranscriptEntry } from './transcripts/entry';
 import { type TranscriptFormat } from './transcripts/format';
-import { type PiSessionEntry } from './transcripts/pi-entry';
+import type { TranscriptReaderRegistry } from './transcripts/reader';
 /** Version of the wrapper itself — bumped only if these fields change. */
 export declare const RUN_LOG_WRAPPER_VERSION = 1;
 export interface RunEventRecord {
@@ -24,15 +25,17 @@ export interface RunEventRecord {
     /** That transcript's format version at write time. */
     transcriptVersion: number;
     /** The harness's session entry, byte-for-byte as it was produced. */
-    entry: PiSessionEntry;
+    entry: TranscriptEntry;
 }
 export interface WrapEntryOptions {
     runId: string;
     seq: number;
-    entry: PiSessionEntry;
+    entry: TranscriptEntry;
     recordedAt?: string;
     transcriptFormat?: TranscriptFormat;
     transcriptVersion?: number;
+    /** Readers used to validate the entry. Defaults to the process registry. */
+    readers?: TranscriptReaderRegistry;
 }
 export declare function wrapEntry(options: WrapEntryOptions): RunEventRecord;
 /**
@@ -40,12 +43,12 @@ export declare function wrapEntry(options: WrapEntryOptions): RunEventRecord;
  * unreadable — a log that cannot be parsed must fail loudly, never silently
  * render as an empty conversation.
  */
-export declare function assertRunEventRecord(value: unknown): RunEventRecord;
+export declare function assertRunEventRecord(value: unknown, readers?: TranscriptReaderRegistry): RunEventRecord;
 /**
- * The de-duplication key for an append. pi entry ids are unique within a
+ * The de-duplication key for an append. Transcript entry ids are unique within a
  * session, so a retried append (a Job restart re-emitting its tail, a
  * reconnecting writer) is recognised rather than duplicated.
  */
-export declare function idempotencyKey(runId: string, entry: PiSessionEntry): string;
+export declare function idempotencyKey(runId: string, entry: TranscriptEntry): string;
 /** Records must be contiguous and in order before anything projects them. */
 export declare function assertOrdered(records: readonly RunEventRecord[]): void;

package/esm/record.js

@@ -8,8 +8,8 @@
  * which reader can parse the entry, and `transcriptVersion` says which version
  * that reader must migrate from.
  */
-import { PI_TRANSCRIPT_FORMAT, SUPPORTED_PI_TRANSCRIPT_VERSION } from './transcripts/format';
-import { assertPiSessionEntry } from './transcripts/pi-entry';
+import { PI_TRANSCRIPT_FORMAT } from './transcripts/format';
+import { transcriptReaders } from './transcripts/registry';
 /** Version of the wrapper itself — bumped only if these fields change. */
 export const RUN_LOG_WRAPPER_VERSION = 1;
 export function wrapEntry(options) {
@@ -18,13 +18,17 @@ export function wrapEntry(options) {
     if (!Number.isInteger(options.seq) || options.seq < 1) {
         throw new TypeError(`run log seq must be a positive integer, received ${String(options.seq)}`);
     }
+    const format = options.transcriptFormat ?? PI_TRANSCRIPT_FORMAT;
+    const reader = (options.readers ?? transcriptReaders).require(format);
     return {
         runId: options.runId,
         seq: options.seq,
         recordedAt: options.recordedAt ?? new Date().toISOString(),
-        transcriptFormat: options.transcriptFormat ?? PI_TRANSCRIPT_FORMAT,
-        transcriptVersion: options.transcriptVersion ?? SUPPORTED_PI_TRANSCRIPT_VERSION,
-        entry: assertPiSessionEntry(options.entry)
+        transcriptFormat: format,
+        transcriptVersion: options.transcriptVersion ?? reader.version,
+        // The entry is validated by the format's own reader: what makes an entry
+        // well-formed is the transcript's rule, not the wrapper's.
+        entry: reader.assertEntry(options.entry)
     };
 }
 /**
@@ -32,7 +36,7 @@ export function wrapEntry(options) {
  * unreadable — a log that cannot be parsed must fail loudly, never silently
  * render as an empty conversation.
  */
-export function assertRunEventRecord(value) {
+export function assertRunEventRecord(value, readers = transcriptReaders) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         throw new TypeError(`run log record must be an object, received ${typeof value}`);
     }
@@ -58,20 +62,18 @@ export function assertRunEventRecord(value) {
         recordedAt: record.recordedAt,
         transcriptFormat: record.transcriptFormat,
         transcriptVersion: record.transcriptVersion,
-        entry: assertPiSessionEntry(record.entry)
+        entry: readers.require(record.transcriptFormat).assertEntry(record.entry)
     };
 }
 /**
- * The de-duplication key for an append. pi entry ids are unique within a
+ * The de-duplication key for an append. Transcript entry ids are unique within a
  * session, so a retried append (a Job restart re-emitting its tail, a
  * reconnecting writer) is recognised rather than duplicated.
  */
 export function idempotencyKey(runId, entry) {
-    const id = typeof entry.id === 'string' ? entry.id : null;
-    if (id)
-        return `${runId}:${entry.type}:${id}`;
-    // Session headers carry no tree id; there is exactly one per session file.
-    return `${runId}:${entry.type}:${String(entry.id ?? 'header')}`;
+    // An opening entry may carry no id; there is exactly one per session.
+    const id = typeof entry.id === 'string' && entry.id.length > 0 ? entry.id : 'header';
+    return `${runId}:${entry.type}:${id}`;
 }
 /** Records must be contiguous and in order before anything projects them. */
 export function assertOrdered(records) {

package/esm/store.d.ts

@@ -6,8 +6,8 @@
  * memory here for tests and for a run that has not been persisted yet.
  */
 import { type RunEventRecord } from './record';
+import type { TranscriptEntry } from './transcripts/entry';
 import type { TranscriptFormat } from './transcripts/format';
-import type { PiSessionEntry } from './transcripts/pi-entry';
 /** Read position: `afterSeq` is exclusive, so `0` means "from the start". */
 export interface RunLogCursor {
     afterSeq: number;
@@ -28,10 +28,10 @@ export interface AppendOptions {
 export interface RunLogAppendStore {
     /**
      * Append entries to a run, returning the records actually written. Entries
-     * already present (matched by pi entry id) are skipped, which makes an append
-     * safe to retry.
+     * already present (matched by transcript entry id) are skipped, which makes an
+     * append safe to retry.
      */
-    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    append(runId: string, entries: readonly TranscriptEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
 }
 export interface RunLogReadStore {
     read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
@@ -41,7 +41,7 @@ export type RunLogStore = RunLogAppendStore & RunLogReadStore;
 export declare class MemoryRunLogStore implements RunLogStore {
     private readonly runs;
     private readonly seen;
-    append(runId: string, entries: readonly PiSessionEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
+    append(runId: string, entries: readonly TranscriptEntry[], options?: AppendOptions): Promise<RunEventRecord[]>;
     read(runId: string, cursor?: RunLogCursor, limit?: number): Promise<RunLogPage>;
     /** Test/debug helper: every record of a run, ignoring cursors. */
     snapshot(runId: string): RunEventRecord[];