@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
@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
3
3
  import path from "node:path";
4
4
  import { isPathInside, toPosix } from "../paths.js";
5
5
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
6
- import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, } from "../sync/sync-policy.js";
6
+ import { compileSyncPolicyExclude, compileSyncPolicyTraversal, configuredSnapshotPathMatcher, isIgnoreControlPath, } from "../sync/sync-policy.js";
7
7
  import { sessionStorageRoot } from "./snapshot-paths.js";
8
8
  function directoryStat(absolute) {
9
9
  try {
@@ -56,31 +56,75 @@ export function agentDirectoryAnchor(root, boundary) {
56
56
  }
57
57
  return anchor;
58
58
  }
59
- export function agentDirectorySessionRoot(root, sessionDir) {
59
+ export function agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
60
60
  const sessionRoot = sessionStorageRoot(root, sessionDir);
61
61
  if (physicalRelative(sessionRoot, root) !== undefined)
62
62
  throw new Error("Pi session storage overlaps the agent directory root.");
63
63
  const relative = physicalRelative(root, sessionRoot);
64
64
  if (relative !== undefined) {
65
+ const logical = toPosix(relative);
65
66
  const canTraverse = compileSyncPolicyTraversal({ scope: "agent-directory", include: ["sessions"] });
66
- if (!canTraverse(toPosix(relative)))
67
+ const reserved = ignorePolicy || reservedIgnoreNames
68
+ ? new Set([
69
+ ...(ignorePolicy ? [ignorePolicy.filename, ...ignorePolicy.reservedNames] : []),
70
+ ...(reservedIgnoreNames ?? []),
71
+ ].map((name) => name.toLowerCase()))
72
+ : undefined;
73
+ if (!canTraverse(logical) || (reserved && isIgnoreControlPath(logical, reserved)))
67
74
  throw new Error("Pi session storage overlaps protected agent files.");
68
75
  }
69
76
  return sessionRoot;
70
77
  }
71
- export function agentDirectoryPhysicalSessionPath(root, sessionDir) {
72
- const sessionRoot = agentDirectorySessionRoot(root, sessionDir);
78
+ export function agentDirectoryPhysicalSessionPath(root, sessionDir, ignorePolicy, reservedIgnoreNames) {
79
+ const sessionRoot = agentDirectorySessionRoot(root, sessionDir, ignorePolicy, reservedIgnoreNames);
73
80
  const nested = physicalRelative(root, sessionRoot) !== undefined;
74
81
  return (relativePath) => nested && physicalRelative(sessionRoot, path.resolve(root, relativePath)) !== undefined;
75
82
  }
83
+ async function realpathWithMissingTail(target) {
84
+ let ancestor = path.resolve(target);
85
+ for (;;) {
86
+ try {
87
+ const resolved = await fs.realpath(ancestor);
88
+ return path.resolve(resolved, path.relative(ancestor, target));
89
+ }
90
+ catch (error) {
91
+ const code = error.code;
92
+ const parent = path.dirname(ancestor);
93
+ if (parent === ancestor || (code !== "ENOENT" && code !== "ENOTDIR"))
94
+ throw error;
95
+ ancestor = parent;
96
+ }
97
+ }
98
+ }
99
+ export function reservedIgnoreTargetGuard(root, options) {
100
+ if (options.reservedIgnoreNames === undefined)
101
+ return undefined;
102
+ const reserved = new Set(options.reservedIgnoreNames);
103
+ function check(agentRoot, target) {
104
+ const relative = physicalRelative(agentRoot, target);
105
+ if (physicalRelative(target, agentRoot) !== undefined ||
106
+ (relative !== undefined && isIgnoreControlPath(toPosix(relative), reserved)))
107
+ throw new Error("Transfer would access a protected ignore rule path or its ancestor.");
108
+ }
109
+ return async (target) => {
110
+ check(root, target);
111
+ const canonicalRoot = await realpathWithMissingTail(root);
112
+ const canonicalTarget = await realpathWithMissingTail(target);
113
+ check(canonicalRoot, canonicalTarget);
114
+ return canonicalTarget;
115
+ };
116
+ }
76
117
  /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
77
118
  export async function assertUnexcludedTargets(root, targets, options, { recursive = true } = {}) {
78
119
  const wholeDirectory = options.scope === "agent-directory";
79
- if (!wholeDirectory && (options.exclude === undefined || (Array.isArray(options.exclude) && !options.exclude.length)))
120
+ const guardReserved = reservedIgnoreTargetGuard(root, options);
121
+ if (!wholeDirectory &&
122
+ !guardReserved &&
123
+ (options.exclude === undefined || (Array.isArray(options.exclude) && !options.exclude.length)))
80
124
  return;
81
125
  const excluded = compileSyncPolicyExclude(options);
82
126
  const sessionRoot = wholeDirectory
83
- ? agentDirectorySessionRoot(root, options.sessionDir)
127
+ ? agentDirectorySessionRoot(root, options.sessionDir, options.ignorePolicy, options.reservedIgnoreNames)
84
128
  : sessionStorageRoot(root, options.sessionDir);
85
129
  const configured = configuredSnapshotPathMatcher(options);
86
130
  let visited = 0;
@@ -93,11 +137,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
93
137
  if (++visited > 16_384)
94
138
  throw new Error("Exclude safety preflight exceeds its path bound; review a smaller transfer.");
95
139
  };
96
- const refuse = () => {
140
+ function refuse() {
97
141
  throw new Error("Transfer would replace an excluded path or directory descendant; no replacement is authorized.");
98
- };
142
+ }
99
143
  async function visit(target) {
100
144
  validate();
145
+ if (guardReserved) {
146
+ await guardReserved(target);
147
+ validate();
148
+ }
149
+ let logicalPath;
101
150
  let sessionPath;
102
151
  if (wholeDirectory) {
103
152
  if (physicalRelative(target, sessionRoot) !== undefined)
@@ -105,14 +154,16 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
105
154
  const sessionRelative = physicalRelative(sessionRoot, target);
106
155
  if (sessionRelative !== undefined) {
107
156
  sessionPath = `sessions/${toPosix(sessionRelative)}`;
108
- if (excluded(sessionPath))
109
- refuse();
157
+ logicalPath = sessionPath;
110
158
  }
111
159
  else {
112
160
  const relative = physicalRelative(root, target);
113
- if (relative === undefined || /^sessions(?:\/|$)/iu.test(toPosix(relative)) || excluded(toPosix(relative)))
161
+ if (!relative || /^sessions(?:\/|$)/iu.test(toPosix(relative)))
114
162
  refuse();
163
+ logicalPath = toPosix(relative);
115
164
  }
165
+ if (!options.ignorePolicy && excluded(logicalPath))
166
+ refuse();
116
167
  }
117
168
  else {
118
169
  const candidates = [];
@@ -120,22 +171,28 @@ export async function assertUnexcludedTargets(root, targets, options, { recursiv
120
171
  candidates.push(toPosix(path.relative(root, target)));
121
172
  if (isPathInside(sessionRoot, target))
122
173
  candidates.push(`sessions/${toPosix(path.relative(sessionRoot, target))}`);
123
- if (candidates.some(excluded))
174
+ if (candidates.some((candidate) => excluded(candidate)))
124
175
  refuse();
125
176
  }
126
- let stat;
177
+ let observed;
127
178
  try {
128
- stat = await fs.lstat(target);
179
+ observed = await fs.lstat(target);
129
180
  }
130
181
  catch (error) {
131
- validate();
132
182
  const code = error.code;
133
- if (code !== "ENOENT" && code !== "ENOTDIR")
183
+ if (code !== "ENOENT" && code !== "ENOTDIR") {
184
+ validate();
134
185
  throw error;
135
- return;
186
+ }
136
187
  }
137
188
  validate();
138
- if (wholeDirectory && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) {
189
+ if (options.ignorePolicy && logicalPath !== undefined && excluded(logicalPath, observed?.isDirectory()))
190
+ refuse();
191
+ if (!observed)
192
+ return;
193
+ const stat = observed;
194
+ if ((wholeDirectory && !stat.isDirectory() && (!stat.isFile() || stat.nlink !== 1)) ||
195
+ (guardReserved && stat.isFile() && stat.nlink !== 1)) {
139
196
  throw new Error("Refusing an unsafe symlink, hard link, or special file during snapshot mutation.");
140
197
  }
141
198
  if (sessionPath && stat.isFile() && !configured(sessionPath))
@@ -23,13 +23,15 @@ export type ScopedImage = {
23
23
  } | ScopedNode;
24
24
  export declare function scopedPathIdentity(target: string, guards: Guards): Promise<string>;
25
25
  export declare function scopedIdentity(stat: BigIntStats): string;
26
+ export declare function installedVacancyIdentityMatches(image: ScopedImage, expected: string): boolean;
26
27
  export declare function stableScopedIdentity(target: string, stat: BigIntStats): string;
27
28
  export declare function readTransactionJournal(file: string, guards: Guards, maxBytes?: number): Promise<string | undefined>;
28
29
  export declare function scopedTransactionImage(target: string, guards: Guards, copyTo?: string, checkPath?: (source: string) => Promise<void>, beforeCopyFile?: (handle: FileHandle) => Promise<void>): Promise<ScopedImage>;
29
30
  export declare function ownedScopedSubset(image: ScopedImage, expected: ScopedImage): boolean;
30
31
  export declare function matchesScopedFilePrefix(source: string, original: ScopedImage, partial: ScopedImage, guards: Guards): Promise<boolean>;
31
32
  export declare function scopedDescendant(image: ScopedImage, relative: string): ScopedImage | undefined;
32
- export declare function removeScopedImage(target: string, image: ScopedImage, guards: Guards): Promise<void>;
33
+ export declare function recheckScopedImage(target: string, image: ScopedImage, guards: Guards): Promise<void>;
34
+ export declare function removeScopedImage(target: string, image: ScopedImage, guards: Guards, validateIgnorePolicy?: () => Promise<void>): Promise<void>;
33
35
  export declare function legacyImage(target: string, durable?: boolean): Promise<string>;
34
36
  type PostFiles = NonNullable<TransactionEntry["postFiles"]>;
35
37
  export declare function ownedScopedPostTree(image: ScopedImage, files: PostFiles, requireComplete: boolean): boolean;
@@ -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,17 +1,37 @@
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;
7
8
  export declare function isScopedJournal(journal: TransactionJournalPolicy): boolean;
8
9
  export declare function isRecoveryStageId(value: unknown): value is string;
9
10
  export declare function isScopedIdentity(value: unknown): value is string;
11
+ interface IgnoreSourceBinding {
12
+ version: 1;
13
+ filename: string;
14
+ sourceDigest: string;
15
+ reservedNames: string[];
16
+ }
10
17
  export interface TransactionJournalPolicy {
11
18
  version: number;
12
19
  exclude?: string[];
13
20
  selection?: SnapshotSelection;
21
+ ignoreSource?: IgnoreSourceBinding;
22
+ }
23
+ export declare function ignoreSourceBinding(policy: Pick<EffectiveIgnorePolicy, "filename" | "sourceDigest" | "reservedNames">): IgnoreSourceBinding;
24
+ type TransactionGuards = Pick<SnapshotOptions, "validateIgnorePolicy" | "signal" | "validateMutation">;
25
+ export interface TransactionOptions extends SyncSelectionConfig, TransactionGuards {
26
+ sessionDir?: string;
27
+ exclude?: readonly string[];
28
+ protectedTargets?: readonly string[];
29
+ expectedPreimages?: ReadonlyMap<string, string>;
30
+ resolveConfiguredSessionDir?: boolean;
31
+ }
32
+ export declare class StaleIgnorePolicyError extends Error {
14
33
  }
34
+ export declare function ignorePolicyValidator(options: SyncSelectionConfig & TransactionGuards): (() => Promise<void>) | undefined;
15
35
  export declare function validateJournalPolicy(journal: TransactionJournalPolicy): void;
16
36
  export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: SyncSelectionConfig): void;
17
37
  export interface TransactionEntry {
@@ -47,4 +67,7 @@ export interface TransactionJournal extends TransactionJournalPolicy {
47
67
  export declare function validateJournal(directory: string, journal: TransactionJournal, sessionDir?: string): void;
48
68
  export declare function transactionHasSessionTargets(journal: TransactionJournal): boolean;
49
69
  export declare function isStrictlyInside(root: string, target: string): boolean;
70
+ export declare function touchesProtectedTarget(target: string, protectedTargets?: readonly string[]): boolean | undefined;
71
+ export declare function assertSafeParents(root: string, sessionRoot: string | undefined, target: string): Promise<void>;
50
72
  export declare function assertAllowedTarget(root: string, sessionRoot: string | undefined, target: string): void;
73
+ 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 { 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,91 @@ 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;
12
16
  export function isScopedJournal(journal) {
13
17
  return [
14
18
  LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
15
19
  FIXED_WORKSPACE_JOURNAL_VERSION,
16
20
  AGENT_DIRECTORY_JOURNAL_VERSION,
21
+ IGNORE_POLICY_JOURNAL_VERSION,
17
22
  ].includes(journal.version);
18
23
  }
24
+ function usesSlottedWorkspace(journal) {
25
+ return journal.version === AGENT_DIRECTORY_JOURNAL_VERSION || journal.version === IGNORE_POLICY_JOURNAL_VERSION;
26
+ }
19
27
  export function isRecoveryStageId(value) {
20
28
  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
29
  }
22
30
  export function isScopedIdentity(value) {
23
31
  return typeof value === "string" && /^\d{1,20}:[1-9]\d{0,19}:\d{1,20}$/u.test(value);
24
32
  }
33
+ export function ignoreSourceBinding(policy) {
34
+ const filename = validateIgnoreFilename(policy.filename);
35
+ if (typeof policy.sourceDigest !== "string" ||
36
+ policy.sourceDigest.length !== 64 ||
37
+ !/^[0-9a-f]{64}$/u.test(policy.sourceDigest))
38
+ throw new Error("Invalid ignore policy source digest.");
39
+ return {
40
+ version: 1,
41
+ filename,
42
+ sourceDigest: policy.sourceDigest,
43
+ reservedNames: [
44
+ ...new Set([DEFAULT_IGNORE_FILENAME, filename, ...policy.reservedNames].map((name) => validateIgnoreFilename(name).toLowerCase())),
45
+ ].sort(),
46
+ };
47
+ }
48
+ function sameIgnoreSource(left, right) {
49
+ return (left.version === right.version &&
50
+ left.filename === right.filename &&
51
+ left.sourceDigest === right.sourceDigest &&
52
+ left.reservedNames.length === right.reservedNames.length &&
53
+ left.reservedNames.every((name, index) => name === right.reservedNames[index]));
54
+ }
55
+ export class StaleIgnorePolicyError extends Error {
56
+ }
57
+ export function ignorePolicyValidator(options) {
58
+ if (!options.ignorePolicy && options.version !== 4)
59
+ return;
60
+ const validateIgnorePolicy = options.validateIgnorePolicy;
61
+ if (!options.ignorePolicy || options.scope !== "agent-directory" || typeof validateIgnorePolicy !== "function")
62
+ throw new Error("Ignore-file mutation requires an explicit local policy and a freshness check.");
63
+ return async () => {
64
+ options.validateMutation?.();
65
+ options.signal?.throwIfAborted();
66
+ try {
67
+ const pending = validateIgnorePolicy();
68
+ if (typeof pending?.then !== "function")
69
+ throw new Error("The ignore policy freshness check must be async.");
70
+ await pending;
71
+ }
72
+ catch (cause) {
73
+ throw new StaleIgnorePolicyError("Pi Sync ignore policy changed or could not be verified; preserve any transaction evidence and reopen the review.", { cause });
74
+ }
75
+ options.validateMutation?.();
76
+ options.signal?.throwIfAborted();
77
+ };
78
+ }
25
79
  export function validateJournalPolicy(journal) {
26
80
  if (!journal || (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) && !isScopedJournal(journal)))
27
81
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
82
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION) {
83
+ const binding = journal.ignoreSource;
84
+ try {
85
+ if (journal.exclude === undefined &&
86
+ portableSnapshotSelection(journal.selection).version === 4 &&
87
+ binding &&
88
+ Array.isArray(binding.reservedNames) &&
89
+ Object.keys(binding).length === 4 &&
90
+ sameIgnoreSource(binding, ignoreSourceBinding(binding)))
91
+ return;
92
+ }
93
+ catch (cause) {
94
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.", { cause });
95
+ }
96
+ throw new Error("Invalid ignore-file transaction policy; preserve evidence for review.");
97
+ }
98
+ if (journal.ignoreSource !== undefined)
99
+ throw new Error("Unsupported transaction ignore source binding; preserve evidence for review.");
28
100
  if (isScopedJournal(journal)) {
29
101
  if (journal.exclude !== undefined || portableSnapshotSelection(journal.selection).version !== 3)
30
102
  throw new Error("Invalid agent-directory transaction policy; preserve evidence.");
@@ -37,6 +109,16 @@ export function validateJournalPolicy(journal) {
37
109
  normalizeSyncExclude(journal.exclude);
38
110
  }
39
111
  export function assertRecoveryPolicy(journal, options) {
112
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION || options.ignorePolicy || options.version === 4) {
113
+ if (journal.version === IGNORE_POLICY_JOURNAL_VERSION &&
114
+ journal.ignoreSource &&
115
+ options.scope === "agent-directory" &&
116
+ options.ignorePolicy &&
117
+ sameIgnoreSource(journal.ignoreSource, ignoreSourceBinding(options.ignorePolicy)) &&
118
+ sameSnapshotSelection(journal.selection, selectionForSnapshot(undefined, undefined, options)))
119
+ return;
120
+ throw new Error("Pending transaction has a different ignore-file policy; preserve its backup for reviewed recovery.");
121
+ }
40
122
  const directoryKey = syncDirectoryPolicyKey(journal.selection ?? {});
41
123
  const effectiveDirectoryKey = syncDirectoryPolicyKey(options);
42
124
  if (directoryKey !== undefined
@@ -117,7 +199,7 @@ export function validateJournal(directory, journal, sessionDir) {
117
199
  entry.recoveryStaged ||
118
200
  !["file", "directory"].includes(entry.kind))) ||
119
201
  (entry.recoveryWorkspaceId !== undefined &&
120
- (journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION ||
202
+ (!usesSlottedWorkspace(journal) ||
121
203
  !entry.recoveryWorkspace ||
122
204
  !isRecoveryStageId(entry.recoveryWorkspaceId))) ||
123
205
  (entry.scopedRemoval !== undefined &&
@@ -154,6 +236,28 @@ export function transactionHasSessionTargets(journal) {
154
236
  export function isStrictlyInside(root, target) {
155
237
  return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
156
238
  }
239
+ export function touchesProtectedTarget(target, protectedTargets) {
240
+ return protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
241
+ isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)));
242
+ }
243
+ export async function assertSafeParents(root, sessionRoot, target) {
244
+ assertAllowedTarget(root, sessionRoot, target);
245
+ const boundary = isPathInside(root, target) ? root : sessionRoot;
246
+ for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
247
+ if (path.dirname(parent) === parent)
248
+ throw new Error("Transaction parent did not reach its owned boundary.");
249
+ try {
250
+ const stat = await fs.lstat(parent);
251
+ if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
252
+ throw new Error("Unsafe transaction parent.");
253
+ }
254
+ catch (error) {
255
+ const code = error.code;
256
+ if (code !== "ENOENT" && code !== "ENOTDIR")
257
+ throw error;
258
+ }
259
+ }
260
+ }
157
261
  export function assertAllowedTarget(root, sessionRoot, target) {
158
262
  const resolved = path.resolve(target);
159
263
  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 {};