@evo-dev/core 0.0.1-alpha.11 → 0.0.1-alpha.13

package/src/evolution/imports/storage.ts

@@ -0,0 +1,952 @@
+import { randomUUID } from "node:crypto";
+import type { Stats } from "node:fs";
+import { chmod, link, lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import type { FileHandle } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  createTrajectoryImportIndexDigest,
+  createTrajectoryImportSnapshotId,
+  stableTrajectoryImportJson,
+} from "./diff.ts";
+import {
+  type ResolveTrajectoryImportSourcePathsInput,
+  type TrajectoryImportPaths,
+  type TrajectoryImportSourcePaths,
+  resolveTrajectoryImportPaths,
+  resolveTrajectoryImportSourcePaths,
+} from "./paths.ts";
+import type {
+  CanonicalImportRecordType,
+  CanonicalImportSourceIdentityKind,
+  TrajectoryImportGenerationContractV1,
+  TrajectoryImportIndexRecordV1,
+  TrajectoryImportManifestV1,
+  TrajectoryImportMaterializationProgressV1,
+  TrajectoryImportPreviousSnapshotV1,
+  TrajectoryImportReceiptV1,
+  TrajectoryImportSource,
+} from "./types.ts";
+
+const PRIVATE_DIRECTORY_MODE = 0o700;
+const PRIVATE_FILE_MODE = 0o600;
+const DEFAULT_LOCK_WAIT_MS = 2_000;
+const DEFAULT_LOCK_RETRY_MS = 10;
+const DEFAULT_LOCK_STALE_MS = 120_000;
+const DEFAULT_LOCK_HEARTBEAT_MS = 15_000;
+
+const SOURCES = new Set<TrajectoryImportSource>([
+  "claude-code",
+  "codex",
+  "hermes",
+  "letta-code",
+  "openclaw",
+  "openhands",
+]);
+const RECORD_TYPES = new Set<CanonicalImportRecordType>([
+  "meta",
+  "user",
+  "reasoning",
+  "assistant",
+  "assistant-tool-call",
+  "tool",
+]);
+const IDENTITY_KINDS = new Set<CanonicalImportSourceIdentityKind>([
+  "native",
+  "location",
+  "content",
+  "synthetic",
+]);
+
+export interface TrajectoryImportSourceLock {
+  ownerPath: string;
+  recoveryPath: string;
+  ownerToken: string;
+  handle: FileHandle;
+  timer: ReturnType<typeof setInterval>;
+  heartbeat: Promise<void> | null;
+  stopped: boolean;
+  lost: boolean;
+}
+
+export interface AcquireTrajectoryImportSourceLockOptions {
+  waitMs?: number;
+  retryMs?: number;
+  staleAfterMs?: number;
+  heartbeatMs?: number;
+}
+
+export async function ensurePrivateTrajectoryImportDirectory(path: string): Promise<void> {
+  await mkdir(path, { recursive: true, mode: PRIVATE_DIRECTORY_MODE });
+  const current = await lstat(path);
+  if (current.isSymbolicLink() || !current.isDirectory()) {
+    throw new Error("Trajectory import private state path must be a real directory.");
+  }
+  await chmod(path, PRIVATE_DIRECTORY_MODE);
+}
+
+export async function ensureTrajectoryImportStageDirectories(
+  paths: TrajectoryImportPaths,
+): Promise<void> {
+  for (const directory of [
+    paths.rootDir,
+    paths.projectDir,
+    paths.sourceDir,
+    paths.lockDir,
+    paths.generationsDir,
+    paths.generationDir,
+    paths.snapshotsDir,
+    paths.snapshotDir,
+    paths.receiptsDir,
+    paths.previewReceiptDir,
+  ]) {
+    await ensurePrivateTrajectoryImportDirectory(directory);
+  }
+}
+
+export async function acquireTrajectoryImportSourceLock(
+  paths: TrajectoryImportSourcePaths,
+  options: AcquireTrajectoryImportSourceLockOptions = {},
+): Promise<TrajectoryImportSourceLock> {
+  const waitMs = normalizeDuration("waitMs", options.waitMs, DEFAULT_LOCK_WAIT_MS, true);
+  const retryMs = normalizeDuration("retryMs", options.retryMs, DEFAULT_LOCK_RETRY_MS, false);
+  const staleAfterMs = normalizeDuration(
+    "staleAfterMs",
+    options.staleAfterMs,
+    DEFAULT_LOCK_STALE_MS,
+    false,
+  );
+  const heartbeatMs = normalizeDuration(
+    "heartbeatMs",
+    options.heartbeatMs,
+    DEFAULT_LOCK_HEARTBEAT_MS,
+    false,
+  );
+  if (heartbeatMs >= staleAfterMs) {
+    throw new Error("Trajectory import lock heartbeat must be shorter than its stale timeout.");
+  }
+
+  for (const directory of [paths.rootDir, paths.projectDir, paths.sourceDir, paths.lockDir]) {
+    await ensurePrivateTrajectoryImportDirectory(directory);
+  }
+  const deadline = Date.now() + waitMs;
+
+  while (true) {
+    if (await pathExists(paths.lockRecoveryPath)) {
+      await recoverStaleControlFile(paths.lockRecoveryPath, staleAfterMs);
+      if (await pathExists(paths.lockRecoveryPath)) {
+        await waitForTrajectoryImportLock(deadline, retryMs);
+        continue;
+      }
+    }
+
+    const ownerToken = randomUUID();
+    let handle: FileHandle;
+    try {
+      handle = await createPrivateExclusiveFile(
+        paths.lockOwnerPath,
+        `${stableTrajectoryImportJson({
+          schemaVersion: 1,
+          kind: "trajectory-import-source-lock",
+          ownerToken,
+          createdAt: new Date().toISOString(),
+          pid: process.pid,
+        })}\n`,
+      );
+    } catch (error) {
+      if (!hasErrorCode(error, "EEXIST")) throw error;
+      const recovered = await recoverStaleTrajectoryImportOwner(paths, staleAfterMs);
+      if (!recovered) await waitForTrajectoryImportLock(deadline, retryMs);
+      continue;
+    }
+
+    const lock: TrajectoryImportSourceLock = {
+      ownerPath: paths.lockOwnerPath,
+      recoveryPath: paths.lockRecoveryPath,
+      ownerToken,
+      handle,
+      timer: undefined as unknown as ReturnType<typeof setInterval>,
+      heartbeat: null,
+      stopped: false,
+      lost: false,
+    };
+    lock.timer = setInterval(() => {
+      if (lock.stopped || lock.heartbeat !== null) return;
+      lock.heartbeat = heartbeatTrajectoryImportSourceLock(lock).finally(() => {
+        lock.heartbeat = null;
+      });
+    }, heartbeatMs);
+    lock.timer.unref?.();
+    return lock;
+  }
+}
+
+export async function withTrajectoryImportSourceLock<T>(
+  paths: TrajectoryImportSourcePaths,
+  operation: (lock: TrajectoryImportSourceLock) => Promise<T>,
+  options: AcquireTrajectoryImportSourceLockOptions = {},
+): Promise<T> {
+  const lock = await acquireTrajectoryImportSourceLock(paths, options);
+  try {
+    const result = await operation(lock);
+    await assertTrajectoryImportSourceLockOwned(lock);
+    return result;
+  } finally {
+    await releaseTrajectoryImportSourceLock(lock);
+  }
+}
+
+export async function assertTrajectoryImportSourceLockOwned(
+  lock: TrajectoryImportSourceLock,
+): Promise<void> {
+  if (lock.lost || !(await trajectoryImportSourceLockIsOwned(lock))) {
+    lock.lost = true;
+    throw new Error("Trajectory import source lock ownership was lost.");
+  }
+}
+
+export async function releaseTrajectoryImportSourceLock(
+  lock: TrajectoryImportSourceLock,
+): Promise<void> {
+  lock.stopped = true;
+  clearInterval(lock.timer);
+  await lock.heartbeat?.catch(() => undefined);
+  await lock.handle.close().catch(() => undefined);
+  const recoveryToken = randomUUID();
+  let recoveryHandle: FileHandle;
+  try {
+    recoveryHandle = await createPrivateExclusiveFile(
+      lock.recoveryPath,
+      `${stableTrajectoryImportJson({
+        schemaVersion: 1,
+        kind: "trajectory-import-lock-release",
+        ownerToken: recoveryToken,
+        createdAt: new Date().toISOString(),
+        pid: process.pid,
+      })}\n`,
+    );
+  } catch (error) {
+    if (hasErrorCode(error, "EEXIST")) return;
+    throw error;
+  }
+  try {
+    if (await trajectoryImportSourceLockIsOwned(lock)) {
+      await rm(lock.ownerPath, { force: true });
+    }
+  } finally {
+    await recoveryHandle.close().catch(() => undefined);
+    await removeOwnedControlFile(lock.recoveryPath, recoveryToken);
+  }
+}
+
+export async function readTrajectoryImportManifest(
+  input: ResolveTrajectoryImportSourcePathsInput,
+): Promise<TrajectoryImportManifestV1 | null> {
+  const paths = resolveTrajectoryImportSourcePaths(input);
+  return readTrajectoryImportManifestAtPath(paths.manifestPath);
+}
+
+export async function readTrajectoryImportManifestAtPath(
+  path: string,
+): Promise<TrajectoryImportManifestV1 | null> {
+  return readOptionalJson(path, parseTrajectoryImportManifest);
+}
+
+export async function writeTrajectoryImportManifest(
+  paths: TrajectoryImportSourcePaths,
+  manifest: TrajectoryImportManifestV1,
+): Promise<void> {
+  const normalized = parseTrajectoryImportManifest(manifest);
+  await writePrivateAtomicFile(paths.manifestPath, `${stableTrajectoryImportJson(normalized)}\n`);
+}
+
+export async function readTrajectoryImportIndex(
+  path: string,
+): Promise<TrajectoryImportIndexRecordV1[]> {
+  await assertRegularStateFile(path);
+  const content = await readFile(path, "utf8");
+  const lines = content.endsWith("\n") ? content.slice(0, -1).split("\n") : content.split("\n");
+  if (lines.length === 1 && lines[0] === "") return [];
+  const records = lines.map((line, ordinal) => {
+    if (line.trim() === "") {
+      throw new Error("Trajectory import index contains an empty record.");
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch {
+      throw new Error("Trajectory import index contains invalid JSON.");
+    }
+    return parseTrajectoryImportIndexRecord(value, ordinal);
+  });
+  validateTrajectoryImportIndexSet(records);
+  return records;
+}
+
+export async function writeImmutableTrajectoryImportIndex(
+  paths: TrajectoryImportPaths,
+  records: TrajectoryImportIndexRecordV1[],
+): Promise<{ created: boolean; digest: string; records: TrajectoryImportIndexRecordV1[] }> {
+  const normalized = records.map((record, ordinal) =>
+    parseTrajectoryImportIndexRecord(record, ordinal),
+  );
+  validateTrajectoryImportIndexSet(normalized);
+  const content = `${normalized.map(stableTrajectoryImportJson).join("\n")}\n`;
+  const created = await writePrivateImmutableFile(paths.recordIndexPath, content);
+  return {
+    created,
+    digest: createTrajectoryImportIndexDigest(normalized),
+    records: normalized,
+  };
+}
+
+export async function readTrajectoryImportReceipt(
+  path: string,
+): Promise<TrajectoryImportReceiptV1 | null> {
+  return readOptionalJson(path, parseTrajectoryImportReceipt);
+}
+
+export async function writeImmutableTrajectoryImportReceipt(
+  path: string,
+  receipt: TrajectoryImportReceiptV1,
+): Promise<{ created: boolean; receipt: TrajectoryImportReceiptV1 }> {
+  const normalized = parseTrajectoryImportReceipt(receipt);
+  const created = await writePrivateImmutableFile(
+    path,
+    `${stableTrajectoryImportJson(normalized)}\n`,
+  );
+  return { created, receipt: normalized };
+}
+
+export async function readTrajectoryImportMaterializationProgress(
+  path: string,
+): Promise<TrajectoryImportMaterializationProgressV1 | null> {
+  return readOptionalJson(path, parseTrajectoryImportMaterializationProgress);
+}
+
+export async function writeTrajectoryImportMaterializationProgress(
+  paths: TrajectoryImportPaths,
+  progress: TrajectoryImportMaterializationProgressV1,
+): Promise<void> {
+  const normalized = parseTrajectoryImportMaterializationProgress(progress);
+  await writePrivateAtomicFile(
+    paths.materializationPath,
+    `${stableTrajectoryImportJson(normalized)}\n`,
+  );
+}
+
+export async function readTrajectoryImportPreviousSnapshot(
+  input: ResolveTrajectoryImportSourcePathsInput,
+): Promise<TrajectoryImportPreviousSnapshotV1 | null> {
+  const manifest = await readTrajectoryImportManifest(input);
+  if (manifest === null) return null;
+  if (manifest.projectKey !== input.projectKey || manifest.sourceKey !== input.sourceKey) {
+    throw new Error("Trajectory import manifest does not match its state path.");
+  }
+  return readTrajectoryImportSnapshot({
+    ...input,
+    generationId: manifest.currentGenerationId,
+    snapshotId: manifest.currentSnapshotId,
+  });
+}
+
+export async function readTrajectoryImportSnapshot(
+  input: ResolveTrajectoryImportSourcePathsInput & {
+    generationId: string;
+    snapshotId: string;
+  },
+): Promise<TrajectoryImportPreviousSnapshotV1> {
+  const manifest = await readTrajectoryImportManifest(input);
+  if (manifest === null) {
+    throw new Error("Trajectory import manifest was not found.");
+  }
+  if (manifest.projectKey !== input.projectKey || manifest.sourceKey !== input.sourceKey) {
+    throw new Error("Trajectory import manifest does not match its state path.");
+  }
+  if (manifest.currentGenerationId !== input.generationId) {
+    throw new Error("Trajectory import snapshot generation does not match its manifest.");
+  }
+  const paths = resolveTrajectoryImportPaths({
+    ...input,
+    previewId: manifest.currentPreviewId,
+  });
+  const records = await readTrajectoryImportIndex(paths.recordIndexPath);
+  const digest = createTrajectoryImportIndexDigest(records);
+  if (input.snapshotId === manifest.currentSnapshotId && digest !== manifest.currentIndexDigest) {
+    throw new Error("Trajectory import current index digest does not match its manifest.");
+  }
+  if (createTrajectoryImportSnapshotId(input.generationId, records) !== input.snapshotId) {
+    throw new Error("Trajectory import snapshot id does not match its index.");
+  }
+  return {
+    sourceKey: manifest.sourceKey,
+    generationId: input.generationId,
+    initialInputFingerprint: manifest.initialInputFingerprint,
+    generationContract: manifest.generationContract,
+    snapshotId: input.snapshotId,
+    records,
+  };
+}
+
+async function heartbeatTrajectoryImportSourceLock(
+  lock: TrajectoryImportSourceLock,
+): Promise<void> {
+  if (!(await trajectoryImportSourceLockIsOwned(lock))) {
+    lock.lost = true;
+    return;
+  }
+  try {
+    const now = new Date();
+    await lock.handle.utimes(now, now);
+    if (!(await trajectoryImportSourceLockIsOwned(lock))) lock.lost = true;
+  } catch {
+    lock.lost = true;
+  }
+}
+
+async function trajectoryImportSourceLockIsOwned(
+  lock: TrajectoryImportSourceLock,
+): Promise<boolean> {
+  try {
+    const value = JSON.parse(await readFile(lock.ownerPath, "utf8")) as {
+      ownerToken?: unknown;
+    };
+    return value.ownerToken === lock.ownerToken;
+  } catch {
+    return false;
+  }
+}
+
+async function recoverStaleTrajectoryImportOwner(
+  paths: TrajectoryImportSourcePaths,
+  staleAfterMs: number,
+): Promise<boolean> {
+  const observed = await lstat(paths.lockOwnerPath).catch(() => null);
+  if (observed === null || !isStale(observed, staleAfterMs)) return observed === null;
+
+  const recoveryToken = randomUUID();
+  let recoveryHandle: FileHandle;
+  try {
+    recoveryHandle = await createPrivateExclusiveFile(
+      paths.lockRecoveryPath,
+      `${stableTrajectoryImportJson({
+        schemaVersion: 1,
+        kind: "trajectory-import-lock-recovery",
+        ownerToken: recoveryToken,
+        createdAt: new Date().toISOString(),
+        pid: process.pid,
+      })}\n`,
+    );
+  } catch (error) {
+    if (hasErrorCode(error, "EEXIST")) return false;
+    throw error;
+  }
+
+  try {
+    const current = await lstat(paths.lockOwnerPath).catch(() => null);
+    if (
+      current === null ||
+      !sameFileIdentity(observed, current) ||
+      !isStale(current, staleAfterMs)
+    ) {
+      return current === null;
+    }
+    const quarantinePath = join(
+      paths.lockDir,
+      `.owner.stale-${recoveryToken}-${randomUUID()}.json`,
+    );
+    try {
+      await rename(paths.lockOwnerPath, quarantinePath);
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) return true;
+      throw error;
+    }
+    const moved = await lstat(quarantinePath);
+    if (!sameFileIdentity(current, moved)) {
+      await restoreQuarantinedLock(quarantinePath, paths.lockOwnerPath);
+      return false;
+    }
+    await rm(quarantinePath, { force: true });
+    return true;
+  } finally {
+    await recoveryHandle.close().catch(() => undefined);
+    await removeOwnedControlFile(paths.lockRecoveryPath, recoveryToken);
+  }
+}
+
+async function recoverStaleControlFile(path: string, staleAfterMs: number): Promise<void> {
+  const observed = await lstat(path).catch(() => null);
+  if (observed === null || !isStale(observed, staleAfterMs)) return;
+  const quarantinePath = `${path}.stale-${randomUUID()}`;
+  try {
+    await rename(path, quarantinePath);
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return;
+    throw error;
+  }
+  const moved = await lstat(quarantinePath);
+  if (sameFileIdentity(observed, moved)) {
+    await rm(quarantinePath, { force: true });
+  } else {
+    await restoreQuarantinedLock(quarantinePath, path);
+  }
+}
+
+async function restoreQuarantinedLock(quarantinePath: string, targetPath: string): Promise<void> {
+  try {
+    await link(quarantinePath, targetPath);
+  } catch (error) {
+    if (!hasErrorCode(error, "EEXIST")) throw error;
+  } finally {
+    await rm(quarantinePath, { force: true });
+  }
+}
+
+async function removeOwnedControlFile(path: string, ownerToken: string): Promise<void> {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8")) as { ownerToken?: unknown };
+    if (value.ownerToken === ownerToken) await rm(path, { force: true });
+  } catch {
+    // A missing or replaced recovery claim is not ours to remove.
+  }
+}
+
+async function waitForTrajectoryImportLock(deadline: number, retryMs: number): Promise<void> {
+  if (Date.now() >= deadline) {
+    throw new Error("Trajectory import source lock is busy.");
+  }
+  await new Promise<void>((resolvePromise) => setTimeout(resolvePromise, retryMs));
+}
+
+async function writePrivateImmutableFile(path: string, content: string): Promise<boolean> {
+  await ensurePrivateTrajectoryImportDirectory(dirname(path));
+  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+  let handle: FileHandle | null = null;
+  try {
+    handle = await createPrivateExclusiveFile(temporaryPath, content);
+    await handle.close();
+    handle = null;
+    try {
+      await link(temporaryPath, path);
+      await chmod(path, PRIVATE_FILE_MODE);
+      return true;
+    } catch (error) {
+      if (!hasErrorCode(error, "EEXIST")) throw error;
+      await assertRegularStateFile(path);
+      const existing = await readFile(path, "utf8");
+      if (existing !== content) {
+        throw new Error("Trajectory import immutable state digest conflict.");
+      }
+      await chmod(path, PRIVATE_FILE_MODE);
+      return false;
+    }
+  } finally {
+    await handle?.close().catch(() => undefined);
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+async function writePrivateAtomicFile(path: string, content: string): Promise<void> {
+  await ensurePrivateTrajectoryImportDirectory(dirname(path));
+  const temporaryPath = join(dirname(path), `.${randomUUID()}.tmp`);
+  let handle: FileHandle | null = null;
+  try {
+    handle = await createPrivateExclusiveFile(temporaryPath, content);
+    await handle.close();
+    handle = null;
+    await rename(temporaryPath, path);
+    await chmod(path, PRIVATE_FILE_MODE);
+  } finally {
+    await handle?.close().catch(() => undefined);
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}
+
+async function createPrivateExclusiveFile(path: string, content: string): Promise<FileHandle> {
+  const handle = await open(path, "wx", PRIVATE_FILE_MODE);
+  try {
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    await chmod(path, PRIVATE_FILE_MODE);
+    return handle;
+  } catch (error) {
+    await handle.close().catch(() => undefined);
+    await rm(path, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+async function readOptionalJson<T>(path: string, parser: (value: unknown) => T): Promise<T | null> {
+  try {
+    await assertRegularStateFile(path);
+    const content = await readFile(path, "utf8");
+    return parser(JSON.parse(content));
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return null;
+    if (error instanceof SyntaxError) {
+      throw new Error("Trajectory import state contains invalid JSON.");
+    }
+    throw error;
+  }
+}
+
+async function assertRegularStateFile(path: string): Promise<void> {
+  const current = await lstat(path);
+  if (current.isSymbolicLink() || !current.isFile()) {
+    throw new Error("Trajectory import state path must be a regular file.");
+  }
+}
+
+function parseTrajectoryImportManifest(value: unknown): TrajectoryImportManifestV1 {
+  const record = expectRecord(value, "manifest");
+  const source = expectString(record.source, "manifest.source");
+  if (!SOURCES.has(source as TrajectoryImportSource)) {
+    throw new Error("Invalid trajectory import manifest.source.");
+  }
+  const applyState = expectString(record.applyState, "manifest.applyState");
+  if (!["staged", "materializing", "completed"].includes(applyState)) {
+    throw new Error("Invalid trajectory import manifest.applyState.");
+  }
+  const scope = expectRecord(record.scope, "manifest.scope");
+  return {
+    schemaVersion: expectLiteral(record.schemaVersion, 1, "manifest.schemaVersion"),
+    kind: expectLiteral(record.kind, "trajectory-import-manifest", "manifest.kind"),
+    source: source as TrajectoryImportSource,
+    sourceKey: expectStateId(record.sourceKey, "src", "manifest.sourceKey"),
+    projectKey: expectScopeId(record.projectKey, "manifest.projectKey"),
+    scope: {
+      roleId: expectNullableScopeId(scope.roleId, "manifest.scope.roleId"),
+    },
+    currentGenerationId: expectStateId(
+      record.currentGenerationId,
+      "gen",
+      "manifest.currentGenerationId",
+    ),
+    initialInputFingerprint: expectNonEmptyString(
+      record.initialInputFingerprint,
+      "manifest.initialInputFingerprint",
+    ),
+    generationContract: parseGenerationContract(record.generationContract),
+    currentSnapshotId: expectStateId(
+      record.currentSnapshotId,
+      "snap",
+      "manifest.currentSnapshotId",
+    ),
+    previousSnapshotId:
+      record.previousSnapshotId === null || record.previousSnapshotId === undefined
+        ? null
+        : expectStateId(record.previousSnapshotId, "snap", "manifest.previousSnapshotId"),
+    currentPreviewId: expectStateId(
+      record.currentPreviewId,
+      "preview",
+      "manifest.currentPreviewId",
+    ),
+    currentInputFingerprint: expectNonEmptyString(
+      record.currentInputFingerprint,
+      "manifest.currentInputFingerprint",
+    ),
+    currentInputBytes: expectNonNegativeInteger(
+      record.currentInputBytes,
+      "manifest.currentInputBytes",
+    ),
+    currentIndexDigest: expectDigest(record.currentIndexDigest, "manifest.currentIndexDigest"),
+    stagedAt: expectIsoTimestamp(record.stagedAt, "manifest.stagedAt"),
+    applyState: applyState as TrajectoryImportManifestV1["applyState"],
+    latestMaterializedSnapshotId:
+      record.latestMaterializedSnapshotId === null
+        ? null
+        : expectStateId(
+            record.latestMaterializedSnapshotId,
+            "snap",
+            "manifest.latestMaterializedSnapshotId",
+          ),
+    rawContentStored: expectLiteral(record.rawContentStored, false, "manifest.rawContentStored"),
+  };
+}
+
+function parseTrajectoryImportReceipt(value: unknown): TrajectoryImportReceiptV1 {
+  const record = expectRecord(value, "receipt");
+  const operation = expectString(record.operation, "receipt.operation");
+  const outcome = expectString(record.outcome, "receipt.outcome");
+  if (!["stage", "materialize"].includes(operation)) {
+    throw new Error("Invalid trajectory import receipt.operation.");
+  }
+  if (!["staged", "completed"].includes(outcome)) {
+    throw new Error("Invalid trajectory import receipt.outcome.");
+  }
+  const counts = expectRecord(record.counts, "receipt.counts");
+  return {
+    schemaVersion: expectLiteral(record.schemaVersion, 1, "receipt.schemaVersion"),
+    kind: expectLiteral(record.kind, "trajectory-import-receipt", "receipt.kind"),
+    previewId: expectStateId(record.previewId, "preview", "receipt.previewId"),
+    sourceKey: expectStateId(record.sourceKey, "src", "receipt.sourceKey"),
+    generationId: expectStateId(record.generationId, "gen", "receipt.generationId"),
+    snapshotId: expectStateId(record.snapshotId, "snap", "receipt.snapshotId"),
+    operation: operation as TrajectoryImportReceiptV1["operation"],
+    outcome: outcome as TrajectoryImportReceiptV1["outcome"],
+    counts: {
+      total: expectNonNegativeInteger(counts.total, "receipt.counts.total"),
+      new: expectNonNegativeInteger(counts.new, "receipt.counts.new"),
+      unchanged: expectNonNegativeInteger(counts.unchanged, "receipt.counts.unchanged"),
+      changed: expectNonNegativeInteger(counts.changed, "receipt.counts.changed"),
+      missing: expectNonNegativeInteger(counts.missing, "receipt.counts.missing"),
+    },
+    createdAt: expectIsoTimestamp(record.createdAt, "receipt.createdAt"),
+    rawContentStored: expectLiteral(record.rawContentStored, false, "receipt.rawContentStored"),
+  };
+}
+
+function parseTrajectoryImportMaterializationProgress(
+  value: unknown,
+): TrajectoryImportMaterializationProgressV1 {
+  const record = expectRecord(value, "materializationProgress");
+  const progress: TrajectoryImportMaterializationProgressV1 = {
+    schemaVersion: expectLiteral(record.schemaVersion, 1, "materializationProgress.schemaVersion"),
+    kind: expectLiteral(
+      record.kind,
+      "trajectory-import-materialization-progress",
+      "materializationProgress.kind",
+    ),
+    previewId: expectStateId(record.previewId, "preview", "materializationProgress.previewId"),
+    sourceKey: expectStateId(record.sourceKey, "src", "materializationProgress.sourceKey"),
+    generationId: expectStateId(record.generationId, "gen", "materializationProgress.generationId"),
+    snapshotId: expectStateId(record.snapshotId, "snap", "materializationProgress.snapshotId"),
+    expectedSegmentIds: expectSafeIdArray(
+      record.expectedSegmentIds,
+      "materializationProgress.expectedSegmentIds",
+    ),
+    completedSegmentIds: expectSafeIdArray(
+      record.completedSegmentIds,
+      "materializationProgress.completedSegmentIds",
+    ),
+    expectedTriggerIds: expectSafeIdArray(
+      record.expectedTriggerIds,
+      "materializationProgress.expectedTriggerIds",
+    ),
+    completedTriggerIds: expectSafeIdArray(
+      record.completedTriggerIds,
+      "materializationProgress.completedTriggerIds",
+    ),
+    updatedAt: expectIsoTimestamp(record.updatedAt, "materializationProgress.updatedAt"),
+    rawContentStored: expectLiteral(
+      record.rawContentStored,
+      false,
+      "materializationProgress.rawContentStored",
+    ),
+  };
+  assertCompletedIdsExpected(
+    progress.completedSegmentIds,
+    progress.expectedSegmentIds,
+    "materializationProgress.completedSegmentIds",
+  );
+  assertCompletedIdsExpected(
+    progress.completedTriggerIds,
+    progress.expectedTriggerIds,
+    "materializationProgress.completedTriggerIds",
+  );
+  return progress;
+}
+
+function assertCompletedIdsExpected(completed: string[], expected: string[], field: string): void {
+  const expectedIds = new Set(expected);
+  if (completed.some((id) => !expectedIds.has(id))) {
+    throw new Error(`Invalid trajectory import ${field}: unexpected completed id.`);
+  }
+}
+
+function parseTrajectoryImportIndexRecord(
+  value: unknown,
+  ordinal: number,
+): TrajectoryImportIndexRecordV1 {
+  const record = expectRecord(value, `index[${ordinal}]`);
+  const sourceIdentityKind = expectString(
+    record.sourceIdentityKind,
+    `index[${ordinal}].sourceIdentityKind`,
+  );
+  if (!IDENTITY_KINDS.has(sourceIdentityKind as CanonicalImportSourceIdentityKind)) {
+    throw new Error(`Invalid trajectory import index[${ordinal}].sourceIdentityKind.`);
+  }
+  const recordType = expectString(record.recordType, `index[${ordinal}].recordType`);
+  if (!RECORD_TYPES.has(recordType as CanonicalImportRecordType)) {
+    throw new Error(`Invalid trajectory import index[${ordinal}].recordType.`);
+  }
+  const storedOrdinal = expectNonNegativeInteger(record.ordinal, `index[${ordinal}].ordinal`);
+  if (storedOrdinal !== ordinal) {
+    throw new Error("Trajectory import index ordinals must be contiguous.");
+  }
+  return {
+    schemaVersion: expectLiteral(record.schemaVersion, 1, `index[${ordinal}].schemaVersion`),
+    kind: expectLiteral(record.kind, "trajectory-import-index-record", `index[${ordinal}].kind`),
+    stableRecordKeyHash: expectDigest(
+      record.stableRecordKeyHash,
+      `index[${ordinal}].stableRecordKeyHash`,
+    ),
+    contentDigest: expectDigest(record.contentDigest, `index[${ordinal}].contentDigest`),
+    ordinal: storedOrdinal,
+    sourceIdentityKind: sourceIdentityKind as CanonicalImportSourceIdentityKind,
+    recordType: recordType as CanonicalImportRecordType,
+  };
+}
+
+function validateTrajectoryImportIndexSet(records: TrajectoryImportIndexRecordV1[]): void {
+  const keys = new Set<string>();
+  for (const record of records) {
+    if (keys.has(record.stableRecordKeyHash)) {
+      throw new Error("Trajectory import index contains a duplicate record identity.");
+    }
+    keys.add(record.stableRecordKeyHash);
+  }
+}
+
+function parseGenerationContract(value: unknown): TrajectoryImportGenerationContractV1 {
+  const record = expectRecord(value, "generationContract");
+  return {
+    normalizerVersion: expectNonEmptyString(
+      record.normalizerVersion,
+      "generationContract.normalizerVersion",
+    ),
+    canonicalSchemaVersion: expectPositiveInteger(
+      record.canonicalSchemaVersion,
+      "generationContract.canonicalSchemaVersion",
+    ),
+    canonicalConfigHash: expectNonEmptyString(
+      record.canonicalConfigHash,
+      "generationContract.canonicalConfigHash",
+    ),
+  };
+}
+
+function expectRecord(value: unknown, field: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function expectString(value: unknown, field: string): string {
+  if (typeof value !== "string") throw new Error(`Invalid trajectory import ${field}.`);
+  return value;
+}
+
+function expectNonEmptyString(value: unknown, field: string): string {
+  const text = expectString(value, field);
+  if (text.trim() === "") throw new Error(`Invalid trajectory import ${field}.`);
+  return text;
+}
+
+function expectScopeId(value: unknown, field: string): string {
+  const text = expectString(value, field);
+  if (
+    text.length > 120 ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/u.test(text) ||
+    text === "." ||
+    text === ".."
+  ) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return text;
+}
+
+function expectNullableScopeId(value: unknown, field: string): string | null {
+  return value === null ? null : expectScopeId(value, field);
+}
+
+function expectStateId(value: unknown, prefix: string, field: string): string {
+  const text = expectString(value, field);
+  if (!new RegExp(`^${prefix}-[a-f0-9]{24}$`, "u").test(text)) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return text;
+}
+
+function expectDigest(value: unknown, field: string): string {
+  const text = expectString(value, field);
+  if (!/^[a-f0-9]{64}$/u.test(text)) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return text;
+}
+
+function expectSafeIdArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value)) throw new Error(`Invalid trajectory import ${field}.`);
+  const ids = value.map((item, index) => {
+    const text = expectString(item, `${field}[${index}]`);
+    if (!/^[a-z][a-z0-9-]{1,119}$/u.test(text)) {
+      throw new Error(`Invalid trajectory import ${field}[${index}].`);
+    }
+    return text;
+  });
+  if (new Set(ids).size !== ids.length) {
+    throw new Error(`Invalid trajectory import ${field}: duplicate id.`);
+  }
+  return ids;
+}
+
+function expectNonNegativeInteger(value: unknown, field: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return value as number;
+}
+
+function expectPositiveInteger(value: unknown, field: string): number {
+  const parsed = expectNonNegativeInteger(value, field);
+  if (parsed < 1) throw new Error(`Invalid trajectory import ${field}.`);
+  return parsed;
+}
+
+function expectIsoTimestamp(value: unknown, field: string): string {
+  const text = expectString(value, field);
+  if (!Number.isFinite(Date.parse(text))) {
+    throw new Error(`Invalid trajectory import ${field}.`);
+  }
+  return text;
+}
+
+function expectLiteral<T extends string | number | boolean>(
+  value: unknown,
+  expected: T,
+  field: string,
+): T {
+  if (value !== expected) throw new Error(`Invalid trajectory import ${field}.`);
+  return expected;
+}
+
+function normalizeDuration(
+  field: string,
+  value: number | undefined,
+  fallback: number,
+  allowZero: boolean,
+): number {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || (allowZero ? resolved < 0 : resolved < 1)) {
+    throw new Error(`Invalid trajectory import lock ${field}.`);
+  }
+  return resolved;
+}
+
+function sameFileIdentity(left: Stats, right: Stats): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function isStale(stats: Stats, staleAfterMs: number): boolean {
+  return Date.now() - stats.mtimeMs > staleAfterMs;
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (hasErrorCode(error, "ENOENT")) return false;
+    throw error;
+  }
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === code
+  );
+}