trajectories 0.0.0 → 0.1.1

package/dist/readers/guards.js

@@ -0,0 +1,121 @@
+import { assertCursorPortable } from './cursor.js';
+import { assertDeepAgentsPortable } from './deepagents.js';
+import { assertGitHubCopilotHistory } from './github-copilot.js';
+import { assertClinePortable } from './cline.js';
+import { assertFxPortable } from './fx.js';
+import { piCompactedContext } from './pi-compaction.js';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+function unsupported(harness, reason) {
+    throw new Error(`Unsupported ${harness} continuation history: ${reason}. Native bytes can be archived, but this bootstrap cannot safely export their active context.`);
+}
+/** The upstream normalizer is an archive reader, not a native active-branch resolver. */
+export function assertPortableHistory(harness, raw, fxCompanions = {}) {
+    if (harness === 'cursor')
+        return assertCursorPortable(raw);
+    if (harness === 'deepagents')
+        return assertDeepAgentsPortable(raw);
+    if (harness === 'github-copilot')
+        return assertGitHubCopilotHistory(raw);
+    if (harness === 'cline')
+        return assertClinePortable(raw);
+    if (harness === 'fx')
+        return assertFxPortable(raw, fxCompanions);
+    if (harness === 'opencode') {
+        const data = JSON.parse(raw);
+        if (data.info?.revert != null)
+            unsupported(harness, 'reverted history requires native context reconstruction');
+        for (const message of data.messages ?? []) {
+            if (message.info?.summary === true)
+                unsupported(harness, 'summary history requires native context reconstruction');
+            for (const part of message.parts ?? []) {
+                if (part.type === 'compaction' || part.ignored === true || part.state?.time?.compacted != null)
+                    unsupported(harness, 'compacted or ignored history requires native context reconstruction');
+            }
+        }
+        return;
+    }
+    if (!['pi', 'omp', 'claude-code', 'codex'].includes(harness))
+        return;
+    const rows = raw.split('\n').filter(line => line.trim()).map((line, index) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`Invalid native JSON at line ${index + 1}.`);
+        }
+        if (!object(parsed))
+            throw new Error(`Invalid native record at line ${index + 1}.`);
+        return parsed;
+    });
+    if (harness === 'codex') {
+        for (const row of rows) {
+            const payload = object(row.payload) ? row.payload : {};
+            if (row.type === 'compacted' || (row.type === 'event_msg' && ['thread_rolled_back', 'context_compacted'].includes(String(payload.type)))) {
+                unsupported(harness, 'compaction or rollback requires native context reconstruction');
+            }
+            if (row.type === 'session_meta' && payload.history_base != null)
+                unsupported(harness, 'inherited history lives in an external rollout prefix');
+        }
+        return;
+    }
+    if (harness === 'pi' || harness === 'omp') {
+        if (harness === 'pi' && piCompactedContext(raw))
+            return;
+        for (const row of rows) {
+            if (['compaction', 'branch_summary', 'reset_boundary'].includes(String(row.type)))
+                unsupported(harness, `${String(row.type)} requires native context reconstruction`);
+            const message = object(row.message) ? row.message : {};
+            if (row.type === 'custom_message' || (row.type === 'message' && ['custom', 'hookMessage'].includes(String(message.role))))
+                unsupported(harness, 'custom context messages require native context reconstruction');
+        }
+        const chain = rows.filter(row => typeof row.id === 'string' && Object.hasOwn(row, 'parentId'));
+        const messages = rows.filter(row => row.type === 'message');
+        assertLinearContext(harness, chain, messages, 'id', 'parentId', chain.at(-1));
+        return;
+    }
+    for (const row of rows) {
+        if (row.isCompactSummary === true || row.subtype === 'compact_boundary' || row.type === 'compact_boundary')
+            unsupported(harness, 'compaction requires native context reconstruction');
+    }
+    const conversational = rows.filter(row => row.type === 'user' || row.type === 'assistant');
+    const standaloneSidechain = conversational.length > 0 && conversational.every(row => row.isSidechain === true);
+    const messages = conversational.filter(row => standaloneSidechain || row.isSidechain !== true);
+    // Progress and attachments can participate in parent chains without becoming
+    // conversation messages. They must remain available when walking the chain.
+    const chain = rows.filter(row => typeof row.uuid === 'string');
+    assertLinearContext(harness, chain, messages, 'uuid', 'parentUuid', messages.at(-1));
+}
+function assertLinearContext(harness, chain, messages, idKey, parentKey, leaf) {
+    // Legacy flat transcripts have no topology to contradict their file order.
+    if (!chain.some(row => Object.hasOwn(row, parentKey)))
+        return;
+    const byId = new Map();
+    const messageIds = new Set();
+    for (const row of messages) {
+        const id = row[idKey];
+        if (typeof id !== 'string')
+            unsupported(harness, 'conversation entries mix identified and unidentified history');
+        if (messageIds.has(id))
+            unsupported(harness, 'duplicate native conversation ids');
+        messageIds.add(id);
+    }
+    for (const row of chain)
+        byId.set(row[idKey], row);
+    const ancestors = new Set();
+    let current = leaf;
+    while (current) {
+        const id = current[idKey];
+        if (ancestors.has(id))
+            unsupported(harness, 'cyclic native parent chain');
+        ancestors.add(id);
+        const parent = current[parentKey];
+        if (parent === null || parent === undefined)
+            break;
+        if (typeof parent !== 'string' || !byId.has(parent))
+            unsupported(harness, 'missing native parent entry');
+        current = byId.get(parent);
+    }
+    if ([...messageIds].some(id => !ancestors.has(id)))
+        unsupported(harness, 'branched or disconnected native conversation');
+}

package/dist/readers/pi-compaction.d.ts

@@ -0,0 +1,7 @@
+import { type CanonicalResult } from '@letta-ai/trajectory';
+type Row = Record<string, unknown>;
+/** Narrow Pi 0.84.4 buildContextEntries contract; no runtime or extension execution. */
+export declare function piCompactedContext(raw: string): Row[] | undefined;
+/** Preserve archive identities; only summary messages are derived from native summary entries. */
+export declare function projectPiCompaction(raw: string, canonical: CanonicalResult): CanonicalResult;
+export {};

package/dist/readers/pi-compaction.js

@@ -0,0 +1,112 @@
+import { normalizeToCanonical } from '@letta-ai/trajectory';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+function fail(reason) { throw new Error(`Unsupported pi continuation history: ${reason} requires native context reconstruction.`); }
+/** Narrow Pi 0.84.4 buildContextEntries contract; no runtime or extension execution. */
+export function piCompactedContext(raw) {
+    const rows = raw.split('\n').filter(line => line.trim()).map(line => JSON.parse(line));
+    if (!rows.some(row => row.type === 'compaction'))
+        return undefined;
+    const header = rows[0];
+    if (!header || header.type !== 'session' || header.version !== 3 || typeof header.id !== 'string' || !header.id)
+        fail('compaction without an identified v3 session');
+    const entries = rows.slice(1);
+    const seen = new Set();
+    let parent = null;
+    for (const entry of entries) {
+        if (typeof entry.id !== 'string' || !entry.id || seen.has(entry.id))
+            fail('missing or duplicate native entry ids');
+        if (entry.parentId !== parent)
+            fail('branched, disconnected or reordered native entry chain');
+        seen.add(entry.id);
+        parent = entry.id;
+        switch (entry.type) {
+            case 'message': {
+                const message = entry.message;
+                if (!object(message) || !['user', 'assistant', 'toolResult'].includes(String(message.role)))
+                    fail('unsupported native message role');
+                if (message.role === 'toolResult' && (typeof message.toolCallId !== 'string' || !message.toolCallId
+                    || typeof message.toolName !== 'string' || !message.toolName))
+                    fail('unidentified native tool result');
+                const content = message.content;
+                if (typeof content === 'string' && message.role === 'user')
+                    break;
+                if (!Array.isArray(content))
+                    fail('unsupported native message content');
+                for (const block of content) {
+                    if (!object(block))
+                        fail('unsupported native content block');
+                    if (block.type === 'text' && typeof block.text === 'string')
+                        continue;
+                    if (message.role === 'assistant' && block.type === 'thinking' && typeof block.thinking === 'string')
+                        continue;
+                    if (message.role === 'assistant' && block.type === 'toolCall' && typeof block.id === 'string' && block.id
+                        && typeof block.name === 'string' && block.name && object(block.arguments))
+                        continue;
+                    fail('unsupported native content block');
+                }
+                break;
+            }
+            case 'compaction': {
+                if (typeof entry.summary !== 'string' || !entry.summary.trim() || typeof entry.timestamp !== 'string' || !Number.isFinite(Date.parse(entry.timestamp))
+                    || typeof entry.tokensBefore !== 'number' || !Number.isFinite(entry.tokensBefore) || entry.tokensBefore < 0 || entry.fromHook === true)
+                    fail('unsupported compaction summary');
+                if (typeof entry.firstKeptEntryId !== 'string' || !seen.has(entry.firstKeptEntryId) || entry.firstKeptEntryId === entry.id)
+                    fail('missing or non-ancestral compaction retention anchor');
+                break;
+            }
+            case 'model_change':
+            case 'thinking_level_change':
+            case 'session_info':
+            case 'label': break;
+            default: fail(`unsupported ${String(entry.type)} entry`);
+        }
+    }
+    let latest = entries.length - 1;
+    while (entries[latest]?.type !== 'compaction')
+        latest--;
+    const compaction = entries[latest];
+    const kept = entries.findIndex(entry => entry.id === compaction.firstKeptEntryId);
+    const selected = [compaction, ...entries.slice(kept, latest), ...entries.slice(latest + 1)];
+    const archive = normalizeToCanonical({ source: 'pi', transcript: raw,
+        bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null } },
+        filters: { systemMessages: 'include', toolResults: 'include' },
+    });
+    for (const entry of selected) {
+        if (entry.type !== 'message')
+            continue;
+        const message = entry.message;
+        if (message.role === 'assistant' && ['aborted', 'error'].includes(String(message.stopReason)))
+            continue;
+        if (!archive.records.some(record => record.source_identity_kind === 'native' && record.stable_source_record_id === entry.id))
+            fail('selected native message omitted by normalization');
+    }
+    return selected;
+}
+/** Preserve archive identities; only summary messages are derived from native summary entries. */
+export function projectPiCompaction(raw, canonical) {
+    let entries;
+    try {
+        entries = piCompactedContext(raw);
+    }
+    catch {
+        return canonical;
+    } // Unsupported archives remain capturable; exports run the strict guard.
+    if (!entries)
+        return canonical;
+    const group = canonical.records.find(record => record.record_type === 'meta')?.source_group_id ?? 'default';
+    const records = canonical.records.filter(record => record.record_type === 'meta');
+    const diagnostics = [...canonical.diagnostics];
+    for (const entry of entries) {
+        if (entry.type === 'message')
+            records.push(...canonical.records.filter(record => record.source_identity_kind === 'native' && record.stable_source_record_id === entry.id));
+        if (entry.type !== 'compaction')
+            continue;
+        const content = `The conversation history before this point was compacted into the following summary:\n\n<summary>\n${entry.summary}\n</summary>`;
+        const derived = normalizeToCanonical({ source: 'pi', transcript: JSON.stringify({ ...entry, type: 'message', message: { role: 'user', content, timestamp: Date.parse(entry.timestamp) } }),
+            sourceContext: { groupId: group, partial: true }, bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null } },
+            filters: { systemMessages: 'include', toolResults: 'include' }, });
+        records.push(...derived.records.filter(record => record.record_type === 'user'));
+        diagnostics.push({ code: 'noise_record_dropped', message: `[trajectories/pi-compaction-context-v1] Native Pi summary entry ${entry.id} supplies the derived user context; retained messages follow native order. Complete original history remains in snapshot.raw.` });
+    }
+    return { ...canonical, records, diagnostics };
+}

package/dist/readers/pi-context.d.ts

@@ -0,0 +1,13 @@
+import { type CanonicalResult } from '@letta-ai/trajectory';
+/**
+ * Pi excludes aborted/error assistant drafts when building provider messages.
+ * Apply that narrow projection after the verified Pi compaction view, retaining raw
+ * bytes elsewhere and preserving every surviving canonical identity. OMP has
+ * different semantics and must not use this projection.
+ *
+ * Verified source and pinned identity contract: docs/pi-provider-context.md.
+ */
+export declare function projectPiProviderContext(raw: string, canonical: CanonicalResult): CanonicalResult;
+/** Full archive normalization; continuation applies the separate failed-draft filter. */
+export declare function normalizePiArchive(raw: string): CanonicalResult;
+export declare function projectPiDrafts(raw: string, canonical: CanonicalResult): CanonicalResult;

package/dist/readers/pi-context.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { normalizeToCanonical } from '@letta-ai/trajectory';
+import { projectPiCompaction } from './pi-compaction.js';
+const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+/**
+ * Pi excludes aborted/error assistant drafts when building provider messages.
+ * Apply that narrow projection after the verified Pi compaction view, retaining raw
+ * bytes elsewhere and preserving every surviving canonical identity. OMP has
+ * different semantics and must not use this projection.
+ *
+ * Verified source and pinned identity contract: docs/pi-provider-context.md.
+ */
+export function projectPiProviderContext(raw, canonical) {
+    return projectPiDrafts(raw, projectPiCompaction(raw, canonical));
+}
+/** Full archive normalization; continuation applies the separate failed-draft filter. */
+export function normalizePiArchive(raw) {
+    return normalizeToCanonical({ source: 'pi', transcript: raw,
+        bounds: { toolArguments: { maxCharacters: null }, toolResults: { maxCharacters: null } },
+        filters: { systemMessages: 'include', toolResults: 'include' },
+    });
+}
+export function projectPiDrafts(raw, canonical) {
+    const group = canonical.records.find(record => record.record_type === 'meta')?.source_group_id ?? 'default';
+    const omitted = new Set();
+    const diagnostics = [];
+    let byteOffset = 0;
+    for (const [index, line] of raw.split('\n').entries()) {
+        const offset = byteOffset;
+        byteOffset += Buffer.byteLength(line, 'utf8') + 1;
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue;
+        } // The caller retains and rejects malformed-input diagnostics.
+        if (!row || typeof row !== 'object' || Array.isArray(row))
+            continue;
+        const entry = row;
+        if (entry.type !== 'message' || entry.message?.role !== 'assistant'
+            || (entry.message.stopReason !== 'aborted' && entry.message.stopReason !== 'error'))
+            continue;
+        const nativeId = typeof entry.id === 'string' && entry.id ? entry.id : undefined;
+        const identity = nativeId === undefined ? `location\0${sha256(`${group}|byte|${offset}`)}` : `native\0${nativeId}`;
+        omitted.add(identity);
+        diagnostics.push({
+            code: 'noise_record_dropped',
+            inputLine: index + 1,
+            message: `[trajectories/pi-provider-context-v1] Pi omits assistant entry ${nativeId ?? `at byte ${offset}`} with stopReason=${entry.message.stopReason} from provider context; complete native bytes remain in snapshot.raw.`,
+        });
+    }
+    if (!omitted.size)
+        return canonical;
+    return {
+        ...canonical,
+        // Keep tool results, even when their corresponding draft was omitted. The
+        // normal native-writer orphan guard must reject that ambiguous history.
+        records: canonical.records.filter(record => !omitted.has(`${record.source_identity_kind}\0${record.stable_source_record_id}`)),
+        diagnostics: [...canonical.diagnostics, ...diagnostics],
+    };
+}

package/dist/store.d.ts

@@ -0,0 +1,25 @@
+import type { Harness, Snapshot, ManagedSession, WriteOptions, NativeExport } from './types.js';
+/** Validate portable prefix continuity, optionally requiring new conversation records. */
+export declare function assertSnapshotContinuation(baseline: Snapshot, observed: Snapshot, options?: {
+    requireProgress?: boolean;
+    allowInitialSystem?: boolean;
+}): void;
+export declare function getSnapshot(root: string, id: string): Promise<Snapshot>;
+export declare function getSession(root: string, id: string): Promise<ManagedSession>;
+export declare function listSessions(root: string): Promise<ManagedSession[]>;
+export declare function createSession(root: string, snapshot: Snapshot, options: {
+    workspace: string;
+    id?: string;
+}): Promise<ManagedSession>;
+/** Import observed native history. An exact replay of the latest append is idempotent. */
+export declare function appendSnapshot(root: string, id: string, snapshot: Snapshot, options: {
+    expectedHead: string;
+}): Promise<ManagedSession>;
+/** Prepare a new native continuation; execution and native shutdown belong to the caller. */
+export declare function switchSession(root: string, id: string, target: Harness, options: Omit<WriteOptions, 'cwd'> & {
+    cwd?: string;
+    expectedHead: string;
+}): Promise<{
+    session: ManagedSession;
+    native: NativeExport;
+}>;

package/dist/store.js

@@ -0,0 +1,218 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile, rename, link, rm, readdir, realpath } from 'node:fs/promises';
+import { join, resolve, isAbsolute } from 'node:path';
+import { assertSnapshot, assertPortableSnapshot, writeSnapshot, readSnapshot } from './convert.js';
+import { piCompactedContext } from './readers/pi-compaction.js';
+import { normalizePiArchive, projectPiDrafts } from './readers/pi-context.js';
+import { portableConversationTokens } from './portable.js';
+/** Compare the portable conversation, not timestamps, provider metadata, or native ids of messages. */
+function conversation(snapshot) {
+    return portableConversationTokens(snapshot.canonical.records.map(record => JSON.parse(record.record_json)))
+        .map(token => token.semantic);
+}
+/** Validate portable prefix continuity, optionally requiring new conversation records. */
+export function assertSnapshotContinuation(baseline, observed, options = {}) {
+    assertSnapshot(baseline);
+    assertPortableSnapshot(observed);
+    let before = conversation(baseline), after = conversation(observed);
+    if (baseline.source.harness === 'pi' && observed.source.harness === 'pi'
+        && baseline.source.nativeSessionId && baseline.source.nativeSessionId === observed.source.nativeSessionId && piCompactedContext(observed.raw)) {
+        if (!observed.raw.startsWith(baseline.raw) || (observed.raw.length > baseline.raw.length && !baseline.raw.endsWith('\n'))) {
+            throw new Error('Compacted Pi continuation must preserve its exact append-only native archive. The session head was not changed.');
+        }
+        before = conversation({ ...baseline, canonical: projectPiDrafts(baseline.raw, normalizePiArchive(baseline.raw)) });
+        after = conversation({ ...observed, canonical: projectPiDrafts(observed.raw, normalizePiArchive(observed.raw)) });
+    }
+    // A fresh target may initialize its own system instructions before the imported
+    // conversation. Preserve them in the snapshot; subsequent same-session appends
+    // must retain them exactly. Never allow replacement of existing instructions.
+    if (options.allowInitialSystem && before.length && JSON.parse(before[0])[0] !== 'system') {
+        if (after.length && JSON.parse(after[0])[0] === 'system')
+            after.shift();
+    }
+    if (!before.length || after.length < before.length || before.some((record, index) => record !== after[index])) {
+        throw new Error('Observed native history does not preserve the complete prepared conversation prefix. The session head was not changed.');
+    }
+    if (options.requireProgress && after.length === before.length) {
+        throw new Error('Observed native history contains no new conversation records after its prepared baseline.');
+    }
+}
+function safeId(value) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(value))
+        throw new Error('Invalid session or snapshot id.');
+    return value;
+}
+function sessionPath(root, id) { return join(resolve(root), 'sessions', `${safeId(id)}.json`); }
+function snapshotPath(root, id) { return join(resolve(root), 'snapshots', `${safeId(id)}.json`); }
+async function initialize(root) {
+    try {
+        const format = JSON.parse(await readFile(join(resolve(root), 'format.json'), 'utf8'));
+        if (format.version === 2)
+            throw new Error('Version-1 writers cannot write a canonical-log store.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    await mkdir(resolve(root), { recursive: true, mode: 0o700 });
+    for (const kind of ['sessions', 'snapshots', 'locks'])
+        await mkdir(join(root, kind), { recursive: true, mode: 0o700 });
+}
+async function withLock(root, id, operation) {
+    await initialize(root);
+    const lock = join(root, 'locks', safeId(id));
+    try {
+        await mkdir(lock, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`Session ${id} is locked by another operation. Inspect abandoned locks before removing them.`);
+        throw error;
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        await rm(lock, { recursive: true });
+    }
+}
+async function persistSnapshot(root, snapshot) {
+    assertSnapshot(snapshot);
+    const destination = snapshotPath(root, snapshot.id);
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(snapshot, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        // Publish a complete file atomically without replacing another writer's
+        // immutable snapshot. A killed writer can leave a .tmp, never a partial id.
+        try {
+            await link(temporary, destination);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const existing = await getSnapshot(root, snapshot.id);
+            if (existing.raw !== snapshot.raw || JSON.stringify(existing.canonical) !== JSON.stringify(snapshot.canonical))
+                throw new Error('Conflicting immutable snapshot.');
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function persistSession(root, session) {
+    const destination = sessionPath(root, session.id);
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(session, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function getSnapshot(root, id) {
+    const snapshot = JSON.parse(await readFile(snapshotPath(root, id), 'utf8'));
+    assertSnapshot(snapshot);
+    if (snapshot.id !== id)
+        throw new Error('Snapshot filename does not match its identity.');
+    return snapshot;
+}
+export async function getSession(root, id) {
+    const session = JSON.parse(await readFile(sessionPath(root, id), 'utf8'));
+    if (session.version !== 1 || session.id !== id || !Array.isArray(session.snapshots) || !session.snapshots.includes(session.head) || !Array.isArray(session.bindings))
+        throw new Error('Invalid managed session.');
+    safeId(session.head);
+    return session;
+}
+export async function listSessions(root) {
+    let files;
+    try {
+        files = await readdir(join(resolve(root), 'sessions'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const sessions = await Promise.all(files.filter(file => file.endsWith('.json')).map(file => getSession(root, file.slice(0, -5))));
+    return sessions.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+}
+export async function createSession(root, snapshot, options) {
+    if (!isAbsolute(options.workspace))
+        throw new Error('workspace must be an absolute path.');
+    const workspace = await realpath(options.workspace);
+    const id = safeId(options.id ?? randomUUID());
+    return withLock(root, id, async () => {
+        try {
+            await readFile(sessionPath(root, id));
+            throw new Error(`Session ${id} already exists.`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await persistSnapshot(root, snapshot);
+        const now = new Date().toISOString();
+        const session = { version: 1, id, createdAt: now, updatedAt: now, workspace, head: snapshot.id, snapshots: [snapshot.id], bindings: [] };
+        await persistSession(root, session);
+        return session;
+    });
+}
+/** Import observed native history. An exact replay of the latest append is idempotent. */
+export async function appendSnapshot(root, id, snapshot, options) {
+    return withLock(root, id, async () => {
+        const session = await getSession(root, id);
+        assertSnapshot(snapshot);
+        if (session.head === snapshot.id && (options.expectedHead === session.head || session.snapshots.at(-2) === options.expectedHead)) {
+            // The commit may have succeeded before a workflow step's acknowledgement
+            // was saved. Prove this exact transition; never accept an unrelated or
+            // older expected head just because the requested snapshot already exists.
+            await getSnapshot(root, snapshot.id);
+            return session;
+        }
+        if (session.head !== options.expectedHead)
+            throw new Error('Session head changed; read the latest session before importing.');
+        if (session.snapshots.includes(snapshot.id))
+            throw new Error('Cannot replace the head with an older snapshot. Create a separate session to branch.');
+        const current = await getSnapshot(root, session.head);
+        const nativeId = snapshot.source.nativeSessionId;
+        if (!nativeId)
+            throw new Error('A continuation requires an identified native session.');
+        let baseline;
+        let preparedTarget = false;
+        if (current.source.harness === snapshot.source.harness && current.source.nativeSessionId === nativeId)
+            baseline = current;
+        else {
+            const binding = session.bindings.find(item => item.snapshotId === session.head && item.harness === snapshot.source.harness && item.nativeSessionId === nativeId);
+            if (!binding)
+                throw new Error('Native session is not a prepared continuation of the current head.');
+            baseline = await getSnapshot(root, binding.exportedSnapshotId);
+            preparedTarget = true;
+        }
+        assertSnapshotContinuation(baseline, snapshot, { allowInitialSystem: preparedTarget });
+        await persistSnapshot(root, snapshot);
+        session.snapshots.push(snapshot.id);
+        session.head = snapshot.id;
+        session.updatedAt = new Date().toISOString();
+        await persistSession(root, session);
+        return session;
+    });
+}
+/** Prepare a new native continuation; execution and native shutdown belong to the caller. */
+export async function switchSession(root, id, target, options) {
+    return withLock(root, id, async () => {
+        const session = await getSession(root, id);
+        if (session.head !== options.expectedHead)
+            throw new Error('Session head changed; refusing to export stale history.');
+        const snapshot = await getSnapshot(root, session.head);
+        const native = await writeSnapshot(snapshot, target, { ...options, cwd: options.cwd ?? session.workspace });
+        const exported = await readSnapshot({ harness: target, path: join(options.directory, native.entrypoint), nativeSessionId: native.sessionId });
+        if (exported.source.nativeSessionId !== native.sessionId || !conversation(exported).length)
+            throw new Error('Native export did not establish an identified conversation.');
+        await persistSnapshot(root, exported);
+        session.bindings.push({ harness: target, nativeSessionId: native.sessionId, snapshotId: snapshot.id, exportedSnapshotId: exported.id, directory: resolve(options.directory), entrypoint: native.entrypoint, createdAt: new Date().toISOString() });
+        session.updatedAt = new Date().toISOString();
+        await persistSession(root, session);
+        return { session, native };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+import type { CanonicalResult, NormalizedRecord } from '@letta-ai/trajectory';
+export declare const HARNESSES: readonly ["claude-code", "codex", "pi", "omp", "opencode", "grok-build", "cursor", "deepagents", "github-copilot", "cline", "fx"];
+export type Harness = typeof HARNESSES[number];
+/** Immutable history. Text-file inputs retain decoded source text;
+ * Cursor retains SQLite rows/blobs;
+ * Deep Agents retains decoded messages and metadata from one selected checkpoint. */
+export interface Snapshot {
+    version: 1;
+    id: string;
+    createdAt: string;
+    source: {
+        harness: Harness;
+        nativeSessionId?: string;
+        path?: string;
+        sha256: string;
+    };
+    cwd?: string;
+    raw: string;
+    /** Native metadata sidecars needed to interpret otherwise headerless histories. */
+    attachments?: Array<{
+        name: string;
+        content: string;
+        sha256: string;
+    }>;
+    canonical: CanonicalResult;
+    /** Archived histories can be inspected even when active-context conversion is unsupported. */
+    portabilityIssues?: ConversionDiagnostic[];
+}
+export interface ConversionDiagnostic {
+    code: string;
+    message: string;
+}
+/** Explicit destination; converters never overwrite a runtime's existing store. */
+export interface WriteOptions {
+    directory: string;
+    cwd: string;
+    sessionId?: string;
+    model?: string;
+    provider?: string;
+    timestamp?: string;
+}
+export interface NativeExport {
+    harness: Harness;
+    sessionId: string;
+    /** Paths are relative to WriteOptions.directory. */
+    files: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** Relative path of the native import/resume artifact. */
+    entrypoint: string;
+    /** Argument vector, never a shell command. Does not launch automatically. */
+    resume: {
+        command: string;
+        args: string[];
+        cwd: string;
+    };
+    /** Explicit native import steps, when a harness owns a database rather than a file store. */
+    prepare?: Array<{
+        command: string;
+        args: string[];
+        cwd: string;
+    }>;
+    diagnostics: ConversionDiagnostic[];
+}
+export interface NativeEntropy {
+    uuid(): string;
+    bytes(length: number): Uint8Array;
+}
+export type NativeWriter = (records: readonly NormalizedRecord[], options: WriteOptions, entropy?: NativeEntropy) => NativeExport;
+export interface SessionBinding {
+    harness: Harness;
+    nativeSessionId: string;
+    snapshotId: string;
+    /** What the target format actually carries, before that runtime continues it. */
+    exportedSnapshotId: string;
+    directory: string;
+    entrypoint: string;
+    createdAt: string;
+}
+/** One central conversation can have successive native runtime sessions. */
+export interface ManagedSession {
+    version: 1;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    workspace: string;
+    head: string;
+    snapshots: string[];
+    bindings: SessionBinding[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export const HARNESSES = ['claude-code', 'codex', 'pi', 'omp', 'opencode', 'grok-build', 'cursor', 'deepagents', 'github-copilot', 'cline', 'fx'];