trajectories 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,14 +1,153 @@
-// src/types.ts
-var HARNESSES = ["claude-code", "codex", "pi", "omp", "opencode", "grok-build", "cursor", "deepagents", "github-copilot", "cline", "fx"];
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
 // src/log-types.ts
-class TrajectoriesError extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.code = code;
-    this.name = "TrajectoriesError";
+var TrajectoriesError;
+var init_log_types = __esm(() => {
+  TrajectoriesError = class TrajectoriesError extends Error {
+    code;
+    constructor(code, message, options) {
+      super(message, options);
+      this.code = code;
+      this.name = "TrajectoriesError";
+    }
+  };
+});
+
+// src/log-io.ts
+import { createHash as createHash9, randomUUID as randomUUID2 } from "node:crypto";
+import { link, mkdir as mkdir2, open, readFile as readFile4, rename, rm } from "node:fs/promises";
+import { dirname as dirname3, join as join5, resolve as resolve8 } from "node:path";
+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;
+}
+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;
+}
+function objectPath(store, id) {
+  if (!/^[a-f0-9]{64}$/.test(id))
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Invalid content reference.");
+  return join5(resolve8(store), "objects", id.slice(0, 2), id);
+}
+async function syncDirectory(path) {
+  const file = await open(path, "r");
+  try {
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+}
+async function ensureDirectory(path) {
+  try {
+    await mkdir2(path, { mode: 448 });
+    await syncDirectory(dirname3(path));
+  } catch (cause) {
+    if (cause.code === "EEXIST")
+      return;
+    if (cause.code !== "ENOENT")
+      throw cause;
+    await ensureDirectory(dirname3(path));
+    await ensureDirectory(path);
   }
 }
+async function atomicWrite(path, content, immutable = false) {
+  await ensureDirectory(dirname3(path));
+  const temporary = `${path}.${randomUUID2()}.tmp`;
+  const file = await open(temporary, "wx", 384);
+  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(dirname3(path));
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+async function putObject(store, content) {
+  const id = digest2(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 (digest2(existing) !== id)
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Stored content is corrupt.");
+  return id;
+}
+async function getObject(store, id, derived) {
+  let bytes;
+  try {
+    bytes = await readFile4(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 (digest2(bytes) !== id)
+    throw new TrajectoriesError("INTEGRITY_ERROR", `Content hash mismatch ${id}.`);
+  return bytes;
+}
+async function withSessionLock(store, id, action) {
+  const locks = join5(resolve8(store), "locks");
+  await ensureDirectory(locks);
+  const path = join5(locks, safeId(id));
+  try {
+    await mkdir2(path, { mode: 448 });
+  } 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);
+  }
+}
+var digest2 = (content) => createHash9("sha256").update(content).digest("hex");
+var init_log_io = __esm(() => {
+  init_log_types();
+});
+
+// src/types.ts
+var NATIVE_HARNESSSES = ["claude-code", "codex", "pi", "omp", "opencode", "grok-build", "cursor", "deepagents", "github-copilot", "cline", "fx"];
+var HARNESSES = [...NATIVE_HARNESSSES, "atif"];
+function isNativeHarness(value) {
+  return NATIVE_HARNESSSES.includes(value);
+}
+
+// src/index.ts
+init_log_types();
+
 // src/convert.ts
 import { createHash as createHash8 } from "node:crypto";
 import { readFile as readFile3, mkdir, writeFile, realpath } from "node:fs/promises";
@@ -5064,6 +5203,47 @@ function normalizeGrokBuild(transcript, metadata = {}) {
   };
 }
 
+// src/readers/atif.ts
+var STEP_RECORD_ID = /^(?:trajectory:.+:)?step:([1-9]\d*)$/;
+var isObject4 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var present = (value) => value !== undefined && value !== null;
+function injectedOrigin(step) {
+  if (step.source !== "user")
+    return;
+  const role = isObject4(step.extra) ? step.extra.role : undefined;
+  return typeof role === "string" && role ? "harness" : undefined;
+}
+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 = isObject4(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 (!isObject4(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 };
+}
+
 // src/readers/cursor.ts
 import { createHash as createHash5 } from "node:crypto";
 import { readFile as readFile2, stat } from "node:fs/promises";
@@ -6830,7 +7010,7 @@ function finalizeSnapshot(input, archived, clineCompaction = false) {
   const invalid = archived.diagnostics.filter((d) => d.code === "invalid_json_line" || d.code === "non_object_json_line");
   if (invalid.length)
     throw new Error(`Invalid native transcript: ${invalid.map((d) => d.message).join("; ")}`);
-  const canonical = input.harness === "pi" ? projectPiProviderContext(raw, archived) : archived;
+  const canonical = input.harness === "pi" ? projectPiProviderContext(raw, archived) : input.harness === "atif" ? enrichAtifCanonical(raw, archived) : archived;
   const metadata = provenance(input.harness, canonical);
   if (input.nativeSessionId && metadata.nativeSessionId !== input.nativeSessionId)
     throw new Error("Selected native session does not match source provenance.");
@@ -6968,12 +7148,30 @@ function assertSnapshot(snapshot) {
     if (sha2562(attachment.content) !== attachment.sha256)
       throw new Error("Snapshot attachment integrity check failed.");
   }
+  for (const annotation of snapshot.annotations ?? []) {
+    if (typeof annotation.kind !== "string" || !annotation.kind || typeof annotation.content !== "string" || sha2562(annotation.content) !== annotation.sha256)
+      throw new Error("Snapshot annotation integrity check failed.");
+  }
   for (const record of canonical.records) {
     if (sha2562(record.record_json) !== record.record_hash)
       throw new Error("Snapshot canonical record integrity check failed.");
   }
   validateTranscript(canonical.records.map((r) => JSON.parse(r.record_json)));
 }
+function annotateSnapshot(snapshot, annotation) {
+  assertSnapshot(snapshot);
+  if (typeof annotation?.kind !== "string" || !annotation.kind.trim())
+    throw new Error("Snapshot annotation requires a kind.");
+  if (typeof annotation.content !== "string")
+    throw new Error("Snapshot annotation content must be a string.");
+  const entry = {
+    kind: annotation.kind,
+    content: annotation.content,
+    sha256: sha2562(annotation.content),
+    createdAt: new Date().toISOString()
+  };
+  return { ...snapshot, annotations: [...snapshot.annotations ?? [], entry] };
+}
 function assertPortableSnapshot(snapshot) {
   assertSnapshot(snapshot);
   const clineCompaction = snapshot.source.harness === "cline" && snapshot.attachments?.some((attachment) => attachment.name.endsWith(".compaction.json") || attachment.name.endsWith(".json") && JSON.parse(attachment.content).compaction_path);
@@ -6998,8 +7196,9 @@ function convertManaged(snapshot, target, options, entropySeed, records) {
 }
 function convertWithEntropy(snapshot, target, options, entropy, retainedRecords) {
   assertPortableSnapshot(snapshot);
-  if (!HARNESSES.includes(target))
-    throw new Error(`Unsupported target: ${target}`);
+  if (!isNativeHarness(target)) {
+    throw new Error(HARNESSES.includes(target) ? `Unsupported target: ${target} is a read-only interchange format.` : `Unsupported target: ${target}`);
+  }
   if (!isAbsolute2(options.cwd) || !isAbsolute2(options.directory))
     throw new Error("cwd and directory must be absolute paths.");
   const records = retainedRecords ?? snapshot.canonical.records.map((r) => JSON.parse(r.record_json));
@@ -7040,119 +7239,13 @@ async function writeSnapshot(snapshot, target, options) {
   await writeNativeExport(output, options.directory);
   return output;
 }
-// src/log-io.ts
-import { createHash as createHash9, randomUUID as randomUUID2 } from "node:crypto";
-import { link, mkdir as mkdir2, open, readFile as readFile4, rename, rm } from "node:fs/promises";
-import { dirname as dirname3, join as join5, resolve as resolve8 } from "node:path";
-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;
-}
-var digest2 = (content) => createHash9("sha256").update(content).digest("hex");
-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;
-}
-function objectPath(store, id) {
-  if (!/^[a-f0-9]{64}$/.test(id))
-    throw new TrajectoriesError("INTEGRITY_ERROR", "Invalid content reference.");
-  return join5(resolve8(store), "objects", id.slice(0, 2), id);
-}
-async function syncDirectory(path) {
-  const file = await open(path, "r");
-  try {
-    await file.sync();
-  } finally {
-    await file.close();
-  }
-}
-async function ensureDirectory(path) {
-  try {
-    await mkdir2(path, { mode: 448 });
-    await syncDirectory(dirname3(path));
-  } catch (cause) {
-    if (cause.code === "EEXIST")
-      return;
-    if (cause.code !== "ENOENT")
-      throw cause;
-    await ensureDirectory(dirname3(path));
-    await ensureDirectory(path);
-  }
-}
-async function atomicWrite(path, content, immutable = false) {
-  await ensureDirectory(dirname3(path));
-  const temporary = `${path}.${randomUUID2()}.tmp`;
-  const file = await open(temporary, "wx", 384);
-  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(dirname3(path));
-  } finally {
-    await rm(temporary, { force: true });
-  }
-}
-async function putObject(store, content) {
-  const id = digest2(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 (digest2(existing) !== id)
-    throw new TrajectoriesError("INTEGRITY_ERROR", "Stored content is corrupt.");
-  return id;
-}
-async function getObject(store, id, derived) {
-  let bytes;
-  try {
-    bytes = await readFile4(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 (digest2(bytes) !== id)
-    throw new TrajectoriesError("INTEGRITY_ERROR", `Content hash mismatch ${id}.`);
-  return bytes;
-}
-async function withSessionLock(store, id, action) {
-  const locks = join5(resolve8(store), "locks");
-  await ensureDirectory(locks);
-  const path = join5(locks, safeId(id));
-  try {
-    await mkdir2(path, { mode: 448 });
-  } 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);
-  }
-}
+// src/log.ts
+init_log_types();
+init_log_io();
 
 // src/log-state.ts
+init_log_types();
+init_log_io();
 import { open as open2, readFile as readFile5, readdir } from "node:fs/promises";
 import { dirname as dirname4, join as join6, resolve as resolve9 } from "node:path";
 var logPath = (store, id) => join6(resolve9(store), "logs", `${safeId(id)}.jsonl`);
@@ -7240,10 +7333,14 @@ async function publishFrame(store, body) {
 }
 
 // src/log-recovery.ts
+init_log_types();
+init_log_io();
 import { readFile as readFile6 } from "node:fs/promises";
 import { join as join8, resolve as resolve11 } from "node:path";
 
 // src/log-content.ts
+init_log_io();
+init_log_types();
 function textChunks(text) {
   const bytes = Buffer.from(text), chunks = [];
   let start = 0, rolling = 0;
@@ -7320,9 +7417,15 @@ async function getText(store, ref, derived) {
 }
 
 // src/log-read.ts
+init_log_types();
+init_log_io();
 import { readdir as readdir2 } from "node:fs/promises";
 import { join as join7, resolve as resolve10 } from "node:path";
 
+// src/log-records.ts
+init_log_io();
+init_log_types();
+
 // src/portable.ts
 function canonicalJson2(value) {
   if (Array.isArray(value))
@@ -7676,10 +7779,13 @@ async function recoverEvidence(store, evidence, frames, ownId, cache = recoveryC
 }
 
 // src/log-stage.ts
+init_log_types();
 import { readFile as readFile8, realpath as realpath3 } from "node:fs/promises";
 import { resolve as resolve13 } from "node:path";
+init_log_io();
 
 // src/log-baseline.ts
+init_log_types();
 var semantic = (record) => portableConversationTokens([record])[0]?.semantic;
 var isTool = (record) => record.role === "tool" || record.role === "assistant" && ("tool_calls" in record);
 var omittedRole = (record) => ["system", "reasoning", "observation"].includes(record.role);
@@ -7971,7 +8077,7 @@ async function stageCapture(store, snapshot, requested) {
       allowInitialSystem: baseline?.firstTarget,
       origin: { harness: binding.harness, ...binding.nativeSessionId ? { nativeSessionId: binding.nativeSessionId } : {}, bindingId: binding.id }
     });
-    const { raw, canonical, attachments, ...header } = snapshot;
+    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) ? {
@@ -8027,6 +8133,8 @@ async function validateStageBacking(store, stage, frames) {
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { lstat, realpath as realpath4 } from "node:fs/promises";
 import { resolve as resolve14 } from "node:path";
+init_log_types();
+init_log_io();
 var manifestOf = (native) => ({ ...native, files: native.files.map((file) => ({
   path: file.path,
   sha256: sha2562(file.content),
@@ -8040,8 +8148,9 @@ async function preparedReceipt(store, frame) {
 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 realpath4(resolve14(requested.write.cwd));
@@ -8202,8 +8311,10 @@ async function appendCapture(store, id, input, options) {
   return commitCapture(store, ref, stage);
 }
 // src/migrate.ts
+init_log_types();
 import { lstat as lstat2, mkdir as mkdir4, readFile as readFile9, realpath as realpath5 } from "node:fs/promises";
 import { dirname as dirname5, join as join10, resolve as resolve15 } from "node:path";
+init_log_io();
 function validateSnapshot(snapshot) {
   try {
     assertPortableSnapshot(snapshot);
@@ -8379,15 +8490,983 @@ async function migrateLegacyStore(source, destination, options) {
     throw new TrajectoriesError("INTEGRITY_ERROR", cause instanceof Error ? cause.message : "Legacy migration failed; preserve the source and partial destination.", { cause });
   }
 }
+// src/shared.ts
+init_log_types();
+init_log_io();
+import { timingSafeEqual } from "node:crypto";
+
+// src/shared-managed.ts
+init_log_types();
+init_log_io();
+import { open as open3, readFile as readFile10, rm as rm3 } from "node:fs/promises";
+import { dirname as dirname6, isAbsolute as isAbsolute4 } from "node:path";
+function fail5(message) {
+  throw new TrajectoriesError("INTEGRITY_ERROR", message);
+}
+var equal = (a, b) => stableJson(a) === stableJson(b);
+function hash2(value) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+    fail5("Invalid shared content hash.");
+}
+async function managedObjectIds(store, frames, lineage) {
+  const ids = new Set;
+  async function object(id, derived) {
+    hash2(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)
+      fail5("Missing text reference.");
+    await getText(store, ref, derived);
+    const visiting = new Set;
+    async function visit(part) {
+      if (!part || visiting.has(part.id))
+        fail5("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)
+          fail5("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) {
+      hash2(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();
+}
+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)
+      fail5("Committed frame has no matching durable intent.");
+    intents.push({ intentId: frame.body.intentId, data });
+    if (frame.body.capture) {
+      const pointer = JSON.parse(await readFile10(capturePath(store, frame.body.capture.id), "utf8"));
+      if (pointer.object !== frame.body.stage)
+        fail5("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))
+    fail5("Invalid managed transfer.");
+  safeId(delta.sessionId);
+  hash2(delta.head);
+  if (expectedHead !== null)
+    hash2(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 || digest2(stableJson(frame.body)) !== frame.head)
+      fail5("Shared log chain is corrupt.");
+    hash2(frame.head);
+    hash2(frame.body.input);
+    safeId(frame.body.intentId);
+    if (intents.has(frame.body.intentId))
+      fail5("Repeated shared intent.");
+    intents.add(frame.body.intentId);
+    if (!isAbsolute4(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")
+      fail5("Invalid managed frame metadata.");
+    safeId(frame.body.binding.id);
+    checkpointLimits(frame.body.session.nativeCheckpoints);
+    if (frame.body.kind !== "capture" && frame.body.kind !== "binding")
+      fail5("Unknown managed frame kind.");
+    parent = frame.head;
+  }
+  if (parent !== delta.head)
+    fail5("Transfer head does not match its suffix.");
+  if (new Set(delta.objectIds).size !== delta.objectIds.length)
+    fail5("Duplicate shared object declaration.");
+  for (const id of delta.objectIds)
+    hash2(id);
+  if (delta.intents.length !== delta.frames.length || new Set(delta.intents.map((item) => item.intentId)).size !== delta.intents.length)
+    fail5("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)
+    fail5("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)
+      fail5("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)
+        fail5("Capture frame has inconsistent provenance.");
+      safeId(ref.id);
+      hash2(frame.body.stage);
+      if (delta.captures.find((item) => item.id === ref.id)?.object !== frame.body.stage)
+        fail5("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) {
+      fail5("Prepared binding frame has inconsistent retained input.");
+    }
+  }
+}
+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))
+    fail5("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)))
+    fail5("Initial capture session options differ.");
+  if (typeof stage.options.requireProgress !== "boolean")
+    fail5("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: digest2(snapshot.raw),
+    ...snapshot.source.nativeSessionId ? { nativeSessionId: snapshot.source.nativeSessionId } : {}
+  };
+  if (!equal(stage.ref.source, source))
+    fail5("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))
+    fail5("Capture diagnostics or native metadata differ from recovered evidence.");
+  const operation = frame.body.parent === null ? "create" : "append";
+  if (digest2(stableJson({ operation, options: stage.options, snapshot: snapshot.id })) !== stage.input)
+    fail5("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))
+    fail5("Capture records or context do not reproduce from native evidence.");
+}
+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))
+        fail5("Immutable session metadata changed.");
+      if (!combined.length && (frame.body.kind !== "capture" || frame.body.session.createdAt !== frame.body.time))
+        fail5("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 readFile10(path, "utf8")), { object: pointer.object }))
+            fail5("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.");
+      }
+      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 !== digest2(stableJson([frame.body.input, "native-entropy"]))))
+            fail5("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)
+            fail5("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))
+            fail5("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)
+        fail5("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(dirname6(path));
+        const file = await open3(path, "a", 384);
+        try {
+          await file.writeFile(delta.frames.map((frame) => stableJson(frame) + `
+`).join(""));
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await syncDirectory(dirname6(path));
+      }
+      return sessionOf(validated.at(-1));
+    } catch (error) {
+      if (!publicationStarted)
+        for (const path of createdPointers)
+          await rm3(path);
+      if (error instanceof TrajectoriesError)
+        throw error;
+      throw new TrajectoriesError("INTEGRITY_ERROR", "Shared history validation or publication failed.", { cause: error });
+    }
+  });
+}
+
+// src/shared-observed.ts
+init_log_types();
+import { readdir as readdir4, readFile as readFile11 } from "node:fs/promises";
+import { join as join11, resolve as resolve16 } from "node:path";
+init_log_io();
+function sharedObservationId(machineId, sessionId) {
+  safeId(machineId);
+  if (typeof sessionId !== "string" || !sessionId || sessionId.length > 4096)
+    throw new TrajectoriesError("INVALID_INPUT", "An indexed session identity is required.");
+  return digest2(stableJson([machineId, sessionId]));
+}
+var hash3 = (value) => {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid shared content identity.");
+  return value;
+};
+var observationPath = (store, id) => join11(resolve16(store), "observations", `${hash3(id)}.jsonl`);
+function assertSession(value) {
+  if (!value || typeof value !== "object" || typeof value.id !== "string" || !value.id || typeof value.source !== "string" || !value.source || typeof value.source_path !== "string" || typeof value.content_hash !== "string" || !Number.isSafeInteger(value.record_count) || value.record_count < 0 || typeof value.created_at !== "string" || typeof value.updated_at !== "string")
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid canonical observed session metadata.");
+  for (const key of ["title", "cwd", "model", "started_at", "ended_at"])
+    if (value[key] !== null && typeof value[key] !== "string")
+      throw new TrajectoriesError("INVALID_INPUT", `Invalid session ${key}.`);
+  for (const key of ["parent_session_id", "parent_tool_use_id", "agent_nickname", "thread_role"])
+    if (value[key] !== undefined && value[key] !== null && typeof value[key] !== "string")
+      throw new TrajectoriesError("INVALID_INPUT", `Invalid session ${key}.`);
+  if (value.content_hash_version !== undefined && ![1, 2].includes(value.content_hash_version))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid observed hash version.");
+  if (value.diagnostics !== undefined) {
+    if (!Array.isArray(value.diagnostics))
+      throw new TrajectoriesError("INVALID_INPUT", "Invalid observed diagnostics.");
+    const codes = new Set;
+    for (const item of value.diagnostics) {
+      if (!item || typeof item.code !== "string" || !item.code || codes.has(item.code) || !Number.isSafeInteger(item.occurrenceCount) || item.occurrenceCount < 0 || item.sample !== null && typeof item.sample !== "string" || item.firstSeenAt !== undefined && typeof item.firstSeenAt !== "string")
+        throw new TrajectoriesError("INVALID_INPUT", "Invalid observed diagnostic aggregate.");
+      codes.add(item.code);
+    }
+  }
+}
+function assertRecord(value, sessionId) {
+  if (!value || typeof value !== "object" || typeof value.id !== "string" || !value.id || value.session_id !== sessionId || typeof value.source_type !== "string" || typeof value.record_type !== "string" || typeof value.source_order_id !== "string" || !Number.isSafeInteger(value.component_index) || value.component_index < 0 || typeof value.record_hash !== "string" || typeof value.content_hash !== "string" || typeof value.record_json !== "string")
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid canonical observed record or session identity.");
+  for (const key of [
+    "content",
+    "tool_call_id",
+    "tool_name",
+    "tool_arguments_json",
+    "tool_result_json",
+    "record_timestamp",
+    "source_timestamp",
+    "stable_source_record_id",
+    "source_identity_kind"
+  ])
+    if (value[key] !== null && typeof value[key] !== "string")
+      throw new TrajectoriesError("INVALID_INPUT", `Invalid record ${key}.`);
+  if (![null, 0, 1].includes(value.tool_result_ok))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid tool outcome.");
+  if (value.source_identity_kind !== null && !["native", "location", "content", "synthetic"].includes(value.source_identity_kind))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid source identity kind.");
+  for (const key of ["native_session_id", "binding_id"])
+    if (value[key] !== undefined && value[key] !== null && typeof value[key] !== "string")
+      throw new TrajectoriesError("INVALID_INPUT", "Invalid native lineage identity.");
+  let parsed;
+  try {
+    parsed = JSON.parse(value.record_json);
+  } catch {
+    throw new TrajectoriesError("INVALID_INPUT", "Malformed canonical record JSON.");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    throw new TrajectoriesError("INVALID_INPUT", "Canonical record JSON must be an object.");
+  try {
+    validateTranscript([parsed], { partial: true });
+  } catch {
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid normalized canonical record.");
+  }
+  const record = parsed;
+  if (value.record_type !== (record.role === "assistant" && record.tool_calls ? "assistant-tool-call" : record.role) || digest2(value.record_json) !== value.record_hash)
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Canonical record type or digest disagrees with its payload.");
+}
+function assertObservedSummary(value, id) {
+  if (!value || typeof value !== "object")
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid shared observation.");
+  assertSession(value.session);
+  hash3(value.head);
+  if (id !== undefined && value.id !== id || value.id !== sharedObservationId(value.machineId, value.session.id))
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Shared observation identity mismatch.");
+}
+function assertObservedManifest(value, id) {
+  assertObservedSummary(value, id);
+  if (!Array.isArray(value.recordObjects))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid shared record manifest.");
+  const ids = new Set;
+  for (const ref of value.recordObjects) {
+    if (!ref || typeof ref.id !== "string" || !ref.id || ids.has(ref.id))
+      throw new TrajectoriesError("INVALID_INPUT", "Invalid shared record identities.");
+    ids.add(ref.id);
+    hash3(ref.object);
+  }
+  if (ids.size !== value.session.record_count)
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Shared manifest count mismatch.");
+}
+function assertObservedState(value, id) {
+  assertObservedSummary(value, id);
+  if (!Array.isArray(value.records))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid shared canonical records.");
+  const ids = new Set;
+  for (const record of value.records) {
+    assertRecord(record, value.session.id);
+    if (ids.has(record.id))
+      throw new TrajectoriesError("INVALID_INPUT", "Duplicate shared canonical record.");
+    ids.add(record.id);
+  }
+  if (ids.size !== value.session.record_count)
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Shared record count mismatch.");
+}
+async function frames(store, id) {
+  let text;
+  try {
+    text = await readFile11(observationPath(store, id), "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    throw error;
+  }
+  if (!text.endsWith(`
+`))
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Partial observed-history log.");
+  const output = [];
+  for (const line of text.trimEnd().split(`
+`)) {
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch {
+      throw new TrajectoriesError("INTEGRITY_ERROR", "Invalid observed-history JSON.");
+    }
+    const body = frame?.body;
+    if (!body || body.version !== 1 || body.id !== id || sharedObservationId(body.machineId, body.sessionId) !== id || body.parent !== (output.at(-1)?.head ?? null) || digest2(stableJson(body)) !== frame.head || !Array.isArray(body.set) || !Array.isArray(body.remove))
+      throw new TrajectoriesError("INTEGRITY_ERROR", "Invalid observed-history chain.");
+    output.push(frame);
+  }
+  return output;
+}
+async function materialize(store, id, history) {
+  const current = history.at(-1);
+  if (!current)
+    throw new TrajectoriesError("NOT_FOUND", "Shared observed session not found.");
+  const refs = new Map;
+  for (const { body } of history) {
+    for (const key of body.remove)
+      refs.delete(key);
+    for (const item of body.set)
+      refs.set(item.id, hash3(item.object));
+  }
+  const session = JSON.parse((await getObject(store, hash3(current.body.sessionObject))).toString());
+  assertSession(session);
+  if (session.id !== current.body.sessionId || session.record_count !== refs.size)
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Observed session metadata disagrees with its record view.");
+  return {
+    id,
+    head: current.head,
+    machineId: current.body.machineId,
+    session,
+    recordObjects: [...refs].map(([recordId, object]) => ({ id: recordId, object }))
+  };
+}
+async function getObservedManifest(store, id) {
+  return materialize(store, id, await frames(store, id));
+}
+async function readObservedHistory(store, id) {
+  const { recordObjects, ...summary } = await getObservedManifest(store, id);
+  const records = [];
+  for (const ref of recordObjects) {
+    const record = JSON.parse((await getObject(store, ref.object)).toString());
+    assertRecord(record, summary.session.id);
+    if (record.id !== ref.id)
+      throw new TrajectoriesError("INTEGRITY_ERROR", "Observed record identity changed.");
+    records.push(record);
+  }
+  records.sort((a, b) => a.source_order_id < b.source_order_id ? -1 : a.source_order_id > b.source_order_id ? 1 : a.component_index - b.component_index || a.id.localeCompare(b.id));
+  return { ...summary, records };
+}
+async function listObservedHistories(store) {
+  let names;
+  try {
+    names = await readdir4(join11(resolve16(store), "observations"));
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return [];
+    throw error;
+  }
+  const output = [];
+  for (const name of names.sort()) {
+    if (!/^[a-f0-9]{64}\.jsonl$/.test(name))
+      continue;
+    const { recordObjects, ...summary } = await getObservedManifest(store, name.slice(0, -6));
+    output.push(summary);
+  }
+  return output;
+}
+async function commitObservedDelta(store, delta) {
+  if (!delta || delta.version !== 1 || delta.id !== sharedObservationId(delta.machineId, delta.sessionId) || delta.parent !== null && hash3(delta.parent) !== delta.parent || !Array.isArray(delta.set) || !Array.isArray(delta.remove))
+    throw new TrajectoriesError("INVALID_INPUT", "Invalid observed-history delta.");
+  hash3(delta.sessionObject);
+  const keys = new Set;
+  for (const item of delta.set) {
+    if (!item || typeof item.id !== "string" || !item.id || keys.has(item.id))
+      throw new TrajectoriesError("INVALID_INPUT", "Duplicate or invalid record identity.");
+    keys.add(item.id);
+    hash3(item.object);
+  }
+  for (const key of delta.remove) {
+    if (typeof key !== "string" || !key || keys.has(key))
+      throw new TrajectoriesError("INVALID_INPUT", "Duplicate or contradictory record changes.");
+    keys.add(key);
+  }
+  return withSessionLock(store, delta.id, async () => {
+    const history = await frames(store, delta.id);
+    const head = digest2(stableJson(delta));
+    if (history.at(-1)?.head === head) {
+      const { recordObjects, ...summary } = await materialize(store, delta.id, history);
+      return summary;
+    }
+    if ((history.at(-1)?.head ?? null) !== delta.parent)
+      throw new TrajectoriesError("STALE_HEAD", "Shared observed history advanced; refresh before publishing.");
+    for (const item of delta.set) {
+      const record = JSON.parse((await getObject(store, item.object)).toString());
+      assertRecord(record, delta.sessionId);
+      if (record.id !== item.id)
+        throw new TrajectoriesError("INTEGRITY_ERROR", "Observed record reference has a different identity.");
+    }
+    const prospective = [...history, { head, body: delta }];
+    const manifest = await materialize(store, delta.id, prospective);
+    const { open } = await import("node:fs/promises");
+    await Promise.resolve().then(() => init_log_io());
+    const path = observationPath(store, delta.id);
+    await ensureDirectory(join11(resolve16(store), "observations"));
+    const file = await open(path, "a", 384);
+    try {
+      await file.writeFile(stableJson({ head, body: delta }) + `
+`);
+      await file.sync();
+    } finally {
+      await file.close();
+    }
+    await syncDirectory(join11(resolve16(store), "observations"));
+    const { recordObjects, ...summary } = manifest;
+    return summary;
+  });
+}
+async function prepareObservedHistory(input, previous) {
+  assertSession(input.session);
+  const id = sharedObservationId(input.machineId, input.session.id);
+  if (previous)
+    assertObservedManifest(previous, id);
+  if (previous && (previous.id !== id || previous.machineId !== input.machineId || previous.session.id !== input.session.id))
+    throw new TrajectoriesError("INTEGRITY_ERROR", "Remote observation identity mismatch.");
+  const prior = new Map(previous?.recordObjects.map((item) => [item.id, item.object]) ?? []);
+  const objects = new Map;
+  const add = (value) => {
+    const bytes = Buffer.from(stableJson(value));
+    const key = digest2(bytes);
+    objects.set(key, bytes);
+    return key;
+  };
+  const sessionObject = add(input.session);
+  const seen = new Set;
+  const set = [];
+  for (const record of input.records) {
+    assertRecord(record, input.session.id);
+    if (seen.has(record.id))
+      throw new TrajectoriesError("INVALID_INPUT", "Duplicate canonical record ID.");
+    seen.add(record.id);
+    const key = digest2(stableJson(record));
+    if (prior.get(record.id) !== key) {
+      add(record);
+      set.push({ id: record.id, object: key });
+    }
+  }
+  if (input.session.record_count !== seen.size)
+    throw new TrajectoriesError("INVALID_INPUT", "Session record count disagrees with canonical records.");
+  const remove = [...prior.keys()].filter((key) => !seen.has(key));
+  if (previous && !set.length && !remove.length && stableJson(previous.session) === stableJson(input.session))
+    return { delta: null, objects: new Map, changedRecords: 0, removedRecords: 0 };
+  return { delta: {
+    version: 1,
+    id,
+    parent: previous?.head ?? null,
+    machineId: input.machineId,
+    sessionId: input.session.id,
+    sessionObject,
+    set,
+    remove
+  }, objects, changedRecords: set.length, removedRecords: remove.length };
+}
+
+// src/shared.ts
+var 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);
+}
+var json2 = (value, status = 200) => new Response(JSON.stringify(value), {
+  status,
+  headers: { "content-type": "application/json", "cache-control": "no-store" }
+});
+var decode3 = (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.");
+}
+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 json2({ 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 = decode3(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 json2({ missing });
+      }
+      if (path === "/v1/objects/batch" && request.method === "POST") {
+        const items = decode3(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 || digest2(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 json2({ 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 (digest2(bytes) !== key)
+            throw new TrajectoriesError("INTEGRITY_ERROR", "Shared object does not match its declared digest.");
+          await putObject(options.store, bytes);
+          return json2({ object: key });
+        }
+        let bytes;
+        try {
+          bytes = await getObject(options.store, key);
+        } catch (error) {
+          if (missingObject(error))
+            return json2({ 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 json2(await listObservedHistories(options.store));
+      const observed = /^\/v1\/observed\/([a-f0-9]{64})$/.exec(path);
+      if (observed && request.method === "GET")
+        return json2(url.searchParams.get("manifest") === "1" ? await getObservedManifest(options.store, observed[1]) : await readObservedHistory(options.store, observed[1]));
+      if (observed && request.method === "POST") {
+        const delta = decode3(await boundedBody(request, limit));
+        if (delta?.id !== observed[1])
+          throw new TrajectoriesError("INVALID_INPUT", "Shared route and observation identity differ.");
+        return json2(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 json2(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 json2(await getSession(options.store, managed[1]));
+        const after = url.searchParams.get("after");
+        return json2(await exportManagedDelta(options.store, managed[1], { afterHead: after }));
+      }
+      if (managed && request.method === "POST") {
+        const input = decode3(await boundedBody(request, limit));
+        if (input?.delta?.sessionId !== managed[1])
+          throw new TrajectoriesError("INVALID_INPUT", "Shared route and managed identity differ.");
+        return json2(await importManagedDelta(options.store, input.delta, { expectedHead: input.expectedHead }));
+      }
+      return json2({ 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 json2({ error: { code, message: error instanceof TrajectoriesError ? error.message : "Shared history could not be validated." } }, status);
+    }
+  };
+}
+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 = decode3(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) => decode3(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 = decode3(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 = decode3(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 (digest2(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 = decode3(await boundedBody(response, MAX_BYTES));
+      assertObservedSummary(committed, id);
+      if (committed.head !== digest2(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 = decode3(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 (digest2(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 };
+    }
+  };
+}
 export {
   HARNESSES,
+  NATIVE_HARNESSSES,
   TrajectoriesError,
+  annotateSnapshot,
   appendCapture,
   assertPortableSnapshot,
   assertSnapshot,
   assertSnapshotContinuation,
   convert,
   createSession,
+  createSharedClient,
+  createSharedHandler,
   getHeadMetadata,
   getNativeBinding,
   getSession,
@@ -8395,6 +9474,7 @@ export {
   migrateLegacyStore,
   readSession,
   readSnapshot,
+  sharedObservationId,
   stageCapture,
   switchSession,
   writeNativeExport,