trajectories 0.1.2 → 0.1.3

package/dist/shared.js

@@ -0,0 +1,357 @@
+import { timingSafeEqual } from 'node:crypto';
+import { TrajectoriesError } from './log-types.js';
+import { digest, getObject, putObject, safeId, stableJson } from './log-io.js';
+import { getSession, listSessions } from './log-read.js';
+import { exportManagedDelta, importManagedDelta, validateManagedDelta } from './shared-managed.js';
+import { commitObservedDelta, getObservedManifest, listObservedHistories, prepareObservedHistory, readObservedHistory, sharedObservationId, assertObservedState, assertObservedSummary } from './shared-observed.js';
+export { sharedObservationId } from './shared-observed.js';
+const MAX_BYTES = 64 * 1024 * 1024;
+function tokenBytes(token) {
+    if (typeof token !== 'string' || !token || /[\s\x00-\x1f\x7f]/u.test(token) || token.length > 4096)
+        throw new TrajectoriesError('INVALID_INPUT', 'A nonempty shared-store token is required.');
+    return Buffer.from(`Bearer ${token}`);
+}
+async function boundedBody(message, limit) {
+    const declared = message.headers.get('content-length');
+    if (declared !== null && (!/^\d+$/.test(declared) || Number(declared) > limit))
+        throw new TrajectoriesError('CAPACITY_EXCEEDED', 'Shared transfer exceeds the admitted byte limit.');
+    const reader = message.body?.getReader();
+    if (!reader)
+        return new Uint8Array();
+    let size = 0;
+    const chunks = [];
+    try {
+        for (;;) {
+            const item = await reader.read();
+            if (item.done)
+                break;
+            size += item.value.byteLength;
+            if (size > limit)
+                throw new TrajectoriesError('CAPACITY_EXCEEDED', 'Shared transfer exceeds the admitted byte limit.');
+            chunks.push(item.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, size);
+}
+const json = (value, status = 200) => new Response(JSON.stringify(value), {
+    status, headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+});
+const decode = (bytes) => {
+    try {
+        return JSON.parse(Buffer.from(bytes).toString());
+    }
+    catch {
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared-store JSON.');
+    }
+};
+function missingObject(error) { return error.cause?.code === 'ENOENT'; }
+function assertManagedSummary(value, id) {
+    if (!value || value.version !== 2 || typeof value.workspace !== 'string' || !value.workspace
+        || typeof value.head !== 'string' || !/^[a-f0-9]{64}$/.test(value.head)
+        || typeof value.createdAt !== 'string' || typeof value.updatedAt !== 'string'
+        || !value.nativeCheckpoints || !Number.isSafeInteger(value.nativeCheckpoints.maxCount) || value.nativeCheckpoints.maxCount < 0
+        || !Number.isSafeInteger(value.nativeCheckpoints.maxBytes) || value.nativeCheckpoints.maxBytes < 0)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid shared managed session metadata.');
+    safeId(value.id);
+    if (id !== undefined && value.id !== id)
+        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared managed session identity mismatch.');
+}
+/** Node-compatible fetch handler; the host owns sockets, TLS, credentials and process lifetime. */
+export function createSharedHandler(options) {
+    const expected = tokenBytes(options.token), limit = options.maxBytes ?? MAX_BYTES;
+    if (!Number.isSafeInteger(limit) || limit <= 0)
+        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared-store byte limit.');
+    return async (request) => {
+        const supplied = Buffer.from(request.headers.get('authorization') ?? '');
+        if (supplied.byteLength !== expected.byteLength || !timingSafeEqual(supplied, expected))
+            return json({ error: { code: 'UNAUTHORIZED', message: 'Shared-store authentication required.' } }, 401);
+        try {
+            const url = new URL(request.url), path = url.pathname;
+            if (path === '/v1/objects/check' && request.method === 'POST') {
+                const keys = decode(await boundedBody(request, limit));
+                if (!Array.isArray(keys) || keys.length > 512 || new Set(keys).size !== keys.length
+                    || !keys.every(key => typeof key === 'string' && /^[a-f0-9]{64}$/.test(key)))
+                    throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared object inventory.');
+                const missing = [];
+                for (const key of keys) {
+                    try {
+                        await getObject(options.store, key);
+                    }
+                    catch (error) {
+                        if (missingObject(error))
+                            missing.push(key);
+                        else
+                            throw error;
+                    }
+                }
+                return json({ missing });
+            }
+            if (path === '/v1/objects/batch' && request.method === 'POST') {
+                const items = decode(await boundedBody(request, limit));
+                if (!Array.isArray(items) || items.length > 512)
+                    throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared object batch.');
+                const verified = new Map();
+                for (const item of items) {
+                    if (!item || typeof item.object !== 'string' || !/^[a-f0-9]{64}$/.test(item.object)
+                        || typeof item.base64 !== 'string' || verified.has(item.object))
+                        throw new TrajectoriesError('INVALID_INPUT', 'Invalid shared batch item.');
+                    const bytes = Buffer.from(item.base64, 'base64');
+                    if (bytes.toString('base64') !== item.base64 || digest(bytes) !== item.object)
+                        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared batch contains corrupt content.');
+                    verified.set(item.object, bytes);
+                }
+                for (const bytes of verified.values())
+                    await putObject(options.store, bytes);
+                return json({ objects: [...verified.keys()] });
+            }
+            const object = /^\/v1\/objects\/([a-f0-9]{64})$/.exec(path);
+            if (object && ['GET', 'HEAD', 'PUT'].includes(request.method)) {
+                const key = object[1];
+                if (request.method === 'PUT') {
+                    const bytes = await boundedBody(request, limit);
+                    if (digest(bytes) !== key)
+                        throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared object does not match its declared digest.');
+                    await putObject(options.store, bytes);
+                    return json({ object: key });
+                }
+                let bytes;
+                try {
+                    bytes = await getObject(options.store, key);
+                }
+                catch (error) {
+                    if (missingObject(error))
+                        return json({ error: { code: 'NOT_FOUND', message: 'Shared object not found.' } }, 404);
+                    throw error;
+                }
+                if (bytes.byteLength > limit)
+                    throw new TrajectoriesError('CAPACITY_EXCEEDED', 'Shared object exceeds the admitted byte limit.');
+                return new Response(request.method === 'HEAD' ? null : new Uint8Array(bytes), {
+                    headers: { 'content-type': 'application/octet-stream', 'content-length': String(bytes.byteLength), 'cache-control': 'no-store' },
+                });
+            }
+            if (path === '/v1/observed' && request.method === 'GET')
+                return json(await listObservedHistories(options.store));
+            const observed = /^\/v1\/observed\/([a-f0-9]{64})$/.exec(path);
+            if (observed && request.method === 'GET')
+                return json(url.searchParams.get('manifest') === '1'
+                    ? await getObservedManifest(options.store, observed[1]) : await readObservedHistory(options.store, observed[1]));
+            if (observed && request.method === 'POST') {
+                const delta = decode(await boundedBody(request, limit));
+                if (delta?.id !== observed[1])
+                    throw new TrajectoriesError('INVALID_INPUT', 'Shared route and observation identity differ.');
+                return json(await commitObservedDelta(options.store, delta));
+            }
+            if (path === '/v1/managed' && request.method === 'GET') {
+                const sessions = [];
+                let cursor;
+                do {
+                    const page = await listSessions(options.store, { cursor, limit: 1000 });
+                    sessions.push(...page.items);
+                    cursor = page.nextCursor ?? undefined;
+                } while (cursor);
+                return json(sessions);
+            }
+            const managed = /^\/v1\/managed\/([A-Za-z0-9][A-Za-z0-9_-]{0,127})$/.exec(path);
+            if (managed && request.method === 'GET') {
+                if (url.searchParams.get('summary') === '1')
+                    return json(await getSession(options.store, managed[1]));
+                const after = url.searchParams.get('after');
+                return json(await exportManagedDelta(options.store, managed[1], { afterHead: after }));
+            }
+            if (managed && request.method === 'POST') {
+                const input = decode(await boundedBody(request, limit));
+                if (input?.delta?.sessionId !== managed[1])
+                    throw new TrajectoriesError('INVALID_INPUT', 'Shared route and managed identity differ.');
+                return json(await importManagedDelta(options.store, input.delta, { expectedHead: input.expectedHead }));
+            }
+            return json({ error: { code: 'NOT_FOUND', message: 'Shared-store route not found.' } }, 404);
+        }
+        catch (error) {
+            const code = error instanceof TrajectoriesError ? error.code : 'INTEGRITY_ERROR';
+            const status = code === 'NOT_FOUND' ? 404 : code === 'STALE_HEAD' || code === 'INTENT_CONFLICT' || code === 'OPERATION_PENDING' ? 409
+                : code === 'CAPACITY_EXCEEDED' ? 413 : 422;
+            return json({ error: { code, message: error instanceof TrajectoriesError ? error.message : 'Shared history could not be validated.' } }, status);
+        }
+    };
+}
+export function createSharedClient(options) {
+    tokenBytes(options.token);
+    const base = new URL(options.url);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new TrajectoriesError('INVALID_INPUT', 'Shared endpoint must be an HTTP(S) URL without embedded credentials, query or fragment.');
+    if (!base.pathname.endsWith('/'))
+        base.pathname += '/';
+    async function request(path, init = {}) {
+        const response = await fetch(new URL(path, base), { ...init, redirect: 'error', signal: options.signal,
+            headers: { ...Object.fromEntries(new Headers(init.headers)), authorization: `Bearer ${options.token}` } });
+        if (!response.ok) {
+            if (init.method === 'HEAD')
+                throw new TrajectoriesError(response.status === 404 ? 'NOT_FOUND' : 'INTEGRITY_ERROR', 'Shared object lookup failed.');
+            const data = decode(await boundedBody(response, MAX_BYTES));
+            const code = data.error?.code;
+            const allowed = ['INVALID_INPUT', 'NOT_FOUND', 'INTEGRITY_ERROR', 'UNSUPPORTED_CONTEXT', 'STALE_HEAD', 'INTENT_CONFLICT', 'OPERATION_PENDING', 'OUTCOME_UNKNOWN', 'CAPACITY_EXCEEDED'];
+            throw new TrajectoriesError(allowed.includes(code ?? '') ? code : 'INVALID_INPUT', data.error?.message ?? 'Shared request failed.');
+        }
+        return response;
+    }
+    const read = async (path) => decode(await boundedBody(await request(path), MAX_BYTES));
+    async function upload(objects) {
+        let objectsTransferred = 0, bytesTransferred = 0;
+        const entries = [...objects];
+        for (let offset = 0; offset < entries.length; offset += 512) {
+            const group = entries.slice(offset, offset + 512), keys = group.map(([key]) => key);
+            const response = await request('v1/objects/check', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(keys) });
+            const inventory = decode(await boundedBody(response, MAX_BYTES));
+            if (!inventory || !Array.isArray(inventory.missing) || new Set(inventory.missing).size !== inventory.missing.length
+                || !inventory.missing.every(key => keys.includes(key)))
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid shared object inventory response.');
+            const missing = new Set(inventory.missing);
+            let batch = [], batchBytes = 0;
+            const flush = async () => {
+                if (!batch.length)
+                    return;
+                const reply = decode(await boundedBody(await request('v1/objects/batch', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(batch) }), MAX_BYTES));
+                if (!reply || stableJson(reply.objects) !== stableJson(batch.map(item => item.object)))
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared batch acknowledgment differs.');
+                objectsTransferred += batch.length;
+                bytesTransferred += batchBytes;
+                batch = [];
+                batchBytes = 0;
+            };
+            for (const [key, bytes] of group) {
+                if (!missing.has(key))
+                    continue;
+                if (digest(bytes) !== key)
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Local shared object is corrupt.');
+                if (bytes.byteLength > 1024 * 1024) {
+                    await flush();
+                    await request(`v1/objects/${key}`, { method: 'PUT', body: new Uint8Array(bytes) });
+                    objectsTransferred++;
+                    bytesTransferred += bytes.byteLength;
+                    continue;
+                }
+                if (batchBytes + bytes.byteLength > 1024 * 1024)
+                    await flush();
+                batch.push({ object: key, base64: Buffer.from(bytes).toString('base64') });
+                batchBytes += bytes.byteLength;
+            }
+            await flush();
+        }
+        return { objectsTransferred, bytesTransferred };
+    }
+    return {
+        async listObserved() {
+            const values = await read('v1/observed');
+            if (!Array.isArray(values))
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid shared session list.');
+            const ids = new Set();
+            for (const value of values) {
+                assertObservedSummary(value);
+                if (ids.has(value.id))
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Duplicate shared session.');
+                ids.add(value.id);
+            }
+            return values;
+        },
+        async getObserved(id) { const value = await read(`v1/observed/${id}`); assertObservedState(value, id); return value; },
+        async listManaged() {
+            const values = await read('v1/managed');
+            if (!Array.isArray(values))
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Invalid managed session list.');
+            const ids = new Set();
+            for (const value of values) {
+                assertManagedSummary(value);
+                if (ids.has(value.id))
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Duplicate managed session.');
+                ids.add(value.id);
+            }
+            return values;
+        },
+        async pushObserved(input) {
+            const id = sharedObservationId(input.machineId, input.session.id);
+            let previous;
+            try {
+                previous = await read(`v1/observed/${id}?manifest=1`);
+            }
+            catch (error) {
+                if (!(error instanceof TrajectoriesError) || error.code !== 'NOT_FOUND')
+                    throw error;
+            }
+            const prepared = await prepareObservedHistory(input, previous);
+            if (!prepared.delta)
+                return { id, head: previous.head, changedRecords: 0, removedRecords: 0, objectsTransferred: 0, bytesTransferred: 0 };
+            const transferred = await upload(prepared.objects);
+            const response = await request(`v1/observed/${id}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: stableJson(prepared.delta) });
+            const committed = decode(await boundedBody(response, MAX_BYTES));
+            assertObservedSummary(committed, id);
+            if (committed.head !== digest(stableJson(prepared.delta)) || stableJson(committed.session) !== stableJson(input.session))
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared observation acknowledgment does not match the published delta.');
+            return { id, head: committed.head, ...transferred, changedRecords: prepared.changedRecords, removedRecords: prepared.removedRecords };
+        },
+        async pushManaged(store, id) {
+            let remote;
+            try {
+                remote = await read(`v1/managed/${id}?summary=1`);
+            }
+            catch (error) {
+                if (!(error instanceof TrajectoriesError) || error.code !== 'NOT_FOUND')
+                    throw error;
+            }
+            if (remote)
+                assertManagedSummary(remote, id);
+            const delta = await exportManagedDelta(store, id, { afterHead: remote?.head ?? null });
+            const objects = new Map();
+            for (const key of delta.objectIds)
+                objects.set(key, await getObject(store, key));
+            const transferred = await upload(objects);
+            if (delta.frames.length) {
+                const committed = decode(await boundedBody(await request(`v1/managed/${id}`, { method: 'POST', headers: { 'content-type': 'application/json' },
+                    body: stableJson({ expectedHead: remote?.head ?? null, delta }) }), MAX_BYTES));
+                assertManagedSummary(committed, id);
+                if (committed.head !== delta.head)
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared managed acknowledgment differs from the submitted head.');
+            }
+            return { id, head: delta.head, framesTransferred: delta.frames.length, ...transferred };
+        },
+        async pullManaged(store, id) {
+            let local;
+            try {
+                local = await getSession(store, id);
+            }
+            catch (error) {
+                if (!(error instanceof TrajectoriesError) || error.code !== 'NOT_FOUND')
+                    throw error;
+            }
+            const delta = await read(`v1/managed/${id}${local ? `?after=${encodeURIComponent(local.head)}` : ''}`);
+            if (delta?.sessionId !== id)
+                throw new TrajectoriesError('INTEGRITY_ERROR', 'Shared managed transfer belongs to another session.');
+            validateManagedDelta(delta, local?.head ?? null);
+            let objectsTransferred = 0, bytesTransferred = 0;
+            for (const key of delta.objectIds) {
+                try {
+                    await getObject(store, key);
+                    continue;
+                }
+                catch (error) {
+                    if (!missingObject(error))
+                        throw error;
+                }
+                const bytes = await boundedBody(await request(`v1/objects/${key}`), MAX_BYTES);
+                if (digest(bytes) !== key)
+                    throw new TrajectoriesError('INTEGRITY_ERROR', 'Remote shared object is corrupt.');
+                await putObject(store, bytes);
+                objectsTransferred++;
+                bytesTransferred += bytes.byteLength;
+            }
+            await importManagedDelta(store, delta, { expectedHead: local?.head ?? null });
+            return { id, head: delta.head, framesTransferred: delta.frames.length, objectsTransferred, bytesTransferred };
+        },
+    };
+}

package/dist/types.d.ts

@@ -1,6 +1,42 @@
-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"];
+import type { CanonicalRecord, CanonicalResult, NormalizedRecord } from '@letta-ai/trajectory';
+/** Harnesses that own a native store this package can export to. */
+export declare const NATIVE_HARNESSSES: readonly ["claude-code", "codex", "pi", "omp", "opencode", "grok-build", "cursor", "deepagents", "github-copilot", "cline", "fx"];
+export type NativeHarness = typeof NATIVE_HARNESSSES[number];
+/** ATIF is a read-only interchange format: it is captured and normalized, but has no native writer. */
+export declare const HARNESSES: readonly ["claude-code", "codex", "pi", "omp", "opencode", "grok-build", "cursor", "deepagents", "github-copilot", "cline", "fx", "atif"];
 export type Harness = typeof HARNESSES[number];
+export declare function isNativeHarness(value: Harness): value is NativeHarness;
+/** Opaque per-record enrichment (for example ATIF step `metrics`/`extra`).
+ * Carried outside `record_json`, so `record_hash`, `record_id` and `content_hash`
+ * never move when enrichment is attached. */
+export type CanonicalRecordMetadata = Record<string, unknown>;
+/** Who authored a message's underlying source turn when the source format can tell.
+ * ATIF records harness-injected prompts as `user` steps tagged `extra.role`; those
+ * surface as canonical user records with origin `harness`. */
+export type RecordOrigin = 'user' | 'harness';
+/** A canonical record plus optional post-normalization enrichment.
+ * The wrapper properties are excluded from every per-record hash and from the
+ * lossless `record_json`; the snapshot id deterministically covers them. */
+export interface ExtendedCanonicalRecord extends CanonicalRecord {
+    metadata?: CanonicalRecordMetadata;
+    origin?: RecordOrigin;
+}
+/** Canonical form as retained by a Snapshot; records may carry enrichment. */
+export interface SnapshotCanonical extends CanonicalResult {
+    records: ExtendedCanonicalRecord[];
+}
+/** Post-hoc annotation for a finished trajectory (judge verdict, review error,
+ * first-pointed step). The channel is append-only and lives outside `raw` and
+ * every content hash: attaching one never re-normalizes, never changes the
+ * snapshot id, and never moves a record id. */
+export interface SnapshotAnnotation {
+    /** What this annotation is, e.g. `judge-verdict`. */
+    kind: string;
+    /** Canonical JSON payload; integrity-hashed on its own. */
+    content: string;
+    sha256: string;
+    createdAt: string;
+}
 /** 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. */
@@ -22,7 +58,9 @@ export interface Snapshot {
         content: string;
         sha256: string;
     }>;
-    canonical: CanonicalResult;
+    /** Appended after normalization; outside the snapshot id and all content hashes. */
+    annotations?: SnapshotAnnotation[];
+    canonical: SnapshotCanonical;
     /** Archived histories can be inspected even when active-context conversion is unsupported. */
     portabilityIssues?: ConversionDiagnostic[];
 }

package/dist/types.js

@@ -1 +1,7 @@
-export const HARNESSES = ['claude-code', 'codex', 'pi', 'omp', 'opencode', 'grok-build', 'cursor', 'deepagents', 'github-copilot', 'cline', 'fx'];
+/** Harnesses that own a native store this package can export to. */
+export const NATIVE_HARNESSSES = ['claude-code', 'codex', 'pi', 'omp', 'opencode', 'grok-build', 'cursor', 'deepagents', 'github-copilot', 'cline', 'fx'];
+/** ATIF is a read-only interchange format: it is captured and normalized, but has no native writer. */
+export const HARNESSES = [...NATIVE_HARNESSSES, 'atif'];
+export function isNativeHarness(value) {
+    return NATIVE_HARNESSSES.includes(value);
+}

package/docs/shared-history.md

@@ -0,0 +1,133 @@
+# Shared history across machines
+
+Trajectories keeps SQLite for local ingestion and search. An authenticated shared
+store receives canonical records and immutable managed-session evidence, so another
+machine can read or index that history without reaching the originating machine.
+Each session retains its own history and identity. Synchronization uploads missing
+objects and changed records or managed log suffixes; it does not copy SQLite files
+or create a full snapshot on every sync.
+
+Confirm your installed CLI supports this feature with `trajectories remote --help`.
+Upgrade to the latest published package, or build from this checkout if unavailable.
+
+## CLI
+
+Provision the same secret on the server and each client in an owner-owned regular
+file with mode `0600`. Pass its **path**, never its value, through `--token-file`
+or `TRAJECTORIES_REMOTE_TOKEN_FILE`.
+
+```sh
+# Shared host: private durable directory; listens on loopback by default.
+trajectories remote serve --store /srv/private/trajectories \
+  --token-file /private/trajectories-token --port 8789
+
+# Client: reach that listener through a private SSH tunnel.
+ssh -N -L 8789:127.0.0.1:8789 user@shared-host
+
+# Publish this machine's native histories already indexed in SQLite.
+trajectories remote push --url http://127.0.0.1:8789 \
+  --token-file /private/trajectories-token --machine laptop \
+  --db /local/ledger.sqlite
+
+# Publish managed sessions instead; --session selects one when needed.
+trajectories remote push --url http://127.0.0.1:8789 \
+  --token-file /private/trajectories-token --machine laptop \
+  --store /local/session-store --session conversation
+
+# Another machine: pull observed histories into its existing lexical index.
+# --store also mirrors managed logs and indexes their accepted history.
+trajectories remote pull --url http://127.0.0.1:8789 \
+  --token-file /private/trajectories-token --machine server --db /local/ledger.sqlite \
+  --store /local/managed-mirror
+trajectories remote list --url http://127.0.0.1:8789 \
+  --token-file /private/trajectories-token
+trajectories search 'deployment decision' --db /local/ledger.sqlite --robot
+```
+
+Keep `--machine` stable for that originating machine. With neither `--store` nor
+`--db`, push uses the existing canonical SQLite path. An explicit `--store`
+selects managed sessions; add `--db` to publish both lanes. Push and pull print
+JSON summaries, not record bodies or credentials. Remote `list` also prints only
+summary identities, heads, sources and counts. Use TLS termination or a private
+tunnel for transport; the built-in HTTP listener does not provide TLS.
+
+## What is shared
+
+- **Observed native history:** histories ingested by any supported native reader
+  contribute canonical session records, complete tool-output fields and normalization
+  diagnostics. A SQLite read transaction pins one source generation before upload.
+  Machine identity namespaces colliding native session IDs. Pulled rows retain
+  per-record lineage and parent links; their local origin is
+  `shared://MACHINE/ENCODED_INDEXED_ID`. The original source path remains available
+  through the remote SDK. These records are history, not a raw native transcript
+  archive or proof of native execution recovery.
+- **Managed sessions:** transfer the exact canonical log chain, accepted ordering,
+  bindings, receipts and required immutable backing evidence. Hash verification
+  and expected-head checks reject corruption and conflicting continuations.
+  Repeating an unchanged push sends no additional objects. Local indexing remains
+  a derived lexical projection of accepted history.
+
+An unchanged observed mirror skips downloading its history body when its stored
+head matches the remote summary. Managed pulls still validate their transfer,
+including an empty delta. If a managed mirror has advanced locally, pull verifies
+that a refreshed remote head is an ancestor of its accepted local chain and reports
+`ahead`, retaining that branch. A diverged session reports `conflict`; pull continues
+with other sessions, indexes available accepted histories and prints its summary
+before exiting nonzero. It does not merge conflicting branches automatically.
+
+When pulling into a machine's existing native index, pass the same stable
+`--machine` ID used by its pushes. Its own observed sessions are reported as
+`skipped-origin`, so native rows remain the only local copy while other machines'
+histories are imported. Omit this option when building a complete separate mirror.
+
+Pull never launches a harness, takes native execution ownership or migrates a
+workspace. A restored managed session retains its workspace reference; preparing
+and executing a continuation still requires the caller's workspace, native tools
+and credentials. Pulled observed rows are excluded from later native-history pushes.
+
+Existing CLI deletions suppress the selected local mirror through its tombstone;
+another pull cannot revive it. They do not delete the shared session or propagate
+a global deletion. Diagnostic first-seen times are preserved; last-seen times are
+derived locally when indexing.
+
+## SDK
+
+The shared handler and client work in Node 22.13+ without Bun SQLite. The host owns
+HTTP adaptation, TLS, credential loading and process lifetime.
+
+```ts
+import { createSharedHandler, createSharedClient } from 'trajectories';
+
+const token = await loadSecret(); // Your host's private credential mechanism.
+const handler = createSharedHandler({ store: '/srv/private/trajectories', token });
+// Mount handler as (request: Request) => Promise<Response> in your HTTP host.
+
+const client = createSharedClient({ url: 'https://history.example.com/', token });
+const observed = await client.listObserved();
+const history = await client.getObserved(observed[0]!.id);
+await client.pushManaged('/local/session-store', 'conversation');
+await client.pullManaged('/local/managed-mirror', 'conversation');
+```
+
+`pushObserved({ machineId, session, records })` publishes the canonical SQLite-shaped
+metadata and record structures exposed by the SDK types. SDK clients can also pass
+an `AbortSignal`. Tokens in endpoint URLs and redirects are rejected.
+
+The default request/response body limit is **64 MiB**; the handler can configure
+`maxBytes`, while the client retains its 64 MiB admission limit. Complete observed
+history responses, managed deltas and individual objects must fit those limits;
+an oversized transfer fails explicitly. Object uploads batch at most 512 objects
+and check the remote inventory first. `bytesTransferred` counts missing immutable
+object bytes only, excluding manifests, JSON/base64 encoding and HTTP/TLS overhead.
+
+## DuckDB's role
+
+DuckDB remains an optional, rebuildable analytical projection, with no production
+dependency or local-storage migration. On the measured metadata corpus, four warm
+cross-session aggregate queries ran **2.9–33.5× faster** than indexed SQLite.
+DuckDB's [SQLite extension](https://duckdb.org/docs/current/core_extensions/sqlite)
+can read existing SQLite tables directly. That approach had mixed results in this
+trial, including a slower large-session
+read. This evidence supports repeated aggregate analysis, not replacing SQLite
+ingestion, FTS5 search or managed commit authority. See the
+[benchmark, costs and limits](../evidence/duckdb-local-2026-10-13/README.md).

package/legacy/src/db.ts

@@ -1289,7 +1289,7 @@ export class TrajectoryDb {
             session.id,
           ],
         );
-        this.insertRecordsInternal(session.id, session.source, records);
+        this.insertRecordsInternal(session.id, session.source, records, session.source_path);
         if (diagnostics) this.writeIngestDiagnostics(session.id, session.source, diagnostics);
         return { inserted: false, updated: true, deduped: false };
       }
@@ -1321,7 +1321,7 @@ export class TrajectoryDb {
           session.thread_role ?? null,
         ],
       );
-      this.insertRecordsInternal(session.id, session.source, records);
+      this.insertRecordsInternal(session.id, session.source, records, session.source_path);
       if (diagnostics) this.writeIngestDiagnostics(session.id, session.source, diagnostics);
       return { inserted: true, updated: false, deduped: false };
     }).immediate();
@@ -1368,7 +1368,7 @@ export class TrajectoryDb {
         }
         const contentHash = extendSessionHash(session.content_hash, fresh);
 
-        this.insertRecordsInternal(sessionId, session.source, fresh);
+        this.insertRecordsInternal(sessionId, session.source, fresh, session.source_path);
         this.db.run(
           `UPDATE sessions SET
             content_hash = ?, content_hash_version = ?, ended_at = ?, record_count = ?, updated_at = ?
@@ -1702,18 +1702,22 @@ export class TrajectoryDb {
     for (const row of rows.iterate(...key)) {
       batch.push(JSON.parse(row.canonical_json) as CanonicalDbRecord);
       if (batch.length === 256) {
-        this.insertRecordsInternal(session.id, session.source, batch);
+        this.insertRecordsInternal(session.id, session.source, batch, session.source_path);
         batch = [];
       }
     }
-    if (batch.length) this.insertRecordsInternal(session.id, session.source, batch);
+    if (batch.length) this.insertRecordsInternal(session.id, session.source, batch, session.source_path);
   }
 
   private insertRecordsInternal(
     sessionId: string,
     sourceType: string,
     records: CanonicalDbRecord[],
+    sourcePath?: string,
   ): void {
+    // Shared mirrors carry original per-record lineage, as managed projections do.
+    // Native ingestion still attributes records to the admitted source adapter.
+    const preserveRecordSource = sourceType === "managed" || sourcePath?.startsWith("shared://") === true;
     const insertRecordStmt = this.db.prepare(
       `INSERT OR REPLACE INTO records (
         id, session_id, source_type, native_session_id, binding_id, record_type, stable_source_record_id,
@@ -1741,7 +1745,7 @@ export class TrajectoryDb {
       insertRecordStmt.run(
         r.id,
         sessionId,
-        sourceType === "managed" ? r.source_type : sourceType,
+        preserveRecordSource ? r.source_type : sourceType,
         r.native_session_id ?? null,
         r.binding_id ?? null,
         r.record_type,
@@ -1808,7 +1812,7 @@ export class TrajectoryDb {
       insertFtsStmt.run(
         r.id,
         sessionId,
-        sourceType === "managed" ? r.source_type : sourceType,
+        preserveRecordSource ? r.source_type : sourceType,
         r.record_type,
         r.content ?? "",
         r.tool_name ?? "",

package/legacy/src/reader.ts

@@ -15,6 +15,7 @@ import { SCHEMA_VERSION } from "./schema.js";
 import { classifyReadStore, formatMismatchMessage, incompleteStoreMessage } from "./schema-gate.js";
 import type {
   CanonicalDbRecord,
+  IngestDiagnosticRecord,
   QueryResult,
   RecordMatchType,
   RecordSearchHit,
@@ -1220,6 +1221,26 @@ export class TrajectoryReader {
     return sessionRecords(this.db, sessionId);
   }
 
+  /** Read normalization uncertainty without opening a writer or reviving a tombstone. */
+  getSessionDiagnostics(sessionId: string): IngestDiagnosticRecord[] {
+    if (!this.getSession(sessionId)) return [];
+    return this.db.query<IngestDiagnosticRecord, [string]>(
+      `SELECT session_id, source, code, occurrence_count, sample, first_seen_at, last_seen_at
+       FROM ingest_diagnostics WHERE session_id = ? ORDER BY code ASC`,
+    ).all(sessionId);
+  }
+
+  /** Pin one source generation before sending its complete history to a remote. */
+  readSessionForSync(sessionId: string): {
+    session: SessionRecord; records: CanonicalDbRecord[]; diagnostics: IngestDiagnosticRecord[];
+  } | null {
+    return this.db.transaction(() => {
+      const session = this.getSession(sessionId);
+      if (!session) return null;
+      return { session, records: this.getSessionRecords(sessionId), diagnostics: this.getSessionDiagnostics(sessionId) };
+    }).deferred();
+  }
+
   getSessionCount(): number {
     return countSessions(this.db);
   }