@narumitw/pi-sync 0.51.1 → 0.52.0

package/src/settings/settings-validation.ts

@@ -12,6 +12,7 @@ import {
   normalizeWebDavUrl,
   validateWebDavCredentials,
 } from "../backends/webdav/webdav-config.js";
+import { normalizeLocalFields } from "../sync/local-fields.js";
 import { normalizeSyncInclude } from "../sync/sync-policy.js";
 import { localConfigPath } from "./config-file.js";
 import type {
@@ -33,9 +34,9 @@ export function normalizeOnSwitch(value: unknown): OnSwitchAction {
 }
 
 export function validateSettingsDocument(value: Record<string, unknown>): PiSyncSettingsV3 {
-  if (value.version !== 3) {
+  if (value.version !== 3 && value.version !== 4 && value.version !== 5) {
     throw new Error(
-      `Unsupported pi-sync settings: version 3 is required. Keep the existing file for recovery, then create a new version 3 ${path.basename(localConfigPath())}; pi-sync will not migrate or overwrite old settings.`,
+      `Unsupported pi-sync settings: version 3 or 4 or 5 is required. Keep the existing ${path.basename(localConfigPath())} for recovery and use a compatible pi-sync client or review a separate supported setup; do not downgrade portable field policies. pi-sync will not migrate or overwrite unsupported settings.`,
     );
   }
   rejectLegacyFields(
@@ -95,6 +96,16 @@ export function validateSettingsDocument(value: Record<string, unknown>): PiSync
   } else if (!activeSyncSetup || !Object.hasOwn(syncSetups, activeSyncSetup)) {
     throw new Error("Invalid pi-sync settings: activeSyncSetup must reference an existing own-property sync setup.");
   }
+  for (const setup of Object.values(syncSetups)) {
+    const policy = (setup as SyncSetupSettings).sync;
+    if (policy.localFields !== undefined && value.version !== 4 && value.version !== 5)
+      throw new Error("localFields requires explicit settings version 4; older binaries must refuse portable state.");
+  }
+  for (const setup of Object.values(syncSetups)) {
+    const policy = (setup as SyncSetupSettings).sync;
+    if ((policy.mergeContent || policy.partialSync) && value.version !== 5)
+      throw new Error("Content/partial sync requires explicit settings version 5.");
+  }
   validateUniqueRemoteSyncSetups(syncSetups, storageConnections);
   return value as PiSyncSettingsV3;
 }
@@ -201,7 +212,17 @@ function validateSyncSetup(name: string, value: Record<string, unknown>, connect
   if (!Object.hasOwn(sync, "include")) {
     throw new Error(`Invalid pi-sync settings: sync setup “${name}” is missing sync.include.`);
   }
-  normalizeSyncInclude(sync.include);
+  const include = normalizeSyncInclude(sync.include);
+  const localFields = normalizeLocalFields(sync.localFields);
+  if (localFields.length > 0 && !include.includes("settings.json"))
+    throw new Error("Nonempty localFields requires settings.json in sync.include.");
+  for (const key of ["mergeContent", "partialSync"])
+    if (sync[key] !== undefined && typeof sync[key] !== "boolean") throw new Error(`${key} must be boolean.`);
+  if (sync.mergeSettings !== undefined && typeof sync.mergeSettings !== "boolean")
+    throw new Error("mergeSettings must be boolean.");
+  if (sync.automaticTransfer !== undefined && typeof sync.automaticTransfer !== "boolean") {
+    throw new Error(`Invalid pi-sync settings: sync setup “${name}” sync.automaticTransfer must be boolean.`);
+  }
   if (typeof sync.automatic !== "boolean") {
     throw new Error(`Invalid pi-sync settings: sync setup “${name}” sync.automatic must be boolean.`);
   }

package/src/snapshot/session-paths.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { type ExtensionCommandContext, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { AnySyncConfig } from "../settings/settings-types.js";
 import { readJsonIfExists } from "../state/json-file.js";
+import { sessionStorageRoot } from "./snapshot-paths.js";
 import type { Snapshot, SnapshotOptions } from "./snapshot-types.js";
 
 export function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionContext) {
@@ -19,7 +20,11 @@ export function sessionDirFromContext(ctx: ExtensionCommandContext | ExtensionCo
 
 export async function configuredSessionDir() {
   const settings = await readJsonIfExists<{ sessionDir?: string }>(path.join(agentDir(), "settings.json"));
-  return settings?.sessionDir ? expandHome(settings.sessionDir) : undefined;
+  return settings?.sessionDir ? expandSessionDir(settings.sessionDir) : undefined;
+}
+
+export async function effectiveSessionRoot(ctx: ExtensionCommandContext | ExtensionContext) {
+  return path.resolve(sessionStorageRoot(agentDir(), sessionDirFromContext(ctx) ?? (await configuredSessionDir())));
 }
 
 export async function sessionDirForApply(ctx: ExtensionCommandContext | ExtensionContext, snapshot: Snapshot) {
@@ -31,17 +36,39 @@ export async function sessionDirForApply(ctx: ExtensionCommandContext | Extensio
   return sessionDirFromSnapshot(snapshot) ?? contextSessionDir;
 }
 
+/** Hash-only merge plans cannot describe installation into a different session root. */
+export function requireStableMergeSessionRoot(before: Snapshot, after: Snapshot) {
+  const root = agentDir();
+  if (
+    path.resolve(sessionStorageRoot(root, sessionDirFromSnapshot(before))) !==
+    path.resolve(sessionStorageRoot(root, sessionDirFromSnapshot(after)))
+  ) {
+    throw new Error(
+      "Merged transfer changes the session root; no local apply or baseline acceptance is allowed. Review /sync diff and choose an explicit push or pull direction.",
+    );
+  }
+}
+
 function sessionDirFromSnapshot(snapshot: Snapshot) {
   const settingsFile = snapshot.files.find((file) => file.path === "settings.json");
   if (!settingsFile) return undefined;
+  let settings: unknown;
   try {
-    const settings = JSON.parse(decodeBase64Strict(settingsFile.contentBase64, settingsFile.path).toString("utf8")) as {
-      sessionDir?: string;
-    };
-    return settings.sessionDir ? expandHome(settings.sessionDir) : undefined;
+    settings = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(
+        decodeBase64Strict(settingsFile.contentBase64, settingsFile.path),
+      ),
+    );
   } catch {
-    return undefined;
+    // JSON parser errors can quote private settings values; never surface their payload.
+    throw new Error("Merged settings cannot be parsed; review a directional recovery.");
   }
+  if (!settings || typeof settings !== "object" || Array.isArray(settings))
+    throw new Error("Merged settings must be a JSON object; review a directional recovery.");
+  const sessionDir = (settings as { sessionDir?: unknown }).sessionDir;
+  if (sessionDir !== undefined && typeof sessionDir !== "string")
+    throw new Error("Merged sessionDir must be a string; review a directional recovery.");
+  return sessionDir ? expandSessionDir(sessionDir) : undefined;
 }
 
 function decodeBase64Strict(value: string, filePath: string) {
@@ -55,7 +82,7 @@ export function agentDir() {
   return getAgentDir();
 }
 
-function expandHome(value: string) {
+export function expandSessionDir(value: string) {
   return value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
 }
 

package/src/snapshot/snapshot-apply.ts

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
-import type { Dirent } from "node:fs";
+import type { Dirent, Stats } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "../paths.js";
+import { syncDirectory } from "../state/json-file.js";
 import { agentDir } from "./session-paths.js";
 import {
   createSnapshot,
@@ -26,11 +27,34 @@ function fileHashMap(snapshot: Snapshot) {
 export async function applySnapshot(
   snapshot: Snapshot,
   protectedRelativePaths = new Set<string>(),
-  options: Pick<SnapshotOptions, "include" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles"> = {},
+  options: Pick<
+    SnapshotOptions,
+    | "include"
+    | "sessionDir"
+    | "syncFiles"
+    | "syncSessions"
+    | "extraFiles"
+    | "signal"
+    | "validateMutation"
+    | "expectedFileHashes"
+  > = {},
 ) {
   const root = agentDir();
   const { sessionDir } = options;
-  await recoverPendingSnapshotTransactions();
+  const transactionOptions = {
+    sessionDir,
+    signal: options.signal,
+    validateMutation: options.validateMutation,
+    protectedTargets: [...protectedRelativePaths].map((relative) => snapshotTarget(root, relative, sessionDir)),
+    expectedPreimages: new Map(
+      Object.entries(options.expectedFileHashes ?? {}).map(([relative, hash]) => [
+        snapshotTarget(root, relative, sessionDir),
+        hash === null ? "missing" : `file:${hash}`,
+      ]),
+    ),
+  };
+  options.validateMutation?.();
+  await recoverPendingSnapshotTransactions(transactionOptions);
   const current = await createSnapshot(snapshot.profile, {
     ...options,
     ...(options.include === undefined ? { syncSessions: snapshotIncludesSessions(snapshot) } : {}),
@@ -46,8 +70,8 @@ export async function applySnapshot(
     ),
     snapshot,
   );
-  await preflightSnapshotMutations(root, plan, sessionDir);
-  await applySnapshotTransaction(plan, { sessionDir });
+  await preflightSnapshotMutations(root, plan, sessionDir, options);
+  await applySnapshotTransaction(plan, transactionOptions);
   return appliedFileHashMap(snapshot, current, protectedRelativePaths);
 }
 
@@ -181,18 +205,43 @@ function decodeBase64Strict(value: string, filePath: string) {
   return Buffer.from(value, "base64");
 }
 
-async function preflightSnapshotMutations(
+type MutationGuards = Pick<SnapshotOptions, "signal" | "validateMutation">;
+
+export async function preflightSnapshotMutations(
   root: string,
   plan: { deletes: string[]; writes: Array<{ target: string; content: Buffer }> },
   sessionDir?: string,
+  options: MutationGuards = {},
 ) {
+  assertMutationCurrent(options);
   const deletePaths = new Set(plan.deletes);
   for (const target of plan.deletes) {
-    await assertNoSymlinkParents(rootForTarget(root, target, sessionDir), target);
+    await assertNoSymlinkParents(rootForTarget(root, target, sessionDir), target, options);
+    assertMutationCurrent(options);
   }
   for (const item of plan.writes) {
-    await prepareSnapshotWrite(rootForTarget(root, item.target, sessionDir), item.target, deletePaths);
+    await prepareSnapshotWrite(rootForTarget(root, item.target, sessionDir), item.target, deletePaths, options);
+    assertMutationCurrent(options);
+  }
+}
+
+function assertMutationCurrent(options: MutationGuards) {
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+}
+
+async function guardedStat(target: string, options: MutationGuards) {
+  assertMutationCurrent(options);
+  let stat: Stats;
+  try {
+    stat = await fs.lstat(target);
+  } catch (error) {
+    assertMutationCurrent(options);
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
   }
+  assertMutationCurrent(options);
+  return stat;
 }
 
 function rootForTarget(root: string, target: string, sessionDir?: string) {
@@ -201,43 +250,46 @@ function rootForTarget(root: string, target: string, sessionDir?: string) {
   return root;
 }
 
-async function prepareSnapshotWrite(root: string, target: string, deletePaths: Set<string>) {
-  const parentWillBeReplaced = await ensureSafeDirectory(root, path.dirname(target), deletePaths);
+async function prepareSnapshotWrite(root: string, target: string, deletePaths: Set<string>, options: MutationGuards) {
+  const parentWillBeReplaced = await ensureSafeDirectory(root, path.dirname(target), deletePaths, options);
+  assertMutationCurrent(options);
   if (parentWillBeReplaced) return;
-  try {
-    const stat = await fs.lstat(target);
-    if (stat.isSymbolicLink()) throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
-    if (stat.isDirectory() && !deletePaths.has(target)) {
-      throw new Error(`Refusing to overwrite directory during snapshot apply: ${target}`);
-    }
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  const stat = await guardedStat(target, options);
+  assertMutationCurrent(options);
+  if (stat?.isSymbolicLink()) throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
+  if (stat?.isDirectory() && !deletePaths.has(target)) {
+    throw new Error(`Refusing to overwrite directory during snapshot apply: ${target}`);
   }
 }
 
-async function ensureSafeDirectory(root: string, directory: string, deletePaths: Set<string>) {
+async function ensureSafeDirectory(root: string, directory: string, deletePaths: Set<string>, options: MutationGuards) {
+  assertMutationCurrent(options);
   assertWithinRoot(root, directory);
   const rootPath = path.resolve(root);
   const relative = path.relative(rootPath, path.resolve(directory));
   let current = rootPath;
   for (const part of relative.split(path.sep).filter(Boolean)) {
     current = path.join(current, part);
-    try {
-      const stat = await fs.lstat(current);
+    const stat = await guardedStat(current, options);
+    assertMutationCurrent(options);
+    if (stat) {
       if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
       if (!stat.isDirectory()) {
         if (deletePaths.has(current)) return true;
         throw new Error(`Snapshot path parent is not a directory: ${current}`);
       }
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    } else {
       await fs.mkdir(current);
+      assertMutationCurrent(options);
+      await syncDirectory(path.dirname(current));
+      assertMutationCurrent(options);
     }
   }
   return false;
 }
 
-async function assertNoSymlinkParents(root: string, target: string) {
+async function assertNoSymlinkParents(root: string, target: string, options: MutationGuards) {
+  assertMutationCurrent(options);
   assertWithinRoot(root, target);
   const rootPath = path.resolve(root);
   const relative = path.relative(rootPath, path.resolve(target));
@@ -245,13 +297,10 @@ async function assertNoSymlinkParents(root: string, target: string) {
   const parts = relative.split(path.sep).filter(Boolean);
   for (const part of parts.slice(0, -1)) {
     current = path.join(current, part);
-    try {
-      const stat = await fs.lstat(current);
-      if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
-      if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
-      throw error;
-    }
+    const stat = await guardedStat(current, options);
+    assertMutationCurrent(options);
+    if (!stat) return;
+    if (stat.isSymbolicLink()) throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
+    if (!stat.isDirectory()) throw new Error(`Snapshot path parent is not a directory: ${current}`);
   }
 }

package/src/snapshot/snapshot-case-replacement.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { SnapshotApplyPlan } from "./snapshot-types.js";
+
+/** Only the top-level file correction produced by addTopLevelCaseVariantDeletes is eligible. */
+export function isCaseReplacement(root: string, before: string, after: string) {
+  return (
+    before !== after &&
+    path.dirname(before) === root &&
+    path.dirname(after) === root &&
+    path.basename(before).toLowerCase() === path.basename(after).toLowerCase()
+  );
+}
+
+/** Absence is handled by the journal's removal/replacement evidence, never by naming evidence. */
+export async function caseReplacementSpelling(before: string, after: string): Promise<string | undefined> {
+  const observations = await Promise.all(
+    [before, after].map(async (target) => {
+      try {
+        const stat = await fs.lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1) throw new Error("Unsafe case replacement target.");
+        return await fs.realpath(target);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+        throw error;
+      }
+    }),
+  );
+  if (observations.every((value) => value === undefined)) return undefined;
+  if (!observations[0] || observations[0] !== observations[1])
+    throw new Error("Case replacement no longer identifies one physical file; preserve evidence for review.");
+  const names = (await fs.readdir(path.dirname(before))).filter(
+    (name) => name.toLowerCase() === path.basename(before).toLowerCase(),
+  );
+  if (names.length !== 1 || (names[0] !== path.basename(before) && names[0] !== path.basename(after)))
+    throw new Error("Case replacement spelling changed; preserve evidence for review.");
+  return path.join(path.dirname(before), names[0]);
+}
+
+export async function coalesceCaseReplacements(root: string, plan: SnapshotApplyPlan) {
+  const replacements = new Map<string, string>();
+  const deletesByCase = new Map<string, string[]>();
+  const writeTargets = new Set(plan.writes.map((item) => item.target));
+  for (const target of new Set(plan.deletes)) {
+    if (path.dirname(target) !== root || writeTargets.has(target)) continue;
+    const key = path.basename(target).toLowerCase();
+    const group = deletesByCase.get(key) ?? [];
+    group.push(target);
+    deletesByCase.set(key, group);
+  }
+  for (const item of plan.writes) {
+    if (path.dirname(item.target) !== root) continue;
+    const candidates = deletesByCase.get(path.basename(item.target).toLowerCase()) ?? [];
+    if (candidates.length !== 1) continue;
+    const before = candidates[0];
+    if (!before || !isCaseReplacement(root, before, item.target)) continue;
+    // Different real paths on a case-sensitive filesystem remain independent targets.
+    let beforePath: string;
+    let afterPath: string;
+    try {
+      [beforePath, afterPath] = await Promise.all([fs.realpath(before), fs.realpath(item.target)]);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    if (beforePath !== afterPath) continue;
+    if (replacements.has(before)) throw new Error("Multiple writes alias a case replacement target.");
+    if ((await caseReplacementSpelling(before, item.target)) !== before)
+      throw new Error("Case replacement preimage spelling changed; review is required.");
+    replacements.set(before, item.target);
+  }
+  const beforeByAfter = new Map([...replacements].map(([before, after]) => [after, before]));
+  return {
+    replacements,
+    plan: {
+      deletes: plan.deletes,
+      writes: plan.writes.map((item) => ({ ...item, target: beforeByAfter.get(item.target) ?? item.target })),
+    },
+  };
+}

package/src/snapshot/snapshot-codec.ts

@@ -36,9 +36,14 @@ export async function decodeSnapshot(
   await pipeline(Readable.from([buffer]), createGunzip(), sink, { signal: options.signal });
   throwIfAborted(options.signal);
   const parsed = JSON.parse(Buffer.concat(chunks, total).toString("utf8")) as Snapshot;
-  if (parsed.version !== VERSION || !Array.isArray(parsed.files)) {
+  if ((parsed.version !== VERSION && parsed.version !== 2 && parsed.version !== 3) || !Array.isArray(parsed.files)) {
     throw new Error("Unsupported snapshot format.");
   }
+  if (parsed.version === 2 || parsed.version === 3) {
+    const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
+    validatePortableSnapshot(parsed);
+    if (parsed.localFields !== undefined) parsed.localFields = normalizeLocalFields(parsed.localFields);
+  } else if (parsed.localFields !== undefined) throw new Error("Portable field policy requires snapshot version 2.");
   snapshotSelectionInclude(parsed);
   return parsed;
 }

package/src/snapshot/snapshot-root-transition.ts

@@ -0,0 +1,154 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isPathInside } from "../paths.js";
+import { syncDirectory } from "../state/json-file.js";
+import { expandSessionDir } from "./session-paths.js";
+import { sessionStorageRoot } from "./snapshot-paths.js";
+import { fileImage } from "./snapshot-transaction-plan.js";
+import type { SnapshotApplyPlan } from "./snapshot-types.js";
+
+export interface SessionRootTransition {
+  beforeRoot: string;
+  /** null is a verified missing postimage, never an empty settings file. */
+  settingsAfterBase64?: string | null;
+  /** Reviewed bytes live in a private fsynced sidecar, pinned by the entry afterImage. */
+  settingsAfterFile?: true;
+}
+interface TransitionGuards {
+  signal?: AbortSignal;
+  validateMutation?: () => void;
+}
+function validateOwner(guards: TransitionGuards) {
+  guards.validateMutation?.();
+  guards.signal?.throwIfAborted();
+}
+interface SettingsEntry {
+  target: string;
+  afterTarget?: string;
+  backupName: string;
+  kind: string;
+  beforeImage?: string;
+  afterImage?: string;
+}
+
+function rootFromSettings(root: string, bytes: Buffer) {
+  let settings: unknown;
+  try {
+    settings = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw new Error("Invalid settings root-transition evidence.");
+  }
+  if (!settings || typeof settings !== "object" || Array.isArray(settings))
+    throw new Error("Invalid settings root-transition evidence.");
+  const value = (settings as { sessionDir?: unknown }).sessionDir;
+  if (value !== undefined && typeof value !== "string") throw new Error("Invalid settings root-transition evidence.");
+  return path.resolve(sessionStorageRoot(root, value ? expandSessionDir(value) : undefined));
+}
+
+async function beforeRoot(directory: string, root: string, entry: SettingsEntry, guards: TransitionGuards) {
+  validateOwner(guards);
+  if (entry.kind === "missing" && entry.beforeImage === "missing") return path.join(root, "sessions");
+  if (entry.kind !== "file") throw new Error("Root transition requires regular settings preimage evidence.");
+  const backup = path.join(directory, "before", entry.backupName);
+  const stat = await fs.lstat(backup);
+  validateOwner(guards);
+  if (!stat.isFile()) throw new Error("Invalid settings root-transition backup.");
+  const bytes = await fs.readFile(backup);
+  validateOwner(guards);
+  if (fileImage(bytes) !== entry.beforeImage) throw new Error("Changed settings root-transition backup.");
+  return rootFromSettings(root, bytes);
+}
+
+export async function prepareSessionRootTransition(
+  directory: string,
+  root: string,
+  sessionRoot: string,
+  entries: SettingsEntry[],
+  plan: SnapshotApplyPlan,
+  guards: TransitionGuards = {},
+): Promise<SessionRootTransition | undefined> {
+  const settingsTarget = path.join(root, "settings.json");
+  const entry = entries.find((item) => item.target === settingsTarget || item.afterTarget === settingsTarget);
+  const write = plan.writes.find((item) => item.target === settingsTarget || item.target === entry?.target);
+  if (!entry || !entries.some((item) => item !== entry && isPathInside(sessionRoot, item.target))) return undefined;
+  const deleted = !write && plan.deletes.includes(entry.target) && entry.afterImage === "missing";
+  if (!write && !deleted) return undefined;
+  const afterRoot = write ? rootFromSettings(root, write.content) : path.join(root, "sessions");
+  // An explicit context root is not a settings-driven transition.
+  if (afterRoot !== sessionRoot) return undefined;
+  const previous = await beforeRoot(directory, root, entry, guards);
+  if (previous === sessionRoot) return undefined;
+  if (write && fileImage(write.content) !== entry.afterImage) throw new Error("Changed settings transition postimage.");
+  if (!write) return { beforeRoot: previous, settingsAfterBase64: null };
+  validateOwner(guards);
+  const handle = await fs.open(path.join(directory, "settings-after"), "wx", 0o600);
+  try {
+    validateOwner(guards);
+    await handle.writeFile(write.content);
+    validateOwner(guards);
+    await handle.sync();
+    validateOwner(guards);
+  } finally {
+    await handle.close();
+  }
+  await syncDirectory(directory);
+  validateOwner(guards);
+  return { beforeRoot: previous, settingsAfterFile: true };
+}
+
+export function validateSessionRootTransition(value: SessionRootTransition) {
+  if (
+    !value ||
+    typeof value.beforeRoot !== "string" ||
+    !path.isAbsolute(value.beforeRoot) ||
+    path.resolve(value.beforeRoot) !== value.beforeRoot ||
+    (value.settingsAfterFile !== undefined && value.settingsAfterFile !== true) ||
+    (value.settingsAfterFile === true
+      ? value.settingsAfterBase64 !== undefined
+      : value.settingsAfterBase64 !== null &&
+        (typeof value.settingsAfterBase64 !== "string" ||
+          value.settingsAfterBase64.length > 32 * 1024 * 1024 ||
+          Buffer.from(value.settingsAfterBase64, "base64").toString("base64") !== value.settingsAfterBase64))
+  )
+    throw new Error("Invalid session root-transition evidence.");
+}
+
+/** Authorization is bound to both settings images, never just an arbitrary pinned root. */
+export async function resolveTransitionSessionRoot(
+  directory: string,
+  root: string,
+  sessionRoot: string,
+  transition: SessionRootTransition,
+  entries: SettingsEntry[],
+  currentRoot: string,
+  guards: TransitionGuards = {},
+) {
+  const settingsTarget = path.join(root, "settings.json");
+  const entry = entries.find((item) => item.target === settingsTarget || item.afterTarget === settingsTarget);
+  if (!entry) throw new Error("Missing settings root-transition evidence.");
+  let after: Buffer | undefined;
+  if (transition.settingsAfterFile) {
+    const file = path.join(directory, "settings-after");
+    const stat = await fs.lstat(file);
+    validateOwner(guards);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.nlink !== 1 ||
+      (process.platform !== "win32" && (stat.mode & 0o077) !== 0)
+    )
+      throw new Error("Unsafe settings root-transition postimage.");
+    after = await fs.readFile(file);
+    validateOwner(guards);
+  } else if (transition.settingsAfterBase64 !== null)
+    after = Buffer.from(transition.settingsAfterBase64 as string, "base64");
+  if (
+    (after ? fileImage(after) : "missing") !== entry.afterImage ||
+    (after ? rootFromSettings(root, after) : path.join(root, "sessions")) !== sessionRoot ||
+    (await beforeRoot(directory, root, entry, guards)) !== transition.beforeRoot
+  )
+    throw new Error("Inconsistent settings root-transition evidence.");
+  if (currentRoot !== transition.beforeRoot && currentRoot !== sessionRoot)
+    throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
+  return sessionRoot;
+}

package/src/snapshot/snapshot-transaction-plan.ts

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { isPathInside } from "../paths.js";
+import type { SnapshotApplyPlan } from "./snapshot-types.js";
+
+export function fileImage(content: Buffer) {
+  return `file:${createHash("sha256").update(content).digest("hex")}`;
+}
+
+/** Work follows path depth and emitted evidence, not every target/write pair. */
+export function indexTransactionPlan(plan: SnapshotApplyPlan, targets: readonly string[]) {
+  const targetIndex = indexTargets(targets);
+  const writeImages = new Map<string, string>();
+  const postFiles = new Map(targets.map((target) => [target, [] as { relative: string; image: string }[]]));
+  for (const write of plan.writes) {
+    const image = fileImage(write.content);
+    // Preserve the first exact write and the original descendant order, including duplicates.
+    if (!writeImages.has(write.target)) writeImages.set(write.target, image);
+    for (const ancestor of ancestorTargets(write.target, targetIndex, false)) {
+      if (ancestor !== write.target && isStrictDescendant(ancestor, write.target)) {
+        postFiles.get(ancestor)?.push({ relative: path.relative(ancestor, write.target), image });
+      }
+    }
+  }
+  const deleteIndex = indexTargets(plan.deletes);
+  const deletes = plan.deletes.filter((target) => {
+    for (const ancestor of ancestorTargets(target, deleteIndex, false)) {
+      if (ancestor !== target && isStrictDescendant(ancestor, target)) return false;
+    }
+    return true;
+  });
+  const deletedWrites = new Set<string>();
+  const outerDeleteIndex = indexTargets(deletes);
+  for (const write of plan.writes) {
+    for (const ancestor of ancestorTargets(write.target, outerDeleteIndex)) {
+      if (ancestor === write.target || isPathInside(ancestor, write.target)) {
+        deletedWrites.add(write.target);
+        break;
+      }
+    }
+  }
+  return { writeImages, postFiles, deletes, deletedWrites };
+}
+
+function isStrictDescendant(parent: string, target: string) {
+  return path.relative(path.resolve(parent), path.resolve(target)) !== "" && isPathInside(parent, target);
+}
+
+function pathKey(target: string) {
+  const resolved = path.resolve(target);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function indexTargets(targets: readonly string[]) {
+  const index = new Map<string, string[]>();
+  for (const target of new Set(targets)) {
+    const key = pathKey(target);
+    const rows = index.get(key) ?? [];
+    rows.push(target);
+    index.set(key, rows);
+  }
+  return index;
+}
+
+function* ancestorTargets(target: string, index: Map<string, string[]>, includeSelf = true) {
+  const resolved = path.resolve(target);
+  // Strict-descendant queries skip the same-address bucket, including native case aliases.
+  for (let ancestor = includeSelf ? resolved : path.dirname(resolved); ; ancestor = path.dirname(ancestor)) {
+    yield* index.get(pathKey(ancestor)) ?? [];
+    if (path.dirname(ancestor) === ancestor) return;
+  }
+}