@narumitw/pi-sync-daemon 0.7.0 → 0.9.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 (93) hide show
  1. package/CHANGELOG.md +21 -0
  2. package/README.md +16 -2
  3. package/dist/cli.js +1 -1
  4. package/dist/consent.d.ts +14 -2
  5. package/dist/consent.js +147 -14
  6. package/dist/engine/backends/git/git-backend.d.ts +2 -3
  7. package/dist/engine/backends/git/git-backend.js +71 -25
  8. package/dist/engine/backends/git/git-storage.d.ts +1 -1
  9. package/dist/engine/backends/git/git-storage.js +30 -9
  10. package/dist/engine/backends/s3/s3-backend.js +8 -0
  11. package/dist/engine/backends/sync-backend.d.ts +1 -0
  12. package/dist/engine/backends/webdav/webdav-backend.js +8 -0
  13. package/dist/engine/commands/command-types.d.ts +2 -1
  14. package/dist/engine/host.d.ts +1 -0
  15. package/dist/engine/ignore/effective-ignore-policy.d.ts +10 -0
  16. package/dist/engine/ignore/effective-ignore-policy.js +33 -0
  17. package/dist/engine/ignore/ignore-edit.d.ts +13 -0
  18. package/dist/engine/ignore/ignore-edit.js +102 -0
  19. package/dist/engine/ignore/ignore-initialization.d.ts +9 -0
  20. package/dist/engine/ignore/ignore-initialization.js +252 -0
  21. package/dist/engine/ignore/ignore-migration-prompt.d.ts +7 -0
  22. package/dist/engine/ignore/ignore-migration-prompt.js +139 -0
  23. package/dist/engine/ignore/ignore-settings.d.ts +30 -0
  24. package/dist/engine/ignore/ignore-settings.js +393 -0
  25. package/dist/engine/ignore/ignore-source.d.ts +27 -0
  26. package/dist/engine/ignore/ignore-source.js +250 -0
  27. package/dist/engine/settings/config-file.d.ts +9 -2
  28. package/dist/engine/settings/config-file.js +124 -28
  29. package/dist/engine/settings/config.d.ts +6 -2
  30. package/dist/engine/settings/config.js +140 -11
  31. package/dist/engine/settings/settings-management.d.ts +5 -3
  32. package/dist/engine/settings/settings-management.js +24 -10
  33. package/dist/engine/settings/settings-types.d.ts +25 -2
  34. package/dist/engine/settings/settings-validation.js +23 -5
  35. package/dist/engine/snapshot/session-paths.d.ts +1 -1
  36. package/dist/engine/snapshot/session-paths.js +41 -13
  37. package/dist/engine/snapshot/snapshot-apply.d.ts +3 -3
  38. package/dist/engine/snapshot/snapshot-apply.js +23 -4
  39. package/dist/engine/snapshot/snapshot-codec.d.ts +1 -1
  40. package/dist/engine/snapshot/snapshot-codec.js +14 -5
  41. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +4 -2
  42. package/dist/engine/snapshot/snapshot-exclude-safety.js +76 -19
  43. package/dist/engine/snapshot/snapshot-transaction-images.d.ts +3 -1
  44. package/dist/engine/snapshot/snapshot-transaction-images.js +33 -3
  45. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +30 -2
  46. package/dist/engine/snapshot/snapshot-transaction-policy.js +135 -11
  47. package/dist/engine/snapshot/snapshot-transaction-verification.d.ts +7 -0
  48. package/dist/engine/snapshot/snapshot-transaction-verification.js +78 -0
  49. package/dist/engine/snapshot/snapshot-transaction.d.ts +1 -12
  50. package/dist/engine/snapshot/snapshot-transaction.js +129 -109
  51. package/dist/engine/snapshot/snapshot-types.d.ts +27 -1
  52. package/dist/engine/snapshot/snapshot-types.js +9 -1
  53. package/dist/engine/snapshot/snapshot.d.ts +6 -4
  54. package/dist/engine/snapshot/snapshot.js +91 -34
  55. package/dist/engine/state/state-types.d.ts +1 -0
  56. package/dist/engine/sync/agent-plan.js +1 -0
  57. package/dist/engine/sync/agent-sync.js +8 -1
  58. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  59. package/dist/engine/sync/continuous-sync.js +50 -18
  60. package/dist/engine/sync/continuous-watch.js +4 -1
  61. package/dist/engine/sync/initialization.js +3 -2
  62. package/dist/engine/sync/local-fields.d.ts +3 -1
  63. package/dist/engine/sync/local-fields.js +62 -1
  64. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  65. package/dist/engine/sync/merge-acceptance.js +29 -0
  66. package/dist/engine/sync/merge-apply.js +42 -11
  67. package/dist/engine/sync/merge-journal.d.ts +24 -4
  68. package/dist/engine/sync/merge-journal.js +134 -8
  69. package/dist/engine/sync/merged-sync.d.ts +1 -1
  70. package/dist/engine/sync/merged-sync.js +128 -83
  71. package/dist/engine/sync/remote-snapshot.d.ts +11 -3
  72. package/dist/engine/sync/remote-snapshot.js +72 -18
  73. package/dist/engine/sync/session-push.js +20 -6
  74. package/dist/engine/sync/sync-inspection.js +7 -5
  75. package/dist/engine/sync/sync-mutations.d.ts +2 -1
  76. package/dist/engine/sync/sync-mutations.js +157 -73
  77. package/dist/engine/sync/sync-policy.d.ts +29 -8
  78. package/dist/engine/sync/sync-policy.js +152 -16
  79. package/dist/engine/sync/sync-queries.js +8 -1
  80. package/dist/engine/sync/sync-state.d.ts +4 -2
  81. package/dist/engine/sync/sync-state.js +15 -2
  82. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  83. package/dist/engine/sync/transfer-freshness.js +82 -0
  84. package/dist/engine-service.d.ts +1 -1
  85. package/dist/engine-service.js +146 -27
  86. package/dist/monitor.d.ts +4 -1
  87. package/dist/monitor.js +84 -32
  88. package/dist/server.d.ts +1 -0
  89. package/dist/server.js +46 -5
  90. package/dist/service-host.d.ts +1 -1
  91. package/dist/service-host.js +2 -1
  92. package/docs/architecture.md +30 -0
  93. package/package.json +2 -1
@@ -22,6 +22,16 @@ export function scopedIdentity(stat) {
22
22
  changedImage();
23
23
  return identity;
24
24
  }
25
+ export function installedVacancyIdentityMatches(image, expected) {
26
+ if (image.kind === "missing" || !isScopedIdentity(expected))
27
+ return false;
28
+ if (scopedIdentity(image.stat) === expected)
29
+ return true;
30
+ if (process.platform !== "win32" || image.kind !== "file" || image.stat.ino === 0n)
31
+ return false;
32
+ const [device, inode] = expected.split(":");
33
+ return image.stat.dev.toString() === device && image.stat.ino.toString() === inode;
34
+ }
25
35
  export function stableScopedIdentity(target, stat) {
26
36
  const identity = scopedIdentity(stat);
27
37
  if (stat.birthtimeNs > 0n) {
@@ -180,8 +190,16 @@ export async function scopedTransactionImage(target, guards, copyTo, checkPath,
180
190
  const hash = createHash("sha256");
181
191
  const copy = destination ? await fs.open(destination, "wx", 0o600) : undefined;
182
192
  try {
183
- if (copy)
184
- await beforeCopyFile?.(copy);
193
+ if (copy && beforeCopyFile) {
194
+ if (process.platform === "darwin") {
195
+ validate(guards);
196
+ await copy.utimes(observed.atime, observed.mtime);
197
+ validate(guards);
198
+ await copy.sync();
199
+ validate(guards);
200
+ }
201
+ await beforeCopyFile(copy);
202
+ }
185
203
  await readStableFile(source, observed, guards, async (chunk) => {
186
204
  hash.update(chunk);
187
205
  if (copy)
@@ -236,7 +254,13 @@ export function scopedDescendant(image, relative) {
236
254
  }
237
255
  return node;
238
256
  }
239
- export async function removeScopedImage(target, image, guards) {
257
+ export async function recheckScopedImage(target, image, guards) {
258
+ if (image.kind !== "missing")
259
+ await recheck(target, image.stat, guards);
260
+ else if (await lstat(target, guards))
261
+ changedImage();
262
+ }
263
+ export async function removeScopedImage(target, image, guards, validateIgnorePolicy) {
240
264
  if (image.kind === "missing")
241
265
  return;
242
266
  async function remove(target, node) {
@@ -245,12 +269,18 @@ export async function removeScopedImage(target, image, guards) {
245
269
  const observed = await scopedTransactionImage(target, guards);
246
270
  if (observed.kind !== "file" || !sameObservation(node.stat, observed.stat) || observed.value !== node.value)
247
271
  changedImage();
272
+ if (validateIgnorePolicy) {
273
+ await validateIgnorePolicy();
274
+ await recheck(target, node.stat, guards);
275
+ }
248
276
  validate(guards);
249
277
  await fs.unlink(target);
250
278
  return;
251
279
  }
252
280
  for (const [name, child] of node.children)
253
281
  await remove(path.join(target, name), child);
282
+ if (validateIgnorePolicy)
283
+ await validateIgnorePolicy();
254
284
  await recheck(target, node.stat, guards, true);
255
285
  validate(guards);
256
286
  await fs.rmdir(target);
@@ -1,19 +1,44 @@
1
1
  import { type SyncSelectionConfig } from "../sync/sync-policy.js";
2
2
  import { type SessionRootTransition } from "./snapshot-root-transition.js";
3
- import type { SnapshotSelection } from "./snapshot-types.js";
3
+ import type { EffectiveIgnorePolicy, SnapshotOptions, SnapshotSelection } from "./snapshot-types.js";
4
4
  export declare const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
5
5
  export declare const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
6
6
  export declare const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
7
+ export declare const IGNORE_POLICY_JOURNAL_VERSION = 11;
8
+ export declare const BOUND_DIRECTORY_JOURNAL_VERSION = 12;
9
+ export declare const BOUND_INCLUDED_PATHS_JOURNAL_VERSION = 13;
10
+ type RecoveryPolicyBinding = Pick<SnapshotOptions, "setupName" | "ignoreSourceIdentity" | "recoverySetupKey">;
11
+ export declare function recoveryPolicyKey(options: SyncSelectionConfig & RecoveryPolicyBinding): string | undefined;
7
12
  export declare function isScopedJournal(journal: TransactionJournalPolicy): boolean;
8
13
  export declare function isRecoveryStageId(value: unknown): value is string;
9
14
  export declare function isScopedIdentity(value: unknown): value is string;
15
+ interface IgnoreSourceBinding {
16
+ version: 1;
17
+ filename: string;
18
+ sourceDigest: string;
19
+ reservedNames: string[];
20
+ }
10
21
  export interface TransactionJournalPolicy {
11
22
  version: number;
12
23
  exclude?: string[];
13
24
  selection?: SnapshotSelection;
25
+ ignoreSource?: IgnoreSourceBinding;
26
+ localPolicyKey?: string;
27
+ }
28
+ export declare function ignoreSourceBinding(policy: Pick<EffectiveIgnorePolicy, "filename" | "sourceDigest" | "reservedNames">): IgnoreSourceBinding;
29
+ type TransactionGuards = Pick<SnapshotOptions, "validateIgnorePolicy" | "signal" | "validateMutation">;
30
+ export interface TransactionOptions extends SyncSelectionConfig, TransactionGuards, RecoveryPolicyBinding, Pick<SnapshotOptions, "validateApplyReview"> {
31
+ sessionDir?: string;
32
+ exclude?: readonly string[];
33
+ protectedTargets?: readonly string[];
34
+ expectedPreimages?: ReadonlyMap<string, string>;
35
+ resolveConfiguredSessionDir?: boolean;
36
+ }
37
+ export declare class StaleIgnorePolicyError extends Error {
14
38
  }
39
+ export declare function ignorePolicyValidator(options: SyncSelectionConfig & TransactionGuards): (() => Promise<void>) | undefined;
15
40
  export declare function validateJournalPolicy(journal: TransactionJournalPolicy): void;
16
- export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: SyncSelectionConfig): void;
41
+ export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: TransactionOptions): void;
17
42
  export interface TransactionEntry {
18
43
  target: string;
19
44
  afterTarget?: string;
@@ -47,4 +72,7 @@ export interface TransactionJournal extends TransactionJournalPolicy {
47
72
  export declare function validateJournal(directory: string, journal: TransactionJournal, sessionDir?: string): void;
48
73
  export declare function transactionHasSessionTargets(journal: TransactionJournal): boolean;
49
74
  export declare function isStrictlyInside(root: string, target: string): boolean;
75
+ export declare function touchesProtectedTarget(target: string, protectedTargets?: readonly string[]): boolean | undefined;
76
+ export declare function assertSafeParents(root: string, sessionRoot: string | undefined, target: string): Promise<void>;
50
77
  export declare function assertAllowedTarget(root: string, sessionRoot: string | undefined, target: string): void;
78
+ export {};
@@ -1,7 +1,10 @@
1
+ import fs from "node:fs/promises";
1
2
  import path from "node:path";
3
+ import { DEFAULT_IGNORE_FILENAME, validateIgnoreFilename } from "../ignore/ignore-source.js";
2
4
  import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
3
5
  import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
4
- import { portableSnapshotSelection, syncDirectoryPolicyKey } from "../sync/sync-policy.js";
6
+ import { mergePathIdentity } from "../sync/file-merge-planner.js";
7
+ import { localIgnorePolicyKey, portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
5
8
  import { agentDir } from "./session-paths.js";
6
9
  import { isCaseReplacement } from "./snapshot-case-replacement.js";
7
10
  import { sessionStorageRoot } from "./snapshot-paths.js";
@@ -9,22 +12,108 @@ import { validateSessionRootTransition } from "./snapshot-root-transition.js";
9
12
  export const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
10
13
  export const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
11
14
  export const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
15
+ export const IGNORE_POLICY_JOURNAL_VERSION = 11;
16
+ export const BOUND_DIRECTORY_JOURNAL_VERSION = 12;
17
+ export const BOUND_INCLUDED_PATHS_JOURNAL_VERSION = 13;
18
+ function isLocallyBoundJournal(journal) {
19
+ return (journal.version === BOUND_DIRECTORY_JOURNAL_VERSION || journal.version === BOUND_INCLUDED_PATHS_JOURNAL_VERSION);
20
+ }
21
+ export function recoveryPolicyKey(options) {
22
+ return options.setupName || options.reservedIgnoreNames !== undefined ? localIgnorePolicyKey(options) : undefined;
23
+ }
12
24
  export function isScopedJournal(journal) {
13
25
  return [
14
26
  LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
15
27
  FIXED_WORKSPACE_JOURNAL_VERSION,
16
28
  AGENT_DIRECTORY_JOURNAL_VERSION,
29
+ IGNORE_POLICY_JOURNAL_VERSION,
30
+ BOUND_DIRECTORY_JOURNAL_VERSION,
17
31
  ].includes(journal.version);
18
32
  }
33
+ function usesSlottedWorkspace(journal) {
34
+ return journal.version >= AGENT_DIRECTORY_JOURNAL_VERSION && isScopedJournal(journal);
35
+ }
19
36
  export function isRecoveryStageId(value) {
20
37
  return (typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value));
21
38
  }
22
39
  export function isScopedIdentity(value) {
23
40
  return typeof value === "string" && /^\d{1,20}:[1-9]\d{0,19}:\d{1,20}$/u.test(value);
24
41
  }
42
+ export function ignoreSourceBinding(policy) {
43
+ const filename = validateIgnoreFilename(policy.filename);
44
+ if (typeof policy.sourceDigest !== "string" ||
45
+ policy.sourceDigest.length !== 64 ||
46
+ !/^[0-9a-f]{64}$/u.test(policy.sourceDigest))
47
+ throw new Error("Invalid ignore policy source digest.");
48
+ return {
49
+ version: 1,
50
+ filename,
51
+ sourceDigest: policy.sourceDigest,
52
+ reservedNames: [
53
+ ...new Set([DEFAULT_IGNORE_FILENAME, filename, ...policy.reservedNames].map((name) => validateIgnoreFilename(name).toLowerCase())),
54
+ ].sort(),
55
+ };
56
+ }
57
+ function sameIgnoreSource(left, right) {
58
+ return (left.version === right.version &&
59
+ left.filename === right.filename &&
60
+ left.sourceDigest === right.sourceDigest &&
61
+ left.reservedNames.length === right.reservedNames.length &&
62
+ left.reservedNames.every((name, index) => name === right.reservedNames[index]));
63
+ }
64
+ export class StaleIgnorePolicyError extends Error {
65
+ }
66
+ export function ignorePolicyValidator(options) {
67
+ const scopedIgnore = options.ignorePolicy !== undefined || options.version === 4;
68
+ if (!scopedIgnore && options.reservedIgnoreNames === undefined && !options.validateIgnorePolicy)
69
+ return;
70
+ const validateIgnorePolicy = options.validateIgnorePolicy;
71
+ if ((scopedIgnore && (!options.ignorePolicy || options.scope !== "agent-directory")) ||
72
+ typeof validateIgnorePolicy !== "function")
73
+ throw new Error("Ignore-file mutation requires an explicit local policy and a freshness check.");
74
+ return async () => {
75
+ options.validateMutation?.();
76
+ options.signal?.throwIfAborted();
77
+ try {
78
+ const pending = validateIgnorePolicy();
79
+ if (typeof pending?.then !== "function")
80
+ throw new Error("The ignore policy freshness check must be async.");
81
+ await pending;
82
+ }
83
+ catch (cause) {
84
+ throw new StaleIgnorePolicyError("Pi Sync ignore policy changed or could not be verified; preserve any transaction evidence and reopen the review.", { cause });
85
+ }
86
+ options.validateMutation?.();
87
+ options.signal?.throwIfAborted();
88
+ };
89
+ }
25
90
  export function validateJournalPolicy(journal) {
26
- if (!journal || (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal)))
91
+ if (!journal ||
92
+ (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal) && !isLocallyBoundJournal(journal)))
27
93
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
94
+ if (isLocallyBoundJournal(journal)
95
+ ? typeof journal.localPolicyKey !== "string" || !/^[0-9a-f]{64}$/u.test(journal.localPolicyKey)
96
+ : journal.localPolicyKey !== undefined)
97
+ throw new Error("Invalid transaction local policy binding; preserve evidence for review.");
98
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION ||
99
+ (journal.version === BOUND_DIRECTORY_JOURNAL_VERSION && journal.selection?.version === 4)) {
100
+ const binding = journal.ignoreSource;
101
+ try {
102
+ if (journal.exclude === undefined &&
103
+ portableSnapshotSelection(journal.selection).version === 4 &&
104
+ binding &&
105
+ Array.isArray(binding.reservedNames) &&
106
+ Object.keys(binding).length === 4 &&
107
+ sameIgnoreSource(binding, ignoreSourceBinding(binding)))
108
+ return;
109
+ }
110
+ catch (cause) {
111
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.", { cause });
112
+ }
113
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.");
114
+ }
115
+ if (journal.ignoreSource !== undefined)
116
+ throw new Error("Unsupported transaction ignore source binding; preserve evidence for review.");
28
117
  if (isScopedJournal(journal)) {
29
118
  if (journal.exclude !== undefined || portableSnapshotSelection(journal.selection).version !== 3)
30
119
  throw new Error("Invalid agent-directory transaction policy; preserve evidence.");
@@ -37,6 +126,18 @@ export function validateJournalPolicy(journal) {
37
126
  normalizeSyncExclude(journal.exclude);
38
127
  }
39
128
  export function assertRecoveryPolicy(journal, options) {
129
+ const localKey = recoveryPolicyKey(options);
130
+ if (journal.localPolicyKey !== localKey)
131
+ throw new Error("Pending transaction has different setup or ignore policy evidence; preserve its backup for reviewed recovery.");
132
+ if (journal.ignoreSource || options.ignorePolicy || options.version === 4) {
133
+ if (journal.ignoreSource &&
134
+ options.scope === "agent-directory" &&
135
+ options.ignorePolicy &&
136
+ sameIgnoreSource(journal.ignoreSource, ignoreSourceBinding(options.ignorePolicy)) &&
137
+ sameSnapshotSelection(journal.selection, selectionForSnapshot(undefined, undefined, options)))
138
+ return;
139
+ throw new Error("Pending transaction has a different ignore-file policy; preserve its backup for reviewed recovery.");
140
+ }
40
141
  const directoryKey = syncDirectoryPolicyKey(journal.selection ?? {});
41
142
  const effectiveDirectoryKey = syncDirectoryPolicyKey(options);
42
143
  if (directoryKey !== undefined
@@ -48,16 +149,18 @@ export function assertRecoveryPolicy(journal, options) {
48
149
  export function validateJournal(directory, journal, sessionDir) {
49
150
  validateJournalPolicy(journal);
50
151
  const wholeDirectory = isScopedJournal(journal);
152
+ const scopedWorkspace = wholeDirectory && journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION;
51
153
  if (!Array.isArray(journal.entries) || journal.entries.length > 16_384)
52
154
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
53
155
  if (journal.completed !== undefined &&
54
- ((!wholeDirectory && ![6, 7].includes(journal.version)) || journal.completed !== true))
156
+ ((!wholeDirectory && ![6, 7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version)) ||
157
+ journal.completed !== true))
55
158
  throw new Error("Invalid transaction completion evidence.");
56
159
  const root = path.resolve(agentDir());
57
160
  if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
58
161
  throw new Error("Transaction root no longer matches the Pi agent directory.");
59
162
  if (journal.sessionRootTransition !== undefined) {
60
- if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
163
+ if (![7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version) || typeof journal.sessionRoot !== "string")
61
164
  throw new Error("Invalid session root-transition version.");
62
165
  validateSessionRootTransition(journal.sessionRootTransition);
63
166
  }
@@ -88,7 +191,7 @@ export function validateJournal(directory, journal, sessionDir) {
88
191
  assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
89
192
  assertAllowedTarget(root, journal.sessionRoot, entry.target);
90
193
  if (entry.afterTarget !== undefined &&
91
- ((!wholeDirectory && ![5, 6, 7].includes(journal.version)) ||
194
+ ((!wholeDirectory && ![5, 6, 7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version)) ||
92
195
  typeof entry.afterTarget !== "string" ||
93
196
  !isCaseReplacement(root, entry.target, entry.afterTarget) ||
94
197
  path.resolve(entry.afterTarget) !== entry.afterTarget ||
@@ -101,8 +204,7 @@ export function validateJournal(directory, journal, sessionDir) {
101
204
  (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
102
205
  (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
103
206
  throw new Error("Invalid transaction postimage evidence.");
104
- if (entry.recoveryStaged !== undefined &&
105
- (typeof entry.recoveryStaged !== "boolean" || journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION))
207
+ if (entry.recoveryStaged !== undefined && (typeof entry.recoveryStaged !== "boolean" || scopedWorkspace))
106
208
  throw new Error("Invalid recovery staging evidence.");
107
209
  if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
108
210
  throw new Error("Invalid transaction removal evidence.");
@@ -112,16 +214,16 @@ export function validateJournal(directory, journal, sessionDir) {
112
214
  if (entry.removalPending && entry.replacementStarted)
113
215
  throw new Error("Conflicting transaction replacement evidence.");
114
216
  if ((entry.recoveryWorkspace !== undefined &&
115
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
217
+ (!scopedWorkspace ||
116
218
  !isScopedIdentity(entry.recoveryWorkspace) ||
117
219
  entry.recoveryStaged ||
118
220
  !["file", "directory"].includes(entry.kind))) ||
119
221
  (entry.recoveryWorkspaceId !== undefined &&
120
- (journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION ||
222
+ (!usesSlottedWorkspace(journal) ||
121
223
  !entry.recoveryWorkspace ||
122
224
  !isRecoveryStageId(entry.recoveryWorkspaceId))) ||
123
225
  (entry.scopedRemoval !== undefined &&
124
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
226
+ (!scopedWorkspace ||
125
227
  !entry.removalPending ||
126
228
  !["before", "after"].includes(entry.scopedRemoval?.image) ||
127
229
  !isScopedIdentity(entry.scopedRemoval?.identity) ||
@@ -129,7 +231,7 @@ export function validateJournal(directory, journal, sessionDir) {
129
231
  ? !["file", "directory"].includes(entry.kind)
130
232
  : entry.afterImage === "missing" && !entry.postFiles?.length))) ||
131
233
  (entry.vacantInstall !== undefined &&
132
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
234
+ (!scopedWorkspace ||
133
235
  !entry.recoveryWorkspace ||
134
236
  !isScopedIdentity(entry.vacantInstall) ||
135
237
  entry.removalPending ||
@@ -154,6 +256,28 @@ export function transactionHasSessionTargets(journal) {
154
256
  export function isStrictlyInside(root, target) {
155
257
  return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
156
258
  }
259
+ export function touchesProtectedTarget(target, protectedTargets) {
260
+ return protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
261
+ isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)));
262
+ }
263
+ export async function assertSafeParents(root, sessionRoot, target) {
264
+ assertAllowedTarget(root, sessionRoot, target);
265
+ const boundary = isPathInside(root, target) ? root : sessionRoot;
266
+ for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
267
+ if (path.dirname(parent) === parent)
268
+ throw new Error("Transaction parent did not reach its owned boundary.");
269
+ try {
270
+ const stat = await fs.lstat(parent);
271
+ if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
272
+ throw new Error("Unsafe transaction parent.");
273
+ }
274
+ catch (error) {
275
+ const code = error.code;
276
+ if (code !== "ENOENT" && code !== "ENOTDIR")
277
+ throw error;
278
+ }
279
+ }
280
+ }
157
281
  export function assertAllowedTarget(root, sessionRoot, target) {
158
282
  const resolved = path.resolve(target);
159
283
  if (isStrictlyInside(root, resolved)) {
@@ -0,0 +1,7 @@
1
+ import { type ScopedImage } from "./snapshot-transaction-images.js";
2
+ import { type TransactionEntry, type TransactionJournal, type TransactionOptions } from "./snapshot-transaction-policy.js";
3
+ export declare function verifyTarget(directory: string, entry: TransactionEntry, journal: TransactionJournal, options: TransactionOptions, deletedByThisCall?: boolean): Promise<{
4
+ value: string;
5
+ before: string;
6
+ scoped: ScopedImage | undefined;
7
+ }>;
@@ -0,0 +1,78 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { caseReplacementSpelling } from "./snapshot-case-replacement.js";
4
+ import { installedVacancyIdentityMatches, legacyImage, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, recheckScopedImage, scopedIdentity, scopedTransactionImage, } from "./snapshot-transaction-images.js";
5
+ import { assertSafeParents, isScopedJournal, } from "./snapshot-transaction-policy.js";
6
+ export async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
7
+ await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
8
+ const isScoped = isScopedJournal(journal);
9
+ const backup = isScoped && entry.kind !== "missing"
10
+ ? await scopedTransactionImage(path.join(directory, "before", entry.backupName), options)
11
+ : undefined;
12
+ const before = isScoped ? (backup?.value ?? "missing") : await legacyBeforeImage(directory, entry);
13
+ if ((backup && backup.kind !== entry.kind) || (journal.version >= 2 && before !== entry.beforeImage))
14
+ throw new Error("Transaction backup changed; preserve evidence for review.");
15
+ const spelling = entry.afterTarget ? await caseReplacementSpelling(entry.target, entry.afterTarget) : entry.target;
16
+ const scoped = isScoped ? await scopedTransactionImage(entry.target, options) : undefined;
17
+ const value = scoped?.value ?? (await legacyImage(entry.target));
18
+ const result = { value, before, scoped };
19
+ const postFiles = entry.postFiles ?? [];
20
+ if (entry.vacantInstall) {
21
+ if (scoped?.kind === "missing" ||
22
+ (scoped &&
23
+ value === before &&
24
+ spelling === entry.target &&
25
+ (await installedVacancyMatches(entry.target, scoped, entry.vacantInstall, options))))
26
+ return result;
27
+ }
28
+ else if (value === "missing") {
29
+ if (value === before ||
30
+ deletedByThisCall ||
31
+ (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
32
+ return result;
33
+ }
34
+ else if (scoped && entry.scopedRemoval) {
35
+ const removal = entry.scopedRemoval;
36
+ if ((removal.image === "before"
37
+ ? backup && ownedScopedSubset(scoped, backup)
38
+ : value === entry.afterImage || ownedScopedPostTree(scoped, postFiles, false)) &&
39
+ scoped.kind !== "missing" &&
40
+ scopedIdentity(scoped.stat) === removal.identity)
41
+ return result;
42
+ }
43
+ else if (value === before || (journal.version >= 2 && value === entry.afterImage)) {
44
+ return result;
45
+ }
46
+ else if (journal.version >= 2) {
47
+ const requireComplete = journal.version < 4 || entry.replacementStarted === true || !entry.removalPending;
48
+ if (scoped
49
+ ? ownedScopedPostTree(scoped, postFiles, true)
50
+ : await ownedLegacyPostTree(entry.target, postFiles, requireComplete))
51
+ return result;
52
+ }
53
+ throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
54
+ }
55
+ async function installedVacancyMatches(target, image, expected, options) {
56
+ if (!installedVacancyIdentityMatches(image, expected) || image.kind === "missing")
57
+ return false;
58
+ if (scopedIdentity(image.stat) === expected)
59
+ return true;
60
+ const names = await fs.readdir(path.dirname(target));
61
+ options.validateMutation?.();
62
+ options.signal?.throwIfAborted();
63
+ if (!names.includes(path.basename(target)))
64
+ return false;
65
+ await recheckScopedImage(target, image, options);
66
+ return true;
67
+ }
68
+ async function legacyBeforeImage(directory, entry) {
69
+ if (entry.kind === "missing")
70
+ return "missing";
71
+ const backup = path.join(directory, "before", entry.backupName);
72
+ if (entry.kind === "symlink")
73
+ return `symlink:${entry.linkTarget}`;
74
+ const value = await legacyImage(backup);
75
+ if (value === "missing")
76
+ throw new Error("Transaction backup is missing; preserve evidence for review.");
77
+ return value;
78
+ }
@@ -1,16 +1,5 @@
1
- import { type SyncSelectionConfig } from "../sync/sync-policy.js";
1
+ import { type TransactionOptions } from "./snapshot-transaction-policy.js";
2
2
  import type { SnapshotApplyPlan } from "./snapshot-types.js";
3
- interface TransactionOptions extends SyncSelectionConfig {
4
- sessionDir?: string;
5
- exclude?: readonly string[];
6
- signal?: AbortSignal;
7
- validateMutation?: () => void;
8
- protectedTargets?: readonly string[];
9
- /** Fresh apply authorization only; recovery remains bound to durable journal images. */
10
- expectedPreimages?: ReadonlyMap<string, string>;
11
- resolveConfiguredSessionDir?: boolean;
12
- }
13
3
  export declare function applySnapshotTransaction(plan: SnapshotApplyPlan, options?: TransactionOptions): Promise<void>;
14
4
  export declare function recoverSnapshotTransactionsOnStartup(options?: TransactionOptions): Promise<void>;
15
5
  export declare function recoverPendingSnapshotTransactions(options?: TransactionOptions): Promise<void>;
16
- export {};