trajectories 0.0.0 → 0.1.1

package/dist/log-records.js

@@ -0,0 +1,85 @@
+import { digest, getObject, putObject, stableJson } from './log-io.js';
+import { TrajectoriesError } from './log-types.js';
+import { portableConversationTokens } from './portable.js';
+import { normalizePiArchive, projectPiDrafts } from './readers/pi-context.js';
+import { getText as loadText, putText as saveText } from './log-content.js';
+export function units(snapshot, archive = false) {
+    const records = archive && snapshot.source.harness === 'pi'
+        ? projectPiDrafts(snapshot.raw, normalizePiArchive(snapshot.raw)).records : snapshot.canonical.records;
+    const result = [];
+    for (const canonical of records) {
+        const original = JSON.parse(canonical.record_json);
+        for (const token of portableConversationTokens([original])) {
+            const payload = original.role === 'assistant' && 'tool_calls' in original
+                ? { ...original, tool_calls: [original.tool_calls[token.componentIndex]] } : original;
+            const record_json = JSON.stringify(payload);
+            result.push({ semantic: token.semantic, payload,
+                canonical: { ...canonical, record_json, record_hash: digest(record_json) } });
+        }
+    }
+    return result;
+}
+function nativeKey(unit) {
+    return stableJson([unit.canonical.stable_source_record_id, unit.canonical.component_index, unit.semantic]);
+}
+export function contextEdit(before, after) {
+    let start = 0, end = 0;
+    while (start < before.length && start < after.length && before[start] === after[start])
+        start++;
+    while (end < before.length - start && end < after.length - start && before.at(-end - 1) === after.at(-end - 1))
+        end++;
+    return { start, remove: before.length - start - end, insert: after.slice(start, after.length - end) };
+}
+export function applyEdit(context, edit) {
+    if (!edit)
+        return [...context];
+    if (!Number.isSafeInteger(edit.start) || !Number.isSafeInteger(edit.remove) || edit.start < 0 || edit.remove < 0
+        || edit.start + edit.remove > context.length)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid context edit.');
+    return [...context.slice(0, edit.start), ...edit.insert, ...context.slice(edit.start + edit.remove)];
+}
+export async function loadRecord(store, record) {
+    const ref = JSON.parse((await getObject(store, record.object)).toString());
+    const stored = JSON.parse(await loadText(store, ref));
+    const value = { ...stored, payload: JSON.parse(stored.canonical.record_json) };
+    if (digest(stored.canonical.record_json) !== stored.canonical.record_hash)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Canonical payload hash mismatch.');
+    if (value.id !== record.id)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Canonical record identity mismatch.');
+    return value;
+}
+export async function planRecords(input) {
+    const archive = units(input.observed, true), mapping = [...input.beforeIds], records = [], added = [];
+    async function accept(unit) {
+        const id = `r_${digest(stableJson([input.sessionId, input.intentId, records.length]))}`;
+        const value = { id, canonical: unit.canonical, origin: input.origin };
+        const text = await saveText(input.store, stableJson(value));
+        records.push({ id, object: await putObject(input.store, stableJson(text)) });
+        return id;
+    }
+    let leading, offset = 0;
+    if (input.allowInitialSystem && input.before[0]?.payload.role !== 'system' && archive[0]?.payload.role === 'system') {
+        leading = await accept(archive[0]);
+        mapping.unshift(leading);
+        offset = 1;
+    }
+    if (archive.length - offset < input.before.length || input.before.some((unit, i) => unit.semantic !== archive[i + offset]?.semantic))
+        throw new TrajectoriesError('UNSUPPORTED_CONTEXT', 'Captured archive does not preserve its latest accepted native prefix.');
+    for (let i = input.before.length + offset; i < archive.length; i++) {
+        const id = await accept(archive[i]);
+        mapping.push(id);
+        added.push(id);
+    }
+    const byNative = new Map();
+    for (const [index, unit] of input.beforeActive.entries())
+        if (input.beforeActiveIds[index])
+            byNative.set(nativeKey(unit), input.beforeActiveIds[index]);
+    for (const [index, unit] of archive.entries())
+        if (mapping[index])
+            byNative.set(nativeKey(unit), mapping[index]);
+    const active = [];
+    for (const unit of units(input.observed))
+        active.push(byNative.get(nativeKey(unit)) ?? await accept(unit));
+    return { records, edit: contextEdit(input.context, active), added, ...(leading ? { leading } : {}),
+        progress: archive.length - offset > input.before.length };
+}

package/dist/log-recovery.d.ts

@@ -0,0 +1,18 @@
+import type { NativeExport, Snapshot } from './types.js';
+import type { BindingId, CaptureRef } from './log-types.js';
+import type { Frame, StageData } from './log-state.js';
+export declare const MANAGED_CODEC_VERSION = "trajectories-native-codec-2";
+export declare const capturePath: (store: string, id: string) => string;
+export declare function loadStage(store: string, ref: CaptureRef): Promise<StageData>;
+interface RecoveryCache {
+    snapshots: Map<string, Snapshot>;
+    bindings: Map<string, Snapshot>;
+    exports: Map<string, NativeExport>;
+    visiting: Set<string>;
+}
+export declare function regenerateExport(store: string, frames: Frame[], bindingId: BindingId, cache?: RecoveryCache): Promise<NativeExport>;
+export declare function bindingSnapshot(store: string, frames: Frame[], bindingId: BindingId, cache?: RecoveryCache): Promise<Snapshot>;
+export declare function exportRecords(store: string, frames: Frame[], source: Snapshot): Promise<import('@letta-ai/trajectory').NormalizedRecord[]>;
+export declare function recoverSnapshot(store: string, stage: StageData, frames: Frame[], cache?: RecoveryCache): Promise<Snapshot>;
+export declare function recoverEvidence(store: string, evidence: StageData['evidence'], frames: Frame[], ownId?: string, cache?: RecoveryCache): Promise<Snapshot>;
+export {};

package/dist/log-recovery.js

@@ -0,0 +1,123 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { getObject, safeId, stableJson } from './log-io.js';
+import { derivedChunks, getText } from './log-content.js';
+import { atHead, selection } from './log-read.js';
+import { loadRecord } from './log-records.js';
+import { convertManaged, readNativeExportSnapshot, sha256, snapshotFromEvidence } from './convert.js';
+import { NATIVE_ENTROPY_VERSION } from './writers/entropy.js';
+export const MANAGED_CODEC_VERSION = 'trajectories-native-codec-2';
+export const capturePath = (store, id) => join(resolve(store), 'captures', `${safeId(id)}.json`);
+export async function loadStage(store, ref) {
+    let pointer;
+    try {
+        pointer = JSON.parse(await readFile(capturePath(store, ref.id), 'utf8'));
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            throw new TrajectoriesError('NOT_FOUND', 'The staged capture is missing from this store.', { cause });
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'The staged capture pointer is corrupt or unreadable.', { cause });
+    }
+    let stage;
+    try {
+        stage = JSON.parse((await getObject(store, pointer.object)).toString());
+    }
+    catch (cause) {
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid staged capture manifest.', { cause });
+    }
+    if (stage.version !== 2 || stage.input !== ref.integrity || stableJson(stage.ref) !== stableJson(ref))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Capture reference does not match its retained manifest.');
+    return stage;
+}
+const recoveryCache = () => ({ snapshots: new Map(), bindings: new Map(), exports: new Map(), visiting: new Set() });
+async function retained(cache, map, key, action) {
+    if (map.has(key))
+        return map.get(key);
+    if (cache.visiting.has(key))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Retained native evidence contains a reference cycle.');
+    cache.visiting.add(key);
+    try {
+        const value = await action();
+        map.set(key, value);
+        return value;
+    }
+    finally {
+        cache.visiting.delete(key);
+    }
+}
+export async function regenerateExport(store, frames, bindingId, cache = recoveryCache()) {
+    return retained(cache, cache.exports, `export:${bindingId}`, async () => {
+        const prepared = frames.find(frame => frame.body.kind === 'binding' && frame.body.binding.id === bindingId);
+        const recipe = prepared?.body.recipe;
+        if (!recipe || recipe.codec !== MANAGED_CODEC_VERSION || recipe.entropy !== NATIVE_ENTROPY_VERSION)
+            throw new TrajectoriesError('UNSUPPORTED_CONTEXT', 'The exact export codec is unavailable; migrate before continuing.');
+        const sourceFrames = atHead(frames, recipe.atHead);
+        if (prepared.body.parent !== recipe.atHead)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Export baseline must reference its exact parent.');
+        const capture = [...sourceFrames].reverse().find(frame => frame.body.capture)?.body.capture;
+        if (!capture)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Export source capture is missing.');
+        const source = await recoverSnapshot(store, await loadStage(store, capture), sourceFrames, cache);
+        const native = convertManaged(source, prepared.body.binding.harness, recipe.write, recipe.seed, await exportRecords(store, sourceFrames, source));
+        if (native.files.length !== recipe.native.files.length || native.files.some((file, index) => {
+            const expected = recipe.native.files[index];
+            return !expected || file.path !== expected.path || sha256(file.content) !== expected.sha256 || Buffer.byteLength(file.content) !== expected.sizeBytes;
+        }))
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Frozen export does not reproduce all prepared native files.');
+        return native;
+    });
+}
+export async function bindingSnapshot(store, frames, bindingId, cache = recoveryCache()) {
+    return retained(cache, cache.bindings, `binding:${bindingId}`, async () => {
+        const frame = frames.find(frame => frame.body.kind === 'binding' && frame.body.binding.id === bindingId);
+        if (frame?.body.legacyBaseline)
+            return recoverEvidence(store, frame.body.legacyBaseline, frames, undefined, cache);
+        return readNativeExportSnapshot(await regenerateExport(store, frames, bindingId, cache));
+    });
+}
+export async function exportRecords(store, frames, source) {
+    const selected = selection(frames), byId = new Map(selected.history.map(record => [record.id, record]));
+    const context = await Promise.all(selected.context.map(id => loadRecord(store, byId.get(id))));
+    const meta = source.canonical.records.find(record => record.record_type === 'meta');
+    return [...(meta ? [JSON.parse(meta.record_json)] : []), ...context.map(record => record.payload)];
+}
+export async function recoverSnapshot(store, stage, frames, cache = recoveryCache()) {
+    return retained(cache, cache.snapshots, `capture:${stage.ref.id}`, () => recoverEvidence(store, stage.evidence, frames, stage.ref.id, cache));
+}
+export async function recoverEvidence(store, evidence, frames, ownId, cache = recoveryCache()) {
+    let derived;
+    if (evidence.derivedBinding) {
+        const native = await regenerateExport(store, frames, evidence.derivedBinding, cache);
+        const baseline = readNativeExportSnapshot(native);
+        derived = derivedChunks([baseline.raw, ...(baseline.attachments ?? []).map(a => a.content)]);
+    }
+    let raw = await getText(store, evidence.raw, derived);
+    const prefix = evidence.prefix;
+    if (prefix) {
+        let baseline;
+        if (prefix.capture) {
+            const frame = frames.find(frame => frame.body.capture?.id === prefix.capture), ref = frame?.body.capture;
+            if (!ref || ref.id === ownId)
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Missing or cyclic evidence prefix.');
+            baseline = await recoverSnapshot(store, await loadStage(store, ref), atHead(frames, frame.head), cache);
+        }
+        else if (prefix.binding)
+            baseline = await bindingSnapshot(store, frames, prefix.binding, cache);
+        else
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Evidence prefix has no retained source.');
+        if (sha256(baseline.raw) !== prefix.sha256 || Buffer.byteLength(baseline.raw) !== prefix.bytes)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Evidence prefix integrity mismatch.');
+        raw = baseline.raw + raw;
+    }
+    const attachments = [];
+    for (const attachment of evidence.attachments)
+        attachments.push({ name: attachment.name,
+            content: await getText(store, attachment.text, derived), sha256: attachment.sha256 });
+    const header = evidence.header;
+    const snapshot = snapshotFromEvidence({ harness: header.source.harness, raw,
+        ...(header.source.nativeSessionId ? { nativeSessionId: header.source.nativeSessionId } : {}), attachments });
+    if (snapshot.id !== header.id || snapshot.source.sha256 !== header.source.sha256)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Retained native evidence does not reproduce its captured canonical identity.');
+    return { ...snapshot, createdAt: header.createdAt, source: header.source };
+}

package/dist/log-stage.d.ts

@@ -0,0 +1,14 @@
+import type { Snapshot } from './types.js';
+import type { CaptureRef, NativeCheckpointLimits, StageOptions } from './log-types.js';
+import { type StageData } from './log-state.js';
+export interface IntentData {
+    input: string;
+    stage?: string;
+    export?: import('./log-state.js').ExportRecipe;
+}
+export declare function readIntent(store: string, id: string, intent: string): Promise<IntentData | null>;
+export declare function saveIntent(store: string, id: string, intent: string, data: IntentData): Promise<void>;
+export declare function checkpointLimits(value?: NativeCheckpointLimits): NativeCheckpointLimits;
+export declare function normalizeStageOptions(options: StageOptions): Promise<StageOptions>;
+export declare function stageCapture(store: string, snapshot: Snapshot, requested: StageOptions): Promise<CaptureRef>;
+export declare function validateStageBacking(store: string, stage: StageData, frames: import('./log-state.js').Frame[]): Promise<void>;

package/dist/log-stage.js

@@ -0,0 +1,138 @@
+import { readFile, realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { assertPortableSnapshot, assertSnapshot, snapshotFromEvidence } from './convert.js';
+import { atomicWrite, digest, getObject, putObject, safeId, stableJson, withSessionLock } from './log-io.js';
+import { derivedChunks, putText } from './log-content.js';
+import { intentPath, initializeLog, readFrames } from './log-state.js';
+import { capturePath, loadStage, recoverSnapshot, regenerateExport } from './log-recovery.js';
+import { planRecords } from './log-records.js';
+import { units, loadRecord } from './log-records.js';
+import { captureBaseline } from './log-baseline.js';
+import { selection } from './log-read.js';
+import { assertSnapshotContinuation } from './store.js';
+import { readNativeExportSnapshot, sha256 } from './convert.js';
+export async function readIntent(store, id, intent) {
+    try {
+        return JSON.parse(await readFile(intentPath(store, id, intent), 'utf8'));
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return null;
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Intent binding is corrupt.', { cause });
+    }
+}
+export async function saveIntent(store, id, intent, data) {
+    await atomicWrite(intentPath(store, id, intent), stableJson(data));
+}
+export function checkpointLimits(value = { maxCount: 0, maxBytes: 0 }) {
+    if (!Number.isSafeInteger(value.maxCount) || !Number.isSafeInteger(value.maxBytes) || value.maxCount < 0 || value.maxBytes < 0)
+        throw new TrajectoriesError('INVALID_INPUT', 'Native checkpoint count and byte limits must be nonnegative safe integers.');
+    return { maxCount: value.maxCount, maxBytes: value.maxBytes };
+}
+export async function normalizeStageOptions(options) {
+    if (!options || typeof options !== 'object')
+        throw new TrajectoriesError('INVALID_INPUT', 'Stage options are required.');
+    safeId(options.sessionId);
+    safeId(options.intentId);
+    if (options.requireProgress !== undefined && typeof options.requireProgress !== 'boolean')
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid progress guard.');
+    if (options.expectedHead === null) {
+        let workspace;
+        try {
+            workspace = await realpath(resolve(options.workspace));
+        }
+        catch (cause) {
+            throw new TrajectoriesError('INVALID_INPUT', 'Workspace must exist.', { cause });
+        }
+        return { ...options, workspace, nativeCheckpoints: checkpointLimits(options.nativeCheckpoints), requireProgress: options.requireProgress ?? false };
+    }
+    if (!/^[a-f0-9]{64}$/.test(options.expectedHead))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid expected head.');
+    return { ...options, requireProgress: options.requireProgress ?? false };
+}
+export async function stageCapture(store, snapshot, requested) {
+    const options = await normalizeStageOptions(requested);
+    try {
+        assertSnapshot(snapshot);
+    }
+    catch (cause) {
+        throw new TrajectoriesError('INVALID_INPUT', 'Capture must be a valid, intact Snapshot.', { cause });
+    }
+    try {
+        assertPortableSnapshot(snapshot);
+        const recovered = snapshotFromEvidence({ harness: snapshot.source.harness, raw: snapshot.raw,
+            ...(snapshot.source.nativeSessionId ? { nativeSessionId: snapshot.source.nativeSessionId } : {}), attachments: snapshot.attachments });
+        if (recovered.id !== snapshot.id)
+            throw new Error('Canonical input differs from its retained native evidence.');
+    }
+    catch (cause) {
+        throw new TrajectoriesError('UNSUPPORTED_CONTEXT', cause instanceof Error ? cause.message : 'Invalid captured history.', { cause });
+    }
+    const input = digest(stableJson({ operation: options.expectedHead === null ? 'create' : 'append', options, snapshot: snapshot.id }));
+    return withSessionLock(store, options.sessionId, async () => {
+        await initializeLog(store);
+        const frames = await readFrames(store, options.sessionId), current = frames.at(-1);
+        const existing = await readIntent(store, options.sessionId, options.intentId);
+        if (existing) {
+            if (existing.input !== input)
+                throw new TrajectoriesError('INTENT_CONFLICT', 'This intent is bound to different capture input or options.');
+            if (!existing.stage)
+                throw new TrajectoriesError('OPERATION_PENDING', 'This capture is still publishing; reconcile the original intent.');
+            const stage = JSON.parse((await getObject(store, existing.stage)).toString());
+            await loadStage(store, stage.ref);
+            await validateStageBacking(store, stage, frames);
+            return stage.ref;
+        }
+        if ((current?.head ?? null) !== options.expectedHead)
+            throw new TrajectoriesError('STALE_HEAD', 'The session head changed before staging.');
+        let baseline;
+        if (options.expectedHead !== null) {
+            baseline = await captureBaseline(store, frames, snapshot, options.bindingId);
+            try {
+                assertSnapshotContinuation(baseline.snapshot, snapshot, { requireProgress: options.requireProgress, allowInitialSystem: baseline.firstTarget });
+            }
+            catch (cause) {
+                throw new TrajectoriesError('UNSUPPORTED_CONTEXT', cause instanceof Error ? cause.message : 'Capture failed continuity validation.', { cause });
+            }
+        }
+        await saveIntent(store, options.sessionId, options.intentId, { input });
+        const binding = baseline?.binding ?? { id: `b_${digest(stableJson([options.sessionId, options.intentId]))}`,
+            harness: snapshot.source.harness, nativeSessionId: snapshot.source.nativeSessionId ?? '' };
+        const ref = { id: `c_${input}`, sessionId: options.sessionId, parent: options.expectedHead, intentId: options.intentId,
+            bindingId: binding.id, integrity: input, source: { harness: snapshot.source.harness, sha256: snapshot.source.sha256,
+                ...(snapshot.source.nativeSessionId ? { nativeSessionId: snapshot.source.nativeSessionId } : {}) } };
+        const planned = await planRecords({ store, sessionId: options.sessionId, intentId: options.intentId, observed: snapshot,
+            before: baseline?.before ?? [], beforeIds: baseline?.ids ?? [], beforeActive: baseline ? units(baseline.snapshot) : [],
+            beforeActiveIds: baseline?.activeIds ?? [], context: selection(frames).context, allowInitialSystem: baseline?.firstTarget,
+            origin: { harness: binding.harness, ...(binding.nativeSessionId ? { nativeSessionId: binding.nativeSessionId } : {}), bindingId: binding.id } });
+        const { raw, canonical, attachments, ...header } = snapshot;
+        const generated = baseline?.derivedBinding ? readNativeExportSnapshot(await regenerateExport(store, frames, baseline.derivedBinding)) : undefined;
+        const derived = generated ? derivedChunks([generated.raw, ...(generated.attachments ?? []).map(a => a.content)]) : undefined;
+        const prefix = baseline && raw.startsWith(baseline.snapshot.raw) ? { ...baseline.mapping,
+            sha256: sha256(baseline.snapshot.raw), bytes: Buffer.byteLength(baseline.snapshot.raw) } : undefined;
+        const evidence = { header, raw: await putText(store, prefix ? raw.slice(baseline.snapshot.raw.length) : raw, derived), attachments: [],
+            ...(baseline?.derivedBinding ? { derivedBinding: baseline.derivedBinding } : {}), ...(prefix ? { prefix } : {}) };
+        for (const attachment of attachments ?? [])
+            evidence.attachments.push({ name: attachment.name, sha256: attachment.sha256, text: await putText(store, attachment.content, derived) });
+        const meta = canonical.records.find(record => record.record_type === 'meta');
+        const stage = { version: 2, ref, input, options, evidence, records: planned.records, edit: planned.edit,
+            progress: planned.progress, diagnostics: await putText(store, stableJson(canonical.diagnostics)),
+            ...(meta ? { nativeMeta: JSON.parse(meta.record_json) } : {}), mapping: { ...baseline?.mapping, added: planned.added,
+                ...(planned.leading ? { leading: planned.leading } : {}) }, binding };
+        const object = await putObject(store, stableJson(stage));
+        await atomicWrite(capturePath(store, ref.id), stableJson({ object }), true);
+        await validateStageBacking(store, stage, frames);
+        await saveIntent(store, options.sessionId, options.intentId, { input, stage: object });
+        return ref;
+    });
+}
+export async function validateStageBacking(store, stage, frames) {
+    await recoverSnapshot(store, stage, frames);
+    const parent = stage.ref.parent;
+    const index = parent === null ? -1 : frames.findIndex(frame => frame.head === parent);
+    if (parent !== null && index < 0)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Staged parent is missing.');
+    for (const record of [...selection(frames.slice(0, index + 1)).history, ...stage.records])
+        await loadRecord(store, record);
+}

package/dist/log-state.d.ts

@@ -0,0 +1,89 @@
+import type { Snapshot, WriteOptions } from './types.js';
+import type { BindingId, CaptureId, CaptureRef, Head, NativeBinding, NativeCheckpointLimits, PreparedExport, RecordId, StageOptions } from './log-types.js';
+import type { TextRef } from './log-content.js';
+export interface StoredRecord {
+    id: RecordId;
+    object: string;
+}
+export interface ContextEdit {
+    start: number;
+    remove: number;
+    insert: RecordId[];
+}
+export interface ExportRecipe {
+    version: 1;
+    codec: string;
+    entropy: string;
+    seed: string;
+    atHead: Head;
+    write: WriteOptions;
+    native: PreparedExport;
+}
+export interface FrameBody {
+    parent: Head | null;
+    intentId: string;
+    input: string;
+    time: string;
+    kind: 'capture' | 'binding';
+    session: {
+        id: string;
+        workspace: string;
+        createdAt: string;
+        nativeCheckpoints: NativeCheckpointLimits;
+    };
+    records: StoredRecord[];
+    edit?: ContextEdit;
+    binding: NativeBinding;
+    progress: boolean;
+    diagnostics: TextRef;
+    nativeMeta?: import('@letta-ai/trajectory').NormalizedRecord;
+    capture?: CaptureRef;
+    stage?: string;
+    recipe?: ExportRecipe;
+    /** Migration-only seed for old exports whose random metadata cannot be regenerated. */
+    legacyBaseline?: StageData['evidence'];
+}
+export interface Frame {
+    head: Head;
+    body: FrameBody;
+}
+export interface StageData {
+    version: 2;
+    ref: CaptureRef;
+    input: string;
+    options: StageOptions;
+    evidence: {
+        header: Omit<Snapshot, 'raw' | 'canonical' | 'attachments'>;
+        raw: TextRef;
+        attachments: Array<{
+            name: string;
+            sha256: string;
+            text: TextRef;
+        }>;
+        derivedBinding?: BindingId;
+        prefix?: {
+            capture?: CaptureId;
+            binding?: BindingId;
+            sha256: string;
+            bytes: number;
+        };
+    };
+    records: StoredRecord[];
+    edit: ContextEdit;
+    progress: boolean;
+    diagnostics: TextRef;
+    nativeMeta?: import('@letta-ai/trajectory').NormalizedRecord;
+    mapping: {
+        capture?: CaptureId;
+        binding?: BindingId;
+        leading?: RecordId;
+        added: RecordId[];
+    };
+    binding: NativeBinding;
+}
+export declare const logPath: (store: string, id: string) => string;
+export declare const intentPath: (store: string, id: string, intent: string) => string;
+export declare function assertLogStore(store: string): Promise<void>;
+export declare function initializeLog(store: string): Promise<void>;
+export declare function readFrames(store: string, id: string): Promise<Frame[]>;
+export declare function publishFrame(store: string, body: FrameBody): Promise<Frame>;

package/dist/log-state.js

@@ -0,0 +1,92 @@
+import { open, readFile, readdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { atomicWrite, digest, ensureDirectory, safeId, stableJson, syncDirectory } from './log-io.js';
+export const logPath = (store, id) => join(resolve(store), 'logs', `${safeId(id)}.jsonl`);
+export const intentPath = (store, id, intent) => join(resolve(store), 'intents', safeId(id), `${safeId(intent)}.json`);
+export async function assertLogStore(store) {
+    try {
+        const legacy = await readdir(join(resolve(store), 'sessions'));
+        if (legacy.some(name => name.endsWith('.json')))
+            throw new TrajectoriesError('INVALID_INPUT', 'Version-1 session authority found; migrate this store before using the canonical log.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const marker = join(resolve(store), 'format.json');
+    try {
+        const current = JSON.parse(await readFile(marker, 'utf8'));
+        if (current.version !== 2)
+            throw new TrajectoriesError('INVALID_INPUT', 'Store migration is required.');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        if (error instanceof TrajectoriesError)
+            throw error;
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Store format marker is corrupt or unreadable.', { cause: error });
+    }
+}
+export async function initializeLog(store) {
+    await assertLogStore(store);
+    const marker = join(resolve(store), 'format.json');
+    try {
+        await readFile(marker);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        try {
+            await atomicWrite(marker, stableJson({ version: 2 }), true);
+        }
+        catch (cause) {
+            if (cause.code !== 'EEXIST')
+                throw cause;
+        }
+    }
+}
+export async function readFrames(store, id) {
+    await assertLogStore(store);
+    let text;
+    try {
+        text = await readFile(logPath(store, id), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    if (!text.endsWith('\n'))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'The canonical log has a partial tail; reconcile it before continuing.');
+    const frames = [];
+    for (const line of text.slice(0, -1).split('\n')) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch (cause) {
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'The canonical log contains invalid JSON.', { cause });
+        }
+        if (!frame?.body || digest(stableJson(frame.body)) !== frame.head || frame.body.parent !== (frames.at(-1)?.head ?? null)
+            || frame.body.session.id !== id)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'The canonical log chain is corrupt.');
+        frames.push(frame);
+    }
+    return frames;
+}
+export async function publishFrame(store, body) {
+    const frame = { head: digest(stableJson(body)), body };
+    const path = logPath(store, body.session.id);
+    await ensureDirectory(dirname(path));
+    const file = await open(path, 'a', 0o600);
+    try {
+        await file.writeFile(stableJson(frame) + '\n');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await syncDirectory(dirname(path));
+    return frame;
+}

package/dist/log-switch.d.ts

@@ -0,0 +1,3 @@
+import { type Harness } from './types.js';
+import type { PreparedSession, SwitchOptions } from './log-types.js';
+export declare function switchSession(store: string, id: string, target: Harness, requested: SwitchOptions): Promise<PreparedSession>;