@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.29

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 (397) hide show
  1. package/LICENSE +54 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +822 -2
  5. package/dist/ablation.d.ts +2 -0
  6. package/dist/ablation.js +3 -0
  7. package/dist/ablation.js.map +1 -0
  8. package/dist/completion/check.d.ts +64 -0
  9. package/dist/completion/check.js +152 -0
  10. package/dist/completion/check.js.map +1 -0
  11. package/dist/completion/checks.d.ts +45 -0
  12. package/dist/completion/checks.js +173 -0
  13. package/dist/completion/checks.js.map +1 -0
  14. package/dist/completion/flags.d.ts +25 -0
  15. package/dist/completion/flags.js +87 -0
  16. package/dist/completion/flags.js.map +1 -0
  17. package/dist/completion/index.d.ts +8 -0
  18. package/dist/completion/index.js +9 -0
  19. package/dist/completion/index.js.map +1 -0
  20. package/dist/completion/snapshot.d.ts +33 -0
  21. package/dist/completion/snapshot.js +83 -0
  22. package/dist/completion/snapshot.js.map +1 -0
  23. package/dist/context/cap.d.ts +32 -0
  24. package/dist/context/cap.js +50 -0
  25. package/dist/context/cap.js.map +1 -0
  26. package/dist/context/estimate.d.ts +18 -0
  27. package/dist/context/estimate.js +20 -0
  28. package/dist/context/estimate.js.map +1 -0
  29. package/dist/context/file-spill.d.ts +15 -0
  30. package/dist/context/file-spill.js +40 -0
  31. package/dist/context/file-spill.js.map +1 -0
  32. package/dist/context/index.d.ts +10 -0
  33. package/dist/context/index.js +10 -0
  34. package/dist/context/index.js.map +1 -0
  35. package/dist/context/mask.d.ts +27 -0
  36. package/dist/context/mask.js +71 -0
  37. package/dist/context/mask.js.map +1 -0
  38. package/dist/context/mid-turn.d.ts +40 -0
  39. package/dist/context/mid-turn.js +82 -0
  40. package/dist/context/mid-turn.js.map +1 -0
  41. package/dist/context/policy.d.ts +9 -0
  42. package/dist/context/policy.js +140 -0
  43. package/dist/context/policy.js.map +1 -0
  44. package/dist/context/spill-ledger.d.ts +25 -0
  45. package/dist/context/spill-ledger.js +54 -0
  46. package/dist/context/spill-ledger.js.map +1 -0
  47. package/dist/context/spill.d.ts +10 -0
  48. package/dist/context/spill.js +18 -0
  49. package/dist/context/spill.js.map +1 -0
  50. package/dist/context/summarize.d.ts +53 -0
  51. package/dist/context/summarize.js +204 -0
  52. package/dist/context/summarize.js.map +1 -0
  53. package/dist/context/summary-template.d.ts +29 -0
  54. package/dist/context/summary-template.js +69 -0
  55. package/dist/context/summary-template.js.map +1 -0
  56. package/dist/context/types.d.ts +150 -0
  57. package/dist/context/types.js +2 -0
  58. package/dist/context/types.js.map +1 -0
  59. package/dist/context/write-cap.d.ts +19 -0
  60. package/dist/context/write-cap.js +41 -0
  61. package/dist/context/write-cap.js.map +1 -0
  62. package/dist/create-harness.d.ts +7 -0
  63. package/dist/create-harness.js +21 -0
  64. package/dist/create-harness.js.map +1 -0
  65. package/dist/credentials/addresses.d.ts +14 -0
  66. package/dist/credentials/addresses.js +144 -0
  67. package/dist/credentials/addresses.js.map +1 -0
  68. package/dist/credentials/allowlist.d.ts +54 -0
  69. package/dist/credentials/allowlist.js +134 -0
  70. package/dist/credentials/allowlist.js.map +1 -0
  71. package/dist/credentials/egress-policy.d.ts +69 -0
  72. package/dist/credentials/egress-policy.js +170 -0
  73. package/dist/credentials/egress-policy.js.map +1 -0
  74. package/dist/credentials/egress-proxy.d.ts +82 -0
  75. package/dist/credentials/egress-proxy.js +650 -0
  76. package/dist/credentials/egress-proxy.js.map +1 -0
  77. package/dist/credentials/git-route.d.ts +68 -0
  78. package/dist/credentials/git-route.js +288 -0
  79. package/dist/credentials/git-route.js.map +1 -0
  80. package/dist/credentials/index.d.ts +13 -0
  81. package/dist/credentials/index.js +14 -0
  82. package/dist/credentials/index.js.map +1 -0
  83. package/dist/credentials/scrub.d.ts +23 -0
  84. package/dist/credentials/scrub.js +115 -0
  85. package/dist/credentials/scrub.js.map +1 -0
  86. package/dist/errors.d.ts +60 -0
  87. package/dist/errors.js +67 -0
  88. package/dist/errors.js.map +1 -0
  89. package/dist/extensions/compose.d.ts +27 -0
  90. package/dist/extensions/compose.js +83 -0
  91. package/dist/extensions/compose.js.map +1 -0
  92. package/dist/extensions/context-files-node.d.ts +28 -0
  93. package/dist/extensions/context-files-node.js +74 -0
  94. package/dist/extensions/context-files-node.js.map +1 -0
  95. package/dist/extensions/context-files.d.ts +68 -0
  96. package/dist/extensions/context-files.js +214 -0
  97. package/dist/extensions/context-files.js.map +1 -0
  98. package/dist/extensions/digest.d.ts +6 -0
  99. package/dist/extensions/digest.js +68 -0
  100. package/dist/extensions/digest.js.map +1 -0
  101. package/dist/extensions/index.d.ts +10 -0
  102. package/dist/extensions/index.js +10 -0
  103. package/dist/extensions/index.js.map +1 -0
  104. package/dist/extensions/load.d.ts +42 -0
  105. package/dist/extensions/load.js +211 -0
  106. package/dist/extensions/load.js.map +1 -0
  107. package/dist/extensions/lock.d.ts +8 -0
  108. package/dist/extensions/lock.js +95 -0
  109. package/dist/extensions/lock.js.map +1 -0
  110. package/dist/extensions/node.d.ts +10 -0
  111. package/dist/extensions/node.js +11 -0
  112. package/dist/extensions/node.js.map +1 -0
  113. package/dist/extensions/project-dirs.d.ts +24 -0
  114. package/dist/extensions/project-dirs.js +97 -0
  115. package/dist/extensions/project-dirs.js.map +1 -0
  116. package/dist/extensions/skills-node.d.ts +34 -0
  117. package/dist/extensions/skills-node.js +123 -0
  118. package/dist/extensions/skills-node.js.map +1 -0
  119. package/dist/extensions/skills.d.ts +51 -0
  120. package/dist/extensions/skills.js +175 -0
  121. package/dist/extensions/skills.js.map +1 -0
  122. package/dist/extensions/trust-file.d.ts +3 -0
  123. package/dist/extensions/trust-file.js +62 -0
  124. package/dist/extensions/trust-file.js.map +1 -0
  125. package/dist/extensions/trust-store-node.d.ts +10 -0
  126. package/dist/extensions/trust-store-node.js +33 -0
  127. package/dist/extensions/trust-store-node.js.map +1 -0
  128. package/dist/extensions/types.d.ts +42 -0
  129. package/dist/extensions/types.js +2 -0
  130. package/dist/extensions/types.js.map +1 -0
  131. package/dist/harness.d.ts +156 -0
  132. package/dist/harness.js +2 -0
  133. package/dist/harness.js.map +1 -0
  134. package/dist/index.d.ts +4 -0
  135. package/dist/index.js +5 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/mcp/connection.d.ts +22 -0
  138. package/dist/mcp/connection.js +267 -0
  139. package/dist/mcp/connection.js.map +1 -0
  140. package/dist/mcp/content.d.ts +27 -0
  141. package/dist/mcp/content.js +177 -0
  142. package/dist/mcp/content.js.map +1 -0
  143. package/dist/mcp/errors.d.ts +19 -0
  144. package/dist/mcp/errors.js +21 -0
  145. package/dist/mcp/errors.js.map +1 -0
  146. package/dist/mcp/index.d.ts +10 -0
  147. package/dist/mcp/index.js +10 -0
  148. package/dist/mcp/index.js.map +1 -0
  149. package/dist/mcp/manager.d.ts +7 -0
  150. package/dist/mcp/manager.js +173 -0
  151. package/dist/mcp/manager.js.map +1 -0
  152. package/dist/mcp/record.d.ts +7 -0
  153. package/dist/mcp/record.js +20 -0
  154. package/dist/mcp/record.js.map +1 -0
  155. package/dist/mcp/stdio.d.ts +39 -0
  156. package/dist/mcp/stdio.js +382 -0
  157. package/dist/mcp/stdio.js.map +1 -0
  158. package/dist/mcp/types.d.ts +172 -0
  159. package/dist/mcp/types.js +2 -0
  160. package/dist/mcp/types.js.map +1 -0
  161. package/dist/memory/index.d.ts +2 -0
  162. package/dist/memory/index.js +3 -0
  163. package/dist/memory/index.js.map +1 -0
  164. package/dist/permissions/default-rules.d.ts +7 -0
  165. package/dist/permissions/default-rules.js +42 -0
  166. package/dist/permissions/default-rules.js.map +1 -0
  167. package/dist/permissions/errors.d.ts +11 -0
  168. package/dist/permissions/errors.js +14 -0
  169. package/dist/permissions/errors.js.map +1 -0
  170. package/dist/permissions/index.d.ts +9 -0
  171. package/dist/permissions/index.js +9 -0
  172. package/dist/permissions/index.js.map +1 -0
  173. package/dist/permissions/match.d.ts +33 -0
  174. package/dist/permissions/match.js +287 -0
  175. package/dist/permissions/match.js.map +1 -0
  176. package/dist/permissions/pipeline.d.ts +9 -0
  177. package/dist/permissions/pipeline.js +235 -0
  178. package/dist/permissions/pipeline.js.map +1 -0
  179. package/dist/permissions/rules.d.ts +22 -0
  180. package/dist/permissions/rules.js +74 -0
  181. package/dist/permissions/rules.js.map +1 -0
  182. package/dist/permissions/shadow.d.ts +5 -0
  183. package/dist/permissions/shadow.js +22 -0
  184. package/dist/permissions/shadow.js.map +1 -0
  185. package/dist/permissions/types.d.ts +104 -0
  186. package/dist/permissions/types.js +2 -0
  187. package/dist/permissions/types.js.map +1 -0
  188. package/dist/sandbox/base.d.ts +45 -0
  189. package/dist/sandbox/base.js +74 -0
  190. package/dist/sandbox/base.js.map +1 -0
  191. package/dist/sandbox/docker/index.d.ts +41 -0
  192. package/dist/sandbox/docker/index.js +497 -0
  193. package/dist/sandbox/docker/index.js.map +1 -0
  194. package/dist/sandbox/errors.d.ts +44 -0
  195. package/dist/sandbox/errors.js +57 -0
  196. package/dist/sandbox/errors.js.map +1 -0
  197. package/dist/sandbox/host-files.d.ts +65 -0
  198. package/dist/sandbox/host-files.js +258 -0
  199. package/dist/sandbox/host-files.js.map +1 -0
  200. package/dist/sandbox/index.d.ts +10 -0
  201. package/dist/sandbox/index.js +10 -0
  202. package/dist/sandbox/index.js.map +1 -0
  203. package/dist/sandbox/none.d.ts +17 -0
  204. package/dist/sandbox/none.js +108 -0
  205. package/dist/sandbox/none.js.map +1 -0
  206. package/dist/sandbox/policy.d.ts +49 -0
  207. package/dist/sandbox/policy.js +149 -0
  208. package/dist/sandbox/policy.js.map +1 -0
  209. package/dist/sandbox/process.d.ts +61 -0
  210. package/dist/sandbox/process.js +253 -0
  211. package/dist/sandbox/process.js.map +1 -0
  212. package/dist/sandbox/spawn-env.d.ts +20 -0
  213. package/dist/sandbox/spawn-env.js +128 -0
  214. package/dist/sandbox/spawn-env.js.map +1 -0
  215. package/dist/sandbox/srt/index.d.ts +38 -0
  216. package/dist/sandbox/srt/index.js +283 -0
  217. package/dist/sandbox/srt/index.js.map +1 -0
  218. package/dist/sandbox/srt/settings.d.ts +60 -0
  219. package/dist/sandbox/srt/settings.js +84 -0
  220. package/dist/sandbox/srt/settings.js.map +1 -0
  221. package/dist/sandbox/types.d.ts +125 -0
  222. package/dist/sandbox/types.js +6 -0
  223. package/dist/sandbox/types.js.map +1 -0
  224. package/dist/server/answers.d.ts +16 -0
  225. package/dist/server/answers.js +43 -0
  226. package/dist/server/answers.js.map +1 -0
  227. package/dist/server/connection.d.ts +99 -0
  228. package/dist/server/connection.js +309 -0
  229. package/dist/server/connection.js.map +1 -0
  230. package/dist/server/dispatcher.d.ts +86 -0
  231. package/dist/server/dispatcher.js +800 -0
  232. package/dist/server/dispatcher.js.map +1 -0
  233. package/dist/server/index.d.ts +13 -0
  234. package/dist/server/index.js +12 -0
  235. package/dist/server/index.js.map +1 -0
  236. package/dist/server/local-transport.d.ts +44 -0
  237. package/dist/server/local-transport.js +103 -0
  238. package/dist/server/local-transport.js.map +1 -0
  239. package/dist/server/outbox.d.ts +31 -0
  240. package/dist/server/outbox.js +130 -0
  241. package/dist/server/outbox.js.map +1 -0
  242. package/dist/server/params.d.ts +25 -0
  243. package/dist/server/params.js +112 -0
  244. package/dist/server/params.js.map +1 -0
  245. package/dist/server/protocol.schema.json +2448 -0
  246. package/dist/server/rpc-session.d.ts +43 -0
  247. package/dist/server/rpc-session.js +167 -0
  248. package/dist/server/rpc-session.js.map +1 -0
  249. package/dist/server/stdio-streams.d.ts +67 -0
  250. package/dist/server/stdio-streams.js +218 -0
  251. package/dist/server/stdio-streams.js.map +1 -0
  252. package/dist/server/stdio.d.ts +59 -0
  253. package/dist/server/stdio.js +189 -0
  254. package/dist/server/stdio.js.map +1 -0
  255. package/dist/server/websocket.d.ts +106 -0
  256. package/dist/server/websocket.js +327 -0
  257. package/dist/server/websocket.js.map +1 -0
  258. package/dist/session/approvals.d.ts +81 -0
  259. package/dist/session/approvals.js +217 -0
  260. package/dist/session/approvals.js.map +1 -0
  261. package/dist/session/code-call-log.d.ts +42 -0
  262. package/dist/session/code-call-log.js +63 -0
  263. package/dist/session/code-call-log.js.map +1 -0
  264. package/dist/session/code-call-result.d.ts +19 -0
  265. package/dist/session/code-call-result.js +95 -0
  266. package/dist/session/code-call-result.js.map +1 -0
  267. package/dist/session/code-call.d.ts +49 -0
  268. package/dist/session/code-call.js +345 -0
  269. package/dist/session/code-call.js.map +1 -0
  270. package/dist/session/effect-scope.d.ts +11 -0
  271. package/dist/session/effect-scope.js +10 -0
  272. package/dist/session/effect-scope.js.map +1 -0
  273. package/dist/session/errors.d.ts +19 -0
  274. package/dist/session/errors.js +27 -0
  275. package/dist/session/errors.js.map +1 -0
  276. package/dist/session/file-index.d.ts +8 -0
  277. package/dist/session/file-index.js +70 -0
  278. package/dist/session/file-index.js.map +1 -0
  279. package/dist/session/file-key-store.d.ts +16 -0
  280. package/dist/session/file-key-store.js +169 -0
  281. package/dist/session/file-key-store.js.map +1 -0
  282. package/dist/session/file-lock.d.ts +52 -0
  283. package/dist/session/file-lock.js +324 -0
  284. package/dist/session/file-lock.js.map +1 -0
  285. package/dist/session/index.d.ts +22 -0
  286. package/dist/session/index.js +20 -0
  287. package/dist/session/index.js.map +1 -0
  288. package/dist/session/jsonl-store.d.ts +37 -0
  289. package/dist/session/jsonl-store.js +386 -0
  290. package/dist/session/jsonl-store.js.map +1 -0
  291. package/dist/session/jsonl.d.ts +9 -0
  292. package/dist/session/jsonl.js +10 -0
  293. package/dist/session/jsonl.js.map +1 -0
  294. package/dist/session/lock.d.ts +19 -0
  295. package/dist/session/lock.js +2 -0
  296. package/dist/session/lock.js.map +1 -0
  297. package/dist/session/memory-store.d.ts +12 -0
  298. package/dist/session/memory-store.js +60 -0
  299. package/dist/session/memory-store.js.map +1 -0
  300. package/dist/session/migrate.d.ts +41 -0
  301. package/dist/session/migrate.js +86 -0
  302. package/dist/session/migrate.js.map +1 -0
  303. package/dist/session/pointer.d.ts +15 -0
  304. package/dist/session/pointer.js +22 -0
  305. package/dist/session/pointer.js.map +1 -0
  306. package/dist/session/rebuild.d.ts +53 -0
  307. package/dist/session/rebuild.js +230 -0
  308. package/dist/session/rebuild.js.map +1 -0
  309. package/dist/session/resume.d.ts +26 -0
  310. package/dist/session/resume.js +128 -0
  311. package/dist/session/resume.js.map +1 -0
  312. package/dist/session/retention.d.ts +97 -0
  313. package/dist/session/retention.js +702 -0
  314. package/dist/session/retention.js.map +1 -0
  315. package/dist/session/runner.d.ts +156 -0
  316. package/dist/session/runner.js +656 -0
  317. package/dist/session/runner.js.map +1 -0
  318. package/dist/session/scheduler.d.ts +47 -0
  319. package/dist/session/scheduler.js +85 -0
  320. package/dist/session/scheduler.js.map +1 -0
  321. package/dist/session/secret-key-store.d.ts +47 -0
  322. package/dist/session/secret-key-store.js +79 -0
  323. package/dist/session/secret-key-store.js.map +1 -0
  324. package/dist/session/session.d.ts +106 -0
  325. package/dist/session/session.js +353 -0
  326. package/dist/session/session.js.map +1 -0
  327. package/dist/session/sticky.d.ts +48 -0
  328. package/dist/session/sticky.js +232 -0
  329. package/dist/session/sticky.js.map +1 -0
  330. package/dist/session/store.d.ts +108 -0
  331. package/dist/session/store.js +163 -0
  332. package/dist/session/store.js.map +1 -0
  333. package/dist/telemetry/index.d.ts +2 -0
  334. package/dist/telemetry/index.js +3 -0
  335. package/dist/telemetry/index.js.map +1 -0
  336. package/dist/testing/fake-sandbox.d.ts +52 -0
  337. package/dist/testing/fake-sandbox.js +370 -0
  338. package/dist/testing/fake-sandbox.js.map +1 -0
  339. package/dist/testing/index.d.ts +10 -0
  340. package/dist/testing/index.js +11 -0
  341. package/dist/testing/index.js.map +1 -0
  342. package/dist/testing/key-store-conformance.d.ts +22 -0
  343. package/dist/testing/key-store-conformance.js +97 -0
  344. package/dist/testing/key-store-conformance.js.map +1 -0
  345. package/dist/testing/run-cases.d.ts +21 -0
  346. package/dist/testing/run-cases.js +20 -0
  347. package/dist/testing/run-cases.js.map +1 -0
  348. package/dist/testing/sandbox-conformance.d.ts +64 -0
  349. package/dist/testing/sandbox-conformance.js +468 -0
  350. package/dist/testing/sandbox-conformance.js.map +1 -0
  351. package/dist/testing/scheduler-conformance.d.ts +32 -0
  352. package/dist/testing/scheduler-conformance.js +72 -0
  353. package/dist/testing/scheduler-conformance.js.map +1 -0
  354. package/dist/testing/store-conformance.d.ts +21 -0
  355. package/dist/testing/store-conformance.js +320 -0
  356. package/dist/testing/store-conformance.js.map +1 -0
  357. package/dist/tools/builtins/bash.d.ts +9 -0
  358. package/dist/tools/builtins/bash.js +75 -0
  359. package/dist/tools/builtins/bash.js.map +1 -0
  360. package/dist/tools/builtins/builtins.d.ts +38 -0
  361. package/dist/tools/builtins/builtins.js +48 -0
  362. package/dist/tools/builtins/builtins.js.map +1 -0
  363. package/dist/tools/builtins/descriptions.d.ts +69 -0
  364. package/dist/tools/builtins/descriptions.js +94 -0
  365. package/dist/tools/builtins/descriptions.js.map +1 -0
  366. package/dist/tools/builtins/fetch.d.ts +12 -0
  367. package/dist/tools/builtins/fetch.js +157 -0
  368. package/dist/tools/builtins/fetch.js.map +1 -0
  369. package/dist/tools/builtins/files.d.ts +27 -0
  370. package/dist/tools/builtins/files.js +274 -0
  371. package/dist/tools/builtins/files.js.map +1 -0
  372. package/dist/tools/builtins/paths.d.ts +30 -0
  373. package/dist/tools/builtins/paths.js +62 -0
  374. package/dist/tools/builtins/paths.js.map +1 -0
  375. package/dist/tools/builtins/results.d.ts +15 -0
  376. package/dist/tools/builtins/results.js +31 -0
  377. package/dist/tools/builtins/results.js.map +1 -0
  378. package/dist/tools/builtins/search.d.ts +18 -0
  379. package/dist/tools/builtins/search.js +217 -0
  380. package/dist/tools/builtins/search.js.map +1 -0
  381. package/dist/tools/errors.d.ts +13 -0
  382. package/dist/tools/errors.js +17 -0
  383. package/dist/tools/errors.js.map +1 -0
  384. package/dist/tools/index.d.ts +12 -0
  385. package/dist/tools/index.js +11 -0
  386. package/dist/tools/index.js.map +1 -0
  387. package/dist/tools/registry.d.ts +3 -0
  388. package/dist/tools/registry.js +234 -0
  389. package/dist/tools/registry.js.map +1 -0
  390. package/dist/tools/tool-search.d.ts +30 -0
  391. package/dist/tools/tool-search.js +118 -0
  392. package/dist/tools/tool-search.js.map +1 -0
  393. package/dist/tools/types.d.ts +106 -0
  394. package/dist/tools/types.js +2 -0
  395. package/dist/tools/types.js.map +1 -0
  396. package/llms.txt +469 -0
  397. package/package.json +118 -3
@@ -0,0 +1,702 @@
1
+ /**
2
+ * Retention for a `jsonlStore()` folder. Nothing is ever deleted unless the caller sets a retention period: an expired
3
+ * session is then gzipped into `.archive/`, where the store still lists and loads it, or deleted with its pointer. The
4
+ * code only runs when a caller asks, either through `pruneSessions()` or when the store first touches a user, and never
5
+ * on a timer. Every doubt resolves to keeping a file: a file the run cannot read, a session it cannot date and a session
6
+ * that a surviving one continues are all left where they are.
7
+ */
8
+ import { Buffer } from "node:buffer";
9
+ import { randomUUID } from "node:crypto";
10
+ import { mkdir, open, readdir, readFile, rename, rm, stat } from "node:fs/promises";
11
+ import { join } from "node:path";
12
+ import { promisify } from "node:util";
13
+ import { gunzip as gunzipCallback, gzip as gzipCallback } from "node:zlib";
14
+ import { HarnessError, isHarnessError } from "../errors.js";
15
+ import { isDerivedFile } from "./session.js";
16
+ import { checkKey, encodeName } from "./store.js";
17
+ const gunzip = promisify(gunzipCallback);
18
+ const gzip = promisify(gzipCallback);
19
+ /**
20
+ * The folder under the store's folder that holds archived sessions, one folder per user. `encodeName()` encodes every
21
+ * `.`, so no user's folder can have this name.
22
+ */
23
+ export const ARCHIVE_DIR = ".archive";
24
+ /** The extension of an archived file: the session file's `.jsonl`, gzipped. */
25
+ export const ARCHIVE_EXTENSION = ".jsonl.gz";
26
+ const LIVE_EXTENSION = ".jsonl";
27
+ const POINTER_EXTENSION = ".pointer.json";
28
+ const DAY_MS = 86_400_000;
29
+ // How much of a live file one read takes, while the run looks for its first and last lines.
30
+ const CHUNK_BYTES = 64 * 1024;
31
+ // An archive never changes in place, so what it holds is kept by path, size, time and inode; this bounds the memory.
32
+ const MAX_CACHED_ARCHIVES = 1024;
33
+ /** Throws a `HarnessError` with code `invalid_retention` unless `days` is a positive finite number and `action` is known. */
34
+ export function checkRetention(retention) {
35
+ if (!Number.isFinite(retention?.days) || retention.days <= 0) {
36
+ throw new HarnessError("invalid_retention", "retention.days must be a positive number");
37
+ }
38
+ if (retention.action !== "archive" && retention.action !== "purge") {
39
+ throw new HarnessError("invalid_retention", 'retention.action must be "archive" or "purge"');
40
+ }
41
+ }
42
+ /** Where a session file's archive is. */
43
+ export const archivePath = (dir, userId, file) => join(dir, ARCHIVE_DIR, encodeName(userId), `${encodeName(file)}${ARCHIVE_EXTENSION}`);
44
+ /** The bytes of an archived file, or `undefined` when there is none. */
45
+ export async function readArchive(path) {
46
+ let packed;
47
+ try {
48
+ packed = await readFile(path);
49
+ }
50
+ catch (error) {
51
+ if (error.code === "ENOENT")
52
+ return undefined;
53
+ throw error;
54
+ }
55
+ try {
56
+ return await gunzip(packed);
57
+ }
58
+ catch (error) {
59
+ throw new HarnessError("session_corrupt", `${path} is not a readable archive`, { cause: error });
60
+ }
61
+ }
62
+ const isMissing = (error) => error?.code === "ENOENT";
63
+ /** A file's bytes, or `undefined` when it is gone, so a file deleted while the run goes on is simply not there. */
64
+ async function readIfThere(path) {
65
+ try {
66
+ return await readFile(path);
67
+ }
68
+ catch (error) {
69
+ if (isMissing(error))
70
+ return undefined;
71
+ throw error;
72
+ }
73
+ }
74
+ async function flushFile(path) {
75
+ const handle = await open(path, "r");
76
+ try {
77
+ await handle.sync();
78
+ }
79
+ finally {
80
+ await handle.close();
81
+ }
82
+ }
83
+ /** Writes `data` to `path` through a temp file and a rename, flushed, so a crash leaves the old file or the new. */
84
+ async function writeAtomically(path, data) {
85
+ await mkdir(join(path, ".."), { recursive: true });
86
+ const temp = `${path}.${randomUUID()}.tmp`;
87
+ try {
88
+ const handle = await open(temp, "wx");
89
+ try {
90
+ await handle.writeFile(data);
91
+ await handle.sync();
92
+ }
93
+ finally {
94
+ await handle.close();
95
+ }
96
+ await rename(temp, path);
97
+ }
98
+ catch (error) {
99
+ await rm(temp, { force: true });
100
+ throw error;
101
+ }
102
+ await flushFile(join(path, "..")).catch(() => undefined);
103
+ }
104
+ /** Moves a file's archive back to its place, for a session that is written again. Returns whether there was one. */
105
+ export async function restoreArchive(dir, userId, file, live) {
106
+ const archived = archivePath(dir, userId, file);
107
+ const bytes = await readArchive(archived);
108
+ if (bytes === undefined)
109
+ return false;
110
+ await writeAtomically(live, bytes);
111
+ await rm(archived, { force: true });
112
+ return true;
113
+ }
114
+ /** The edges of a whole file's bytes, or `undefined` for a file with no complete line, which was never acknowledged. */
115
+ function edgesOf(bytes) {
116
+ const firstEnd = bytes.indexOf(0x0a);
117
+ if (firstEnd < 0)
118
+ return undefined;
119
+ const end = bytes.lastIndexOf(0x0a);
120
+ const start = end === firstEnd ? 0 : bytes.lastIndexOf(0x0a, end - 1) + 1;
121
+ return { first: bytes.subarray(0, firstEnd), last: bytes.subarray(start, end) };
122
+ }
123
+ /** Reads up to `length` bytes at `position`, fewer when the file is shorter. */
124
+ async function readAt(handle, position, length) {
125
+ const buffer = Buffer.alloc(length);
126
+ const { bytesRead } = await handle.read(buffer, 0, length, position);
127
+ return buffer.subarray(0, bytesRead);
128
+ }
129
+ /** The position of the last newline before `before`, or -1, read backwards a chunk at a time. */
130
+ async function newlineBefore(handle, before) {
131
+ for (let end = before; end > 0; end -= CHUNK_BYTES) {
132
+ const start = Math.max(0, end - CHUNK_BYTES);
133
+ const at = (await readAt(handle, start, end - start)).lastIndexOf(0x0a);
134
+ if (at >= 0)
135
+ return start + at;
136
+ }
137
+ return -1;
138
+ }
139
+ /**
140
+ * A live file's edges, read from its two ends, so a long log costs two short reads; `"empty"` for a file with no complete
141
+ * line, and `"gone"` for a file that is not there. The bytes past the size the file had when it was opened don't count.
142
+ */
143
+ async function liveEdges(path) {
144
+ let handle;
145
+ try {
146
+ handle = await open(path, "r");
147
+ }
148
+ catch (error) {
149
+ if (isMissing(error))
150
+ return "gone";
151
+ throw error;
152
+ }
153
+ try {
154
+ const { size } = await handle.stat();
155
+ const head = [];
156
+ let firstEnd = -1;
157
+ for (let at = 0; at < size && firstEnd < 0;) {
158
+ const chunk = await readAt(handle, at, Math.min(CHUNK_BYTES, size - at));
159
+ if (chunk.length === 0)
160
+ break;
161
+ const newline = chunk.indexOf(0x0a);
162
+ head.push(newline < 0 ? chunk : chunk.subarray(0, newline));
163
+ if (newline >= 0)
164
+ firstEnd = at + newline;
165
+ at += chunk.length;
166
+ }
167
+ if (firstEnd < 0)
168
+ return "empty";
169
+ const first = Buffer.concat(head);
170
+ const end = await newlineBefore(handle, size);
171
+ if (end <= firstEnd)
172
+ return { first, last: first };
173
+ const start = (await newlineBefore(handle, end)) + 1;
174
+ return { first, last: await readAt(handle, start, end - start) };
175
+ }
176
+ finally {
177
+ await handle.close();
178
+ }
179
+ }
180
+ /** What a file's first and last complete lines say about it. */
181
+ function contentsOf(edges) {
182
+ let header;
183
+ try {
184
+ header = JSON.parse(edges.first.toString("utf8"));
185
+ }
186
+ catch {
187
+ return { kind: "opaque" };
188
+ }
189
+ if (header?.type !== "session_header")
190
+ return { kind: "opaque" };
191
+ // A spawned child's header names the session that started it, but its log does not continue that session's.
192
+ const parent = header.spawn === undefined ? header.parent?.session : undefined;
193
+ let lastAt;
194
+ try {
195
+ const at = Date.parse(String(JSON.parse(edges.last.toString("utf8")).timestamp));
196
+ lastAt = Number.isNaN(at) ? undefined : at;
197
+ }
198
+ catch {
199
+ lastAt = undefined;
200
+ }
201
+ return { kind: "log", lastAt, continues: typeof parent === "string" ? parent : undefined };
202
+ }
203
+ /** The file id that a store-written name holds, or `undefined` for a name the store would not write. */
204
+ function idOf(name, extension) {
205
+ const encoded = name.slice(0, -extension.length);
206
+ try {
207
+ const id = decodeURIComponent(encoded);
208
+ return encodeName(id) === encoded ? id : undefined;
209
+ }
210
+ catch {
211
+ return undefined;
212
+ }
213
+ }
214
+ const listFolder = (folder) => readdir(folder).catch((error) => {
215
+ if (isMissing(error))
216
+ return [];
217
+ throw error;
218
+ });
219
+ const archives = new Map();
220
+ /** What an archived copy holds, unpacked once and then kept while the file keeps its size, time and inode. */
221
+ async function readArchivedCopy(path) {
222
+ const info = await stat(path).catch((error) => {
223
+ if (isMissing(error))
224
+ return undefined;
225
+ throw error;
226
+ });
227
+ if (info === undefined)
228
+ return "gone";
229
+ const cached = archives.get(path);
230
+ if (cached?.size === info.size && cached.mtimeMs === info.mtimeMs && cached.ino === info.ino)
231
+ return cached.copy;
232
+ let copy;
233
+ try {
234
+ const bytes = await readArchive(path);
235
+ copy = bytes === undefined ? "gone" : contentsOrEmpty(edgesOf(bytes));
236
+ }
237
+ catch (error) {
238
+ if (isHarnessError(error) && error.code === "session_corrupt")
239
+ copy = { kind: "opaque" };
240
+ else
241
+ throw error;
242
+ }
243
+ archives.delete(path);
244
+ if (copy !== "gone")
245
+ archives.set(path, { size: info.size, mtimeMs: info.mtimeMs, ino: info.ino, copy });
246
+ const oldest = archives.keys().next().value;
247
+ if (archives.size > MAX_CACHED_ARCHIVES && oldest !== undefined)
248
+ archives.delete(oldest);
249
+ return copy;
250
+ }
251
+ const contentsOrEmpty = (edges) => edges === undefined ? "empty" : contentsOf(edges);
252
+ /** What a file's live or archived copy holds: its contents, `"empty"` with no complete line, or `"gone"` when it went. */
253
+ async function readCopy(path, archived) {
254
+ if (archived)
255
+ return readArchivedCopy(path);
256
+ const edges = await liveEdges(path);
257
+ return edges === "empty" || edges === "gone" ? edges : contentsOf(edges);
258
+ }
259
+ /**
260
+ * Adds one copy of a file to the scan: a name the store would not write is skipped, and a gone file is left out. `stubs`
261
+ * holds the live files with no complete line, by file id, so the archived copy read after them can take them along.
262
+ */
263
+ async function addCopy(found, stubs, folder, name, archived) {
264
+ const path = join(folder, name);
265
+ const id = idOf(name, archived ? ARCHIVE_EXTENSION : LIVE_EXTENSION);
266
+ if (id === undefined) {
267
+ found.skipped.push(path);
268
+ return;
269
+ }
270
+ const known = found.files.get(id);
271
+ if (known !== undefined) {
272
+ // The live copy, read first, decides what the file holds, but a purge removes both copies.
273
+ known.archived = path;
274
+ return;
275
+ }
276
+ const contents = await readCopy(path, archived);
277
+ if (contents === "gone")
278
+ return;
279
+ if (contents === "empty") {
280
+ // A file with no complete line holds nothing. A live one is kept in mind, as its archive, if any, is the file.
281
+ if (!archived)
282
+ stubs.set(id, path);
283
+ return;
284
+ }
285
+ if (contents.kind === "opaque") {
286
+ found.opaque = true;
287
+ found.skipped.push(path);
288
+ }
289
+ const stub = archived ? stubs.get(id) : undefined;
290
+ if (!archived)
291
+ found.files.set(id, { id, live: path, contents });
292
+ else
293
+ found.files.set(id, stub === undefined ? { id, archived: path, contents } : { id, archived: path, stub, contents });
294
+ }
295
+ async function readPointer(path) {
296
+ const text = await readIfThere(path);
297
+ if (text === undefined)
298
+ return undefined;
299
+ try {
300
+ const file = JSON.parse(text.toString("utf8")).file;
301
+ return { file: typeof file === "string" ? file : undefined };
302
+ }
303
+ catch {
304
+ return { file: undefined };
305
+ }
306
+ }
307
+ /** Reads the user's live and archived files and pointers. A file that goes while the run reads it is left out. */
308
+ async function scan(userDir, archiveDir) {
309
+ const found = { files: new Map(), pointers: new Map(), skipped: [], opaque: false };
310
+ const names = await listFolder(userDir);
311
+ const stubs = new Map();
312
+ for (const name of names.filter((entry) => entry.endsWith(LIVE_EXTENSION))) {
313
+ await addCopy(found, stubs, userDir, name, false);
314
+ }
315
+ for (const name of (await listFolder(archiveDir)).filter((entry) => entry.endsWith(ARCHIVE_EXTENSION))) {
316
+ await addCopy(found, stubs, archiveDir, name, true);
317
+ }
318
+ for (const name of names.filter((entry) => entry.endsWith(POINTER_EXTENSION))) {
319
+ const id = idOf(name, POINTER_EXTENSION);
320
+ const pointer = id === undefined ? undefined : await readPointer(join(userDir, name));
321
+ if (id !== undefined && pointer !== undefined)
322
+ found.pointers.set(id, pointer.file);
323
+ }
324
+ return found;
325
+ }
326
+ const continuesOf = (file) => file.contents.kind === "log" ? file.contents.continues : undefined;
327
+ /** Each pointer's chain: the derived file it names, then each derived file that one continues, newest first. */
328
+ function pointerChains(found, owner) {
329
+ const chains = new Map();
330
+ for (const [sessionId, target] of found.pointers) {
331
+ const chain = [];
332
+ for (let at = target; at !== undefined && isDerivedFile(at) && !owner.has(at);) {
333
+ const file = found.files.get(at);
334
+ if (file === undefined)
335
+ break;
336
+ owner.set(at, sessionId);
337
+ chain.push(file);
338
+ at = continuesOf(file);
339
+ }
340
+ chains.set(sessionId, chain);
341
+ }
342
+ return chains;
343
+ }
344
+ /** The session a derived file belongs to, found by walking up the files it continues, and the files on the way. */
345
+ function homeOf(file, found, owner) {
346
+ const path = [file];
347
+ for (let at = continuesOf(file); at !== undefined;) {
348
+ // A first file's id names its session even when the file itself is gone.
349
+ if (!isDerivedFile(at) || owner.has(at))
350
+ return { home: owner.get(at) ?? at, path };
351
+ const next = found.files.get(at);
352
+ if (next === undefined || path.includes(next))
353
+ break;
354
+ path.push(next);
355
+ at = continuesOf(next);
356
+ }
357
+ return { home: undefined, path };
358
+ }
359
+ /** Orders a session's loose files so that each goes before every loose file it continues. */
360
+ function newestFirst(members) {
361
+ const byId = new Map(members.map((file) => [file.id, file]));
362
+ const depth = (file) => {
363
+ let count = 0;
364
+ for (let at = byId.get(continuesOf(file) ?? ""); at !== undefined && count < members.length; count += 1) {
365
+ at = byId.get(continuesOf(at) ?? "");
366
+ }
367
+ return count;
368
+ };
369
+ return members
370
+ .map((file) => ({ file, depth: depth(file) }))
371
+ .sort((a, b) => b.depth - a.depth)
372
+ .map(({ file }) => file);
373
+ }
374
+ /** The derived files no pointer reaches, by the session they continue. A file whose session can't be found is skipped. */
375
+ function looseFiles(found, owner) {
376
+ const loose = new Map();
377
+ for (const file of found.files.values()) {
378
+ if (owner.has(file.id))
379
+ continue;
380
+ const { home, path } = homeOf(file, found, owner);
381
+ if (home === undefined) {
382
+ // A file whose header can't be read is in `skipped` already, from the scan.
383
+ const name = file.live ?? file.archived ?? file.id;
384
+ if (!found.skipped.includes(name))
385
+ found.skipped.push(name);
386
+ continue;
387
+ }
388
+ for (const member of path)
389
+ owner.set(member.id, home);
390
+ loose.set(home, [...(loose.get(home) ?? []), ...path]);
391
+ }
392
+ for (const [id, members] of loose)
393
+ loose.set(id, newestFirst(members));
394
+ return loose;
395
+ }
396
+ /** The newest last entry among the files, or `undefined` when one of them, or the pointer, can't be read. */
397
+ function lastAtOf(files, readablePointer) {
398
+ let lastAt = readablePointer ? Number.NEGATIVE_INFINITY : undefined;
399
+ for (const file of files) {
400
+ const at = file.contents.kind === "log" ? file.contents.lastAt : undefined;
401
+ lastAt = lastAt === undefined || at === undefined ? undefined : Math.max(lastAt, at);
402
+ }
403
+ return lastAt;
404
+ }
405
+ /**
406
+ * Groups the files into sessions. A session owns its first file, the derived files its pointer's chain reaches, and the
407
+ * derived files that continue one of its files. Its files are ordered so that a file goes before the file it continues:
408
+ * the loose files, newest first, then the chain from the file the pointer names, then the first file. A run that stops
409
+ * part-way so never leaves a file whose parent it removed, and every remaining file still continues, through files that
410
+ * remain, the first file, so the next run finds the session again.
411
+ */
412
+ function sessionsOf(found) {
413
+ const owner = new Map();
414
+ const chains = pointerChains(found, owner);
415
+ for (const file of found.files.values())
416
+ if (!isDerivedFile(file.id))
417
+ owner.set(file.id, file.id);
418
+ const loose = looseFiles(found, owner);
419
+ const sessions = new Map();
420
+ for (const id of new Set([...owner.values(), ...found.pointers.keys()])) {
421
+ const first = found.files.get(id);
422
+ const files = [...(loose.get(id) ?? []), ...(chains.get(id) ?? []), ...(first ? [first] : [])];
423
+ const pointer = found.pointers.has(id);
424
+ const lastAt = lastAtOf(files, !pointer || found.pointers.get(id) !== undefined);
425
+ sessions.set(id, { id, files, pointer, lastAt });
426
+ }
427
+ return { sessions, owner };
428
+ }
429
+ /** The sessions whose logs `session` continues: the owners of the files its own files name as parents. */
430
+ function parentsOf(session, owner, sessions) {
431
+ const parents = [];
432
+ for (const file of session.files) {
433
+ const above = continuesOf(file);
434
+ const parent = above === undefined ? undefined : sessions.get(owner.get(above) ?? above);
435
+ if (parent !== undefined && parent !== session && !parents.includes(parent))
436
+ parents.push(parent);
437
+ }
438
+ return parents;
439
+ }
440
+ /** Whether `action` has anything to do to the session: a purge removes any copy or pointer, an archive moves live files. */
441
+ const hasWork = (session, action) => action === "purge"
442
+ ? session.pointer || session.files.length > 0
443
+ : session.files.some((file) => file.live !== undefined);
444
+ const keep = (run, sessionId, reason, error) => {
445
+ run.result.kept.push({ sessionId, reason });
446
+ if (reason === "error")
447
+ run.result.errors.push({ sessionId, error });
448
+ };
449
+ /** Gives up the lock of a session whose work is over, so its writer can open it before the run ends. */
450
+ async function release(run, sessionId) {
451
+ const handle = run.acting.get(sessionId);
452
+ run.acting.delete(sessionId);
453
+ await handle?.release().catch(() => undefined);
454
+ }
455
+ /** Whether a session is to be left alone, can't be judged, or is to be expired. */
456
+ function verdictOf(run, session, cutoff, opaque) {
457
+ if ((session.lastAt !== undefined && session.lastAt >= cutoff) || !hasWork(session, run.action))
458
+ return "fresh";
459
+ return session.lastAt === undefined || (run.action === "purge" && opaque) ? "unreadable" : "expired";
460
+ }
461
+ const isBusy = (run, session) => run.busy(session.id) || session.files.some((file) => run.busy(file.id));
462
+ /** Picks the expired sessions to act on and takes each one's lock, keeping those it can't date, read or lock. */
463
+ async function choose(run, cutoff, opaque) {
464
+ for (const session of run.sessions.values()) {
465
+ const verdict = verdictOf(run, session, cutoff, opaque);
466
+ if (verdict !== "expired") {
467
+ if (verdict === "unreadable")
468
+ keep(run, session.id, "unreadable");
469
+ continue;
470
+ }
471
+ if (isBusy(run, session)) {
472
+ keep(run, session.id, "locked");
473
+ continue;
474
+ }
475
+ try {
476
+ const handle = await run.options.lock?.acquire({ userId: run.options.userId, sessionId: session.id });
477
+ if (handle === "would_block")
478
+ keep(run, session.id, "locked");
479
+ else
480
+ run.acting.set(session.id, handle);
481
+ }
482
+ catch (error) {
483
+ keep(run, session.id, "error", error);
484
+ }
485
+ }
486
+ }
487
+ /**
488
+ * Reads the folder again once the locks are taken, so a session written between the first read and its lock is judged
489
+ * on what it holds now: one that is fresh or unreadable now is let go, and every later decision uses this read.
490
+ */
491
+ async function recheck(run, cutoff) {
492
+ const found = await scan(run.userDir, run.archiveDir);
493
+ ({ sessions: run.sessions, owner: run.owner } = sessionsOf(found));
494
+ for (const path of found.skipped)
495
+ if (!run.result.skipped.includes(path))
496
+ run.result.skipped.push(path);
497
+ for (const id of [...run.acting.keys()]) {
498
+ const session = run.sessions.get(id);
499
+ const verdict = session === undefined ? "fresh" : verdictOf(run, session, cutoff, found.opaque);
500
+ if (verdict === "expired")
501
+ continue;
502
+ if (verdict === "unreadable")
503
+ keep(run, id, "unreadable");
504
+ await release(run, id);
505
+ }
506
+ }
507
+ /**
508
+ * Expires the user's sessions: each one whose last entry is more than `retention.days` old is archived or purged, and
509
+ * with no `retention` nothing happens. A session is a first file, the derived files that continue it and its pointer,
510
+ * and its files count wherever they are, live or archived, so an archived session expires again under a purge.
511
+ *
512
+ * Before anything is removed, the run takes the lock of every session it means to expire, reads the folder again, and
513
+ * decides from that second read which sessions survive: the fresh ones, the locked ones, and the ones it can't read or
514
+ * date. A writer that appended between the first read and the lock is so judged on what it wrote. A purge then keeps
515
+ * every expired session that a survivor continues, directly or through another kept session, and it keeps every
516
+ * session when any file in the user's folder can't be read, because that file could continue any of them. A purge
517
+ * removes a fork before the session it continues, and keeps that session when the fork's removal fails. Each lock is
518
+ * given up as soon as its session is archived, purged or kept. Without `lock`, nothing stops a writer elsewhere from
519
+ * appending to a session while the run moves it, so pass the lock that writers hold.
520
+ *
521
+ * Each archived file is written and read back before its original goes, and a file deleted while the run goes on is
522
+ * not brought back. A session's files go one at a time, newest first, then its first file and then its pointer, so a
523
+ * run that stops part-way leaves a session the next run still finds and finishes. A failure stops only its own session:
524
+ * it is recorded in `errors` and the run goes on.
525
+ */
526
+ export function pruneSessions(options) {
527
+ return expireSessions(options, () => false);
528
+ }
529
+ /**
530
+ * `pruneSessions()` for the store, which passes `busy`: a session with a file that one of the store's own calls is
531
+ * reading or writing is kept as `locked`, so a pass never moves a file under a call that is already past expiry.
532
+ */
533
+ export async function expireSessions(options, busy) {
534
+ const result = { archived: [], purged: [], kept: [], skipped: [], errors: [] };
535
+ const { retention } = options;
536
+ if (retention === undefined)
537
+ return result;
538
+ checkRetention(retention);
539
+ checkKey({ userId: options.userId, sessionId: "-" });
540
+ const userDir = join(options.dir, encodeName(options.userId));
541
+ const archiveDir = join(options.dir, ARCHIVE_DIR, encodeName(options.userId));
542
+ const found = await scan(userDir, archiveDir);
543
+ const { sessions, owner } = sessionsOf(found);
544
+ result.skipped.push(...found.skipped);
545
+ const action = retention.action;
546
+ const run = { options, action, userDir, archiveDir, busy, sessions, owner, result, acting: new Map() };
547
+ const cutoff = (options.now?.() ?? new Date()).getTime() - retention.days * DAY_MS;
548
+ try {
549
+ await choose(run, cutoff, found.opaque);
550
+ if (run.acting.size > 0)
551
+ await recheck(run, cutoff);
552
+ if (retention.action === "archive") {
553
+ for (const id of [...run.acting.keys()]) {
554
+ await attempt(run, id, () => archiveSession(run, id));
555
+ await release(run, id);
556
+ }
557
+ }
558
+ else {
559
+ await purgeAll(run);
560
+ }
561
+ }
562
+ finally {
563
+ for (const id of [...run.acting.keys()])
564
+ await release(run, id);
565
+ }
566
+ return result;
567
+ }
568
+ /** Runs one session's expiry, and records a failure as that session's instead of ending the run. */
569
+ async function attempt(run, sessionId, task) {
570
+ try {
571
+ await task();
572
+ return true;
573
+ }
574
+ catch (error) {
575
+ keep(run, sessionId, "error", error);
576
+ return false;
577
+ }
578
+ }
579
+ /** Takes out of `pending` every session that a survivor continues, directly or through another kept session. */
580
+ function protect(run, pending) {
581
+ const survivors = [...run.sessions.values()].filter((session) => !pending.has(session.id));
582
+ for (let session = survivors.pop(); session !== undefined; session = survivors.pop()) {
583
+ for (const parent of parentsOf(session, run.owner, run.sessions)) {
584
+ if (!pending.delete(parent.id))
585
+ continue;
586
+ keep(run, parent.id, "continued");
587
+ survivors.push(parent);
588
+ }
589
+ }
590
+ }
591
+ /** For each pending session, the pending sessions that continue it. */
592
+ function childrenOf(run, pending) {
593
+ const children = new Map();
594
+ for (const id of pending) {
595
+ for (const parent of parentsOf(run.sessions.get(id), run.owner, run.sessions)) {
596
+ if (pending.has(parent.id))
597
+ children.set(parent.id, [...(children.get(parent.id) ?? []), id]);
598
+ }
599
+ }
600
+ return children;
601
+ }
602
+ /**
603
+ * Purges the chosen sessions, minus those a survivor continues, each fork before the session it continues. Every
604
+ * decision is made before the first file goes, and each session's lock is given up as soon as its own fate is settled:
605
+ * a parent's lock stays held until the parent itself is purged or kept, so no fork of it can start meanwhile.
606
+ */
607
+ async function purgeAll(run) {
608
+ const pending = new Set(run.acting.keys());
609
+ protect(run, pending);
610
+ for (const id of [...run.acting.keys()])
611
+ if (!pending.has(id))
612
+ await release(run, id);
613
+ const children = childrenOf(run, pending);
614
+ const ended = new Map();
615
+ for (let progress = true; progress;) {
616
+ progress = false;
617
+ for (const id of pending) {
618
+ const waiting = children.get(id) ?? [];
619
+ if (!waiting.every((child) => ended.has(child)))
620
+ continue;
621
+ pending.delete(id);
622
+ progress = true;
623
+ // A fork that could not be removed still continues this session, so it stays.
624
+ ended.set(id, await purgeUnlessContinued(run, id, waiting, ended));
625
+ }
626
+ }
627
+ // What is left is a cycle of sessions that continue each other, which only a corrupt folder has.
628
+ for (const id of pending)
629
+ keep(run, id, "continued");
630
+ }
631
+ /** Purges one session once its forks have ended, unless one of them failed to go, and gives up its lock. */
632
+ async function purgeUnlessContinued(run, id, forks, ended) {
633
+ let done = false;
634
+ if (forks.some((fork) => ended.get(fork) === false))
635
+ keep(run, id, "continued");
636
+ else
637
+ done = await attempt(run, id, () => purgeSession(run, run.sessions.get(id)));
638
+ if (done)
639
+ run.result.purged.push(id);
640
+ await release(run, id);
641
+ return done;
642
+ }
643
+ async function purgeSession(run, session) {
644
+ for (const file of session.files) {
645
+ if (file.live !== undefined)
646
+ await rm(file.live, { force: true });
647
+ if (file.stub !== undefined)
648
+ await removeStub(file.stub);
649
+ if (file.archived !== undefined)
650
+ await rm(file.archived, { force: true });
651
+ }
652
+ if (session.pointer)
653
+ await rm(join(run.userDir, `${encodeName(session.id)}${POINTER_EXTENSION}`), { force: true });
654
+ }
655
+ /** Removes a live file that held no complete line when the run read it, and keeps it if a line has landed since. */
656
+ async function removeStub(path) {
657
+ const edges = await liveEdges(path);
658
+ if (edges === "gone")
659
+ return;
660
+ if (edges !== "empty") {
661
+ throw new HarnessError("session_conflict", `${path} was written during the run, so the session was kept`);
662
+ }
663
+ await rm(path, { force: true });
664
+ }
665
+ async function archiveSession(run, sessionId) {
666
+ let moved = false;
667
+ for (const file of run.sessions.get(sessionId).files) {
668
+ if (file.live === undefined)
669
+ continue;
670
+ if (await archiveFile(run.options.dir, run.options.userId, file.id, file.live))
671
+ moved = true;
672
+ }
673
+ if (moved)
674
+ run.result.archived.push(sessionId);
675
+ }
676
+ /**
677
+ * Archives one file and removes the original once the archive reads back to the same bytes. A file that is gone, or
678
+ * that goes while its archive is written, is not archived, so a delete during the run never brings a session back.
679
+ * Returns whether the file was archived.
680
+ */
681
+ async function archiveFile(dir, userId, id, live) {
682
+ const original = await readIfThere(live);
683
+ if (original === undefined)
684
+ return false;
685
+ const target = archivePath(dir, userId, id);
686
+ await writeAtomically(target, await gzip(original));
687
+ if (!(await readArchive(target))?.equals(original)) {
688
+ throw new HarnessError("session_corrupt", `${target} does not match ${live}, so the original was kept`);
689
+ }
690
+ // The archive is written before the original is read again, and a delete removes the original before its archive, so
691
+ // in whichever order the two run, a deleted file leaves no archive behind.
692
+ const again = await readIfThere(live);
693
+ if (again === undefined || !again.equals(original)) {
694
+ await rm(target, { force: true });
695
+ if (again === undefined)
696
+ return false;
697
+ throw new HarnessError("session_corrupt", `${live} changed while it was archived, so the original was kept`);
698
+ }
699
+ await rm(live, { force: true });
700
+ return true;
701
+ }
702
+ //# sourceMappingURL=retention.js.map