@agentic-kit/run-log 0.2.0

package/esm/projectors/parts.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Renderable projection: run log records → an ordered list of parts a UI draws.
+ *
+ * This is the projection that replaces per-host transcript encodings. A tool
+ * call and its later result collapse into one part, so a renderer never has to
+ * correlate two messages itself, and an unknown entry type becomes an
+ * `unknown` part rather than disappearing — a log written by a newer pi still
+ * renders, minus the detail this version understands.
+ */
+import { type PiSessionEntry } from '../pi-entry';
+import type { RunEventRecord } from '../record';
+export type ToolStatus = 'requested' | 'completed' | 'failed';
+export interface PartBase {
+    /** Sequence of the record that introduced the part — a stable React key. */
+    seq: number;
+    entryId?: string;
+}
+export interface TextPart extends PartBase {
+    kind: 'text';
+    role: 'user' | 'assistant';
+    text: string;
+    model?: string;
+    provider?: string;
+}
+export interface ThinkingPart extends PartBase {
+    kind: 'thinking';
+    text: string;
+}
+export interface ToolPart extends PartBase {
+    kind: 'tool';
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    status: ToolStatus;
+    /** Text of the tool result, once one has been logged. */
+    output?: string;
+    details?: unknown;
+    /** Sequence of the record that settled the call. */
+    settledSeq?: number;
+}
+export interface BashPart extends PartBase {
+    kind: 'bash';
+    command: string;
+    output: string;
+    exitCode?: number;
+}
+export interface CustomPart extends PartBase {
+    kind: 'custom';
+    customType: string;
+    text: string;
+    display: boolean;
+    details?: unknown;
+}
+export interface SummaryPart extends PartBase {
+    kind: 'summary';
+    reason: 'compaction' | 'branch';
+    summary: string;
+}
+export interface UnknownPart extends PartBase {
+    kind: 'unknown';
+    entryType: string;
+    entry: PiSessionEntry;
+}
+export type ConversationPart = TextPart | ThinkingPart | ToolPart | BashPart | CustomPart | SummaryPart | UnknownPart;
+export interface Conversation {
+    parts: ConversationPart[];
+    /** From the session header, when the log carries one. */
+    sessionId?: string;
+    cwd?: string;
+}
+/**
+ * Project records into a conversation. Pure and total: the same records always
+ * produce the same parts, whichever host wrote them.
+ */
+export declare function projectParts(records: readonly RunEventRecord[]): Conversation;

package/esm/projectors/parts.js

@@ -0,0 +1,135 @@
+/**
+ * Renderable projection: run log records → an ordered list of parts a UI draws.
+ *
+ * This is the projection that replaces per-host transcript encodings. A tool
+ * call and its later result collapse into one part, so a renderer never has to
+ * correlate two messages itself, and an unknown entry type becomes an
+ * `unknown` part rather than disappearing — a log written by a newer pi still
+ * renders, minus the detail this version understands.
+ */
+import { contentText, isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isPiSessionHeader, isToolResultMessage, toolCalls } from '../pi-entry';
+/**
+ * Project records into a conversation. Pure and total: the same records always
+ * produce the same parts, whichever host wrote them.
+ */
+export function projectParts(records) {
+    const parts = [];
+    const toolsByCallId = new Map();
+    let sessionId;
+    let cwd;
+    for (const record of records) {
+        const { entry, seq } = record;
+        if (isPiSessionHeader(entry)) {
+            sessionId = entry.id;
+            if (typeof entry.cwd === 'string')
+                cwd = entry.cwd;
+            continue;
+        }
+        if (isPiCompactionEntry(entry)) {
+            parts.push({ kind: 'summary', reason: 'compaction', summary: entry.summary, seq, entryId: entry.id });
+            continue;
+        }
+        if (isPiBranchSummaryEntry(entry)) {
+            parts.push({ kind: 'summary', reason: 'branch', summary: entry.summary, seq, entryId: entry.id });
+            continue;
+        }
+        if (!isPiMessageEntry(entry)) {
+            parts.push({ kind: 'unknown', entryType: entry.type, entry, seq, entryId: entry.id });
+            continue;
+        }
+        const message = entry.message;
+        const base = { seq, entryId: entry.id };
+        if (message.role === 'user') {
+            parts.push({ kind: 'text', role: 'user', text: contentText(message.content), ...base });
+            continue;
+        }
+        if (isAssistantMessage(message)) {
+            for (const block of Array.isArray(message.content) ? message.content : []) {
+                if (block.type === 'text' && block.text.length > 0) {
+                    parts.push({
+                        kind: 'text',
+                        role: 'assistant',
+                        text: block.text,
+                        ...(message.model ? { model: message.model } : {}),
+                        ...(message.provider ? { provider: message.provider } : {}),
+                        ...base
+                    });
+                }
+                else if (block.type === 'thinking') {
+                    parts.push({ kind: 'thinking', text: block.thinking, ...base });
+                }
+            }
+            for (const call of toolCalls(message)) {
+                const part = {
+                    kind: 'tool',
+                    toolCallId: call.id,
+                    name: call.name,
+                    arguments: call.arguments ?? {},
+                    status: 'requested',
+                    ...base
+                };
+                toolsByCallId.set(call.id, part);
+                parts.push(part);
+            }
+            continue;
+        }
+        if (isToolResultMessage(message)) {
+            const existing = toolsByCallId.get(message.toolCallId);
+            const output = contentText(message.content);
+            const status = message.isError ? 'failed' : 'completed';
+            if (existing) {
+                existing.status = status;
+                existing.output = output;
+                existing.settledSeq = seq;
+                if (message.details !== undefined)
+                    existing.details = message.details;
+            }
+            else {
+                // A result whose call is not in this window (paged read, forked branch).
+                parts.push({
+                    kind: 'tool',
+                    toolCallId: message.toolCallId,
+                    name: message.toolName,
+                    arguments: {},
+                    status,
+                    output,
+                    settledSeq: seq,
+                    ...base
+                });
+            }
+            continue;
+        }
+        if (message.role === 'bashExecution') {
+            parts.push({
+                kind: 'bash',
+                command: message.command,
+                output: message.output,
+                ...(typeof message.exitCode === 'number' ? { exitCode: message.exitCode } : {}),
+                ...base
+            });
+            continue;
+        }
+        if (message.role === 'custom') {
+            parts.push({
+                kind: 'custom',
+                customType: message.customType,
+                text: contentText(message.content),
+                display: message.display !== false,
+                ...(message.details !== undefined ? { details: message.details } : {}),
+                ...base
+            });
+            continue;
+        }
+        parts.push({
+            kind: 'summary',
+            reason: message.role === 'branchSummary' ? 'branch' : 'compaction',
+            summary: message.summary ?? '',
+            ...base
+        });
+    }
+    return {
+        parts,
+        ...(sessionId ? { sessionId } : {}),
+        ...(cwd ? { cwd } : {})
+    };
+}

package/esm/projectors/session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session projection: run log records → a pi session file.
+ *
+ * This is what makes a run resumable anywhere. The log is the source of truth;
+ * a `.jsonl` session is a derived artifact, so a run that started in the cloud
+ * can be continued locally (and vice versa) by projecting the log back into the
+ * only format pi's `SessionManager` reads.
+ *
+ * Returns a string rather than writing a file: the projection is pure, and the
+ * node-side write lives in `@agentic-kit/run-log/file-store`.
+ */
+import { type PiSessionEntry } from '../pi-entry';
+import { type RunEventRecord } from '../record';
+export interface SessionProjectionOptions {
+    /** Used when the log carries no session header (a run logged headerless). */
+    sessionId?: string;
+    cwd?: string;
+    timestamp?: string;
+}
+export interface SessionProjection {
+    /** The full session file contents, newline-terminated. */
+    jsonl: string;
+    /** Entries in file order, header first. */
+    entries: PiSessionEntry[];
+    piSessionVersion: number;
+}
+/**
+ * Project records into a pi session file. Throws when the records cannot form a
+ * loadable session — an unresumable session must fail at projection time, not
+ * when pi later reads a truncated tree.
+ */
+export declare function projectSession(records: readonly RunEventRecord[], options?: SessionProjectionOptions): SessionProjection;
+/** Parse a pi session file into entries — the inverse, for importing a session. */
+export declare function parseSessionJsonl(jsonl: string): PiSessionEntry[];

package/esm/projectors/session.js

@@ -0,0 +1,64 @@
+/**
+ * Session projection: run log records → a pi session file.
+ *
+ * This is what makes a run resumable anywhere. The log is the source of truth;
+ * a `.jsonl` session is a derived artifact, so a run that started in the cloud
+ * can be continued locally (and vice versa) by projecting the log back into the
+ * only format pi's `SessionManager` reads.
+ *
+ * Returns a string rather than writing a file: the projection is pure, and the
+ * node-side write lives in `@agentic-kit/run-log/file-store`.
+ */
+import { isPiSessionHeader } from '../pi-entry';
+import { assertOrdered, SUPPORTED_PI_SESSION_VERSION } from '../record';
+/**
+ * Project records into a pi session file. Throws when the records cannot form a
+ * loadable session — an unresumable session must fail at projection time, not
+ * when pi later reads a truncated tree.
+ */
+export function projectSession(records, options = {}) {
+    assertOrdered(records);
+    const versions = new Set(records.map((record) => record.piSessionVersion));
+    if (versions.size > 1) {
+        throw new Error(`run log mixes pi session versions (${Array.from(versions).sort().join(', ')}); migrate the older entries before projecting a session`);
+    }
+    const piSessionVersion = records[0]?.piSessionVersion ?? SUPPORTED_PI_SESSION_VERSION;
+    const entries = records.map((record) => record.entry);
+    const headerIndex = entries.findIndex(isPiSessionHeader);
+    if (headerIndex > 0) {
+        throw new Error(`run log carries a session header at position ${String(headerIndex)}; a pi session file requires it first`);
+    }
+    const body = headerIndex === 0 ? entries.slice(1) : entries;
+    const header = headerIndex === 0
+        ? entries[0]
+        : {
+            type: 'session',
+            version: piSessionVersion,
+            id: options.sessionId ?? records[0]?.runId ?? 'run-log',
+            timestamp: options.timestamp ?? records[0]?.recordedAt ?? new Date().toISOString(),
+            ...(options.cwd ? { cwd: options.cwd } : {})
+        };
+    const ordered = [header, ...body];
+    return {
+        entries: ordered,
+        piSessionVersion,
+        jsonl: ordered.map((entry) => JSON.stringify(entry)).join('\n') + '\n'
+    };
+}
+/** Parse a pi session file into entries — the inverse, for importing a session. */
+export function parseSessionJsonl(jsonl) {
+    const entries = [];
+    const lines = jsonl.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line.length === 0)
+            continue;
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`pi session line ${String(i + 1)} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return entries;
+}

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

@@ -0,0 +1,77 @@
+/**
+ * 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
+ * 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';
+/** `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. */
+export declare const APPROVAL_RESOLUTION_TYPE = "constructive.approval.resolution";
+export type ToolCallStatus = 'requested' | 'awaiting-approval' | 'rejected' | 'running' | 'completed' | 'failed';
+export interface ToolCallState {
+    toolCallId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    status: ToolCallStatus;
+    requestedSeq: number;
+    settledSeq?: number;
+    output?: string;
+    approval?: ApprovalState;
+}
+export interface ApprovalState {
+    toolCallId: string;
+    requestedSeq: number;
+    prompt: string;
+    resolvedSeq?: number;
+    decision?: 'approved' | 'rejected';
+    reason?: string;
+    actorId?: string;
+}
+export interface ToolStateProjection {
+    tools: Record<string, ToolCallState>;
+    /** In log order — the oldest unanswered request first. */
+    pendingApprovals: ApprovalState[];
+}
+export declare function projectToolState(records: readonly RunEventRecord[]): ToolStateProjection;
+/** The parts of an approval request an extension needs to write one. */
+export interface ApprovalRequestInput {
+    toolCallId: string;
+    prompt: string;
+}
+export interface ApprovalResolutionInput {
+    toolCallId: string;
+    decision: 'approved' | 'rejected';
+    reason?: string;
+    actorId?: string;
+}
+/** Build the pi `custom` message an approval request is carried in. */
+export declare const approvalRequestMessage: (input: ApprovalRequestInput) => {
+    role: "custom";
+    customType: string;
+    content: string;
+    display: boolean;
+    details: {
+        toolCallId: string;
+    };
+    timestamp: number;
+};
+/** Build the pi `custom` message a human's answer is carried in. */
+export declare const approvalResolutionMessage: (input: ApprovalResolutionInput) => {
+    role: "custom";
+    customType: string;
+    content: string;
+    display: boolean;
+    details: {
+        actorId?: string;
+        reason?: string;
+        toolCallId: string;
+        decision: "rejected" | "approved";
+    };
+    timestamp: number;
+};

package/esm/projectors/tool-state.js

@@ -0,0 +1,127 @@
+/**
+ * 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
+ * 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 '../pi-entry';
+/** `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. */
+export const APPROVAL_RESOLUTION_TYPE = 'constructive.approval.resolution';
+const details = (value) => typeof value === 'object' && value !== null ? value : {};
+export function projectToolState(records) {
+    const tools = {};
+    const approvals = new Map();
+    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
+                };
+            }
+            continue;
+        }
+        if (isToolResultMessage(message)) {
+            const state = tools[message.toolCallId];
+            const settled = {
+                status: message.isError ? 'failed' : 'completed',
+                settledSeq: seq,
+                output: contentText(message.content)
+            };
+            tools[message.toolCallId] = state
+                ? { ...state, ...settled }
+                : {
+                    toolCallId: message.toolCallId,
+                    name: message.toolName,
+                    arguments: {},
+                    requestedSeq: seq,
+                    status: settled.status,
+                    settledSeq: seq,
+                    output: settled.output
+                };
+            continue;
+        }
+        if (message.role !== 'custom')
+            continue;
+        if (message.customType === APPROVAL_REQUEST_TYPE) {
+            const info = details(message.details);
+            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
+            if (!toolCallId) {
+                throw new Error(`approval request at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
+            }
+            const approval = {
+                toolCallId,
+                requestedSeq: seq,
+                prompt: contentText(message.content)
+            };
+            approvals.set(toolCallId, approval);
+            const state = tools[toolCallId];
+            if (state)
+                tools[toolCallId] = { ...state, status: 'awaiting-approval', approval };
+            continue;
+        }
+        if (message.customType === APPROVAL_RESOLUTION_TYPE) {
+            const info = details(message.details);
+            const toolCallId = typeof info.toolCallId === 'string' ? info.toolCallId : null;
+            if (!toolCallId) {
+                throw new Error(`approval resolution at seq ${String(seq)} carries no toolCallId; the run log cannot attribute it`);
+            }
+            const approved = info.decision === 'approved';
+            const existing = approvals.get(toolCallId);
+            const approval = {
+                ...(existing ?? { toolCallId, requestedSeq: seq, prompt: '' }),
+                resolvedSeq: seq,
+                decision: approved ? 'approved' : 'rejected',
+                ...(typeof info.reason === 'string' ? { reason: info.reason } : {}),
+                ...(typeof info.actorId === 'string' ? { actorId: info.actorId } : {})
+            };
+            approvals.set(toolCallId, approval);
+            const state = tools[toolCallId];
+            if (state && state.status === 'awaiting-approval') {
+                tools[toolCallId] = { ...state, status: approved ? 'running' : 'rejected', approval };
+            }
+            else if (state) {
+                tools[toolCallId] = { ...state, approval };
+            }
+        }
+    }
+    const pendingApprovals = Array.from(approvals.values())
+        .filter((approval) => approval.resolvedSeq === undefined)
+        .sort((a, b) => a.requestedSeq - b.requestedSeq);
+    return { tools, pendingApprovals };
+}
+/** Build the pi `custom` message an approval request is carried in. */
+export const approvalRequestMessage = (input) => ({
+    role: 'custom',
+    customType: APPROVAL_REQUEST_TYPE,
+    content: input.prompt,
+    display: true,
+    details: { toolCallId: input.toolCallId },
+    timestamp: Date.now()
+});
+/** Build the pi `custom` message a human's answer is carried in. */
+export const approvalResolutionMessage = (input) => ({
+    role: 'custom',
+    customType: APPROVAL_RESOLUTION_TYPE,
+    content: input.reason ?? input.decision,
+    display: true,
+    details: {
+        toolCallId: input.toolCallId,
+        decision: input.decision,
+        ...(input.reason ? { reason: input.reason } : {}),
+        ...(input.actorId ? { actorId: input.actorId } : {})
+    },
+    timestamp: Date.now()
+});

package/esm/projectors/usage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Usage projection: run log records → token and cost totals.
+ *
+ * Every usage-bearing pi entry counts, not just assistant messages: 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
+ * exists to prevent.
+ *
+ * This projection describes what a run *observed*. It is reconciliation input,
+ * never the billing authority — a gateway-observed record is (see
+ * `@agentic-kit/pi-ext-metered-model`).
+ */
+import type { RunEventRecord } from '../record';
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    cost: number;
+    /** Number of usage-bearing entries folded into these totals. */
+    calls: number;
+}
+export interface ModelUsage extends UsageTotals {
+    provider: string;
+    model: string;
+}
+export interface RunUsage extends UsageTotals {
+    /** Per provider+model breakdown, keyed `provider/model`. */
+    byModel: Record<string, ModelUsage>;
+}
+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;

package/esm/projectors/usage.js

@@ -0,0 +1,76 @@
+/**
+ * Usage projection: run log records → token and cost totals.
+ *
+ * Every usage-bearing pi entry counts, not just assistant messages: 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
+ * exists to prevent.
+ *
+ * This projection describes what a run *observed*. It is reconciliation input,
+ * never the billing authority — a gateway-observed record is (see
+ * `@agentic-kit/pi-ext-metered-model`).
+ */
+import { isAssistantMessage, isPiBranchSummaryEntry, isPiCompactionEntry, isPiMessageEntry, isToolResultMessage } from '../pi-entry';
+const empty = () => ({
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: 0,
+    calls: 0
+});
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+function fold(target, usage) {
+    const input = num(usage.input);
+    const output = num(usage.output);
+    const cacheRead = num(usage.cacheRead);
+    const cacheWrite = num(usage.cacheWrite);
+    target.input += input;
+    target.output += output;
+    target.cacheRead += cacheRead;
+    target.cacheWrite += cacheWrite;
+    // Providers that omit a total still have one: the parts they did report.
+    target.totalTokens += usage.totalTokens === undefined
+        ? input + output + cacheRead + cacheWrite
+        : num(usage.totalTokens);
+    target.cost += num(usage.cost?.total);
+    target.calls += 1;
+}
+export const modelKey = (provider, model) => `${provider}/${model}`;
+/** Fold every usage-bearing entry in the records into run totals. */
+export function projectUsage(records) {
+    const totals = { ...empty(), byModel: {} };
+    const add = (usage, provider = 'unknown', model = 'unknown') => {
+        if (!usage)
+            return;
+        fold(totals, usage);
+        const key = modelKey(provider, model);
+        const bucket = totals.byModel[key] ?? { ...empty(), provider, model };
+        fold(bucket, usage);
+        totals.byModel[key] = bucket;
+    };
+    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);
+            }
+            continue;
+        }
+        if (isPiCompactionEntry(entry) || isPiBranchSummaryEntry(entry)) {
+            add(entry.usage, lastProvider, lastModel);
+        }
+    }
+    return totals;
+}

package/esm/record.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The run log record: four platform-owned fields around a verbatim pi entry.
+ *
+ * The wrapper exists to give an entry identity (which run) and order (which
+ * position) across hosts — nothing else. It deliberately does not re-encode pi's
+ * semantics, because pi already versions and migrates its own session format;
+ * `piSessionVersion` records which version an entry was written under so a
+ * reader can hand old entries to pi's migrations instead of guessing.
+ */
+import { type PiSessionEntry } from './pi-entry';
+/** Version of the wrapper itself — bumped only if these four fields change. */
+export declare const RUN_LOG_WRAPPER_VERSION = 1;
+/** The pi session format version this package projects without migration. */
+export declare const SUPPORTED_PI_SESSION_VERSION = 3;
+export interface RunEventRecord {
+    /** The run this entry belongs to. */
+    runId: string;
+    /** 1-based position within the run. Gapless and strictly increasing. */
+    seq: number;
+    /** When the platform durably recorded the entry (ISO 8601). */
+    recordedAt: string;
+    /** pi's session format version at write time. */
+    piSessionVersion: number;
+    /** The pi session entry, byte-for-byte as pi produced it. */
+    entry: PiSessionEntry;
+}
+export interface WrapEntryOptions {
+    runId: string;
+    seq: number;
+    entry: PiSessionEntry;
+    recordedAt?: string;
+    piSessionVersion?: number;
+}
+export declare function wrapEntry(options: WrapEntryOptions): RunEventRecord;
+/**
+ * Narrow an untrusted record (database row, HTTP body). Throws on anything
+ * unreadable — a log that cannot be parsed must fail loudly, never silently
+ * render as an empty conversation.
+ */
+export declare function assertRunEventRecord(value: unknown): RunEventRecord;
+/**
+ * The de-duplication key for an append. pi 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;
+/** Records must be contiguous and in order before anything projects them. */
+export declare function assertOrdered(records: readonly RunEventRecord[]): void;