@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,116 @@
1
+ import { createHash } from "node:crypto";
2
+ import { regenerateSnapshotIdentity } from "../snapshot/snapshot.js";
3
+ import { compileSyncExclude } from "./exclude-policy.js";
4
+ import { jsonEqual, parseSettingsDocument, renderSettingsMembers, } from "./json-document.js";
5
+ import { normalizeLocalFields } from "./local-field-policy.js";
6
+ import { snapshotSelectionExclude, validateSnapshotSelection } from "./sync-policy.js";
7
+ export { normalizeLocalFields } from "./local-field-policy.js";
8
+ /** Shared transport contract: older snapshots cannot carry portable policy metadata. */
9
+ export function validateSnapshotFieldPolicy(snapshot) {
10
+ if (snapshot.version !== 1 && snapshot.version !== 2 && snapshot.version !== 3 && snapshot.version !== 4)
11
+ throw new Error("Unsupported snapshot format.");
12
+ if (snapshot.version === 1 && snapshot.localFields !== undefined)
13
+ throw new Error("Portable field policy requires snapshot version 2.");
14
+ if (snapshot.version === 2 || snapshot.version === 3 || snapshot.version === 4) {
15
+ if (snapshot.version === 2 && snapshot.localFields === undefined)
16
+ throw new Error("Snapshot version 2 requires explicit localFields rules.");
17
+ normalizeLocalFields(snapshot.localFields);
18
+ }
19
+ }
20
+ /** Portable transport images must not carry values declared machine-local. Physical journal images are different. */
21
+ export function validatePortableSnapshot(snapshot) {
22
+ validateSnapshotFieldPolicy(snapshot);
23
+ validateSnapshotSelection(snapshot);
24
+ const excludedPath = compileSyncExclude(snapshotSelectionExclude(snapshot));
25
+ if (snapshot.files.some((file) => excludedPath(file.path)))
26
+ throw new Error("Portable snapshot retains excluded paths.");
27
+ if (snapshot.version === 1 || !snapshot.localFields?.length)
28
+ return;
29
+ try {
30
+ for (const entry of snapshot.files) {
31
+ if (typeof entry?.path !== "string" || entry.path.toLowerCase() !== "settings.json")
32
+ continue;
33
+ const document = parseSettingsDocument(Buffer.from(entry.contentBase64, "base64"));
34
+ if (snapshot.localFields.some((field) => document.root.members.has(field)))
35
+ throw new Error("Excluded field.");
36
+ }
37
+ }
38
+ catch {
39
+ throw new Error("Portable snapshot settings.json retains excluded fields or has an unsupported document.");
40
+ }
41
+ }
42
+ export function sameLocalFields(left, right) {
43
+ if (left === undefined || right === undefined)
44
+ return left === right;
45
+ return JSON.stringify(normalizeLocalFields(left)) === JSON.stringify(normalizeLocalFields(right));
46
+ }
47
+ function file(content) {
48
+ return {
49
+ path: "settings.json",
50
+ contentBase64: content.toString("base64"),
51
+ sha256: createHash("sha256").update(content).digest("hex"),
52
+ };
53
+ }
54
+ export function portableSnapshot(snapshot, fields) {
55
+ if (fields === undefined)
56
+ return snapshot;
57
+ const excluded = new Set(normalizeLocalFields(fields));
58
+ const files = snapshot.files.map((entry) => {
59
+ if (entry.path !== "settings.json" || excluded.size === 0)
60
+ return entry;
61
+ const document = parseSettingsDocument(Buffer.from(entry.contentBase64, "base64"));
62
+ const object = Object.create(null);
63
+ for (const key of [...document.root.members.keys()].sort())
64
+ if (!excluded.has(key))
65
+ object[key] = document.root.members.get(key)?.node.value;
66
+ const canonical = (value) => Array.isArray(value)
67
+ ? value.map(canonical)
68
+ : value && typeof value === "object"
69
+ ? Object.fromEntries(Object.entries(value)
70
+ .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
71
+ .map(([key, child]) => [key, canonical(child)]))
72
+ : value;
73
+ return file(Buffer.from(`${JSON.stringify(canonical(object))}\n`));
74
+ });
75
+ return regenerateSnapshotIdentity({
76
+ ...snapshot,
77
+ version: snapshot.version === 4 ? 4 : 2,
78
+ localFields: [...excluded],
79
+ files,
80
+ });
81
+ }
82
+ export function overlayLocalFields(portable, local, fields) {
83
+ if (!fields?.length)
84
+ return portable;
85
+ const target = portable.files.find((entry) => entry.path === "settings.json");
86
+ const current = local.files.find((entry) => entry.path === "settings.json");
87
+ if (!target && !current)
88
+ return portable;
89
+ const original = current
90
+ ? parseSettingsDocument(Buffer.from(current.contentBase64, "base64"))
91
+ : parseSettingsDocument(Buffer.from("{}"));
92
+ if (!target) {
93
+ if (fields.some((field) => original.root.members.has(field)))
94
+ throw new Error("Portable settings deletion requires manual review; local-only fields were preserved.");
95
+ return portable;
96
+ }
97
+ const incoming = parseSettingsDocument(Buffer.from(target.contentBase64, "base64"));
98
+ const selected = new Map();
99
+ const excluded = new Set(fields);
100
+ for (const [key, member] of incoming.root.members) {
101
+ if (excluded.has(key))
102
+ continue;
103
+ const existing = original.root.members.get(key);
104
+ selected.set(key, existing && jsonEqual(existing.node.value, member.node.value)
105
+ ? { document: original, node: existing.node }
106
+ : { document: incoming, node: member.node });
107
+ }
108
+ for (const [key, member] of original.root.members)
109
+ if (excluded.has(key))
110
+ selected.set(key, { document: original, node: member.node });
111
+ const content = renderSettingsMembers(original, selected);
112
+ return regenerateSnapshotIdentity({
113
+ ...portable,
114
+ files: portable.files.map((entry) => (entry.path === "settings.json" ? file(content) : entry)),
115
+ });
116
+ }
@@ -0,0 +1,5 @@
1
+ import type { Snapshot, SnapshotOptions } from "../snapshot/snapshot-types.js";
2
+ /** Read-only filesystem applicability check before publishing a combined result. */
3
+ export declare function preflightMergedTargets(before: Snapshot, after: Snapshot, options: SnapshotOptions, protectedTarget?: string | readonly string[]): Promise<void>;
4
+ /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
5
+ export declare function applyMergedSnapshot(before: Snapshot, after: Snapshot, protectedPaths: Set<string>, options: SnapshotOptions, validate: () => Promise<void>, protectedTarget?: string): Promise<void>;
@@ -0,0 +1,386 @@
1
+ import { createHash, randomUUID } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
4
+ import { withEngineMutationQueue as withFileMutationQueue } from "../host.js";
5
+ import { agentDir } from "../snapshot/session-paths.js";
6
+ import { createSnapshot, snapshotTarget } from "../snapshot/snapshot.js";
7
+ import { preflightSnapshotApply, preflightSnapshotMutations } from "../snapshot/snapshot-apply.js";
8
+ import { assertUnexcludedTargets } from "../snapshot/snapshot-exclude-safety.js";
9
+ import { assertCanonicalMutationTargets } from "../snapshot/snapshot-mutation-queues.js";
10
+ import { sessionStorageRoot } from "../snapshot/snapshot-paths.js";
11
+ import { syncDirectory } from "../state/json-file.js";
12
+ import { syncMutationParents } from "../state/mutation-directory-sync.js";
13
+ import { mergePathIdentity } from "./file-merge-planner.js";
14
+ import { fileHashMap } from "./sync-state.js";
15
+ /** Read-only filesystem applicability check before publishing a combined result. */
16
+ export async function preflightMergedTargets(before, after, options, protectedTarget) {
17
+ const root = agentDir();
18
+ const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
19
+ const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
20
+ const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
21
+ const changed = new Set(paths.filter((item) => beforeHashes[item] !== afterHashes[item]));
22
+ await assertUnexcludedTargets(root, [...changed].map((item) => snapshotTarget(root, item, options.sessionDir)), options);
23
+ await assertCanonicalMergedTargets(root, changed, options);
24
+ await assertDistinctMergedTargets(root, paths, changed, options, protectedTarget, new Set(Object.keys(afterHashes)));
25
+ const removed = replacementPaths(new Set(paths.filter((item) => changed.has(item) && !afterHashes[item])), afterHashes);
26
+ const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
27
+ for (const relative of paths) {
28
+ if (changed.has(relative))
29
+ await assertFilesystemTarget(root, relative, options, removedTargets, beforeHashes);
30
+ }
31
+ await assertCanonicalMutationTargets([...changed].map((relative) => snapshotTarget(root, relative, options.sessionDir)), options);
32
+ }
33
+ function replacementPaths(removed, afterHashes) {
34
+ for (const relative of [...removed]) {
35
+ let parent = path.posix.dirname(relative);
36
+ while (parent !== ".") {
37
+ if (afterHashes[parent]) {
38
+ for (let directory = path.posix.dirname(relative); directory !== parent; directory = path.posix.dirname(directory))
39
+ removed.add(directory);
40
+ removed.add(parent);
41
+ break;
42
+ }
43
+ parent = path.posix.dirname(parent);
44
+ }
45
+ }
46
+ return removed;
47
+ }
48
+ /** Snapshot collection canonicalizes top-level names, but merged journals own exact physical paths. */
49
+ async function assertCanonicalMergedTargets(root, changed, options) {
50
+ const topLevel = new Map([...changed].filter((relative) => !relative.includes("/")).map((relative) => [relative.toLowerCase(), relative]));
51
+ if (topLevel.size === 0)
52
+ return;
53
+ options.signal?.throwIfAborted();
54
+ options.validateMutation?.();
55
+ let names;
56
+ try {
57
+ names = await fs.readdir(root);
58
+ }
59
+ catch (error) {
60
+ options.signal?.throwIfAborted();
61
+ options.validateMutation?.();
62
+ if (error.code !== "ENOENT")
63
+ throw error;
64
+ return;
65
+ }
66
+ options.signal?.throwIfAborted();
67
+ options.validateMutation?.();
68
+ for (const name of names) {
69
+ const canonical = topLevel.get(name.toLowerCase());
70
+ if (canonical !== undefined && name !== canonical)
71
+ throw new Error("Merged target has a noncanonical case variant; normalize selected top-level file spelling before retrying. Journal retained if already committed.");
72
+ }
73
+ }
74
+ /** Even an unchanged virtual alias must not describe different bytes for a changed physical file. */
75
+ async function assertDistinctMergedTargets(root, paths, changed, options, protectedTarget, finalPaths = new Set(paths)) {
76
+ const protectedKeys = new Set();
77
+ for (const target of typeof protectedTarget === "string" ? [protectedTarget] : (protectedTarget ?? []))
78
+ protectedKeys.add(mergePathIdentity(await resolvedTargetIdentity(path.resolve(target), options)));
79
+ options.signal?.throwIfAborted();
80
+ options.validateMutation?.();
81
+ const keys = new Map();
82
+ for (const relative of paths) {
83
+ options.signal?.throwIfAborted();
84
+ const target = snapshotTarget(root, relative, options.sessionDir);
85
+ const key = mergePathIdentity(await resolvedTargetIdentity(target, options));
86
+ options.signal?.throwIfAborted();
87
+ options.validateMutation?.();
88
+ const existing = keys.get(key);
89
+ if (existing &&
90
+ (mergePathIdentity(existing) !== mergePathIdentity(relative) ||
91
+ (finalPaths.has(existing) && finalPaths.has(relative))))
92
+ throw new Error("Merged paths resolve to the same file; reviewed directional recovery is required.");
93
+ if (protectedKeys.has(key) && changed.has(relative))
94
+ throw new Error("A merged transfer targets the current session; review is required.");
95
+ keys.set(key, relative);
96
+ }
97
+ }
98
+ async function assertReviewedTree(directory, relative, beforeHashes) {
99
+ for (const name of await fs.readdir(directory)) {
100
+ const child = path.join(directory, name);
101
+ const childRelative = `${relative}/${name}`;
102
+ const stat = await fs.lstat(child);
103
+ if (stat.isDirectory()) {
104
+ await assertReviewedTree(child, childRelative, beforeHashes);
105
+ }
106
+ else if (stat.isFile() &&
107
+ stat.nlink === 1 &&
108
+ beforeHashes[childRelative] ===
109
+ createHash("sha256")
110
+ .update(await fs.readFile(child))
111
+ .digest("hex")) {
112
+ }
113
+ else {
114
+ throw new Error("Reviewed directory contains unknown or changed files; publication refused.");
115
+ }
116
+ }
117
+ }
118
+ function hasBlockingFileAncestor(target, files) {
119
+ for (let parent = path.dirname(target); parent !== path.dirname(parent); parent = path.dirname(parent))
120
+ if (files.has(parent))
121
+ return true;
122
+ return false;
123
+ }
124
+ async function resolvedTargetIdentity(target, options) {
125
+ // Resolve the nearest existing ancestor too: roots may alias even when a target is absent.
126
+ let ancestor = target;
127
+ while (true) {
128
+ options.signal?.throwIfAborted();
129
+ try {
130
+ const resolved = await fs.realpath(ancestor);
131
+ return path.resolve(resolved, path.relative(ancestor, target));
132
+ }
133
+ catch (error) {
134
+ const code = error.code;
135
+ if (code !== "ENOENT" && code !== "ENOTDIR")
136
+ throw error;
137
+ const parent = path.dirname(ancestor);
138
+ if (parent === ancestor)
139
+ return target;
140
+ ancestor = parent;
141
+ }
142
+ }
143
+ }
144
+ async function assertFilesystemTarget(root, relative, options, removedTargets = new Set(), beforeHashes) {
145
+ const target = snapshotTarget(root, relative, options.sessionDir);
146
+ const boundary = relative.startsWith("sessions/") && options.sessionDir
147
+ ? path.resolve(sessionStorageRoot(root, options.sessionDir))
148
+ : path.resolve(root);
149
+ for (let parent = path.dirname(target); mergePathIdentity(parent) !== mergePathIdentity(boundary); parent = path.dirname(parent)) {
150
+ options.signal?.throwIfAborted();
151
+ if (path.dirname(parent) === parent)
152
+ throw new Error("Unowned merged target.");
153
+ try {
154
+ const stat = await fs.lstat(parent);
155
+ if ((!stat.isDirectory() || stat.isSymbolicLink()) &&
156
+ !(stat.isFile() && stat.nlink === 1 && removedTargets.has(parent)))
157
+ throw new Error("Unsafe merge filesystem layout; review the selected paths before transfer.");
158
+ }
159
+ catch (error) {
160
+ const code = error.code;
161
+ if (code !== "ENOENT")
162
+ throw error;
163
+ }
164
+ }
165
+ options.signal?.throwIfAborted();
166
+ try {
167
+ const stat = await fs.lstat(target);
168
+ if ((!stat.isFile() && !removedTargets.has(target)) || (stat.isFile() && stat.nlink > 1))
169
+ throw new Error("Merge target is non-regular or hard-linked; review a directional operation before transfer.");
170
+ if (stat.isDirectory() && beforeHashes)
171
+ await assertReviewedTree(target, relative, beforeHashes);
172
+ }
173
+ catch (error) {
174
+ const code = error.code;
175
+ if (code !== "ENOENT" && !(code === "ENOTDIR" && removedTargets.size > 0))
176
+ throw error;
177
+ }
178
+ }
179
+ /** Roll forward only while each target is still its reviewed preimage or committed postimage. */
180
+ export async function applyMergedSnapshot(before, after, protectedPaths, options, validate, protectedTarget) {
181
+ const root = agentDir();
182
+ const beforeHashes = Object.assign(Object.create(null), fileHashMap(before));
183
+ const afterHashes = Object.assign(Object.create(null), fileHashMap(after));
184
+ const paths = [...new Set([...Object.keys(beforeHashes), ...Object.keys(afterHashes)])].sort();
185
+ const replacements = replacementPaths(new Set(paths.filter((item) => beforeHashes[item] && !afterHashes[item])), afterHashes);
186
+ const intermediateDirectories = [...replacements].filter((item) => !beforeHashes[item] && !afterHashes[item]);
187
+ const changed = [
188
+ ...new Set([...paths.filter((item) => beforeHashes[item] !== afterHashes[item]), ...intermediateDirectories]),
189
+ ].sort();
190
+ const protectedKeys = new Set([...protectedPaths].map(mergePathIdentity));
191
+ if (changed.some((item) => protectedKeys.has(mergePathIdentity(item)))) {
192
+ throw new Error("A merged transfer targets the current session; review is required.");
193
+ }
194
+ // Exact file queues, not a directory pseudo-lock: Pi edit/write tools use these keys.
195
+ const targets = changed.map((item) => snapshotTarget(root, item, options.sessionDir));
196
+ const relativeByTarget = new Map(targets.map((target, index) => [target, changed[index]]));
197
+ const targetSet = new Set(targets);
198
+ await assertDistinctMergedTargets(root, paths, new Set(changed), options, protectedTarget, new Set(Object.keys(afterHashes)));
199
+ await assertCanonicalMutationTargets(targets, options);
200
+ // Existing case aliases share Pi's non-reentrant realpath queue. Reserve the
201
+ // missing destination separately only after deleting its reviewed preimage.
202
+ const targetsByQueue = new Map();
203
+ const queueTargets = [];
204
+ const deferredTargets = [];
205
+ for (const target of targets) {
206
+ let key = path.resolve(target);
207
+ try {
208
+ key = await fs.realpath(target);
209
+ }
210
+ catch (error) {
211
+ const code = error.code;
212
+ if (code !== "ENOENT" && code !== "ENOTDIR")
213
+ throw error;
214
+ }
215
+ options.signal?.throwIfAborted();
216
+ options.validateMutation?.();
217
+ const aliases = targetsByQueue.get(key) ?? [];
218
+ aliases.push(target);
219
+ targetsByQueue.set(key, aliases);
220
+ }
221
+ for (const [key, aliases] of targetsByQueue) {
222
+ queueTargets.push(key);
223
+ if (aliases.length > 1)
224
+ deferredTargets.push(...aliases.filter((target) => path.resolve(target) !== key));
225
+ }
226
+ async function acquire(index) {
227
+ const target = queueTargets[index];
228
+ if (target)
229
+ return withFileMutationQueue(target, () => acquire(index + 1));
230
+ await validate();
231
+ await assertCanonicalMergedTargets(root, changed, options);
232
+ await validate();
233
+ const current = await createSnapshot(before.profile, options);
234
+ const currentHashes = Object.assign(Object.create(null), fileHashMap(current));
235
+ const blockingFiles = new Set(paths
236
+ .filter((relative) => (beforeHashes[relative] && !afterHashes[relative]) ||
237
+ (afterHashes[relative] && currentHashes[relative] === afterHashes[relative]))
238
+ .map((relative) => snapshotTarget(root, relative, options.sessionDir)));
239
+ for (const item of changed) {
240
+ if (currentHashes[item] !== beforeHashes[item] && currentHashes[item] !== afterHashes[item]) {
241
+ throw new Error("Local content changed during merged transfer; journal retained for review. No newer bytes were replaced.");
242
+ }
243
+ const target = snapshotTarget(root, item, options.sessionDir);
244
+ try {
245
+ const stat = await fs.lstat(target);
246
+ if ((!stat.isFile() && !stat.isDirectory()) || (stat.isFile() && stat.nlink > 1))
247
+ throw new Error("Merged transfer target is no longer an independent regular file.");
248
+ }
249
+ catch (error) {
250
+ const code = error.code;
251
+ if (code !== "ENOENT" && !(code === "ENOTDIR" && hasBlockingFileAncestor(target, blockingFiles)))
252
+ throw error;
253
+ }
254
+ }
255
+ const plan = preflightSnapshotApply(root, after, current, options);
256
+ plan.writes = plan.writes.filter((item) => targetSet.has(item.target));
257
+ plan.deletes = plan.deletes.filter((target) => targetSet.has(target));
258
+ await preflightSnapshotMutations(root, plan, options.sessionDir, options);
259
+ const deletedTargets = new Set(plan.deletes);
260
+ for (const relative of intermediateDirectories) {
261
+ for (let parent = path.posix.dirname(relative); parent !== "."; parent = path.posix.dirname(parent)) {
262
+ if (afterHashes[parent] && deletedTargets.has(snapshotTarget(root, parent, options.sessionDir))) {
263
+ plan.deletes.push(snapshotTarget(root, relative, options.sessionDir));
264
+ break;
265
+ }
266
+ }
267
+ }
268
+ // A parent must remain until every reviewed leaf and intermediate directory is gone.
269
+ plan.deletes.sort((left, right) => right.split(path.sep).length - left.split(path.sep).length || left.localeCompare(right));
270
+ const removed = replacementPaths(new Set(paths.filter((relative) => deletedTargets.has(snapshotTarget(root, relative, options.sessionDir)))), afterHashes);
271
+ const removedTargets = new Set([...removed].map((item) => snapshotTarget(root, item, options.sessionDir)));
272
+ await assertCanonicalMergedTargets(root, changed, options);
273
+ await validate();
274
+ const revalidateTarget = async (target) => {
275
+ await validate();
276
+ const relative = relativeByTarget.get(target);
277
+ if (!relative)
278
+ throw new Error("Unowned merge target.");
279
+ await assertFilesystemTarget(root, relative, options, removedTargets, currentHashes);
280
+ await validate();
281
+ let hash;
282
+ try {
283
+ const stat = await fs.lstat(target);
284
+ if (stat.isDirectory() && removed.has(relative)) {
285
+ if ((await fs.readdir(target)).length)
286
+ throw new Error("Reviewed directory has remaining contents; journal retained for review.");
287
+ }
288
+ else {
289
+ if (!stat.isFile() || stat.nlink > 1)
290
+ throw new Error("Merged transfer target is no longer an independent regular file.");
291
+ hash = createHash("sha256")
292
+ .update(await fs.readFile(target))
293
+ .digest("hex");
294
+ }
295
+ }
296
+ catch (error) {
297
+ if (error.code !== "ENOENT")
298
+ throw error;
299
+ }
300
+ options.signal?.throwIfAborted();
301
+ options.validateMutation?.();
302
+ if (hash !== beforeHashes[relative] && hash !== afterHashes[relative])
303
+ throw new Error("Local content changed at the apply boundary; journal retained, newer bytes untouched.");
304
+ };
305
+ for (const target of plan.deletes) {
306
+ await revalidateTarget(target);
307
+ try {
308
+ const stat = await fs.lstat(target);
309
+ await validate();
310
+ if (stat.isDirectory())
311
+ await fs.rmdir(target); // Only an empty, reviewed directory may be replaced.
312
+ else
313
+ await fs.rm(target, { force: true });
314
+ }
315
+ catch (error) {
316
+ if (error.code !== "ENOENT")
317
+ throw error;
318
+ }
319
+ await syncDirectory(path.dirname(target));
320
+ }
321
+ const requireAbsentDestinations = async () => {
322
+ await validate();
323
+ for (const target of deferredTargets) {
324
+ try {
325
+ await fs.lstat(target);
326
+ }
327
+ catch (error) {
328
+ if (error.code !== "ENOENT")
329
+ throw error;
330
+ continue;
331
+ }
332
+ throw new Error("Case replacement destination changed before queue reservation; journal retained for review.");
333
+ }
334
+ await validate();
335
+ };
336
+ async function acquireDestinations(index) {
337
+ const target = deferredTargets[index];
338
+ if (target)
339
+ return withFileMutationQueue(target, () => acquireDestinations(index + 1));
340
+ // Writers registered after deletion must finish first; never accept their
341
+ // bytes as our own, even if they match a recognizable pre/postimage.
342
+ await requireAbsentDestinations();
343
+ await writeTargets();
344
+ }
345
+ await requireAbsentDestinations();
346
+ await acquireDestinations(0);
347
+ async function writeTargets() {
348
+ for (const item of plan.writes) {
349
+ await validate();
350
+ const relative = relativeByTarget.get(item.target);
351
+ if (!relative)
352
+ throw new Error("Unowned merge write target.");
353
+ await assertFilesystemTarget(root, relative, options, new Set());
354
+ await fs.mkdir(path.dirname(item.target), { recursive: true });
355
+ const temporary = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
356
+ let mode = 0o600;
357
+ try {
358
+ mode = (await fs.stat(item.target)).mode & 0o777;
359
+ }
360
+ catch (error) {
361
+ if (error.code !== "ENOENT")
362
+ throw error;
363
+ }
364
+ try {
365
+ const handle = await fs.open(temporary, "wx", mode);
366
+ try {
367
+ await handle.writeFile(item.content);
368
+ await handle.sync();
369
+ }
370
+ finally {
371
+ await handle.close();
372
+ }
373
+ await revalidateTarget(item.target);
374
+ await fs.rename(temporary, item.target);
375
+ await syncDirectory(path.dirname(item.target));
376
+ }
377
+ finally {
378
+ await fs.rm(temporary, { force: true });
379
+ }
380
+ }
381
+ await syncMutationParents(targets, [root, ...(options.sessionDir ? [sessionStorageRoot(root, options.sessionDir)] : [])], options);
382
+ await validate();
383
+ }
384
+ }
385
+ await acquire(0);
386
+ }
@@ -0,0 +1,31 @@
1
+ import type { RemoteHead } from "../backends/sync-backend.js";
2
+ import type { AnySyncConfig } from "../settings/settings-types.js";
3
+ import type { Snapshot } from "../snapshot/snapshot-types.js";
4
+ import type { PartialProgress } from "./partial-progress.js";
5
+ export interface MergeJournal {
6
+ version: 1;
7
+ identity: string;
8
+ before: Snapshot;
9
+ after: Snapshot;
10
+ accepted?: Snapshot;
11
+ progress?: PartialProgress;
12
+ upload: Snapshot;
13
+ expectedHead: RemoteHead;
14
+ committedHead?: RemoteHead;
15
+ /** No remote publication was attempted; a stale candidate can retire if local preimages remain intact. */
16
+ applyOnly?: boolean;
17
+ backup: string;
18
+ stateIdentity: string;
19
+ /** Effective collection/apply root; absent legacy evidence cannot authorize session recovery. */
20
+ sessionRoot?: string;
21
+ warnings?: string[];
22
+ }
23
+ export declare function mergeJournalIdentity(config: AnySyncConfig, backendIdentity: string): string;
24
+ export declare function mergeJournalPath(config: AnySyncConfig): string;
25
+ export declare function readMergeJournal(config: AnySyncConfig): Promise<MergeJournal | undefined>;
26
+ export declare function writeMergeJournal(config: AnySyncConfig, journal: MergeJournal): Promise<void>;
27
+ export declare function clearMergeJournal(config: AnySyncConfig): Promise<void>;
28
+ export declare function retireMergeJournal(config: AnySyncConfig): Promise<void>;
29
+ export declare function requireNoMergeJournal(config: AnySyncConfig, options?: {
30
+ force?: boolean;
31
+ }): Promise<void>;