@narumitw/pi-sync-daemon 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (265) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/LICENSE +21 -0
  3. package/README.md +89 -2
  4. package/dist/cli.d.ts +2 -0
  5. package/dist/cli.js +128 -0
  6. package/dist/client.d.ts +55 -0
  7. package/dist/client.js +484 -0
  8. package/dist/consent.d.ts +24 -0
  9. package/dist/consent.js +205 -0
  10. package/dist/document.d.ts +10 -0
  11. package/dist/document.js +6 -0
  12. package/dist/endpoint.d.ts +8 -0
  13. package/dist/endpoint.js +91 -0
  14. package/dist/engine/backends/backend-factory.d.ts +6 -0
  15. package/dist/engine/backends/backend-factory.js +16 -0
  16. package/dist/engine/backends/backend-identity.d.ts +3 -0
  17. package/dist/engine/backends/backend-identity.js +38 -0
  18. package/dist/engine/backends/backend-types.d.ts +70 -0
  19. package/dist/engine/backends/backend-types.js +1 -0
  20. package/dist/engine/backends/git/git-backend.d.ts +55 -0
  21. package/dist/engine/backends/git/git-backend.js +700 -0
  22. package/dist/engine/backends/git/git-config.d.ts +5 -0
  23. package/dist/engine/backends/git/git-config.js +118 -0
  24. package/dist/engine/backends/git/git-runner.d.ts +25 -0
  25. package/dist/engine/backends/git/git-runner.js +232 -0
  26. package/dist/engine/backends/git/git-storage.d.ts +39 -0
  27. package/dist/engine/backends/git/git-storage.js +226 -0
  28. package/dist/engine/backends/s3/s3-backend.d.ts +32 -0
  29. package/dist/engine/backends/s3/s3-backend.js +436 -0
  30. package/dist/engine/backends/s3/s3-client.d.ts +36 -0
  31. package/dist/engine/backends/s3/s3-client.js +352 -0
  32. package/dist/engine/backends/s3/s3-conditions.d.ts +4 -0
  33. package/dist/engine/backends/s3/s3-conditions.js +66 -0
  34. package/dist/engine/backends/snapshot-pointer.d.ts +6 -0
  35. package/dist/engine/backends/snapshot-pointer.js +22 -0
  36. package/dist/engine/backends/sync-backend.d.ts +71 -0
  37. package/dist/engine/backends/sync-backend.js +23 -0
  38. package/dist/engine/backends/webdav/webdav-backend.d.ts +34 -0
  39. package/dist/engine/backends/webdav/webdav-backend.js +534 -0
  40. package/dist/engine/backends/webdav/webdav-client.d.ts +36 -0
  41. package/dist/engine/backends/webdav/webdav-client.js +326 -0
  42. package/dist/engine/backends/webdav/webdav-config.d.ts +5 -0
  43. package/dist/engine/backends/webdav/webdav-config.js +73 -0
  44. package/dist/engine/commands/command-types.d.ts +31 -0
  45. package/dist/engine/commands/command-types.js +1 -0
  46. package/dist/engine/host.d.ts +70 -0
  47. package/dist/engine/host.js +16 -0
  48. package/dist/engine/paths.d.ts +9 -0
  49. package/dist/engine/paths.js +71 -0
  50. package/dist/engine/settings/config-errors.d.ts +1 -0
  51. package/dist/engine/settings/config-errors.js +4 -0
  52. package/dist/engine/settings/config-file.d.ts +33 -0
  53. package/dist/engine/settings/config-file.js +630 -0
  54. package/dist/engine/settings/config.d.ts +24 -0
  55. package/dist/engine/settings/config.js +200 -0
  56. package/dist/engine/settings/settings-management.d.ts +24 -0
  57. package/dist/engine/settings/settings-management.js +191 -0
  58. package/dist/engine/settings/settings-store.d.ts +8 -0
  59. package/dist/engine/settings/settings-store.js +41 -0
  60. package/dist/engine/settings/settings-types.d.ts +134 -0
  61. package/dist/engine/settings/settings-types.js +1 -0
  62. package/dist/engine/settings/settings-validation.d.ts +15 -0
  63. package/dist/engine/settings/settings-validation.js +356 -0
  64. package/dist/engine/snapshot/session-paths.d.ts +12 -0
  65. package/dist/engine/snapshot/session-paths.js +91 -0
  66. package/dist/engine/snapshot/snapshot-apply.d.ts +22 -0
  67. package/dist/engine/snapshot/snapshot-apply.js +262 -0
  68. package/dist/engine/snapshot/snapshot-case-replacement.d.ts +15 -0
  69. package/dist/engine/snapshot/snapshot-case-replacement.js +82 -0
  70. package/dist/engine/snapshot/snapshot-codec.d.ts +6 -0
  71. package/dist/engine/snapshot/snapshot-codec.js +53 -0
  72. package/dist/engine/snapshot/snapshot-exclude-safety.d.ts +7 -0
  73. package/dist/engine/snapshot/snapshot-exclude-safety.js +47 -0
  74. package/dist/engine/snapshot/snapshot-mutation-queues.d.ts +9 -0
  75. package/dist/engine/snapshot/snapshot-mutation-queues.js +133 -0
  76. package/dist/engine/snapshot/snapshot-paths.d.ts +1 -0
  77. package/dist/engine/snapshot/snapshot-paths.js +11 -0
  78. package/dist/engine/snapshot/snapshot-root-transition.d.ts +25 -0
  79. package/dist/engine/snapshot/snapshot-root-transition.js +122 -0
  80. package/dist/engine/snapshot/snapshot-transaction-directory.d.ts +2 -0
  81. package/dist/engine/snapshot/snapshot-transaction-directory.js +16 -0
  82. package/dist/engine/snapshot/snapshot-transaction-plan.d.ts +12 -0
  83. package/dist/engine/snapshot/snapshot-transaction-plan.js +68 -0
  84. package/dist/engine/snapshot/snapshot-transaction.d.ts +15 -0
  85. package/dist/engine/snapshot/snapshot-transaction.js +787 -0
  86. package/dist/engine/snapshot/snapshot-types.d.ts +48 -0
  87. package/dist/engine/snapshot/snapshot-types.js +1 -0
  88. package/dist/engine/snapshot/snapshot.d.ts +30 -0
  89. package/dist/engine/snapshot/snapshot.js +364 -0
  90. package/dist/engine/state/json-file.d.ts +6 -0
  91. package/dist/engine/state/json-file.js +49 -0
  92. package/dist/engine/state/lock-policy.d.ts +2 -0
  93. package/dist/engine/state/lock-policy.js +2 -0
  94. package/dist/engine/state/lock.d.ts +20 -0
  95. package/dist/engine/state/lock.js +259 -0
  96. package/dist/engine/state/lockfile-fs.d.ts +13 -0
  97. package/dist/engine/state/lockfile-fs.js +13 -0
  98. package/dist/engine/state/merge-baseline-store.d.ts +11 -0
  99. package/dist/engine/state/merge-baseline-store.js +187 -0
  100. package/dist/engine/state/mutation-directory-sync.d.ts +5 -0
  101. package/dist/engine/state/mutation-directory-sync.js +34 -0
  102. package/dist/engine/state/operation-availability.d.ts +49 -0
  103. package/dist/engine/state/operation-availability.js +40 -0
  104. package/dist/engine/state/state-directory.d.ts +14 -0
  105. package/dist/engine/state/state-directory.js +225 -0
  106. package/dist/engine/state/state-types.d.ts +27 -0
  107. package/dist/engine/state/state-types.js +1 -0
  108. package/dist/engine/state/sync-state-store.d.ts +11 -0
  109. package/dist/engine/state/sync-state-store.js +54 -0
  110. package/dist/engine/sync/agent-candidate.d.ts +44 -0
  111. package/dist/engine/sync/agent-candidate.js +207 -0
  112. package/dist/engine/sync/agent-plan.d.ts +8 -0
  113. package/dist/engine/sync/agent-plan.js +84 -0
  114. package/dist/engine/sync/agent-policy.d.ts +9 -0
  115. package/dist/engine/sync/agent-policy.js +10 -0
  116. package/dist/engine/sync/agent-refusal-retry.d.ts +4 -0
  117. package/dist/engine/sync/agent-refusal-retry.js +39 -0
  118. package/dist/engine/sync/agent-request.d.ts +14 -0
  119. package/dist/engine/sync/agent-request.js +13 -0
  120. package/dist/engine/sync/agent-runner.d.ts +6 -0
  121. package/dist/engine/sync/agent-runner.js +183 -0
  122. package/dist/engine/sync/agent-store.d.ts +7 -0
  123. package/dist/engine/sync/agent-store.js +177 -0
  124. package/dist/engine/sync/agent-sync.d.ts +4 -0
  125. package/dist/engine/sync/agent-sync.js +132 -0
  126. package/dist/engine/sync/apply-review.d.ts +8 -0
  127. package/dist/engine/sync/apply-review.js +51 -0
  128. package/dist/engine/sync/conflict-artifact-ownership.d.ts +4 -0
  129. package/dist/engine/sync/conflict-artifact-ownership.js +53 -0
  130. package/dist/engine/sync/conflict-artifacts.d.ts +32 -0
  131. package/dist/engine/sync/conflict-artifacts.js +158 -0
  132. package/dist/engine/sync/conflict-groups.d.ts +9 -0
  133. package/dist/engine/sync/conflict-groups.js +76 -0
  134. package/dist/engine/sync/conflict-preview.d.ts +4 -0
  135. package/dist/engine/sync/conflict-preview.js +53 -0
  136. package/dist/engine/sync/conflict-resolution.d.ts +13 -0
  137. package/dist/engine/sync/conflict-resolution.js +53 -0
  138. package/dist/engine/sync/conflict-retention.d.ts +5 -0
  139. package/dist/engine/sync/conflict-retention.js +61 -0
  140. package/dist/engine/sync/conflict-review.d.ts +4 -0
  141. package/dist/engine/sync/conflict-review.js +73 -0
  142. package/dist/engine/sync/content-conflicts.d.ts +10 -0
  143. package/dist/engine/sync/content-conflicts.js +70 -0
  144. package/dist/engine/sync/continuous-errors.d.ts +14 -0
  145. package/dist/engine/sync/continuous-errors.js +66 -0
  146. package/dist/engine/sync/continuous-lease.d.ts +9 -0
  147. package/dist/engine/sync/continuous-lease.js +206 -0
  148. package/dist/engine/sync/continuous-record.d.ts +31 -0
  149. package/dist/engine/sync/continuous-record.js +199 -0
  150. package/dist/engine/sync/continuous-storage.d.ts +14 -0
  151. package/dist/engine/sync/continuous-storage.js +59 -0
  152. package/dist/engine/sync/continuous-sync.d.ts +15 -0
  153. package/dist/engine/sync/continuous-sync.js +496 -0
  154. package/dist/engine/sync/continuous-watch.d.ts +3 -0
  155. package/dist/engine/sync/continuous-watch.js +65 -0
  156. package/dist/engine/sync/exclude-policy.d.ts +5 -0
  157. package/dist/engine/sync/exclude-policy.js +79 -0
  158. package/dist/engine/sync/field-migration.d.ts +5 -0
  159. package/dist/engine/sync/field-migration.js +20 -0
  160. package/dist/engine/sync/file-merge-planner.d.ts +36 -0
  161. package/dist/engine/sync/file-merge-planner.js +123 -0
  162. package/dist/engine/sync/initialization.d.ts +12 -0
  163. package/dist/engine/sync/initialization.js +75 -0
  164. package/dist/engine/sync/json-document.d.ts +29 -0
  165. package/dist/engine/sync/json-document.js +172 -0
  166. package/dist/engine/sync/local-field-policy.d.ts +2 -0
  167. package/dist/engine/sync/local-field-policy.js +26 -0
  168. package/dist/engine/sync/local-fields.d.ts +9 -0
  169. package/dist/engine/sync/local-fields.js +116 -0
  170. package/dist/engine/sync/merge-apply.d.ts +5 -0
  171. package/dist/engine/sync/merge-apply.js +386 -0
  172. package/dist/engine/sync/merge-journal.d.ts +31 -0
  173. package/dist/engine/sync/merge-journal.js +179 -0
  174. package/dist/engine/sync/merge-transfer-error.d.ts +3 -0
  175. package/dist/engine/sync/merge-transfer-error.js +64 -0
  176. package/dist/engine/sync/merged-sync.d.ts +6 -0
  177. package/dist/engine/sync/merged-sync.js +618 -0
  178. package/dist/engine/sync/mutation-owner.d.ts +2 -0
  179. package/dist/engine/sync/mutation-owner.js +18 -0
  180. package/dist/engine/sync/package-merge.d.ts +3 -0
  181. package/dist/engine/sync/package-merge.js +82 -0
  182. package/dist/engine/sync/partial-progress.d.ts +15 -0
  183. package/dist/engine/sync/partial-progress.js +39 -0
  184. package/dist/engine/sync/remote-snapshot.d.ts +28 -0
  185. package/dist/engine/sync/remote-snapshot.js +62 -0
  186. package/dist/engine/sync/resolver-stream.d.ts +4 -0
  187. package/dist/engine/sync/resolver-stream.js +34 -0
  188. package/dist/engine/sync/session-merge.d.ts +3 -0
  189. package/dist/engine/sync/session-merge.js +178 -0
  190. package/dist/engine/sync/session-push.d.ts +5 -0
  191. package/dist/engine/sync/session-push.js +32 -0
  192. package/dist/engine/sync/settings-conflicts.d.ts +8 -0
  193. package/dist/engine/sync/settings-conflicts.js +56 -0
  194. package/dist/engine/sync/settings-merge.d.ts +13 -0
  195. package/dist/engine/sync/settings-merge.js +93 -0
  196. package/dist/engine/sync/signals.d.ts +2 -0
  197. package/dist/engine/sync/signals.js +8 -0
  198. package/dist/engine/sync/startup-timings.d.ts +11 -0
  199. package/dist/engine/sync/startup-timings.js +44 -0
  200. package/dist/engine/sync/sync-decision.d.ts +35 -0
  201. package/dist/engine/sync/sync-decision.js +66 -0
  202. package/dist/engine/sync/sync-error-guidance.d.ts +2 -0
  203. package/dist/engine/sync/sync-error-guidance.js +55 -0
  204. package/dist/engine/sync/sync-errors.d.ts +9 -0
  205. package/dist/engine/sync/sync-errors.js +18 -0
  206. package/dist/engine/sync/sync-inspection.d.ts +26 -0
  207. package/dist/engine/sync/sync-inspection.js +40 -0
  208. package/dist/engine/sync/sync-loaders.d.ts +7 -0
  209. package/dist/engine/sync/sync-loaders.js +8 -0
  210. package/dist/engine/sync/sync-local.d.ts +5 -0
  211. package/dist/engine/sync/sync-local.js +40 -0
  212. package/dist/engine/sync/sync-mutations.d.ts +30 -0
  213. package/dist/engine/sync/sync-mutations.js +589 -0
  214. package/dist/engine/sync/sync-operations.d.ts +2 -0
  215. package/dist/engine/sync/sync-operations.js +3 -0
  216. package/dist/engine/sync/sync-policy.d.ts +85 -0
  217. package/dist/engine/sync/sync-policy.js +356 -0
  218. package/dist/engine/sync/sync-queries.d.ts +7 -0
  219. package/dist/engine/sync/sync-queries.js +195 -0
  220. package/dist/engine/sync/sync-state.d.ts +31 -0
  221. package/dist/engine/sync/sync-state.js +92 -0
  222. package/dist/engine/sync/text-merge.d.ts +19 -0
  223. package/dist/engine/sync/text-merge.js +124 -0
  224. package/dist/engine/types.d.ts +5 -0
  225. package/dist/engine/types.js +2 -0
  226. package/dist/engine/ui/merge-review.d.ts +2 -0
  227. package/dist/engine/ui/merge-review.js +7 -0
  228. package/dist/engine/ui/merged-sync-summary.d.ts +25 -0
  229. package/dist/engine/ui/merged-sync-summary.js +86 -0
  230. package/dist/engine/ui/sync-format.d.ts +13 -0
  231. package/dist/engine/ui/sync-format.js +150 -0
  232. package/dist/engine/ui/sync-status.d.ts +9 -0
  233. package/dist/engine/ui/sync-status.js +30 -0
  234. package/dist/engine/ui/terminal-text.d.ts +3 -0
  235. package/dist/engine/ui/terminal-text.js +9 -0
  236. package/dist/engine/ui/transfer-changes.d.ts +12 -0
  237. package/dist/engine/ui/transfer-changes.js +24 -0
  238. package/dist/engine/ui/transfer-review.d.ts +3 -0
  239. package/dist/engine/ui/transfer-review.js +19 -0
  240. package/dist/engine-service.d.ts +11 -0
  241. package/dist/engine-service.js +315 -0
  242. package/dist/identity.d.ts +20 -0
  243. package/dist/identity.js +133 -0
  244. package/dist/index.d.ts +8 -0
  245. package/dist/index.js +4 -0
  246. package/dist/lifecycle-log.d.ts +7 -0
  247. package/dist/lifecycle-log.js +53 -0
  248. package/dist/lifecycle.d.ts +2 -0
  249. package/dist/lifecycle.js +21 -0
  250. package/dist/model-signature.d.ts +2 -0
  251. package/dist/model-signature.js +7 -0
  252. package/dist/monitor.d.ts +11 -0
  253. package/dist/monitor.js +245 -0
  254. package/dist/participant-admission.d.ts +5 -0
  255. package/dist/participant-admission.js +30 -0
  256. package/dist/protocol.d.ts +97 -0
  257. package/dist/protocol.js +90 -0
  258. package/dist/resolver-host.d.ts +11 -0
  259. package/dist/resolver-host.js +78 -0
  260. package/dist/server.d.ts +18 -0
  261. package/dist/server.js +724 -0
  262. package/dist/service-host.d.ts +7 -0
  263. package/dist/service-host.js +174 -0
  264. package/docs/architecture.md +133 -0
  265. package/package.json +54 -4
@@ -0,0 +1,787 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
5
+ import { syncDirectory, writeJson } from "../state/json-file.js";
6
+ import { withLock } from "../state/lock.js";
7
+ import { syncMutationParents } from "../state/mutation-directory-sync.js";
8
+ import { stateDir } from "../state/state-directory.js";
9
+ import { normalizeSyncExclude, sameSyncExclude } from "../sync/exclude-policy.js";
10
+ import { mergePathIdentity } from "../sync/file-merge-planner.js";
11
+ import { agentDir, configuredSessionDir } from "./session-paths.js";
12
+ import { caseReplacementSpelling, coalesceCaseReplacements, isCaseReplacement } from "./snapshot-case-replacement.js";
13
+ import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
14
+ import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
15
+ import { sessionStorageRoot } from "./snapshot-paths.js";
16
+ import { prepareSessionRootTransition, resolveTransitionSessionRoot, validateSessionRootTransition, } from "./snapshot-root-transition.js";
17
+ import { pendingTransactionEntries, transactionRoot } from "./snapshot-transaction-directory.js";
18
+ import { fileImage, indexTransactionPlan } from "./snapshot-transaction-plan.js";
19
+ const JOURNAL_VERSION = 4;
20
+ export async function applySnapshotTransaction(plan, options = {}) {
21
+ options.validateMutation?.();
22
+ await recoverPendingSnapshotTransactions(options);
23
+ const coalesced = await coalesceCaseReplacements(path.resolve(agentDir()), plan);
24
+ options.validateMutation?.();
25
+ options.signal?.throwIfAborted();
26
+ const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
27
+ if (targets.length > 16_384)
28
+ throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
29
+ return withTargetQueues(targets, options, async (heldKeys) => {
30
+ await assertUnexcludedTargets(agentDir(), targets, options);
31
+ options.signal?.throwIfAborted();
32
+ if (targets.some((target) => options.protectedTargets?.some((protectedTarget) => mergePathIdentity(target) === mergePathIdentity(protectedTarget) ||
33
+ isPathInside(mergePathIdentity(target), mergePathIdentity(protectedTarget)))))
34
+ throw new Error("Snapshot transaction targets the current session; review is required.");
35
+ for (const [before, after] of coalesced.replacements) {
36
+ if ((await caseReplacementSpelling(before, after)) !== before)
37
+ throw new Error("Case replacement changed before preparation; review is required.");
38
+ options.validateMutation?.();
39
+ options.signal?.throwIfAborted();
40
+ }
41
+ const originalTargets = new Map([...coalesced.replacements].map(([before, after]) => [after, before]));
42
+ const expectedPreimages = new Map([...(options.expectedPreimages ?? [])].map(([target, expected]) => [
43
+ originalTargets.get(target) ?? target,
44
+ expected,
45
+ ]));
46
+ // A case-sensitive spelling replacement has two targets, unlike a coalesced physical alias.
47
+ // Bind both the source bytes and destination absence/bytes before capturing their backups.
48
+ for (const [target, expected] of options.expectedPreimages ?? []) {
49
+ if (originalTargets.has(target))
50
+ continue;
51
+ const variants = coalesced.plan.deletes.filter((candidate) => candidate !== target &&
52
+ path.dirname(candidate) === path.dirname(target) &&
53
+ mergePathIdentity(candidate) === mergePathIdentity(target));
54
+ if (variants.length > 1)
55
+ throw new Error("Ambiguous reviewed file preimage spellings; review required.");
56
+ const original = variants[0];
57
+ if (!original)
58
+ continue;
59
+ const destination = await image(target);
60
+ options.validateMutation?.();
61
+ options.signal?.throwIfAborted();
62
+ if (destination !== "missing" && destination !== expected)
63
+ throw new Error("Reviewed destination preimage changed before apply.");
64
+ expectedPreimages.set(original, expected);
65
+ expectedPreimages.set(target, destination);
66
+ }
67
+ for (const [target, expected] of expectedPreimages) {
68
+ const current = await image(target);
69
+ options.validateMutation?.();
70
+ options.signal?.throwIfAborted();
71
+ if (current !== expected)
72
+ throw new Error("Reviewed file preimage changed before apply; snapshot installation refused.");
73
+ }
74
+ const transaction = await prepareTransaction(coalesced.plan, targets, { ...options, expectedPreimages }, coalesced.replacements);
75
+ const entriesByTarget = new Map(transaction.journal.entries.flatMap((entry) => [
76
+ [entry.target, entry],
77
+ ...(entry.afterTarget ? [[entry.afterTarget, entry]] : []),
78
+ ]));
79
+ // A released additional key cannot authorize rollback, even for recognized raced bytes.
80
+ const changesQueueKey = transaction.journal.entries.some((entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)));
81
+ try {
82
+ for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
83
+ options.signal?.throwIfAborted();
84
+ const entry = entriesByTarget.get(target);
85
+ if (!entry)
86
+ throw new Error("Unowned transaction target.");
87
+ await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
88
+ await syncDirectory(path.dirname(target));
89
+ }
90
+ await withMissingTargetQueues(transaction.journal.entries
91
+ .filter((entry) => entry.removalPending)
92
+ .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]), heldKeys, options, async () => {
93
+ await retireRemovalIntent(transaction.directory, transaction.journal, transaction.journal.entries.filter((entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0)), options);
94
+ // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
95
+ const uninstalledWrites = new Set(transaction.deletedWrites);
96
+ for (const item of plan.writes) {
97
+ options.signal?.throwIfAborted();
98
+ const entry = entriesByTarget.get(item.target);
99
+ if (!entry)
100
+ throw new Error("Unowned transaction target.");
101
+ const deletedByThisCall = uninstalledWrites.delete(entry.target);
102
+ await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
103
+ options.validateMutation?.();
104
+ options.signal?.throwIfAborted();
105
+ await fs.mkdir(path.dirname(item.target), { recursive: true });
106
+ options.validateMutation?.();
107
+ options.signal?.throwIfAborted();
108
+ const temp = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
109
+ try {
110
+ let mode = 0o600;
111
+ try {
112
+ const stat = await fs.lstat(item.target);
113
+ if (stat.isFile())
114
+ mode = stat.mode & 0o777;
115
+ }
116
+ catch (error) {
117
+ if (error.code !== "ENOENT")
118
+ throw error;
119
+ }
120
+ const handle = await fs.open(temp, "wx", mode);
121
+ try {
122
+ await handle.writeFile(item.content);
123
+ await handle.sync();
124
+ }
125
+ finally {
126
+ await handle.close();
127
+ }
128
+ await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
129
+ options.signal?.throwIfAborted();
130
+ options.validateMutation?.();
131
+ await fs.rename(temp, item.target);
132
+ await syncDirectory(path.dirname(item.target));
133
+ }
134
+ finally {
135
+ await fs.rm(temp, { force: true });
136
+ }
137
+ }
138
+ options.validateMutation?.();
139
+ options.signal?.throwIfAborted();
140
+ await syncMutationParents(targets, [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])], options);
141
+ options.validateMutation?.();
142
+ options.signal?.throwIfAborted();
143
+ });
144
+ }
145
+ catch (error) {
146
+ // Aborted owners cannot roll back files after another session has replaced them.
147
+ if (options.signal?.aborted)
148
+ throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
149
+ // Additional queues have been released. Recovery must reserve missing keys afresh.
150
+ if (changesQueueKey)
151
+ throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
152
+ cause: error,
153
+ });
154
+ try {
155
+ await restoreTransaction(transaction.directory, transaction.journal, options, heldKeys);
156
+ }
157
+ catch (recoveryError) {
158
+ throw new AggregateError([error, recoveryError], "Snapshot apply failed and guarded recovery requires review. Transaction and backup retained; newer bytes were not restored over.");
159
+ }
160
+ throw error;
161
+ }
162
+ // Files are durably installed. Cleanup cannot roll back once it starts deleting evidence.
163
+ await completeTransaction(transaction.directory, transaction.journal);
164
+ });
165
+ }
166
+ export async function recoverSnapshotTransactionsOnStartup(options = {}) {
167
+ if (!(await pendingTransactionEntries()).some((entry) => entry.isDirectory()))
168
+ return;
169
+ // A pending settings.json may itself be the interrupted postimage. Read each journal
170
+ // before consulting that file, and only consult it when a session target needs it.
171
+ options.validateMutation?.();
172
+ options.signal?.throwIfAborted();
173
+ await withLock("recovery", () => recoverPendingSnapshotTransactions({ ...options, resolveConfiguredSessionDir: true }), {
174
+ reclaimStale: true,
175
+ });
176
+ }
177
+ export async function recoverPendingSnapshotTransactions(options = {}) {
178
+ for (const entry of (await pendingTransactionEntries()).sort((a, b) => a.name.localeCompare(b.name))) {
179
+ if (!entry.isDirectory())
180
+ continue;
181
+ const directory = path.join(transactionRoot(), entry.name);
182
+ let journal;
183
+ try {
184
+ const file = path.join(directory, "journal.json");
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) {
191
+ // Unknown evidence is not disposable, including interrupted preparation directories.
192
+ if (error.code === "ENOENT")
193
+ continue;
194
+ throw new Error("Cannot recover malformed pi-sync transaction; preserve private evidence for review.");
195
+ }
196
+ let sessionDir = options.sessionDir;
197
+ if (sessionDir === undefined &&
198
+ options.resolveConfiguredSessionDir &&
199
+ !journal.completed &&
200
+ transactionHasSessionTargets(journal)) {
201
+ sessionDir = await configuredSessionDir();
202
+ }
203
+ options.validateMutation?.();
204
+ options.signal?.throwIfAborted();
205
+ if (journal.sessionRootTransition && !journal.completed) {
206
+ // Validate every path before consulting backup evidence under the recorded root.
207
+ validateJournal(directory, journal, journal.sessionRoot);
208
+ sessionDir = await resolveTransitionSessionRoot(directory, journal.root, journal.sessionRoot, journal.sessionRootTransition, journal.entries, path.resolve(sessionStorageRoot(journal.root, sessionDir)), options);
209
+ options.validateMutation?.();
210
+ options.signal?.throwIfAborted();
211
+ }
212
+ 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
+ if (journal.completed) {
216
+ await removeTransaction(directory);
217
+ continue;
218
+ }
219
+ await withTargetQueues(journal.entries.map((entry) => entry.target).sort(), options, (heldKeys) => restoreTransaction(directory, journal, { ...options, sessionDir }, heldKeys));
220
+ }
221
+ }
222
+ async function prepareTransaction(plan, targets, options, replacements = new Map()) {
223
+ const { sessionDir } = options;
224
+ const root = path.resolve(agentDir());
225
+ const sessionRoot = sessionDir ? path.resolve(sessionStorageRoot(root, sessionDir)) : undefined;
226
+ const indexed = indexTransactionPlan(plan, targets);
227
+ const directory = path.join(transactionRoot(), randomUUID());
228
+ const backupDirectory = path.join(directory, "before");
229
+ await fs.mkdir(backupDirectory, { recursive: true, mode: 0o700 });
230
+ const entries = [];
231
+ for (const [index, target] of targets.entries()) {
232
+ options.signal?.throwIfAborted();
233
+ options.validateMutation?.();
234
+ assertAllowedTarget(root, sessionRoot, target);
235
+ await assertSafeParents(root, sessionRoot, target);
236
+ const entry = { target, backupName: `${index}`, kind: "missing" };
237
+ if (replacements.has(target))
238
+ entry.afterTarget = replacements.get(target);
239
+ const backup = path.join(backupDirectory, entry.backupName);
240
+ try {
241
+ const stat = await fs.lstat(target);
242
+ if (stat.isSymbolicLink()) {
243
+ entry.kind = "symlink";
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.");
267
+ }
268
+ catch (error) {
269
+ const code = error.code;
270
+ if (code !== "ENOENT" && code !== "ENOTDIR")
271
+ throw error;
272
+ }
273
+ entry.beforeImage =
274
+ entry.kind === "symlink"
275
+ ? `symlink:${entry.linkTarget}`
276
+ : entry.kind === "missing"
277
+ ? "missing"
278
+ : await image(backup, true);
279
+ options.validateMutation?.();
280
+ options.signal?.throwIfAborted();
281
+ const expected = options.expectedPreimages?.get(target);
282
+ if (expected !== undefined && entry.beforeImage !== expected)
283
+ throw new Error("Reviewed file preimage changed during backup; private preparation evidence retained.");
284
+ if (entry.afterTarget) {
285
+ if (entry.kind !== "file" || (await caseReplacementSpelling(target, entry.afterTarget)) !== target)
286
+ throw new Error("Case replacement preimage changed during backup; evidence retained for review.");
287
+ options.validateMutation?.();
288
+ options.signal?.throwIfAborted();
289
+ }
290
+ entry.afterImage = indexed.writeImages.get(target) ?? "missing";
291
+ entry.postFiles = indexed.postFiles.get(target) ?? [];
292
+ entries.push(entry);
293
+ }
294
+ // File fsync does not persist the name linking each backup into this directory.
295
+ await syncDirectory(backupDirectory);
296
+ const effectiveRoot = sessionRoot ?? path.join(root, "sessions");
297
+ const sessionRootTransition = await prepareSessionRootTransition(directory, root, effectiveRoot, entries, plan, options);
298
+ const journal = {
299
+ version: sessionRootTransition ? 7 : replacements.size ? 5 : JOURNAL_VERSION,
300
+ root,
301
+ ...(options.exclude === undefined ? {} : { exclude: normalizeSyncExclude(options.exclude) }),
302
+ sessionRoot: sessionRootTransition ? effectiveRoot : sessionRoot,
303
+ sessionRootTransition,
304
+ entries,
305
+ };
306
+ options.signal?.throwIfAborted();
307
+ options.validateMutation?.();
308
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
309
+ await syncDirectory(transactionRoot());
310
+ await syncDirectory(stateDir());
311
+ await syncDirectory(path.dirname(stateDir()));
312
+ return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
313
+ }
314
+ async function restoreTransaction(directory, journal, options, heldKeys) {
315
+ validateJournal(directory, journal, options.sessionDir);
316
+ const missingSpellings = [];
317
+ for (const entry of journal.entries) {
318
+ if (!entry.afterTarget)
319
+ continue;
320
+ options.validateMutation?.();
321
+ options.signal?.throwIfAborted();
322
+ const spelling = await caseReplacementSpelling(entry.target, entry.afterTarget);
323
+ options.validateMutation?.();
324
+ options.signal?.throwIfAborted();
325
+ if (spelling === undefined)
326
+ missingSpellings.push(entry.target, entry.afterTarget);
327
+ }
328
+ // Reserve an interrupted removal's other spelling before staging or image checks:
329
+ // recognizable bytes installed by a writer in that gap are not our postimage.
330
+ return withMissingTargetQueues(missingSpellings, heldKeys, options, (reservedKeys) => restoreQueuedTransaction(directory, journal, options, reservedKeys));
331
+ }
332
+ async function restoreQueuedTransaction(directory, journal, options, heldKeys) {
333
+ validateJournal(directory, journal, options.sessionDir);
334
+ options.validateMutation?.();
335
+ options.signal?.throwIfAborted();
336
+ for (const entry of journal.entries) {
337
+ if (options.protectedTargets?.some((target) => mergePathIdentity(target) === mergePathIdentity(entry.target) ||
338
+ isPathInside(mergePathIdentity(entry.target), mergePathIdentity(target))))
339
+ throw new Error("Pending transaction touches the current session; resume a different session before guarded recovery.");
340
+ await verifyTarget(directory, entry, journal);
341
+ }
342
+ // Recover copies left by a process crash even when the target is already restored.
343
+ for (const entry of journal.entries) {
344
+ if (!entry.recoveryStaged)
345
+ continue;
346
+ options.validateMutation?.();
347
+ options.signal?.throwIfAborted();
348
+ await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
349
+ options.validateMutation?.();
350
+ options.signal?.throwIfAborted();
351
+ await fs.rm(recoveryStagePath(directory, entry), { recursive: true, force: true });
352
+ options.validateMutation?.();
353
+ options.signal?.throwIfAborted();
354
+ }
355
+ // Verify the complete group before removing any path. Recheck each destructive boundary.
356
+ 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);
359
+ const spellingMatches = async () => !entry.afterTarget || (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.target;
360
+ if (current === before && (await spellingMatches()))
361
+ continue;
362
+ options.signal?.throwIfAborted();
363
+ options.validateMutation?.();
364
+ if (entry.kind === "file") {
365
+ const temporary = await prepareRecoveryStage(directory, journal, entry, options);
366
+ try {
367
+ await fs.mkdir(path.dirname(entry.target), { recursive: true });
368
+ await fs.copyFile(path.join(directory, "before", entry.backupName), temporary);
369
+ // Windows requires write access to flush an existing regular file.
370
+ const handle = await fs.open(temporary, process.platform === "win32" ? "r+" : "r");
371
+ try {
372
+ await handle.sync();
373
+ }
374
+ finally {
375
+ await handle.close();
376
+ }
377
+ const verified = await verifyTarget(directory, entry, journal);
378
+ options.validateMutation?.();
379
+ options.signal?.throwIfAborted();
380
+ if (verified === before && (await spellingMatches()))
381
+ continue;
382
+ const needsCaseQueue = entry.afterTarget !== undefined &&
383
+ (await caseReplacementSpelling(entry.target, entry.afterTarget)) === entry.afterTarget;
384
+ if (needsCaseQueue) {
385
+ // Keep the installed-spelling queue while reserving the now-missing original spelling.
386
+ await removeOwnedTarget(directory, entry, journal, options);
387
+ }
388
+ else if (verified.startsWith("directory:") &&
389
+ !(await removeOwnedTarget(directory, entry, journal, options, before)))
390
+ continue;
391
+ await withMissingTargetQueues(entry.afterTarget && (needsCaseQueue || verified === "missing")
392
+ ? [entry.target, entry.afterTarget]
393
+ : verified.startsWith("directory:")
394
+ ? [entry.target]
395
+ : [], heldKeys, options, async () => {
396
+ const atRename = await verifyTarget(directory, entry, journal);
397
+ options.validateMutation?.();
398
+ options.signal?.throwIfAborted();
399
+ if (atRename === before && (await spellingMatches()))
400
+ return;
401
+ await retireRestorationIntent(directory, journal, entry, options);
402
+ const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
403
+ options.validateMutation?.();
404
+ options.signal?.throwIfAborted();
405
+ if (atInstall === before && (await spellingMatches()))
406
+ return;
407
+ await fs.rename(temporary, entry.target);
408
+ await syncDirectory(path.dirname(entry.target));
409
+ });
410
+ }
411
+ finally {
412
+ await fs.rm(temporary, { force: true });
413
+ }
414
+ continue;
415
+ }
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
+ try {
422
+ await fs.mkdir(path.dirname(entry.target), { recursive: true });
423
+ await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
424
+ if (entry.kind === "directory") {
425
+ await fs.cp(path.join(directory, "before", entry.backupName), temporary, {
426
+ recursive: true,
427
+ dereference: false,
428
+ verbatimSymlinks: true,
429
+ preserveTimestamps: true,
430
+ filter: () => {
431
+ options.validateMutation?.();
432
+ options.signal?.throwIfAborted();
433
+ return true;
434
+ },
435
+ });
436
+ }
437
+ else if (entry.linkTarget !== undefined)
438
+ await fs.symlink(entry.linkTarget, temporary);
439
+ if ((await image(temporary, true)) !== before)
440
+ throw new Error("Staged recovery image differs from the backup; evidence retained.");
441
+ options.validateMutation?.();
442
+ options.signal?.throwIfAborted();
443
+ if (!(await removeOwnedTarget(directory, entry, journal, options, before)))
444
+ continue;
445
+ await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
446
+ const atRename = await verifyTarget(directory, entry, journal);
447
+ options.validateMutation?.();
448
+ options.signal?.throwIfAborted();
449
+ if (atRename === before)
450
+ return;
451
+ await retireRestorationIntent(directory, journal, entry, options);
452
+ const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
453
+ options.validateMutation?.();
454
+ options.signal?.throwIfAborted();
455
+ if (atInstall === before)
456
+ return;
457
+ await fs.rename(temporary, entry.target);
458
+ await syncDirectory(path.dirname(entry.target));
459
+ });
460
+ }
461
+ finally {
462
+ await fs.rm(temporary, { recursive: true, force: true });
463
+ }
464
+ }
465
+ await syncMutationParents(journal.entries.map((entry) => entry.target), [journal.root, ...(journal.sessionRoot ? [journal.sessionRoot] : [])], options);
466
+ options.validateMutation?.();
467
+ options.signal?.throwIfAborted();
468
+ await completeTransaction(directory, journal);
469
+ }
470
+ async function verifyTarget(directory, entry, journal, deletedByThisCall = false) {
471
+ await assertSafeParents(journal.root, journal.sessionRoot, entry.target);
472
+ // Hash the potentially large backup before observing the live target, not after it.
473
+ const before = await beforeImage(directory, entry);
474
+ if (journal.version >= 2 && before !== entry.beforeImage)
475
+ throw new Error("Transaction backup changed; preserve evidence for review.");
476
+ if (entry.afterTarget)
477
+ await caseReplacementSpelling(entry.target, entry.afterTarget);
478
+ const current = await image(entry.target);
479
+ if (current === before)
480
+ return current;
481
+ if (current === "missing") {
482
+ if (deletedByThisCall || (journal.version >= 4 && entry.removalPending && !entry.replacementStarted))
483
+ return current;
484
+ }
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
+ throw new Error("Transaction target has unrecognized or newer bytes; automatic rollback refused. Preserve the transaction and review its backup with Pi closed.");
490
+ }
491
+ async function removeOwnedTarget(directory, entry, journal, options, restoringBefore) {
492
+ await assertUnexcludedTargets(journal.root, [entry.target], options);
493
+ const current = await verifyTarget(directory, entry, journal);
494
+ options.validateMutation?.();
495
+ options.signal?.throwIfAborted();
496
+ if (restoringBefore !== undefined && current === restoringBefore)
497
+ return false;
498
+ // Persist intent before removal, including descendants affected by a recursive delete.
499
+ // Until replacement is armed, interrupted removal can recognize absence without accepting unknown bytes.
500
+ upgradeRemovalEvidence(journal);
501
+ for (const affected of journal.entries) {
502
+ if (affected.target === entry.target || isStrictlyInside(entry.target, affected.target)) {
503
+ affected.removalPending = true;
504
+ affected.replacementStarted = false;
505
+ }
506
+ }
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
+ }
517
+ function upgradeRemovalEvidence(journal) {
518
+ if (journal.version < JOURNAL_VERSION) {
519
+ // Old pending markers may already have survived a committed replacement.
520
+ for (const entry of journal.entries)
521
+ entry.removalPending = false;
522
+ journal.version = JOURNAL_VERSION;
523
+ }
524
+ }
525
+ async function retireRemovalIntent(directory, journal, entries, options) {
526
+ options.validateMutation?.();
527
+ options.signal?.throwIfAborted();
528
+ if (!entries.length)
529
+ return;
530
+ upgradeRemovalEvidence(journal);
531
+ for (const entry of entries) {
532
+ entry.removalPending = false;
533
+ entry.replacementStarted = true;
534
+ }
535
+ await writeJson(path.join(directory, "journal.json"), journal, { maxBytes: 32 * 1024 * 1024 });
536
+ options.validateMutation?.();
537
+ options.signal?.throwIfAborted();
538
+ }
539
+ async function retireRestorationIntent(directory, journal, entry, options) {
540
+ // Installing a complete parent preimage supersedes descendant replacement progress too.
541
+ for (const child of journal.entries) {
542
+ if (isStrictlyInside(entry.target, child.target)) {
543
+ child.removalPending = false;
544
+ child.replacementStarted = false;
545
+ }
546
+ }
547
+ await retireRemovalIntent(directory, journal, [entry], options);
548
+ }
549
+ function recoveryStagePath(directory, entry) {
550
+ const token = createHash("sha256").update(directory).update("\\0").update(entry.backupName).digest("hex");
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;
572
+ }
573
+ async function beforeImage(directory, entry) {
574
+ if (entry.kind === "missing")
575
+ return "missing";
576
+ if (entry.kind === "symlink")
577
+ return `symlink:${entry.linkTarget}`;
578
+ const value = await image(path.join(directory, "before", entry.backupName));
579
+ if (value === "missing")
580
+ throw new Error("Transaction backup is missing; preserve evidence for review.");
581
+ return value;
582
+ }
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
+ async function assertSafeParents(root, sessionRoot, target) {
756
+ assertAllowedTarget(root, sessionRoot, target);
757
+ const boundary = isPathInside(root, target) ? root : sessionRoot;
758
+ for (let parent = path.dirname(target); boundary && mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
759
+ if (path.dirname(parent) === parent)
760
+ throw new Error("Transaction parent did not reach its owned boundary.");
761
+ try {
762
+ const stat = await fs.lstat(parent);
763
+ if ((!stat.isDirectory() && !stat.isFile()) || stat.isSymbolicLink())
764
+ throw new Error("Unsafe transaction parent.");
765
+ }
766
+ catch (error) {
767
+ const code = error.code;
768
+ if (code !== "ENOENT" && code !== "ENOTDIR")
769
+ throw error;
770
+ }
771
+ }
772
+ }
773
+ async function completeTransaction(directory, journal) {
774
+ // Publish completion before deleting any backup. A surviving journal after power loss
775
+ // may only retry cleanup, never roll back already accepted files.
776
+ await writeJson(path.join(directory, "journal.json"), { ...journal, version: journal.sessionRootTransition ? 7 : 6, completed: true }, {
777
+ maxBytes: 32 * 1024 * 1024,
778
+ });
779
+ await removeTransaction(directory);
780
+ }
781
+ async function removeTransaction(directory) {
782
+ await fs.rm(directory, { recursive: true, force: true });
783
+ // After evidence deletion, failure cannot safely trigger rollback or withhold acceptance.
784
+ // A failed cleanup fsync may leave obsolete evidence after power loss; live file durability
785
+ // was established before cleanup; a surviving completed journal allows only cleanup.
786
+ await syncDirectory(transactionRoot()).catch(() => { });
787
+ }