@narumitw/pi-sync-daemon 0.6.2 → 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 (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +17 -3
  3. package/dist/consent.js +26 -1
  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 +39 -13
  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/paths.js +1 -1
  24. package/dist/engine/settings/config-file.d.ts +9 -2
  25. package/dist/engine/settings/config-file.js +126 -28
  26. package/dist/engine/settings/config.d.ts +5 -4
  27. package/dist/engine/settings/config.js +114 -13
  28. package/dist/engine/settings/settings-management.js +34 -32
  29. package/dist/engine/settings/settings-types.d.ts +40 -5
  30. package/dist/engine/settings/settings-validation.js +52 -24
  31. package/dist/engine/snapshot/session-paths.d.ts +6 -4
  32. package/dist/engine/snapshot/session-paths.js +84 -15
  33. package/dist/engine/snapshot/snapshot-apply.d.ts +7 -8
  34. package/dist/engine/snapshot/snapshot-apply.js +107 -21
  35. package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
  36. package/dist/engine/snapshot/snapshot-bounds.js +20 -0
  37. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  38. package/dist/engine/snapshot/snapshot-codec.js +15 -7
  39. package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
  40. package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +9 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +239 -24
  43. package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
  44. package/dist/engine/snapshot/snapshot-payload.js +10 -0
  45. package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
  46. package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
  47. package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
  48. package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
  49. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +39 -0
  50. package/dist/engine/snapshot/snapshot-transaction-images.js +387 -0
  51. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +73 -0
  52. package/dist/engine/snapshot/snapshot-transaction-policy.js +276 -0
  53. package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
  54. package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
  55. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  56. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  57. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -11
  58. package/dist/engine/snapshot/snapshot-transaction.js +390 -364
  59. package/dist/engine/snapshot/snapshot-types.d.ts +47 -2
  60. package/dist/engine/snapshot/snapshot-types.js +9 -1
  61. package/dist/engine/snapshot/snapshot.d.ts +22 -3
  62. package/dist/engine/snapshot/snapshot.js +357 -43
  63. package/dist/engine/state/merge-baseline-store.js +20 -9
  64. package/dist/engine/state/state-types.d.ts +3 -0
  65. package/dist/engine/sync/apply-review.d.ts +3 -3
  66. package/dist/engine/sync/apply-review.js +5 -4
  67. package/dist/engine/sync/continuous-sync.js +37 -12
  68. package/dist/engine/sync/continuous-watch.d.ts +4 -1
  69. package/dist/engine/sync/continuous-watch.js +90 -15
  70. package/dist/engine/sync/exclude-policy.d.ts +4 -0
  71. package/dist/engine/sync/exclude-policy.js +8 -1
  72. package/dist/engine/sync/initialization.js +9 -4
  73. package/dist/engine/sync/local-fields.d.ts +3 -1
  74. package/dist/engine/sync/local-fields.js +88 -8
  75. package/dist/engine/sync/merge-apply.js +190 -47
  76. package/dist/engine/sync/merge-journal.d.ts +18 -4
  77. package/dist/engine/sync/merge-journal.js +126 -10
  78. package/dist/engine/sync/merged-sync.d.ts +1 -1
  79. package/dist/engine/sync/merged-sync.js +124 -68
  80. package/dist/engine/sync/partial-progress.js +5 -3
  81. package/dist/engine/sync/remote-snapshot.d.ts +10 -2
  82. package/dist/engine/sync/remote-snapshot.js +59 -17
  83. package/dist/engine/sync/session-push.js +7 -6
  84. package/dist/engine/sync/sync-decision.d.ts +4 -0
  85. package/dist/engine/sync/sync-decision.js +17 -2
  86. package/dist/engine/sync/sync-inspection.js +8 -6
  87. package/dist/engine/sync/sync-mutations.d.ts +10 -2
  88. package/dist/engine/sync/sync-mutations.js +245 -101
  89. package/dist/engine/sync/sync-policy.d.ts +36 -10
  90. package/dist/engine/sync/sync-policy.js +285 -20
  91. package/dist/engine/sync/sync-queries.js +49 -32
  92. package/dist/engine/sync/sync-state.d.ts +11 -0
  93. package/dist/engine/sync/sync-state.js +42 -5
  94. package/dist/engine/ui/sync-format.js +22 -7
  95. package/dist/engine-service.js +24 -2
  96. package/docs/architecture.md +28 -0
  97. package/package.json +2 -1
@@ -6,10 +6,11 @@ import { agentDir } from "../snapshot/session-paths.js";
6
6
  import { addTopLevelCaseVariantDeletes } from "../snapshot/snapshot-apply.js";
7
7
  import { throwIfAborted } from "./signals.js";
8
8
  /** Inspect the apply engine's additional alias removals, which logical snapshots omit. */
9
- export async function inspectCaseCleanup(snapshot, signal) {
9
+ export async function inspectCaseCleanup(snapshot, options) {
10
+ const { signal } = options;
10
11
  throwIfAborted(signal);
11
12
  const root = agentDir();
12
- const plan = await addTopLevelCaseVariantDeletes(root, { writes: [], deletes: [] }, snapshot);
13
+ const plan = await addTopLevelCaseVariantDeletes(root, { writes: [], deletes: [] }, snapshot, options);
13
14
  throwIfAborted(signal);
14
15
  const review = [];
15
16
  for (const target of plan.deletes.sort()) {
@@ -44,8 +45,8 @@ export async function inspectCaseCleanup(snapshot, signal) {
44
45
  }
45
46
  return review;
46
47
  }
47
- export async function revalidateCaseCleanup(expected, snapshot, signal) {
48
- const current = await inspectCaseCleanup(snapshot, signal);
48
+ export async function revalidateCaseCleanup(expected, snapshot, options) {
49
+ const current = await inspectCaseCleanup(snapshot, options);
49
50
  if (JSON.stringify(current) !== JSON.stringify(expected))
50
51
  throw new Error("Case-variant paths changed during transfer review; reopen the preview.");
51
52
  }
@@ -1,5 +1,6 @@
1
1
  import { loadConfigForCheck, syncCheckConfigFingerprint } from "../settings/config.js";
2
- import { snapshotOptionsForContext } from "../snapshot/session-paths.js";
2
+ import { resolvedSnapshotOptionsForContext } from "../snapshot/session-paths.js";
3
+ import { ignorePolicyValidator } from "../snapshot/snapshot-transaction-policy.js";
3
4
  import { withLock } from "../state/lock.js";
4
5
  import { withStateDirectoryAccess } from "../state/state-directory.js";
5
6
  import { readStateForConfig } from "../state/sync-state-store.js";
@@ -10,7 +11,7 @@ import { acquireContinuousLease } from "./continuous-lease.js";
10
11
  import { normalizeContinuousClock, readContinuousRecord, reserveContinuousRequest, updateContinuousRecord, } from "./continuous-record.js";
11
12
  import { continuousBinding, hashContinuous } from "./continuous-storage.js";
12
13
  import { watchContinuous } from "./continuous-watch.js";
13
- import { readMergeJournal } from "./merge-journal.js";
14
+ import { assertMergeJournalPolicy, readMergeJournal } from "./merge-journal.js";
14
15
  import { createStartupTimings } from "./startup-timings.js";
15
16
  import { captureMutationOwner } from "./sync-local.js";
16
17
  import { fileHashMap } from "./sync-state.js";
@@ -197,6 +198,17 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
197
198
  if (!ctx.isIdle())
198
199
  throw new DOMException("Owning session became busy", "AbortError");
199
200
  };
201
+ const openWatch = async () => {
202
+ try {
203
+ const { sessionDir } = await resolvedSnapshotOptionsForContext(ctx, config, signal);
204
+ validate();
205
+ return await watchContinuous(config, changed, { sessionDir, signal });
206
+ }
207
+ catch {
208
+ validate();
209
+ return () => { };
210
+ }
211
+ };
200
212
  const stopWatch = () => {
201
213
  closeWatch();
202
214
  wake();
@@ -204,7 +216,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
204
216
  signal.addEventListener("abort", stopWatch, { once: true });
205
217
  let pollDue = 0;
206
218
  try {
207
- closeWatch = await watchContinuous(config, changed);
219
+ closeWatch = await openWatch();
208
220
  validate();
209
221
  while (!signal.aborted && ctx.isIdle()) {
210
222
  validate();
@@ -218,7 +230,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
218
230
  if (syncCheckConfigFingerprint(latest) !== syncCheckConfigFingerprint(config)) {
219
231
  closeWatch();
220
232
  config = latest;
221
- closeWatch = await watchContinuous(config, changed);
233
+ closeWatch = await openWatch();
222
234
  validate();
223
235
  pollDue = 0;
224
236
  }
@@ -231,7 +243,12 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
231
243
  await updateContinuousRecord(binding, lease, (current) => normalizeContinuousClock(current, now));
232
244
  validate();
233
245
  }
234
- const configuration = hashContinuous([{ ...config, showStatus: undefined, debug: undefined }, ctx.model]);
246
+ const configuration = hashContinuous([
247
+ config.ignorePolicy
248
+ ? syncCheckConfigFingerprint(config)
249
+ : { ...config, showStatus: undefined, debug: undefined },
250
+ ctx.model,
251
+ ]);
235
252
  const controlChanged = record.configuration !== configuration;
236
253
  if (controlChanged || explicitRetry) {
237
254
  record.next = 0;
@@ -258,7 +275,9 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
258
275
  // transfer adopt authorization that changed after this cycle's inspection.
259
276
  const validateCycle = (latest) => {
260
277
  validate();
261
- if ((latest && syncCheckConfigFingerprint(latest) !== expectedConfig) ||
278
+ if ((latest &&
279
+ (syncCheckConfigFingerprint(latest) !== expectedConfig ||
280
+ (ctx.backgroundAuthorized && !ctx.backgroundAuthorized(latest)))) ||
262
281
  hashContinuous(ctx.model) !== expectedModel)
263
282
  activeCycle.abort(new DOMException("Continuous authorization changed", "AbortError"));
264
283
  activeCycle.signal.throwIfAborted();
@@ -324,7 +343,7 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
324
343
  pollDue = clock.now() + POLL_MS + Math.floor(clock.random() * 6_000);
325
344
  closeWatch();
326
345
  closeWatch = () => { };
327
- closeWatch = await watchContinuous(config, changed);
346
+ closeWatch = await openWatch();
328
347
  validate();
329
348
  }
330
349
  validate();
@@ -362,6 +381,8 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
362
381
  // A newly pending journal may prove an uncertain commit. It is never authority to republish.
363
382
  const pending = await guardedLock("continuous-journal", () => readMergeJournal(config));
364
383
  validate();
384
+ if (pending)
385
+ assertMergeJournalPolicy(pending, config);
365
386
  if (!force &&
366
387
  !pending &&
367
388
  current.phase === "blocked" &&
@@ -372,21 +393,25 @@ export function createContinuousSync(loaders, clock = systemClock, publish) {
372
393
  validate();
373
394
  const observed = await timings.measure("inspection and guards", () => guardedLock("continuous-check", async () => {
374
395
  validate();
375
- const inspection = await inspectionModule.inspectSync(config, snapshotOptionsForContext(ctx, config), signal, undefined, timings);
396
+ const snapshotOptions = await resolvedSnapshotOptionsForContext(ctx, config, signal);
397
+ validate();
398
+ const validateIgnore = ignorePolicyValidator({ ...snapshotOptions, validateMutation: validate });
399
+ if (validateIgnore)
400
+ await validateIgnore();
401
+ const inspection = await inspectionModule.inspectSync(config, snapshotOptions, signal, undefined, timings);
376
402
  validate();
377
403
  let localIdentity = inspection.localIdentity;
378
404
  if (!localIdentity) {
379
405
  const snapshotModule = await loaders.snapshot();
380
406
  validate();
381
- const local = await snapshotModule.createSnapshot(config.snapshotIdentity, {
382
- ...snapshotOptionsForContext(ctx, config),
383
- signal,
384
- });
407
+ const local = await snapshotModule.createSnapshot(config.snapshotIdentity, snapshotOptions);
385
408
  validate();
386
409
  localIdentity = hashContinuous(fileHashMap(local));
387
410
  }
388
411
  const journal = await readMergeJournal(config);
389
412
  validate();
413
+ if (journal)
414
+ assertMergeJournalPolicy(journal, config);
390
415
  return { inspection, journal, localIdentity };
391
416
  }));
392
417
  validate();
@@ -1,3 +1,6 @@
1
1
  import type { AnySyncConfig } from "../settings/settings-types.js";
2
2
  /** Hints only. The scheduler's periodic snapshot scan remains required. */
3
- export declare function watchContinuous(config: AnySyncConfig, changed: (settings: boolean) => void): Promise<() => void>;
3
+ export declare function watchContinuous(config: AnySyncConfig, changed: (settings: boolean) => void, options?: {
4
+ sessionDir?: string;
5
+ signal?: AbortSignal;
6
+ }): Promise<() => void>;
@@ -3,27 +3,58 @@ import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { getEngineRoot as getAgentDir } from "../host.js";
5
5
  import { isDeniedPath, toPosix } from "../paths.js";
6
+ import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
6
7
  import { compileSyncExclude } from "./exclude-policy.js";
8
+ import { compileSyncPolicyTraversal, configuredSnapshotPathMatcher, syncSessionsSelected } from "./sync-policy.js";
9
+ function relativeWithin(root, target) {
10
+ const relative = path.relative(root, target);
11
+ return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)
12
+ ? undefined
13
+ : toPosix(relative);
14
+ }
7
15
  /** Hints only. The scheduler's periodic snapshot scan remains required. */
8
- export async function watchContinuous(config, changed) {
16
+ export async function watchContinuous(config, changed, options = {}) {
9
17
  const root = getAgentDir();
10
18
  const watchers = [];
11
19
  const excluded = compileSyncExclude(config.exclude);
12
20
  const selected = config.include.map((item) => path.resolve(root, item));
21
+ const scoped = config.scope === "agent-directory";
22
+ const sessionRoot = sessionStorageRoot(root, options.sessionDir);
23
+ const managed = configuredSnapshotPathMatcher(config);
24
+ const traverse = compileSyncPolicyTraversal(config);
25
+ const scopedPath = (target) => {
26
+ const sessionPath = relativeWithin(sessionRoot, target);
27
+ if (sessionPath !== undefined)
28
+ return sessionPath ? `sessions/${sessionPath}` : "sessions";
29
+ const relative = relativeWithin(root, target);
30
+ return relative && !/^sessions(?:\/|$)/iu.test(relative) ? relative : undefined;
31
+ };
13
32
  const relevant = (target) => selected.some((item) => target === item || target.startsWith(`${item}${path.sep}`) || item.startsWith(`${target}${path.sep}`));
33
+ let closed = false;
14
34
  const add = (directory, recursive) => {
15
35
  try {
16
- const watcher = watch(directory, { recursive, persistent: false }, (_event, file) => {
36
+ const watcher = watch(directory, { recursive, persistent: false }, (event, file) => {
17
37
  // Unknown names can be our own private writes. Periodic scans cover them.
18
- if (!file)
38
+ if (!file || closed || options.signal?.aborted)
19
39
  return;
20
40
  const target = path.resolve(directory, String(file));
21
- if (target === path.join(root, "pi-sync.json"))
22
- changed(true);
23
- else if (isDeniedPath(path.relative(root, target)))
41
+ if (!relativeWithin(directory, target))
24
42
  return;
25
- else if (!excluded(toPosix(path.relative(root, target))) && relevant(target))
43
+ if (target === path.join(root, "pi-sync.json") ||
44
+ (config.ignorePolicy &&
45
+ path.dirname(target) === root &&
46
+ path.basename(target).toLowerCase() === config.ignorePolicy.filename.toLowerCase()))
47
+ changed(true);
48
+ else if (scoped) {
49
+ const relative = scopedPath(target);
50
+ if (relative && (managed(relative) || (event === "rename" && traverse(relative))))
51
+ changed(false);
52
+ }
53
+ else if (!isDeniedPath(path.relative(root, target)) &&
54
+ !excluded(toPosix(path.relative(root, target))) &&
55
+ relevant(target)) {
26
56
  changed(false);
57
+ }
27
58
  });
28
59
  watcher.on("error", () => watcher.close());
29
60
  watchers.push(watcher);
@@ -32,12 +63,59 @@ export async function watchContinuous(config, changed) {
32
63
  /* Periodic scans cover unavailable or unsupported watchers. */
33
64
  }
34
65
  };
35
- add(root, false);
36
- const directories = new Set();
66
+ const directories = new Set([root]);
67
+ const close = () => {
68
+ if (closed)
69
+ return;
70
+ closed = true;
71
+ for (const watcher of watchers)
72
+ watcher.close();
73
+ };
37
74
  try {
75
+ options.signal?.throwIfAborted();
76
+ add(root, false);
77
+ if (scoped) {
78
+ const pending = [root];
79
+ if (syncSessionsSelected(config) && traverse("sessions"))
80
+ pending.push(sessionRoot);
81
+ const scheduled = new Set(pending);
82
+ for (let index = 0; index < pending.length && index < 512; index++) {
83
+ const directory = pending[index];
84
+ if (!directory)
85
+ continue;
86
+ options.signal?.throwIfAborted();
87
+ try {
88
+ const stat = await fs.lstat(directory);
89
+ options.signal?.throwIfAborted();
90
+ if (!stat.isDirectory())
91
+ continue;
92
+ if (directory !== root)
93
+ add(directory, false);
94
+ const entries = await fs.readdir(directory, { withFileTypes: true });
95
+ options.signal?.throwIfAborted();
96
+ for (const entry of entries) {
97
+ if (pending.length >= 512)
98
+ break;
99
+ if (!entry.isDirectory())
100
+ continue;
101
+ const target = path.join(directory, entry.name);
102
+ const relative = scopedPath(target);
103
+ if (relative && traverse(relative) && !scheduled.has(target)) {
104
+ scheduled.add(target);
105
+ pending.push(target);
106
+ }
107
+ }
108
+ }
109
+ catch {
110
+ options.signal?.throwIfAborted();
111
+ }
112
+ }
113
+ return close;
114
+ }
38
115
  for (const target of selected) {
39
116
  try {
40
117
  const stat = await fs.lstat(target);
118
+ options.signal?.throwIfAborted();
41
119
  if (stat.isSymbolicLink())
42
120
  continue;
43
121
  const directory = stat.isDirectory() ? target : path.dirname(target);
@@ -47,19 +125,16 @@ export async function watchContinuous(config, changed) {
47
125
  add(directory, stat.isDirectory());
48
126
  }
49
127
  catch (error) {
128
+ options.signal?.throwIfAborted();
50
129
  if (error.code !== "ENOENT")
51
130
  continue;
52
131
  // Missing targets are found by the parent hint or the next periodic scan.
53
132
  }
54
133
  }
55
- return () => {
56
- for (const watcher of watchers)
57
- watcher.close();
58
- };
134
+ return close;
59
135
  }
60
136
  catch (error) {
61
- for (const watcher of watchers)
62
- watcher.close();
137
+ close();
63
138
  throw error;
64
139
  }
65
140
  }
@@ -3,3 +3,7 @@ export declare function normalizeSyncExclude(value: unknown): string[];
3
3
  export declare function sameSyncExclude(left: unknown, right: unknown): boolean;
4
4
  /** Compile at the operation boundary and reuse for every file/directory. */
5
5
  export declare function compileSyncExclude(value: unknown): (relativePath: string) => boolean;
6
+ export declare function compilePathRules(value: unknown): {
7
+ matches: (relativePath: string) => boolean;
8
+ mayMatchBelow: (directory: string) => boolean;
9
+ };
@@ -51,6 +51,9 @@ export function sameSyncExclude(left, right) {
51
51
  }
52
52
  /** Compile at the operation boundary and reuse for every file/directory. */
53
53
  export function compileSyncExclude(value) {
54
+ return compilePathRules(value).matches;
55
+ }
56
+ export function compilePathRules(value) {
54
57
  const matchers = normalizeSyncExclude(value).map((rule) =>
55
58
  // A trailing globstar also matches zero segments; ancestor matching owns its subtree.
56
59
  new Minimatch(rule.replace(/(?:\/\*\*)+$/u, ""), {
@@ -63,7 +66,7 @@ export function compileSyncExclude(value) {
63
66
  platform: "linux",
64
67
  optimizationLevel: 0,
65
68
  }));
66
- return (relativePath) => {
69
+ const matches = (relativePath) => {
67
70
  if (matchers.length === 0)
68
71
  return false;
69
72
  for (let candidate = relativePath; candidate;) {
@@ -76,4 +79,8 @@ export function compileSyncExclude(value) {
76
79
  }
77
80
  return false;
78
81
  };
82
+ return {
83
+ matches,
84
+ mayMatchBelow: (directory) => matchers.some((matcher) => matcher.match(directory, true)),
85
+ };
79
86
  }
@@ -2,7 +2,7 @@ import { loadConfig } from "../settings/config.js";
2
2
  import { isMissingConfigError } from "../settings/config-errors.js";
3
3
  import { consumeLocalConfigMigrationNotice } from "../settings/config-file.js";
4
4
  import { readLocalConfigObject } from "../settings/settings-store.js";
5
- import { sessionDirFromContext } from "../snapshot/session-paths.js";
5
+ import { effectiveSessionRoot, sessionDirFromContext, snapshotOptionsForContext } from "../snapshot/session-paths.js";
6
6
  import { pendingTransactionEntries } from "../snapshot/snapshot-transaction-directory.js";
7
7
  import { stateDirectoryMigrationNotice, withStateDirectoryAccess } from "../state/state-directory.js";
8
8
  import { captureMutationOwner } from "./mutation-owner.js";
@@ -29,12 +29,17 @@ export async function initializeSync(ctx, signal, publish) {
29
29
  validate();
30
30
  const settings = await readLocalConfigObject();
31
31
  validate();
32
- const setup = settings?.activeSyncSetup;
32
+ const config = settings?.activeSyncSetup ? await loadConfig() : undefined;
33
+ validate();
34
+ const sessionDir = config?.scope === "agent-directory"
35
+ ? await effectiveSessionRoot(ctx, config, signal)
36
+ : sessionDirFromContext(ctx);
37
+ validate();
33
38
  const current = ctx.sessionManager.getSessionFile?.();
34
39
  await recoverSnapshotTransactionsOnStartup({
35
- exclude: setup ? settings.syncSetups[setup]?.sync.exclude : undefined,
40
+ ...(config ? snapshotOptionsForContext(ctx, config) : {}),
36
41
  signal,
37
- sessionDir: sessionDirFromContext(ctx),
42
+ sessionDir,
38
43
  protectedTargets: [...(ctx.protectedSessionFiles ?? []), ...(current ? [current] : [])],
39
44
  validateMutation: validate,
40
45
  });
@@ -1,7 +1,9 @@
1
- import type { Snapshot } from "../snapshot/snapshot-types.js";
1
+ import { type IgnoreSnapshotSelection, type Snapshot } from "../snapshot/snapshot-types.js";
2
2
  export { normalizeLocalFields } from "./local-field-policy.js";
3
3
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
4
4
  export declare function validateSnapshotFieldPolicy(snapshot: Pick<Snapshot, "version" | "localFields">): void;
5
+ export declare function validateIgnoreSnapshotSessionFlag(selection: IgnoreSnapshotSelection, syncSessions: unknown): void;
6
+ export declare function validateIgnoreSnapshotIdentity({ id, createdAt, machine, profile, }: Pick<Snapshot, "id" | "createdAt" | "machine" | "profile">): void;
5
7
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
6
8
  export declare function validatePortableSnapshot(snapshot: Snapshot): void;
7
9
  export declare function sameLocalFields(left: unknown, right: unknown): boolean;
@@ -1,31 +1,102 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import { regenerateSnapshotIdentity } from "../snapshot/snapshot.js";
3
- import { compileSyncExclude } from "./exclude-policy.js";
3
+ import { assertAgentDirectorySnapshotBound } from "../snapshot/snapshot-bounds.js";
4
+ import { IGNORE_SNAPSHOT_VERSION, isSupportedSnapshotVersion, } from "../snapshot/snapshot-types.js";
4
5
  import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
5
6
  import { normalizeLocalFields } from "./local-field-policy.js";
6
- import { snapshotSelectionExclude, validateSnapshotSelection } from "./sync-policy.js";
7
+ import { compileSyncPolicyExclude, configuredSnapshotPathMatcher, validateSnapshotSelection } from "./sync-policy.js";
7
8
  export { normalizeLocalFields } from "./local-field-policy.js";
8
9
  /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
9
10
  export function validateSnapshotFieldPolicy(snapshot) {
10
- if (snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3 && snapshot.version !== 4)
11
+ if (!isSupportedSnapshotVersion(snapshot.version))
11
12
  throw new Error("Unsupported snapshot format.");
12
13
  if (snapshot.version === 1 && snapshot.localFields !== undefined)
13
14
  throw new Error("Portable field policy requires snapshot version 2.");
14
- if (snapshot.version === 2 || snapshot.version === 3 || snapshot.version === 4) {
15
+ if (snapshot.version !== 1) {
15
16
  if (snapshot.version === 2 && snapshot.localFields === undefined)
16
17
  throw new Error("Snapshot version 2 requires explicit localFields rules.");
17
18
  normalizeLocalFields(snapshot.localFields);
18
19
  }
19
20
  }
21
+ export function validateIgnoreSnapshotSessionFlag(selection, syncSessions) {
22
+ if ((syncSessions !== undefined && typeof syncSessions !== "boolean") ||
23
+ (syncSessions === true && !selection.sessions))
24
+ throw new Error("Invalid ignore snapshot session metadata.");
25
+ }
26
+ export function validateIgnoreSnapshotIdentity({ id, createdAt, machine, profile, }) {
27
+ if (typeof id !== "string" ||
28
+ id.length > 512 ||
29
+ id === "." ||
30
+ id === ".." ||
31
+ !/^[A-Za-z0-9._-]+(?![\s\S])/u.test(id) ||
32
+ typeof createdAt !== "string" ||
33
+ createdAt.length > 64 ||
34
+ /[\p{Cc}\p{Cs}]/u.test(createdAt) ||
35
+ Number.isNaN(Date.parse(createdAt)) ||
36
+ typeof machine !== "string" ||
37
+ machine.length > 256 ||
38
+ /[\p{Cc}\p{Cs}]/u.test(machine) ||
39
+ typeof profile !== "string" ||
40
+ !profile ||
41
+ profile.length > 256 ||
42
+ /[\p{Cc}\p{Cs}]/u.test(profile))
43
+ throw new Error("Invalid ignore snapshot identity.");
44
+ }
45
+ function validateIgnoreSnapshotEnvelope(snapshot, selection) {
46
+ validateIgnoreSnapshotIdentity(snapshot);
47
+ validateIgnoreSnapshotSessionFlag(selection, snapshot.syncSessions);
48
+ if (!Array.isArray(snapshot.files) ||
49
+ Object.keys(snapshot).some((key) => ![
50
+ "version",
51
+ "id",
52
+ "createdAt",
53
+ "machine",
54
+ "profile",
55
+ "syncSessions",
56
+ "selection",
57
+ "localFields",
58
+ "files",
59
+ ].includes(key)))
60
+ throw new Error("Invalid ignore snapshot payload.");
61
+ }
62
+ function validateIgnoreSnapshotFiles(files) {
63
+ for (const file of files) {
64
+ if (Object.keys(file).length !== 3 ||
65
+ !Object.hasOwn(file, "path") ||
66
+ !Object.hasOwn(file, "contentBase64") ||
67
+ !Object.hasOwn(file, "sha256") ||
68
+ typeof file.sha256 !== "string" ||
69
+ file.sha256.length !== 64)
70
+ throw new Error("Invalid ignore snapshot file.");
71
+ const content = Buffer.from(file.contentBase64, "base64");
72
+ if (content.toString("base64") !== file.contentBase64 ||
73
+ createHash("sha256").update(content).digest("hex") !== file.sha256)
74
+ throw new Error("Ignore snapshot file checksum or encoding mismatch.");
75
+ }
76
+ }
20
77
  /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
21
78
  export function validatePortableSnapshot(snapshot) {
22
79
  validateSnapshotFieldPolicy(snapshot);
23
80
  validateSnapshotSelection(snapshot);
24
- const excludedPath = compileSyncExclude(snapshotSelectionExclude(snapshot));
25
- if (snapshot.files.some((file) => excludedPath(file.path)))
26
- throw new Error("Portable snapshot retains excluded paths.");
81
+ const selection = snapshot.selection;
82
+ if (selection?.version === 4)
83
+ validateIgnoreSnapshotEnvelope(snapshot, selection);
84
+ if (selection?.scope) {
85
+ const selected = configuredSnapshotPathMatcher(selection);
86
+ if (snapshot.files.some((file) => typeof file?.path !== "string" || !selected(file.path)))
87
+ throw new Error("Portable snapshot retains excluded or unsafe agent-directory paths.");
88
+ assertAgentDirectorySnapshotBound(snapshot.files);
89
+ if (snapshot.version === IGNORE_SNAPSHOT_VERSION)
90
+ validateIgnoreSnapshotFiles(snapshot.files);
91
+ }
92
+ else {
93
+ const excludedPath = compileSyncPolicyExclude(selection ?? {});
94
+ if (snapshot.files.some((file) => excludedPath(file.path)))
95
+ throw new Error("Portable snapshot retains excluded paths.");
96
+ }
27
97
  if (snapshot.version === 1 || !snapshot.localFields?.length)
28
98
  return;
99
+ requireCanonicalFieldSettingsPath(snapshot);
29
100
  try {
30
101
  for (const entry of snapshot.files) {
31
102
  if (typeof entry?.path !== "string" || entry.path.toLowerCase() !== "settings.json")
@@ -51,10 +122,17 @@ function file(content) {
51
122
  sha256: createHash("sha256").update(content).digest("hex"),
52
123
  };
53
124
  }
125
+ function requireCanonicalFieldSettingsPath(snapshot) {
126
+ if (snapshot.selection?.scope &&
127
+ snapshot.files.some(({ path }) => path !== "settings.json" && path.toLowerCase() === "settings.json"))
128
+ throw new Error("Directory scope requires the exact settings.json spelling when machine-local fields are configured.");
129
+ }
54
130
  export function portableSnapshot(snapshot, fields) {
55
131
  if (fields === undefined)
56
132
  return snapshot;
57
133
  const excluded = new Set(normalizeLocalFields(fields));
134
+ if (excluded.size > 0)
135
+ requireCanonicalFieldSettingsPath(snapshot);
58
136
  const files = snapshot.files.map((entry) => {
59
137
  if (entry.path !== "settings.json" || excluded.size === 0)
60
138
  return entry;
@@ -74,7 +152,7 @@ export function portableSnapshot(snapshot, fields) {
74
152
  });
75
153
  return regenerateSnapshotIdentity({
76
154
  ...snapshot,
77
- version: snapshot.version === 4 ? 4 : 2,
155
+ version: snapshot.version >= 4 ? snapshot.version : 2,
78
156
  localFields: [...excluded],
79
157
  files,
80
158
  });
@@ -82,6 +160,8 @@ export function portableSnapshot(snapshot, fields) {
82
160
  export function overlayLocalFields(portable, local, fields) {
83
161
  if (!fields?.length)
84
162
  return portable;
163
+ requireCanonicalFieldSettingsPath(portable);
164
+ requireCanonicalFieldSettingsPath(local);
85
165
  const target = portable.files.find((entry) => entry.path === "settings.json");
86
166
  const current = local.files.find((entry) => entry.path === "settings.json");
87
167
  if (!target && !current)