trajectories 0.0.0 → 0.1.1

package/dist/log-baseline.d.ts

@@ -0,0 +1,26 @@
+import type { Snapshot } from './types.js';
+import type { BindingId, CaptureId, NativeBinding, RecordId } from './log-types.js';
+import { type Unit } from './log-records.js';
+import type { Frame, StageData } from './log-state.js';
+import type { NormalizedRecord } from '@letta-ai/trajectory';
+export declare function mapPreparedRecords(source: readonly {
+    id: RecordId;
+    record: {
+        payload: NormalizedRecord;
+    };
+}[], target: readonly Unit[]): RecordId[];
+export declare function captureMapping(store: string, frames: Frame[], stage: StageData, visited?: Set<CaptureId>): Promise<RecordId[]>;
+export interface Baseline {
+    snapshot: Snapshot;
+    before: Unit[];
+    ids: RecordId[];
+    activeIds: RecordId[];
+    binding: NativeBinding;
+    mapping: {
+        capture?: CaptureId;
+        binding?: BindingId;
+    };
+    derivedBinding?: BindingId;
+    firstTarget: boolean;
+}
+export declare function captureBaseline(store: string, frames: Frame[], observed: Snapshot, requestedBinding?: BindingId): Promise<Baseline>;

package/dist/log-baseline.js

@@ -0,0 +1,104 @@
+import { TrajectoriesError } from './log-types.js';
+import { atHead, selection } from './log-read.js';
+import { loadRecord, units } from './log-records.js';
+import { bindingSnapshot, loadStage, recoverSnapshot } from './log-recovery.js';
+import { portableConversationTokens } from './portable.js';
+const semantic = (record) => portableConversationTokens([record])[0]?.semantic;
+const isTool = (record) => record.role === 'tool' || (record.role === 'assistant' && 'tool_calls' in record);
+const omittedRole = (record) => ['system', 'reasoning', 'observation'].includes(record.role);
+// Native codecs can serialize a completed batch in call order and omit a tool's
+// success flag. Its call identity, arguments and complete result must survive.
+const bindingSemantic = (record) => record.role === 'tool'
+    ? JSON.stringify(['tool', record.tool_call_id, record.content]) : semantic(record);
+export function mapPreparedRecords(source, target) {
+    const ids = [];
+    let index = 0, next = 0;
+    const fail = () => { throw new TrajectoriesError('UNSUPPORTED_CONTEXT', 'Prepared baseline does not preserve its canonical conversation.'); };
+    while (next < target.length) {
+        const wanted = target[next];
+        while (index < source.length && omittedRole(source[index].record.payload)
+            && semantic(source[index].record.payload) !== wanted.semantic)
+            index++;
+        if (index >= source.length)
+            fail();
+        if (isTool(wanted.payload)) {
+            const batch = [];
+            while (index < source.length && (isTool(source[index].record.payload) || omittedRole(source[index].record.payload))) {
+                const item = source[index++];
+                if (isTool(item.record.payload))
+                    batch.push({ id: item.id, key: bindingSemantic(item.record.payload) });
+            }
+            if (!batch.length)
+                fail();
+            while (next < target.length && isTool(target[next].payload)) {
+                const key = bindingSemantic(target[next++].payload), match = batch.findIndex(item => item.key === key);
+                if (match < 0)
+                    fail();
+                ids.push(batch.splice(match, 1)[0].id);
+            }
+            if (batch.length)
+                fail();
+        }
+        else {
+            if (semantic(source[index].record.payload) !== wanted.semantic)
+                fail();
+            ids.push(source[index++].id);
+            next++;
+        }
+    }
+    if (source.slice(index).some(item => !omittedRole(item.record.payload)))
+        fail();
+    return ids;
+}
+async function bindingMapping(store, frames, id) {
+    const frame = frames.find(frame => frame.body.kind === 'binding' && frame.body.binding.id === id);
+    if (!frame?.body.parent)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Prepared binding baseline is missing.');
+    const snapshot = await bindingSnapshot(store, frames, id);
+    const selected = selection(atHead(frames, frame.body.parent)), byId = new Map(selected.history.map(record => [record.id, record]));
+    const portable = await Promise.all(selected.context.map(async (id) => ({ id, record: await loadRecord(store, byId.get(id)) })));
+    const ids = mapPreparedRecords(portable, units(snapshot, true));
+    return { snapshot, ids };
+}
+export async function captureMapping(store, frames, stage, visited = new Set()) {
+    if (visited.has(stage.ref.id))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Native baseline reference cycle.');
+    visited.add(stage.ref.id);
+    let prefix = [];
+    if (stage.mapping.capture) {
+        const ref = frames.find(frame => frame.body.capture?.id === stage.mapping.capture)?.body.capture;
+        if (!ref)
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Accepted native baseline capture is missing.');
+        prefix = await captureMapping(store, frames, await loadStage(store, ref), visited);
+    }
+    else if (stage.mapping.binding)
+        prefix = (await bindingMapping(store, frames, stage.mapping.binding)).ids;
+    return [...(stage.mapping.leading ? [stage.mapping.leading] : []), ...prefix, ...stage.mapping.added];
+}
+export async function captureBaseline(store, frames, observed, requestedBinding) {
+    const current = frames.at(-1);
+    const latest = [...frames].reverse().find(frame => frame.body.capture);
+    if (!latest?.body.capture)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Current accepted native source is missing.');
+    const selected = selection(frames);
+    if (!requestedBinding || requestedBinding === latest.body.binding.id) {
+        if (requestedBinding && current.body.binding.id !== requestedBinding)
+            throw new TrajectoriesError('STALE_HEAD', 'Requested binding is not current at this head.');
+        const stage = await loadStage(store, latest.body.capture);
+        if (stage.ref.source.harness !== observed.source.harness || !observed.source.nativeSessionId
+            || stage.ref.source.nativeSessionId !== observed.source.nativeSessionId)
+            throw new TrajectoriesError('INVALID_INPUT', 'Another native lineage must name its committed prepared binding.');
+        const snapshot = await recoverSnapshot(store, stage, frames);
+        return { snapshot, before: units(snapshot, true), ids: await captureMapping(store, frames, stage), activeIds: selected.context,
+            binding: stage.binding, mapping: { capture: stage.ref.id }, firstTarget: false,
+            ...(stage.evidence.derivedBinding ? { derivedBinding: stage.evidence.derivedBinding } : {}) };
+    }
+    if (current.body.binding.id !== requestedBinding || current.body.binding.harness !== observed.source.harness
+        || current.body.binding.nativeSessionId !== observed.source.nativeSessionId)
+        throw new TrajectoriesError('STALE_HEAD', 'Target capture does not belong to the exact committed binding.');
+    const prepared = await bindingMapping(store, frames, requestedBinding);
+    const bindingFrame = frames.find(frame => frame.body.kind === 'binding' && frame.body.binding.id === requestedBinding);
+    return { snapshot: prepared.snapshot, before: units(prepared.snapshot, true), ids: prepared.ids, activeIds: prepared.ids,
+        binding: current.body.binding, mapping: { binding: requestedBinding },
+        ...(!bindingFrame.body.legacyBaseline ? { derivedBinding: requestedBinding } : {}), firstTarget: true };
+}

package/dist/log-content.d.ts

@@ -0,0 +1,16 @@
+interface Part {
+    id: string;
+    bytes: number;
+    tree?: true;
+}
+export interface TextRef {
+    root: Part;
+    sha256: string;
+    bytes: number;
+}
+/** Content-defined boundaries keep unchanged ranges shared after native JSON rewrites. */
+export declare function textChunks(text: string): Buffer[];
+export declare function derivedChunks(texts: readonly string[]): Map<string, Buffer>;
+export declare function putText(store: string, text: string, derived?: ReadonlyMap<string, Buffer>): Promise<TextRef>;
+export declare function getText(store: string, ref: TextRef, derived?: ReadonlyMap<string, Buffer>): Promise<string>;
+export {};

package/dist/log-content.js

@@ -0,0 +1,80 @@
+import { digest, getObject, putObject, stableJson } from './log-io.js';
+import { TrajectoriesError } from './log-types.js';
+/** Content-defined boundaries keep unchanged ranges shared after native JSON rewrites. */
+export function textChunks(text) {
+    const bytes = Buffer.from(text), chunks = [];
+    let start = 0, rolling = 0;
+    for (let i = 0; i < bytes.length; i++) {
+        rolling = ((rolling << 1) + Math.imul(bytes[i] + 1, 0x9e3779b1)) >>> 0;
+        const length = i + 1 - start;
+        if (length >= 16384 || (length >= 2048 && (rolling & 4095) === 0)) {
+            chunks.push(bytes.subarray(start, i + 1));
+            start = i + 1;
+            rolling = 0;
+        }
+    }
+    if (start < bytes.length || !chunks.length)
+        chunks.push(bytes.subarray(start));
+    return chunks;
+}
+export function derivedChunks(texts) {
+    const result = new Map();
+    for (const text of texts)
+        for (const bytes of textChunks(text))
+            result.set(digest(bytes), bytes);
+    return result;
+}
+export async function putText(store, text, derived) {
+    let parts = [];
+    for (const bytes of textChunks(text)) {
+        const id = digest(bytes);
+        if (!derived?.has(id))
+            await putObject(store, bytes);
+        parts.push({ id, bytes: bytes.length });
+    }
+    while (parts.length > 1) {
+        const next = [];
+        for (let i = 0; i < parts.length; i += 32) {
+            const group = parts.slice(i, i + 32);
+            next.push({ id: await putObject(store, stableJson(group)), bytes: group.reduce((sum, p) => sum + p.bytes, 0), tree: true });
+        }
+        parts = next;
+    }
+    return { root: parts[0], sha256: digest(text), bytes: Buffer.byteLength(text) };
+}
+export async function getText(store, ref, derived) {
+    if (!ref || !Number.isSafeInteger(ref.bytes) || ref.bytes < 0)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid text reference.');
+    const chunks = [], ancestors = new Set();
+    async function visit(part) {
+        if (!part || !Number.isSafeInteger(part.bytes) || part.bytes < 0 || ancestors.has(part.id))
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid content tree.');
+        const bytes = await getObject(store, part.id, derived);
+        if (part.tree) {
+            ancestors.add(part.id);
+            let children;
+            try {
+                children = JSON.parse(bytes.toString());
+            }
+            catch (cause) {
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid content-tree node.', { cause });
+            }
+            if (!Array.isArray(children) || !children.length || children.length > 32
+                || children.reduce((sum, child) => sum + child.bytes, 0) !== part.bytes)
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid content-tree size.');
+            for (const child of children)
+                await visit(child);
+            ancestors.delete(part.id);
+        }
+        else {
+            if (bytes.length !== part.bytes)
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid content size.');
+            chunks.push(bytes);
+        }
+    }
+    await visit(ref.root);
+    const bytes = Buffer.concat(chunks), text = bytes.toString('utf8');
+    if (bytes.length !== ref.bytes || digest(bytes) !== ref.sha256 || !Buffer.from(text).equals(bytes))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Text integrity mismatch.');
+    return text;
+}

package/dist/log-io.d.ts

@@ -0,0 +1,10 @@
+export declare function stableJson(value: unknown): string;
+export declare const digest: (content: string | Uint8Array) => string;
+export declare function safeId(value: string): string;
+export declare function objectPath(store: string, id: string): string;
+export declare function syncDirectory(path: string): Promise<void>;
+export declare function ensureDirectory(path: string): Promise<void>;
+export declare function atomicWrite(path: string, content: string | Uint8Array, immutable?: boolean): Promise<void>;
+export declare function putObject(store: string, content: string | Uint8Array): Promise<string>;
+export declare function getObject(store: string, id: string, derived?: ReadonlyMap<string, Buffer>): Promise<Buffer>;
+export declare function withSessionLock<T>(store: string, id: string, action: () => Promise<T>): Promise<T>;

package/dist/log-io.js

@@ -0,0 +1,121 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+export function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(item => item === undefined ? 'null' : stableJson(item)).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.keys(value).sort()
+            .filter(key => value[key] !== undefined)
+            .map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+    const result = JSON.stringify(value);
+    if (result === undefined)
+        throw new TrajectoriesError('INVALID_INPUT', 'Input must be JSON serializable.');
+    return result;
+}
+export const digest = (content) => createHash('sha256').update(content).digest('hex');
+export function safeId(value) {
+    if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(value))
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid session or intent identifier.');
+    return value;
+}
+export function objectPath(store, id) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid content reference.');
+    return join(resolve(store), 'objects', id.slice(0, 2), id);
+}
+export async function syncDirectory(path) {
+    const file = await open(path, 'r');
+    try {
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function ensureDirectory(path) {
+    try {
+        await mkdir(path, { mode: 0o700 });
+        await syncDirectory(dirname(path));
+    }
+    catch (cause) {
+        if (cause.code === 'EEXIST')
+            return;
+        if (cause.code !== 'ENOENT')
+            throw cause;
+        await ensureDirectory(dirname(path));
+        await ensureDirectory(path);
+    }
+}
+export async function atomicWrite(path, content, immutable = false) {
+    await ensureDirectory(dirname(path));
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(content);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    try {
+        if (immutable)
+            await link(temporary, path);
+        else
+            await rename(temporary, path);
+        await syncDirectory(dirname(path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export async function putObject(store, content) {
+    const id = digest(content), path = objectPath(store, id);
+    try {
+        await atomicWrite(path, content, true);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const existing = await getObject(store, id);
+    if (digest(existing) !== id)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Stored content is corrupt.');
+    return id;
+}
+export async function getObject(store, id, derived) {
+    let bytes;
+    try {
+        bytes = await readFile(objectPath(store, id));
+    }
+    catch (error) {
+        const fallback = derived?.get(id);
+        if (error.code !== 'ENOENT' || !fallback)
+            throw new TrajectoriesError('INTEGRITY_ERROR', `Missing retained content ${id}.`, { cause: error });
+        bytes = fallback;
+    }
+    if (digest(bytes) !== id)
+        throw new TrajectoriesError('INTEGRITY_ERROR', `Content hash mismatch ${id}.`);
+    return bytes;
+}
+export async function withSessionLock(store, id, action) {
+    const locks = join(resolve(store), 'locks');
+    await ensureDirectory(locks);
+    const path = join(locks, safeId(id));
+    try {
+        await mkdir(path, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new TrajectoriesError('OPERATION_PENDING', 'A writer holds this session; reconcile interrupted writers before retrying.');
+        throw error;
+    }
+    try {
+        return await action();
+    }
+    finally {
+        await rm(path, { recursive: true });
+        await syncDirectory(locks);
+    }
+}

package/dist/log-read.d.ts

@@ -0,0 +1,24 @@
+import type { CommitReceipt, ConversationRecord, Head, HeadMetadata, ManagedSession, NativeBinding, Page, PageCursor, ReadOptions, RecordId } from './log-types.js';
+import { type Frame, type StoredRecord } from './log-state.js';
+import { type CanonicalConversationRecord } from './log-records.js';
+export declare function sessionOf(frame: Frame): ManagedSession;
+export declare function receiptOf(store: string, frame: Frame): Promise<CommitReceipt>;
+export declare function atHead(frames: Frame[], head: Head): Frame[];
+export declare function selection(frames: Frame[]): {
+    context: RecordId[];
+    history: StoredRecord[];
+};
+export declare function getSession(store: string, id: string): Promise<ManagedSession>;
+export declare function getHeadMetadata(store: string, id: string, options: {
+    atHead: Head;
+}): Promise<HeadMetadata>;
+export declare function getNativeBinding(store: string, id: string, options: {
+    atHead: Head;
+    bindingId?: NativeBinding['id'];
+}): Promise<NativeBinding>;
+export declare function readCanonicalSession(store: string, id: string, options: ReadOptions): Promise<Page<CanonicalConversationRecord>>;
+export declare function readSession(store: string, id: string, options: ReadOptions): Promise<Page<ConversationRecord>>;
+export declare function listSessions(store: string, options?: {
+    cursor?: PageCursor;
+    limit?: number;
+}): Promise<Page<ManagedSession>>;

package/dist/log-read.js

@@ -0,0 +1,117 @@
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { digest, stableJson } from './log-io.js';
+import { getText } from './log-content.js';
+import { assertLogStore, readFrames } from './log-state.js';
+import { applyEdit, loadRecord } from './log-records.js';
+export function sessionOf(frame) {
+    return { version: 2, ...frame.body.session, head: frame.head, updatedAt: frame.body.time };
+}
+export async function receiptOf(store, frame) {
+    return { intentId: frame.body.intentId, session: sessionOf(frame), parent: frame.body.parent,
+        diagnostics: JSON.parse(await getText(store, frame.body.diagnostics)),
+        ...(frame.body.capture ? { capture: frame.body.capture } : {}) };
+}
+export function atHead(frames, head) {
+    const index = frames.findIndex(frame => frame.head === head);
+    if (index < 0)
+        throw new TrajectoriesError('NOT_FOUND', 'Unknown committed head.');
+    return frames.slice(0, index + 1);
+}
+export function selection(frames) {
+    let context = [];
+    const history = [], known = new Set();
+    for (const frame of frames) {
+        for (const record of frame.body.records) {
+            if (known.has(record.id))
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Duplicate central record identity.');
+            known.add(record.id);
+            history.push(record);
+        }
+        context = applyEdit(context, frame.body.edit);
+        if (context.some(id => !known.has(id)))
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Context references an uncommitted record.');
+    }
+    return { context, history };
+}
+function pageLimit(value = 100) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 1000)
+        throw new TrajectoriesError('INVALID_INPUT', 'Page limit must be between 1 and 1000.');
+    return value;
+}
+function encode(value) { const body = stableJson(value); return Buffer.from(body).toString('base64url') + '.' + digest(body); }
+function decode(cursor) {
+    try {
+        const [encoded, hash, extra] = cursor.split('.'), text = Buffer.from(encoded, 'base64url').toString();
+        if (extra || digest(text) !== hash)
+            throw new Error('hash');
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid page cursor.', { cause });
+    }
+}
+export async function getSession(store, id) {
+    const frame = (await readFrames(store, id)).at(-1);
+    if (!frame)
+        throw new TrajectoriesError('NOT_FOUND', 'Managed session does not exist.');
+    return sessionOf(frame);
+}
+export async function getHeadMetadata(store, id, options) {
+    const frame = atHead(await readFrames(store, id), options.atHead).at(-1);
+    return { head: frame.head, parent: frame.body.parent, kind: frame.body.kind, progress: frame.body.progress,
+        diagnostics: (await receiptOf(store, frame)).diagnostics, binding: frame.body.binding,
+        ...(frame.body.capture ? { capture: frame.body.capture } : {}),
+        ...(frame.body.nativeMeta ? { nativeMeta: frame.body.nativeMeta } : {}) };
+}
+export async function getNativeBinding(store, id, options) {
+    const frames = atHead(await readFrames(store, id), options.atHead), binding = frames.at(-1).body.binding;
+    if (options.bindingId && binding.id !== options.bindingId)
+        throw new TrajectoriesError('STALE_HEAD', 'Binding is not active at the pinned head.');
+    return binding;
+}
+export async function readCanonicalSession(store, id, options) {
+    const limit = pageLimit(options.limit);
+    if (options.view !== 'history' && options.view !== 'context')
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid conversation view.');
+    const selected = selection(atHead(await readFrames(store, id), options.atHead));
+    const byId = new Map(selected.history.map(record => [record.id, record]));
+    const records = options.view === 'history' ? selected.history : selected.context.map(id => byId.get(id));
+    let offset = 0;
+    if (options.cursor) {
+        const cursor = decode(options.cursor);
+        if (cursor.id !== id || cursor.head !== options.atHead || cursor.view !== options.view || !Number.isSafeInteger(cursor.offset)
+            || cursor.offset < 1 || cursor.offset >= records.length)
+            throw new TrajectoriesError('INVALID_INPUT', 'Cursor does not belong to this session, head and view.');
+        offset = cursor.offset;
+    }
+    const items = await Promise.all(records.slice(offset, offset + limit).map(record => loadRecord(store, record)));
+    return { items, nextCursor: offset + limit < records.length ? encode({ id, head: options.atHead, view: options.view, offset: offset + limit }) : null };
+}
+export async function readSession(store, id, options) {
+    const page = await readCanonicalSession(store, id, options);
+    return { ...page, items: page.items.map(({ canonical: _, ...record }) => record) };
+}
+export async function listSessions(store, options = {}) {
+    await assertLogStore(store);
+    const limit = pageLimit(options.limit);
+    let names;
+    try {
+        names = (await readdir(join(resolve(store), 'logs'))).filter(name => name.endsWith('.jsonl')).map(name => name.slice(0, -6)).sort();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        names = [];
+    }
+    let offset = 0;
+    if (options.cursor) {
+        const c = decode(options.cursor), index = names.indexOf(c.after);
+        if (c.view !== 'sessions' || c.store !== resolve(store) || index < 0)
+            throw new TrajectoriesError('INVALID_INPUT', 'Unknown session-list cursor.');
+        offset = index + 1;
+    }
+    const ids = names.slice(offset, offset + limit), items = await Promise.all(ids.map(id => getSession(store, id)));
+    return { items, nextCursor: offset + limit < names.length ? encode({ view: 'sessions', store: resolve(store), after: ids.at(-1) }) : null };
+}

package/dist/log-reconcile.d.ts

@@ -0,0 +1,5 @@
+/** Host-only recovery after its own writer/process guard proves all writers stopped.
+ * Never guesses from elapsed time, discards partial tails, or resolves native effects. */
+export declare function reconcileStoppedWriter(store: string, id: string, proof: {
+    writersStopped: true;
+}): Promise<boolean>;

package/dist/log-reconcile.js

@@ -0,0 +1,38 @@
+import { lstat, readdir, rmdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { safeId, syncDirectory } from './log-io.js';
+import { TrajectoriesError } from './log-types.js';
+import { readFrames } from './log-state.js';
+import { loadStage, bindingSnapshot } from './log-recovery.js';
+import { validateStageBacking } from './log-stage.js';
+import { selection } from './log-read.js';
+import { loadRecord } from './log-records.js';
+/** Host-only recovery after its own writer/process guard proves all writers stopped.
+ * Never guesses from elapsed time, discards partial tails, or resolves native effects. */
+export async function reconcileStoppedWriter(store, id, proof) {
+    if (proof?.writersStopped !== true)
+        throw new TrajectoriesError('INVALID_INPUT', 'The host must prove that every writer has stopped.');
+    const frames = await readFrames(store, id);
+    selection(frames);
+    for (const frame of frames) {
+        if (frame.body.capture)
+            await validateStageBacking(store, await loadStage(store, frame.body.capture), frames);
+        else if (frame.body.kind === 'binding')
+            await bindingSnapshot(store, frames, frame.body.binding.id);
+        for (const record of frame.body.records)
+            await loadRecord(store, record);
+    }
+    const path = join(resolve(store), 'locks', safeId(id));
+    try {
+        if (!(await lstat(path)).isDirectory() || (await readdir(path)).length)
+            throw new TrajectoriesError('OUTCOME_UNKNOWN', 'The writer lock is not the expected empty lock directory.');
+        await rmdir(path);
+        await syncDirectory(join(resolve(store), 'locks'));
+        return true;
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return false;
+        throw cause;
+    }
+}

package/dist/log-records.d.ts

@@ -0,0 +1,35 @@
+import type { NormalizedRecord } from '@letta-ai/trajectory';
+import type { Snapshot } from './types.js';
+import type { ConversationRecord, RecordId } from './log-types.js';
+import type { ContextEdit, StoredRecord } from './log-state.js';
+export interface CanonicalConversationRecord extends ConversationRecord {
+    canonical: Snapshot['canonical']['records'][number];
+}
+export interface Unit {
+    semantic: string;
+    payload: NormalizedRecord;
+    canonical: CanonicalConversationRecord['canonical'];
+}
+export declare function units(snapshot: Snapshot, archive?: boolean): Unit[];
+export declare function contextEdit(before: readonly RecordId[], after: readonly RecordId[]): ContextEdit;
+export declare function applyEdit(context: readonly RecordId[], edit?: ContextEdit): RecordId[];
+export declare function loadRecord(store: string, record: StoredRecord): Promise<CanonicalConversationRecord>;
+export declare function planRecords(input: {
+    store: string;
+    sessionId: string;
+    intentId: string;
+    observed: Snapshot;
+    before: Unit[];
+    beforeIds: RecordId[];
+    beforeActive: Unit[];
+    beforeActiveIds: RecordId[];
+    context: RecordId[];
+    origin: ConversationRecord['origin'];
+    allowInitialSystem?: boolean;
+}): Promise<{
+    records: StoredRecord[];
+    edit: ContextEdit;
+    added: RecordId[];
+    leading?: RecordId;
+    progress: boolean;
+}>;