@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,262 @@
1
+ import { createHash } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { assertWithinRoot, isDeniedPath, isPathInside, parentPaths, safeJoin, toPosix } from "../paths.js";
5
+ import { syncDirectory } from "../state/json-file.js";
6
+ import { compileSyncExclude } from "../sync/exclude-policy.js";
7
+ import { agentDir } from "./session-paths.js";
8
+ import { createSnapshot, isSessionFilePath, isSessionPath, sessionStorageRoot, snapshotIncludesSessions, snapshotTarget, } from "./snapshot.js";
9
+ import { assertUnexcludedTargets } from "./snapshot-exclude-safety.js";
10
+ import { applySnapshotTransaction, recoverPendingSnapshotTransactions } from "./snapshot-transaction.js";
11
+ function sha256(value) {
12
+ return createHash("sha256").update(value).digest("hex");
13
+ }
14
+ function fileHashMap(snapshot) {
15
+ return Object.fromEntries(snapshot.files.map((file) => [file.path, file.sha256]));
16
+ }
17
+ export async function applySnapshot(snapshot, protectedRelativePaths = new Set(), options = {}) {
18
+ const root = agentDir();
19
+ const { sessionDir } = options;
20
+ const excluded = compileSyncExclude(options.exclude);
21
+ snapshot = { ...snapshot, files: snapshot.files.filter((file) => !excluded(file.path)) };
22
+ const transactionOptions = {
23
+ sessionDir,
24
+ exclude: options.exclude,
25
+ signal: options.signal,
26
+ validateMutation: options.validateMutation,
27
+ protectedTargets: [...protectedRelativePaths].map((relative) => snapshotTarget(root, relative, sessionDir)),
28
+ expectedPreimages: new Map(Object.entries(options.expectedFileHashes ?? {})
29
+ .filter(([relative]) => !excluded(relative))
30
+ .map(([relative, hash]) => [
31
+ snapshotTarget(root, relative, sessionDir),
32
+ hash === null ? "missing" : `file:${hash}`,
33
+ ])),
34
+ };
35
+ options.validateMutation?.();
36
+ await recoverPendingSnapshotTransactions(transactionOptions);
37
+ const current = await createSnapshot(snapshot.profile, {
38
+ ...options,
39
+ ...(options.include === undefined ? { syncSessions: snapshotIncludesSessions(snapshot) } : {}),
40
+ sessionDir,
41
+ });
42
+ const plan = await addTopLevelCaseVariantDeletes(root, protectSnapshotApplyPlan(root, preflightSnapshotApply(root, snapshot, current, { sessionDir, exclude: options.exclude }), protectedRelativePaths, sessionDir), snapshot);
43
+ await preflightSnapshotMutations(root, plan, sessionDir, options);
44
+ await applySnapshotTransaction(plan, transactionOptions);
45
+ return appliedFileHashMap(snapshot, current, protectedRelativePaths);
46
+ }
47
+ export function preflightSnapshotApply(root, snapshot, current, options = {}) {
48
+ const seenPaths = new Set();
49
+ const remotePaths = new Set();
50
+ const writes = [];
51
+ const deletes = [];
52
+ const excluded = compileSyncExclude(options.exclude);
53
+ for (const file of snapshot.files) {
54
+ const normalized = toPosix(file.path);
55
+ if (!isSafeSnapshotPath(file.path)) {
56
+ throw new Error(`Unsafe path in snapshot: ${file.path}`);
57
+ }
58
+ if (isSessionPath(normalized) && !isSessionFilePath(normalized)) {
59
+ throw new Error(`Unsafe session path in snapshot: ${file.path}`);
60
+ }
61
+ if (excluded(normalized))
62
+ continue;
63
+ if (seenPaths.has(normalized))
64
+ throw new Error(`Duplicate path in snapshot: ${normalized}`);
65
+ seenPaths.add(normalized);
66
+ remotePaths.add(normalized);
67
+ const target = snapshotTarget(root, normalized, options.sessionDir);
68
+ const content = decodeBase64Strict(file.contentBase64, normalized);
69
+ if (sha256(content) !== file.sha256)
70
+ throw new Error(`Checksum mismatch in snapshot file: ${normalized}`);
71
+ writes.push({ target, content });
72
+ }
73
+ const deletePaths = new Set();
74
+ for (const file of current.files) {
75
+ const normalized = toPosix(file.path);
76
+ if (excluded(normalized))
77
+ continue;
78
+ if (!remotePaths.has(normalized)) {
79
+ deletePaths.add(snapshotTarget(root, normalized, options.sessionDir));
80
+ }
81
+ for (const remotePath of parentPaths(normalized)) {
82
+ if (remotePaths.has(remotePath)) {
83
+ deletePaths.add(snapshotTarget(root, remotePath, options.sessionDir));
84
+ }
85
+ }
86
+ }
87
+ deletes.push(...deletePaths);
88
+ return { writes, deletes };
89
+ }
90
+ export function protectSnapshotApplyPlan(root, plan, protectedRelativePaths, sessionDir) {
91
+ if (protectedRelativePaths.size === 0)
92
+ return plan;
93
+ const protectedTargets = new Set([...protectedRelativePaths].map((relativePath) => snapshotTarget(root, relativePath, sessionDir)));
94
+ return {
95
+ writes: plan.writes.filter((item) => !protectedTargets.has(item.target)),
96
+ deletes: plan.deletes.filter((target) => !protectedTargets.has(target)),
97
+ };
98
+ }
99
+ export async function addTopLevelCaseVariantDeletes(root, plan, snapshot) {
100
+ const topLevelPaths = new Map();
101
+ for (const file of snapshot.files) {
102
+ const normalized = toPosix(file.path);
103
+ if (!normalized.includes("/") && isSafeSnapshotPath(file.path)) {
104
+ topLevelPaths.set(normalized.toLowerCase(), normalized);
105
+ }
106
+ }
107
+ if (topLevelPaths.size === 0)
108
+ return plan;
109
+ let entries;
110
+ try {
111
+ entries = await fs.readdir(root, { withFileTypes: true });
112
+ }
113
+ catch (error) {
114
+ if (error.code === "ENOENT")
115
+ return plan;
116
+ throw error;
117
+ }
118
+ const deletes = new Set(plan.deletes);
119
+ for (const entry of entries) {
120
+ const canonicalPath = topLevelPaths.get(entry.name.toLowerCase());
121
+ if (canonicalPath && entry.name !== canonicalPath && (entry.isFile() || entry.isSymbolicLink())) {
122
+ deletes.add(safeJoin(root, entry.name));
123
+ }
124
+ }
125
+ return { ...plan, deletes: [...deletes] };
126
+ }
127
+ export function appliedFileHashMap(snapshot, current, protectedRelativePaths) {
128
+ const hashes = fileHashMap(snapshot);
129
+ if (protectedRelativePaths.size === 0)
130
+ return hashes;
131
+ const currentHashes = fileHashMap(current);
132
+ for (const relativePath of protectedRelativePaths) {
133
+ const normalized = toPosix(relativePath);
134
+ if (currentHashes[normalized]) {
135
+ hashes[normalized] = currentHashes[normalized];
136
+ }
137
+ else {
138
+ delete hashes[normalized];
139
+ }
140
+ }
141
+ return hashes;
142
+ }
143
+ function isSafeSnapshotPath(relativePath) {
144
+ if (relativePath.includes("\\"))
145
+ return false;
146
+ const normalized = toPosix(relativePath);
147
+ return (Boolean(normalized) &&
148
+ normalized !== "." &&
149
+ normalized !== ".." &&
150
+ !normalized.startsWith("../") &&
151
+ !path.posix.isAbsolute(normalized) &&
152
+ path.posix.normalize(normalized) === normalized &&
153
+ !isDeniedPath(normalized));
154
+ }
155
+ function decodeBase64Strict(value, filePath) {
156
+ if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) {
157
+ throw new Error(`Invalid base64 content in snapshot file: ${filePath}`);
158
+ }
159
+ return Buffer.from(value, "base64");
160
+ }
161
+ export async function preflightSnapshotMutations(root, plan, sessionDir, options = {}) {
162
+ assertMutationCurrent(options);
163
+ await assertUnexcludedTargets(root, [...plan.deletes, ...plan.writes.map((item) => item.target)], {
164
+ ...options,
165
+ sessionDir,
166
+ });
167
+ assertMutationCurrent(options);
168
+ const deletePaths = new Set(plan.deletes);
169
+ for (const target of plan.deletes) {
170
+ await assertNoSymlinkParents(rootForTarget(root, target, sessionDir), target, options);
171
+ assertMutationCurrent(options);
172
+ }
173
+ for (const item of plan.writes) {
174
+ await prepareSnapshotWrite(rootForTarget(root, item.target, sessionDir), item.target, deletePaths, options);
175
+ assertMutationCurrent(options);
176
+ }
177
+ }
178
+ function assertMutationCurrent(options) {
179
+ options.validateMutation?.();
180
+ options.signal?.throwIfAborted();
181
+ }
182
+ async function guardedStat(target, options) {
183
+ assertMutationCurrent(options);
184
+ let stat;
185
+ try {
186
+ stat = await fs.lstat(target);
187
+ }
188
+ catch (error) {
189
+ assertMutationCurrent(options);
190
+ if (error.code === "ENOENT")
191
+ return undefined;
192
+ throw error;
193
+ }
194
+ assertMutationCurrent(options);
195
+ return stat;
196
+ }
197
+ function rootForTarget(root, target, sessionDir) {
198
+ const sessionRoot = sessionDir ? sessionStorageRoot(root, sessionDir) : undefined;
199
+ if (sessionRoot && isPathInside(sessionRoot, target))
200
+ return sessionRoot;
201
+ return root;
202
+ }
203
+ async function prepareSnapshotWrite(root, target, deletePaths, options) {
204
+ const parentWillBeReplaced = await ensureSafeDirectory(root, path.dirname(target), deletePaths, options);
205
+ assertMutationCurrent(options);
206
+ if (parentWillBeReplaced)
207
+ return;
208
+ const stat = await guardedStat(target, options);
209
+ assertMutationCurrent(options);
210
+ if (stat?.isSymbolicLink())
211
+ throw new Error(`Refusing to overwrite symlink during snapshot apply: ${target}`);
212
+ if (stat?.isDirectory() && !deletePaths.has(target)) {
213
+ throw new Error(`Refusing to overwrite directory during snapshot apply: ${target}`);
214
+ }
215
+ }
216
+ async function ensureSafeDirectory(root, directory, deletePaths, options) {
217
+ assertMutationCurrent(options);
218
+ assertWithinRoot(root, directory);
219
+ const rootPath = path.resolve(root);
220
+ const relative = path.relative(rootPath, path.resolve(directory));
221
+ let current = rootPath;
222
+ for (const part of relative.split(path.sep).filter(Boolean)) {
223
+ current = path.join(current, part);
224
+ const stat = await guardedStat(current, options);
225
+ assertMutationCurrent(options);
226
+ if (stat) {
227
+ if (stat.isSymbolicLink())
228
+ throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
229
+ if (!stat.isDirectory()) {
230
+ if (deletePaths.has(current))
231
+ return true;
232
+ throw new Error(`Snapshot path parent is not a directory: ${current}`);
233
+ }
234
+ }
235
+ else {
236
+ await fs.mkdir(current);
237
+ assertMutationCurrent(options);
238
+ await syncDirectory(path.dirname(current));
239
+ assertMutationCurrent(options);
240
+ }
241
+ }
242
+ return false;
243
+ }
244
+ async function assertNoSymlinkParents(root, target, options) {
245
+ assertMutationCurrent(options);
246
+ assertWithinRoot(root, target);
247
+ const rootPath = path.resolve(root);
248
+ const relative = path.relative(rootPath, path.resolve(target));
249
+ let current = rootPath;
250
+ const parts = relative.split(path.sep).filter(Boolean);
251
+ for (const part of parts.slice(0, -1)) {
252
+ current = path.join(current, part);
253
+ const stat = await guardedStat(current, options);
254
+ assertMutationCurrent(options);
255
+ if (!stat)
256
+ return;
257
+ if (stat.isSymbolicLink())
258
+ throw new Error(`Refusing to follow symlink during snapshot apply: ${current}`);
259
+ if (!stat.isDirectory())
260
+ throw new Error(`Snapshot path parent is not a directory: ${current}`);
261
+ }
262
+ }
@@ -0,0 +1,15 @@
1
+ import type { SnapshotApplyPlan } from "./snapshot-types.js";
2
+ /** Only the top-level file correction produced by addTopLevelCaseVariantDeletes is eligible. */
3
+ export declare function isCaseReplacement(root: string, before: string, after: string): boolean;
4
+ /** Absence is handled by the journal's removal/replacement evidence, never by naming evidence. */
5
+ export declare function caseReplacementSpelling(before: string, after: string): Promise<string | undefined>;
6
+ export declare function coalesceCaseReplacements(root: string, plan: SnapshotApplyPlan): Promise<{
7
+ replacements: Map<string, string>;
8
+ plan: {
9
+ deletes: string[];
10
+ writes: {
11
+ content: Buffer;
12
+ target: string;
13
+ }[];
14
+ };
15
+ }>;
@@ -0,0 +1,82 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ /** Only the top-level file correction produced by addTopLevelCaseVariantDeletes is eligible. */
4
+ export function isCaseReplacement(root, before, after) {
5
+ return (before !== after &&
6
+ path.dirname(before) === root &&
7
+ path.dirname(after) === root &&
8
+ path.basename(before).toLowerCase() === path.basename(after).toLowerCase());
9
+ }
10
+ /** Absence is handled by the journal's removal/replacement evidence, never by naming evidence. */
11
+ export async function caseReplacementSpelling(before, after) {
12
+ const observations = await Promise.all([before, after].map(async (target) => {
13
+ try {
14
+ const stat = await fs.lstat(target);
15
+ if (!stat.isFile() || stat.nlink !== 1)
16
+ throw new Error("Unsafe case replacement target.");
17
+ return await fs.realpath(target);
18
+ }
19
+ catch (error) {
20
+ if (error.code === "ENOENT")
21
+ return undefined;
22
+ throw error;
23
+ }
24
+ }));
25
+ if (observations.every((value) => value === undefined))
26
+ return undefined;
27
+ if (!observations[0] || observations[0] !== observations[1])
28
+ throw new Error("Case replacement no longer identifies one physical file; preserve evidence for review.");
29
+ const names = (await fs.readdir(path.dirname(before))).filter((name) => name.toLowerCase() === path.basename(before).toLowerCase());
30
+ if (names.length !== 1 || (names[0] !== path.basename(before) && names[0] !== path.basename(after)))
31
+ throw new Error("Case replacement spelling changed; preserve evidence for review.");
32
+ return path.join(path.dirname(before), names[0]);
33
+ }
34
+ export async function coalesceCaseReplacements(root, plan) {
35
+ const replacements = new Map();
36
+ const deletesByCase = new Map();
37
+ const writeTargets = new Set(plan.writes.map((item) => item.target));
38
+ for (const target of new Set(plan.deletes)) {
39
+ if (path.dirname(target) !== root || writeTargets.has(target))
40
+ continue;
41
+ const key = path.basename(target).toLowerCase();
42
+ const group = deletesByCase.get(key) ?? [];
43
+ group.push(target);
44
+ deletesByCase.set(key, group);
45
+ }
46
+ for (const item of plan.writes) {
47
+ if (path.dirname(item.target) !== root)
48
+ continue;
49
+ const candidates = deletesByCase.get(path.basename(item.target).toLowerCase()) ?? [];
50
+ if (candidates.length !== 1)
51
+ continue;
52
+ const before = candidates[0];
53
+ if (!before || !isCaseReplacement(root, before, item.target))
54
+ continue;
55
+ // Different real paths on a case-sensitive filesystem remain independent targets.
56
+ let beforePath;
57
+ let afterPath;
58
+ try {
59
+ [beforePath, afterPath] = await Promise.all([fs.realpath(before), fs.realpath(item.target)]);
60
+ }
61
+ catch (error) {
62
+ if (error.code === "ENOENT")
63
+ continue;
64
+ throw error;
65
+ }
66
+ if (beforePath !== afterPath)
67
+ continue;
68
+ if (replacements.has(before))
69
+ throw new Error("Multiple writes alias a case replacement target.");
70
+ if ((await caseReplacementSpelling(before, item.target)) !== before)
71
+ throw new Error("Case replacement preimage spelling changed; review is required.");
72
+ replacements.set(before, item.target);
73
+ }
74
+ const beforeByAfter = new Map([...replacements].map(([before, after]) => [after, before]));
75
+ return {
76
+ replacements,
77
+ plan: {
78
+ deletes: plan.deletes,
79
+ writes: plan.writes.map((item) => ({ ...item, target: beforeByAfter.get(item.target) ?? item.target })),
80
+ },
81
+ };
82
+ }
@@ -0,0 +1,6 @@
1
+ import type { Snapshot } from "./snapshot-types.js";
2
+ export declare function encodeSnapshot(snapshot: Snapshot): Promise<NonSharedBuffer>;
3
+ export declare function decodeSnapshot(buffer: Buffer, options?: {
4
+ signal?: AbortSignal;
5
+ maxOutputLength?: number;
6
+ }): Promise<Snapshot>;
@@ -0,0 +1,53 @@
1
+ import { Readable, Writable } from "node:stream";
2
+ import { pipeline } from "node:stream/promises";
3
+ import { promisify } from "node:util";
4
+ import { createGunzip, gzip } from "node:zlib";
5
+ import { throwIfAborted } from "../sync/signals.js";
6
+ import { snapshotSelectionInclude, validateSnapshotSelection } from "../sync/sync-policy.js";
7
+ const VERSION = 1;
8
+ const MAX_DECOMPRESSED_SNAPSHOT_BYTES = 512 * 1024 * 1024;
9
+ const gzipAsync = promisify(gzip);
10
+ export async function encodeSnapshot(snapshot) {
11
+ snapshotSelectionInclude(snapshot);
12
+ validateSnapshotSelection(snapshot);
13
+ if (snapshot.version === 4) {
14
+ const { validatePortableSnapshot } = await import("../sync/local-fields.js");
15
+ validatePortableSnapshot(snapshot);
16
+ }
17
+ return gzipAsync(Buffer.from(JSON.stringify(snapshot), "utf8"));
18
+ }
19
+ export async function decodeSnapshot(buffer, options = {}) {
20
+ throwIfAborted(options.signal);
21
+ const limit = options.maxOutputLength ?? MAX_DECOMPRESSED_SNAPSHOT_BYTES;
22
+ const chunks = [];
23
+ let total = 0;
24
+ const sink = new Writable({
25
+ write(chunk, _encoding, callback) {
26
+ total += chunk.byteLength;
27
+ if (total > limit) {
28
+ callback(new Error(`Decompressed snapshot exceeds the ${limit}-byte limit.`));
29
+ return;
30
+ }
31
+ chunks.push(Buffer.from(chunk));
32
+ callback();
33
+ },
34
+ });
35
+ await pipeline(Readable.from([buffer]), createGunzip(), sink, { signal: options.signal });
36
+ throwIfAborted(options.signal);
37
+ const parsed = JSON.parse(Buffer.concat(chunks, total).toString("utf8"));
38
+ if ((parsed.version !== VERSION && parsed.version !== 2 && parsed.version !== 3 && parsed.version !== 4) ||
39
+ !Array.isArray(parsed.files)) {
40
+ throw new Error("Unsupported snapshot format.");
41
+ }
42
+ validateSnapshotSelection(parsed);
43
+ if (parsed.version === 2 || parsed.version === 3 || parsed.version === 4) {
44
+ const { normalizeLocalFields, validatePortableSnapshot } = await import("../sync/local-fields.js");
45
+ validatePortableSnapshot(parsed);
46
+ if (parsed.localFields !== undefined)
47
+ parsed.localFields = normalizeLocalFields(parsed.localFields);
48
+ }
49
+ else if (parsed.localFields !== undefined)
50
+ throw new Error("Portable field policy requires snapshot version 2.");
51
+ snapshotSelectionInclude(parsed);
52
+ return parsed;
53
+ }
@@ -0,0 +1,7 @@
1
+ /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
2
+ export declare function assertUnexcludedTargets(root: string, targets: Iterable<string>, options: {
3
+ exclude?: readonly string[];
4
+ sessionDir?: string;
5
+ signal?: AbortSignal;
6
+ validateMutation?: () => void;
7
+ }): Promise<void>;
@@ -0,0 +1,47 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { isPathInside, toPosix } from "../paths.js";
4
+ import { compileSyncExclude } from "../sync/exclude-policy.js";
5
+ import { sessionStorageRoot } from "./snapshot-paths.js";
6
+ /** Metadata-only preflight: an ancestor replacement must not capture/remove excluded descendants. */
7
+ export async function assertUnexcludedTargets(root, targets, options) {
8
+ if (!options.exclude?.length)
9
+ return;
10
+ const excluded = compileSyncExclude(options.exclude);
11
+ const sessionRoot = sessionStorageRoot(root, options.sessionDir);
12
+ let visited = 0;
13
+ const validate = () => {
14
+ options.signal?.throwIfAborted();
15
+ options.validateMutation?.();
16
+ };
17
+ async function visit(target) {
18
+ validate();
19
+ if (++visited > 16_384)
20
+ throw new Error("Exclude safety preflight exceeds its path bound; review a smaller transfer.");
21
+ const candidates = [];
22
+ if (isPathInside(root, target))
23
+ candidates.push(toPosix(path.relative(root, target)));
24
+ if (isPathInside(sessionRoot, target))
25
+ candidates.push(`sessions/${toPosix(path.relative(sessionRoot, target))}`);
26
+ if (candidates.some(excluded))
27
+ throw new Error("Transfer would replace an excluded path or directory descendant; no replacement is authorized.");
28
+ try {
29
+ const stat = await fs.lstat(target);
30
+ validate();
31
+ if (!stat.isDirectory() || stat.isSymbolicLink())
32
+ return;
33
+ const names = await fs.readdir(target);
34
+ validate();
35
+ for (const name of names)
36
+ await visit(path.join(target, name));
37
+ }
38
+ catch (error) {
39
+ validate();
40
+ const code = error.code;
41
+ if (code !== "ENOENT" && code !== "ENOTDIR")
42
+ throw error;
43
+ }
44
+ }
45
+ for (const target of new Set(targets))
46
+ await visit(target);
47
+ }
@@ -0,0 +1,9 @@
1
+ import { type EngineHost } from "../host.js";
2
+ type MutationGuards = {
3
+ signal?: AbortSignal;
4
+ validateMutation?: () => void;
5
+ };
6
+ export declare function assertCanonicalMutationTargets(targets: readonly string[], options: MutationGuards): Promise<void>;
7
+ export declare function withTargetQueues<T>(targets: readonly string[], options: MutationGuards, action: (heldKeys: ReadonlySet<string>) => Promise<T>, coordinator?: Pick<EngineHost, "mutate" | "reserveTargets">): Promise<T>;
8
+ export declare function withMissingTargetQueues<T>(targets: readonly string[], heldKeys: ReadonlySet<string>, options: MutationGuards, action: (heldKeys: ReadonlySet<string>) => Promise<T>): Promise<T>;
9
+ export {};
@@ -0,0 +1,133 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { engineHost, withEngineMutationQueue as withFileMutationQueue } from "../host.js";
4
+ function assertCurrent(options) {
5
+ options.validateMutation?.();
6
+ options.signal?.throwIfAborted();
7
+ }
8
+ function isMissing(error) {
9
+ const code = error.code;
10
+ return code === "ENOENT" || code === "ENOTDIR";
11
+ }
12
+ async function targetMissing(target, options) {
13
+ assertCurrent(options);
14
+ try {
15
+ await fs.lstat(target);
16
+ assertCurrent(options);
17
+ return false;
18
+ }
19
+ catch (error) {
20
+ assertCurrent(options);
21
+ if (!isMissing(error))
22
+ throw error;
23
+ return true;
24
+ }
25
+ }
26
+ async function queueKey(target, options) {
27
+ assertCurrent(options);
28
+ try {
29
+ const key = await fs.realpath(target);
30
+ assertCurrent(options);
31
+ return key;
32
+ }
33
+ catch (error) {
34
+ assertCurrent(options);
35
+ if (!isMissing(error))
36
+ throw error;
37
+ return path.resolve(target);
38
+ }
39
+ }
40
+ /** Resolve missing descendants too, including descendants of a file scheduled for removal. */
41
+ async function assertCanonicalParent(target, options) {
42
+ const parent = path.dirname(path.resolve(target));
43
+ const suffix = [];
44
+ for (let current = parent;; current = path.dirname(current)) {
45
+ assertCurrent(options);
46
+ let canonical;
47
+ try {
48
+ canonical = await fs.realpath(current);
49
+ }
50
+ catch (error) {
51
+ assertCurrent(options);
52
+ if (!isMissing(error) || path.dirname(current) === current)
53
+ throw error;
54
+ suffix.unshift(path.basename(current));
55
+ continue;
56
+ }
57
+ assertCurrent(options);
58
+ // Pi queues existing paths by realpath and missing paths by lexical resolve.
59
+ // Its public API cannot reserve a missing alias key while that alias exists,
60
+ // or report a key that changes during registration. Refuse aliased parents
61
+ // before mutation rather than risk a non-reentrant queue or overwrite a writer.
62
+ if (path.join(canonical, ...suffix) !== parent)
63
+ throw new Error("Snapshot mutation through an aliased parent is unsafe; use the canonical agent/session path. Transaction evidence retained for review.");
64
+ return;
65
+ }
66
+ }
67
+ export async function assertCanonicalMutationTargets(targets, options) {
68
+ for (const target of targets)
69
+ await assertCanonicalParent(target, options);
70
+ }
71
+ export async function withTargetQueues(targets, options, action, coordinator = engineHost()) {
72
+ // Check the whole group before reserving any key or changing live files.
73
+ await assertCanonicalMutationTargets(targets, options);
74
+ const keys = new Set();
75
+ const missing = new Set();
76
+ for (const target of targets) {
77
+ if (await targetMissing(target, options))
78
+ missing.add(target);
79
+ const key = await queueKey(target, options);
80
+ if (keys.has(key))
81
+ throw new Error("Transaction targets alias the same file.");
82
+ keys.add(key);
83
+ }
84
+ const ordered = [...keys].sort();
85
+ async function acquire(index) {
86
+ assertCurrent(options);
87
+ const key = ordered[index];
88
+ // Pass the resolved key, not an alias whose lookup can select a different key.
89
+ if (key)
90
+ return coordinator.mutate(key, () => acquire(index + 1));
91
+ for (const target of targets) {
92
+ await assertCanonicalParent(target, options);
93
+ if (missing.has(target) && !(await targetMissing(target, options)))
94
+ throw new Error("Missing transaction target appeared during queue acquisition; review is required.");
95
+ if (!keys.has(await queueKey(target, options)))
96
+ throw new Error("Transaction queue identity changed; review is required.");
97
+ }
98
+ assertCurrent(options);
99
+ return action(keys);
100
+ }
101
+ const reserve = coordinator.reserveTargets;
102
+ return reserve ? reserve(ordered, () => acquire(0)) : acquire(0);
103
+ }
104
+ export async function withMissingTargetQueues(targets, heldKeys, options, action) {
105
+ const unique = [...new Set(targets)];
106
+ const requireAbsent = async () => {
107
+ for (const target of unique) {
108
+ await assertCanonicalParent(target, options);
109
+ if (!(await targetMissing(target, options)))
110
+ throw new Error("Snapshot target changed before destination queue reservation; evidence retained.");
111
+ }
112
+ };
113
+ // Canonical parents make each missing key equal to the intended installed key.
114
+ // Retain the old physical key and exclude it from these non-reentrant queues.
115
+ const keys = unique
116
+ .map((target) => path.resolve(target))
117
+ .filter((key) => !heldKeys.has(key))
118
+ .sort();
119
+ await requireAbsent();
120
+ const combined = new Set([...heldKeys, ...keys]);
121
+ async function acquire(index) {
122
+ assertCurrent(options);
123
+ const key = keys[index];
124
+ if (key)
125
+ return withFileMutationQueue(key, () => acquire(index + 1));
126
+ // A writer registered in the removal gap must finish before this check.
127
+ // Even recognizable pre/postimages belong to that writer, not this transaction.
128
+ await requireAbsent();
129
+ assertCurrent(options);
130
+ return action(combined);
131
+ }
132
+ return acquire(0);
133
+ }
@@ -0,0 +1 @@
1
+ export declare function sessionStorageRoot(root: string, configuredSessionDir?: string): string;
@@ -0,0 +1,11 @@
1
+ import path from "node:path";
2
+ function expandHome(value) {
3
+ if (value === "~")
4
+ return process.env.HOME ?? value;
5
+ if (value.startsWith("~/"))
6
+ return path.join(process.env.HOME ?? "~", value.slice(2));
7
+ return value;
8
+ }
9
+ export function sessionStorageRoot(root, configuredSessionDir) {
10
+ return configuredSessionDir ? path.resolve(expandHome(configuredSessionDir)) : path.resolve(root, "sessions");
11
+ }
@@ -0,0 +1,25 @@
1
+ import type { SnapshotApplyPlan } from "./snapshot-types.js";
2
+ export interface SessionRootTransition {
3
+ beforeRoot: string;
4
+ /** null is a verified missing postimage, never an empty settings file. */
5
+ settingsAfterBase64?: string | null;
6
+ /** Reviewed bytes live in a private fsynced sidecar, pinned by the entry afterImage. */
7
+ settingsAfterFile?: true;
8
+ }
9
+ interface TransitionGuards {
10
+ signal?: AbortSignal;
11
+ validateMutation?: () => void;
12
+ }
13
+ interface SettingsEntry {
14
+ target: string;
15
+ afterTarget?: string;
16
+ backupName: string;
17
+ kind: string;
18
+ beforeImage?: string;
19
+ afterImage?: string;
20
+ }
21
+ export declare function prepareSessionRootTransition(directory: string, root: string, sessionRoot: string, entries: SettingsEntry[], plan: SnapshotApplyPlan, guards?: TransitionGuards): Promise<SessionRootTransition | undefined>;
22
+ export declare function validateSessionRootTransition(value: SessionRootTransition): void;
23
+ /** Authorization is bound to both settings images, never just an arbitrary pinned root. */
24
+ export declare function resolveTransitionSessionRoot(directory: string, root: string, sessionRoot: string, transition: SessionRootTransition, entries: SettingsEntry[], currentRoot: string, guards?: TransitionGuards): Promise<string>;
25
+ export {};