@narumitw/pi-sync-daemon 0.6.2 → 0.7.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 +8 -0
- package/README.md +1 -1
- package/dist/consent.js +11 -1
- package/dist/engine/backends/git/git-storage.js +11 -6
- package/dist/engine/paths.js +1 -1
- package/dist/engine/settings/config-file.js +2 -0
- package/dist/engine/settings/config.d.ts +2 -4
- package/dist/engine/settings/config.js +22 -7
- package/dist/engine/settings/settings-management.d.ts +2 -2
- package/dist/engine/settings/settings-management.js +27 -33
- package/dist/engine/settings/settings-types.d.ts +18 -4
- package/dist/engine/settings/settings-validation.js +34 -24
- package/dist/engine/snapshot/session-paths.d.ts +5 -3
- package/dist/engine/snapshot/session-paths.js +55 -9
- package/dist/engine/snapshot/snapshot-apply.d.ts +6 -7
- package/dist/engine/snapshot/snapshot-apply.js +88 -21
- package/dist/engine/snapshot/snapshot-bounds.d.ts +4 -0
- package/dist/engine/snapshot/snapshot-bounds.js +20 -0
- package/dist/engine/snapshot/snapshot-codec.js +3 -4
- package/dist/engine/snapshot/snapshot-entry-projection.d.ts +10 -0
- package/dist/engine/snapshot/snapshot-entry-projection.js +78 -0
- package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -2
- package/dist/engine/snapshot/snapshot-exclude-safety.js +180 -22
- package/dist/engine/snapshot/snapshot-payload.d.ts +2 -0
- package/dist/engine/snapshot/snapshot-payload.js +10 -0
- package/dist/engine/snapshot/snapshot-reviewed-preimages.d.ts +2 -0
- package/dist/engine/snapshot/snapshot-reviewed-preimages.js +60 -0
- package/dist/engine/snapshot/snapshot-root-transition.d.ts +4 -0
- package/dist/engine/snapshot/snapshot-root-transition.js +16 -0
- package/dist/engine/snapshot/snapshot-transaction-images.d.ts +37 -0
- package/dist/engine/snapshot/snapshot-transaction-images.js +357 -0
- package/dist/engine/snapshot/snapshot-transaction-policy.d.ts +50 -0
- package/dist/engine/snapshot/snapshot-transaction-policy.js +172 -0
- package/dist/engine/snapshot/snapshot-transaction-stage.d.ts +32 -0
- package/dist/engine/snapshot/snapshot-transaction-stage.js +303 -0
- package/dist/engine/snapshot/snapshot-transaction.d.ts +2 -1
- package/dist/engine/snapshot/snapshot-transaction.js +379 -331
- package/dist/engine/snapshot/snapshot-types.d.ts +24 -1
- package/dist/engine/snapshot/snapshot.d.ts +19 -2
- package/dist/engine/snapshot/snapshot.js +283 -26
- package/dist/engine/state/merge-baseline-store.js +20 -9
- package/dist/engine/state/state-types.d.ts +2 -0
- package/dist/engine/sync/apply-review.d.ts +3 -3
- package/dist/engine/sync/apply-review.js +5 -4
- package/dist/engine/sync/continuous-sync.js +19 -9
- package/dist/engine/sync/continuous-watch.d.ts +4 -1
- package/dist/engine/sync/continuous-watch.js +86 -14
- package/dist/engine/sync/exclude-policy.d.ts +4 -0
- package/dist/engine/sync/exclude-policy.js +8 -1
- package/dist/engine/sync/initialization.js +9 -5
- package/dist/engine/sync/local-fields.js +27 -8
- package/dist/engine/sync/merge-apply.js +155 -40
- package/dist/engine/sync/merge-journal.js +13 -4
- package/dist/engine/sync/merged-sync.js +21 -18
- package/dist/engine/sync/partial-progress.js +5 -3
- package/dist/engine/sync/remote-snapshot.d.ts +1 -0
- package/dist/engine/sync/remote-snapshot.js +8 -5
- package/dist/engine/sync/session-push.js +7 -6
- package/dist/engine/sync/sync-decision.d.ts +4 -0
- package/dist/engine/sync/sync-decision.js +17 -2
- package/dist/engine/sync/sync-inspection.js +3 -3
- package/dist/engine/sync/sync-mutations.d.ts +8 -1
- package/dist/engine/sync/sync-mutations.js +153 -72
- package/dist/engine/sync/sync-policy.d.ts +20 -10
- package/dist/engine/sync/sync-policy.js +170 -16
- package/dist/engine/sync/sync-queries.js +41 -31
- package/dist/engine/sync/sync-state.d.ts +11 -0
- package/dist/engine/sync/sync-state.js +24 -5
- package/dist/engine/ui/sync-format.js +22 -7
- package/docs/architecture.md +6 -0
- package/package.json +1 -1
|
@@ -1,33 +1,46 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
2
2
|
import fs from "node:fs/promises";
|
|
3
3
|
import path from "node:path";
|
|
4
|
-
import {
|
|
4
|
+
import { isPathInside } from "../paths.js";
|
|
5
5
|
import { syncDirectory, writeJson } from "../state/json-file.js";
|
|
6
6
|
import { withLock } from "../state/lock.js";
|
|
7
7
|
import { syncMutationParents } from "../state/mutation-directory-sync.js";
|
|
8
8
|
import { stateDir } from "../state/state-directory.js";
|
|
9
|
-
import { normalizeSyncExclude
|
|
9
|
+
import { normalizeSyncExclude } from "../sync/exclude-policy.js";
|
|
10
10
|
import { mergePathIdentity } from "../sync/file-merge-planner.js";
|
|
11
|
+
import { includeFromSelectionConfig, selectionForSnapshot } from "../sync/sync-policy.js";
|
|
11
12
|
import { agentDir, configuredSessionDir } from "./session-paths.js";
|
|
12
|
-
import {
|
|
13
|
+
import { agentDirectoryConfiguredSessionDir } from "./snapshot.js";
|
|
14
|
+
import { caseReplacementSpelling, coalesceCaseReplacements } from "./snapshot-case-replacement.js";
|
|
15
|
+
import { recheckAgentDirectoryBudget } from "./snapshot-entry-projection.js";
|
|
13
16
|
import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
|
|
14
17
|
import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
|
|
15
18
|
import { sessionStorageRoot } from "./snapshot-paths.js";
|
|
16
|
-
import { prepareSessionRootTransition, resolveTransitionSessionRoot,
|
|
19
|
+
import { prepareSessionRootTransition, resolveTransitionSessionRoot, stableAgentDirectorySettingsImage, } from "./snapshot-root-transition.js";
|
|
17
20
|
import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
|
|
18
|
-
import {
|
|
21
|
+
import { legacyImage, MAX_TRANSACTION_JOURNAL_BYTES, ownedLegacyPostTree, ownedScopedPostTree, ownedScopedSubset, readTransactionJournal, removeScopedImage, scopedDescendant, scopedIdentity, scopedPathIdentity, scopedTransactionImage, stableScopedIdentity, } from "./snapshot-transaction-images.js";
|
|
22
|
+
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";
|
|
24
|
+
import { assertNoUnclaimedLegacyStage, buildScopedRecoveryStage, cleanScopedLegacyStage, cleanScopedWorkspace, inspectScopedRecoveryStage, prepareLegacyRecoveryStage, recoveryStagePath, } from "./snapshot-transaction-stage.js";
|
|
19
25
|
const JOURNAL_VERSION = 4;
|
|
26
|
+
class ScopedRemovalError extends Error {
|
|
27
|
+
}
|
|
20
28
|
export async function applySnapshotTransaction(plan, options = {}) {
|
|
21
29
|
options.validateMutation?.();
|
|
30
|
+
const root = path.resolve(agentDir());
|
|
31
|
+
if (options.scope === "agent-directory") {
|
|
32
|
+
const sessionDir = options.sessionDir ?? (await agentDirectoryConfiguredSessionDir(options.signal, root));
|
|
33
|
+
options = { ...options, sessionDir: sessionStorageRoot(root, sessionDir) };
|
|
34
|
+
}
|
|
22
35
|
await recoverPendingSnapshotTransactions(options);
|
|
23
|
-
const coalesced = await coalesceCaseReplacements(
|
|
36
|
+
const coalesced = await coalesceCaseReplacements(root, plan);
|
|
24
37
|
options.validateMutation?.();
|
|
25
38
|
options.signal?.throwIfAborted();
|
|
26
39
|
const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
|
|
27
40
|
if (targets.length > 16_384)
|
|
28
41
|
throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
|
|
29
42
|
return withTargetQueues(targets, options, async (heldKeys) => {
|
|
30
|
-
await assertUnexcludedTargets(
|
|
43
|
+
await assertUnexcludedTargets(root, [...targets, ...coalesced.replacements.values()], options);
|
|
31
44
|
options.signal?.throwIfAborted();
|
|
32
45
|
if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
|
|
33
46
|
isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
|
|
@@ -39,13 +52,13 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
39
52
|
options.signal?.throwIfAborted();
|
|
40
53
|
}
|
|
41
54
|
const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
|
|
42
|
-
const
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
55
|
+
const scoped = options.scope === "agent-directory";
|
|
56
|
+
const expectedPreimages = new Map([...(options.expectedPreimages ?? [])]
|
|
57
|
+
.filter(([target]) => !scoped || !originalTargets.has(target))
|
|
58
|
+
.map(([target, expected]) => [originalTargets.get(target) ?? target, expected]));
|
|
46
59
|
// A case-sensitive spelling replacement has two targets, unlike a coalesced physical alias.
|
|
47
60
|
// Bind both the source bytes and destination absence/bytes before capturing their backups.
|
|
48
|
-
for (const [target, expected] of options.expectedPreimages ?? []) {
|
|
61
|
+
for (const [target, expected] of scoped ? [] : (options.expectedPreimages ?? [])) {
|
|
49
62
|
if (originalTargets.has(target))
|
|
50
63
|
continue;
|
|
51
64
|
const variants = coalesced.plan.deletes.filter((candidate) => candidate !== target &&
|
|
@@ -56,7 +69,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
56
69
|
const original = variants[0];
|
|
57
70
|
if (!original)
|
|
58
71
|
continue;
|
|
59
|
-
const destination = await
|
|
72
|
+
const destination = await legacyImage(target);
|
|
60
73
|
options.validateMutation?.();
|
|
61
74
|
options.signal?.throwIfAborted();
|
|
62
75
|
if (destination !== "missing" && destination !== expected)
|
|
@@ -64,8 +77,20 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
64
77
|
expectedPreimages.set(original, expected);
|
|
65
78
|
expectedPreimages.set(target, destination);
|
|
66
79
|
}
|
|
80
|
+
if (options.scope === "agent-directory") {
|
|
81
|
+
const evidence = await stableAgentDirectorySettingsImage(root, plan, options);
|
|
82
|
+
if (evidence) {
|
|
83
|
+
const target = originalTargets.get(evidence.target) ?? evidence.target;
|
|
84
|
+
const reviewed = expectedPreimages.get(target);
|
|
85
|
+
if (reviewed !== undefined && reviewed !== evidence.image)
|
|
86
|
+
throw new Error("Reviewed Pi settings changed before apply; snapshot installation refused.");
|
|
87
|
+
expectedPreimages.set(target, evidence.image);
|
|
88
|
+
}
|
|
89
|
+
}
|
|
67
90
|
for (const [target, expected] of expectedPreimages) {
|
|
68
|
-
|
|
91
|
+
if (scoped)
|
|
92
|
+
await assertUnexcludedTargets(root, [target], options);
|
|
93
|
+
const current = scoped ? (await scopedTransactionImage(target, options)).value : await legacyImage(target);
|
|
69
94
|
options.validateMutation?.();
|
|
70
95
|
options.signal?.throwIfAborted();
|
|
71
96
|
if (current !== expected)
|
|
@@ -79,17 +104,21 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
79
104
|
// A released additional key cannot authorize rollback, even for recognized raced bytes.
|
|
80
105
|
const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
|
|
81
106
|
try {
|
|
107
|
+
if (scoped && transaction.deletes.length)
|
|
108
|
+
await recheckAgentDirectoryBudget(root, plan, options, stateDir(root));
|
|
82
109
|
for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
|
|
83
110
|
options.signal?.throwIfAborted();
|
|
84
111
|
const entry = entriesByTarget.get(target);
|
|
85
112
|
if (!entry)
|
|
86
113
|
throw new Error("Unowned transaction target.");
|
|
87
|
-
await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
|
|
114
|
+
await removeOwnedTarget(transaction.directory, entry, transaction.journal, options, { apply: true });
|
|
88
115
|
await syncDirectory(path.dirname(target));
|
|
89
116
|
}
|
|
90
117
|
await withMissingTargetQueues(transaction.journal.entries
|
|
91
118
|
.filter((entry) => entry.removalPending)
|
|
92
119
|
.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
|
|
120
|
+
if (scoped && plan.writes.length)
|
|
121
|
+
await recheckAgentDirectoryBudget(root, { deletes: [], writes: plan.writes }, options);
|
|
93
122
|
await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
|
|
94
123
|
// Only this uninterrupted call knows which deleted writes have not attempted installation yet.
|
|
95
124
|
const uninstalledWrites = new Set(transaction.deletedWrites);
|
|
@@ -99,7 +128,9 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
99
128
|
if (!entry)
|
|
100
129
|
throw new Error("Unowned transaction target.");
|
|
101
130
|
const deletedByThisCall = uninstalledWrites.delete(entry.target);
|
|
102
|
-
|
|
131
|
+
if (options.scope === "agent-directory")
|
|
132
|
+
await assertUnexcludedTargets(transaction.journal.root, [item.target], options);
|
|
133
|
+
await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
|
|
103
134
|
options.validateMutation?.();
|
|
104
135
|
options.signal?.throwIfAborted();
|
|
105
136
|
await fs.mkdir(path.dirname(item.target), { recursive: true });
|
|
@@ -125,7 +156,7 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
125
156
|
finally {
|
|
126
157
|
await handle.close();
|
|
127
158
|
}
|
|
128
|
-
await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
|
|
159
|
+
await verifyTarget(transaction.directory, entry, transaction.journal, options, deletedByThisCall);
|
|
129
160
|
options.signal?.throwIfAborted();
|
|
130
161
|
options.validateMutation?.();
|
|
131
162
|
await fs.rename(temp, item.target);
|
|
@@ -146,6 +177,8 @@ export async function applySnapshotTransaction(plan, options = {}) {
|
|
|
146
177
|
// Aborted owners cannot roll back files after another session has replaced them.
|
|
147
178
|
if (options.signal?.aborted)
|
|
148
179
|
throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
|
|
180
|
+
if (error instanceof ScopedRemovalError)
|
|
181
|
+
throw error;
|
|
149
182
|
// Additional queues have been released. Recovery must reserve missing keys afresh.
|
|
150
183
|
if (changesQueueKey)
|
|
151
184
|
throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
|
|
@@ -181,24 +214,26 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
|
|
|
181
214
|
const directory = path.join(transactionRoot(), entry.name);
|
|
182
215
|
let journal;
|
|
183
216
|
try {
|
|
184
|
-
const
|
|
185
|
-
const stat = await fs.lstat(file);
|
|
186
|
-
if (!stat.isFile() || stat.size > 32 * 1024 * 1024)
|
|
187
|
-
throw new Error("Invalid journal file.");
|
|
188
|
-
journal = JSON.parse(await fs.readFile(file, "utf8"));
|
|
189
|
-
}
|
|
190
|
-
catch (error) {
|
|
217
|
+
const content = await readTransactionJournal(path.join(directory, "journal.json"), options);
|
|
191
218
|
// Unknown evidence is not disposable, including interrupted preparation directories.
|
|
192
|
-
if (
|
|
219
|
+
if (content === undefined)
|
|
193
220
|
continue;
|
|
221
|
+
journal = JSON.parse(content);
|
|
222
|
+
}
|
|
223
|
+
catch {
|
|
224
|
+
options.validateMutation?.();
|
|
225
|
+
options.signal?.throwIfAborted();
|
|
194
226
|
throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
|
|
195
227
|
}
|
|
228
|
+
validateJournalPolicy(journal);
|
|
229
|
+
if (!journal.completed)
|
|
230
|
+
assertRecoveryPolicy(journal, options);
|
|
196
231
|
let sessionDir = options.sessionDir;
|
|
197
|
-
if (sessionDir === undefined &&
|
|
198
|
-
options.
|
|
199
|
-
|
|
200
|
-
transactionHasSessionTargets(journal))
|
|
201
|
-
|
|
232
|
+
if (sessionDir === undefined && !journal.completed) {
|
|
233
|
+
if (options.scope === "agent-directory")
|
|
234
|
+
sessionDir = await agentDirectoryConfiguredSessionDir(options.signal);
|
|
235
|
+
else if (options.resolveConfiguredSessionDir && transactionHasSessionTargets(journal))
|
|
236
|
+
sessionDir = await configuredSessionDir();
|
|
202
237
|
}
|
|
203
238
|
options.validateMutation?.();
|
|
204
239
|
options.signal?.throwIfAborted();
|
|
@@ -210,8 +245,6 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
|
|
|
210
245
|
options.signal?.throwIfAborted();
|
|
211
246
|
}
|
|
212
247
|
validateJournal(directory, journal, sessionDir);
|
|
213
|
-
if (!journal.completed && !sameSyncExclude(journal.exclude, options.exclude))
|
|
214
|
-
throw new Error("Pending transaction has a different exclude policy; preserve its backup for reviewed recovery.");
|
|
215
248
|
if (journal.completed) {
|
|
216
249
|
await removeTransaction(directory);
|
|
217
250
|
continue;
|
|
@@ -222,7 +255,8 @@ export async function recoverPendingSnapshotTransactions(options = {}) {
|
|
|
222
255
|
async function prepareTransaction(plan, targets, options, replacements = new Map()) {
|
|
223
256
|
const { sessionDir } = options;
|
|
224
257
|
const root = path.resolve(agentDir());
|
|
225
|
-
const
|
|
258
|
+
const wholeDirectory = options.scope === "agent-directory";
|
|
259
|
+
const sessionRoot = sessionDir || wholeDirectory ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
|
|
226
260
|
const indexed = indexTransactionPlan(plan, targets);
|
|
227
261
|
const directory = path.join(transactionRoot(), randomUUID());
|
|
228
262
|
const backupDirectory = path.join(directory, "before");
|
|
@@ -233,52 +267,25 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
|
|
|
233
267
|
options.validateMutation?.();
|
|
234
268
|
assertAllowedTarget(root, sessionRoot, target);
|
|
235
269
|
await assertSafeParents(root, sessionRoot, target);
|
|
270
|
+
if (wholeDirectory)
|
|
271
|
+
await assertUnexcludedTargets(root, [target], options);
|
|
236
272
|
const entry = { target, backupName: `${index}`, kind: "missing" };
|
|
237
273
|
if (replacements.has(target))
|
|
238
274
|
entry.afterTarget = replacements.get(target);
|
|
239
275
|
const backup = path.join(backupDirectory, entry.backupName);
|
|
240
|
-
|
|
241
|
-
const
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
entry.linkTarget = await fs.readlink(target);
|
|
245
|
-
}
|
|
246
|
-
else if (stat.isDirectory()) {
|
|
247
|
-
entry.kind = "directory";
|
|
248
|
-
await fs.cp(target, backup, {
|
|
249
|
-
recursive: true,
|
|
250
|
-
dereference: false,
|
|
251
|
-
verbatimSymlinks: true,
|
|
252
|
-
preserveTimestamps: true,
|
|
253
|
-
filter: () => {
|
|
254
|
-
options.signal?.throwIfAborted();
|
|
255
|
-
options.validateMutation?.();
|
|
256
|
-
return true;
|
|
257
|
-
},
|
|
258
|
-
});
|
|
259
|
-
}
|
|
260
|
-
else if (stat.isFile()) {
|
|
261
|
-
entry.kind = "file";
|
|
262
|
-
await fs.copyFile(target, backup);
|
|
263
|
-
await fs.chmod(backup, stat.mode);
|
|
264
|
-
}
|
|
265
|
-
else
|
|
266
|
-
throw new Error("Unsupported existing snapshot target.");
|
|
276
|
+
if (wholeDirectory) {
|
|
277
|
+
const captured = await scopedTransactionImage(target, options, backup, (source) => assertUnexcludedTargets(root, [source], options, { recursive: false }));
|
|
278
|
+
entry.kind = captured.kind;
|
|
279
|
+
entry.beforeImage = captured.value;
|
|
267
280
|
}
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
if (code !== "ENOENT" && code !== "ENOTDIR")
|
|
271
|
-
throw error;
|
|
281
|
+
else {
|
|
282
|
+
await captureLegacyBackup(target, backup, entry, options);
|
|
272
283
|
}
|
|
273
|
-
entry.beforeImage =
|
|
274
|
-
entry.kind === "symlink"
|
|
275
|
-
? `symlink:${entry.linkTarget}`
|
|
276
|
-
: entry.kind === "missing"
|
|
277
|
-
? "missing"
|
|
278
|
-
: await image(backup, true);
|
|
279
284
|
options.validateMutation?.();
|
|
280
285
|
options.signal?.throwIfAborted();
|
|
281
286
|
const expected = options.expectedPreimages?.get(target);
|
|
287
|
+
if (wholeDirectory && entry.kind === "directory" && expected === undefined)
|
|
288
|
+
throw new Error("Scoped directory replacement requires a reviewed preimage.");
|
|
282
289
|
if (expected !== undefined && entry.beforeImage !== expected)
|
|
283
290
|
throw new Error("Reviewed file preimage changed during backup; private preparation evidence retained.");
|
|
284
291
|
if (entry.afterTarget) {
|
|
@@ -294,23 +301,76 @@ async function prepareTransaction(plan, targets, options, replacements = new Map
|
|
|
294
301
|
// File fsync does not persist the name linking each backup into this directory.
|
|
295
302
|
await syncDirectory(backupDirectory);
|
|
296
303
|
const effectiveRoot = sessionRoot ?? path.join(root, "sessions");
|
|
297
|
-
const sessionRootTransition =
|
|
304
|
+
const sessionRootTransition = wholeDirectory
|
|
305
|
+
? undefined
|
|
306
|
+
: await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
|
|
298
307
|
const journal = {
|
|
299
|
-
version:
|
|
308
|
+
version: wholeDirectory
|
|
309
|
+
? AGENT_DIRECTORY_JOURNAL_VERSION
|
|
310
|
+
: sessionRootTransition
|
|
311
|
+
? 7
|
|
312
|
+
: replacements.size
|
|
313
|
+
? 5
|
|
314
|
+
: JOURNAL_VERSION,
|
|
300
315
|
root,
|
|
301
|
-
...(
|
|
316
|
+
...(wholeDirectory
|
|
317
|
+
? { selection: selectionForSnapshot(includeFromSelectionConfig(options), options.exclude, options) }
|
|
318
|
+
: options.exclude === undefined
|
|
319
|
+
? {}
|
|
320
|
+
: { exclude: normalizeSyncExclude(options.exclude) }),
|
|
302
321
|
sessionRoot: sessionRootTransition ? effectiveRoot : sessionRoot,
|
|
303
322
|
sessionRootTransition,
|
|
304
323
|
entries,
|
|
305
324
|
};
|
|
306
325
|
options.signal?.throwIfAborted();
|
|
307
326
|
options.validateMutation?.();
|
|
308
|
-
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes:
|
|
327
|
+
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
|
|
309
328
|
await syncDirectory(transactionRoot());
|
|
310
329
|
await syncDirectory(stateDir());
|
|
311
330
|
await syncDirectory(path.dirname(stateDir()));
|
|
312
331
|
return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
|
|
313
332
|
}
|
|
333
|
+
async function captureLegacyBackup(target, backup, entry, options) {
|
|
334
|
+
try {
|
|
335
|
+
const stat = await fs.lstat(target);
|
|
336
|
+
if (stat.isSymbolicLink()) {
|
|
337
|
+
entry.kind = "symlink";
|
|
338
|
+
entry.linkTarget = await fs.readlink(target);
|
|
339
|
+
}
|
|
340
|
+
else if (stat.isDirectory()) {
|
|
341
|
+
entry.kind = "directory";
|
|
342
|
+
await fs.cp(target, backup, {
|
|
343
|
+
recursive: true,
|
|
344
|
+
dereference: false,
|
|
345
|
+
verbatimSymlinks: true,
|
|
346
|
+
preserveTimestamps: true,
|
|
347
|
+
filter: () => {
|
|
348
|
+
options.signal?.throwIfAborted();
|
|
349
|
+
options.validateMutation?.();
|
|
350
|
+
return true;
|
|
351
|
+
},
|
|
352
|
+
});
|
|
353
|
+
}
|
|
354
|
+
else if (stat.isFile()) {
|
|
355
|
+
entry.kind = "file";
|
|
356
|
+
await fs.copyFile(target, backup);
|
|
357
|
+
await fs.chmod(backup, stat.mode);
|
|
358
|
+
}
|
|
359
|
+
else
|
|
360
|
+
throw new Error("Unsupported existing snapshot target.");
|
|
361
|
+
}
|
|
362
|
+
catch (error) {
|
|
363
|
+
const code = error.code;
|
|
364
|
+
if (code !== "ENOENT" && code !== "ENOTDIR")
|
|
365
|
+
throw error;
|
|
366
|
+
}
|
|
367
|
+
entry.beforeImage =
|
|
368
|
+
entry.kind === "symlink"
|
|
369
|
+
? `symlink:${entry.linkTarget}`
|
|
370
|
+
: entry.kind === "missing"
|
|
371
|
+
? "missing"
|
|
372
|
+
: await legacyImage(backup, true);
|
|
373
|
+
}
|
|
314
374
|
async function restoreTransaction(directory, journal, options, heldKeys) {
|
|
315
375
|
validateJournal(directory, journal, options.sessionDir);
|
|
316
376
|
const missingSpellings = [];
|
|
@@ -331,15 +391,30 @@ async function restoreTransaction(directory, journal, options, heldKeys) {
|
|
|
331
391
|
}
|
|
332
392
|
async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
333
393
|
validateJournal(directory, journal, options.sessionDir);
|
|
394
|
+
const scoped = isScopedJournal(journal);
|
|
334
395
|
options.validateMutation?.();
|
|
335
396
|
options.signal?.throwIfAborted();
|
|
397
|
+
await assertUnexcludedTargets(journal.root, journal.entries.flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), options);
|
|
336
398
|
for (const entry of journal.entries) {
|
|
337
399
|
if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
|
|
338
400
|
isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
|
|
339
401
|
throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
|
|
340
|
-
await verifyTarget(directory, entry, journal);
|
|
402
|
+
const { value, before } = await verifyTarget(directory, entry, journal, options);
|
|
403
|
+
if (scoped) {
|
|
404
|
+
await assertNoUnclaimedLegacyStage(directory, entry, options);
|
|
405
|
+
const stage = await inspectScopedRecoveryStage(directory, entry, options);
|
|
406
|
+
if (entry.recoveryWorkspace && !stage && value !== before)
|
|
407
|
+
throw new Error("Recovery workspace is missing; preserve evidence for review.");
|
|
408
|
+
if (entry.vacantInstall && value === "missing") {
|
|
409
|
+
if (!stage ||
|
|
410
|
+
stage.image.kind === "missing" ||
|
|
411
|
+
stage.image.value !== before ||
|
|
412
|
+
stage.partial.kind !== "missing" ||
|
|
413
|
+
scopedIdentity(stage.image.stat) !== entry.vacantInstall)
|
|
414
|
+
throw new Error("Recovery vacancy has no verified staging image; preserve evidence for review.");
|
|
415
|
+
}
|
|
416
|
+
}
|
|
341
417
|
}
|
|
342
|
-
// Recover copies left by a process crash even when the target is already restored.
|
|
343
418
|
for (const entry of journal.entries) {
|
|
344
419
|
if (!entry.recoveryStaged)
|
|
345
420
|
continue;
|
|
@@ -348,21 +423,42 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
348
423
|
await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
|
|
349
424
|
options.validateMutation?.();
|
|
350
425
|
options.signal?.throwIfAborted();
|
|
351
|
-
|
|
426
|
+
if (scoped)
|
|
427
|
+
await cleanScopedLegacyStage(directory, entry, options);
|
|
428
|
+
else
|
|
429
|
+
await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
|
|
430
|
+
options.validateMutation?.();
|
|
431
|
+
options.signal?.throwIfAborted();
|
|
432
|
+
}
|
|
433
|
+
if (scoped && journal.version !== AGENT_DIRECTORY_JOURNAL_VERSION) {
|
|
434
|
+
journal.version = AGENT_DIRECTORY_JOURNAL_VERSION;
|
|
435
|
+
for (const entry of journal.entries)
|
|
436
|
+
delete entry.recoveryStaged;
|
|
352
437
|
options.validateMutation?.();
|
|
353
438
|
options.signal?.throwIfAborted();
|
|
439
|
+
await persistJournal(directory, journal);
|
|
354
440
|
}
|
|
355
441
|
// Verify the complete group before removing any path. Recheck each destructive boundary.
|
|
356
442
|
for (const entry of [...journal.entries].sort((a, b) => a.target.length - b.target.length)) {
|
|
357
|
-
const current = await verifyTarget(directory, entry, journal);
|
|
358
|
-
const before = await beforeImage(directory, entry);
|
|
443
|
+
const { value: current, before } = await verifyTarget(directory, entry, journal, options);
|
|
359
444
|
const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
|
|
360
|
-
if (current === before && (await spellingMatches()))
|
|
445
|
+
if (current === before && (await spellingMatches())) {
|
|
446
|
+
if (entry.recoveryWorkspace)
|
|
447
|
+
await cleanScopedWorkspace(directory, entry, options);
|
|
361
448
|
continue;
|
|
449
|
+
}
|
|
362
450
|
options.signal?.throwIfAborted();
|
|
363
451
|
options.validateMutation?.();
|
|
452
|
+
if (entry.kind === "missing") {
|
|
453
|
+
await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before });
|
|
454
|
+
continue;
|
|
455
|
+
}
|
|
456
|
+
if (scoped) {
|
|
457
|
+
await restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches);
|
|
458
|
+
continue;
|
|
459
|
+
}
|
|
460
|
+
const temporary = await prepareLegacyRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
|
|
364
461
|
if (entry.kind === "file") {
|
|
365
|
-
const temporary = await prepareRecoveryStage(directory, journal, entry, options);
|
|
366
462
|
try {
|
|
367
463
|
await fs.mkdir(path.dirname(entry.target), { recursive: true });
|
|
368
464
|
await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
|
|
@@ -374,7 +470,7 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
374
470
|
finally {
|
|
375
471
|
await handle.close();
|
|
376
472
|
}
|
|
377
|
-
const verified = await verifyTarget(directory, entry, journal);
|
|
473
|
+
const { value: verified } = await verifyTarget(directory, entry, journal, options);
|
|
378
474
|
options.validateMutation?.();
|
|
379
475
|
options.signal?.throwIfAborted();
|
|
380
476
|
if (verified === before && (await spellingMatches()))
|
|
@@ -386,20 +482,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
386
482
|
await removeOwnedTarget(directory, entry, journal, options);
|
|
387
483
|
}
|
|
388
484
|
else if (verified.startsWith("directory:") &&
|
|
389
|
-
!(await removeOwnedTarget(directory, entry, journal, options, before)))
|
|
485
|
+
!(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
|
|
390
486
|
continue;
|
|
391
487
|
await withMissingTargetQueues(entry.afterTarget && (needsCaseQueue || verified === "missing")
|
|
392
488
|
? [entry.target, entry.afterTarget]
|
|
393
489
|
: verified.startsWith("directory:")
|
|
394
490
|
? [entry.target]
|
|
395
491
|
: [], heldKeys, options, async () => {
|
|
396
|
-
const atRename = await verifyTarget(directory, entry, journal);
|
|
492
|
+
const { value: atRename } = await verifyTarget(directory, entry, journal, options);
|
|
397
493
|
options.validateMutation?.();
|
|
398
494
|
options.signal?.throwIfAborted();
|
|
399
495
|
if (atRename === before && (await spellingMatches()))
|
|
400
496
|
return;
|
|
401
497
|
await retireRestorationIntent(directory, journal, entry, options);
|
|
402
|
-
const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
|
|
498
|
+
const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
|
|
403
499
|
options.validateMutation?.();
|
|
404
500
|
options.signal?.throwIfAborted();
|
|
405
501
|
if (atInstall === before && (await spellingMatches()))
|
|
@@ -413,11 +509,6 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
413
509
|
}
|
|
414
510
|
continue;
|
|
415
511
|
}
|
|
416
|
-
if (entry.kind === "missing") {
|
|
417
|
-
await removeOwnedTarget(directory, entry, journal, options, before);
|
|
418
|
-
continue;
|
|
419
|
-
}
|
|
420
|
-
const temporary = await prepareRecoveryStage(directory, journal, entry, options);
|
|
421
512
|
try {
|
|
422
513
|
await fs.mkdir(path.dirname(entry.target), { recursive: true });
|
|
423
514
|
await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
|
|
@@ -436,20 +527,20 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
436
527
|
}
|
|
437
528
|
else if (entry.linkTarget !== undefined)
|
|
438
529
|
await fs.symlink(entry.linkTarget, temporary);
|
|
439
|
-
if ((await
|
|
530
|
+
if ((await legacyImage(temporary, true)) !== before)
|
|
440
531
|
throw new Error("Staged recovery image differs from the backup; evidence retained.");
|
|
441
532
|
options.validateMutation?.();
|
|
442
533
|
options.signal?.throwIfAborted();
|
|
443
|
-
if (!(await removeOwnedTarget(directory, entry, journal, options, before)))
|
|
534
|
+
if (!(await removeOwnedTarget(directory, entry, journal, options, { restoringBefore: before })))
|
|
444
535
|
continue;
|
|
445
536
|
await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
|
|
446
|
-
const atRename = await verifyTarget(directory, entry, journal);
|
|
537
|
+
const { value: atRename } = await verifyTarget(directory, entry, journal, options);
|
|
447
538
|
options.validateMutation?.();
|
|
448
539
|
options.signal?.throwIfAborted();
|
|
449
540
|
if (atRename === before)
|
|
450
541
|
return;
|
|
451
542
|
await retireRestorationIntent(directory, journal, entry, options);
|
|
452
|
-
const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
|
|
543
|
+
const { value: atInstall } = await verifyTarget(directory, entry, journal, options, atRename === "missing");
|
|
453
544
|
options.validateMutation?.();
|
|
454
545
|
options.signal?.throwIfAborted();
|
|
455
546
|
if (atInstall === before)
|
|
@@ -467,52 +558,196 @@ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
|
|
|
467
558
|
options.signal?.throwIfAborted();
|
|
468
559
|
await completeTransaction(directory, journal);
|
|
469
560
|
}
|
|
470
|
-
async function
|
|
561
|
+
async function restoreScopedEntry(directory, journal, entry, options, heldKeys, before, spellingMatches) {
|
|
562
|
+
options.validateMutation?.();
|
|
563
|
+
options.signal?.throwIfAborted();
|
|
564
|
+
await fs.mkdir(path.dirname(entry.target), { recursive: true });
|
|
565
|
+
await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
|
|
566
|
+
if (!entry.vacantInstall)
|
|
567
|
+
await buildScopedRecoveryStage(directory, entry, options, () => persistJournal(directory, journal));
|
|
568
|
+
const verifyStage = async () => {
|
|
569
|
+
const stage = await inspectScopedRecoveryStage(directory, entry, options, true);
|
|
570
|
+
if (!stage || stage.image.kind === "missing" || stage.image.value !== before || stage.partial.kind !== "missing")
|
|
571
|
+
throw new Error("Staged recovery image changed; evidence retained.");
|
|
572
|
+
if (entry.vacantInstall && scopedIdentity(stage.image.stat) !== entry.vacantInstall)
|
|
573
|
+
throw new Error("Recovery vacancy has a different staging image; preserve evidence for review.");
|
|
574
|
+
const identity = stableScopedIdentity(stage.payload, stage.image.stat);
|
|
575
|
+
return { payload: stage.payload, identity };
|
|
576
|
+
};
|
|
577
|
+
await verifyStage();
|
|
578
|
+
const { value: verified } = await verifyTarget(directory, entry, journal, options);
|
|
579
|
+
if (verified !== before || !(await spellingMatches())) {
|
|
580
|
+
const needsCaseQueue = entry.afterTarget !== undefined &&
|
|
581
|
+
(await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.afterTarget;
|
|
582
|
+
const needsRemoval = verified !== "missing" && (needsCaseQueue || verified.startsWith("directory:") || entry.kind === "directory");
|
|
583
|
+
const needsVacantTarget = needsRemoval || verified === "missing";
|
|
584
|
+
if (!needsRemoval ||
|
|
585
|
+
(await removeOwnedTarget(directory, entry, journal, options, {
|
|
586
|
+
restoringBefore: needsCaseQueue ? undefined : before,
|
|
587
|
+
}))) {
|
|
588
|
+
const queueTargets = needsVacantTarget ? [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])] : [];
|
|
589
|
+
await withMissingTargetQueues(queueTargets, heldKeys, options, async () => {
|
|
590
|
+
const { value: atRename } = await verifyTarget(directory, entry, journal, options);
|
|
591
|
+
if (atRename === before && (await spellingMatches()))
|
|
592
|
+
return;
|
|
593
|
+
if (needsVacantTarget && atRename !== "missing")
|
|
594
|
+
throw new Error("Transaction target changed after removal; preserve evidence for review.");
|
|
595
|
+
const stage = await verifyStage();
|
|
596
|
+
if (needsVacantTarget && !entry.vacantInstall) {
|
|
597
|
+
entry.vacantInstall = stage.identity;
|
|
598
|
+
delete entry.removalPending;
|
|
599
|
+
delete entry.replacementStarted;
|
|
600
|
+
delete entry.scopedRemoval;
|
|
601
|
+
for (const child of journal.entries) {
|
|
602
|
+
if (isStrictlyInside(entry.target, child.target))
|
|
603
|
+
delete child.scopedRemoval;
|
|
604
|
+
}
|
|
605
|
+
options.validateMutation?.();
|
|
606
|
+
options.signal?.throwIfAborted();
|
|
607
|
+
await syncDirectory(path.dirname(entry.target));
|
|
608
|
+
options.validateMutation?.();
|
|
609
|
+
options.signal?.throwIfAborted();
|
|
610
|
+
await persistJournal(directory, journal);
|
|
611
|
+
await verifyStage();
|
|
612
|
+
}
|
|
613
|
+
if ((await scopedPathIdentity(stage.payload, options)) !== stage.identity)
|
|
614
|
+
throw new Error("Staged recovery image changed before restoration; preserve evidence for review.");
|
|
615
|
+
const { value: atInstall } = await verifyTarget(directory, entry, journal, options);
|
|
616
|
+
if (atInstall === before && (await spellingMatches()))
|
|
617
|
+
return;
|
|
618
|
+
if (atInstall !== atRename)
|
|
619
|
+
throw new Error("Transaction target changed before restoration; preserve evidence for review.");
|
|
620
|
+
options.validateMutation?.();
|
|
621
|
+
options.signal?.throwIfAborted();
|
|
622
|
+
await fs.rename(stage.payload, entry.target);
|
|
623
|
+
await syncDirectory(path.dirname(entry.target));
|
|
624
|
+
await syncDirectory(path.dirname(stage.payload));
|
|
625
|
+
if ((await verifyTarget(directory, entry, journal, options)).value !== before)
|
|
626
|
+
throw new Error("Restored transaction image changed; evidence retained.");
|
|
627
|
+
});
|
|
628
|
+
}
|
|
629
|
+
}
|
|
630
|
+
await cleanScopedWorkspace(directory, entry, options);
|
|
631
|
+
}
|
|
632
|
+
async function verifyTarget(directory, entry, journal, options, deletedByThisCall = false) {
|
|
471
633
|
await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
|
|
634
|
+
const isScoped = isScopedJournal(journal);
|
|
472
635
|
// Hash the potentially large backup before observing the live target, not after it.
|
|
473
|
-
const
|
|
474
|
-
|
|
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))
|
|
475
641
|
throw new Error("Transaction backup changed; preserve evidence for review.");
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
const
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
if (
|
|
482
|
-
if (
|
|
483
|
-
|
|
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;
|
|
484
676
|
}
|
|
485
|
-
else if (journal.version >= 2 &&
|
|
486
|
-
(current === entry.afterImage ||
|
|
487
|
-
(await ownedPostTree(entry.target, entry.postFiles ?? [], journal.version < 4 || entry.replacementStarted === true || !entry.removalPending))))
|
|
488
|
-
return current;
|
|
489
677
|
throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
|
|
490
678
|
}
|
|
491
|
-
async function removeOwnedTarget(directory, entry, journal, options, restoringBefore) {
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
679
|
+
async function removeOwnedTarget(directory, entry, journal, options, { apply, restoringBefore } = {}) {
|
|
680
|
+
const scoped = isScopedJournal(journal);
|
|
681
|
+
try {
|
|
682
|
+
await assertUnexcludedTargets(journal.root, [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])], options);
|
|
683
|
+
const current = await verifyTarget(directory, entry, journal, options);
|
|
684
|
+
options.validateMutation?.();
|
|
685
|
+
options.signal?.throwIfAborted();
|
|
686
|
+
if (restoringBefore !== undefined && current.value === restoringBefore)
|
|
687
|
+
return false;
|
|
688
|
+
if (scoped && apply && current.value !== current.before)
|
|
689
|
+
throw new Error("Reviewed removal image changed; preserve evidence for review.");
|
|
690
|
+
// Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
|
|
691
|
+
upgradeRemovalEvidence(journal);
|
|
692
|
+
for (const affected of journal.entries) {
|
|
693
|
+
if (affected.target !== entry.target && !isStrictlyInside(entry.target, affected.target))
|
|
694
|
+
continue;
|
|
503
695
|
affected.removalPending = true;
|
|
504
696
|
affected.replacementStarted = false;
|
|
697
|
+
if (affected.vacantInstall)
|
|
698
|
+
throw new Error("Transaction removal overlaps a recovery vacancy; preserve evidence for review.");
|
|
699
|
+
if (!current.scoped)
|
|
700
|
+
continue;
|
|
701
|
+
const relative = path.relative(entry.target, affected.target);
|
|
702
|
+
const observed = scopedDescendant(current.scoped, relative);
|
|
703
|
+
if (!observed || observed.kind === "missing")
|
|
704
|
+
continue;
|
|
705
|
+
const observedPath = path.join(entry.target, relative);
|
|
706
|
+
const mayChange = observed.kind === "directory" && observed.children.length > 0;
|
|
707
|
+
if (affected.scopedRemoval) {
|
|
708
|
+
if (mayChange)
|
|
709
|
+
stableScopedIdentity(observedPath, observed.stat);
|
|
710
|
+
continue;
|
|
711
|
+
}
|
|
712
|
+
const image = observed.value === affected.beforeImage
|
|
713
|
+
? "before"
|
|
714
|
+
: observed.value === affected.afterImage || ownedScopedPostTree(observed, affected.postFiles ?? [], true)
|
|
715
|
+
? "after"
|
|
716
|
+
: undefined;
|
|
717
|
+
if (!image)
|
|
718
|
+
continue;
|
|
719
|
+
affected.scopedRemoval = {
|
|
720
|
+
image,
|
|
721
|
+
identity: mayChange ? stableScopedIdentity(observedPath, observed.stat) : scopedIdentity(observed.stat),
|
|
722
|
+
};
|
|
723
|
+
}
|
|
724
|
+
options.validateMutation?.();
|
|
725
|
+
options.signal?.throwIfAborted();
|
|
726
|
+
await persistJournal(directory, journal);
|
|
727
|
+
const verified = await verifyTarget(directory, entry, journal, options);
|
|
728
|
+
options.validateMutation?.();
|
|
729
|
+
options.signal?.throwIfAborted();
|
|
730
|
+
if (restoringBefore !== undefined && verified.value === restoringBefore)
|
|
731
|
+
return false;
|
|
732
|
+
if (current.scoped) {
|
|
733
|
+
if (current.value !== verified.value)
|
|
734
|
+
throw new Error("Transaction removal image changed.");
|
|
735
|
+
await assertUnexcludedTargets(journal.root, [entry.target], options);
|
|
736
|
+
await removeScopedImage(entry.target, current.scoped, options);
|
|
737
|
+
}
|
|
738
|
+
else {
|
|
739
|
+
await fs.rm(entry.target, { recursive: true, force: true });
|
|
505
740
|
}
|
|
741
|
+
await syncDirectory(path.dirname(entry.target));
|
|
742
|
+
return true;
|
|
743
|
+
}
|
|
744
|
+
catch (error) {
|
|
745
|
+
if (!scoped)
|
|
746
|
+
throw error;
|
|
747
|
+
throw new ScopedRemovalError("Scoped transaction removal stopped; preserve transaction and backup for review.", {
|
|
748
|
+
cause: error,
|
|
749
|
+
});
|
|
506
750
|
}
|
|
507
|
-
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
|
|
508
|
-
const verified = await verifyTarget(directory, entry, journal);
|
|
509
|
-
options.validateMutation?.();
|
|
510
|
-
options.signal?.throwIfAborted();
|
|
511
|
-
if (restoringBefore !== undefined && verified === restoringBefore)
|
|
512
|
-
return false;
|
|
513
|
-
await fs.rm(entry.target, { recursive: true, force: true });
|
|
514
|
-
await syncDirectory(path.dirname(entry.target));
|
|
515
|
-
return true;
|
|
516
751
|
}
|
|
517
752
|
function upgradeRemovalEvidence(journal) {
|
|
518
753
|
if (journal.version < JOURNAL_VERSION) {
|
|
@@ -531,8 +766,9 @@ async function retireRemovalIntent(directory, journal, entries, options) {
|
|
|
531
766
|
for (const entry of entries) {
|
|
532
767
|
entry.removalPending = false;
|
|
533
768
|
entry.replacementStarted = true;
|
|
769
|
+
delete entry.scopedRemoval;
|
|
534
770
|
}
|
|
535
|
-
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes:
|
|
771
|
+
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
|
|
536
772
|
options.validateMutation?.();
|
|
537
773
|
options.signal?.throwIfAborted();
|
|
538
774
|
}
|
|
@@ -546,212 +782,20 @@ async function retireRestorationIntent(directory, journal, entry, options) {
|
|
|
546
782
|
}
|
|
547
783
|
await retireRemovalIntent(directory, journal, [entry], options);
|
|
548
784
|
}
|
|
549
|
-
function
|
|
550
|
-
|
|
551
|
-
return path.join(path.dirname(entry.target), `.pi-sync.json.${token}.${entry.kind === "file" ? "restore" : "restore-tree"}`);
|
|
552
|
-
}
|
|
553
|
-
async function prepareRecoveryStage(directory, journal, entry, options) {
|
|
554
|
-
const temporary = recoveryStagePath(directory, entry);
|
|
555
|
-
if (!entry.recoveryStaged) {
|
|
556
|
-
try {
|
|
557
|
-
await fs.lstat(temporary);
|
|
558
|
-
throw new Error("Unowned recovery staging path; preserve evidence for review.");
|
|
559
|
-
}
|
|
560
|
-
catch (error) {
|
|
561
|
-
if (error.code !== "ENOENT")
|
|
562
|
-
throw error;
|
|
563
|
-
}
|
|
564
|
-
options.validateMutation?.();
|
|
565
|
-
options.signal?.throwIfAborted();
|
|
566
|
-
entry.recoveryStaged = true;
|
|
567
|
-
await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
|
|
568
|
-
options.validateMutation?.();
|
|
569
|
-
options.signal?.throwIfAborted();
|
|
570
|
-
}
|
|
571
|
-
return temporary;
|
|
785
|
+
function persistJournal(directory, journal) {
|
|
786
|
+
return writeJson(path.join(directory, "journal.json"), journal, { maxBytes: MAX_TRANSACTION_JOURNAL_BYTES });
|
|
572
787
|
}
|
|
573
|
-
async function
|
|
788
|
+
async function legacyBeforeImage(directory, entry) {
|
|
574
789
|
if (entry.kind === "missing")
|
|
575
790
|
return "missing";
|
|
791
|
+
const backup = path.join(directory, "before", entry.backupName);
|
|
576
792
|
if (entry.kind === "symlink")
|
|
577
793
|
return `symlink:${entry.linkTarget}`;
|
|
578
|
-
const value = await
|
|
794
|
+
const value = await legacyImage(backup);
|
|
579
795
|
if (value === "missing")
|
|
580
796
|
throw new Error("Transaction backup is missing; preserve evidence for review.");
|
|
581
797
|
return value;
|
|
582
798
|
}
|
|
583
|
-
async function image(target, durable = false) {
|
|
584
|
-
let stat;
|
|
585
|
-
try {
|
|
586
|
-
stat = await fs.lstat(target);
|
|
587
|
-
}
|
|
588
|
-
catch (error) {
|
|
589
|
-
const code = error.code;
|
|
590
|
-
if (code === "ENOENT" || code === "ENOTDIR")
|
|
591
|
-
return "missing";
|
|
592
|
-
throw error;
|
|
593
|
-
}
|
|
594
|
-
if (stat.isSymbolicLink())
|
|
595
|
-
return `symlink:${await fs.readlink(target)}`;
|
|
596
|
-
if (stat.isFile()) {
|
|
597
|
-
const content = await fs.readFile(target);
|
|
598
|
-
if (durable) {
|
|
599
|
-
// Keep POSIX read-only backup permissions; Windows flushing requires write access.
|
|
600
|
-
const handle = await fs.open(target, process.platform === "win32" ? "r+" : "r");
|
|
601
|
-
try {
|
|
602
|
-
await handle.sync();
|
|
603
|
-
}
|
|
604
|
-
finally {
|
|
605
|
-
await handle.close();
|
|
606
|
-
}
|
|
607
|
-
}
|
|
608
|
-
return fileImage(content);
|
|
609
|
-
}
|
|
610
|
-
if (!stat.isDirectory())
|
|
611
|
-
throw new Error("Unsupported transaction image.");
|
|
612
|
-
const entries = [];
|
|
613
|
-
for (const name of (await fs.readdir(target)).sort())
|
|
614
|
-
entries.push([name, await image(path.join(target, name), durable)]);
|
|
615
|
-
if (durable)
|
|
616
|
-
await syncDirectory(target);
|
|
617
|
-
return `directory:${createHash("sha256").update(JSON.stringify(entries)).digest("hex")}`;
|
|
618
|
-
}
|
|
619
|
-
async function ownedPostTree(target, files, requireComplete) {
|
|
620
|
-
if (!files.length)
|
|
621
|
-
return false;
|
|
622
|
-
const expected = new Map(files.map((file) => [mergePathIdentity(file.relative), file.image]));
|
|
623
|
-
const prefixes = new Set();
|
|
624
|
-
for (const relative of expected.keys()) {
|
|
625
|
-
for (let parent = path.dirname(relative); parent !== "." && parent !== path.dirname(parent); parent = path.dirname(parent))
|
|
626
|
-
prefixes.add(parent);
|
|
627
|
-
}
|
|
628
|
-
const seen = new Set();
|
|
629
|
-
async function visit(directory) {
|
|
630
|
-
let stat;
|
|
631
|
-
try {
|
|
632
|
-
stat = await fs.lstat(directory);
|
|
633
|
-
}
|
|
634
|
-
catch {
|
|
635
|
-
return false;
|
|
636
|
-
}
|
|
637
|
-
if (!stat.isDirectory() || stat.isSymbolicLink())
|
|
638
|
-
return false;
|
|
639
|
-
for (const name of await fs.readdir(directory)) {
|
|
640
|
-
const child = path.join(directory, name);
|
|
641
|
-
const relative = mergePathIdentity(path.relative(target, child));
|
|
642
|
-
const stat = await fs.lstat(child);
|
|
643
|
-
if (stat.isDirectory() && !stat.isSymbolicLink()) {
|
|
644
|
-
if (!prefixes.has(relative) || !(await visit(child)))
|
|
645
|
-
return false;
|
|
646
|
-
}
|
|
647
|
-
else {
|
|
648
|
-
if (expected.get(relative) !== (await image(child)))
|
|
649
|
-
return false;
|
|
650
|
-
seen.add(relative);
|
|
651
|
-
}
|
|
652
|
-
}
|
|
653
|
-
return true;
|
|
654
|
-
}
|
|
655
|
-
return (await visit(target)) && (!requireComplete || [...expected.keys()].every((key) => seen.has(key)));
|
|
656
|
-
}
|
|
657
|
-
function validateJournal(directory, journal, sessionDir) {
|
|
658
|
-
if (![1, 2, 3, 4, 5, 6, 7].includes(journal.version) ||
|
|
659
|
-
!Array.isArray(journal.entries) ||
|
|
660
|
-
journal.entries.length > 16_384)
|
|
661
|
-
throw new Error("Unsupported pi-sync transaction journal; preserve evidence for review.");
|
|
662
|
-
if (journal.exclude !== undefined && !Array.isArray(journal.exclude))
|
|
663
|
-
throw new Error("Invalid transaction exclude policy; preserve evidence.");
|
|
664
|
-
normalizeSyncExclude(journal.exclude);
|
|
665
|
-
if (journal.completed !== undefined && (![6, 7].includes(journal.version) || journal.completed !== true))
|
|
666
|
-
throw new Error("Invalid transaction completion evidence.");
|
|
667
|
-
const root = path.resolve(agentDir());
|
|
668
|
-
if (typeof journal.root !== "string" || path.resolve(journal.root) !== root)
|
|
669
|
-
throw new Error("Transaction root no longer matches the Pi agent directory.");
|
|
670
|
-
if (journal.sessionRootTransition !== undefined) {
|
|
671
|
-
if (journal.version !== 7 || typeof journal.sessionRoot !== "string")
|
|
672
|
-
throw new Error("Invalid session root-transition version.");
|
|
673
|
-
validateSessionRootTransition(journal.sessionRootTransition);
|
|
674
|
-
}
|
|
675
|
-
else if (journal.version === 7)
|
|
676
|
-
throw new Error("Missing session root-transition evidence.");
|
|
677
|
-
const trustedSessionRoot = sessionDir
|
|
678
|
-
? path.resolve(sessionStorageRoot(root, sessionDir))
|
|
679
|
-
: path.join(root, "sessions");
|
|
680
|
-
if (journal.sessionRoot !== undefined &&
|
|
681
|
-
(typeof journal.sessionRoot !== "string" ||
|
|
682
|
-
!path.isAbsolute(journal.sessionRoot) ||
|
|
683
|
-
path.resolve(journal.sessionRoot) !== journal.sessionRoot ||
|
|
684
|
-
(!journal.completed && transactionHasSessionTargets(journal) && journal.sessionRoot !== trustedSessionRoot)))
|
|
685
|
-
throw new Error("Transaction session root is not owned by this context; preserve evidence for review.");
|
|
686
|
-
for (const entry of journal.entries) {
|
|
687
|
-
if (!entry ||
|
|
688
|
-
typeof entry.target !== "string" ||
|
|
689
|
-
!path.isAbsolute(entry.target) ||
|
|
690
|
-
path.resolve(entry.target) !== entry.target ||
|
|
691
|
-
typeof entry.backupName !== "string" ||
|
|
692
|
-
!/^\d+$/u.test(entry.backupName) ||
|
|
693
|
-
!["missing", "file", "directory", "symlink"].includes(entry.kind))
|
|
694
|
-
throw new Error("Invalid pi-sync transaction entry.");
|
|
695
|
-
assertWithinRoot(directory, path.join(directory, "before", entry.backupName));
|
|
696
|
-
assertAllowedTarget(root, journal.sessionRoot, entry.target);
|
|
697
|
-
if (entry.afterTarget !== undefined &&
|
|
698
|
-
(![5, 6, 7].includes(journal.version) ||
|
|
699
|
-
typeof entry.afterTarget !== "string" ||
|
|
700
|
-
!isCaseReplacement(root, entry.target, entry.afterTarget) ||
|
|
701
|
-
path.resolve(entry.afterTarget) !== entry.afterTarget ||
|
|
702
|
-
entry.kind !== "file"))
|
|
703
|
-
throw new Error("Invalid transaction case replacement evidence.");
|
|
704
|
-
if (entry.afterTarget)
|
|
705
|
-
assertAllowedTarget(root, journal.sessionRoot, entry.afterTarget);
|
|
706
|
-
if (journal.version >= 2 &&
|
|
707
|
-
((entry.beforeImage === undefined ? !journal.completed : typeof entry.beforeImage !== "string") ||
|
|
708
|
-
(entry.afterImage === undefined ? !journal.completed : typeof entry.afterImage !== "string") ||
|
|
709
|
-
(entry.postFiles === undefined ? !journal.completed : !Array.isArray(entry.postFiles))))
|
|
710
|
-
throw new Error("Invalid transaction postimage evidence.");
|
|
711
|
-
if (entry.recoveryStaged !== undefined && typeof entry.recoveryStaged !== "boolean")
|
|
712
|
-
throw new Error("Invalid recovery staging evidence.");
|
|
713
|
-
if (entry.removalPending !== undefined && (journal.version < 3 || typeof entry.removalPending !== "boolean"))
|
|
714
|
-
throw new Error("Invalid transaction removal evidence.");
|
|
715
|
-
if (entry.replacementStarted !== undefined &&
|
|
716
|
-
(journal.version < 4 || typeof entry.replacementStarted !== "boolean"))
|
|
717
|
-
throw new Error("Invalid transaction replacement evidence.");
|
|
718
|
-
if (entry.removalPending && entry.replacementStarted)
|
|
719
|
-
throw new Error("Conflicting transaction replacement evidence.");
|
|
720
|
-
for (const file of entry.postFiles ?? []) {
|
|
721
|
-
if (typeof file.relative !== "string" ||
|
|
722
|
-
typeof file.image !== "string" ||
|
|
723
|
-
!isStrictlyInside(entry.target, path.resolve(entry.target, file.relative)))
|
|
724
|
-
throw new Error("Invalid transaction subtree evidence.");
|
|
725
|
-
}
|
|
726
|
-
}
|
|
727
|
-
}
|
|
728
|
-
function transactionHasSessionTargets(journal) {
|
|
729
|
-
const root = path.resolve(agentDir());
|
|
730
|
-
return (Array.isArray(journal.entries) &&
|
|
731
|
-
journal.entries.some((entry) => typeof entry?.target === "string" &&
|
|
732
|
-
(!isPathInside(root, entry.target) ||
|
|
733
|
-
isPathInside(path.join(root, "sessions"), entry.target) ||
|
|
734
|
-
(typeof journal.sessionRoot === "string" && isPathInside(journal.sessionRoot, entry.target)))));
|
|
735
|
-
}
|
|
736
|
-
function isStrictlyInside(root, target) {
|
|
737
|
-
return path.relative(path.resolve(root), path.resolve(target)) !== "" && isPathInside(root, target);
|
|
738
|
-
}
|
|
739
|
-
function assertAllowedTarget(root, sessionRoot, target) {
|
|
740
|
-
const resolved = path.resolve(target);
|
|
741
|
-
if (isStrictlyInside(root, resolved)) {
|
|
742
|
-
if (isDeniedPath(path.relative(root, resolved)))
|
|
743
|
-
throw new Error("Transaction targets denied private storage.");
|
|
744
|
-
assertWithinRoot(root, resolved);
|
|
745
|
-
return;
|
|
746
|
-
}
|
|
747
|
-
if (sessionRoot && isStrictlyInside(sessionRoot, resolved)) {
|
|
748
|
-
if (isDeniedPath(`sessions/${path.relative(sessionRoot, resolved)}`))
|
|
749
|
-
throw new Error("Transaction targets denied session storage.");
|
|
750
|
-
assertWithinRoot(sessionRoot, resolved);
|
|
751
|
-
return;
|
|
752
|
-
}
|
|
753
|
-
throw new Error("Transaction target is outside configured roots.");
|
|
754
|
-
}
|
|
755
799
|
async function assertSafeParents(root, sessionRoot, target) {
|
|
756
800
|
assertAllowedTarget(root, sessionRoot, target);
|
|
757
801
|
const boundary = isPathInside(root, target) ? root : sessionRoot;
|
|
@@ -773,8 +817,12 @@ async function assertSafeParents(root, sessionRoot, target) {
|
|
|
773
817
|
async function completeTransaction(directory, journal) {
|
|
774
818
|
// Publish completion before deleting any backup. A surviving journal after power loss
|
|
775
819
|
// may only retry cleanup, never roll back already accepted files.
|
|
776
|
-
await writeJson(path.join(directory, "journal.json"), {
|
|
777
|
-
|
|
820
|
+
await writeJson(path.join(directory, "journal.json"), {
|
|
821
|
+
...journal,
|
|
822
|
+
version: isScopedJournal(journal) ? journal.version : journal.sessionRootTransition ? 7 : 6,
|
|
823
|
+
completed: true,
|
|
824
|
+
}, {
|
|
825
|
+
maxBytes: MAX_TRANSACTION_JOURNAL_BYTES,
|
|
778
826
|
});
|
|
779
827
|
await removeTransaction(directory);
|
|
780
828
|
}
|