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