@narumitw/pi-sync-daemon 0.8.0 → 0.9.1

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 (61) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/cli.js +1 -1
  3. package/dist/consent.d.ts +14 -2
  4. package/dist/consent.js +134 -16
  5. package/dist/engine/backends/git/git-backend.d.ts +1 -2
  6. package/dist/engine/backends/git/git-backend.js +61 -30
  7. package/dist/engine/commands/command-types.d.ts +2 -1
  8. package/dist/engine/host.d.ts +1 -0
  9. package/dist/engine/ignore/ignore-initialization.d.ts +8 -1
  10. package/dist/engine/ignore/ignore-initialization.js +142 -40
  11. package/dist/engine/ignore/ignore-settings.d.ts +16 -1
  12. package/dist/engine/ignore/ignore-settings.js +94 -26
  13. package/dist/engine/ignore/ignore-source.d.ts +1 -1
  14. package/dist/engine/ignore/ignore-source.js +1 -1
  15. package/dist/engine/settings/config-file.js +1 -1
  16. package/dist/engine/settings/config.d.ts +3 -2
  17. package/dist/engine/settings/config.js +71 -28
  18. package/dist/engine/settings/settings-management.d.ts +3 -1
  19. package/dist/engine/settings/settings-management.js +8 -2
  20. package/dist/engine/settings/settings-types.d.ts +2 -0
  21. package/dist/engine/snapshot/session-paths.js +7 -2
  22. package/dist/engine/snapshot/snapshot-apply.d.ts +1 -1
  23. package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +7 -2
  24. package/dist/engine/snapshot/snapshot-transaction-policy.js +37 -17
  25. package/dist/engine/snapshot/snapshot-transaction.js +55 -13
  26. package/dist/engine/snapshot/snapshot-types.d.ts +4 -0
  27. package/dist/engine/sync/agent-plan.js +1 -0
  28. package/dist/engine/sync/agent-sync.js +8 -1
  29. package/dist/engine/sync/continuous-sync.d.ts +3 -1
  30. package/dist/engine/sync/continuous-sync.js +32 -15
  31. package/dist/engine/sync/merge-acceptance.d.ts +8 -0
  32. package/dist/engine/sync/merge-acceptance.js +29 -0
  33. package/dist/engine/sync/merge-apply.js +7 -4
  34. package/dist/engine/sync/merge-journal.d.ts +6 -0
  35. package/dist/engine/sync/merge-journal.js +33 -14
  36. package/dist/engine/sync/merged-sync.js +31 -39
  37. package/dist/engine/sync/remote-snapshot.d.ts +2 -1
  38. package/dist/engine/sync/remote-snapshot.js +17 -2
  39. package/dist/engine/sync/session-push.js +20 -6
  40. package/dist/engine/sync/sync-error-guidance.js +16 -3
  41. package/dist/engine/sync/sync-mutations.js +75 -54
  42. package/dist/engine/sync/sync-policy.d.ts +5 -0
  43. package/dist/engine/sync/sync-policy.js +28 -3
  44. package/dist/engine/sync/sync-state.d.ts +2 -0
  45. package/dist/engine/sync/sync-state.js +3 -8
  46. package/dist/engine/sync/transfer-freshness.d.ts +31 -0
  47. package/dist/engine/sync/transfer-freshness.js +82 -0
  48. package/dist/engine/ui/sync-format.d.ts +16 -5
  49. package/dist/engine/ui/sync-format.js +23 -55
  50. package/dist/engine/ui/transfer-review.d.ts +2 -1
  51. package/dist/engine/ui/transfer-review.js +3 -3
  52. package/dist/engine-service.d.ts +1 -1
  53. package/dist/engine-service.js +124 -27
  54. package/dist/monitor.d.ts +4 -1
  55. package/dist/monitor.js +84 -32
  56. package/dist/server.d.ts +1 -0
  57. package/dist/server.js +46 -5
  58. package/dist/service-host.d.ts +1 -1
  59. package/dist/service-host.js +2 -1
  60. package/docs/architecture.md +14 -6
  61. package/package.json +1 -1
@@ -1,22 +1,39 @@
1
1
  import { createHash } from "node:crypto";
2
+ import path from "node:path";
3
+ import { documentFingerprint } from "../../document.js";
2
4
  import { backendIdentityCoordinates } from "../backends/backend-identity.js";
3
5
  import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote } from "../backends/git/git-config.js";
4
6
  import { normalizeWebDavPath, normalizeWebDavUrl } from "../backends/webdav/webdav-config.js";
5
- import { getEngineRoot } from "../host.js";
6
- import { loadEffectiveIgnorePolicy } from "../ignore/effective-ignore-policy.js";
7
+ import { engineHost, getEngineRoot } from "../host.js";
8
+ import { compileEffectiveIgnorePolicy } from "../ignore/effective-ignore-policy.js";
7
9
  import { DEFAULT_IGNORE_FILENAME, readIgnoreSource, validateIgnoreFilename } from "../ignore/ignore-source.js";
8
10
  import { normalizeSyncExclude } from "../sync/exclude-policy.js";
9
11
  import { normalizeLocalFields } from "../sync/local-field-policy.js";
10
- import { normalizeDirectoryRules, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "../sync/sync-policy.js";
12
+ import { localIgnorePolicyKey, normalizeDirectoryRules, normalizeSyncInclude, syncDirectoryPolicyKey, syncSessionsSelected, } from "../sync/sync-policy.js";
13
+ import { safeTerminalText } from "../ui/terminal-text.js";
11
14
  import { localConfigPath, readActiveLocalConfigDocumentForRepair, withLockedLocalConfigDocument, } from "./config-file.js";
12
- import { requireSettings } from "./settings-store.js";
15
+ import { readLocalConfigDocument, requireSettings } from "./settings-store.js";
13
16
  import { DEFAULT_ON_SWITCH, isCloudflareR2Endpoint, normalizeS3Bucket, normalizeS3Endpoint, normalizeStoragePath, optionalString, ownObject, requiredString, validateConfigName, validateSettingsDocument, } from "./settings-validation.js";
14
- export async function loadConfig(setupName) {
15
- return requireLegacyOperationConfig(configFromSettings(await requireSettings(), setupName));
17
+ export async function loadConfig(setupName, signal) {
18
+ signal?.throwIfAborted();
19
+ const document = await readLocalConfigDocument();
20
+ if (!document)
21
+ throw new Error(`Missing pi-sync settings. Open /sync and choose Set up sync, or create ${localConfigPath()}.`);
22
+ return operationalConfig(document, setupName, signal);
16
23
  }
17
24
  /** A background freshness read must never trigger legacy-file publication. */
18
- export async function loadConfigForCheck() {
19
- return requireLegacyOperationConfig(configFromSettings(await readSettingsForCheck()));
25
+ export async function loadConfigForCheck(setupName, signal) {
26
+ signal?.throwIfAborted();
27
+ return operationalConfig(await readActiveLocalConfigDocumentForRepair(), setupName, signal);
28
+ }
29
+ async function operationalConfig(document, setupName, signal) {
30
+ signal?.throwIfAborted();
31
+ const config = configFromSettings(settingsFromCheckDocument(document), setupName);
32
+ if (!config.reservedIgnoreNames)
33
+ return config;
34
+ if (engineHost().ignoreFileOperationsAvailable === false)
35
+ return requireLegacyOperationConfig(config);
36
+ return resolveOperationPolicy(config, setupName, signal, document);
20
37
  }
21
38
  export async function loadSettingsConfig(setupName) {
22
39
  return configFromSettings(await readSettingsForCheck(), setupName);
@@ -37,46 +54,62 @@ export function requireLegacyOperationConfig(config) {
37
54
  }
38
55
  export async function resolveIgnoreConfig(settings, setupName, signal) {
39
56
  signal?.throwIfAborted();
40
- const config = configFromSettings(validateSettingsDocument(settings), setupName);
41
- if (config.pathPolicy !== "ignore-file")
42
- return requireLegacyOperationConfig(config);
57
+ return resolveOperationPolicy(configFromSettings(validateSettingsDocument(settings), setupName), setupName, signal);
58
+ }
59
+ function settingsDocumentFingerprint(document) {
60
+ return documentFingerprint(document && { bytes: document.bytes.toString("base64"), identity: document.identity });
61
+ }
62
+ async function resolveOperationPolicy(config, setupName, signal, original) {
63
+ if (!config.reservedIgnoreNames)
64
+ return config;
43
65
  const root = getEngineRoot();
44
66
  const validateRoot = () => {
67
+ signal?.throwIfAborted();
45
68
  if (root !== getEngineRoot())
46
69
  throw new Error("The Pi agent directory changed; reopen the review before continuing.");
47
70
  };
71
+ const configDocumentFingerprint = original && settingsDocumentFingerprint(original);
48
72
  const settingsFingerprint = syncCheckConfigFingerprint(config);
49
73
  const validateSettings = (document) => {
50
- signal?.throwIfAborted();
51
74
  validateRoot();
52
- const current = configFromSettings(document, setupName);
53
- if (settingsFingerprint !== syncCheckConfigFingerprint(current)) {
75
+ if ((original &&
76
+ (document?.path !== original.path || settingsDocumentFingerprint(document) !== configDocumentFingerprint)) ||
77
+ settingsFingerprint !==
78
+ syncCheckConfigFingerprint(configFromSettings(settingsFromCheckDocument(document), setupName))) {
54
79
  throw new Error("Pi Sync settings changed; reopen the review before continuing.");
55
80
  }
56
- return current;
57
81
  };
58
- const ignorePolicy = await loadEffectiveIgnorePolicy(root, ignorePolicyInput(config), signal);
59
- signal?.throwIfAborted();
82
+ const source = config.pathPolicy === "ignore-file" ? await readIgnoreSource(root, config.ignoreFile, signal) : undefined;
60
83
  validateRoot();
84
+ if (original && source && !source.present) {
85
+ throw new Error(`Ignore file is missing: ${safeTerminalText(path.join(root, source.filename))}. Create it and reopen Pi Sync; starter rules are only a preview.`);
86
+ }
87
+ if (original && source)
88
+ validateSettings(await readActiveLocalConfigDocumentForRepair());
61
89
  return {
62
90
  ...config,
63
- ignorePolicy,
91
+ ...(configDocumentFingerprint ? { configDocumentFingerprint } : {}),
92
+ ...(source ? { ignorePolicy: compileEffectiveIgnorePolicy(source, ignorePolicyInput(config)) } : {}),
93
+ ...(source?.identity ? { ignoreSourceIdentity: source.identity } : {}),
64
94
  validateIgnorePolicy: async () => {
65
- signal?.throwIfAborted();
66
95
  validateRoot();
67
96
  await withLockedLocalConfigDocument(async (document, recheck) => {
68
- const current = validateSettings(settingsFromCheckDocument(document));
69
- const source = await readIgnoreSource(root, current.ignoreFile, signal);
70
- validateRoot();
71
- recheck();
72
- if (source.sourceDigest !== ignorePolicy.sourceDigest) {
73
- throw new Error("Pi Sync ignore policy changed; reopen the review before continuing.");
97
+ validateSettings(document);
98
+ if (source) {
99
+ const current = await readIgnoreSource(root, source.filename, signal);
100
+ validateRoot();
101
+ recheck();
102
+ if (current.sourceDigest !== source.sourceDigest || current.identity !== source.identity) {
103
+ throw new Error("Pi Sync ignore policy changed; reopen the review before continuing.");
104
+ }
105
+ if (!current.present) {
106
+ throw new Error(`Ignore file "${source.filename}" is missing; starter rules can only be used for a preview.`);
107
+ }
74
108
  }
75
- if (!source.present) {
76
- throw new Error(`Ignore file "${source.filename}" is missing; starter rules can only be used for a preview.`);
109
+ else {
110
+ recheck();
77
111
  }
78
112
  }, signal, true);
79
- signal?.throwIfAborted();
80
113
  validateRoot();
81
114
  },
82
115
  };
@@ -140,6 +173,7 @@ export function syncSetupReviewIdentity(setupName, setup, connectionName, connec
140
173
  return syncConfigReviewIdentity(resolveSyncConfig(setupName, setup, connectionName, connection, DEFAULT_ON_SWITCH, false, true));
141
174
  }
142
175
  export function syncConfigReviewIdentity(config) {
176
+ const localPolicy = localIgnorePolicyKey(config);
143
177
  const directoryPolicy = config.pathPolicy === "ignore-file" && !config.ignorePolicy
144
178
  ? JSON.stringify([config.pathPolicy, config.ignoreFile])
145
179
  : syncDirectoryPolicyKey(config);
@@ -162,6 +196,7 @@ export function syncConfigReviewIdentity(config) {
162
196
  : config.exclude === undefined
163
197
  ? []
164
198
  : ["exclude", normalizeSyncExclude(config.exclude).map((rule) => rule.toLowerCase())]),
199
+ ...(localPolicy ? [localPolicy] : []),
165
200
  ]);
166
201
  }
167
202
  export function syncConfigReviewFingerprint(config) {
@@ -173,6 +208,14 @@ export function syncCheckConfigFingerprint(config) {
173
208
  .update(JSON.stringify({ ...config, showStatus: undefined, debug: undefined }))
174
209
  .digest("hex");
175
210
  }
211
+ export function syncSettingsConfigFingerprint(config) {
212
+ return syncCheckConfigFingerprint({
213
+ ...config,
214
+ configDocumentFingerprint: undefined,
215
+ ignoreSourceIdentity: undefined,
216
+ ignorePolicy: undefined,
217
+ });
218
+ }
176
219
  function storageReviewFromConfig(config) {
177
220
  return {
178
221
  connectionName: config.connectionName,
@@ -20,5 +20,7 @@ export declare function updateSyncSetup(name: string, update: (setup: SyncSetupS
20
20
  upgradeExclude?: boolean;
21
21
  signal?: AbortSignal;
22
22
  }): Promise<void>;
23
- export declare function removeSyncSetup(name: string, signal?: AbortSignal): Promise<void>;
23
+ export declare function removeSyncSetup(name: string, signal?: AbortSignal): Promise<{
24
+ revertedToLegacyOnly: boolean;
25
+ }>;
24
26
  export declare function removeStorageConnection(name: string, signal?: AbortSignal): Promise<void>;
@@ -122,8 +122,10 @@ export async function updateSyncSetup(name, update, options = {}) {
122
122
  }
123
123
  export async function removeSyncSetup(name, signal) {
124
124
  validateConfigName(name, "sync setup");
125
- await updateLocalConfig((settings) => {
126
- if (!Object.hasOwn(settings.syncSetups, name))
125
+ let removedLastIgnoreSetup = false;
126
+ const saved = await updateLocalConfig((settings) => {
127
+ const setup = settings.syncSetups[name];
128
+ if (!Object.hasOwn(settings.syncSetups, name) || !setup)
127
129
  throw new Error(`Sync setup not found: ${name}`);
128
130
  const isCurrent = settings.activeSyncSetup === name;
129
131
  if (isCurrent && Object.keys(settings.syncSetups).length > 1) {
@@ -131,11 +133,15 @@ export async function removeSyncSetup(name, signal) {
131
133
  }
132
134
  const syncSetups = { ...settings.syncSetups };
133
135
  delete syncSetups[name];
136
+ removedLastIgnoreSetup =
137
+ setup.sync.pathPolicy === "ignore-file" &&
138
+ !Object.values(syncSetups).some((remaining) => remaining.sync.pathPolicy === "ignore-file");
134
139
  const next = { ...settings, syncSetups };
135
140
  if (isCurrent)
136
141
  delete next.activeSyncSetup;
137
142
  return next;
138
143
  }, signal);
144
+ return { revertedToLegacyOnly: removedLastIgnoreSetup && saved.activeSyncSetup !== undefined };
139
145
  }
140
146
  export async function removeStorageConnection(name, signal) {
141
147
  validateConfigName(name, "storage connection");
@@ -128,6 +128,8 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
128
128
  reservedIgnoreNames?: readonly string[];
129
129
  ignorePolicy?: EffectiveIgnorePolicy;
130
130
  validateIgnorePolicy?: SnapshotOptions["validateIgnorePolicy"];
131
+ ignoreSourceIdentity?: string;
132
+ configDocumentFingerprint?: string;
131
133
  exclude?: string[];
132
134
  reinclude?: string[];
133
135
  automatic: boolean;
@@ -1,6 +1,7 @@
1
1
  import fs from "node:fs/promises";
2
2
  import os from "node:os";
3
3
  import path from "node:path";
4
+ import { backendIdentityCoordinates } from "../backends/backend-identity.js";
4
5
  import { getEngineRoot as getAgentDir, } from "../host.js";
5
6
  import { configuredSnapshotPathMatcher } from "../sync/sync-policy.js";
6
7
  import { agentDirectorySessionRoot, reservedIgnoreTargetGuard } from "./snapshot-exclude-safety.js";
@@ -142,9 +143,13 @@ export function snapshotOptionsForContext(ctx, config) {
142
143
  return {
143
144
  include: config.include,
144
145
  ...(config.scope === undefined ? {} : { scope: config.scope }),
145
- ...(config.ignorePolicy
146
- ? { ignorePolicy: config.ignorePolicy, validateIgnorePolicy: config.validateIgnorePolicy }
146
+ ...(config.setupName === undefined ? {} : { setupName: config.setupName }),
147
+ ...(config.backend && (config.ignorePolicy || config.reservedIgnoreNames !== undefined)
148
+ ? { recoverySetupKey: JSON.stringify([backendIdentityCoordinates(config), config.localFields]) }
147
149
  : {}),
150
+ ...(config.ignorePolicy ? { ignorePolicy: config.ignorePolicy } : {}),
151
+ ...(config.ignoreSourceIdentity === undefined ? {} : { ignoreSourceIdentity: config.ignoreSourceIdentity }),
152
+ ...(config.validateIgnorePolicy === undefined ? {} : { validateIgnorePolicy: config.validateIgnorePolicy }),
148
153
  ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
149
154
  ...(config.reinclude === undefined ? {} : { reinclude: config.reinclude }),
150
155
  ...(config.reservedIgnoreNames === undefined ? {} : { reservedIgnoreNames: config.reservedIgnoreNames }),
@@ -1,5 +1,5 @@
1
1
  import { type Snapshot, type SnapshotApplyPlan, type SnapshotOptions } from "./snapshot-types.js";
2
- export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "validateIgnorePolicy" | "expectedFileHashes"> & {
2
+ export declare function applySnapshot(snapshot: Snapshot, protectedRelativePaths?: Set<string>, options?: Pick<SnapshotOptions, "include" | "exclude" | "scope" | "reinclude" | "ignorePolicy" | "reservedIgnoreNames" | "setupName" | "recoverySetupKey" | "ignoreSourceIdentity" | "sessionDir" | "syncFiles" | "syncSessions" | "extraFiles" | "signal" | "validateMutation" | "validateIgnorePolicy" | "validateApplyReview" | "expectedFileHashes"> & {
3
3
  reviewedLocal?: Pick<Snapshot, "files">;
4
4
  }): Promise<{
5
5
  [k: string]: string;
@@ -5,6 +5,10 @@ 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
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;
8
12
  export declare function isScopedJournal(journal: TransactionJournalPolicy): boolean;
9
13
  export declare function isRecoveryStageId(value: unknown): value is string;
10
14
  export declare function isScopedIdentity(value: unknown): value is string;
@@ -19,10 +23,11 @@ export interface TransactionJournalPolicy {
19
23
  exclude?: string[];
20
24
  selection?: SnapshotSelection;
21
25
  ignoreSource?: IgnoreSourceBinding;
26
+ localPolicyKey?: string;
22
27
  }
23
28
  export declare function ignoreSourceBinding(policy: Pick<EffectiveIgnorePolicy, "filename" | "sourceDigest" | "reservedNames">): IgnoreSourceBinding;
24
29
  type TransactionGuards = Pick<SnapshotOptions, "validateIgnorePolicy" | "signal" | "validateMutation">;
25
- export interface TransactionOptions extends SyncSelectionConfig, TransactionGuards {
30
+ export interface TransactionOptions extends SyncSelectionConfig, TransactionGuards, RecoveryPolicyBinding, Pick<SnapshotOptions, "validateApplyReview"> {
26
31
  sessionDir?: string;
27
32
  exclude?: readonly string[];
28
33
  protectedTargets?: readonly string[];
@@ -33,7 +38,7 @@ export declare class StaleIgnorePolicyError extends Error {
33
38
  }
34
39
  export declare function ignorePolicyValidator(options: SyncSelectionConfig & TransactionGuards): (() => Promise<void>) | undefined;
35
40
  export declare function validateJournalPolicy(journal: TransactionJournalPolicy): void;
36
- export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: SyncSelectionConfig): void;
41
+ export declare function assertRecoveryPolicy(journal: TransactionJournalPolicy, options: TransactionOptions): void;
37
42
  export interface TransactionEntry {
38
43
  target: string;
39
44
  afterTarget?: string;
@@ -4,7 +4,7 @@ import { DEFAULT_IGNORE_FILENAME, validateIgnoreFilename } from "../ignore/ignor
4
4
  import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
5
5
  import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
6
6
  import { mergePathIdentity } from "../sync/file-merge-planner.js";
7
- import { portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
7
+ import { localIgnorePolicyKey, portableSnapshotSelection, sameSnapshotSelection, selectionForSnapshot, syncDirectoryPolicyKey, } from "../sync/sync-policy.js";
8
8
  import { agentDir } from "./session-paths.js";
9
9
  import { isCaseReplacement } from "./snapshot-case-replacement.js";
10
10
  import { sessionStorageRoot } from "./snapshot-paths.js";
@@ -13,16 +13,25 @@ export const LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION = 8;
13
13
  export const FIXED_WORKSPACE_JOURNAL_VERSION = 9;
14
14
  export const AGENT_DIRECTORY_JOURNAL_VERSION = 10;
15
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
+ }
16
24
  export function isScopedJournal(journal) {
17
25
  return [
18
26
  LEGACY_AGENT_DIRECTORY_JOURNAL_VERSION,
19
27
  FIXED_WORKSPACE_JOURNAL_VERSION,
20
28
  AGENT_DIRECTORY_JOURNAL_VERSION,
21
29
  IGNORE_POLICY_JOURNAL_VERSION,
30
+ BOUND_DIRECTORY_JOURNAL_VERSION,
22
31
  ].includes(journal.version);
23
32
  }
24
33
  function usesSlottedWorkspace(journal) {
25
- return journal.version === AGENT_DIRECTORY_JOURNAL_VERSION || journal.version === IGNORE_POLICY_JOURNAL_VERSION;
34
+ return journal.version >= AGENT_DIRECTORY_JOURNAL_VERSION && isScopedJournal(journal);
26
35
  }
27
36
  export function isRecoveryStageId(value) {
28
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));
@@ -55,10 +64,12 @@ function sameIgnoreSource(left, right) {
55
64
  export class StaleIgnorePolicyError extends Error {
56
65
  }
57
66
  export function ignorePolicyValidator(options) {
58
- if (!options.ignorePolicy && options.version !== 4)
67
+ const scopedIgnore = options.ignorePolicy !== undefined || options.version === 4;
68
+ if (!scopedIgnore && options.reservedIgnoreNames === undefined && !options.validateIgnorePolicy)
59
69
  return;
60
70
  const validateIgnorePolicy = options.validateIgnorePolicy;
61
- if (!options.ignorePolicy || options.scope !== "agent-directory" || typeof validateIgnorePolicy !== "function")
71
+ if ((scopedIgnore && (!options.ignorePolicy || options.scope !== "agent-directory")) ||
72
+ typeof validateIgnorePolicy !== "function")
62
73
  throw new Error("Ignore-file mutation requires an explicit local policy and a freshness check.");
63
74
  return async () => {
64
75
  options.validateMutation?.();
@@ -77,9 +88,15 @@ export function ignorePolicyValidator(options) {
77
88
  };
78
89
  }
79
90
  export function validateJournalPolicy(journal) {
80
- 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)))
81
93
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
82
- if (journal.version === IGNORE_POLICY_JOURNAL_VERSION) {
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)) {
83
100
  const binding = journal.ignoreSource;
84
101
  try {
85
102
  if (journal.exclude === undefined &&
@@ -109,9 +126,11 @@ export function validateJournalPolicy(journal) {
109
126
  normalizeSyncExclude(journal.exclude);
110
127
  }
111
128
  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 &&
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 &&
115
134
  options.scope === "agent-directory" &&
116
135
  options.ignorePolicy &&
117
136
  sameIgnoreSource(journal.ignoreSource, ignoreSourceBinding(options.ignorePolicy)) &&
@@ -130,16 +149,18 @@ export function assertRecoveryPolicy(journal, options) {
130
149
  export function validateJournal(directory, journal, sessionDir) {
131
150
  validateJournalPolicy(journal);
132
151
  const wholeDirectory = isScopedJournal(journal);
152
+ const scopedWorkspace = wholeDirectory && journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION;
133
153
  if (!Array.isArray(journal.entries) || journal.entries.length > 16_384)
134
154
  throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
135
155
  if (journal.completed !== undefined &&
136
- ((!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))
137
158
  throw new Error("Invalid transaction completion evidence.");
138
159
  const root = path.resolve(agentDir());
139
160
  if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
140
161
  throw new Error("Transaction root no longer matches the Pi agent directory.");
141
162
  if (journal.sessionRootTransition !== undefined) {
142
- if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
163
+ if (![7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version) || typeof journal.sessionRoot !== "string")
143
164
  throw new Error("Invalid session root-transition version.");
144
165
  validateSessionRootTransition(journal.sessionRootTransition);
145
166
  }
@@ -170,7 +191,7 @@ export function validateJournal(directory, journal, sessionDir) {
170
191
  assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
171
192
  assertAllowedTarget(root, journal.sessionRoot, entry.target);
172
193
  if (entry.afterTarget !== undefined &&
173
- ((!wholeDirectory && ![5, 6, 7].includes(journal.version)) ||
194
+ ((!wholeDirectory && ![5, 6, 7, BOUND_INCLUDED_PATHS_JOURNAL_VERSION].includes(journal.version)) ||
174
195
  typeof entry.afterTarget !== "string" ||
175
196
  !isCaseReplacement(root, entry.target, entry.afterTarget) ||
176
197
  path.resolve(entry.afterTarget) !== entry.afterTarget ||
@@ -183,8 +204,7 @@ export function validateJournal(directory, journal, sessionDir) {
183
204
  (entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
184
205
  (entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
185
206
  throw new Error("Invalid transaction postimage evidence.");
186
- if (entry.recoveryStaged !== undefined &&
187
- (typeof entry.recoveryStaged !== "boolean" || journal.version >= FIXED_WORKSPACE_JOURNAL_VERSION))
207
+ if (entry.recoveryStaged !== undefined && (typeof entry.recoveryStaged !== "boolean" || scopedWorkspace))
188
208
  throw new Error("Invalid recovery staging evidence.");
189
209
  if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
190
210
  throw new Error("Invalid transaction removal evidence.");
@@ -194,7 +214,7 @@ export function validateJournal(directory, journal, sessionDir) {
194
214
  if (entry.removalPending && entry.replacementStarted)
195
215
  throw new Error("Conflicting transaction replacement evidence.");
196
216
  if ((entry.recoveryWorkspace !== undefined &&
197
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
217
+ (!scopedWorkspace ||
198
218
  !isScopedIdentity(entry.recoveryWorkspace) ||
199
219
  entry.recoveryStaged ||
200
220
  !["file", "directory"].includes(entry.kind))) ||
@@ -203,7 +223,7 @@ export function validateJournal(directory, journal, sessionDir) {
203
223
  !entry.recoveryWorkspace ||
204
224
  !isRecoveryStageId(entry.recoveryWorkspaceId))) ||
205
225
  (entry.scopedRemoval !== undefined &&
206
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
226
+ (!scopedWorkspace ||
207
227
  !entry.removalPending ||
208
228
  !["before", "after"].includes(entry.scopedRemoval?.image) ||
209
229
  !isScopedIdentity(entry.scopedRemoval?.identity) ||
@@ -211,7 +231,7 @@ export function validateJournal(directory, journal, sessionDir) {
211
231
  ? !["file", "directory"].includes(entry.kind)
212
232
  : entry.afterImage === "missing" && !entry.postFiles?.length))) ||
213
233
  (entry.vacantInstall !== undefined &&
214
- (journal.version < FIXED_WORKSPACE_JOURNAL_VERSION ||
234
+ (!scopedWorkspace ||
215
235
  !entry.recoveryWorkspace ||
216
236
  !isScopedIdentity(entry.vacantInstall) ||
217
237
  entry.removalPending ||
@@ -19,7 +19,7 @@ import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgent
19
19
  import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
20
20
  import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedScopedPostTree, readTransactionJournal, recheckScopedImage, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
21
21
  import { indexTransactionPlan } from "./snapshot-transaction-plan.js";
22
- import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
22
+ import { AGENT_DIRECTORY_JOURNAL_VERSION, assertAllowedTarget, assertRecoveryPolicy, assertSafeParents, BOUND_DIRECTORY_JOURNAL_VERSION, BOUND_INCLUDED_PATHS_JOURNAL_VERSION, IGNORE_POLICY_JOURNAL_VERSION, ignorePolicyValidator, ignoreSourceBinding, isScopedJournal, isStrictlyInside, recoveryPolicyKey, StaleIgnorePolicyError, touchesProtectedTarget, transactionHasSessionTargets, validateJournal, validateJournalPolicy, } from "./snapshot-transaction-policy.js";
23
23
  import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
24
24
  import { verifyTarget } from "./snapshot-transaction-verification.js";
25
25
  const JOURNAL_VERSION = 4;
@@ -109,6 +109,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
109
109
  // A released additional key cannot authorize rollback, even for recognized raced bytes.
110
110
  const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
111
111
  try {
112
+ if (options.validateApplyReview)
113
+ await options.validateApplyReview();
112
114
  if (scoped && transaction.deletes.length)
113
115
  await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
114
116
  for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
@@ -122,6 +124,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
122
124
  await withMissingTargetQueues(transaction.journal.entries
123
125
  .filter((entry) => entry.removalPending)
124
126
  .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
127
+ if (options.validateApplyReview && transaction.journal.entries.some((entry) => entry.removalPending))
128
+ await options.validateApplyReview();
125
129
  if (validateIgnorePolicy)
126
130
  await validateIgnorePolicy();
127
131
  if (scoped && plan.writes.length)
@@ -170,10 +174,17 @@ export async function applySnapshotTransaction(plan, options = {}) {
170
174
  const verified = await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
171
175
  options.signal?.throwIfAborted();
172
176
  options.validateMutation?.();
173
- if (validateIgnorePolicy && verified.scoped) {
177
+ if (validateIgnorePolicy) {
174
178
  await validateIgnorePolicy();
175
- await recheckScopedImage(item.target, verified.scoped, options);
179
+ if (verified.scoped)
180
+ await recheckScopedImage(item.target, verified.scoped, options);
181
+ else {
182
+ await assertUnexcludedTargets(root, [item.target], options);
183
+ await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
184
+ }
176
185
  }
186
+ options.validateMutation?.();
187
+ options.signal?.throwIfAborted();
177
188
  await fs.rename(temp, item.target);
178
189
  await syncDirectory(path.dirname(item.target));
179
190
  }
@@ -278,6 +289,7 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
278
289
  const root = path.resolve(agentDir());
279
290
  const wholeDirectory = options.scope === "agent-directory";
280
291
  const ignoreSource = options.ignorePolicy ? ignoreSourceBinding(options.ignorePolicy) : undefined;
292
+ const localPolicyKey = recoveryPolicyKey(options);
281
293
  const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
282
294
  const indexed = indexTransactionPlan(plan, targets);
283
295
  const directory = path.join(transactionRoot(), randomUUID());
@@ -327,17 +339,22 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
327
339
  ? undefined
328
340
  : await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
329
341
  const journal = {
330
- version: ignoreSource
331
- ? IGNORE_POLICY_JOURNAL_VERSION
332
- : wholeDirectory
333
- ? AGENT_DIRECTORY_JOURNAL_VERSION
334
- : sessionRootTransition
335
- ? 7
336
- : replacements.size
337
- ? 5
338
- : JOURNAL_VERSION,
342
+ version: localPolicyKey
343
+ ? wholeDirectory
344
+ ? BOUND_DIRECTORY_JOURNAL_VERSION
345
+ : BOUND_INCLUDED_PATHS_JOURNAL_VERSION
346
+ : ignoreSource
347
+ ? IGNORE_POLICY_JOURNAL_VERSION
348
+ : wholeDirectory
349
+ ? AGENT_DIRECTORY_JOURNAL_VERSION
350
+ : sessionRootTransition
351
+ ? 7
352
+ : replacements.size
353
+ ? 5
354
+ : JOURNAL_VERSION,
339
355
  root,
340
356
  ignoreSource,
357
+ localPolicyKey,
341
358
  ...(wholeDirectory
342
359
  ? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
343
360
  : options.exclude === undefined
@@ -492,6 +509,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
492
509
  const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
493
510
  if (entry.kind === "file") {
494
511
  try {
512
+ options.validateMutation?.();
513
+ options.signal?.throwIfAborted();
495
514
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
496
515
  await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
497
516
  // Windows requires write access to flush an existing regular file.
@@ -532,6 +551,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
532
551
  options.signal?.throwIfAborted();
533
552
  if (atInstall === before && (await spellingMatches()))
534
553
  return;
554
+ if (validateIgnorePolicy) {
555
+ await validateIgnorePolicy();
556
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
557
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
558
+ }
559
+ options.validateMutation?.();
560
+ options.signal?.throwIfAborted();
535
561
  await fs.rename(temporary, entry.target);
536
562
  await syncDirectory(path.dirname(entry.target));
537
563
  });
@@ -542,6 +568,8 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
542
568
  continue;
543
569
  }
544
570
  try {
571
+ options.validateMutation?.();
572
+ options.signal?.throwIfAborted();
545
573
  await fs.mkdir(path.dirname(entry.target), { recursive: true });
546
574
  await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
547
575
  if (entry.kind === "directory") {
@@ -577,6 +605,13 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
577
605
  options.signal?.throwIfAborted();
578
606
  if (atInstall === before)
579
607
  return;
608
+ if (validateIgnorePolicy) {
609
+ await validateIgnorePolicy();
610
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
611
+ await verifyTarget(directory, entry, journal, options, atRename === "missing");
612
+ }
613
+ options.validateMutation?.();
614
+ options.signal?.throwIfAborted();
580
615
  await fs.rename(temporary, entry.target);
581
616
  await syncDirectory(path.dirname(entry.target));
582
617
  });
@@ -743,6 +778,13 @@ async function removeOwnedTarget(directory, entry, journal, options, { apply, re
743
778
  await removeScopedImage(entry.target, current.scoped, options, validateIgnorePolicy);
744
779
  }
745
780
  else {
781
+ if (validateIgnorePolicy) {
782
+ await validateIgnorePolicy();
783
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
784
+ await verifyTarget(directory, entry, journal, options);
785
+ }
786
+ options.validateMutation?.();
787
+ options.signal?.throwIfAborted();
746
788
  await fs.rm(entry.target, { recursive: true, force: true });
747
789
  }
748
790
  await syncDirectory(path.dirname(entry.target));
@@ -797,7 +839,7 @@ async function completeTransaction(directory, journal) {
797
839
  // may only retry cleanup, never roll back already accepted files.
798
840
  await writeJson(path.join(directory, "journal.json"), {
799
841
  ...journal,
800
- version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
842
+ version: isScopedJournal(journal) || journal.localPolicyKey ? journal.version : journal.sessionRootTransition ? 7 : 6,
801
843
  completed: true,
802
844
  }, {
803
845
  maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
@@ -70,10 +70,14 @@ export interface AgentDirectoryInventory {
70
70
  routingDirectories: ReadonlySet<string>;
71
71
  }
72
72
  export interface SnapshotOptions extends DirectoryScope {
73
+ setupName?: string;
74
+ recoverySetupKey?: string;
75
+ ignoreSourceIdentity?: string;
73
76
  signal?: AbortSignal;
74
77
  /** Caller-owned session/generation guard, rechecked at file-mutation boundaries. */
75
78
  validateMutation?: () => void;
76
79
  validateIgnorePolicy?: () => Promise<void>;
80
+ validateApplyReview?: () => Promise<void>;
77
81
  /** Reviewed regular-file preimages; null means the path was absent. Checked under mutation queues. */
78
82
  expectedFileHashes?: Readonly<Record<string, string | null>>;
79
83
  include?: string[];
@@ -45,6 +45,7 @@ export async function resolveAgentPlan(ctx, options, config, backend, state, loc
45
45
  1,
46
46
  backend.identity,
47
47
  syncConfigReviewIdentity(config),
48
+ ...(config.configDocumentFingerprint ? [config.configDocumentFingerprint] : []),
48
49
  syncStateFingerprint(state),
49
50
  head.revision,
50
51
  fileHashMap(localRaw),
@@ -66,8 +66,9 @@ export async function withAgentSyncLock(ctx, options, run) {
66
66
  if (!(await confirmAgentRefusalRetry(ctx, options.setup, request.evidence, validate, options.signal)))
67
67
  return "cancelled";
68
68
  }
69
+ const reserve = background?.reserve;
69
70
  const raw = cached === undefined || retry
70
- ? await runAgentResolver(ctx, request.evidence, validate, options.signal, background ? (signal) => background.reserve(request.key, signal) : undefined)
71
+ ? await runAgentResolver(ctx, request.evidence, validate, options.signal, reserve ? (signal) => reserve(request.key, signal) : undefined)
71
72
  : JSON.stringify(cached);
72
73
  let candidate;
73
74
  try {
@@ -84,6 +85,12 @@ export async function withAgentSyncLock(ctx, options, run) {
84
85
  await withLock("agent-cache-save", async () => {
85
86
  await assertOwner();
86
87
  options.signal?.throwIfAborted();
88
+ if (background) {
89
+ background.validate();
90
+ await request.validate(options.signal);
91
+ options.signal?.throwIfAborted();
92
+ background.validate();
93
+ }
87
94
  await saveAgentCandidate(request.key, candidate);
88
95
  });
89
96
  let retryCacheCommitted = false;