trajectories 0.0.0 → 0.1.2

package/dist/log-switch.js

@@ -0,0 +1,98 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { HARNESSES } from './types.js';
+import { TrajectoriesError } from './log-types.js';
+import { convertManaged, readNativeExportSnapshot, sha256, writeNativeExport } from './convert.js';
+import { digest, stableJson, withSessionLock } from './log-io.js';
+import { putText } from './log-content.js';
+import { initializeLog, publishFrame, readFrames } from './log-state.js';
+import { exportRecords, loadStage, MANAGED_CODEC_VERSION, recoverSnapshot } from './log-recovery.js';
+import { NATIVE_ENTROPY_VERSION } from './writers/entropy.js';
+import { readIntent, saveIntent } from './log-stage.js';
+import { receiptOf } from './log-read.js';
+const manifestOf = (native) => ({ ...native, files: native.files.map(file => ({ path: file.path,
+        sha256: sha256(file.content), sizeBytes: Buffer.byteLength(file.content) })) });
+async function preparedReceipt(store, frame) {
+    if (!frame.body.recipe)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Prepared binding recipe is missing.');
+    return { ...await receiptOf(store, frame), binding: frame.body.binding, native: frame.body.recipe.native };
+}
+export async function switchSession(store, id, target, requested) {
+    if (!requested || typeof requested !== 'object' || !requested.write || typeof requested.write !== 'object')
+        throw new TrajectoriesError('INVALID_INPUT', 'Export options are required.');
+    if (!HARNESSES.includes(target))
+        throw new TrajectoriesError('INVALID_INPUT', 'Unsupported target harness.');
+    let cwd;
+    try {
+        cwd = await realpath(resolve(requested.write.cwd));
+    }
+    catch (cause) {
+        throw new TrajectoriesError('INVALID_INPUT', 'Export workspace must exist.', { cause });
+    }
+    const write = { ...requested.write, directory: resolve(requested.write.directory), cwd };
+    const input = digest(stableJson({ operation: 'switch', id, target, expectedHead: requested.expectedHead, intentId: requested.intentId, write }));
+    return withSessionLock(store, id, async () => {
+        await initializeLog(store);
+        const frames = await readFrames(store, id), current = frames.at(-1);
+        if (!current)
+            throw new TrajectoriesError('NOT_FOUND', 'Managed session does not exist.');
+        const existing = await readIntent(store, id, requested.intentId);
+        if (existing && existing.input !== input)
+            throw new TrajectoriesError('INTENT_CONFLICT', 'This intent is bound to different export input or options.');
+        const committed = frames.find(frame => frame.body.intentId === requested.intentId);
+        if (committed) {
+            if (committed.body.input !== input)
+                throw new TrajectoriesError('INTENT_CONFLICT', 'Committed intent has different export input.');
+            if (current.head !== committed.head)
+                throw new TrajectoriesError('STALE_HEAD', 'Prepared child already has a successor.');
+            return preparedReceipt(store, committed);
+        }
+        if (current.head !== requested.expectedHead)
+            throw new TrajectoriesError('STALE_HEAD', 'Cannot prepare a continuation from a stale head.');
+        if (existing)
+            throw new TrajectoriesError('OUTCOME_UNKNOWN', 'Export intent has no committed receipt; reconcile its frozen files before admitting execution.');
+        if (cwd !== current.body.session.workspace)
+            throw new TrajectoriesError('INVALID_INPUT', 'Export must keep the managed workspace.');
+        try {
+            await lstat(write.directory);
+            throw new TrajectoriesError('INVALID_INPUT', 'Export destination already exists.');
+        }
+        catch (cause) {
+            if (cause.code !== 'ENOENT')
+                throw cause;
+        }
+        const capture = [...frames].reverse().find(frame => frame.body.capture)?.body.capture;
+        if (!capture)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Export source capture is missing.');
+        const snapshot = await recoverSnapshot(store, await loadStage(store, capture), frames);
+        const frozen = { ...write, sessionId: write.sessionId ?? randomUUID(), timestamp: write.timestamp ?? new Date().toISOString() };
+        const seed = digest(stableJson([input, 'native-entropy']));
+        let native;
+        try {
+            native = convertManaged(snapshot, target, frozen, seed, await exportRecords(store, frames, snapshot));
+        }
+        catch (cause) {
+            throw new TrajectoriesError('UNSUPPORTED_CONTEXT', cause instanceof Error ? cause.message : 'Export conversion failed.', { cause });
+        }
+        const baseline = readNativeExportSnapshot(native);
+        if (baseline.source.nativeSessionId !== native.sessionId)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Export failed to establish its native identity.');
+        const recipe = { version: 1, codec: MANAGED_CODEC_VERSION, entropy: NATIVE_ENTROPY_VERSION, seed,
+            atHead: current.head, write: frozen, native: manifestOf(native) };
+        // Freeze identity/entropy and every file fingerprint durably before writing any native file.
+        await saveIntent(store, id, requested.intentId, { input, export: recipe });
+        try {
+            await writeNativeExport(native, frozen.directory);
+        }
+        catch (cause) {
+            throw new TrajectoriesError('OUTCOME_UNKNOWN', 'Native export was interrupted; no binding was published.', { cause });
+        }
+        const binding = { id: `b_${digest(stableJson([id, requested.intentId]))}`, harness: target, nativeSessionId: native.sessionId };
+        const meta = baseline.canonical.records.find(record => record.record_type === 'meta');
+        const body = { parent: current.head, intentId: requested.intentId, input, time: new Date().toISOString(), kind: 'binding',
+            session: current.body.session, records: [], binding, progress: false, recipe,
+            diagnostics: await putText(store, stableJson(native.diagnostics)), ...(meta ? { nativeMeta: JSON.parse(meta.record_json) } : {}) };
+        return preparedReceipt(store, await publishFrame(store, body));
+    });
+}

package/dist/log-types.d.ts

@@ -0,0 +1,129 @@
+import type { NormalizedRecord } from '@letta-ai/trajectory';
+import type { ConversionDiagnostic, Harness, NativeExport, Snapshot, WriteOptions } from './types.js';
+export type Store = string;
+export type SessionId = string;
+export type IntentId = string;
+export type Head = string & {
+    readonly __head: unique symbol;
+};
+export type BindingId = string & {
+    readonly __binding: unique symbol;
+};
+export type CaptureId = string & {
+    readonly __capture: unique symbol;
+};
+export type RecordId = string & {
+    readonly __record: unique symbol;
+};
+export type PageCursor = string & {
+    readonly __cursor: unique symbol;
+};
+export interface NativeCheckpointLimits {
+    maxCount: number;
+    maxBytes: number;
+}
+export interface ManagedSession {
+    version: 2;
+    id: SessionId;
+    workspace: string;
+    head: Head;
+    createdAt: string;
+    updatedAt: string;
+    nativeCheckpoints: NativeCheckpointLimits;
+}
+export interface CaptureRef {
+    id: CaptureId;
+    sessionId: SessionId;
+    parent: Head | null;
+    intentId: IntentId;
+    bindingId?: BindingId;
+    integrity: string;
+    source: Pick<Snapshot['source'], 'harness' | 'nativeSessionId' | 'sha256'>;
+}
+export interface CommitReceipt {
+    intentId: IntentId;
+    session: ManagedSession;
+    parent: Head | null;
+    diagnostics: readonly ConversionDiagnostic[];
+    capture?: CaptureRef;
+}
+export interface PreparedExport extends Omit<NativeExport, 'files'> {
+    files: readonly {
+        path: string;
+        sha256: string;
+        sizeBytes: number;
+    }[];
+}
+export interface NativeBinding {
+    id: BindingId;
+    harness: Harness;
+    nativeSessionId: string;
+}
+export interface PreparedSession extends CommitReceipt {
+    binding: NativeBinding;
+    native: PreparedExport;
+}
+export interface ConversationRecord {
+    id: RecordId;
+    payload: NormalizedRecord;
+    origin: {
+        harness: Harness;
+        nativeSessionId?: string;
+        bindingId?: BindingId;
+    };
+}
+export interface Page<T> {
+    items: readonly T[];
+    nextCursor: PageCursor | null;
+}
+export type StageOptions = {
+    intentId: IntentId;
+    requireProgress?: boolean;
+} & ({
+    sessionId: SessionId;
+    expectedHead: null;
+    workspace: string;
+    nativeCheckpoints?: NativeCheckpointLimits;
+} | {
+    sessionId: SessionId;
+    expectedHead: Head;
+    bindingId?: BindingId;
+});
+export interface CreateOptions {
+    id: SessionId;
+    workspace: string;
+    intentId: IntentId;
+    nativeCheckpoints?: NativeCheckpointLimits;
+}
+export interface AppendOptions {
+    expectedHead: Head;
+    intentId: IntentId;
+    bindingId?: BindingId;
+    requireProgress?: boolean;
+}
+export interface SwitchOptions {
+    expectedHead: Head;
+    intentId: IntentId;
+    write: WriteOptions;
+}
+export interface ReadOptions {
+    atHead: Head;
+    view: 'history' | 'context';
+    cursor?: PageCursor;
+    limit?: number;
+}
+export interface HeadMetadata {
+    head: Head;
+    parent: Head | null;
+    kind: 'capture' | 'binding';
+    progress: boolean;
+    diagnostics: readonly ConversionDiagnostic[];
+    capture?: CaptureRef;
+    binding?: NativeBinding;
+    nativeMeta?: NormalizedRecord;
+}
+export type ErrorCode = 'INVALID_INPUT' | 'NOT_FOUND' | 'INTEGRITY_ERROR' | 'UNSUPPORTED_CONTEXT' | 'STALE_HEAD' | 'INTENT_CONFLICT' | 'OPERATION_PENDING' | 'OUTCOME_UNKNOWN' | 'CAPACITY_EXCEEDED';
+export declare class TrajectoriesError extends Error {
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/log-types.js

@@ -0,0 +1,8 @@
+export class TrajectoriesError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'TrajectoriesError';
+    }
+}

package/dist/log.d.ts

@@ -0,0 +1,8 @@
+import type { Snapshot } from './types.js';
+import type { AppendOptions, CaptureRef, CommitReceipt, CreateOptions } from './log-types.js';
+export { stageCapture } from './log-stage.js';
+export { switchSession } from './log-switch.js';
+export { getSession, listSessions, readSession, readCanonicalSession, getHeadMetadata, getNativeBinding } from './log-read.js';
+export type { CanonicalConversationRecord } from './log-records.js';
+export declare function createSession(store: string, input: Snapshot | CaptureRef, options: CreateOptions): Promise<CommitReceipt>;
+export declare function appendCapture(store: string, id: string, input: Snapshot | CaptureRef, options: AppendOptions): Promise<CommitReceipt>;

package/dist/log.js

@@ -0,0 +1,62 @@
+import { TrajectoriesError } from './log-types.js';
+import { getObject, stableJson, withSessionLock } from './log-io.js';
+import { initializeLog, publishFrame, readFrames } from './log-state.js';
+import { loadStage } from './log-recovery.js';
+import { normalizeStageOptions, readIntent, stageCapture, validateStageBacking } from './log-stage.js';
+import { receiptOf, selection } from './log-read.js';
+export { stageCapture } from './log-stage.js';
+export { switchSession } from './log-switch.js';
+export { getSession, listSessions, readSession, readCanonicalSession, getHeadMetadata, getNativeBinding } from './log-read.js';
+async function commitCapture(store, ref, requested) {
+    const options = await normalizeStageOptions(requested);
+    if (ref.sessionId !== options.sessionId || ref.intentId !== options.intentId || ref.parent !== options.expectedHead)
+        throw new TrajectoriesError('INTENT_CONFLICT', 'Capture reference does not belong to this session mutation.');
+    return withSessionLock(store, options.sessionId, async () => {
+        await initializeLog(store);
+        const stage = await loadStage(store, ref);
+        if (stableJson(stage.options) !== stableJson(options))
+            throw new TrajectoriesError('INTENT_CONFLICT', 'Commit options differ from the staged intent.');
+        const intent = await readIntent(store, options.sessionId, options.intentId);
+        if (!intent || intent.input !== stage.input || !intent.stage || stableJson(JSON.parse((await getObject(store, intent.stage)).toString())) !== stableJson(stage))
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'The staged capture has no matching durable intent binding.');
+        const frames = await readFrames(store, options.sessionId), current = frames.at(-1);
+        const committed = frames.find(frame => frame.body.intentId === options.intentId);
+        if (committed) {
+            if (committed.body.input !== stage.input)
+                throw new TrajectoriesError('INTENT_CONFLICT', 'Committed intent has different input.');
+            if (current.head !== committed.head)
+                throw new TrajectoriesError('STALE_HEAD', 'An acknowledged or unacknowledged child already has a successor.');
+            await validateStageBacking(store, stage, frames);
+            return receiptOf(store, committed);
+        }
+        if ((current?.head ?? null) !== options.expectedHead)
+            throw new TrajectoriesError('STALE_HEAD', 'Session head changed before capture commit.');
+        await validateStageBacking(store, stage, frames);
+        const now = new Date().toISOString();
+        const body = {
+            parent: options.expectedHead, intentId: options.intentId, input: stage.input, time: now, kind: 'capture',
+            session: current?.body.session ?? { id: options.sessionId, workspace: options.workspace,
+                createdAt: now, nativeCheckpoints: options.nativeCheckpoints },
+            records: stage.records, edit: stage.edit, binding: stage.binding, progress: stage.progress,
+            diagnostics: stage.diagnostics, ...(stage.nativeMeta ? { nativeMeta: stage.nativeMeta } : {}), capture: ref, stage: intent.stage,
+        };
+        // Validate the whole selection before appending its commit frame.
+        selection([...frames, { head: '', body }]);
+        return receiptOf(store, await publishFrame(store, body));
+    });
+}
+export async function createSession(store, input, options) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || !options || typeof options !== 'object')
+        throw new TrajectoriesError('INVALID_INPUT', 'Capture and create options are required.');
+    const stage = { sessionId: options.id, expectedHead: null, workspace: options.workspace,
+        intentId: options.intentId, ...(options.nativeCheckpoints ? { nativeCheckpoints: options.nativeCheckpoints } : {}) };
+    const ref = 'integrity' in input ? input : await stageCapture(store, input, stage);
+    return commitCapture(store, ref, stage);
+}
+export async function appendCapture(store, id, input, options) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || !options || typeof options !== 'object')
+        throw new TrajectoriesError('INVALID_INPUT', 'Capture and append options are required.');
+    const stage = { sessionId: id, ...options };
+    const ref = 'integrity' in input ? input : await stageCapture(store, input, stage);
+    return commitCapture(store, ref, stage);
+}

package/dist/migrate.d.ts

@@ -0,0 +1,29 @@
+import type { SessionBinding } from './types.js';
+import type { BindingId, CaptureRef, Head } from './log-types.js';
+export interface MigratedSession {
+    id: string;
+    head: Head;
+    heads: Record<string, Head>;
+    bindings: Array<{
+        sourceHead: string;
+        exportedSnapshotId: string;
+        harness: SessionBinding['harness'];
+        nativeSessionId: string;
+        head: Head;
+        bindingId: BindingId;
+    }>;
+    captures: Record<string, {
+        head: Head;
+        capture: CaptureRef;
+    }>;
+}
+export interface MigrationManifest {
+    version: 2;
+    sourceStore: string;
+    destinationStore: string;
+    sessions: MigratedSession[];
+}
+/** Offline migration. Callers freeze native and Workflow writers before asserting writersStopped. */
+export declare function migrateLegacyStore(source: string, destination: string, options: {
+    writersStopped: true;
+}): Promise<MigrationManifest>;

package/dist/migrate.js

@@ -0,0 +1,173 @@
+import { lstat, mkdir, readFile, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { assertPortableSnapshot, snapshotFromEvidence } from './convert.js';
+import { getSession as getLegacySession, getSnapshot, listSessions as listLegacySessions } from './store.js';
+import { appendCapture, createSession, getSession, readSession } from './log.js';
+import { atomicWrite, digest, ensureDirectory, safeId, stableJson, syncDirectory, withSessionLock } from './log-io.js';
+import { putText } from './log-content.js';
+import { initializeLog, publishFrame, readFrames } from './log-state.js';
+import { bindingSnapshot, loadStage, recoverEvidence, recoverSnapshot } from './log-recovery.js';
+import { loadRecord, units } from './log-records.js';
+import { selection } from './log-read.js';
+import { saveIntent } from './log-stage.js';
+import { mapPreparedRecords } from './log-baseline.js';
+function validateSnapshot(snapshot) {
+    try {
+        assertPortableSnapshot(snapshot);
+        if (snapshotFromEvidence({ harness: snapshot.source.harness, raw: snapshot.raw,
+            nativeSessionId: snapshot.source.nativeSessionId, attachments: snapshot.attachments }).id !== snapshot.id)
+            throw new Error('Legacy canonical history differs from its retained native evidence.');
+    }
+    catch (cause) {
+        throw new TrajectoriesError('UNSUPPORTED_CONTEXT', cause instanceof Error ? cause.message : 'Unsupported legacy history.', { cause });
+    }
+}
+function sameNative(a, b) {
+    return a.source.harness === b.source.harness && a.source.nativeSessionId === b.source.nativeSessionId;
+}
+async function importBinding(store, session, sourceHead, binding, index, snapshot, parent) {
+    validateSnapshot(snapshot);
+    if (snapshot.source.harness !== binding.harness || snapshot.source.nativeSessionId !== binding.nativeSessionId)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Legacy prepared binding disagrees with its retained native identity.');
+    const key = digest(stableJson([session.id, index, sourceHead, binding]));
+    const intentId = `m_binding_${key}`, bindingId = `b_m_${key}`;
+    return withSessionLock(store, session.id, async () => {
+        const frames = await readFrames(store, session.id), current = frames.at(-1);
+        if (current.head !== parent)
+            throw new TrajectoriesError('STALE_HEAD', 'Migration destination changed before binding publication.');
+        const selected = selection(frames), byId = new Map(selected.history.map(record => [record.id, record]));
+        const context = await Promise.all(selected.context.map(async (id) => ({ id, record: await loadRecord(store, byId.get(id)) })));
+        mapPreparedRecords(context, units(snapshot, true));
+        const input = digest(stableJson({ operation: 'migrate-binding', sessionId: session.id, parent, sourceHead, binding, snapshot: snapshot.id }));
+        await saveIntent(store, session.id, intentId, { input });
+        const { raw, canonical, attachments, ...header } = snapshot;
+        const evidence = { header, raw: await putText(store, raw), attachments: [] };
+        for (const attachment of attachments ?? [])
+            evidence.attachments.push({ name: attachment.name, sha256: attachment.sha256,
+                text: await putText(store, attachment.content) });
+        await recoverEvidence(store, evidence, frames);
+        const meta = canonical.records.find(record => record.record_type === 'meta');
+        const frame = await publishFrame(store, { parent, intentId, input, time: new Date().toISOString(), kind: 'binding',
+            session: current.body.session, records: [], binding: { id: bindingId, harness: binding.harness, nativeSessionId: binding.nativeSessionId },
+            progress: false, legacyBaseline: evidence, diagnostics: await putText(store, stableJson(canonical.diagnostics)),
+            ...(meta ? { nativeMeta: JSON.parse(meta.record_json) } : {}) });
+        return { sourceHead, exportedSnapshotId: snapshot.id, harness: binding.harness, nativeSessionId: binding.nativeSessionId,
+            head: frame.head, bindingId };
+    });
+}
+async function migrateSession(source, destination, session) {
+    safeId(session.id);
+    if (!session.snapshots.length || session.snapshots.at(-1) !== session.head || new Set(session.snapshots).size !== session.snapshots.length
+        || session.bindings.some(binding => !session.snapshots.includes(binding.snapshotId)))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Legacy session has an invalid accepted history or prepared source head.');
+    const migrated = { id: session.id, head: '', heads: {}, bindings: [], captures: {} };
+    let observed = await getSnapshot(source, session.snapshots[0]);
+    let selectedBinding;
+    for (const [index, oldHead] of session.snapshots.entries()) {
+        validateSnapshot(observed);
+        const intentId = `m_capture_${oldHead}`;
+        const receipt = index === 0
+            ? await createSession(destination, observed, { id: session.id, workspace: session.workspace, intentId })
+            : await appendCapture(destination, session.id, observed, { expectedHead: migrated.head, intentId,
+                ...(selectedBinding ? { bindingId: selectedBinding } : {}) });
+        migrated.head = receipt.session.head;
+        migrated.captures[oldHead] = { head: receipt.session.head, capture: receipt.capture };
+        const nextId = session.snapshots[index + 1], next = nextId ? await getSnapshot(source, nextId) : undefined;
+        const prepared = session.bindings.map((binding, ordinal) => ({ binding, ordinal })).filter(item => item.binding.snapshotId === oldHead);
+        const selected = next && !sameNative(observed, next) ? prepared.find(item => item.binding.harness === next.source.harness
+            && item.binding.nativeSessionId === next.source.nativeSessionId) : undefined;
+        if (next && !sameNative(observed, next) && !selected)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Legacy native handoff has no prepared binding at its accepted source head.');
+        selectedBinding = undefined;
+        // The capture's chosen old target must be the current binding at its new parent.
+        for (const item of [...prepared.filter(item => item !== selected), ...(selected ? [selected] : [])]) {
+            const baseline = await getSnapshot(source, item.binding.exportedSnapshotId);
+            const imported = await importBinding(destination, session, oldHead, item.binding, item.ordinal, baseline, migrated.head);
+            migrated.bindings.push(imported);
+            migrated.head = imported.head;
+            if (item === selected)
+                selectedBinding = imported.bindingId;
+        }
+        migrated.heads[oldHead] = migrated.head;
+        if (next)
+            observed = next;
+    }
+    const frames = await readFrames(destination, session.id);
+    for (const [oldId, captured] of Object.entries(migrated.captures)) {
+        const recovered = await recoverSnapshot(destination, await loadStage(destination, captured.capture), frames);
+        if (recovered.id !== oldId)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Migrated capture identity changed during reconstruction.');
+    }
+    for (const binding of migrated.bindings)
+        if ((await bindingSnapshot(destination, frames, binding.bindingId)).id !== binding.exportedSnapshotId)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Migrated prepared baseline identity changed during reconstruction.');
+    let cursor;
+    do {
+        const page = await readSession(destination, session.id, { atHead: migrated.head, view: 'history', cursor, limit: 1000 });
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    if ((await getSession(destination, session.id)).head !== migrated.head)
+        throw new TrajectoriesError('STALE_HEAD', 'Migration destination changed before verification.');
+    return migrated;
+}
+async function withSourceLocks(source, ids, action, offset = 0) {
+    return offset === ids.length ? action() : withSessionLock(source, ids[offset], () => withSourceLocks(source, ids, action, offset + 1));
+}
+/** Offline migration. Callers freeze native and Workflow writers before asserting writersStopped. */
+export async function migrateLegacyStore(source, destination, options) {
+    if (options?.writersStopped !== true)
+        throw new TrajectoriesError('INVALID_INPUT', 'Stop all native and Workflow writers before migration; writersStopped must be true.');
+    if (typeof source !== 'string' || !source || typeof destination !== 'string' || !destination)
+        throw new TrajectoriesError('INVALID_INPUT', 'Migration source and destination paths are required.');
+    try {
+        const sourceStore = await realpath(resolve(source)), destinationPath = resolve(destination);
+        try {
+            await lstat(destinationPath);
+            throw new TrajectoriesError('INVALID_INPUT', 'Migration destination must be fresh; existing and partial destinations are preserved.');
+        }
+        catch (cause) {
+            if (cause.code !== 'ENOENT')
+                throw cause;
+        }
+        if (!(await lstat(join(sourceStore, 'sessions'))).isDirectory())
+            throw new TrajectoriesError('INVALID_INPUT', 'Migration source must be a version-1 session store.');
+        try {
+            const format = JSON.parse(await readFile(join(sourceStore, 'format.json'), 'utf8'));
+            if (format.version !== 1)
+                throw new TrajectoriesError('INVALID_INPUT', 'Migration source must use version 1.');
+        }
+        catch (cause) {
+            if (cause.code !== 'ENOENT')
+                throw cause;
+        }
+        const initial = await listLegacySessions(sourceStore), ids = initial.map(session => session.id).sort();
+        return await withSourceLocks(sourceStore, ids, async () => {
+            const sessions = await Promise.all(ids.map(id => getLegacySession(sourceStore, id)));
+            if (stableJson((await listLegacySessions(sourceStore)).map(session => session.id).sort()) !== stableJson(ids))
+                throw new TrajectoriesError('OPERATION_PENDING', 'Legacy session inventory changed while acquiring migration locks.');
+            await ensureDirectory(dirname(destinationPath));
+            try {
+                await mkdir(destinationPath, { mode: 0o700 });
+            }
+            catch (cause) {
+                if (cause.code === 'EEXIST')
+                    throw new TrajectoriesError('INVALID_INPUT', 'Migration destination already exists.', { cause });
+                throw cause;
+            }
+            await syncDirectory(dirname(destinationPath));
+            const destinationStore = await realpath(destinationPath);
+            await initializeLog(destinationStore);
+            const manifest = { version: 2, sourceStore, destinationStore, sessions: [] };
+            for (const session of sessions)
+                manifest.sessions.push(await migrateSession(sourceStore, destinationStore, session));
+            await atomicWrite(join(destinationStore, 'migration.json'), stableJson(manifest) + '\n', true);
+            return manifest;
+        });
+    }
+    catch (cause) {
+        if (cause instanceof TrajectoriesError)
+            throw cause;
+        throw new TrajectoriesError('INTEGRITY_ERROR', cause instanceof Error ? cause.message : 'Legacy migration failed; preserve the source and partial destination.', { cause });
+    }
+}

package/dist/normalization-runtime.d.ts

@@ -0,0 +1 @@
+export { NormalizationError, normalizeToCanonical, normalizeTranscript, } from '@letta-ai/trajectory';