@narumitw/pi-sync-daemon 0.7.0 → 0.8.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 (74) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +16 -2
  3. package/dist/consent.js +21 -6
  4. package/dist/engine/backends/git/git-backend.d.ts +1 -1
  5. package/dist/engine/backends/git/git-backend.js +17 -2
  6. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  7. package/dist/engine/backends/git/git-storage.js +30 -9
  8. package/dist/engine/backends/s3/s3-backend.js +8 -0
  9. package/dist/engine/backends/sync-backend.d.ts +1 -0
  10. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  11. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  12. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  13. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  14. package/dist/engine/ignore/ignore-edit.js +102 -0
  15. package/dist/engine/ignore/ignore-initialization.d.ts +6 -0
  16. package/dist/engine/ignore/ignore-initialization.js +186 -0
  17. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  18. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  19. package/dist/engine/ignore/ignore-settings.d.ts +15 -0
  20. package/dist/engine/ignore/ignore-settings.js +322 -0
  21. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  22. package/dist/engine/ignore/ignore-source.js +250 -0
  23. package/dist/engine/settings/config-file.d.ts +9 -2
  24. package/dist/engine/settings/config-file.js +124 -28
  25. package/dist/engine/settings/config.d.ts +3 -0
  26. package/dist/engine/settings/config.js +93 -7
  27. package/dist/engine/settings/settings-management.d.ts +2 -2
  28. package/dist/engine/settings/settings-management.js +16 -8
  29. package/dist/engine/settings/settings-types.d.ts +23 -2
  30. package/dist/engine/settings/settings-validation.js +23 -5
  31. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  32. package/dist/engine/snapshot/session-paths.js +36 -13
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  34. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  35. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  36. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  37. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  38. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  39. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  40. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  41. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +24 -1
  42. package/dist/engine/snapshot/snapshot-transaction-policy.js +106 -2
  43. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  44. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  45. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  46. package/dist/engine/snapshot/snapshot-transaction.js +86 -108
  47. package/dist/engine/snapshot/snapshot-types.d.ts +23 -1
  48. package/dist/engine/snapshot/snapshot-types.js +9 -1
  49. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  50. package/dist/engine/snapshot/snapshot.js +91 -34
  51. package/dist/engine/state/state-types.d.ts +1 -0
  52. package/dist/engine/sync/continuous-sync.js +18 -3
  53. package/dist/engine/sync/continuous-watch.js +4 -1
  54. package/dist/engine/sync/initialization.js +3 -2
  55. package/dist/engine/sync/local-fields.d.ts +3 -1
  56. package/dist/engine/sync/local-fields.js +62 -1
  57. package/dist/engine/sync/merge-apply.js +35 -7
  58. package/dist/engine/sync/merge-journal.d.ts +18 -4
  59. package/dist/engine/sync/merge-journal.js +115 -8
  60. package/dist/engine/sync/merged-sync.d.ts +1 -1
  61. package/dist/engine/sync/merged-sync.js +103 -50
  62. package/dist/engine/sync/remote-snapshot.d.ts +9 -2
  63. package/dist/engine/sync/remote-snapshot.js +56 -17
  64. package/dist/engine/sync/sync-inspection.js +7 -5
  65. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  66. package/dist/engine/sync/sync-mutations.js +110 -47
  67. package/dist/engine/sync/sync-policy.d.ts +24 -8
  68. package/dist/engine/sync/sync-policy.js +127 -16
  69. package/dist/engine/sync/sync-queries.js +8 -1
  70. package/dist/engine/sync/sync-state.d.ts +2 -2
  71. package/dist/engine/sync/sync-state.js +20 -2
  72. package/dist/engine-service.js +24 -2
  73. package/docs/architecture.md +22 -0
  74. package/package.json +2 -1
@@ -1,7 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
- import { isPathInside } from "../paths.js";
5
4
  import { syncDirectory, writeJson } from "../state/json-file.js";
6
5
  import { withLock } from "../state/lock.js";
7
6
  import { syncMutationParents } from "../state/mutation-directory-sync.js";
@@ -18,10 +17,11 @@ import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-q
18
17
  import { sessionStorageRoot } from "./snapshot-paths.js";
19
18
  import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
20
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
21
- import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, readTransactionJournal, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
20
+ import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
22
21
  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";
22
+ import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
24
23
  import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
24
+ import { verifyTarget } from "./snapshot-transaction-verification.js";
25
25
  const JOURNAL_VERSION = 4;
26
26
  class ScopedRemovalError extends Error {
27
27
  }
@@ -29,9 +29,10 @@ export async function applySnapshotTransaction(plan, options = {}) {
29
29
  options.validateMutation?.();
30
30
  const root = path.resolve(agentDir());
31
31
  if (options.scope === "agent-directory") {
32
- const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root));
32
+ const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root, options));
33
33
  options = { ...options, sessionDir: sessionStorageRoot(root, sessionDir) };
34
34
  }
35
+ const validateIgnorePolicy = ignorePolicyValidator(options);
35
36
  await recoverPendingSnapshotTransactions(options);
36
37
  const coalesced = await coalesceCaseReplacements(root, plan);
37
38
  options.validateMutation?.();
@@ -40,10 +41,11 @@ export async function applySnapshotTransaction(plan, options = {}) {
40
41
  if (targets.length > 16_384)
41
42
  throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
42
43
  return withTargetQueues(targets, options, async (heldKeys) => {
44
+ if (validateIgnorePolicy)
45
+ await validateIgnorePolicy();
43
46
  await assertUnexcludedTargets(root, [...targets, ...coalesced.replacements.values()], options);
44
47
  options.signal?.throwIfAborted();
45
- if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
46
- isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
48
+ if (targets.some((target) => touchesProtectedTarget(target, options.protectedTargets)))
47
49
  throw new Error("Snapshot transaction targets the current session; review is required.");
48
50
  for (const [before, after] of coalesced.replacements) {
49
51
  if ((await caseReplacementSpelling(before, after)) !== before)
@@ -53,6 +55,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
53
55
  }
54
56
  const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
55
57
  const scoped = options.scope === "agent-directory";
58
+ /** Fresh apply authorization only; recovery remains bound to durable journal images. */
56
59
  const expectedPreimages = new Map([...(options.expectedPreimages ?? [])]
57
60
  .filter(([target]) => !scoped || !originalTargets.has(target))
58
61
  .map(([target, expected]) => [originalTargets.get(target) ?? target, expected]));
@@ -88,7 +91,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
88
91
  }
89
92
  }
90
93
  for (const [target, expected] of expectedPreimages) {
91
- if (scoped)
94
+ if (scoped || options.reservedIgnoreNames?.length)
92
95
  await assertUnexcludedTargets(root, [target], options);
93
96
  const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
94
97
  options.validateMutation?.();
@@ -96,6 +99,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
96
99
  if (current !== expected)
97
100
  throw new Error("Reviewed file preimage changed before apply; snapshot installation refused.");
98
101
  }
102
+ if (validateIgnorePolicy)
103
+ await validateIgnorePolicy();
99
104
  const transaction = await prepareTransaction(coalesced.plan, targets, { ...options, expectedPreimages }, coalesced.replacements);
100
105
  const entriesByTarget = new Map(transaction.journal.entries.flatMap((entry) => [
101
106
  [entry.target, entry],
@@ -117,8 +122,12 @@ export async function applySnapshotTransaction(plan, options = {}) {
117
122
  await withMissingTargetQueues(transaction.journal.entries
118
123
  .filter((entry) => entry.removalPending)
119
124
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
125
+ if (validateIgnorePolicy)
126
+ await validateIgnorePolicy();
120
127
  if (scoped && plan.writes.length)
121
128
  await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
129
+ if (validateIgnorePolicy)
130
+ await validateIgnorePolicy();
122
131
  await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
123
132
  // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
124
133
  const uninstalledWrites = new Set(transaction.deletedWrites);
@@ -128,11 +137,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
128
137
  if (!entry)
129
138
  throw new Error("Unowned transaction target.");
130
139
  const deletedByThisCall = uninstalledWrites.delete(entry.target);
131
- if (options.scope === "agent-directory")
140
+ if (options.scope === "agent-directory" || options.reservedIgnoreNames?.length)
132
141
  await assertUnexcludedTargets(transaction.journal.root, [item.target], options);
133
142
  await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
134
143
  options.validateMutation?.();
135
144
  options.signal?.throwIfAborted();
145
+ if (validateIgnorePolicy)
146
+ await validateIgnorePolicy();
136
147
  await fs.mkdir(path.dirname(item.target), { recursive: true });
137
148
  options.validateMutation?.();
138
149
  options.signal?.throwIfAborted();
@@ -156,9 +167,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
156
167
  finally {
157
168
  await handle.close();
158
169
  }
159
- await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
170
+ const verified = await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
160
171
  options.signal?.throwIfAborted();
161
172
  options.validateMutation?.();
173
+ if (validateIgnorePolicy && verified.scoped) {
174
+ await validateIgnorePolicy();
175
+ await recheckScopedImage(item.target, verified.scoped, options);
176
+ }
162
177
  await fs.rename(temp, item.target);
163
178
  await syncDirectory(path.dirname(item.target));
164
179
  }
@@ -171,13 +186,17 @@ export async function applySnapshotTransaction(plan, options = {}) {
171
186
  await syncMutationParents(targets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
172
187
  options.validateMutation?.();
173
188
  options.signal?.throwIfAborted();
189
+ if (validateIgnorePolicy)
190
+ await validateIgnorePolicy();
174
191
  });
192
+ if (validateIgnorePolicy)
193
+ await validateIgnorePolicy();
175
194
  }
176
195
  catch (error) {
177
196
  // Aborted owners cannot roll back files after another session has replaced them.
178
197
  if (options.signal?.aborted)
179
198
  throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
180
- if (error instanceof ScopedRemovalError)
199
+ if (error instanceof ScopedRemovalError || error instanceof StaleIgnorePolicyError)
181
200
  throw error;
182
201
  // Additional queues have been released. Recovery must reserve missing keys afresh.
183
202
  if (changesQueueKey)
@@ -226,14 +245,16 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
226
245
  throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
227
246
  }
228
247
  validateJournalPolicy(journal);
229
- if (!journal.completed)
248
+ if (!journal.completed) {
230
249
  assertRecoveryPolicy(journal, options);
250
+ ignorePolicyValidator(options);
251
+ }
231
252
  let sessionDir = options.sessionDir;
232
253
  if (sessionDir === undefined && !journal.completed) {
233
254
  if (options.scope === "agent-directory")
234
- sessionDir = await agentDirectoryConfiguredSessionDir(options.signal);
255
+ sessionDir = await agentDirectoryConfiguredSessionDir(options.signal, agentDir(), options);
235
256
  else if (options.resolveConfiguredSessionDir && transactionHasSessionTargets(journal))
236
- sessionDir = await configuredSessionDir();
257
+ sessionDir = await configuredSessionDir(options);
237
258
  }
238
259
  options.validateMutation?.();
239
260
  options.signal?.throwIfAborted();
@@ -256,6 +277,7 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
256
277
  const { sessionDir } = options;
257
278
  const root = path.resolve(agentDir());
258
279
  const wholeDirectory = options.scope === "agent-directory";
280
+ const ignoreSource = options.ignorePolicy ? ignoreSourceBinding(options.ignorePolicy) : undefined;
259
281
  const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
260
282
  const indexed = indexTransactionPlan(plan, targets);
261
283
  const directory = path.join(transactionRoot(), randomUUID());
@@ -267,7 +289,7 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
267
289
  options.validateMutation?.();
268
290
  assertAllowedTarget(root, sessionRoot, target);
269
291
  await assertSafeParents(root, sessionRoot, target);
270
- if (wholeDirectory)
292
+ if (wholeDirectory || options.reservedIgnoreNames?.length)
271
293
  await assertUnexcludedTargets(root, [target], options);
272
294
  const entry = { target, backupName: `${index}`, kind: "missing" };
273
295
  if (replacements.has(target))
@@ -305,14 +327,17 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
305
327
  ? undefined
306
328
  : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
307
329
  const journal = {
308
- version: wholeDirectory
309
- ? AGENT_DIRECTORY_JOURNAL_VERSION
310
- : sessionRootTransition
311
- ? 7
312
- : replacements.size
313
- ? 5
314
- : JOURNAL_VERSION,
330
+ version: ignoreSource
331
+ ? IGNORE_POLICY_JOURNAL_VERSION
332
+ : wholeDirectory
333
+ ? AGENT_DIRECTORY_JOURNAL_VERSION
334
+ : sessionRootTransition
335
+ ? 7
336
+ : replacements.size
337
+ ? 5
338
+ : JOURNAL_VERSION,
315
339
  root,
340
+ ignoreSource,
316
341
  ...(wholeDirectory
317
342
  ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
318
343
  : options.exclude === undefined
@@ -392,12 +417,16 @@ async function restoreTransaction(directory, journal, options, heldKeys) {
392
417
  async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
393
418
  validateJournal(directory, journal, options.sessionDir);
394
419
  const scoped = isScopedJournal(journal);
420
+ const validateIgnorePolicy = ignorePolicyValidator(options);
395
421
  options.validateMutation?.();
396
422
  options.signal?.throwIfAborted();
423
+ if (validateIgnorePolicy) {
424
+ assertRecoveryPolicy(journal, options);
425
+ await validateIgnorePolicy();
426
+ }
397
427
  await assertUnexcludedTargets(journal.root, journal.entries.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), options);
398
428
  for (const entry of journal.entries) {
399
- if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
400
- isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
429
+ if (touchesProtectedTarget(entry.target, options.protectedTargets))
401
430
  throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
402
431
  const { value, before } = await verifyTarget(directory, entry, journal, options);
403
432
  if (scoped) {
@@ -430,7 +459,7 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
430
459
  options.validateMutation?.();
431
460
  options.signal?.throwIfAborted();
432
461
  }
433
- if (scoped && journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION) {
462
+ if (scoped && journal.version < AGENT_DIRECTORY_JOURNAL_VERSION) {
434
463
  journal.version = AGENT_DIRECTORY_JOURNAL_VERSION;
435
464
  for (const entry of journal.entries)
436
465
  delete entry.recoveryStaged;
@@ -443,8 +472,11 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
443
472
  const { value: current, before } = await verifyTarget(directory, entry, journal, options);
444
473
  const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
445
474
  if (current === before && (await spellingMatches())) {
446
- if (entry.recoveryWorkspace)
475
+ if (entry.recoveryWorkspace) {
476
+ if (validateIgnorePolicy)
477
+ await validateIgnorePolicy();
447
478
  await cleanScopedWorkspace(directory, entry, options);
479
+ }
448
480
  continue;
449
481
  }
450
482
  options.signal?.throwIfAborted();
@@ -556,15 +588,23 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
556
588
  await syncMutationParents(journal.entries.map((entry) => entry.target), [journal.root, ...(journal.sessionRoot ? [journal.sessionRoot] : [])], options);
557
589
  options.validateMutation?.();
558
590
  options.signal?.throwIfAborted();
591
+ if (validateIgnorePolicy)
592
+ await validateIgnorePolicy();
559
593
  await completeTransaction(directory, journal);
560
594
  }
561
595
  async function restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches) {
596
+ const validateIgnorePolicy = ignorePolicyValidator(options);
562
597
  options.validateMutation?.();
563
598
  options.signal?.throwIfAborted();
599
+ if (validateIgnorePolicy)
600
+ await validateIgnorePolicy();
564
601
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
565
602
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
566
- if (!entry.vacantInstall)
603
+ if (!entry.vacantInstall) {
604
+ if (validateIgnorePolicy)
605
+ await validateIgnorePolicy();
567
606
  await buildScopedRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
607
+ }
568
608
  const verifyStage = async () => {
569
609
  const stage = await inspectScopedRecoveryStage(directory, entry, options, true);
570
610
  if (!stage || stage.image.kind === "missing" || stage.image.value !== before || stage.partial.kind !== "missing")
@@ -572,7 +612,7 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
572
612
  if (entry.vacantInstall && scopedIdentity(stage.image.stat) !== entry.vacantInstall)
573
613
  throw new Error("Recovery vacancy has a different staging image; preserve evidence for review.");
574
614
  const identity = stableScopedIdentity(stage.payload, stage.image.stat);
575
- return { payload: stage.payload, identity };
615
+ return { payload: stage.payload, identity, image: stage.image };
576
616
  };
577
617
  await verifyStage();
578
618
  const { value: verified } = await verifyTarget(directory, entry, journal, options);
@@ -587,6 +627,8 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
587
627
  }))) {
588
628
  const queueTargets = needsVacantTarget ? [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])] : [];
589
629
  await withMissingTargetQueues(queueTargets, heldKeys, options, async () => {
630
+ if (validateIgnorePolicy)
631
+ await validateIgnorePolicy();
590
632
  const { value: atRename } = await verifyTarget(directory, entry, journal, options);
591
633
  if (atRename === before && (await spellingMatches()))
592
634
  return;
@@ -594,6 +636,8 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
594
636
  throw new Error("Transaction target changed after removal; preserve evidence for review.");
595
637
  const stage = await verifyStage();
596
638
  if (needsVacantTarget && !entry.vacantInstall) {
639
+ if (validateIgnorePolicy)
640
+ await validateIgnorePolicy();
597
641
  entry.vacantInstall = stage.identity;
598
642
  delete entry.removalPending;
599
643
  delete entry.replacementStarted;
@@ -612,13 +656,18 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
612
656
  }
613
657
  if ((await scopedPathIdentity(stage.payload, options)) !== stage.identity)
614
658
  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()))
659
+ const atInstall = await verifyTarget(directory, entry, journal, options);
660
+ if (atInstall.value === before && (await spellingMatches()))
617
661
  return;
618
- if (atInstall !== atRename)
662
+ if (atInstall.value !== atRename)
619
663
  throw new Error("Transaction target changed before restoration; preserve evidence for review.");
620
664
  options.validateMutation?.();
621
665
  options.signal?.throwIfAborted();
666
+ if (validateIgnorePolicy && atInstall.scoped) {
667
+ await validateIgnorePolicy();
668
+ await recheckScopedImage(stage.payload, stage.image, options);
669
+ await recheckScopedImage(entry.target, atInstall.scoped, options);
670
+ }
622
671
  await fs.rename(stage.payload, entry.target);
623
672
  await syncDirectory(path.dirname(entry.target));
624
673
  await syncDirectory(path.dirname(stage.payload));
@@ -627,58 +676,16 @@ async function restoreScopedEntry(directory, journal, entry, options, heldKeys,
627
676
  });
628
677
  }
629
678
  }
679
+ if (validateIgnorePolicy)
680
+ await validateIgnorePolicy();
630
681
  await cleanScopedWorkspace(directory, entry, options);
631
682
  }
632
- async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
633
- await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
634
- const isScoped = isScopedJournal(journal);
635
- // Hash the potentially large backup before observing the live target, not after it.
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))
641
- throw new Error("Transaction backup changed; preserve evidence for review.");
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;
676
- }
677
- throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
678
- }
679
683
  async function removeOwnedTarget(directory, entry, journal, options, { apply, restoringBefore } = {}) {
680
684
  const scoped = isScopedJournal(journal);
685
+ const validateIgnorePolicy = ignorePolicyValidator(options);
681
686
  try {
687
+ if (validateIgnorePolicy)
688
+ await validateIgnorePolicy();
682
689
  await assertUnexcludedTargets(journal.root, [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])], options);
683
690
  const current = await verifyTarget(directory, entry, journal, options);
684
691
  options.validateMutation?.();
@@ -733,7 +740,7 @@ async function removeOwnedTarget(directory, entry, journal, options, { apply, re
733
740
  if (current.value !== verified.value)
734
741
  throw new Error("Transaction removal image changed.");
735
742
  await assertUnexcludedTargets(journal.root, [entry.target], options);
736
- await removeScopedImage(entry.target, current.scoped, options);
743
+ await removeScopedImage(entry.target, current.scoped, options, validateIgnorePolicy);
737
744
  }
738
745
  else {
739
746
  await fs.rm(entry.target, { recursive: true, force: true });
@@ -742,7 +749,7 @@ async function removeOwnedTarget(directory, entry, journal, options, { apply, re
742
749
  return true;
743
750
  }
744
751
  catch (error) {
745
- if (!scoped)
752
+ if (!scoped || error instanceof StaleIgnorePolicyError)
746
753
  throw error;
747
754
  throw new ScopedRemovalError("Scoped transaction removal stopped; preserve transaction and backup for review.", {
748
755
  cause: error,
@@ -785,35 +792,6 @@ async function retireRestorationIntent(directory, journal, entry, options) {
785
792
  function persistJournal(directory, journal) {
786
793
  return writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
787
794
  }
788
- async function legacyBeforeImage(directory, entry) {
789
- if (entry.kind === "missing")
790
- return "missing";
791
- const backup = path.join(directory, "before", entry.backupName);
792
- if (entry.kind === "symlink")
793
- return `symlink:${entry.linkTarget}`;
794
- const value = await legacyImage(backup);
795
- if (value === "missing")
796
- throw new Error("Transaction backup is missing; preserve evidence for review.");
797
- return value;
798
- }
799
- async function assertSafeParents(root, sessionRoot, target) {
800
- assertAllowedTarget(root, sessionRoot, target);
801
- const boundary = isPathInside(root, target) ? root : sessionRoot;
802
- for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
803
- if (path.dirname(parent) === parent)
804
- throw new Error("Transaction parent did not reach its owned boundary.");
805
- try {
806
- const stat = await fs.lstat(parent);
807
- if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
808
- throw new Error("Unsafe transaction parent.");
809
- }
810
- catch (error) {
811
- const code = error.code;
812
- if (code !== "ENOENT" && code !== "ENOTDIR")
813
- throw error;
814
- }
815
- }
816
- }
817
795
  async function completeTransaction(directory, journal) {
818
796
  // Publish completion before deleting any backup. A surviving journal after power loss
819
797
  // may only retry cleanup, never roll back already accepted files.
@@ -3,9 +3,30 @@ export interface SnapshotFile {
3
3
  contentBase64: string;
4
4
  sha256: string;
5
5
  }
6
+ export interface EffectiveIgnorePolicy {
7
+ filename: string;
8
+ sourceDigest: string;
9
+ fingerprint: string;
10
+ sessions: boolean;
11
+ reservedNames: readonly string[];
12
+ matches(path: string, directory?: boolean): boolean;
13
+ }
6
14
  export interface DirectoryScope {
7
15
  scope?: "agent-directory";
8
16
  reinclude?: readonly string[];
17
+ ignorePolicy?: EffectiveIgnorePolicy;
18
+ reservedIgnoreNames?: readonly string[];
19
+ }
20
+ export declare const IGNORE_SNAPSHOT_VERSION = 6;
21
+ export declare function isSupportedSnapshotVersion(version: unknown): version is 1 | 2 | 3 | 4 | 5 | 6;
22
+ export interface IgnoreSnapshotSelection {
23
+ version: 4;
24
+ scope: "agent-directory";
25
+ fingerprint: string;
26
+ sessions: boolean;
27
+ include?: never;
28
+ exclude?: never;
29
+ reinclude?: never;
9
30
  }
10
31
  export type SnapshotSelection = {
11
32
  version: 1;
@@ -25,7 +46,7 @@ export type SnapshotSelection = {
25
46
  include: string[];
26
47
  exclude: string[];
27
48
  reinclude: string[];
28
- };
49
+ } | IgnoreSnapshotSelection;
29
50
  export interface Snapshot {
30
51
  version: number;
31
52
  id: string;
@@ -52,6 +73,7 @@ export interface SnapshotOptions extends DirectoryScope {
52
73
  signal?: AbortSignal;
53
74
  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
54
75
  validateMutation?: () => void;
76
+ validateIgnorePolicy?: () => Promise<void>;
55
77
  /** Reviewed regular-file preimages; null means the path was absent. Checked under mutation queues. */
56
78
  expectedFileHashes?: Readonly<Record<string, string | null>>;
57
79
  include?: string[];
@@ -1 +1,9 @@
1
- export {};
1
+ export const IGNORE_SNAPSHOT_VERSION = 6;
2
+ export function isSupportedSnapshotVersion(version) {
3
+ return (version === 1 ||
4
+ version === 2 ||
5
+ version === 3 ||
6
+ version === 4 ||
7
+ version === 5 ||
8
+ version === IGNORE_SNAPSHOT_VERSION);
9
+ }
@@ -1,14 +1,15 @@
1
+ import { reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
1
2
  export { isDeniedPath } from "../paths.js";
2
3
  export { sessionStorageRoot } from "./snapshot-paths.js";
3
4
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
4
- import type { AgentDirectoryInventory, Snapshot, SnapshotFile, SnapshotOptions } from "./snapshot-types.js";
5
+ import { type AgentDirectoryInventory, type Snapshot, type SnapshotFile, type SnapshotOptions } from "./snapshot-types.js";
5
6
  export { canonicalSnapshotPathForConfig, isConfiguredSnapshotPath } from "../sync/sync-policy.js";
6
7
  export declare function agentDirectoryInventory(snapshot: Pick<Snapshot, "files">): AgentDirectoryInventory | undefined;
7
8
  export declare function regenerateSnapshotIdentity(snapshot: Snapshot): Snapshot;
8
9
  export declare function createSnapshot(profile: string, options?: SnapshotOptions): Promise<Snapshot>;
9
- export declare function collectFiles(root: string, options?: SnapshotOptions, excluded?: (relativePath: string) => boolean): Promise<SnapshotFile[]>;
10
- export declare function agentDirectoryConfiguredSessionDir(signal?: AbortSignal, root?: string): Promise<string | undefined>;
11
- export declare function readAgentDirectorySettings(signal?: AbortSignal, root?: string): Promise<Buffer<ArrayBuffer> | undefined>;
10
+ export declare function collectFiles(root: string, options?: SnapshotOptions, excluded?: (relativePath: string, directory?: boolean) => boolean): Promise<SnapshotFile[]>;
11
+ export declare function agentDirectoryConfiguredSessionDir(signal?: AbortSignal, root?: string, options?: Pick<SnapshotOptions, "reservedIgnoreNames">): Promise<string | undefined>;
12
+ export declare function readAgentDirectorySettings(signal?: AbortSignal, root?: string, options?: Pick<SnapshotOptions, "reservedIgnoreNames">): Promise<Buffer<ArrayBuffer> | undefined>;
12
13
  export declare function agentDirectorySessionDirFromSettings(content: Buffer): string | undefined;
13
14
  export type AgentDirectoryScanOptions = SyncSelectionConfig & Pick<SnapshotOptions, "sessionDir" | "signal" | "validateMutation">;
14
15
  export declare function scanAgentDirectoryInventory(root: string, options: AgentDirectoryScanOptions, pendingStateEntry?: string): Promise<{
@@ -20,6 +21,7 @@ export declare function scanAgentDirectoryInventory(root: string, options: Agent
20
21
  walkedDirectories: Set<string>;
21
22
  routingDirectories: Set<string>;
22
23
  }>;
24
+ export declare function readLegacySnapshotSource(absolutePath: string, guardReserved: ReturnType<typeof reservedIgnoreTargetGuard>, signal?: AbortSignal): Promise<Buffer<ArrayBuffer>>;
23
25
  export declare function isSessionPath(relativePath: string): boolean;
24
26
  export declare function isSessionFilePath(relativePath: string): boolean;
25
27
  export declare function sessionSnapshotPathFromAbsolute(sessionFile: string, configuredSessionDir?: string): string | undefined;