@sema-agent/core 7.59.0 → 7.61.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 (643) hide show
  1. package/CHANGELOG.md +1169 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-definition.d.ts +7 -0
  4. package/dist/agents/agent-definition.js +12 -0
  5. package/dist/agents/agent-transcript-tool.d.ts +4 -3
  6. package/dist/agents/agent-transcript-tool.js +4 -2
  7. package/dist/agents/cascade.d.ts +61 -10
  8. package/dist/agents/cascade.js +60 -20
  9. package/dist/agents/child-model-seat.js +6 -3
  10. package/dist/agents/composition-allowance.d.ts +53 -0
  11. package/dist/agents/composition-allowance.js +49 -0
  12. package/dist/agents/composition-placement.d.ts +29 -0
  13. package/dist/agents/composition-placement.js +24 -0
  14. package/dist/agents/cumulative-stats.d.ts +4 -0
  15. package/dist/agents/cumulative-stats.js +3 -1
  16. package/dist/agents/inherited-tool-pool.d.ts +28 -1
  17. package/dist/agents/inherited-tool-pool.js +22 -0
  18. package/dist/agents/list-agents-tool.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.d.ts +1 -1
  20. package/dist/agents/peer-notice-route.js +4 -3
  21. package/dist/agents/peer-notices.d.ts +4 -4
  22. package/dist/agents/peer-notices.js +8 -4
  23. package/dist/agents/peer-session-drain.d.ts +8 -1
  24. package/dist/agents/peer-session-drain.js +36 -7
  25. package/dist/agents/repair-loop.js +16 -6
  26. package/dist/agents/retain-ledger.d.ts +11 -1
  27. package/dist/agents/retain-ledger.js +16 -3
  28. package/dist/agents/roster-store.d.ts +2 -2
  29. package/dist/agents/roster-store.js +8 -3
  30. package/dist/agents/send-message-tool.d.ts +14 -27
  31. package/dist/agents/send-message-tool.js +47 -54
  32. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  33. package/dist/agents/subagent-completion-gate.js +62 -0
  34. package/dist/agents/subagent-steps.d.ts +7 -6
  35. package/dist/agents/subagent.d.ts +52 -28
  36. package/dist/agents/subagent.js +276 -246
  37. package/dist/agents/suspend-guard.d.ts +9 -0
  38. package/dist/agents/suspend-guard.js +4 -0
  39. package/dist/agents/tool-filter.d.ts +1 -3
  40. package/dist/agents/tool-filter.js +4 -12
  41. package/dist/agents/verify.d.ts +41 -14
  42. package/dist/agents/verify.js +37 -27
  43. package/dist/bench/metrics.d.ts +3 -5
  44. package/dist/bench/metrics.js +0 -1
  45. package/dist/brain/anthropic.js +1 -0
  46. package/dist/brain/degrading.js +3 -1
  47. package/dist/brain/errors.d.ts +7 -1
  48. package/dist/brain/errors.js +6 -0
  49. package/dist/brain/failover.js +2 -1
  50. package/dist/brain/open-responses.js +1 -0
  51. package/dist/brain/openai.js +1 -0
  52. package/dist/brain/provider-dialect.d.ts +10 -0
  53. package/dist/brain/provider-dialect.js +13 -2
  54. package/dist/brain/route-adjudicator.js +3 -1
  55. package/dist/brain/status-sink.d.ts +7 -1
  56. package/dist/brain/status-sink.js +6 -0
  57. package/dist/brain/stream-engine.d.ts +3 -0
  58. package/dist/brain/stream-engine.js +4 -0
  59. package/dist/brain/timeout.d.ts +3 -1
  60. package/dist/brain/timeout.js +18 -5
  61. package/dist/core/a2a.d.ts +15 -5
  62. package/dist/core/a2a.js +34 -19
  63. package/dist/core/agent-definition.d.ts +20 -0
  64. package/dist/core/agent-state.d.ts +1 -1
  65. package/dist/core/allow-entry.d.ts +61 -23
  66. package/dist/core/allow-entry.js +134 -39
  67. package/dist/core/artifact-host.d.ts +0 -2
  68. package/dist/core/artifact-host.js +0 -1
  69. package/dist/core/ask-origin.d.ts +79 -0
  70. package/dist/core/ask-origin.js +76 -0
  71. package/dist/core/ask-question.d.ts +19 -13
  72. package/dist/core/ask-question.js +8 -2
  73. package/dist/core/auto-compaction.d.ts +2 -0
  74. package/dist/core/auto-compaction.js +2 -1
  75. package/dist/core/auto-mode-defaults.d.ts +8 -0
  76. package/dist/core/auto-mode-defaults.js +1 -0
  77. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  78. package/dist/core/auto-mode.d.ts +39 -4
  79. package/dist/core/auto-mode.js +66 -17
  80. package/dist/core/background-agent-store.d.ts +17 -6
  81. package/dist/core/background-agent-store.js +15 -13
  82. package/dist/core/background-shell.d.ts +12 -1
  83. package/dist/core/background-shell.js +12 -0
  84. package/dist/core/checkpoint-requirements.d.ts +24 -3
  85. package/dist/core/checkpoint-requirements.js +9 -1
  86. package/dist/core/checkpoint-store.d.ts +86 -32
  87. package/dist/core/checkpoint-store.js +10 -5
  88. package/dist/core/child-clamp-seats.d.ts +3 -2
  89. package/dist/core/child-clamp-seats.js +4 -3
  90. package/dist/core/closest-name.d.ts +13 -0
  91. package/dist/core/closest-name.js +35 -0
  92. package/dist/core/compliance.d.ts +1 -1
  93. package/dist/core/context-settings.js +3 -5
  94. package/dist/core/credential-echo.d.ts +52 -0
  95. package/dist/core/credential-echo.js +65 -0
  96. package/dist/core/credential-vocabulary.d.ts +13 -3
  97. package/dist/core/credential-vocabulary.js +12 -4
  98. package/dist/core/cross-boundary-taint.d.ts +5 -6
  99. package/dist/core/decision-receipt.d.ts +14 -1
  100. package/dist/core/decision-receipt.js +6 -3
  101. package/dist/core/delegation-frames.d.ts +13 -9
  102. package/dist/core/effective-path-target.js +2 -3
  103. package/dist/core/engine-attestation.d.ts +11 -1
  104. package/dist/core/engine-attestation.js +2 -0
  105. package/dist/core/engine-notice.d.ts +106 -32
  106. package/dist/core/file-history-retention.d.ts +8 -0
  107. package/dist/core/file-history-retention.js +14 -11
  108. package/dist/core/file-history-store.d.ts +31 -1
  109. package/dist/core/file-history-store.js +31 -2
  110. package/dist/core/frame-settlement.d.ts +15 -0
  111. package/dist/core/frame-settlement.js +10 -1
  112. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  113. package/dist/core/fs-write-gate-policy.js +8 -7
  114. package/dist/core/gate-fold.js +9 -6
  115. package/dist/core/gate-lanes.js +46 -12
  116. package/dist/core/gate-outcome.d.ts +40 -1
  117. package/dist/core/gate-outcome.js +10 -0
  118. package/dist/core/git-worktree-env.d.ts +7 -3
  119. package/dist/core/git-worktree-env.js +16 -13
  120. package/dist/core/governance-codes.d.ts +19 -3
  121. package/dist/core/governance-codes.js +27 -3
  122. package/dist/core/hands-band-screen.js +0 -1
  123. package/dist/core/hands-band.d.ts +0 -3
  124. package/dist/core/hooks.d.ts +51 -60
  125. package/dist/core/hooks.js +131 -78
  126. package/dist/core/host-floor.js +3 -5
  127. package/dist/core/image-admission.d.ts +145 -52
  128. package/dist/core/image-admission.js +202 -47
  129. package/dist/core/image-downsample.d.ts +36 -69
  130. package/dist/core/image-downsample.js +111 -73
  131. package/dist/core/input-author.d.ts +36 -0
  132. package/dist/core/input-author.js +39 -0
  133. package/dist/core/integer-option.d.ts +21 -0
  134. package/dist/core/integer-option.js +13 -0
  135. package/dist/core/leg-identity.d.ts +62 -0
  136. package/dist/core/leg-identity.js +18 -0
  137. package/dist/core/locked-config.d.ts +55 -3
  138. package/dist/core/locked-config.js +84 -51
  139. package/dist/core/lsp.d.ts +5 -3
  140. package/dist/core/lsp.js +3 -2
  141. package/dist/core/mailbox-store.d.ts +85 -10
  142. package/dist/core/mailbox-store.js +31 -10
  143. package/dist/core/mcp-call-meta.d.ts +2 -2
  144. package/dist/core/mcp-call-meta.js +9 -10
  145. package/dist/core/mcp-connection-pool.d.ts +6 -20
  146. package/dist/core/mcp-connection-pool.js +10 -28
  147. package/dist/core/mcp-failure.d.ts +83 -16
  148. package/dist/core/mcp-failure.js +67 -30
  149. package/dist/core/mcp-host-seat.d.ts +131 -0
  150. package/dist/core/mcp-host-seat.js +305 -0
  151. package/dist/core/mcp-probe.d.ts +7 -2
  152. package/dist/core/mcp-probe.js +9 -4
  153. package/dist/core/mcp-server-link.d.ts +18 -6
  154. package/dist/core/mcp-server-link.js +19 -4
  155. package/dist/core/mcp-server-spec.d.ts +39 -9
  156. package/dist/core/mcp-server-spec.js +55 -21
  157. package/dist/core/mcp-session-end.d.ts +1 -2
  158. package/dist/core/mcp-session-end.js +1 -1
  159. package/dist/core/mcp.d.ts +23 -55
  160. package/dist/core/mcp.js +172 -156
  161. package/dist/core/media-byte-cap.d.ts +21 -46
  162. package/dist/core/media-byte-cap.js +55 -55
  163. package/dist/core/member-group.d.ts +7 -0
  164. package/dist/core/member-group.js +35 -0
  165. package/dist/core/memory-admission.d.ts +23 -6
  166. package/dist/core/memory-admission.js +19 -9
  167. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  168. package/dist/core/memory-engine/consolidation.js +7 -1
  169. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  170. package/dist/core/memory-engine/content-origin.js +21 -3
  171. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  172. package/dist/core/memory-engine/dual-root.js +59 -11
  173. package/dist/core/memory-engine/engine.js +27 -24
  174. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  175. package/dist/core/memory-engine/file-backend.js +35 -15
  176. package/dist/core/memory-engine/index.d.ts +2 -1
  177. package/dist/core/memory-engine/index.js +2 -1
  178. package/dist/core/memory-engine/layout.d.ts +3 -0
  179. package/dist/core/memory-engine/layout.js +13 -3
  180. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  181. package/dist/core/memory-engine/memory-deployment.js +182 -0
  182. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  183. package/dist/core/memory-engine/scope-contract.js +2 -2
  184. package/dist/core/memory-engine/sync-client.d.ts +68 -13
  185. package/dist/core/memory-engine/sync-client.js +147 -18
  186. package/dist/core/memory-engine/sync-report.d.ts +106 -0
  187. package/dist/core/memory-engine/sync-report.js +119 -0
  188. package/dist/core/memory-engine/sync.d.ts +13 -3
  189. package/dist/core/mode-policy.d.ts +15 -7
  190. package/dist/core/mode-policy.js +18 -6
  191. package/dist/core/model-receipt.d.ts +39 -0
  192. package/dist/core/model-receipt.js +139 -0
  193. package/dist/core/mods/agent-stations.d.ts +100 -0
  194. package/dist/core/mods/agent-stations.js +154 -0
  195. package/dist/core/mods/dollar.d.ts +62 -0
  196. package/dist/core/mods/extension-call.d.ts +15 -1
  197. package/dist/core/mods/extension-call.js +7 -2
  198. package/dist/core/mods/kernel/dispatch.d.ts +9 -4
  199. package/dist/core/mods/kernel/dispatch.js +8 -8
  200. package/dist/core/mods/kernel/events.d.ts +13 -4
  201. package/dist/core/mods/kernel/events.js +14 -10
  202. package/dist/core/mods/kernel/receive.d.ts +5 -0
  203. package/dist/core/mods/kernel/receive.js +10 -0
  204. package/dist/core/mods/kernel/registration.d.ts +3 -0
  205. package/dist/core/mods/kernel/registration.js +5 -0
  206. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  207. package/dist/core/mods/kernel/site-rules.js +10 -2
  208. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  209. package/dist/core/mods/lifecycle-stations.js +35 -0
  210. package/dist/core/mods/session-append.d.ts +115 -0
  211. package/dist/core/mods/session-append.js +311 -0
  212. package/dist/core/mods/session-compact.d.ts +48 -0
  213. package/dist/core/mods/session-compact.js +194 -0
  214. package/dist/core/mods/session-receive.d.ts +93 -0
  215. package/dist/core/mods/session-receive.js +141 -0
  216. package/dist/core/mods/session-send.d.ts +72 -0
  217. package/dist/core/mods/session-send.js +88 -0
  218. package/dist/core/mods/stations.d.ts +89 -75
  219. package/dist/core/mods/stations.js +57 -53
  220. package/dist/core/mods/tool-call.d.ts +12 -4
  221. package/dist/core/mods/tool-call.js +32 -16
  222. package/dist/core/mounted-mcp.d.ts +5 -0
  223. package/dist/core/mounted-mcp.js +2 -2
  224. package/dist/core/namespaced-rule-name.d.ts +7 -1
  225. package/dist/core/namespaced-rule-name.js +13 -2
  226. package/dist/core/oracle-isolation.js +1 -1
  227. package/dist/core/output-style.js +3 -4
  228. package/dist/core/own-property-receipt.d.ts +62 -0
  229. package/dist/core/own-property-receipt.js +43 -0
  230. package/dist/core/park-selfcheck.js +12 -10
  231. package/dist/core/path-identity.d.ts +11 -0
  232. package/dist/core/path-identity.js +4 -0
  233. package/dist/core/path-rule-binding.d.ts +3 -1
  234. package/dist/core/path-rule-binding.js +3 -1
  235. package/dist/core/peer-seat.d.ts +66 -11
  236. package/dist/core/peer-seat.js +199 -42
  237. package/dist/core/permission-rule-consent.d.ts +21 -26
  238. package/dist/core/permission-rule-consent.js +22 -3
  239. package/dist/core/permission-rule-model.d.ts +38 -13
  240. package/dist/core/permission-rule-model.js +54 -16
  241. package/dist/core/permission-rule-org.d.ts +1 -1
  242. package/dist/core/permission-rule-provider.js +4 -1
  243. package/dist/core/permission-rules.d.ts +4 -0
  244. package/dist/core/permission-rules.js +11 -16
  245. package/dist/core/protocol-http-auth.d.ts +14 -2
  246. package/dist/core/protocol-http-auth.js +16 -7
  247. package/dist/core/read-face-seats.d.ts +7 -5
  248. package/dist/core/read-face-seats.js +4 -1
  249. package/dist/core/redaction-marks.d.ts +4 -3
  250. package/dist/core/redaction-marks.js +2 -2
  251. package/dist/core/remote-env.d.ts +218 -122
  252. package/dist/core/remote-env.js +133 -14
  253. package/dist/core/retention-policy.d.ts +24 -23
  254. package/dist/core/retention-policy.js +36 -2
  255. package/dist/core/retention.d.ts +4 -1
  256. package/dist/core/retention.js +37 -12
  257. package/dist/core/retired-keys.d.ts +8 -3
  258. package/dist/core/retired-keys.js +4 -1
  259. package/dist/core/rewrite-rejudge.d.ts +12 -5
  260. package/dist/core/rewrite-rejudge.js +9 -5
  261. package/dist/core/roles.d.ts +37 -3
  262. package/dist/core/roles.js +126 -78
  263. package/dist/core/row-admission.d.ts +10 -0
  264. package/dist/core/row-admission.js +5 -0
  265. package/dist/core/rule-owner.d.ts +3 -0
  266. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  267. package/dist/core/runner/advisor-instructions.js +2 -1
  268. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  269. package/dist/core/runner/assemble-result.d.ts +13 -8
  270. package/dist/core/runner/assemble-result.js +12 -8
  271. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  272. package/dist/core/runner/call-hook-stations.js +21 -10
  273. package/dist/core/runner/caller-roster.d.ts +12 -9
  274. package/dist/core/runner/caller-roster.js +5 -2
  275. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  276. package/dist/core/runner/checkpoint-scope.js +21 -0
  277. package/dist/core/runner/child-tree.d.ts +7 -8
  278. package/dist/core/runner/child-tree.js +6 -6
  279. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  280. package/dist/core/runner/classifier-ladder.js +39 -8
  281. package/dist/core/runner/compact-session.js +14 -2
  282. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  283. package/dist/core/runner/compaction-restate.d.ts +2 -2
  284. package/dist/core/runner/compaction-restate.js +4 -3
  285. package/dist/core/runner/construction-doors.d.ts +2 -2
  286. package/dist/core/runner/construction-doors.js +7 -2
  287. package/dist/core/runner/contracts.d.ts +158 -65
  288. package/dist/core/runner/cross-boundary-lane.d.ts +4 -6
  289. package/dist/core/runner/cross-boundary-lane.js +11 -2
  290. package/dist/core/runner/decide-continuation.d.ts +4 -2
  291. package/dist/core/runner/decide-continuation.js +7 -4
  292. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  293. package/dist/core/runner/denial-limit-arms.js +17 -10
  294. package/dist/core/runner/env-capability-census.d.ts +15 -20
  295. package/dist/core/runner/env-capability-census.js +25 -34
  296. package/dist/core/runner/expire-settle.d.ts +44 -0
  297. package/dist/core/runner/expire-settle.js +55 -0
  298. package/dist/core/runner/file-history-request.d.ts +2 -2
  299. package/dist/core/runner/file-history-request.js +0 -8
  300. package/dist/core/runner/gate-exit.d.ts +75 -7
  301. package/dist/core/runner/gate-exit.js +20 -1
  302. package/dist/core/runner/git-status-frame.d.ts +5 -2
  303. package/dist/core/runner/git-status-frame.js +4 -4
  304. package/dist/core/runner/halt-attribution.d.ts +2 -1
  305. package/dist/core/runner/halt-attribution.js +2 -1
  306. package/dist/core/runner/image.d.ts +7 -2
  307. package/dist/core/runner/image.js +14 -8
  308. package/dist/core/runner/inline-image.d.ts +10 -8
  309. package/dist/core/runner/inline-image.js +11 -9
  310. package/dist/core/runner/local-claims.d.ts +17 -0
  311. package/dist/core/runner/local-claims.js +18 -0
  312. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  313. package/dist/core/runner/media-removed-seat.js +88 -0
  314. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  315. package/dist/core/runner/park-commit.d.ts +2 -2
  316. package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
  317. package/dist/core/runner/permission-rule-lanes.js +29 -10
  318. package/dist/core/runner/person-path-rows.js +1 -1
  319. package/dist/core/runner/placement-fence.d.ts +26 -0
  320. package/dist/core/runner/placement-fence.js +38 -0
  321. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  322. package/dist/core/runner/prepare-ask-lane.js +4 -4
  323. package/dist/core/runner/prepare-boundary-parks.d.ts +6 -3
  324. package/dist/core/runner/prepare-boundary-parks.js +4 -4
  325. package/dist/core/runner/prepare-caps-and-workflow.d.ts +6 -0
  326. package/dist/core/runner/prepare-caps-and-workflow.js +5 -3
  327. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  328. package/dist/core/runner/prepare-config-doors.js +30 -26
  329. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  330. package/dist/core/runner/prepare-context-lane.js +13 -13
  331. package/dist/core/runner/prepare-delegation-surface.d.ts +13 -11
  332. package/dist/core/runner/prepare-delegation-surface.js +7 -8
  333. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  334. package/dist/core/runner/prepare-execution-env.js +7 -4
  335. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  336. package/dist/core/runner/prepare-file-history.js +3 -12
  337. package/dist/core/runner/prepare-gate-stations.d.ts +23 -17
  338. package/dist/core/runner/prepare-gate-stations.js +10 -7
  339. package/dist/core/runner/prepare-hands-readface.d.ts +8 -6
  340. package/dist/core/runner/prepare-hands-readface.js +19 -11
  341. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  342. package/dist/core/runner/prepare-inherited-gate.js +12 -5
  343. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  344. package/dist/core/runner/prepare-lsp.js +2 -2
  345. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  346. package/dist/core/runner/prepare-memory.d.ts +2 -2
  347. package/dist/core/runner/prepare-memory.js +2 -2
  348. package/dist/core/runner/prepare-park-ask.d.ts +8 -7
  349. package/dist/core/runner/prepare-park-ask.js +6 -12
  350. package/dist/core/runner/prepare-policy-chain.d.ts +15 -25
  351. package/dist/core/runner/prepare-policy-chain.js +131 -128
  352. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  353. package/dist/core/runner/prepare-project-context.js +8 -5
  354. package/dist/core/runner/prepare-prompt-inputs.d.ts +4 -0
  355. package/dist/core/runner/prepare-prompt-inputs.js +4 -2
  356. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  357. package/dist/core/runner/prepare-protocol-tools.js +9 -2
  358. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  359. package/dist/core/runner/prepare-question-face.js +2 -2
  360. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  361. package/dist/core/runner/prepare-run-refs.js +2 -2
  362. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -9
  363. package/dist/core/runner/prepare-suspend-saga.js +21 -13
  364. package/dist/core/runner/prepare-task.d.ts +1 -1
  365. package/dist/core/runner/prepare-task.js +84 -42
  366. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  367. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  368. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  369. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  370. package/dist/core/runner/prepare-wiring-manifest.d.ts +7 -3
  371. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  372. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  373. package/dist/core/runner/prepare-workspace-restore.js +12 -8
  374. package/dist/core/runner/read-root-grant.d.ts +1 -1
  375. package/dist/core/runner/read-root-grant.js +2 -1
  376. package/dist/core/runner/resume-admission.d.ts +5 -3
  377. package/dist/core/runner/resume-admission.js +17 -3
  378. package/dist/core/runner/resume-apply.js +3 -1
  379. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  380. package/dist/core/runner/resume-claim.d.ts +8 -3
  381. package/dist/core/runner/resume-claim.js +28 -12
  382. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  383. package/dist/core/runner/resume-internals-and-config.js +10 -1
  384. package/dist/core/runner/resume-preflight.d.ts +3 -2
  385. package/dist/core/runner/resume-preflight.js +13 -26
  386. package/dist/core/runner/retired-runner-deps.js +6 -1
  387. package/dist/core/runner/run-attachment-seats.js +3 -3
  388. package/dist/core/runner/run-brain-sinks.js +1 -0
  389. package/dist/core/runner/run-git-lane.d.ts +3 -1
  390. package/dist/core/runner/run-git-lane.js +3 -2
  391. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  392. package/dist/core/runner/run-harness-handlers.js +5 -3
  393. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  394. package/dist/core/runner/run-identity-wiring.js +15 -6
  395. package/dist/core/runner/run-leg.d.ts +3 -3
  396. package/dist/core/runner/run-leg.js +65 -56
  397. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  398. package/dist/core/runner/run-notification-lane.js +36 -12
  399. package/dist/core/runner/run-recovery-lanes.js +3 -2
  400. package/dist/core/runner/run-settle-and-teardown.js +14 -8
  401. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  402. package/dist/core/runner/run-stop-and-final-verify.js +12 -4
  403. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  404. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  405. package/dist/core/runner/run-terminal-adoption.js +26 -17
  406. package/dist/core/runner/run-turn-boundary.js +37 -19
  407. package/dist/core/runner/runtask.d.ts +25 -7
  408. package/dist/core/runner/runtask.js +46 -22
  409. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  410. package/dist/core/runner/session-rule-policy.js +6 -1
  411. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  412. package/dist/core/runner/skills-seat.js +2 -2
  413. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  414. package/dist/core/runner/stream-halt-verbs.js +4 -3
  415. package/dist/core/runner/stream-reap.d.ts +7 -6
  416. package/dist/core/runner/stream-reap.js +13 -16
  417. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  418. package/dist/core/runner/stream-settle-backstop.js +5 -3
  419. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  420. package/dist/core/runner/stream-steer-verb.js +8 -7
  421. package/dist/core/runner/sub-agent-deny-lists.js +10 -7
  422. package/dist/core/runner/synthetic-tools.js +2 -2
  423. package/dist/core/runner/terminal-account.d.ts +11 -1
  424. package/dist/core/runner/terminal-account.js +20 -0
  425. package/dist/core/runner/terminal-projection.d.ts +8 -2
  426. package/dist/core/runner/terminal-projection.js +2 -2
  427. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  428. package/dist/core/runner/tool-disclosure.js +5 -4
  429. package/dist/core/runner/tool-end-body.d.ts +3 -3
  430. package/dist/core/runner/tool-end-body.js +1 -1
  431. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  432. package/dist/core/runner/tool-face-overlay.js +26 -19
  433. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  434. package/dist/core/runner/tool-output-projection.js +7 -6
  435. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  436. package/dist/core/runner/tool-result-media-seat.js +17 -1
  437. package/dist/core/runner/tool-table-view.d.ts +56 -0
  438. package/dist/core/runner/tool-table-view.js +51 -0
  439. package/dist/core/runner/turn-attachments.d.ts +6 -7
  440. package/dist/core/runner/turn-attachments.js +4 -17
  441. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  442. package/dist/core/runner/void-verifier-pause.js +41 -0
  443. package/dist/core/runner-deps.d.ts +55 -43
  444. package/dist/core/secret-env.d.ts +14 -13
  445. package/dist/core/secret-env.js +8 -9
  446. package/dist/core/session-log-transfer.js +9 -10
  447. package/dist/core/session-policy-store.d.ts +10 -3
  448. package/dist/core/session-policy-store.js +21 -3
  449. package/dist/core/session-reconcile.d.ts +3 -2
  450. package/dist/core/session-reconcile.js +7 -4
  451. package/dist/core/session-store.d.ts +5 -2
  452. package/dist/core/session-store.js +53 -16
  453. package/dist/core/session.d.ts +2 -1
  454. package/dist/core/shell-confinement.d.ts +37 -0
  455. package/dist/core/shell-confinement.js +56 -0
  456. package/dist/core/skill-grant.d.ts +9 -0
  457. package/dist/core/skill-grant.js +18 -0
  458. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
  459. package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
  460. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  461. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  462. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  463. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  464. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  465. package/dist/core/store-contracts/tool-result-store-contract.js +67 -0
  466. package/dist/core/stub-env.d.ts +5 -5
  467. package/dist/core/stub-env.js +11 -1
  468. package/dist/core/swappable-deps.d.ts +17 -43
  469. package/dist/core/swappable-deps.js +15 -5
  470. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  471. package/dist/core/task-event.d.ts +35 -10
  472. package/dist/core/task-limits.d.ts +5 -0
  473. package/dist/core/task-notification.d.ts +172 -12
  474. package/dist/core/task-notification.js +209 -12
  475. package/dist/core/task-registry-agent.d.ts +23 -55
  476. package/dist/core/task-registry-agent.js +41 -56
  477. package/dist/core/task-registry-monitor.d.ts +8 -1
  478. package/dist/core/task-registry-monitor.js +43 -61
  479. package/dist/core/task-registry-shared.d.ts +52 -114
  480. package/dist/core/task-registry-shared.js +24 -48
  481. package/dist/core/task-registry-workflow.js +5 -22
  482. package/dist/core/task-registry.d.ts +64 -90
  483. package/dist/core/task-registry.js +73 -119
  484. package/dist/core/task-result.d.ts +27 -19
  485. package/dist/core/task-spec-members.d.ts +39 -0
  486. package/dist/core/task-spec-members.js +92 -0
  487. package/dist/core/task-spec.d.ts +13 -16
  488. package/dist/core/task-stream.d.ts +1 -1
  489. package/dist/core/task-tool-shape.d.ts +7 -57
  490. package/dist/core/task-tool-shape.js +7 -66
  491. package/dist/core/terminal-cause.d.ts +30 -0
  492. package/dist/core/terminal-cause.js +1 -0
  493. package/dist/core/tool-catalog-entries.js +3 -6
  494. package/dist/core/tool-check-reading.js +16 -10
  495. package/dist/core/tool-conformance.js +1 -2
  496. package/dist/core/tool-errors.d.ts +6 -3
  497. package/dist/core/tool-errors.js +2 -0
  498. package/dist/core/tool-face-reader.d.ts +7 -6
  499. package/dist/core/tool-face-reader.js +6 -4
  500. package/dist/core/tool-face.d.ts +2 -3
  501. package/dist/core/tool-name-aliases.d.ts +23 -28
  502. package/dist/core/tool-name-aliases.js +63 -7
  503. package/dist/core/tool-name-readings.d.ts +14 -3
  504. package/dist/core/tool-name-readings.js +2 -0
  505. package/dist/core/tool-policy.d.ts +113 -22
  506. package/dist/core/tool-policy.js +85 -15
  507. package/dist/core/tool-registry.d.ts +5 -5
  508. package/dist/core/tool-registry.js +2 -2
  509. package/dist/core/tool-result-store.d.ts +111 -5
  510. package/dist/core/tool-result-store.js +52 -12
  511. package/dist/core/tool-spec.d.ts +39 -10
  512. package/dist/core/trace.d.ts +18 -2
  513. package/dist/core/types.d.ts +3 -3
  514. package/dist/core/types.js +1 -1
  515. package/dist/core/untrusted-text.js +1 -1
  516. package/dist/core/user-attachment.d.ts +10 -5
  517. package/dist/core/user-attachment.js +40 -27
  518. package/dist/core/workflow-journal-store.d.ts +1 -1
  519. package/dist/core/workflow-run-store.d.ts +2 -0
  520. package/dist/core/workflow-run-store.js +6 -5
  521. package/dist/core/workflow-settled-run.d.ts +5 -0
  522. package/dist/core/workflow-settled-run.js +7 -0
  523. package/dist/engine/execution-env/node-execution-env.d.ts +37 -7
  524. package/dist/engine/execution-env/node-execution-env.js +224 -21
  525. package/dist/engine/harness/agent-harness.d.ts +66 -19
  526. package/dist/engine/harness/agent-harness.js +98 -27
  527. package/dist/engine/harness/messages.d.ts +4 -3
  528. package/dist/engine/harness/messages.js +2 -2
  529. package/dist/engine/harness/types.d.ts +151 -34
  530. package/dist/engine/llm/media-removed.d.ts +14 -0
  531. package/dist/engine/llm/media-removed.js +9 -0
  532. package/dist/engine/llm/rejected-images.d.ts +35 -25
  533. package/dist/engine/llm/rejected-images.js +59 -10
  534. package/dist/engine/llm/types.d.ts +24 -3
  535. package/dist/engine/llm/types.js +7 -3
  536. package/dist/engine/loop/agent-loop.d.ts +18 -13
  537. package/dist/engine/loop/agent-loop.js +173 -32
  538. package/dist/engine/loop/types.d.ts +21 -5
  539. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  540. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  541. package/dist/engine/session/import-validate.js +7 -0
  542. package/dist/fixtures/index.d.ts +7 -5
  543. package/dist/fixtures/index.js +5 -3
  544. package/dist/index.d.ts +41 -23
  545. package/dist/index.js +29 -16
  546. package/dist/internal/harness-types.d.ts +3 -1
  547. package/dist/internal/llm.d.ts +2 -1
  548. package/dist/internal/llm.js +1 -0
  549. package/dist/orchestration/goal.d.ts +6 -2
  550. package/dist/orchestration/goal.js +6 -3
  551. package/dist/orchestration/run-workflow-tool.d.ts +20 -20
  552. package/dist/orchestration/run-workflow-tool.js +63 -56
  553. package/dist/orchestration/workflow-governance.d.ts +1 -1
  554. package/dist/orchestration/workflow-governance.js +2 -1
  555. package/dist/orchestration/workflow-types.d.ts +2 -2
  556. package/dist/orchestration/workflow.d.ts +8 -0
  557. package/dist/orchestration/workflow.js +33 -9
  558. package/dist/prompts/default.d.ts +1 -10
  559. package/dist/prompts/default.js +0 -2
  560. package/dist/stores/file/background-agent-store.d.ts +1 -1
  561. package/dist/stores/file/background-agent-store.js +19 -14
  562. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  563. package/dist/stores/file/checkpoint-store.js +24 -16
  564. package/dist/stores/file/file-history-store.d.ts +1 -1
  565. package/dist/stores/file/file-history-store.js +4 -1
  566. package/dist/stores/file/index.d.ts +9 -6
  567. package/dist/stores/file/index.js +33 -9
  568. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  569. package/dist/stores/file/ledger-tuning.js +21 -0
  570. package/dist/stores/file/mailbox-store.d.ts +1 -1
  571. package/dist/stores/file/mailbox-store.js +43 -21
  572. package/dist/stores/file/memory-store.d.ts +1 -1
  573. package/dist/stores/file/memory-store.js +4 -1
  574. package/dist/stores/file/permission-rule-adopt.js +24 -21
  575. package/dist/stores/file/permission-rule-store.js +6 -3
  576. package/dist/stores/file/session-policy-store.d.ts +1 -1
  577. package/dist/stores/file/session-policy-store.js +4 -1
  578. package/dist/stores/file/session-store.d.ts +17 -4
  579. package/dist/stores/file/session-store.js +22 -19
  580. package/dist/stores/file/shared-ledger.d.ts +26 -0
  581. package/dist/stores/file/shared-ledger.js +38 -9
  582. package/dist/stores/file/tool-result-store.d.ts +31 -2
  583. package/dist/stores/file/tool-result-store.js +129 -7
  584. package/dist/stores/file/usage-window-store.d.ts +1 -1
  585. package/dist/stores/file/usage-window-store.js +4 -1
  586. package/dist/stores/file/workflow-journal-store.d.ts +1 -13
  587. package/dist/stores/file/workflow-journal-store.js +4 -18
  588. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  589. package/dist/stores/file/workflow-run-store.js +15 -10
  590. package/dist/tools/fs/containment-face.d.ts +5 -0
  591. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  592. package/dist/tools/fs/dead-cwd.js +4 -11
  593. package/dist/tools/fs/encoding.d.ts +13 -4
  594. package/dist/tools/fs/encoding.js +17 -2
  595. package/dist/tools/fs/fs-bash-background-text.d.ts +13 -0
  596. package/dist/tools/fs/fs-bash-background-text.js +7 -0
  597. package/dist/tools/fs/fs-bash.d.ts +11 -22
  598. package/dist/tools/fs/fs-bash.js +58 -154
  599. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  600. package/dist/tools/fs/fs-pdf.js +34 -27
  601. package/dist/tools/fs/fs-read.d.ts +5 -4
  602. package/dist/tools/fs/fs-read.js +35 -18
  603. package/dist/tools/fs/fs-search-tools.js +4 -1
  604. package/dist/tools/fs/fs-shared.d.ts +39 -16
  605. package/dist/tools/fs/fs-shared.js +25 -6
  606. package/dist/tools/fs/fs-write.js +5 -5
  607. package/dist/tools/fs/index.d.ts +15 -9
  608. package/dist/tools/fs/index.js +12 -18
  609. package/dist/tools/fs/pdf.d.ts +4 -4
  610. package/dist/tools/fs/pdf.js +6 -6
  611. package/dist/tools/fs/read-deny-home.js +8 -1
  612. package/dist/tools/fs/read-deny.d.ts +26 -2
  613. package/dist/tools/fs/read-deny.js +9 -2
  614. package/dist/tools/fs/read-floor.d.ts +57 -6
  615. package/dist/tools/fs/read-floor.js +241 -2
  616. package/dist/tools/fs/removal-targets.d.ts +9 -4
  617. package/dist/tools/fs/removal-targets.js +17 -9
  618. package/dist/tools/fs/search.d.ts +6 -5
  619. package/dist/tools/fs/search.js +10 -10
  620. package/dist/tools/fs/shell-read-establish.js +3 -1
  621. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  622. package/dist/tools/fs/shell-read-identity.js +4 -2
  623. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  624. package/dist/tools/fs/shell-read-judge.js +1 -1
  625. package/dist/tools/monitor.d.ts +12 -10
  626. package/dist/tools/monitor.js +22 -13
  627. package/dist/tools/scheduler-tools.js +42 -4
  628. package/dist/tools/web.d.ts +0 -10
  629. package/dist/tools/web.js +1 -4
  630. package/dist/tools/worktree.d.ts +5 -1
  631. package/dist/tools/worktree.js +20 -17
  632. package/package.json +8 -3
  633. package/test/export-surface.snapshot.json +166 -30
  634. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  635. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  636. package/wire-changes/core@7.60.0.json +3274 -0
  637. package/wire-changes/core@7.61.0.json +4405 -0
  638. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  639. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  640. package/wire-changes/primitives@7.60.0.json +30 -0
  641. package/wire-changes/primitives@7.61.0.json +30 -0
  642. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  643. package/dist/core/runner/image-removed-seat.js +0 -19
@@ -1,9 +1,91 @@
1
1
  import { type ExecutionOutcomeRecordWord } from "../../core/checkpoint-execution-record.js";
2
2
  import { type HolderJudge } from "../../core/checkpoint-generation.js";
3
- import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
3
+ import { type Checkpoint, type PendingSteerEntry, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
4
4
  import type { GateOutcome } from "../../core/gate-outcome.js";
5
5
  import { type CheckpointDeleteGuard, type CheckpointOverdueCursor, type CheckpointOverdueQuery, type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery } from "../../core/checkpoint-queries.js";
6
+ import type { AssertAllKeysHandled } from "../../core/ask-origin.js";
6
7
  import { type CorruptReadInfo } from "./corrupt-read-sink.js";
8
+ /**
9
+ * design/80 §2.4 — THE LOAD-BEARING file store: a {@link CheckpointStore} whose once-only CAS is
10
+ * behaviorally IDENTICAL to {@link import("../../core/checkpoint-store.js").InMemoryCheckpointStore}.
11
+ *
12
+ * **The decisive simplification (§2.4): the local binary is ONE process, one Node event loop.** So the
13
+ * multi-process file-locking literature (per-op `flock`, `O_EXCL` lockfiles) buys nothing — there is NO
14
+ * per-operation lock. Correctness instead rests on three things, exactly mirroring the in-memory store:
15
+ *
16
+ * 1. **In-process async mutex per token** — a `Map<token, Promise>` serialization chain (the SAME shape as
17
+ * `TtlSessionStore.pending`): `resolve`/`reopen`/`expire`/`setPendingSteer`/`put` on a given token chain
18
+ * behind one another, so no two interleaved async tasks can both read `pending` and both commit.
19
+ * 2. **Authoritative state = an in-memory `Map<token, Checkpoint>`**, rebuilt by replaying
20
+ * `checkpoints.jsonl` (+ a compacted `snapshot`) at boot, last-writer-wins by event order (the latest
21
+ * event's status / resolvedOutcome / reopenReason / rev win — the "authoritative fields outside the blob"
22
+ * rule Pg implements with columns).
23
+ * 3. **Commit ordering = appendLine the event + fsync BEFORE flipping the in-memory map** — so a crash can
24
+ * never leave "memory says resolved, disk says pending". A crash *before* the fsync'd append replays as
25
+ * `pending` (a retry can still win); a crash *after* replays as `resolved` (a retry is a no-op `false`).
26
+ * This matches the `testInjectFault` `resolve-before-commit` / `resolve-after-commit` contract exactly.
27
+ *
28
+ * The CAS predicate is byte-for-byte the in-memory one: `row && row.scope === scope && row.status ===
29
+ * 'pending'` plus the `expect.rev` OCC; `setPendingSteer` runs {@link validatePendingSteer} FIRST (before
30
+ * the row lookup); the winner comes from {@link winnerFromOutcome}. NO per-operation flock.
31
+ *
32
+ * **What makes premise 1 true (and what used to only assume it):** the CONSTRUCTOR takes a coarse
33
+ * cross-process writer fence on the ledger directory (`root/checkpoints/LOCK`, via
34
+ * {@link import("./fs-atomic.js").acquireStoreDirLock}) — a second OS process over the same data root is
35
+ * refused loudly ({@link import("./fs-atomic.js").FileStoreLockError}, code `store.dir_in_use`) instead
36
+ * of quietly replaying a private view. Instances INSIDE this process share that fence exactly as they
37
+ * share the authority (refcounted; the last {@link FileCheckpointStore.close} drops it), and a lock left
38
+ * by a dead pid is pruned as stale, so a crash never needs manual cleanup. Before this the doc named a
39
+ * fence this class never took — `FileStorageBackend`'s `root/LOCK` — which meant nothing at all for the
40
+ * direct construction the root export invites: two processes each won the once-only CAS on the same
41
+ * token (approval AND refusal both reported as the winner), and the process that had never loaded the
42
+ * other's rows erased them at its next compaction, with no error on either side.
43
+ */
44
+ /** One persisted ledger event. The replay folds these in order into the authoritative map. */
45
+ type LedgerEvent = {
46
+ t: "put";
47
+ token: string;
48
+ cp: Checkpoint;
49
+ } | {
50
+ t: "resolve";
51
+ token: string;
52
+ rev: number;
53
+ resolvedOutcome?: Checkpoint["resolvedOutcome"];
54
+ } | {
55
+ t: "reopen";
56
+ token: string;
57
+ rev: number;
58
+ reason: ReopenReason;
59
+ }
60
+ /** The execution-outcome record (CheckpointRow.executionOutcome): written once per row by
61
+ * `recordExecutionOutcome`; the replay sets both columns together. A binary released before this kind
62
+ * refuses the replay at the discriminator fence below while the event is still in the live ledger;
63
+ * once compaction has folded it into a snapshot row, that older binary reads the row with a field it
64
+ * does not know and its `reopen` (the pre-record predicate) ignores it — the same rollback shape the
65
+ * queue event above documents, disclosed in the release notes rather than fenced here. */
66
+ | {
67
+ t: "execution";
68
+ token: string;
69
+ gate: GateOutcome;
70
+ atMs: number;
71
+ } | {
72
+ t: "expire";
73
+ token: string;
74
+ }
75
+ /** The row is gone (`deleteSessionCheckpoints`): the replay removes it from the map, and the next compaction writes no line for it. A
76
+ * binary released before this kind refuses the replay at the discriminator fence while the event is in the live ledger; once a
77
+ * compaction has folded it away the directory reads on that binary again — the store-format note the release carries. */
78
+ | {
79
+ t: "delete";
80
+ token: string;
81
+ }
82
+ /** design/171 §5.3 — one APPENDED queue entry, carrying the `seq` the append minted so the replay is
83
+ * deterministic and never re-runs the bound checks an already-committed append passed. */
84
+ | {
85
+ t: "steer_append";
86
+ token: string;
87
+ entry: PendingSteerEntry;
88
+ };
7
89
  export interface FileCheckpointStoreOptions {
8
90
  /** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
9
91
  onCorruptRead?: (info: CorruptReadInfo) => void;
@@ -21,6 +103,48 @@ export interface FileCheckpointStoreOptions {
21
103
  /** The judge of a resolve's claim holder ({@link HolderJudge}); with it the store declares `fence = { holder: true }`. */
22
104
  holderIsCurrent?: HolderJudge;
23
105
  }
106
+ /**
107
+ * Every event kind this reader understands — the ledger's CLOSED SET, exported so a program that reads a `checkpoints.jsonl` itself judges
108
+ * a line against the words the store folds, not a copy of them. Kept as a VALUE (not just the type union) because the fence below judges
109
+ * DECODED JSON, which no compile-time union can vouch for.
110
+ *
111
+ * Total BOTH ways at compile time ({@link CheckpointLedgerKindsAreTheEventUnion}): a plain `Set<LedgerEvent["t"]>` would have accepted a list
112
+ * that silently forgot a member, and the failure shape of that drift is worse than the bug the fence fixes — a future release adding a
113
+ * supported kind (union arm, switch case, writer) but not this list would DURABLY append the event and only then have the replay refuse
114
+ * it: the write is on disk, memory is stale, and every later replay of that directory refuses the store. Forgetting a word, or listing
115
+ * one the union does not have, fails to compile.
116
+ */
117
+ export declare const CHECKPOINT_LEDGER_EVENT_KINDS: readonly ["put", "resolve", "reopen", "execution", "expire", "delete", "steer_append"];
118
+ export type CheckpointLedgerEventKind = (typeof CHECKPOINT_LEDGER_EVENT_KINDS)[number];
119
+ /** The fence over {@link CHECKPOINT_LEDGER_EVENT_KINDS}: `never` while the list and the event union name the same words. */
120
+ export type CheckpointLedgerKindsAreTheEventUnion = AssertAllKeysHandled<Exclude<LedgerEvent["t"], CheckpointLedgerEventKind> | Exclude<CheckpointLedgerEventKind, LedgerEvent["t"]>>;
121
+ export interface ReadCheckpointLedgerOptions {
122
+ /** This reader's half of {@link FileCheckpointStoreOptions.onCorruptRead}: told of every snapshot row / ledger event dropped as damage. */
123
+ onCorruptRead?: (info: CorruptReadInfo) => void;
124
+ }
125
+ /** What {@link readCheckpointLedger} answers: the rows the ledger folds to, or no reading at all. */
126
+ export type CheckpointLedgerReading = {
127
+ /** The directory held still for one whole read. */
128
+ readonly settled: true;
129
+ /** token → row, folded exactly as a store would fold it: fresh objects, owned by the caller, shared with no store. */
130
+ readonly rows: ReadonlyMap<string, Checkpoint>;
131
+ /** Ledger events folded over the snapshot (zero right after a compaction). */
132
+ readonly events: number;
133
+ } | {
134
+ /** The snapshot kept being replaced under the read (a writer compacting, three reads running): no verdict — the last read is not offered in its place. */
135
+ readonly settled: false;
136
+ };
137
+ /**
138
+ * Read a data root's checkpoint ledger WITHOUT opening the store — for a program that must know what the ledger holds beside (or instead of) a
139
+ * running worker: a drain check asking whether a parked row still needs this engine's rows, an operator tool. It takes no writer fence
140
+ * (`checkpoints/LOCK` is neither created nor consulted, so it neither contends with a live store nor is refused by one), opens no append
141
+ * handle, and creates nothing — not the directory either: a root with no ledger reads as no rows. The fold is the store's own
142
+ * (`applyCheckpointEvent` through the same discriminator fence), so a ledger event kind this binary does not know refuses the read exactly as
143
+ * it refuses the store's replay (`checkpoint.unsupported_version`, `detail.reason` `ledger_event_unknown`); {@link CHECKPOINT_LEDGER_EVENT_KINDS}
144
+ * is the word list that fence judges by. A root whose adoption is in flight is refused as the store refuses it. Beside a compacting writer
145
+ * the read is bracketed (see {@link readLedgerSettled}) and is `settled: false` rather than a view that never existed.
146
+ */
147
+ export declare function readCheckpointLedger(root: string, opts?: ReadCheckpointLedgerOptions): CheckpointLedgerReading;
24
148
  export declare class FileCheckpointStore implements CheckpointStore {
25
149
  /** design/173 §2.3 — honest declaration on the restart-survival axis the vocabulary claims: rows
26
150
  * live on disk (fsync'd append log) and survive a process restart. Multi-replica coordination is
@@ -57,7 +181,7 @@ export declare class FileCheckpointStore implements CheckpointStore {
57
181
  private readonly ledgerPath;
58
182
  /** Present exactly when the store was built with a session head read (`FileCheckpointStoreOptions.sessionHeadOf`). */
59
183
  readonly deleteSessionCheckpoints?: (sessionId: string, guard: CheckpointDeleteGuard) => Promise<number>;
60
- constructor(root: string, opts?: FileCheckpointStoreOptions);
184
+ constructor(root: string, options?: FileCheckpointStoreOptions);
61
185
  /** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
62
186
  private withLock;
63
187
  /**
@@ -106,3 +230,4 @@ export declare class FileCheckpointStore implements CheckpointStore {
106
230
  */
107
231
  close(): void;
108
232
  }
233
+ export {};
@@ -1,21 +1,16 @@
1
1
  import { join } from "node:path";
2
2
  import { assertAdoptionBootGate } from "./adoption/marker.js";
3
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
4
+ import { readLedgerTuning } from "./ledger-tuning.js";
3
5
  import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
4
6
  import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
5
7
  import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
6
8
  import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
7
- import { SharedLedgerTable } from "./shared-ledger.js";
9
+ import { readLedgerSettled, SharedLedgerTable } from "./shared-ledger.js";
8
10
  import { guardCorruptSink } from "./corrupt-read-sink.js";
9
- const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
10
- put: true,
11
- resolve: true,
12
- reopen: true,
13
- execution: true,
14
- expire: true,
15
- delete: true,
16
- steer_append: true,
17
- };
18
- const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(Object.keys(CHECKPOINT_LEDGER_EVENT_REGISTRY));
11
+ const FILE_CHECKPOINT_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, fsync: 0, compactEvery: 0, sessionHeadOf: 0, holderIsCurrent: 0 });
12
+ export const CHECKPOINT_LEDGER_EVENT_KINDS = Object.freeze(["put", "resolve", "reopen", "execution", "expire", "delete", "steer_append"]);
13
+ const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(CHECKPOINT_LEDGER_EVENT_KINDS);
19
14
  function applyCheckpointEvent(cps, ev) {
20
15
  if (!KNOWN_CHECKPOINT_LEDGER_EVENTS.has(ev.t)) {
21
16
  throw new CheckpointError("checkpoint.unsupported_version", `file checkpoint ledger: unrecognised event kind "${String(ev.t)}" — ` +
@@ -69,7 +64,7 @@ const isCheckpointRow = (x) => x !== null &&
69
64
  typeof x.token === "string" &&
70
65
  typeof x.scope === "string" &&
71
66
  typeof x.status === "string";
72
- const checkpointLedgers = new SharedLedgerTable({
67
+ const checkpointLedgerModel = {
73
68
  label: "checkpoint ledger",
74
69
  keyOf: (cp) => cp.token,
75
70
  apply: applyCheckpointEvent,
@@ -84,7 +79,18 @@ const checkpointLedgers = new SharedLedgerTable({
84
79
  return false;
85
80
  return ev.t === "put" ? isCheckpointRow(ev.cp) : true;
86
81
  },
87
- });
82
+ };
83
+ const checkpointLedgers = new SharedLedgerTable(checkpointLedgerModel);
84
+ export function readCheckpointLedger(root, opts = {}) {
85
+ assertAdoptionBootGate(root, "readCheckpointLedger");
86
+ const dir = join(root, "checkpoints");
87
+ const read = readLedgerSettled({
88
+ ledgerPath: join(dir, "checkpoints.jsonl"),
89
+ snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
90
+ ...(opts.onCorruptRead !== undefined ? { onCorruptRead: guardCorruptSink(opts.onCorruptRead) } : {}),
91
+ }, checkpointLedgerModel);
92
+ return read.settled ? { settled: true, rows: read.rows, events: read.events } : { settled: false };
93
+ }
88
94
  export class FileCheckpointStore {
89
95
  durability = "durable";
90
96
  fidelity = "json";
@@ -100,13 +106,15 @@ export class FileCheckpointStore {
100
106
  fault = null;
101
107
  discloseCorrupt;
102
108
  ledgerPath;
103
- constructor(root, opts = {}) {
109
+ constructor(root, options) {
110
+ const opts = receiveOptions(options, "FileCheckpointStore", FILE_CHECKPOINT_STORE_OPTION_KEYS);
104
111
  assertAdoptionBootGate(root, "FileCheckpointStore");
105
- this.fsyncEnabled = opts.fsync !== false;
112
+ const tuning = readLedgerTuning(opts, "FileCheckpointStore", "FileCheckpointStore options");
113
+ this.fsyncEnabled = tuning.fsync;
106
114
  this.holderIsCurrent = opts.holderIsCurrent;
107
115
  if (opts.holderIsCurrent !== undefined)
108
116
  this.fence = Object.freeze({ holder: true });
109
- this.compactEvery = opts.compactEvery ?? 1000;
117
+ this.compactEvery = tuning.compactEvery;
110
118
  this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
111
119
  const dir = join(root, "checkpoints");
112
120
  this.ledgerPath = join(dir, "checkpoints.jsonl");
@@ -173,7 +173,7 @@ export declare class FileFileHistoryStore implements FileHistoryStore {
173
173
  * A tie is then decided by the entry id, which IS commit order for engine-minted uuidv7 ids.
174
174
  */
175
175
  private nextCommittedAt;
176
- constructor(root: string, opts?: FileFileHistoryStoreOptions);
176
+ constructor(root: string, options?: FileFileHistoryStoreOptions);
177
177
  /**
178
178
  * The RETENTION pass, run after a boundary file is published (design/381 §片2 — see
179
179
  * {@link FileHistoryStore.reap} for why the backend owns this rather than the host).
@@ -8,6 +8,8 @@ import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, write
8
8
  import { guardCorruptSink } from "./corrupt-read-sink.js";
9
9
  import { isAbsoluteForFamily } from "../../tools/fs/safety.js";
10
10
  import { assertAdoptionBootGate } from "./adoption/marker.js";
11
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
12
+ const FILE_FILE_HISTORY_STORE_OPTION_KEYS = optionKeys()({ onCorruptRead: 0, retention: 0 });
11
13
  function trackedDigest(rows) {
12
14
  const canonical = [...rows]
13
15
  .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
@@ -155,7 +157,8 @@ export class FileFileHistoryStore {
155
157
  this.lastCommittedAt = Math.max(Date.now(), this.lastCommittedAt + 1);
156
158
  return this.lastCommittedAt;
157
159
  }
158
- constructor(root, opts) {
160
+ constructor(root, options) {
161
+ const opts = receiveOptions(options, "FileFileHistoryStore", FILE_FILE_HISTORY_STORE_OPTION_KEYS);
159
162
  assertAdoptionBootGate(root, "FileFileHistoryStore");
160
163
  this.boundaryKeep = resolveFileHistoryRetention("FileFileHistoryStore", opts?.retention);
161
164
  this.base = join(root, "file-history");
@@ -11,17 +11,18 @@ import type { FileHistoryStore } from "../../core/file-history-store.js";
11
11
  import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
12
12
  import type { MailboxStore } from "../../core/mailbox-store.js";
13
13
  import type { RosterStore } from "../../agents/roster-store.js";
14
- import type { SessionPolicyStore } from "../../core/session-policy-store.js";
14
+ import { type SessionPolicyStore } from "../../core/session-policy-store.js";
15
15
  import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
16
16
  import type { UsageWindowStore } from "../../core/usage-window-store.js";
17
17
  import type { EngineStorageBackend } from "../../core/engine-storage-backend.js";
18
- export { FileCheckpointStore, type FileCheckpointStoreOptions } from "./checkpoint-store.js";
18
+ export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, type CheckpointLedgerEventKind, type CheckpointLedgerReading, type FileCheckpointStoreOptions, type ReadCheckpointLedgerOptions, } from "./checkpoint-store.js";
19
19
  export { FileMemoryStore } from "./memory-store.js";
20
20
  export { FileSessionRepo, type FileSessionRepoOptions } from "./session-store.js";
21
21
  export { FileToolResultStore } from "./tool-result-store.js";
22
22
  export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type SessionPolicyCorruptReadInfo } from "./session-policy-store.js";
23
23
  export { FileFileHistoryStore, type FileFileHistoryStoreOptions } from "./file-history-store.js";
24
- export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
24
+ export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
25
+ export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
25
26
  export { FileUsageWindowStore, type FileUsageWindowStoreOptions } from "./usage-window-store.js";
26
27
  export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
27
28
  export { FileStoreLockError, type FileStoreLockErrorCode } from "./fs-atomic.js";
@@ -66,8 +67,10 @@ export interface FileStorageBackendOptions {
66
67
  /** `TtlSessionStore` idle-eviction policy. Default `"forget"` (§7 decision 5 — durable history is never
67
68
  * deleted by an idle timer). */
68
69
  evict?: EvictPolicy;
69
- /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold). */
70
- checkpoint?: FileCheckpointStoreOptions;
70
+ /** Checkpoint store tuning (fsync cadence for `put`/`setPendingSteer`, ledger compaction threshold, the holder judge). The
71
+ * corrupt-read sink and the session head read are the backend's own — the sink is {@link FileStorageBackendOptions.onCorruptRead}
72
+ * (one failure grammar, one sink) and the head read is its session store's — so neither is accepted here. */
73
+ checkpoint?: Omit<FileCheckpointStoreOptions, "onCorruptRead" | "sessionHeadOf">;
71
74
  /**
72
75
  * design/381 §片2 — file-history tuning, today just the boundary RETENTION bound (omitted ⇒ the
73
76
  * engine default; `{ retention: { keep: "unbounded" } }` hands the GC schedule to the deployment).
@@ -184,7 +187,7 @@ export declare class FileStorageBackend implements EngineStorageBackend {
184
187
  * descriptors) this backend joined; `TtlSessionStore.dispose()` only clears the sweep timer. */
185
188
  private readonly fileSessions;
186
189
  private readonly fileWorkflowJournal;
187
- constructor(opts?: FileStorageBackendOptions);
190
+ constructor(options?: FileStorageBackendOptions);
188
191
  /**
189
192
  * The data-dir boot lock could not be handed back — a root that turned read-only under a running
190
193
  * process, an unreadable lock file. Teardown here is best-effort by contract, but best-effort must not
@@ -1,9 +1,10 @@
1
1
  import { join } from "node:path";
2
2
  import { guardedMemoryStore } from "../../core/memory.js";
3
- import { TtlSessionStore } from "../../core/session-store.js";
3
+ import { STORE_HOOK_KEYS, TtlSessionStore } from "../../core/session-store.js";
4
4
  import { BootLock, createFileConsolidationLock, resolveDataRoot } from "./fs-atomic.js";
5
5
  import { assertAdoptionBootGate } from "./adoption/marker.js";
6
6
  import { FileCheckpointStore } from "./checkpoint-store.js";
7
+ import { readLedgerTuning } from "./ledger-tuning.js";
7
8
  import { FileMemoryStore } from "./memory-store.js";
8
9
  import { FileSessionRepo } from "./session-store.js";
9
10
  import { FileToolResultStore } from "./tool-result-store.js";
@@ -14,13 +15,20 @@ import { FileBackgroundAgentStore } from "./background-agent-store.js";
14
15
  import { FileMailboxStore } from "./mailbox-store.js";
15
16
  import { FileRosterStore } from "../../agents/roster-store.js";
16
17
  import { FileFileHistoryStore } from "./file-history-store.js";
17
- export { FileCheckpointStore } from "./checkpoint-store.js";
18
+ import { readMountedToolNames } from "../../core/session-policy-store.js";
19
+ import { optionKeys, receiveMembers, receiveOptions, refuseProxy, refuseStrayMembers } from "../../core/own-property-receipt.js";
20
+ import { receiveFileHistoryRetention } from "../../core/file-history-retention.js";
21
+ function nestedOptions(value, member, keys) {
22
+ return value === undefined ? undefined : receiveMembers(value, { subject: `FileStorageBackendOptions.${member}`, unit: "option", moment: "at new FileStorageBackend" }, keys);
23
+ }
24
+ export { FileCheckpointStore, CHECKPOINT_LEDGER_EVENT_KINDS, readCheckpointLedger, } from "./checkpoint-store.js";
18
25
  export { FileMemoryStore } from "./memory-store.js";
19
26
  export { FileSessionRepo } from "./session-store.js";
20
27
  export { FileToolResultStore } from "./tool-result-store.js";
21
28
  export { FileSessionPolicyStore } from "./session-policy-store.js";
22
29
  export { FileFileHistoryStore } from "./file-history-store.js";
23
- export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
30
+ export { FileWorkflowJournalStore } from "./workflow-journal-store.js";
31
+ export { MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "../../core/workflow-journal-store.js";
24
32
  export { FileUsageWindowStore } from "./usage-window-store.js";
25
33
  export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
26
34
  export { FileStoreLockError } from "./fs-atomic.js";
@@ -28,6 +36,10 @@ export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog
28
36
  export { processFingerprint, isProcessLive } from "./fs-atomic.js";
29
37
  export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
30
38
  export { adoptLocalDataRoot, ackAdoptionConfig, witnessAdoptionConfig, listAdoptionQuarantine, readAdoptionStatus, } from "./adoption/adopt.js";
39
+ const FILE_STORAGE_BACKEND_OPTION_KEYS = optionKeys()({ root: 0, utilityGate: 0, evict: 0, checkpoint: 0, fileHistory: 0, sessionPolicy: 0, embedder: 0, onCorruptRead: 0, sessions: 0 });
40
+ const NESTED_FILE_HISTORY_OPTION_KEYS = optionKeys()({ retention: 0 });
41
+ const NESTED_SESSION_POLICY_OPTION_KEYS = optionKeys()({ mountedToolNames: 0 });
42
+ const NESTED_CHECKPOINT_OPTION_KEYS = optionKeys()({ fsync: 0, compactEvery: 0, holderIsCurrent: 0 });
31
43
  export class FileStorageBackend {
32
44
  root;
33
45
  sessionStore;
@@ -50,10 +62,22 @@ export class FileStorageBackend {
50
62
  ttl;
51
63
  fileSessions;
52
64
  fileWorkflowJournal;
53
- constructor(opts = {}) {
54
- if ("retention" in opts) {
55
- throw Object.assign(new Error(`FileStorageBackend runs no retention executor, so its options take no \`retention\` word: its stores declare "none".`), { code: "config.retention_capability" });
65
+ constructor(options) {
66
+ if (options !== undefined && options !== null && typeof options === "object") {
67
+ refuseProxy(options, { subject: "FileStorageBackend options", unit: "option", moment: "at new FileStorageBackend" });
68
+ if (Object.hasOwn(options, "retention")) {
69
+ throw Object.assign(new Error(`FileStorageBackend runs no retention executor, so its options take no \`retention\` word: its stores declare "none".`), { code: "config.retention_capability" });
70
+ }
56
71
  }
72
+ const opts = receiveOptions(options, "FileStorageBackend", FILE_STORAGE_BACKEND_OPTION_KEYS);
73
+ const checkpointRecord = nestedOptions(opts.checkpoint, "checkpoint", NESTED_CHECKPOINT_OPTION_KEYS);
74
+ const checkpointOptions = checkpointRecord === undefined ? undefined : { ...checkpointRecord, ...readLedgerTuning(checkpointRecord, "FileCheckpointStore", "FileStorageBackendOptions.checkpoint") };
75
+ const sessionPolicyRecord = nestedOptions(opts.sessionPolicy, "sessionPolicy", NESTED_SESSION_POLICY_OPTION_KEYS);
76
+ const sessionPolicyOptions = sessionPolicyRecord?.mountedToolNames === undefined ? sessionPolicyRecord : { ...sessionPolicyRecord, mountedToolNames: readMountedToolNames(sessionPolicyRecord.mountedToolNames) };
77
+ const fileHistoryRecord = nestedOptions(opts.fileHistory, "fileHistory", NESTED_FILE_HISTORY_OPTION_KEYS);
78
+ const fileHistoryOptions = fileHistoryRecord === undefined ? undefined : { ...fileHistoryRecord, retention: receiveFileHistoryRetention("FileStorageBackendOptions.fileHistory", fileHistoryRecord.retention) };
79
+ if (opts.sessions !== undefined)
80
+ refuseStrayMembers(opts.sessions, { subject: "FileStorageBackendOptions.sessions", unit: "hook", moment: "at new FileStorageBackend" }, STORE_HOOK_KEYS);
57
81
  this.root = resolveDataRoot(opts.root);
58
82
  assertAdoptionBootGate(this.root, "FileStorageBackend");
59
83
  this.lock = new BootLock(join(this.root, "LOCK"));
@@ -66,14 +90,14 @@ export class FileStorageBackend {
66
90
  this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } }, ...(opts.sessions !== undefined ? { hooks: opts.sessions } : {}) });
67
91
  this.sessionStore = this.ttl;
68
92
  const sessionHeadOf = this.ttl.headOf;
69
- this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
93
+ this.fileCheckpoints = new FileCheckpointStore(this.root, { ...checkpointOptions, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
70
94
  built.push(() => this.fileCheckpoints.close());
71
95
  this.checkpointStore = this.fileCheckpoints;
72
96
  this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});
73
97
  built.push(() => this.fileMemory.close());
74
98
  this.memoryStore = guardedMemoryStore(this.fileMemory, opts.utilityGate);
75
99
  this.toolResultStore = new FileToolResultStore(this.root, corruptRead);
76
- this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...opts.sessionPolicy, ...corruptRead });
100
+ this.sessionPolicyStore = new FileSessionPolicyStore(this.root, { ...sessionPolicyOptions, ...corruptRead });
77
101
  this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root, true, corruptRead);
78
102
  built.push(() => this.fileWorkflowJournal.dispose());
79
103
  this.workflowJournalStore = this.fileWorkflowJournal;
@@ -85,7 +109,7 @@ export class FileStorageBackend {
85
109
  built.push(() => this.fileMailbox.close());
86
110
  this.mailboxStore = this.fileMailbox;
87
111
  this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
88
- this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...(opts.fileHistory ?? {}), ...(corruptRead ?? {}) });
112
+ this.fileHistoryStore = new FileFileHistoryStore(this.root, { ...fileHistoryOptions, ...(corruptRead ?? {}) });
89
113
  this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
90
114
  }
91
115
  catch (err) {
@@ -0,0 +1,23 @@
1
+ /** Each store's compaction threshold when none is given. */
2
+ export declare const LEDGER_COMPACT_EVERY_DEFAULTS: Readonly<{
3
+ FileCheckpointStore: 1000;
4
+ FileMailboxStore: 500;
5
+ FileBackgroundAgentStore: 1000;
6
+ FileWorkflowRunStore: 1000;
7
+ }>;
8
+ /** A store that takes ledger tuning. */
9
+ export type LedgerTunedStore = keyof typeof LEDGER_COMPACT_EVERY_DEFAULTS;
10
+ /** A store's ledger tuning, read: every member present. */
11
+ export interface LedgerTuning {
12
+ readonly fsync: boolean;
13
+ readonly compactEvery: number;
14
+ }
15
+ /**
16
+ * Read a store's ledger tuning off an options record already received (the store door's copy, or a backend's nested record's):
17
+ * the values judged, the absent ones the store's defaults. `subject` names the record in a refusal (`FileMailboxStore options`,
18
+ * `FileStorageBackendOptions.checkpoint`).
19
+ */
20
+ export declare function readLedgerTuning(given: {
21
+ readonly fsync?: unknown;
22
+ readonly compactEvery?: unknown;
23
+ }, store: LedgerTunedStore, subject: string): LedgerTuning;
@@ -0,0 +1,21 @@
1
+ import { receiptRefusal } from "../../core/own-property-receipt.js";
2
+ export const LEDGER_COMPACT_EVERY_DEFAULTS = Object.freeze({
3
+ FileCheckpointStore: 1000,
4
+ FileMailboxStore: 500,
5
+ FileBackgroundAgentStore: 1000,
6
+ FileWorkflowRunStore: 1000,
7
+ });
8
+ function shown(value) {
9
+ return typeof value === "number" ? String(value) : value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
10
+ }
11
+ export function readLedgerTuning(given, store, subject) {
12
+ const fsync = given.fsync;
13
+ if (fsync !== undefined && typeof fsync !== "boolean") {
14
+ throw receiptRefusal(`${subject}.fsync must be a boolean when given (got ${shown(fsync)}) — refused rather than read as on`);
15
+ }
16
+ const compactEvery = given.compactEvery;
17
+ if (compactEvery !== undefined && !(typeof compactEvery === "number" && Number.isSafeInteger(compactEvery) && compactEvery >= 1)) {
18
+ throw receiptRefusal(`${subject}.compactEvery must be a whole number of events of at least 1 when given (got ${shown(compactEvery)}) — refused rather than kept: such a threshold is never reached (the ledger grows without compacting) or reached at every event (a rewrite per write)`);
19
+ }
20
+ return Object.freeze({ fsync: fsync !== false, compactEvery: compactEvery ?? LEDGER_COMPACT_EVERY_DEFAULTS[store] });
21
+ }
@@ -66,7 +66,7 @@ export declare class FileMailboxStore implements MailboxStore {
66
66
  private readonly touched;
67
67
  /** The swallow-guarded corrupt-read seat (undefined = the old silent tolerance). */
68
68
  private readonly discloseCorrupt;
69
- constructor(root: string, opts?: FileMailboxStoreOptions);
69
+ constructor(root: string, options?: FileMailboxStoreOptions);
70
70
  /**
71
71
  * RB-67 (2026-07-25, red probe): the on-disk name is CASE-FOLDED, so the in-memory key and the physical
72
72
  * file can never disagree. Before this, `AgentOne` and `agentone` produced two DIFFERENT shared-state
@@ -1,12 +1,14 @@
1
1
  import { join, resolve, sep } from "node:path";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
- import { assertRetentionPolicy } from "../../core/retention-policy.js";
3
+ import { receiveRetentionPolicy } from "../../core/retention-policy.js";
4
4
  import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
5
- import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxAppend, judgeMailboxAppendById, } from "../../core/mailbox-store.js";
5
+ import { assertMailboxDecisionMove, detachMailboxMessage, foldMailboxConsumed, MAILBOX_REAP_KNOBS, MAILBOX_REPLAY_FACETS, newestSentAt, readStoredMailboxDecision, readMailboxAppend, judgeMailboxAppendById, } from "../../core/mailbox-store.js";
6
6
  import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
7
7
  import { guardCorruptSink } from "./corrupt-read-sink.js";
8
8
  import { physicalPathOf } from "../../core/physical-path.js";
9
9
  import { assertAdoptionBootGate } from "./adoption/marker.js";
10
+ import { optionKeys, receiveOptions } from "../../core/own-property-receipt.js";
11
+ import { readLedgerTuning } from "./ledger-tuning.js";
10
12
  function diskMarkOf(path) {
11
13
  try {
12
14
  const st = statSync(path);
@@ -322,6 +324,7 @@ function sweepLockResidue(dir, lockName) {
322
324
  }
323
325
  }
324
326
  }
327
+ const FILE_MAILBOX_STORE_OPTION_KEYS = optionKeys()({ fsync: 0, lockWaitMs: 0, compactEvery: 0, onCorruptRead: 0 });
325
328
  export class FileMailboxStore {
326
329
  crossProcessSafe = true;
327
330
  identity;
@@ -332,10 +335,12 @@ export class FileMailboxStore {
332
335
  lockWaitMs;
333
336
  touched = new Map();
334
337
  discloseCorrupt;
335
- constructor(root, opts = {}) {
338
+ constructor(root, options) {
339
+ const opts = receiveOptions(options, "FileMailboxStore", FILE_MAILBOX_STORE_OPTION_KEYS);
336
340
  assertAdoptionBootGate(root, "FileMailboxStore");
337
- this.fsyncEnabled = opts.fsync !== false;
338
- this.compactEvery = opts.compactEvery ?? 500;
341
+ const tuning = readLedgerTuning(opts, "FileMailboxStore", "FileMailboxStore options");
342
+ this.fsyncEnabled = tuning.fsync;
343
+ this.compactEvery = tuning.compactEvery;
339
344
  const lockWaitMs = opts.lockWaitMs ?? 10_000;
340
345
  if (typeof lockWaitMs !== "number" || !Number.isFinite(lockWaitMs) || lockWaitMs <= 0) {
341
346
  throw new Error(`FileMailboxStore: lockWaitMs must be a finite number > 0, got ${JSON.stringify(opts.lockWaitMs)}`);
@@ -384,10 +389,11 @@ export class FileMailboxStore {
384
389
  const events = readJsonlRecords(b.path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
385
390
  b.messages = [];
386
391
  b.nextSeq = 1;
392
+ b.consumed = [];
387
393
  delete b.lease;
388
394
  for (const ev of events)
389
395
  applyEvent(b, ev);
390
- b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.lease !== undefined ? 1 : 0)));
396
+ b.events = Math.max(0, events.length - (b.messages.length + 1 + (b.consumed.length > 0 ? 1 : 0) + (b.lease !== undefined ? 1 : 0)));
391
397
  b.mark = now;
392
398
  }
393
399
  load(scope, handle) {
@@ -404,7 +410,7 @@ export class FileMailboxStore {
404
410
  }
405
411
  ensureDir(join(this.dir, sanitizeScope(scope)));
406
412
  const events = readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE);
407
- const state = { messages: [], nextSeq: 1, log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
413
+ const state = { messages: [], nextSeq: 1, consumed: [], log: new AppendLog(path), events: events.length, refs: 1, path, mark: undefined };
408
414
  for (const ev of events)
409
415
  applyEvent(state, ev);
410
416
  state.mark = diskMarkOf(path);
@@ -427,14 +433,8 @@ export class FileMailboxStore {
427
433
  b.mark = markAfterWrite(path);
428
434
  }
429
435
  compact(b, path) {
430
- const lines = [];
431
- lines.push(JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 }));
432
- for (const m of b.messages)
433
- lines.push(JSON.stringify({ t: "append", m }));
434
- if (b.lease !== undefined)
435
- lines.push(JSON.stringify({ t: "lease", ...b.lease }));
436
436
  b.log.closeForSwap();
437
- atomicWriteFile(this.tmpDir, path, lines.length ? `${lines.join("\n")}\n` : "");
437
+ atomicWriteFile(this.tmpDir, path, snapshotOf(b));
438
438
  b.events = 0;
439
439
  b.mark = markAfterWrite(path);
440
440
  }
@@ -444,7 +444,7 @@ export class FileMailboxStore {
444
444
  const record = readMailboxAppend(msg);
445
445
  return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
446
446
  const b = this.load(scope, handle);
447
- const held = judgeMailboxAppendById(b.messages, record);
447
+ const held = judgeMailboxAppendById({ held: b.messages, consumed: b.consumed }, record);
448
448
  if (held !== undefined)
449
449
  return held;
450
450
  const seq = b.nextSeq;
@@ -503,7 +503,7 @@ export class FileMailboxStore {
503
503
  if (!existsSync(path))
504
504
  return 0;
505
505
  return withPathLock(this.lockKey(scope, handle), () => {
506
- const b = { messages: [], nextSeq: 1 };
506
+ const b = { messages: [], nextSeq: 1, consumed: [] };
507
507
  for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
508
508
  applyEvent(b, ev);
509
509
  return b.messages.length;
@@ -523,14 +523,14 @@ export class FileMailboxStore {
523
523
  });
524
524
  }
525
525
  async reap(scope, now, opts) {
526
- assertRetentionPolicy("MailboxStore.reap", opts);
526
+ const policy = receiveRetentionPolicy("MailboxStore.reap", opts, MAILBOX_REAP_KNOBS);
527
527
  sweepLockResidue(join(this.dir, sanitizeScope(scope)));
528
- if (opts?.maxAgeMs === undefined)
528
+ if (policy.maxAgeMs === undefined)
529
529
  return 0;
530
530
  let dropped = 0;
531
531
  const scopeDir = join(this.dir, sanitizeScope(scope));
532
532
  const prefix = scopeDir + sep;
533
- const maxAgeMs = opts.maxAgeMs;
533
+ const maxAgeMs = policy.maxAgeMs;
534
534
  for (const [key, b] of [...sharedBoxes]) {
535
535
  if (!b.path.startsWith(prefix))
536
536
  continue;
@@ -563,13 +563,13 @@ export class FileMailboxStore {
563
563
  const swept = await this.withBox(key, path, () => {
564
564
  if (sharedBoxes.has(key))
565
565
  return false;
566
- const b = { messages: [], nextSeq: 1 };
566
+ const b = { messages: [], nextSeq: 1, consumed: [] };
567
567
  for (const ev of readJsonlRecords(path, this.discloseCorrupt, MAILBOX_EVENT_JUDGE))
568
568
  applyEvent(b, ev);
569
569
  const newest = newestSentAt(b.messages);
570
570
  if (newest === undefined || newest >= now - maxAgeMs)
571
571
  return false;
572
- atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 })}\n`);
572
+ atomicWriteFile(this.tmpDir, path, snapshotOf({ messages: [], nextSeq: b.nextSeq, consumed: b.consumed }));
573
573
  return true;
574
574
  });
575
575
  if (swept)
@@ -592,6 +592,22 @@ export class FileMailboxStore {
592
592
  }
593
593
  }
594
594
  const num = (v) => typeof v === "number" && Number.isFinite(v);
595
+ function isConsumedRecord(v) {
596
+ if (v === null || typeof v !== "object")
597
+ return false;
598
+ const { id, seq, digests } = v;
599
+ return typeof id === "string" && id !== "" && num(seq) && digests !== null && typeof digests === "object" && MAILBOX_REPLAY_FACETS.every((f) => typeof digests[f] === "string");
600
+ }
601
+ function snapshotOf(b) {
602
+ const lines = [JSON.stringify({ t: "lease", owner: "", expiresAt: 0, maxSeq: b.nextSeq - 1 })];
603
+ if (b.consumed.length > 0)
604
+ lines.push(JSON.stringify({ t: "consumed", records: b.consumed }));
605
+ for (const m of b.messages)
606
+ lines.push(JSON.stringify({ t: "append", m }));
607
+ if (b.lease !== undefined)
608
+ lines.push(JSON.stringify({ t: "lease", ...b.lease }));
609
+ return `${lines.join("\n")}\n`;
610
+ }
595
611
  const MAILBOX_EVENT_JUDGE = {
596
612
  accepts: (r) => {
597
613
  const ev = r;
@@ -603,6 +619,8 @@ const MAILBOX_EVENT_JUDGE = {
603
619
  return num(ev.upToSeq);
604
620
  if (ev.t === "decision")
605
621
  return num(r.seq) && typeof r.state === "string";
622
+ if (ev.t === "consumed")
623
+ return Array.isArray(r.records) && r.records.every(isConsumedRecord);
606
624
  return ev.t === "release" && typeof ev.owner === "string";
607
625
  },
608
626
  what: "a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing",
@@ -625,10 +643,14 @@ function applyEvent(b, ev) {
625
643
  b.lease = { owner: ev.owner, expiresAt: ev.expiresAt, maxSeq: ev.maxSeq };
626
644
  }
627
645
  else if (ev.t === "ack") {
646
+ b.consumed = foldMailboxConsumed(b.consumed, b.messages.filter((m) => m.seq <= ev.upToSeq));
628
647
  b.messages = b.messages.filter((m) => m.seq > ev.upToSeq);
629
648
  if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
630
649
  b.lease = undefined;
631
650
  }
651
+ else if (ev.t === "consumed") {
652
+ b.consumed = foldMailboxConsumed(ev.records, []);
653
+ }
632
654
  else if (ev.t === "decision") {
633
655
  const m = b.messages.find((x) => x.seq === ev.seq);
634
656
  if (m !== undefined)