@narumitw/pi-sync-daemon 0.6.2 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/consent.js +11 -1
  4. package/dist/engine/backends/git/git-storage.js +11 -6
  5. package/dist/engine/paths.js +1 -1
  6. package/dist/engine/settings/config-file.js +2 -0
  7. package/dist/engine/settings/config.d.ts +2 -4
  8. package/dist/engine/settings/config.js +22 -7
  9. package/dist/engine/settings/settings-management.d.ts +2 -2
  10. package/dist/engine/settings/settings-management.js +27 -33
  11. package/dist/engine/settings/settings-types.d.ts +18 -4
  12. package/dist/engine/settings/settings-validation.js +34 -24
  13. package/dist/engine/snapshot/session-paths.d.ts +5 -3
  14. package/dist/engine/snapshot/session-paths.js +55 -9
  15. package/dist/engine/snapshot/snapshot-apply.d.ts +6 -7
  16. package/dist/engine/snapshot/snapshot-apply.js +88 -21
  17. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  18. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  19. package/dist/engine/snapshot/snapshot-codec.js +3 -4
  20. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  21. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  22. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -2
  23. package/dist/engine/snapshot/snapshot-exclude-safety.js +180 -22
  24. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  25. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  26. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  27. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  28. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  29. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  30. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +37 -0
  31. package/dist/engine/snapshot/snapshot-transaction-images.js +357 -0
  32. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +50 -0
  33. package/dist/engine/snapshot/snapshot-transaction-policy.js +172 -0
  34. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  35. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  36. package/dist/engine/snapshot/snapshot-transaction.d.ts +2 -1
  37. package/dist/engine/snapshot/snapshot-transaction.js +379 -331
  38. package/dist/engine/snapshot/snapshot-types.d.ts +24 -1
  39. package/dist/engine/snapshot/snapshot.d.ts +19 -2
  40. package/dist/engine/snapshot/snapshot.js +283 -26
  41. package/dist/engine/state/merge-baseline-store.js +20 -9
  42. package/dist/engine/state/state-types.d.ts +2 -0
  43. package/dist/engine/sync/apply-review.d.ts +3 -3
  44. package/dist/engine/sync/apply-review.js +5 -4
  45. package/dist/engine/sync/continuous-sync.js +19 -9
  46. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  47. package/dist/engine/sync/continuous-watch.js +86 -14
  48. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  49. package/dist/engine/sync/exclude-policy.js +8 -1
  50. package/dist/engine/sync/initialization.js +9 -5
  51. package/dist/engine/sync/local-fields.js +27 -8
  52. package/dist/engine/sync/merge-apply.js +155 -40
  53. package/dist/engine/sync/merge-journal.js +13 -4
  54. package/dist/engine/sync/merged-sync.js +21 -18
  55. package/dist/engine/sync/partial-progress.js +5 -3
  56. package/dist/engine/sync/remote-snapshot.d.ts +1 -0
  57. package/dist/engine/sync/remote-snapshot.js +8 -5
  58. package/dist/engine/sync/session-push.js +7 -6
  59. package/dist/engine/sync/sync-decision.d.ts +4 -0
  60. package/dist/engine/sync/sync-decision.js +17 -2
  61. package/dist/engine/sync/sync-inspection.js +3 -3
  62. package/dist/engine/sync/sync-mutations.d.ts +8 -1
  63. package/dist/engine/sync/sync-mutations.js +153 -72
  64. package/dist/engine/sync/sync-policy.d.ts +20 -10
  65. package/dist/engine/sync/sync-policy.js +170 -16
  66. package/dist/engine/sync/sync-queries.js +41 -31
  67. package/dist/engine/sync/sync-state.d.ts +11 -0
  68. package/dist/engine/sync/sync-state.js +24 -5
  69. package/dist/engine/ui/sync-format.js +22 -7
  70. package/docs/architecture.md +6 -0
  71. package/package.json +1 -1
@@ -1,33 +1,46 @@
1
- import { createHash, randomUUID } from "node:crypto";
1
+ import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
- import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
4
+ import { isPathInside } from "../paths.js";
5
5
  import { syncDirectory, writeJson } from "../state/json-file.js";
6
6
  import { withLock } from "../state/lock.js";
7
7
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
8
8
  import { stateDir } from "../state/state-directory.js";
9
- import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
9
+ import { normalizeSyncExclude } from "../sync/exclude-policy.js";
10
10
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
11
+ import { includeFromSelectionConfig, selectionForSnapshot } from "../sync/sync-policy.js";
11
12
  import { agentDir, configuredSessionDir } from "./session-paths.js";
12
- import { caseReplacementSpelling, coalesceCaseReplacements, isCaseReplacement } from "./snapshot-case-replacement.js";
13
+ import { agentDirectoryConfiguredSessionDir } from "./snapshot.js";
14
+ import { caseReplacementSpelling, coalesceCaseReplacements } from "./snapshot-case-replacement.js";
15
+ import { recheckAgentDirectoryBudget } from "./snapshot-entry-projection.js";
13
16
  import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
14
17
  import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
15
18
  import { sessionStorageRoot } from "./snapshot-paths.js";
16
- import { prepareSessionRootTransition, resolveTransitionSessionRoot, validateSessionRootTransition, } from "./snapshot-root-transition.js";
19
+ import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
17
20
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
18
- import { fileImage, indexTransactionPlan } from "./snapshot-transaction-plan.js";
21
+ import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, readTransactionJournal, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
22
+ import { indexTransactionPlan } from "./snapshot-transaction-plan.js";
23
+ import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, isScopedJournal, isStrictlyInside, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
24
+ import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
19
25
  const JOURNAL_VERSION = 4;
26
+ class ScopedRemovalError extends Error {
27
+ }
20
28
  export async function applySnapshotTransaction(plan, options = {}) {
21
29
  options.validateMutation?.();
30
+ const root = path.resolve(agentDir());
31
+ if (options.scope === "agent-directory") {
32
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root));
33
+ options = { ...options, sessionDir: sessionStorageRoot(root, sessionDir) };
34
+ }
22
35
  await recoverPendingSnapshotTransactions(options);
23
- const coalesced = await coalesceCaseReplacements(path.resolve(agentDir()), plan);
36
+ const coalesced = await coalesceCaseReplacements(root, plan);
24
37
  options.validateMutation?.();
25
38
  options.signal?.throwIfAborted();
26
39
  const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
27
40
  if (targets.length > 16_384)
28
41
  throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
29
42
  return withTargetQueues(targets, options, async (heldKeys) => {
30
- await assertUnexcludedTargets(agentDir(), targets, options);
43
+ await assertUnexcludedTargets(root, [...targets, ...coalesced.replacements.values()], options);
31
44
  options.signal?.throwIfAborted();
32
45
  if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
33
46
  isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
@@ -39,13 +52,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
39
52
  options.signal?.throwIfAborted();
40
53
  }
41
54
  const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
42
- const expectedPreimages = new Map([...(options.expectedPreimages ?? [])].map(([target, expected]) => [
43
- originalTargets.get(target) ?? target,
44
- expected,
45
- ]));
55
+ const scoped = options.scope === "agent-directory";
56
+ const expectedPreimages = new Map([...(options.expectedPreimages ?? [])]
57
+ .filter(([target]) => !scoped || !originalTargets.has(target))
58
+ .map(([target, expected]) => [originalTargets.get(target) ?? target, expected]));
46
59
  // A case-sensitive spelling replacement has two targets, unlike a coalesced physical alias.
47
60
  // Bind both the source bytes and destination absence/bytes before capturing their backups.
48
- for (const [target, expected] of options.expectedPreimages ?? []) {
61
+ for (const [target, expected] of scoped ? [] : (options.expectedPreimages ?? [])) {
49
62
  if (originalTargets.has(target))
50
63
  continue;
51
64
  const variants = coalesced.plan.deletes.filter((candidate) => candidate !== target &&
@@ -56,7 +69,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
56
69
  const original = variants[0];
57
70
  if (!original)
58
71
  continue;
59
- const destination = await image(target);
72
+ const destination = await legacyImage(target);
60
73
  options.validateMutation?.();
61
74
  options.signal?.throwIfAborted();
62
75
  if (destination !== "missing" && destination !== expected)
@@ -64,8 +77,20 @@ export async function applySnapshotTransaction(plan, options = {}) {
64
77
  expectedPreimages.set(original, expected);
65
78
  expectedPreimages.set(target, destination);
66
79
  }
80
+ if (options.scope === "agent-directory") {
81
+ const evidence = await stableAgentDirectorySettingsImage(root, plan, options);
82
+ if (evidence) {
83
+ const target = originalTargets.get(evidence.target) ?? evidence.target;
84
+ const reviewed = expectedPreimages.get(target);
85
+ if (reviewed !== undefined && reviewed !== evidence.image)
86
+ throw new Error("Reviewed Pi settings changed before apply; snapshot installation refused.");
87
+ expectedPreimages.set(target, evidence.image);
88
+ }
89
+ }
67
90
  for (const [target, expected] of expectedPreimages) {
68
- const current = await image(target);
91
+ if (scoped)
92
+ await assertUnexcludedTargets(root, [target], options);
93
+ const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
69
94
  options.validateMutation?.();
70
95
  options.signal?.throwIfAborted();
71
96
  if (current !== expected)
@@ -79,17 +104,21 @@ export async function applySnapshotTransaction(plan, options = {}) {
79
104
  // A released additional key cannot authorize rollback, even for recognized raced bytes.
80
105
  const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
81
106
  try {
107
+ if (scoped && transaction.deletes.length)
108
+ await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
82
109
  for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
83
110
  options.signal?.throwIfAborted();
84
111
  const entry = entriesByTarget.get(target);
85
112
  if (!entry)
86
113
  throw new Error("Unowned transaction target.");
87
- await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
114
+ await removeOwnedTarget(transaction.directory, entry, transaction.journal, options, { apply: true });
88
115
  await syncDirectory(path.dirname(target));
89
116
  }
90
117
  await withMissingTargetQueues(transaction.journal.entries
91
118
  .filter((entry) => entry.removalPending)
92
119
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
120
+ if (scoped && plan.writes.length)
121
+ await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
93
122
  await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
94
123
  // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
95
124
  const uninstalledWrites = new Set(transaction.deletedWrites);
@@ -99,7 +128,9 @@ export async function applySnapshotTransaction(plan, options = {}) {
99
128
  if (!entry)
100
129
  throw new Error("Unowned transaction target.");
101
130
  const deletedByThisCall = uninstalledWrites.delete(entry.target);
102
- await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
131
+ if (options.scope === "agent-directory")
132
+ await assertUnexcludedTargets(transaction.journal.root, [item.target], options);
133
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
103
134
  options.validateMutation?.();
104
135
  options.signal?.throwIfAborted();
105
136
  await fs.mkdir(path.dirname(item.target), { recursive: true });
@@ -125,7 +156,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
125
156
  finally {
126
157
  await handle.close();
127
158
  }
128
- await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
159
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
129
160
  options.signal?.throwIfAborted();
130
161
  options.validateMutation?.();
131
162
  await fs.rename(temp, item.target);
@@ -146,6 +177,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
146
177
  // Aborted owners cannot roll back files after another session has replaced them.
147
178
  if (options.signal?.aborted)
148
179
  throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
180
+ if (error instanceof ScopedRemovalError)
181
+ throw error;
149
182
  // Additional queues have been released. Recovery must reserve missing keys afresh.
150
183
  if (changesQueueKey)
151
184
  throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
@@ -181,24 +214,26 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
181
214
  const directory = path.join(transactionRoot(), entry.name);
182
215
  let journal;
183
216
  try {
184
- const file = path.join(directory, "journal.json");
185
- const stat = await fs.lstat(file);
186
- if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
187
- throw new Error("Invalid journal file.");
188
- journal = JSON.parse(await fs.readFile(file, "utf8"));
189
- }
190
- catch (error) {
217
+ const content = await readTransactionJournal(path.join(directory, "journal.json"), options);
191
218
  // Unknown evidence is not disposable, including interrupted preparation directories.
192
- if (error.code === "ENOENT")
219
+ if (content === undefined)
193
220
  continue;
221
+ journal = JSON.parse(content);
222
+ }
223
+ catch {
224
+ options.validateMutation?.();
225
+ options.signal?.throwIfAborted();
194
226
  throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
195
227
  }
228
+ validateJournalPolicy(journal);
229
+ if (!journal.completed)
230
+ assertRecoveryPolicy(journal, options);
196
231
  let sessionDir = options.sessionDir;
197
- if (sessionDir === undefined &&
198
- options.resolveConfiguredSessionDir &&
199
- !journal.completed &&
200
- transactionHasSessionTargets(journal)) {
201
- sessionDir = await configuredSessionDir();
232
+ if (sessionDir === undefined && !journal.completed) {
233
+ if (options.scope === "agent-directory")
234
+ sessionDir = await agentDirectoryConfiguredSessionDir(options.signal);
235
+ else if (options.resolveConfiguredSessionDir && transactionHasSessionTargets(journal))
236
+ sessionDir = await configuredSessionDir();
202
237
  }
203
238
  options.validateMutation?.();
204
239
  options.signal?.throwIfAborted();
@@ -210,8 +245,6 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
210
245
  options.signal?.throwIfAborted();
211
246
  }
212
247
  validateJournal(directory, journal, sessionDir);
213
- if (!journal.completed && !sameSyncExclude(journal.exclude, options.exclude))
214
- throw new Error("Pending transaction has a different exclude policy; preserve its backup for reviewed recovery.");
215
248
  if (journal.completed) {
216
249
  await removeTransaction(directory);
217
250
  continue;
@@ -222,7 +255,8 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
222
255
  async function prepareTransaction(plan, targets, options, replacements = new Map()) {
223
256
  const { sessionDir } = options;
224
257
  const root = path.resolve(agentDir());
225
- const sessionRoot = sessionDir ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
258
+ const wholeDirectory = options.scope === "agent-directory";
259
+ const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
226
260
  const indexed = indexTransactionPlan(plan, targets);
227
261
  const directory = path.join(transactionRoot(), randomUUID());
228
262
  const backupDirectory = path.join(directory, "before");
@@ -233,52 +267,25 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
233
267
  options.validateMutation?.();
234
268
  assertAllowedTarget(root, sessionRoot, target);
235
269
  await assertSafeParents(root, sessionRoot, target);
270
+ if (wholeDirectory)
271
+ await assertUnexcludedTargets(root, [target], options);
236
272
  const entry = { target, backupName: `${index}`, kind: "missing" };
237
273
  if (replacements.has(target))
238
274
  entry.afterTarget = replacements.get(target);
239
275
  const backup = path.join(backupDirectory, entry.backupName);
240
- try {
241
- const stat = await fs.lstat(target);
242
- if (stat.isSymbolicLink()) {
243
- entry.kind = "symlink";
244
- entry.linkTarget = await fs.readlink(target);
245
- }
246
- else if (stat.isDirectory()) {
247
- entry.kind = "directory";
248
- await fs.cp(target, backup, {
249
- recursive: true,
250
- dereference: false,
251
- verbatimSymlinks: true,
252
- preserveTimestamps: true,
253
- filter: () => {
254
- options.signal?.throwIfAborted();
255
- options.validateMutation?.();
256
- return true;
257
- },
258
- });
259
- }
260
- else if (stat.isFile()) {
261
- entry.kind = "file";
262
- await fs.copyFile(target, backup);
263
- await fs.chmod(backup, stat.mode);
264
- }
265
- else
266
- throw new Error("Unsupported existing snapshot target.");
276
+ if (wholeDirectory) {
277
+ const captured = await scopedTransactionImage(target, options, backup, (source) => assertUnexcludedTargets(root, [source], options, { recursive: false }));
278
+ entry.kind = captured.kind;
279
+ entry.beforeImage = captured.value;
267
280
  }
268
- catch (error) {
269
- const code = error.code;
270
- if (code !== "ENOENT" && code !== "ENOTDIR")
271
- throw error;
281
+ else {
282
+ await captureLegacyBackup(target, backup, entry, options);
272
283
  }
273
- entry.beforeImage =
274
- entry.kind === "symlink"
275
- ? `symlink:${entry.linkTarget}`
276
- : entry.kind === "missing"
277
- ? "missing"
278
- : await image(backup, true);
279
284
  options.validateMutation?.();
280
285
  options.signal?.throwIfAborted();
281
286
  const expected = options.expectedPreimages?.get(target);
287
+ if (wholeDirectory && entry.kind === "directory" && expected === undefined)
288
+ throw new Error("Scoped directory replacement requires a reviewed preimage.");
282
289
  if (expected !== undefined && entry.beforeImage !== expected)
283
290
  throw new Error("Reviewed file preimage changed during backup; private preparation evidence retained.");
284
291
  if (entry.afterTarget) {
@@ -294,23 +301,76 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
294
301
  // File fsync does not persist the name linking each backup into this directory.
295
302
  await syncDirectory(backupDirectory);
296
303
  const effectiveRoot = sessionRoot ?? path.join(root, "sessions");
297
- const sessionRootTransition = await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
304
+ const sessionRootTransition = wholeDirectory
305
+ ? undefined
306
+ : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
298
307
  const journal = {
299
- version: sessionRootTransition ? 7 : replacements.size ? 5 : JOURNAL_VERSION,
308
+ version: wholeDirectory
309
+ ? AGENT_DIRECTORY_JOURNAL_VERSION
310
+ : sessionRootTransition
311
+ ? 7
312
+ : replacements.size
313
+ ? 5
314
+ : JOURNAL_VERSION,
300
315
  root,
301
- ...(options.exclude === undefined ? {} : { exclude: normalizeSyncExclude(options.exclude) }),
316
+ ...(wholeDirectory
317
+ ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
318
+ : options.exclude === undefined
319
+ ? {}
320
+ : { exclude: normalizeSyncExclude(options.exclude) }),
302
321
  sessionRoot: sessionRootTransition ? effectiveRoot : sessionRoot,
303
322
  sessionRootTransition,
304
323
  entries,
305
324
  };
306
325
  options.signal?.throwIfAborted();
307
326
  options.validateMutation?.();
308
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
327
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
309
328
  await syncDirectory(transactionRoot());
310
329
  await syncDirectory(stateDir());
311
330
  await syncDirectory(path.dirname(stateDir()));
312
331
  return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
313
332
  }
333
+ async function captureLegacyBackup(target, backup, entry, options) {
334
+ try {
335
+ const stat = await fs.lstat(target);
336
+ if (stat.isSymbolicLink()) {
337
+ entry.kind = "symlink";
338
+ entry.linkTarget = await fs.readlink(target);
339
+ }
340
+ else if (stat.isDirectory()) {
341
+ entry.kind = "directory";
342
+ await fs.cp(target, backup, {
343
+ recursive: true,
344
+ dereference: false,
345
+ verbatimSymlinks: true,
346
+ preserveTimestamps: true,
347
+ filter: () => {
348
+ options.signal?.throwIfAborted();
349
+ options.validateMutation?.();
350
+ return true;
351
+ },
352
+ });
353
+ }
354
+ else if (stat.isFile()) {
355
+ entry.kind = "file";
356
+ await fs.copyFile(target, backup);
357
+ await fs.chmod(backup, stat.mode);
358
+ }
359
+ else
360
+ throw new Error("Unsupported existing snapshot target.");
361
+ }
362
+ catch (error) {
363
+ const code = error.code;
364
+ if (code !== "ENOENT" && code !== "ENOTDIR")
365
+ throw error;
366
+ }
367
+ entry.beforeImage =
368
+ entry.kind === "symlink"
369
+ ? `symlink:${entry.linkTarget}`
370
+ : entry.kind === "missing"
371
+ ? "missing"
372
+ : await legacyImage(backup, true);
373
+ }
314
374
  async function restoreTransaction(directory, journal, options, heldKeys) {
315
375
  validateJournal(directory, journal, options.sessionDir);
316
376
  const missingSpellings = [];
@@ -331,15 +391,30 @@ async function restoreTransaction(directory, journal, options, heldKeys) {
331
391
  }
332
392
  async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
333
393
  validateJournal(directory, journal, options.sessionDir);
394
+ const scoped = isScopedJournal(journal);
334
395
  options.validateMutation?.();
335
396
  options.signal?.throwIfAborted();
397
+ await assertUnexcludedTargets(journal.root, journal.entries.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), options);
336
398
  for (const entry of journal.entries) {
337
399
  if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
338
400
  isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
339
401
  throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
340
- await verifyTarget(directory, entry, journal);
402
+ const { value, before } = await verifyTarget(directory, entry, journal, options);
403
+ if (scoped) {
404
+ await assertNoUnclaimedLegacyStage(directory, entry, options);
405
+ const stage = await inspectScopedRecoveryStage(directory, entry, options);
406
+ if (entry.recoveryWorkspace && !stage && value !== before)
407
+ throw new Error("Recovery workspace is missing; preserve evidence for review.");
408
+ if (entry.vacantInstall && value === "missing") {
409
+ if (!stage ||
410
+ stage.image.kind === "missing" ||
411
+ stage.image.value !== before ||
412
+ stage.partial.kind !== "missing" ||
413
+ scopedIdentity(stage.image.stat) !== entry.vacantInstall)
414
+ throw new Error("Recovery vacancy has no verified staging image; preserve evidence for review.");
415
+ }
416
+ }
341
417
  }
342
- // Recover copies left by a process crash even when the target is already restored.
343
418
  for (const entry of journal.entries) {
344
419
  if (!entry.recoveryStaged)
345
420
  continue;
@@ -348,21 +423,42 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
348
423
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
349
424
  options.validateMutation?.();
350
425
  options.signal?.throwIfAborted();
351
- await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
426
+ if (scoped)
427
+ await cleanScopedLegacyStage(directory, entry, options);
428
+ else
429
+ await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
430
+ options.validateMutation?.();
431
+ options.signal?.throwIfAborted();
432
+ }
433
+ if (scoped && journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION) {
434
+ journal.version = AGENT_DIRECTORY_JOURNAL_VERSION;
435
+ for (const entry of journal.entries)
436
+ delete entry.recoveryStaged;
352
437
  options.validateMutation?.();
353
438
  options.signal?.throwIfAborted();
439
+ await persistJournal(directory, journal);
354
440
  }
355
441
  // Verify the complete group before removing any path. Recheck each destructive boundary.
356
442
  for (const entry of [...journal.entries].sort((a, b) => a.target.length - b.target.length)) {
357
- const current = await verifyTarget(directory, entry, journal);
358
- const before = await beforeImage(directory, entry);
443
+ const { value: current, before } = await verifyTarget(directory, entry, journal, options);
359
444
  const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
360
- if (current === before && (await spellingMatches()))
445
+ if (current === before && (await spellingMatches())) {
446
+ if (entry.recoveryWorkspace)
447
+ await cleanScopedWorkspace(directory, entry, options);
361
448
  continue;
449
+ }
362
450
  options.signal?.throwIfAborted();
363
451
  options.validateMutation?.();
452
+ if (entry.kind === "missing") {
453
+ await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before });
454
+ continue;
455
+ }
456
+ if (scoped) {
457
+ await restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches);
458
+ continue;
459
+ }
460
+ const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
364
461
  if (entry.kind === "file") {
365
- const temporary = await prepareRecoveryStage(directory, journal, entry, options);
366
462
  try {
367
463
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
368
464
  await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
@@ -374,7 +470,7 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
374
470
  finally {
375
471
  await handle.close();
376
472
  }
377
- const verified = await verifyTarget(directory, entry, journal);
473
+ const { value: verified } = await verifyTarget(directory, entry, journal, options);
378
474
  options.validateMutation?.();
379
475
  options.signal?.throwIfAborted();
380
476
  if (verified === before && (await spellingMatches()))
@@ -386,20 +482,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
386
482
  await removeOwnedTarget(directory, entry, journal, options);
387
483
  }
388
484
  else if (verified.startsWith("directory:") &&
389
- !(await removeOwnedTarget(directory, entry, journal, options, before)))
485
+ !(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
390
486
  continue;
391
487
  await withMissingTargetQueues(entry.afterTarget && (needsCaseQueue || verified === "missing")
392
488
  ? [entry.target, entry.afterTarget]
393
489
  : verified.startsWith("directory:")
394
490
  ? [entry.target]
395
491
  : [], heldKeys, options, async () => {
396
- const atRename = await verifyTarget(directory, entry, journal);
492
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
397
493
  options.validateMutation?.();
398
494
  options.signal?.throwIfAborted();
399
495
  if (atRename === before && (await spellingMatches()))
400
496
  return;
401
497
  await retireRestorationIntent(directory, journal, entry, options);
402
- const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
498
+ const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
403
499
  options.validateMutation?.();
404
500
  options.signal?.throwIfAborted();
405
501
  if (atInstall === before && (await spellingMatches()))
@@ -413,11 +509,6 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
413
509
  }
414
510
  continue;
415
511
  }
416
- if (entry.kind === "missing") {
417
- await removeOwnedTarget(directory, entry, journal, options, before);
418
- continue;
419
- }
420
- const temporary = await prepareRecoveryStage(directory, journal, entry, options);
421
512
  try {
422
513
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
423
514
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
@@ -436,20 +527,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
436
527
  }
437
528
  else if (entry.linkTarget !== undefined)
438
529
  await fs.symlink(entry.linkTarget, temporary);
439
- if ((await image(temporary, true)) !== before)
530
+ if ((await legacyImage(temporary, true)) !== before)
440
531
  throw new Error("Staged recovery image differs from the backup; evidence retained.");
441
532
  options.validateMutation?.();
442
533
  options.signal?.throwIfAborted();
443
- if (!(await removeOwnedTarget(directory, entry, journal, options, before)))
534
+ if (!(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
444
535
  continue;
445
536
  await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
446
- const atRename = await verifyTarget(directory, entry, journal);
537
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
447
538
  options.validateMutation?.();
448
539
  options.signal?.throwIfAborted();
449
540
  if (atRename === before)
450
541
  return;
451
542
  await retireRestorationIntent(directory, journal, entry, options);
452
- const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
543
+ const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
453
544
  options.validateMutation?.();
454
545
  options.signal?.throwIfAborted();
455
546
  if (atInstall === before)
@@ -467,52 +558,196 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
467
558
  options.signal?.throwIfAborted();
468
559
  await completeTransaction(directory, journal);
469
560
  }
470
- async function verifyTarget(directory, entry, journal, deletedByThisCall = false) {
561
+ async function restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches) {
562
+ options.validateMutation?.();
563
+ options.signal?.throwIfAborted();
564
+ await fs.mkdir(path.dirname(entry.target), { recursive: true });
565
+ await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
566
+ if (!entry.vacantInstall)
567
+ await buildScopedRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
568
+ const verifyStage = async () => {
569
+ const stage = await inspectScopedRecoveryStage(directory, entry, options, true);
570
+ if (!stage || stage.image.kind === "missing" || stage.image.value !== before || stage.partial.kind !== "missing")
571
+ throw new Error("Staged recovery image changed; evidence retained.");
572
+ if (entry.vacantInstall && scopedIdentity(stage.image.stat) !== entry.vacantInstall)
573
+ throw new Error("Recovery vacancy has a different staging image; preserve evidence for review.");
574
+ const identity = stableScopedIdentity(stage.payload, stage.image.stat);
575
+ return { payload: stage.payload, identity };
576
+ };
577
+ await verifyStage();
578
+ const { value: verified } = await verifyTarget(directory, entry, journal, options);
579
+ if (verified !== before || !(await spellingMatches())) {
580
+ const needsCaseQueue = entry.afterTarget !== undefined &&
581
+ (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.afterTarget;
582
+ const needsRemoval = verified !== "missing" && (needsCaseQueue || verified.startsWith("directory:") || entry.kind === "directory");
583
+ const needsVacantTarget = needsRemoval || verified === "missing";
584
+ if (!needsRemoval ||
585
+ (await removeOwnedTarget(directory, entry, journal, options, {
586
+ restoringBefore: needsCaseQueue ? undefined : before,
587
+ }))) {
588
+ const queueTargets = needsVacantTarget ? [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])] : [];
589
+ await withMissingTargetQueues(queueTargets, heldKeys, options, async () => {
590
+ const { value: atRename } = await verifyTarget(directory, entry, journal, options);
591
+ if (atRename === before && (await spellingMatches()))
592
+ return;
593
+ if (needsVacantTarget && atRename !== "missing")
594
+ throw new Error("Transaction target changed after removal; preserve evidence for review.");
595
+ const stage = await verifyStage();
596
+ if (needsVacantTarget && !entry.vacantInstall) {
597
+ entry.vacantInstall = stage.identity;
598
+ delete entry.removalPending;
599
+ delete entry.replacementStarted;
600
+ delete entry.scopedRemoval;
601
+ for (const child of journal.entries) {
602
+ if (isStrictlyInside(entry.target, child.target))
603
+ delete child.scopedRemoval;
604
+ }
605
+ options.validateMutation?.();
606
+ options.signal?.throwIfAborted();
607
+ await syncDirectory(path.dirname(entry.target));
608
+ options.validateMutation?.();
609
+ options.signal?.throwIfAborted();
610
+ await persistJournal(directory, journal);
611
+ await verifyStage();
612
+ }
613
+ if ((await scopedPathIdentity(stage.payload, options)) !== stage.identity)
614
+ throw new Error("Staged recovery image changed before restoration; preserve evidence for review.");
615
+ const { value: atInstall } = await verifyTarget(directory, entry, journal, options);
616
+ if (atInstall === before && (await spellingMatches()))
617
+ return;
618
+ if (atInstall !== atRename)
619
+ throw new Error("Transaction target changed before restoration; preserve evidence for review.");
620
+ options.validateMutation?.();
621
+ options.signal?.throwIfAborted();
622
+ await fs.rename(stage.payload, entry.target);
623
+ await syncDirectory(path.dirname(entry.target));
624
+ await syncDirectory(path.dirname(stage.payload));
625
+ if ((await verifyTarget(directory, entry, journal, options)).value !== before)
626
+ throw new Error("Restored transaction image changed; evidence retained.");
627
+ });
628
+ }
629
+ }
630
+ await cleanScopedWorkspace(directory, entry, options);
631
+ }
632
+ async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
471
633
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
634
+ const isScoped = isScopedJournal(journal);
472
635
  // Hash the potentially large backup before observing the live target, not after it.
473
- const before = await beforeImage(directory, entry);
474
- if (journal.version >= 2 && before !== entry.beforeImage)
636
+ const backup = isScoped && entry.kind !== "missing"
637
+ ? await scopedTransactionImage(path.join(directory, "before", entry.backupName), options)
638
+ : undefined;
639
+ const before = isScoped ? (backup?.value ?? "missing") : await legacyBeforeImage(directory, entry);
640
+ if ((backup && backup.kind !== entry.kind) || (journal.version >= 2 && before !== entry.beforeImage))
475
641
  throw new Error("Transaction backup changed; preserve evidence for review.");
476
- if (entry.afterTarget)
477
- await caseReplacementSpelling(entry.target, entry.afterTarget);
478
- const current = await image(entry.target);
479
- if (current === before)
480
- return current;
481
- if (current === "missing") {
482
- if (deletedByThisCall || (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
483
- return current;
642
+ const spelling = entry.afterTarget ? await caseReplacementSpelling(entry.target, entry.afterTarget) : entry.target;
643
+ const scoped = isScoped ? await scopedTransactionImage(entry.target, options) : undefined;
644
+ const value = scoped?.value ?? (await legacyImage(entry.target));
645
+ const result = { value, before, scoped };
646
+ const postFiles = entry.postFiles ?? [];
647
+ if (entry.vacantInstall) {
648
+ if (scoped?.kind === "missing" ||
649
+ (scoped && value === before && spelling === entry.target && scopedIdentity(scoped.stat) === entry.vacantInstall))
650
+ return result;
651
+ }
652
+ else if (value === "missing") {
653
+ if (value === before ||
654
+ deletedByThisCall ||
655
+ (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
656
+ return result;
657
+ }
658
+ else if (scoped && entry.scopedRemoval) {
659
+ const removal = entry.scopedRemoval;
660
+ if ((removal.image === "before"
661
+ ? backup && ownedScopedSubset(scoped, backup)
662
+ : value === entry.afterImage || ownedScopedPostTree(scoped, postFiles, false)) &&
663
+ scoped.kind !== "missing" &&
664
+ scopedIdentity(scoped.stat) === removal.identity)
665
+ return result;
666
+ }
667
+ else if (value === before || (journal.version >= 2 && value === entry.afterImage)) {
668
+ return result;
669
+ }
670
+ else if (journal.version >= 2) {
671
+ const requireComplete = journal.version < 4 || entry.replacementStarted === true || !entry.removalPending;
672
+ if (scoped
673
+ ? ownedScopedPostTree(scoped, postFiles, true)
674
+ : await ownedLegacyPostTree(entry.target, postFiles, requireComplete))
675
+ return result;
484
676
  }
485
- else if (journal.version >= 2 &&
486
- (current === entry.afterImage ||
487
- (await ownedPostTree(entry.target, entry.postFiles ?? [], journal.version < 4 || entry.replacementStarted === true || !entry.removalPending))))
488
- return current;
489
677
  throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
490
678
  }
491
- async function removeOwnedTarget(directory, entry, journal, options, restoringBefore) {
492
- await assertUnexcludedTargets(journal.root, [entry.target], options);
493
- const current = await verifyTarget(directory, entry, journal);
494
- options.validateMutation?.();
495
- options.signal?.throwIfAborted();
496
- if (restoringBefore !== undefined && current === restoringBefore)
497
- return false;
498
- // Persist intent before removal, including descendants affected by a recursive delete.
499
- // Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
500
- upgradeRemovalEvidence(journal);
501
- for (const affected of journal.entries) {
502
- if (affected.target === entry.target || isStrictlyInside(entry.target, affected.target)) {
679
+ async function removeOwnedTarget(directory, entry, journal, options, { apply, restoringBefore } = {}) {
680
+ const scoped = isScopedJournal(journal);
681
+ try {
682
+ await assertUnexcludedTargets(journal.root, [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])], options);
683
+ const current = await verifyTarget(directory, entry, journal, options);
684
+ options.validateMutation?.();
685
+ options.signal?.throwIfAborted();
686
+ if (restoringBefore !== undefined && current.value === restoringBefore)
687
+ return false;
688
+ if (scoped && apply && current.value !== current.before)
689
+ throw new Error("Reviewed removal image changed; preserve evidence for review.");
690
+ // Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
691
+ upgradeRemovalEvidence(journal);
692
+ for (const affected of journal.entries) {
693
+ if (affected.target !== entry.target && !isStrictlyInside(entry.target, affected.target))
694
+ continue;
503
695
  affected.removalPending = true;
504
696
  affected.replacementStarted = false;
697
+ if (affected.vacantInstall)
698
+ throw new Error("Transaction removal overlaps a recovery vacancy; preserve evidence for review.");
699
+ if (!current.scoped)
700
+ continue;
701
+ const relative = path.relative(entry.target, affected.target);
702
+ const observed = scopedDescendant(current.scoped, relative);
703
+ if (!observed || observed.kind === "missing")
704
+ continue;
705
+ const observedPath = path.join(entry.target, relative);
706
+ const mayChange = observed.kind === "directory" && observed.children.length > 0;
707
+ if (affected.scopedRemoval) {
708
+ if (mayChange)
709
+ stableScopedIdentity(observedPath, observed.stat);
710
+ continue;
711
+ }
712
+ const image = observed.value === affected.beforeImage
713
+ ? "before"
714
+ : observed.value === affected.afterImage || ownedScopedPostTree(observed, affected.postFiles ?? [], true)
715
+ ? "after"
716
+ : undefined;
717
+ if (!image)
718
+ continue;
719
+ affected.scopedRemoval = {
720
+ image,
721
+ identity: mayChange ? stableScopedIdentity(observedPath, observed.stat) : scopedIdentity(observed.stat),
722
+ };
723
+ }
724
+ options.validateMutation?.();
725
+ options.signal?.throwIfAborted();
726
+ await persistJournal(directory, journal);
727
+ const verified = await verifyTarget(directory, entry, journal, options);
728
+ options.validateMutation?.();
729
+ options.signal?.throwIfAborted();
730
+ if (restoringBefore !== undefined && verified.value === restoringBefore)
731
+ return false;
732
+ if (current.scoped) {
733
+ if (current.value !== verified.value)
734
+ throw new Error("Transaction removal image changed.");
735
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
736
+ await removeScopedImage(entry.target, current.scoped, options);
737
+ }
738
+ else {
739
+ await fs.rm(entry.target, { recursive: true, force: true });
505
740
  }
741
+ await syncDirectory(path.dirname(entry.target));
742
+ return true;
743
+ }
744
+ catch (error) {
745
+ if (!scoped)
746
+ throw error;
747
+ throw new ScopedRemovalError("Scoped transaction removal stopped; preserve transaction and backup for review.", {
748
+ cause: error,
749
+ });
506
750
  }
507
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
508
- const verified = await verifyTarget(directory, entry, journal);
509
- options.validateMutation?.();
510
- options.signal?.throwIfAborted();
511
- if (restoringBefore !== undefined && verified === restoringBefore)
512
- return false;
513
- await fs.rm(entry.target, { recursive: true, force: true });
514
- await syncDirectory(path.dirname(entry.target));
515
- return true;
516
751
  }
517
752
  function upgradeRemovalEvidence(journal) {
518
753
  if (journal.version < JOURNAL_VERSION) {
@@ -531,8 +766,9 @@ async function retireRemovalIntent(directory, journal, entries, options) {
531
766
  for (const entry of entries) {
532
767
  entry.removalPending = false;
533
768
  entry.replacementStarted = true;
769
+ delete entry.scopedRemoval;
534
770
  }
535
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
771
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
536
772
  options.validateMutation?.();
537
773
  options.signal?.throwIfAborted();
538
774
  }
@@ -546,212 +782,20 @@ async function retireRestorationIntent(directory, journal, entry, options) {
546
782
  }
547
783
  await retireRemovalIntent(directory, journal, [entry], options);
548
784
  }
549
- function recoveryStagePath(directory, entry) {
550
- const token = createHash("sha256").update(directory).update("\\0").update(entry.backupName).digest("hex");
551
- return path.join(path.dirname(entry.target), `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`);
552
- }
553
- async function prepareRecoveryStage(directory, journal, entry, options) {
554
- const temporary = recoveryStagePath(directory, entry);
555
- if (!entry.recoveryStaged) {
556
- try {
557
- await fs.lstat(temporary);
558
- throw new Error("Unowned recovery staging path; preserve evidence for review.");
559
- }
560
- catch (error) {
561
- if (error.code !== "ENOENT")
562
- throw error;
563
- }
564
- options.validateMutation?.();
565
- options.signal?.throwIfAborted();
566
- entry.recoveryStaged = true;
567
- await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
568
- options.validateMutation?.();
569
- options.signal?.throwIfAborted();
570
- }
571
- return temporary;
785
+ function persistJournal(directory, journal) {
786
+ return writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
572
787
  }
573
- async function beforeImage(directory, entry) {
788
+ async function legacyBeforeImage(directory, entry) {
574
789
  if (entry.kind === "missing")
575
790
  return "missing";
791
+ const backup = path.join(directory, "before", entry.backupName);
576
792
  if (entry.kind === "symlink")
577
793
  return `symlink:${entry.linkTarget}`;
578
- const value = await image(path.join(directory, "before", entry.backupName));
794
+ const value = await legacyImage(backup);
579
795
  if (value === "missing")
580
796
  throw new Error("Transaction backup is missing; preserve evidence for review.");
581
797
  return value;
582
798
  }
583
- async function image(target, durable = false) {
584
- let stat;
585
- try {
586
- stat = await fs.lstat(target);
587
- }
588
- catch (error) {
589
- const code = error.code;
590
- if (code === "ENOENT" || code === "ENOTDIR")
591
- return "missing";
592
- throw error;
593
- }
594
- if (stat.isSymbolicLink())
595
- return `symlink:${await fs.readlink(target)}`;
596
- if (stat.isFile()) {
597
- const content = await fs.readFile(target);
598
- if (durable) {
599
- // Keep POSIX read-only backup permissions; Windows flushing requires write access.
600
- const handle = await fs.open(target, process.platform === "win32" ? "r+" : "r");
601
- try {
602
- await handle.sync();
603
- }
604
- finally {
605
- await handle.close();
606
- }
607
- }
608
- return fileImage(content);
609
- }
610
- if (!stat.isDirectory())
611
- throw new Error("Unsupported transaction image.");
612
- const entries = [];
613
- for (const name of (await fs.readdir(target)).sort())
614
- entries.push([name, await image(path.join(target, name), durable)]);
615
- if (durable)
616
- await syncDirectory(target);
617
- return `directory:${createHash("sha256").update(JSON.stringify(entries)).digest("hex")}`;
618
- }
619
- async function ownedPostTree(target, files, requireComplete) {
620
- if (!files.length)
621
- return false;
622
- const expected = new Map(files.map((file) => [mergePathIdentity(file.relative), file.image]));
623
- const prefixes = new Set();
624
- for (const relative of expected.keys()) {
625
- for (let parent = path.dirname(relative); parent !== "." && parent !== path.dirname(parent); parent = path.dirname(parent))
626
- prefixes.add(parent);
627
- }
628
- const seen = new Set();
629
- async function visit(directory) {
630
- let stat;
631
- try {
632
- stat = await fs.lstat(directory);
633
- }
634
- catch {
635
- return false;
636
- }
637
- if (!stat.isDirectory() || stat.isSymbolicLink())
638
- return false;
639
- for (const name of await fs.readdir(directory)) {
640
- const child = path.join(directory, name);
641
- const relative = mergePathIdentity(path.relative(target, child));
642
- const stat = await fs.lstat(child);
643
- if (stat.isDirectory() && !stat.isSymbolicLink()) {
644
- if (!prefixes.has(relative) || !(await visit(child)))
645
- return false;
646
- }
647
- else {
648
- if (expected.get(relative) !== (await image(child)))
649
- return false;
650
- seen.add(relative);
651
- }
652
- }
653
- return true;
654
- }
655
- return (await visit(target)) && (!requireComplete || [...expected.keys()].every((key) => seen.has(key)));
656
- }
657
- function validateJournal(directory, journal, sessionDir) {
658
- if (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) ||
659
- !Array.isArray(journal.entries) ||
660
- journal.entries.length > 16_384)
661
- throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
662
- if (journal.exclude !== undefined && !Array.isArray(journal.exclude))
663
- throw new Error("Invalid transaction exclude policy; preserve evidence.");
664
- normalizeSyncExclude(journal.exclude);
665
- if (journal.completed !== undefined && (![6, 7].includes(journal.version) || journal.completed !== true))
666
- throw new Error("Invalid transaction completion evidence.");
667
- const root = path.resolve(agentDir());
668
- if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
669
- throw new Error("Transaction root no longer matches the Pi agent directory.");
670
- if (journal.sessionRootTransition !== undefined) {
671
- if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
672
- throw new Error("Invalid session root-transition version.");
673
- validateSessionRootTransition(journal.sessionRootTransition);
674
- }
675
- else if (journal.version === 7)
676
- throw new Error("Missing session root-transition evidence.");
677
- const trustedSessionRoot = sessionDir
678
- ? path.resolve(sessionStorageRoot(root, sessionDir))
679
- : path.join(root, "sessions");
680
- if (journal.sessionRoot !== undefined &&
681
- (typeof journal.sessionRoot !== "string" ||
682
- !path.isAbsolute(journal.sessionRoot) ||
683
- path.resolve(journal.sessionRoot) !== journal.sessionRoot ||
684
- (!journal.completed && transactionHasSessionTargets(journal) && journal.sessionRoot !== trustedSessionRoot)))
685
- throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
686
- for (const entry of journal.entries) {
687
- if (!entry ||
688
- typeof entry.target !== "string" ||
689
- !path.isAbsolute(entry.target) ||
690
- path.resolve(entry.target) !== entry.target ||
691
- typeof entry.backupName !== "string" ||
692
- !/^\d+$/u.test(entry.backupName) ||
693
- !["missing", "file", "directory", "symlink"].includes(entry.kind))
694
- throw new Error("Invalid pi-sync transaction entry.");
695
- assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
696
- assertAllowedTarget(root, journal.sessionRoot, entry.target);
697
- if (entry.afterTarget !== undefined &&
698
- (![5, 6, 7].includes(journal.version) ||
699
- typeof entry.afterTarget !== "string" ||
700
- !isCaseReplacement(root, entry.target, entry.afterTarget) ||
701
- path.resolve(entry.afterTarget) !== entry.afterTarget ||
702
- entry.kind !== "file"))
703
- throw new Error("Invalid transaction case replacement evidence.");
704
- if (entry.afterTarget)
705
- assertAllowedTarget(root, journal.sessionRoot, entry.afterTarget);
706
- if (journal.version >= 2 &&
707
- ((entry.beforeImage === undefined ? !journal.completed : typeof entry.beforeImage !== "string") ||
708
- (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
709
- (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
710
- throw new Error("Invalid transaction postimage evidence.");
711
- if (entry.recoveryStaged !== undefined && typeof entry.recoveryStaged !== "boolean")
712
- throw new Error("Invalid recovery staging evidence.");
713
- if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
714
- throw new Error("Invalid transaction removal evidence.");
715
- if (entry.replacementStarted !== undefined &&
716
- (journal.version < 4 || typeof entry.replacementStarted !== "boolean"))
717
- throw new Error("Invalid transaction replacement evidence.");
718
- if (entry.removalPending && entry.replacementStarted)
719
- throw new Error("Conflicting transaction replacement evidence.");
720
- for (const file of entry.postFiles ?? []) {
721
- if (typeof file.relative !== "string" ||
722
- typeof file.image !== "string" ||
723
- !isStrictlyInside(entry.target, path.resolve(entry.target, file.relative)))
724
- throw new Error("Invalid transaction subtree evidence.");
725
- }
726
- }
727
- }
728
- function transactionHasSessionTargets(journal) {
729
- const root = path.resolve(agentDir());
730
- return (Array.isArray(journal.entries) &&
731
- journal.entries.some((entry) => typeof entry?.target === "string" &&
732
- (!isPathInside(root, entry.target) ||
733
- isPathInside(path.join(root, "sessions"), entry.target) ||
734
- (typeof journal.sessionRoot === "string" && isPathInside(journal.sessionRoot, entry.target)))));
735
- }
736
- function isStrictlyInside(root, target) {
737
- return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
738
- }
739
- function assertAllowedTarget(root, sessionRoot, target) {
740
- const resolved = path.resolve(target);
741
- if (isStrictlyInside(root, resolved)) {
742
- if (isDeniedPath(path.relative(root, resolved)))
743
- throw new Error("Transaction targets denied private storage.");
744
- assertWithinRoot(root, resolved);
745
- return;
746
- }
747
- if (sessionRoot && isStrictlyInside(sessionRoot, resolved)) {
748
- if (isDeniedPath(`sessions/${path.relative(sessionRoot, resolved)}`))
749
- throw new Error("Transaction targets denied session storage.");
750
- assertWithinRoot(sessionRoot, resolved);
751
- return;
752
- }
753
- throw new Error("Transaction target is outside configured roots.");
754
- }
755
799
  async function assertSafeParents(root, sessionRoot, target) {
756
800
  assertAllowedTarget(root, sessionRoot, target);
757
801
  const boundary = isPathInside(root, target) ? root : sessionRoot;
@@ -773,8 +817,12 @@ async function assertSafeParents(root, sessionRoot, target) {
773
817
  async function completeTransaction(directory, journal) {
774
818
  // Publish completion before deleting any backup. A surviving journal after power loss
775
819
  // may only retry cleanup, never roll back already accepted files.
776
- await writeJson(path.join(directory, "journal.json"), { ...journal, version: journal.sessionRootTransition ? 7 : 6, completed: true }, {
777
- maxBytes: 32 * 1024 * 1024,
820
+ await writeJson(path.join(directory, "journal.json"), {
821
+ ...journal,
822
+ version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
823
+ completed: true,
824
+ }, {
825
+ maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
778
826
  });
779
827
  await removeTransaction(directory);
780
828
  }