trajectories 0.1.2 → 0.1.3

package/dist/log-stage.js

@@ -106,7 +106,9 @@ export async function stageCapture(store, snapshot, requested) {
             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;
+        // Annotations are post-hoc by definition; a capture stages normalization-time
+        // evidence only, so they are not retained as header state.
+        const { raw, canonical, attachments, annotations: _annotations, ...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,

package/dist/log-state.d.ts

@@ -53,7 +53,7 @@ export interface StageData {
     input: string;
     options: StageOptions;
     evidence: {
-        header: Omit<Snapshot, 'raw' | 'canonical' | 'attachments'>;
+        header: Omit<Snapshot, 'raw' | 'canonical' | 'attachments' | 'annotations'>;
         raw: TextRef;
         attachments: Array<{
             name: string;

package/dist/log-switch.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { lstat, realpath } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { HARNESSES } from './types.js';
+import { HARNESSES, isNativeHarness } 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';
@@ -21,8 +21,9 @@ async function preparedReceipt(store, frame) {
 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.');
+    if (!isNativeHarness(target)) {
+        throw new TrajectoriesError('INVALID_INPUT', HARNESSES.includes(target) ? `Unsupported target harness: ${target} is a read-only interchange format.` : 'Unsupported target harness.');
+    }
     let cwd;
     try {
         cwd = await realpath(resolve(requested.write.cwd));

package/dist/readers/atif.d.ts

@@ -0,0 +1,10 @@
+import type { SnapshotCanonical } from '../types.js';
+/**
+ * Carry ATIF per-step `metrics` and `extra` onto the canonical records the
+ * upstream normalizer emits for that step, and mark harness-injected user turns
+ * with `origin: 'harness'`. The upstream adapter drops both kinds of signal;
+ * they are re-attached here as wrapper properties. `record_json`, `record_hash`,
+ * `record_id` and `content_hash` stay untouched, so enrichment never perturbs
+ * existing record identity — the snapshot id deterministically covers the wrapper.
+ */
+export declare function enrichAtifCanonical(raw: string, canonical: SnapshotCanonical): SnapshotCanonical;

package/dist/readers/atif.js

@@ -0,0 +1,54 @@
+/** Matches the ATIF adapter's source record ids: `step:<n>` or `trajectory:<id>:step:<n>`. */
+const STEP_RECORD_ID = /^(?:trajectory:.+:)?step:([1-9]\d*)$/;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const present = (value) => value !== undefined && value !== null;
+/** ATIF cannot express a harness author: injected prompts (final-answer
+ * instructions, malformed-call retries, fallback final-answer calls) are recorded
+ * as `user` steps tagged with a synthetic `extra.role`. */
+function injectedOrigin(step) {
+    if (step.source !== 'user')
+        return undefined;
+    const role = isObject(step.extra) ? step.extra.role : undefined;
+    return typeof role === 'string' && role ? 'harness' : undefined;
+}
+/**
+ * Carry ATIF per-step `metrics` and `extra` onto the canonical records the
+ * upstream normalizer emits for that step, and mark harness-injected user turns
+ * with `origin: 'harness'`. The upstream adapter drops both kinds of signal;
+ * they are re-attached here as wrapper properties. `record_json`, `record_hash`,
+ * `record_id` and `content_hash` stay untouched, so enrichment never perturbs
+ * existing record identity — the snapshot id deterministically covers the wrapper.
+ */
+export function enrichAtifCanonical(raw, canonical) {
+    let document;
+    try {
+        document = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error('ATIF evidence is not the JSON trajectory that produced this canonical form.', { cause });
+    }
+    const steps = isObject(document) && Array.isArray(document.steps) ? document.steps : undefined;
+    if (!steps)
+        throw new Error('ATIF evidence has no steps array.');
+    const byStep = new Map();
+    for (const step of steps) {
+        if (!isObject(step) || typeof step.step_id !== 'number' || !Number.isInteger(step.step_id))
+            continue;
+        const { metrics, extra } = step;
+        const metadata = present(metrics) || present(extra)
+            ? { ...(present(metrics) ? { metrics } : {}), ...(present(extra) ? { extra } : {}) }
+            : undefined;
+        const origin = injectedOrigin(step);
+        if (!metadata && !origin)
+            continue;
+        byStep.set(step.step_id, { ...(metadata ? { metadata } : {}), ...(origin ? { origin } : {}) });
+    }
+    if (!byStep.size)
+        return canonical;
+    const records = canonical.records.map(record => {
+        const match = STEP_RECORD_ID.exec(record.stable_source_record_id);
+        const enrichment = match ? byStep.get(Number(match[1])) : undefined;
+        return enrichment ? { ...record, ...enrichment } : record;
+    });
+    return { ...canonical, records };
+}

package/dist/shared-managed.d.ts

@@ -0,0 +1,31 @@
+import type { CaptureId, Head, ManagedSession } from './log-types.js';
+import { type Frame } from './log-state.js';
+import { type IntentData } from './log-stage.js';
+/** Immutable history transfer. Native paths are provenance; importing never writes native files. */
+export interface ManagedDelta {
+    version: 1;
+    sessionId: string;
+    afterHead: Head | null;
+    head: Head;
+    frames: Frame[];
+    captures: Array<{
+        id: CaptureId;
+        object: string;
+    }>;
+    intents: Array<{
+        intentId: string;
+        data: IntentData;
+    }>;
+    objectIds: string[];
+}
+/** Enumerate only typed retained references. Generated export chunks remain reproducible from recipes. */
+export declare function managedObjectIds(store: string, frames: Frame[], lineage?: Frame[]): Promise<string[]>;
+export declare function exportManagedDelta(store: string, id: string, options?: {
+    afterHead?: Head | null;
+}): Promise<ManagedDelta>;
+/** Validate wire metadata before fetching any remote content references. */
+export declare function validateManagedDelta(delta: ManagedDelta, expectedHead: Head | null): void;
+/** Storage CAS, not an execution lease: importing cannot establish that a native process stopped. */
+export declare function importManagedDelta(store: string, delta: ManagedDelta, options: {
+    expectedHead: Head | null;
+}): Promise<ManagedSession>;

package/dist/shared-managed.js

@@ -0,0 +1,333 @@
+import { open, readFile, rm } from 'node:fs/promises';
+import { dirname, isAbsolute } from 'node:path';
+import { TrajectoriesError } from './log-types.js';
+import { atomicWrite, digest, ensureDirectory, getObject, safeId, stableJson, syncDirectory, withSessionLock } from './log-io.js';
+import { derivedChunks, getText } from './log-content.js';
+import { initializeLog, logPath, readFrames } from './log-state.js';
+import { capturePath, loadStage, recoverSnapshot, regenerateExport, bindingSnapshot } from './log-recovery.js';
+import { readIntent, saveIntent, validateStageBacking, checkpointLimits } from './log-stage.js';
+import { selection, sessionOf } from './log-read.js';
+import { captureBaseline, mapPreparedRecords } from './log-baseline.js';
+import { planRecords, loadRecord, units } from './log-records.js';
+import { assertSnapshotContinuation } from './store.js';
+import { HARNESSES } from './types.js';
+import { assertSnapshot, readNativeExportSnapshot } from './convert.js';
+function fail(message) { throw new TrajectoriesError('INTEGRITY_ERROR', message); }
+const equal = (a, b) => stableJson(a) === stableJson(b);
+function hash(value) {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value))
+        fail('Invalid shared content hash.');
+}
+/** Enumerate only typed retained references. Generated export chunks remain reproducible from recipes. */
+export async function managedObjectIds(store, frames, lineage) {
+    const ids = new Set();
+    async function object(id, derived) {
+        hash(id);
+        try {
+            const bytes = await getObject(store, id);
+            ids.add(id);
+            return bytes;
+        }
+        catch (error) {
+            if (error.cause?.code !== 'ENOENT' || !derived?.has(id))
+                throw error;
+            return getObject(store, id, derived);
+        }
+    }
+    async function text(ref, derived) {
+        if (!ref?.root)
+            fail('Missing text reference.');
+        await getText(store, ref, derived);
+        const visiting = new Set();
+        async function visit(part) {
+            if (!part || visiting.has(part.id))
+                fail('Invalid shared content tree.');
+            const bytes = await object(part.id, derived);
+            if (part.tree) {
+                visiting.add(part.id);
+                const children = JSON.parse(bytes.toString());
+                if (!Array.isArray(children) || !children.length || children.length > 32)
+                    fail('Invalid shared content tree.');
+                for (const child of children)
+                    await visit(child);
+                visiting.delete(part.id);
+            }
+        }
+        await visit(ref.root);
+    }
+    let accepted = lineage;
+    async function evidence(value) {
+        let derived;
+        if (value.derivedBinding) {
+            accepted ??= await readFrames(store, frames[0].body.session.id);
+            const native = await regenerateExport(store, accepted, value.derivedBinding);
+            const snapshot = readNativeExportSnapshot(native);
+            derived = derivedChunks([snapshot.raw, ...(snapshot.attachments ?? []).map(item => item.content)]);
+        }
+        await text(value.raw, derived);
+        for (const attachment of value.attachments)
+            await text(attachment.text, derived);
+    }
+    for (const frame of frames) {
+        await text(frame.body.diagnostics);
+        for (const record of frame.body.records)
+            await text(JSON.parse((await object(record.object)).toString()));
+        if (frame.body.capture) {
+            hash(frame.body.stage);
+            const stage = JSON.parse((await object(frame.body.stage)).toString());
+            await evidence(stage.evidence);
+            await text(stage.diagnostics);
+            for (const record of stage.records)
+                await text(JSON.parse((await object(record.object)).toString()));
+        }
+        if (frame.body.legacyBaseline)
+            await evidence(frame.body.legacyBaseline);
+    }
+    return [...ids].sort();
+}
+export async function exportManagedDelta(store, id, options = {}) {
+    safeId(id);
+    const accepted = await readFrames(store, id), current = accepted.at(-1);
+    if (!current)
+        throw new TrajectoriesError('NOT_FOUND', 'Managed session does not exist.');
+    const afterHead = options.afterHead ?? null;
+    const index = afterHead === null ? -1 : accepted.findIndex(frame => frame.head === afterHead);
+    if (afterHead !== null && index < 0)
+        throw new TrajectoriesError('STALE_HEAD', 'Requested shared baseline is not an ancestor.');
+    const frames = accepted.slice(index + 1);
+    const captures = [], intents = [];
+    for (const frame of frames) {
+        const data = await readIntent(store, id, frame.body.intentId);
+        if (!data || data.input !== frame.body.input)
+            fail('Committed frame has no matching durable intent.');
+        intents.push({ intentId: frame.body.intentId, data });
+        if (frame.body.capture) {
+            const pointer = JSON.parse(await readFile(capturePath(store, frame.body.capture.id), 'utf8'));
+            if (pointer.object !== frame.body.stage)
+                fail('Capture pointer disagrees with its committed frame.');
+            captures.push({ id: frame.body.capture.id, object: pointer.object });
+        }
+    }
+    return { version: 1, sessionId: id, afterHead, head: current.head, frames, captures, intents,
+        objectIds: await managedObjectIds(store, frames) };
+}
+function validateEnvelope(delta, expectedHead) {
+    if (!delta || delta.version !== 1 || !Array.isArray(delta.frames) || !Array.isArray(delta.captures)
+        || !Array.isArray(delta.intents) || !Array.isArray(delta.objectIds))
+        fail('Invalid managed transfer.');
+    safeId(delta.sessionId);
+    hash(delta.head);
+    if (expectedHead !== null)
+        hash(expectedHead);
+    if (delta.afterHead !== expectedHead)
+        throw new TrajectoriesError('STALE_HEAD', 'Transfer baseline differs from requested head.');
+    let parent = delta.afterHead;
+    const intents = new Set();
+    for (const frame of delta.frames) {
+        if (!frame?.body || frame.body.session?.id !== delta.sessionId || frame.body.parent !== parent
+            || digest(stableJson(frame.body)) !== frame.head)
+            fail('Shared log chain is corrupt.');
+        hash(frame.head);
+        hash(frame.body.input);
+        safeId(frame.body.intentId);
+        if (intents.has(frame.body.intentId))
+            fail('Repeated shared intent.');
+        intents.add(frame.body.intentId);
+        if (!isAbsolute(frame.body.session.workspace) || !Number.isFinite(Date.parse(frame.body.session.createdAt))
+            || !Number.isFinite(Date.parse(frame.body.time)) || !Array.isArray(frame.body.records)
+            || typeof frame.body.progress !== 'boolean' || !HARNESSES.includes(frame.body.binding?.harness)
+            || typeof frame.body.binding.nativeSessionId !== 'string')
+            fail('Invalid managed frame metadata.');
+        safeId(frame.body.binding.id);
+        checkpointLimits(frame.body.session.nativeCheckpoints);
+        if (frame.body.kind !== 'capture' && frame.body.kind !== 'binding')
+            fail('Unknown managed frame kind.');
+        parent = frame.head;
+    }
+    if (parent !== delta.head)
+        fail('Transfer head does not match its suffix.');
+    if (new Set(delta.objectIds).size !== delta.objectIds.length)
+        fail('Duplicate shared object declaration.');
+    for (const id of delta.objectIds)
+        hash(id);
+    if (delta.intents.length !== delta.frames.length || new Set(delta.intents.map(item => item.intentId)).size !== delta.intents.length)
+        fail('Transfer intent inventory is incomplete.');
+    const captures = delta.frames.filter(frame => frame.body.capture);
+    if (delta.captures.length !== captures.length || new Set(delta.captures.map(item => item.id)).size !== delta.captures.length)
+        fail('Transfer capture inventory is incomplete.');
+    for (const frame of delta.frames) {
+        const intent = delta.intents.find(item => item.intentId === frame.body.intentId)?.data;
+        if (!intent || intent.input !== frame.body.input)
+            fail('Transfer intent differs from its frame.');
+        if (frame.body.kind === 'capture') {
+            const ref = frame.body.capture;
+            if (!ref || !frame.body.stage || intent.stage !== frame.body.stage || intent.export
+                || ref.sessionId !== delta.sessionId || ref.parent !== frame.body.parent || ref.intentId !== frame.body.intentId
+                || ref.integrity !== frame.body.input || ref.bindingId !== frame.body.binding.id
+                || ref.source.harness !== frame.body.binding.harness || (ref.source.nativeSessionId ?? '') !== frame.body.binding.nativeSessionId)
+                fail('Capture frame has inconsistent provenance.');
+            safeId(ref.id);
+            hash(frame.body.stage);
+            if (delta.captures.find(item => item.id === ref.id)?.object !== frame.body.stage)
+                fail('Capture pointer differs from its frame.');
+        }
+        else if (frame.body.capture || frame.body.stage || frame.body.records.length || frame.body.edit || frame.body.progress
+            || (!!frame.body.recipe === !!frame.body.legacyBaseline) || !equal(intent.export ?? null, frame.body.recipe ?? null) || intent.stage) {
+            fail('Prepared binding frame has inconsistent retained input.');
+        }
+    }
+}
+/** Validate wire metadata before fetching any remote content references. */
+export function validateManagedDelta(delta, expectedHead) {
+    validateEnvelope(delta, expectedHead);
+}
+async function validateCapture(store, frame, before) {
+    const stage = await loadStage(store, frame.body.capture);
+    if (stage.version !== 2 || stage.options.sessionId !== frame.body.session.id || stage.options.intentId !== frame.body.intentId
+        || stage.options.expectedHead !== frame.body.parent || stage.input !== frame.body.input
+        || !equal(stage.ref, frame.body.capture) || !equal(stage.records, frame.body.records) || !equal(stage.edit, frame.body.edit)
+        || !equal(stage.binding, frame.body.binding) || stage.progress !== frame.body.progress
+        || !equal(stage.diagnostics, frame.body.diagnostics) || !equal(stage.nativeMeta ?? null, frame.body.nativeMeta ?? null))
+        fail('Committed capture does not match its retained stage.');
+    if (frame.body.parent === null && (stage.options.expectedHead !== null || stage.options.workspace !== frame.body.session.workspace
+        || !equal(stage.options.nativeCheckpoints, frame.body.session.nativeCheckpoints)))
+        fail('Initial capture session options differ.');
+    if (typeof stage.options.requireProgress !== 'boolean')
+        fail('Invalid capture progress policy.');
+    await validateStageBacking(store, stage, [...before, frame]);
+    const snapshot = await recoverSnapshot(store, stage, [...before, frame]);
+    assertSnapshot(snapshot);
+    const source = { harness: snapshot.source.harness, sha256: digest(snapshot.raw),
+        ...(snapshot.source.nativeSessionId ? { nativeSessionId: snapshot.source.nativeSessionId } : {}) };
+    if (!equal(stage.ref.source, source))
+        fail('Capture source fingerprint differs from recovered native evidence.');
+    const diagnostics = JSON.parse(await getText(store, stage.diagnostics));
+    const meta = snapshot.canonical.records.find(record => record.record_type === 'meta');
+    if (!equal(diagnostics, snapshot.canonical.diagnostics) || !equal(stage.nativeMeta ?? null, meta ? JSON.parse(meta.record_json) : null))
+        fail('Capture diagnostics or native metadata differ from recovered evidence.');
+    const operation = frame.body.parent === null ? 'create' : 'append';
+    if (digest(stableJson({ operation, options: stage.options, snapshot: snapshot.id })) !== stage.input)
+        fail('Capture intent does not bind its recovered native observation.');
+    const baseline = before.length ? await captureBaseline(store, before, snapshot, stage.options.expectedHead === null ? undefined : stage.options.bindingId) : undefined;
+    if (baseline)
+        assertSnapshotContinuation(baseline.snapshot, snapshot, { requireProgress: stage.options.requireProgress, allowInitialSystem: baseline.firstTarget });
+    const planned = await planRecords({ store, sessionId: frame.body.session.id, intentId: frame.body.intentId, observed: snapshot,
+        before: baseline?.before ?? [], beforeIds: baseline?.ids ?? [], beforeActive: baseline ? units(baseline.snapshot) : [],
+        beforeActiveIds: baseline?.activeIds ?? [], context: selection(before).context, allowInitialSystem: baseline?.firstTarget,
+        origin: { harness: stage.binding.harness, ...(stage.binding.nativeSessionId ? { nativeSessionId: stage.binding.nativeSessionId } : {}), bindingId: stage.binding.id } });
+    const mapping = { ...baseline?.mapping, added: planned.added, ...(planned.leading ? { leading: planned.leading } : {}) };
+    if (!equal(planned.records, stage.records) || !equal(planned.edit, stage.edit) || planned.progress !== stage.progress || !equal(mapping, stage.mapping)
+        || (baseline && !equal(baseline.binding, stage.binding)))
+        fail('Capture records or context do not reproduce from native evidence.');
+}
+/** Storage CAS, not an execution lease: importing cannot establish that a native process stopped. */
+export async function importManagedDelta(store, delta, options) {
+    validateEnvelope(delta, options?.expectedHead);
+    return withSessionLock(store, delta.sessionId, async () => {
+        await initializeLog(store);
+        const existing = await readFrames(store, delta.sessionId), current = existing.at(-1);
+        const replay = current?.head === delta.head;
+        if (replay) {
+            const index = delta.afterHead === null ? -1 : existing.findIndex(frame => frame.head === delta.afterHead);
+            if ((delta.afterHead !== null && index < 0) || !equal(existing.slice(index + 1), delta.frames))
+                throw new TrajectoriesError('INTENT_CONFLICT', 'Shared replay does not match the exact committed transition.');
+        }
+        else if ((current?.head ?? null) !== options.expectedHead) {
+            throw new TrajectoriesError('STALE_HEAD', 'Shared session advanced or diverged.');
+        }
+        const before = replay ? existing.slice(0, existing.length - delta.frames.length) : existing;
+        const seen = new Set(before.map(frame => frame.body.intentId));
+        const combined = [...before];
+        for (const frame of delta.frames) {
+            if (seen.has(frame.body.intentId))
+                throw new TrajectoriesError('INTENT_CONFLICT', 'Intent already belongs to another accepted frame.');
+            seen.add(frame.body.intentId);
+            if (combined[0] && !equal(combined[0].body.session, frame.body.session))
+                fail('Immutable session metadata changed.');
+            if (!combined.length && (frame.body.kind !== 'capture' || frame.body.session.createdAt !== frame.body.time))
+                fail('Invalid initial session frame.');
+            combined.push(frame);
+        }
+        selection(combined);
+        for (const id of delta.objectIds)
+            await getObject(store, id);
+        const createdPointers = [];
+        let publicationStarted = false;
+        try {
+            for (const pointer of delta.captures) {
+                const path = capturePath(store, pointer.id);
+                try {
+                    if (!equal(JSON.parse(await readFile(path, 'utf8')), { object: pointer.object }))
+                        fail('Immutable capture pointer conflicts.');
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                    await atomicWrite(path, stableJson({ object: pointer.object }), true);
+                    createdPointers.push(path);
+                }
+            }
+            for (const item of delta.intents) {
+                const previous = await readIntent(store, delta.sessionId, item.intentId);
+                if (previous && !equal(previous, item.data))
+                    throw new TrajectoriesError('INTENT_CONFLICT', 'Durable intent has different retained input.');
+            }
+            // Validate actual typed closure, including retained prefixes. A sender's
+            // declared object inventory cannot establish complete backing.
+            await managedObjectIds(store, combined, combined);
+            const validated = [...before];
+            for (const frame of delta.frames) {
+                if (frame.body.kind === 'capture')
+                    await validateCapture(store, frame, validated);
+                else {
+                    if (frame.body.recipe && (frame.body.recipe.atHead !== frame.body.parent || frame.body.recipe.write.cwd !== frame.body.session.workspace
+                        || frame.body.recipe.seed !== digest(stableJson([frame.body.input, 'native-entropy']))))
+                        fail('Prepared export recipe is inconsistent.');
+                    const snapshot = await bindingSnapshot(store, [...validated, frame], frame.body.binding.id);
+                    assertSnapshot(snapshot);
+                    if (snapshot.source.harness !== frame.body.binding.harness || snapshot.source.nativeSessionId !== frame.body.binding.nativeSessionId)
+                        fail('Prepared binding native identity differs.');
+                    const native = frame.body.recipe ? await regenerateExport(store, [...validated, frame], frame.body.binding.id) : undefined;
+                    const diagnostics = JSON.parse(await getText(store, frame.body.diagnostics));
+                    const meta = snapshot.canonical.records.find(record => record.record_type === 'meta');
+                    if (!equal(diagnostics, native?.diagnostics ?? snapshot.canonical.diagnostics)
+                        || !equal(frame.body.nativeMeta ?? null, meta ? JSON.parse(meta.record_json) : null))
+                        fail('Prepared binding diagnostics or native metadata differ from retained evidence.');
+                    const selected = selection(validated), records = new Map(selected.history.map(record => [record.id, record]));
+                    const context = await Promise.all(selected.context.map(async (id) => ({ id, record: await loadRecord(store, records.get(id)) })));
+                    mapPreparedRecords(context, units(snapshot, true));
+                }
+                validated.push(frame);
+            }
+            if (!validated.length)
+                fail('An empty transfer cannot create a session.');
+            if (!replay && delta.frames.length) {
+                for (const item of delta.intents)
+                    await saveIntent(store, delta.sessionId, item.intentId, item.data);
+                publicationStarted = true;
+                const path = logPath(store, delta.sessionId);
+                await ensureDirectory(dirname(path));
+                const file = await open(path, 'a', 0o600);
+                try {
+                    await file.writeFile(delta.frames.map(frame => stableJson(frame) + '\n').join(''));
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await syncDirectory(dirname(path));
+            }
+            return sessionOf(validated.at(-1));
+        }
+        catch (error) {
+            // Failed validation reserves no capture identity. After an append starts,
+            // preserve backing for every potentially committed frame; partial tails fail closed.
+            if (!publicationStarted)
+                for (const path of createdPointers)
+                    await rm(path);
+            if (error instanceof TrajectoriesError)
+                throw error;
+            throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared history validation or publication failed.', { cause: error });
+        }
+    });
+}

package/dist/shared-observed.d.ts

@@ -0,0 +1,96 @@
+import type { CanonicalRecordType, SourceIdentityKind } from '@letta-ai/trajectory';
+/** Read-only native-history observations, not proof of accepted native execution. */
+export interface ObservedSession {
+    id: string;
+    source: string;
+    source_path: string;
+    content_hash: string;
+    content_hash_version?: number;
+    title: string | null;
+    cwd: string | null;
+    model: string | null;
+    started_at: string | null;
+    ended_at: string | null;
+    record_count: number;
+    created_at: string;
+    updated_at: string;
+    parent_session_id?: string | null;
+    parent_tool_use_id?: string | null;
+    agent_nickname?: string | null;
+    thread_role?: string | null;
+    diagnostics?: Array<{
+        code: string;
+        occurrenceCount: number;
+        sample: string | null;
+        firstSeenAt?: string;
+    }>;
+}
+export interface ObservedRecord {
+    id: string;
+    session_id: string;
+    source_type: string;
+    native_session_id?: string | null;
+    binding_id?: string | null;
+    record_type: CanonicalRecordType;
+    stable_source_record_id: string | null;
+    source_identity_kind: SourceIdentityKind | null;
+    source_order_id: string;
+    component_index: number;
+    record_timestamp: string | null;
+    source_timestamp: string | null;
+    content: string | null;
+    tool_call_id: string | null;
+    tool_name: string | null;
+    tool_arguments_json: string | null;
+    tool_result_json: string | null;
+    tool_result_ok: number | null;
+    record_json: string;
+    content_hash: string;
+    record_hash: string;
+}
+export interface ObservedSummary {
+    id: string;
+    head: string;
+    machineId: string;
+    session: ObservedSession;
+}
+export interface ObservedState extends ObservedSummary {
+    records: ObservedRecord[];
+}
+export interface ObservedManifest extends ObservedSummary {
+    recordObjects: Array<{
+        id: string;
+        object: string;
+    }>;
+}
+export interface ObservedDelta {
+    version: 1;
+    id: string;
+    parent: string | null;
+    machineId: string;
+    sessionId: string;
+    sessionObject: string;
+    set: Array<{
+        id: string;
+        object: string;
+    }>;
+    remove: string[];
+}
+export declare function sharedObservationId(machineId: string, sessionId: string): string;
+export declare function assertObservedSummary(value: ObservedSummary, id?: string): void;
+export declare function assertObservedManifest(value: ObservedManifest, id?: string): void;
+export declare function assertObservedState(value: ObservedState, id?: string): void;
+export declare function getObservedManifest(store: string, id: string): Promise<ObservedManifest>;
+export declare function readObservedHistory(store: string, id: string): Promise<ObservedState>;
+export declare function listObservedHistories(store: string): Promise<ObservedSummary[]>;
+export declare function commitObservedDelta(store: string, delta: ObservedDelta): Promise<ObservedSummary>;
+export declare function prepareObservedHistory(input: {
+    machineId: string;
+    session: ObservedSession;
+    records: ObservedRecord[];
+}, previous?: ObservedManifest): Promise<{
+    delta: ObservedDelta | null;
+    objects: Map<string, Uint8Array>;
+    changedRecords: number;
+    removedRecords: number;
+}>;