@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,7 +1,7 @@
1
1
  import { lstatSync, readFileSync } from "node:fs";
2
2
  import { dirname, join, resolve } from "node:path";
3
3
  import { err, FileError, ok } from "../../internal/harness.js";
4
- import { StubExecutionEnv } from "../stub-env.js";
4
+ import { performsIo } from "../remote-env.js";
5
5
  import { thrownText } from "../thrown-value.js";
6
6
  import { canonicalize } from "./layout.js";
7
7
  function pathSegmentsDualFamily(p) {
@@ -201,7 +201,7 @@ export const hostProjectMarkerFs = {
201
201
  },
202
202
  };
203
203
  export function projectMarkerFsOf(env) {
204
- return env instanceof StubExecutionEnv ? hostProjectMarkerFs : env;
204
+ return performsIo(env) === false ? hostProjectMarkerFs : env;
205
205
  }
206
206
  function identityError(code, message) {
207
207
  const e = new Error(message);
@@ -1,21 +1,55 @@
1
1
  import { type MemorySyncCursor } from "./sync.js";
2
2
  import { type MemoryBackend, type MemoryEntry, type PatchReport } from "./types.js";
3
+ type CursorAxis = "scope" | "peer" | "store" | "incarnation";
4
+ /** The refusal of a sync whose baseline does not hold, raised before anything is written on either side: the cursor
5
+ * is not this sync's (`config.memory_sync_cursor_mismatch`, with `detail` naming the axis, what the cursor carried
6
+ * there and this sync's value on it) — judged here before any read or transport call on its scope, peer and store,
7
+ * and by the peer before any write on its incarnation, read off the peer's refusal before any local write — or the
8
+ * local store has nothing to bind a cursor to (`config.memory_sync_store`, no `detail`). `outs` are the two ways out
9
+ * its sentence names. */
10
+ type SyncRefusal = Error & {
11
+ code: "config.memory_sync_cursor_mismatch" | "config.memory_sync_store";
12
+ detail?: {
13
+ readonly axis: CursorAxis;
14
+ readonly found: "absent" | "other";
15
+ readonly want: string;
16
+ };
17
+ outs: readonly [string, string];
18
+ };
19
+ /** A thrown value read as a sync refusal this module minted, or `undefined` — the report's one reader of the refusal. */
20
+ export declare function readSyncRefusal(thrown: unknown): Pick<SyncRefusal, "code" | "detail" | "outs" | "message"> | undefined;
3
21
  /**
4
22
  * The identity a sync cursor is bound to — the one mint of {@link MemorySyncCursor.store}: the physical root of
5
23
  * the local File store (the path its root anchor records). A store without a directory has no root to bind a
6
24
  * baseline to and is refused as a sync plane (`config.memory_sync_store`).
7
25
  */
8
26
  export declare function memorySyncStoreOf(backend: MemoryBackend): string;
9
- /** The injected HTTP seam — core never bundles a fetch. The deployment maps `path` (e.g.
10
- * `/v1/memory/sync/user%3Aalice`) onto its server base URL, attaches auth, and returns the
11
- * DECODED JSON body of a 2xx response; any non-2xx / network failure should THROW (the round then
12
- * aborts with zero local side effects — the transport runs before any local write). */
13
- export type MemorySyncTransport = (path: string, body: unknown) => Promise<unknown>;
27
+ /** The injected seam to ONE peer — core never bundles a fetch. */
28
+ export interface MemorySyncTransport {
29
+ /** The addressing identity of the peer `post` reaches (a central sync API: its normalized base URL) and the
30
+ * round's only source of its peer; another peer carries another identity. Rides the wire and the cursor
31
+ * verbatim — never a credential: an identity that is empty or only whitespace, a URL with userinfo, or one the
32
+ * same-principal egress pass would redact is refused before any read or request. Read once per call, and
33
+ * taken at its word: the engine cannot see where `post` actually sends. */
34
+ readonly peer: string;
35
+ /** Maps `path` (e.g. `/v2/memory/sync/user%3Aalice`) onto the peer, attaches auth, and returns the DECODED
36
+ * JSON body of a 2xx response — the answer to the call: its result, or the peer's refusal of it
37
+ * (`{ refused: "baseline_incarnation", incarnation }`, a 2xx answer like a result); any non-2xx / network
38
+ * failure should THROW (the call then aborts with zero local side effects — the transport runs before any
39
+ * local write). */
40
+ post(path: string, body: unknown): Promise<unknown>;
41
+ }
14
42
  /** The wire REQUEST of one round (the server's `parseMemorySyncRequest` twin): the push
15
43
  * half as computed against the client's own cursor. `deletes` ⊆ `Object.keys(baseRevs)` by
16
44
  * construction (a delete is CAS'd on its baseline; an id never synced cannot be delete-propagated). */
17
45
  export interface MemorySyncRequestBody {
46
+ /** The transport's {@link MemorySyncTransport.peer}. */
18
47
  peer: string;
48
+ /** The claim of which state of the peer `baseRevs` was taken against: the cursor's
49
+ * {@link MemorySyncCursor.peerIncarnation} verbatim, present whenever the cursor carries one. The peer compares it
50
+ * with its own incarnation before any write and refuses — writing nothing — when they differ, or when
51
+ * `baseRevs` is not empty and no claim is made. */
52
+ peerIncarnation?: string;
19
53
  /** id → rev at the last completed round (the cursor's baseRevs; empty = first round). */
20
54
  baseRevs: Record<string, string>;
21
55
  /** Full state of every entry new/changed here since the baseline. When
@@ -35,7 +69,9 @@ export interface MemorySyncRequestBody {
35
69
  /** The wire RESPONSE of one round (server `MemorySyncResponse` twin: one RTT, both
36
70
  * directions; `serverDeletes` is the delete-propagation leg [without it a central
37
71
  * removal never crosses = livelock]; `cursor` is the server-computed next baseline with the
38
- * retention discipline ALREADY applied to the pull half). */
72
+ * retention discipline ALREADY applied to the pull half). A peer that refuses answers
73
+ * `{ refused: "baseline_incarnation", incarnation }` instead — its own incarnation, nothing written — which the
74
+ * sync raises as the cursor refusal on the incarnation axis. */
39
75
  export interface MemorySyncResponseBody {
40
76
  /** Ops the server actually landed from our push (empty on an idempotent replay). */
41
77
  applied: PatchReport["applied"];
@@ -57,9 +93,13 @@ export interface MemorySyncResponseBody {
57
93
  /** The next baseline to persist AFTER the pull half lands (the client cannot compute it — it
58
94
  * does not hold the central set). Pull-half ids are retained at the OLD baseline inside; the
59
95
  * client advances the LANDED ones to their landed state before persisting (see ⑤ — otherwise
60
- * every landed pull echoes back next round and a central delete can be resurrected). */
96
+ * every landed pull echoes back next round and a central delete can be resurrected).
97
+ * `incarnation` names the state that answered — the scope's partition on this peer, a value no other partition
98
+ * or state of it carries, every write of this exchange committed under it; it equals the request's claim when
99
+ * one was made, and the next cursor carries it as its `peerIncarnation`. */
61
100
  cursor: {
62
101
  peer: string;
102
+ incarnation: string;
63
103
  baseRevs: Record<string, string>;
64
104
  updatedAtMs: number;
65
105
  };
@@ -85,14 +125,21 @@ export interface SyncMemoryScopeOptions {
85
125
  backend: MemoryBackend;
86
126
  /** The scope this round syncs (one round = one scope, mirroring the server route). */
87
127
  scope: string;
88
- /** The injected HTTP seam. */
128
+ /** The injected seam to the peer; its `peer` is the round's peer. */
89
129
  transport: MemorySyncTransport;
90
- /** The persisted cursor from the last completed round with this peer; absent = first round. A cursor
91
- * for another scope, peer or local store — or one with no store binding — is refused
92
- * (`config.memory_sync_cursor_mismatch`) before any I/O; sync with no cursor instead. */
130
+ /** The persisted cursor from the last completed sync with this transport's peer; absent = the first sync. A
131
+ * cursor for another scope, peer or local store — or one with no peer or store binding — is refused
132
+ * (`config.memory_sync_cursor_mismatch`) before any I/O; a cursor whose baseline was taken against another state of
133
+ * the peer — or one with a non-empty baseline and no incarnation — is refused by the peer before it writes, and the
134
+ * call raises the same refusal before any local write. The refusal carries `detail: { axis, found, want }` and the
135
+ * two ways out its sentence names (`outs`): for a scope, that partition's own cursor or none before its first
136
+ * completed sync; for a peer, re-bind over a transport that reaches the cursor's peer, or drop the cursor; for an
137
+ * incarnation, re-bind against the state the baseline was taken against (setting `peerIncarnation` to `want` only
138
+ * for a cursor that carries none, over that same state), or drop the cursor; for a store, rebind the cursor to this
139
+ * store (its `store` set to `memorySyncStoreOf(backend)`) when this store holds the entries its baseline was taken
140
+ * over, or delete it and sync from none, which brings back an entry deleted on either side since the last completed
141
+ * sync. The engine takes none of them on the host's behalf; `memorySyncReportOf` reads the refusal for a host. */
93
142
  cursor?: MemorySyncCursor;
94
- /** Peer name for the cursor partition (defaults to the cursor's peer, else "central"). */
95
- peer?: string;
96
143
  /** Caller-injected clock (engine precedent) — stamps the returned cursor's updatedAtMs. */
97
144
  now?: () => number;
98
145
  /** push-half batching: cap the number of push-half ENTRIES sent this round. The full
@@ -153,9 +200,17 @@ export interface MemorySyncClientResult {
153
200
  * pulled) or, for an unknown id, a spurious push-half DELETE of an entry never seen here. */
154
201
  warnings?: string[];
155
202
  }
203
+ /** Does a name a sync carries verbatim (a peer identity, a target, a scope key) hold a credential — a URL with userinfo
204
+ * (any, a bare user name included: the slot is the credential's), or anything the same-principal egress pass would
205
+ * redact? Such a name is refused, never cleaned: a cleaned identity is another identity, and the cursor taken under it
206
+ * would not be this peer's. The userinfo is looked for wherever the string holds a URL's authority, not only at its head:
207
+ * a name that wraps a URL under another scheme (`proj:https://user@host/…`) parses as an opaque path, with no userinfo
208
+ * slot to read, yet it carries the same credential. The one test for the sync client and its report. */
209
+ export declare function carriesCredential(peer: string): boolean;
156
210
  /**
157
211
  * One full CLIENT sync round for one (scope, peer) against the central sync API — see the
158
212
  * module header for the ①-⑤ flow and the cursor retention discipline. Pure orchestration: all I/O
159
213
  * rides the injected backend/transport; the caller persists the returned cursor.
160
214
  */
161
215
  export declare function syncMemoryScope(opts: SyncMemoryScopeOptions): Promise<MemorySyncClientResult>;
216
+ export {};
@@ -6,45 +6,155 @@ import { reconcileMemoryEntries } from "./sync.js";
6
6
  import { MEMORY_ORIGIN_CAUSES } from "./types.js";
7
7
  import { directoryPinOf } from "./dual-root.js";
8
8
  import { landingPathOf } from "./layout.js";
9
- function syncRefusal(code, message) {
10
- const e = new Error(message);
11
- e.code = code;
9
+ import { egressText } from "../untrusted-egress.js";
10
+ import { REDACTION_MARKS } from "../redaction-marks.js";
11
+ const DROP_THE_CURSOR = "drop the cursor to accept re-convergence from an empty baseline — entries changed on both sides are reported as conflicts, " +
12
+ "and entries deleted on one side since the last round come back from the other side";
13
+ const REFUSAL_ROWS = {
14
+ scope: {
15
+ why: "a cursor is the baseline of one (scope, peer) partition",
16
+ outs: () => ["pass this partition's own cursor", "pass none before the partition's first completed round"],
17
+ },
18
+ peer: {
19
+ why: "a baseline taken elsewhere would misjudge every entry",
20
+ outs: (want) => [
21
+ "re-bind — run this layer over a transport that reaches the peer the cursor was taken against, or, " +
22
+ `only when this transport reaches that same peer under a new identity, set the cursor's peer to ${quoted(want)}`,
23
+ DROP_THE_CURSOR,
24
+ ],
25
+ },
26
+ incarnation: {
27
+ why: "the peer holds another state than the one the baseline was taken against and refused the round before writing, so nothing " +
28
+ "was written on either side — run on that baseline, an entry the peer lacks would land here as a delete and an older copy as a rollback",
29
+ outs: (want) => [
30
+ "re-bind — run this layer against the state the baseline was taken against, or, only when the cursor carries no incarnation " +
31
+ `(it was written before cursors carried one) and this peer holds that same state, set the cursor's peerIncarnation to ${quoted(want)}; ` +
32
+ "a cursor that carries another incarnation is never re-bound to this one",
33
+ DROP_THE_CURSOR,
34
+ ],
35
+ },
36
+ store: {
37
+ why: "its baseline describes another store's entries, so this round is refused, not run on that baseline or without one",
38
+ outs: () => [
39
+ "rebind — when this store holds the entries the baseline was taken over (the same store, moved to this root or bound before " +
40
+ "cursors carried a store), persist the cursor with its store set to this store's identity (memorySyncStoreOf) and sync again",
41
+ "clear — delete the cursor and sync from none, accepting that an entry deleted on either side since the last completed round " +
42
+ "comes back from the other side",
43
+ ],
44
+ },
45
+ "store-plane": {
46
+ why: "a sync baseline is bound to a File store's root, and this store has none",
47
+ outs: () => [
48
+ "sync the File store that holds this scope",
49
+ "leave this store out of the sync — a store with no directory is not a sync plane",
50
+ ],
51
+ },
52
+ };
53
+ const MINTED_REFUSALS = new WeakSet();
54
+ function syncRefusal(on, head, want) {
55
+ const row = REFUSAL_ROWS[on === "store-plane" ? on : on.axis];
56
+ const [first, second] = row.outs(want);
57
+ const outs = Object.freeze([egressText("same-principal", first), egressText("same-principal", second)]);
58
+ const e = new Error(egressText("same-principal", `memory sync: ${head} — ${row.why}; two ways out: (1) ${outs[0]}; (2) ${outs[1]}`));
59
+ if (on === "store-plane") {
60
+ e.code = "config.memory_sync_store";
61
+ }
62
+ else {
63
+ e.code = "config.memory_sync_cursor_mismatch";
64
+ e.detail = Object.freeze({ axis: on.axis, found: on.found, want: carriesCredential(want) ? REDACTION_MARKS.credentials : want });
65
+ }
66
+ e.outs = outs;
67
+ MINTED_REFUSALS.add(e);
12
68
  return e;
13
69
  }
70
+ export function readSyncRefusal(thrown) {
71
+ return typeof thrown === "object" && thrown !== null && MINTED_REFUSALS.has(thrown) ? thrown : undefined;
72
+ }
14
73
  export function memorySyncStoreOf(backend) {
15
74
  return syncStoreOf(backend).identity;
16
75
  }
17
76
  function syncStoreOf(backend) {
18
77
  const pin = directoryPinOf(backend);
19
78
  if (pin === undefined)
20
- throw syncRefusal("config.memory_sync_store", "memory sync: the local store has no directory — a sync baseline is bound to a File store's root, and this store has none");
79
+ throw syncRefusal("store-plane", "the local store has no directory", "");
21
80
  const root = landingPathOf(pin);
22
81
  return { root, identity: `file:${root}` };
23
82
  }
83
+ function cursorRefusal(axis, got, want) {
84
+ const found = got === undefined ? "absent" : "other";
85
+ const head = found === "absent" ? `cursor has no ${axis} binding` : `cursor is for ${axis} ${quoted(got)}`;
86
+ return syncRefusal({ axis, found }, `${head}; this round's ${axis} is ${quoted(want)}`, want);
87
+ }
24
88
  function refuseForeignCursor(cursor, scope, peer, store) {
25
89
  const axis = [["scope", cursor.scope, scope], ["peer", cursor.peer, peer], ["store", cursor.store, store]];
26
90
  for (const [name, got, want] of axis) {
27
- if (got === want)
28
- continue;
29
- const found = got === undefined ? `has no ${name} binding` : `is for ${name} ${JSON.stringify(typeof got === "string" ? got : typeof got)}`;
30
- throw syncRefusal("config.memory_sync_cursor_mismatch", `memory sync: cursor ${found}; this round's ${name} is ${JSON.stringify(want)} — a baseline taken elsewhere would misjudge every entry; run this round from no cursor`);
91
+ if (got !== want)
92
+ throw cursorRefusal(name, got, want);
31
93
  }
32
94
  }
95
+ function servesClaim(claim, baselineEmpty, incarnation) {
96
+ return claim !== undefined ? claim === incarnation : baselineEmpty;
97
+ }
33
98
  function memorySyncPath(scope) {
34
- return `/v1/memory/sync/${encodeURIComponent(scope)}`;
99
+ return `/v2/memory/sync/${encodeURIComponent(scope)}`;
35
100
  }
36
101
  function baselineStub(id, rev, scope) {
37
102
  return { id, rev, scope, slug: `sync-baseline-stub/${id}`, frontmatter: {}, body: "" };
38
103
  }
39
104
  const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
40
105
  const isNonEmptyString = (v) => typeof v === "string" && v.length > 0;
41
- function parseMemorySyncResponse(raw, scope, peer) {
106
+ const namesSomething = (v) => typeof v === "string" && v.trim().length > 0;
107
+ function quoted(v) {
108
+ if (typeof v !== "string")
109
+ return JSON.stringify(typeof v);
110
+ return carriesCredential(v) ? REDACTION_MARKS.credentials : JSON.stringify(v);
111
+ }
112
+ const isAsciiLetter = (c) => (c >= 65 && c <= 90) || (c >= 97 && c <= 122);
113
+ const isSchemeChar = (c) => isAsciiLetter(c) || (c >= 48 && c <= 57) || c === 43 || c === 45 || c === 46;
114
+ const SPECIAL_SCHEMES = new Set(["ftp", "file", "http", "https", "ws", "wss"]);
115
+ export function carriesCredential(peer) {
116
+ if (egressText("same-principal", peer) !== peer)
117
+ return true;
118
+ for (let mark = peer.indexOf("://"); mark !== -1; mark = peer.indexOf("://", mark + 3)) {
119
+ let from = mark;
120
+ while (from > 0 && isSchemeChar(peer.charCodeAt(from - 1)))
121
+ from--;
122
+ while (from < mark && !isAsciiLetter(peer.charCodeAt(from)))
123
+ from++;
124
+ if (from === mark)
125
+ continue;
126
+ const rest = peer.slice(mark + 3);
127
+ const end = rest.search(SPECIAL_SCHEMES.has(peer.slice(from, mark).toLowerCase()) ? /[\s/\\?#]/ : /[\s/?#]/);
128
+ const authority = end === -1 ? rest : rest.slice(0, end);
129
+ if (authority.lastIndexOf("@") > 0)
130
+ return true;
131
+ }
132
+ try {
133
+ const url = new URL(peer);
134
+ return url.username !== "" || url.password !== "";
135
+ }
136
+ catch {
137
+ return false;
138
+ }
139
+ }
140
+ const isIncarnation = (v) => namesSomething(v) && !carriesCredential(v);
141
+ function parseMemorySyncResponse(raw, scope, peer, claim, baselineEmpty) {
42
142
  const fail = (why) => {
43
- throw new Error(`memory sync: transport response is not a valid sync response (${why})`);
143
+ throw new Error(egressText("same-principal", `memory sync: transport response is not a valid sync response (${why})`));
44
144
  };
45
145
  if (!isRecord(raw))
46
146
  fail("body must be a JSON object { applied, conflicts, serverEntries, serverDeletes, cursor }");
47
147
  const b = raw;
148
+ if (Object.prototype.hasOwnProperty.call(b, "refused")) {
149
+ if (b["refused"] !== "baseline_incarnation")
150
+ fail(`refused must be "baseline_incarnation" — the one refusal a peer answers a sync with`);
151
+ const incarnation = b["incarnation"];
152
+ if (!isIncarnation(incarnation))
153
+ fail("a refusal's incarnation must be a non-empty string that holds no credential");
154
+ if (servesClaim(claim, baselineEmpty, incarnation))
155
+ fail(`the peer refused a sync its incarnation ${quoted(incarnation)} serves`);
156
+ throw cursorRefusal("incarnation", claim, incarnation);
157
+ }
48
158
  const applied = [];
49
159
  if (!Array.isArray(b["applied"]))
50
160
  fail("applied must be an array");
@@ -200,10 +310,18 @@ function parseMemorySyncResponse(raw, scope, peer) {
200
310
  }
201
311
  const cur = b["cursor"];
202
312
  if (!isRecord(cur))
203
- fail("cursor must be an object { peer, baseRevs, updatedAtMs }");
313
+ fail("cursor must be an object { peer, incarnation, baseRevs, updatedAtMs }");
204
314
  const curRec = cur;
205
315
  if (curRec["peer"] !== peer)
206
- fail(`cursor.peer ${JSON.stringify(curRec["peer"])} does not match the requested peer ${JSON.stringify(peer)}`);
316
+ fail(`cursor.peer ${quoted(curRec["peer"])} does not match the requested peer ${quoted(peer)}`);
317
+ const incarnation = curRec["incarnation"];
318
+ if (!isIncarnation(incarnation))
319
+ fail("cursor.incarnation must be a non-empty string that holds no credential — the incarnation of the state that answered");
320
+ if (!servesClaim(claim, baselineEmpty, incarnation)) {
321
+ fail(claim !== undefined
322
+ ? `cursor.incarnation ${quoted(incarnation)} does not match the requested peerIncarnation ${quoted(claim)}`
323
+ : `the request carried a non-empty baseline and no peerIncarnation, which a peer answers only by refusing it — not with a result under ${quoted(incarnation)}`);
324
+ }
207
325
  if (!isRecord(curRec["baseRevs"]))
208
326
  fail("cursor.baseRevs must be an object mapping id → rev");
209
327
  const baseRevs = {};
@@ -223,19 +341,29 @@ function parseMemorySyncResponse(raw, scope, peer) {
223
341
  conflicts,
224
342
  serverEntries,
225
343
  serverDeletes,
226
- cursor: { peer, baseRevs, updatedAtMs: updatedAtMs },
344
+ cursor: { peer, incarnation: incarnation, baseRevs, updatedAtMs: updatedAtMs },
227
345
  ...(pullTruncatedRaw === true ? { pullTruncated: true } : {}),
228
346
  };
229
347
  }
230
348
  export async function syncMemoryScope(opts) {
231
349
  const { backend, scope, transport, cursor } = opts;
232
- if (!isNonEmptyString(scope))
350
+ if (!namesSomething(scope))
233
351
  throw new Error("memory sync: scope must be a non-empty string");
234
- const peer = opts.peer ?? cursor?.peer ?? "central";
352
+ const peer = transport?.peer;
353
+ if (!namesSomething(peer))
354
+ throw new Error("memory sync: transport.peer must be a non-empty string — a transport is { peer, post }, peer = the identity of the peer it reaches");
355
+ if (carriesCredential(peer)) {
356
+ throw new Error(`memory sync: transport.peer ${quoted(peer)} carries a credential — the identity rides the wire, the cursor and refusal sentences verbatim, so it is never a credential: name the peer without userinfo or secret`);
357
+ }
235
358
  const now = opts.now ?? Date.now;
236
359
  const { root: storeRoot, identity: store } = syncStoreOf(backend);
237
360
  if (cursor !== undefined)
238
361
  refuseForeignCursor(cursor, scope, peer, store);
362
+ const claimed = cursor === undefined ? undefined : cursor.peerIncarnation;
363
+ if (claimed !== undefined && !isIncarnation(claimed)) {
364
+ throw new Error(`memory sync: cursor.peerIncarnation must be a non-empty string that holds no credential when present — it is the incarnation a peer answered a sync with, carried back verbatim`);
365
+ }
366
+ const claim = claimed;
239
367
  for (const [name, v] of [["maxPushEntries", opts.maxPushEntries], ["maxPullEntries", opts.maxPullEntries], ["maxEntryBytes", opts.maxEntryBytes]]) {
240
368
  if (v !== undefined && (!Number.isSafeInteger(v) || v < 1)) {
241
369
  throw new Error(`memory sync: ${name} must be a positive integer (>= 1) when set, got ${String(v)}`);
@@ -277,12 +405,13 @@ export async function syncMemoryScope(opts) {
277
405
  }
278
406
  const request = {
279
407
  peer,
408
+ ...(claim !== undefined ? { peerIncarnation: claim } : {}),
280
409
  baseRevs,
281
410
  entries: pushEntries,
282
411
  deletes: plan.deleteRemote.map((d) => d.id),
283
412
  ...(opts.maxPullEntries !== undefined ? { pull: { limit: opts.maxPullEntries } } : {}),
284
413
  };
285
- const resp = parseMemorySyncResponse(await transport(memorySyncPath(scope), request), scope, peer);
414
+ const resp = parseMemorySyncResponse(await transport.post(memorySyncPath(scope), request), scope, peer, claim, Object.keys(baseRevs).length === 0);
286
415
  const conflicts = [...pushGateConflicts, ...resp.conflicts.map((c) => ({ side: "server", ...c }))];
287
416
  const rejected = new Set();
288
417
  const localIds = new Set(local.map((e) => e.id));
@@ -411,7 +540,7 @@ export async function syncMemoryScope(opts) {
411
540
  nextBaseRevs[op.id] = landedRev;
412
541
  }
413
542
  }
414
- nextCursor = { scope, peer, store, baseRevs: nextBaseRevs, updatedAtMs: now() };
543
+ nextCursor = { scope, peer, peerIncarnation: resp.cursor.incarnation, store, baseRevs: nextBaseRevs, updatedAtMs: now() };
415
544
  }
416
545
  return {
417
546
  ok: cursorAdvanced && conflicts.length === 0,
@@ -0,0 +1,106 @@
1
+ import { type MemorySyncClientConflict, type MemorySyncClientResult } from "./sync-client.js";
2
+ import type { PatchReport } from "./types.js";
3
+ /** What a layer's calls landed, both halves, in call order (`serverApplied` / `localApplied` verbatim). A replayed
4
+ * call lands nothing and is still synced: whether a layer arrived is its `outcome`, never these counts. */
5
+ type LayerApplied = {
6
+ readonly server: PatchReport["applied"];
7
+ readonly local: PatchReport["applied"];
8
+ };
9
+ /** One layer of a memory sync — one scope, one outcome, and what all its calls landed. */
10
+ export type MemorySyncLayerReport = {
11
+ readonly scope: string;
12
+ readonly applied: LayerApplied;
13
+ } & ({
14
+ readonly outcome: "synced";
15
+ } | {
16
+ readonly outcome: "incomplete";
17
+ readonly why: "conflicts" | "truncated";
18
+ /** The last call's conflicts (server-reported and local), never hidden. */
19
+ readonly conflicts: readonly MemorySyncClientConflict[];
20
+ /** The answers the client refused to take from the server, as the call disclosed them. */
21
+ readonly warnings?: readonly string[];
22
+ } | {
23
+ readonly outcome: "refused";
24
+ readonly code: "config.memory_sync_cursor_mismatch" | "config.memory_sync_store";
25
+ /** Present on a cursor refusal: the axis it was refused on, whether the cursor carried no binding there
26
+ * (`absent`) or another one (`other`), and this call's value on it (`want`: the scope, the transport's peer,
27
+ * the local store's identity, or the incarnation of the peer state that answered — as the sentence shows it: one
28
+ * that holds a credential is the credentials mark alone). */
29
+ readonly detail?: {
30
+ readonly axis: "scope" | "peer" | "store" | "incarnation";
31
+ readonly found: "absent" | "other";
32
+ readonly want: string;
33
+ };
34
+ /** The two ways out the sentence names — both the host's to take, the engine takes neither. */
35
+ readonly outs: readonly [string, string];
36
+ readonly message: string;
37
+ } | {
38
+ readonly outcome: "failed";
39
+ readonly error: string;
40
+ });
41
+ /** A memory sync as a host reports it: the destination it was run for, the source revision it was run against, the
42
+ * source session's read set, and either its layers or its own refusal (no layer run, no request sent). */
43
+ export type MemorySyncRoundReport = {
44
+ /** The engine declaration the session goes to, as the host named it. */
45
+ readonly target: string;
46
+ /** The source session's revision the sync was run against, as the host named it. */
47
+ readonly sourceRevision: string;
48
+ /** The source session's read set — every scope key it reads, in its order. A scope with no layer was not synced. */
49
+ readonly scopes: readonly string[];
50
+ } & ({
51
+ readonly layers: readonly MemorySyncLayerReport[];
52
+ } | {
53
+ readonly refused: {
54
+ /** `config.memory_sync_target_mismatch`: the machine's sync reaches another peer than the engine the session
55
+ * goes to. `session_active`: the source session has a run in flight. */
56
+ readonly code: "config.memory_sync_target_mismatch" | "session_active";
57
+ readonly message: string;
58
+ };
59
+ });
60
+ /** One call of a layer as the host ran it: the scope, and how `syncMemoryScope` settled — its result or what it threw. */
61
+ type LayerCall = {
62
+ readonly scope: string;
63
+ } & ({
64
+ readonly result: MemorySyncClientResult;
65
+ } | {
66
+ readonly thrown: unknown;
67
+ });
68
+ /** A sync refused before any layer ran: the target mismatch carries the peer the machine's sync reaches (the sentence is
69
+ * minted here); a session in flight carries the host's own sentence for its code. */
70
+ type RoundRefusal = {
71
+ readonly code: "config.memory_sync_target_mismatch";
72
+ readonly reaches: string;
73
+ } | {
74
+ readonly code: "session_active";
75
+ readonly message: string;
76
+ };
77
+ type GapWhy = "refused" | "failed" | "incomplete" | "not_replicated" | "not_read_at_destination";
78
+ /**
79
+ * THE report of a memory sync — the one reading of how its `syncMemoryScope` calls settled, for every host that runs or
80
+ * relays one. Give it the destination (`target`), the source revision, the source session's read set (`scopes`), and
81
+ * either each call of each layer in the order they ran (`layers`; a layer continued after a cut appears once per call)
82
+ * or the sync's own refusal (`refused`; no layer ran). A layer outside the read set, a call carrying both or neither of
83
+ * `result` / `thrown`, or a name that is not a non-empty string is refused with a `TypeError`.
84
+ */
85
+ export declare function memorySyncReportOf(round: {
86
+ readonly target: string;
87
+ readonly sourceRevision: string;
88
+ readonly scopes: readonly string[];
89
+ } & ({
90
+ readonly layers: readonly LayerCall[];
91
+ } | {
92
+ readonly refused: RoundRefusal;
93
+ })): MemorySyncRoundReport;
94
+ /**
95
+ * What of a session's memory does not travel with it: every scope of the report's read set that did not arrive whole,
96
+ * once, with why — `refused` (the sync, or its layer's last call, was refused and wrote nothing on either side), `failed`, `incomplete`,
97
+ * `not_replicated` (no layer was run for it), or `not_read_at_destination` (its layer synced, and the destination's
98
+ * read set, when given, does not hold it). A scope absent from the result travelled. Keys are compared as written. A
99
+ * report that is not one this engine's `memorySyncReportOf` could have minted (a layer with no scope, outside the read
100
+ * set, listed twice, or with an outcome this engine does not read) is refused with a `TypeError`.
101
+ */
102
+ export declare function memoryTravelGapOf(report: MemorySyncRoundReport, readAtDestination?: readonly string[]): Array<{
103
+ readonly scope: string;
104
+ readonly why: GapWhy;
105
+ }>;
106
+ export {};
@@ -0,0 +1,119 @@
1
+ import { carriesCredential, readSyncRefusal } from "./sync-client.js";
2
+ import { egressText, egressThrownText } from "../untrusted-egress.js";
3
+ const OUTCOMES = new Set(["synced", "incomplete", "refused", "failed"]);
4
+ const text = (s) => egressText("same-principal", s);
5
+ function requireNamed(what, v) {
6
+ if (typeof v !== "string" || v.trim().length === 0)
7
+ throw new TypeError(`memory sync report: ${what} must be a non-empty string`);
8
+ if (carriesCredential(v))
9
+ throw new TypeError(`memory sync report: ${what} carries a credential — a name the report carries verbatim never does`);
10
+ return v;
11
+ }
12
+ const appliedOf = (ops) => ops.map((op) => (op.slug !== undefined ? { ...op, slug: text(op.slug) } : { ...op }));
13
+ function requireNames(what, v) {
14
+ if (!Array.isArray(v))
15
+ throw new TypeError(`memory sync report: ${what} must be an array of scope keys`);
16
+ const out = [];
17
+ for (const s of v) {
18
+ const key = requireNamed(`each of ${what}`, s);
19
+ if (!out.includes(key))
20
+ out.push(key);
21
+ }
22
+ return out;
23
+ }
24
+ function hasExactlyOne(v, a, b, what) {
25
+ const hasA = Object.prototype.hasOwnProperty.call(v, a);
26
+ if (hasA === Object.prototype.hasOwnProperty.call(v, b))
27
+ throw new TypeError(`memory sync report: ${what} carries exactly one of { ${a} } and { ${b} }`);
28
+ return hasA;
29
+ }
30
+ function callReport(call) {
31
+ const scope = call.scope;
32
+ if (!hasExactlyOne(call, "result", "thrown", `layer ${JSON.stringify(scope)}`)) {
33
+ const thrown = call.thrown;
34
+ const refusal = readSyncRefusal(thrown);
35
+ const applied = { server: [], local: [] };
36
+ if (refusal !== undefined) {
37
+ return { scope, outcome: "refused", applied, code: refusal.code, ...(refusal.detail !== undefined ? { detail: refusal.detail } : {}), outs: refusal.outs, message: refusal.message };
38
+ }
39
+ return { scope, outcome: "failed", applied, error: egressThrownText("same-principal", thrown) };
40
+ }
41
+ const r = call.result;
42
+ const applied = { server: appliedOf(r.serverApplied), local: appliedOf(r.localApplied) };
43
+ const warnings = (r.warnings ?? []).map(text);
44
+ if (r.ok && r.pushTruncated !== true && r.pullTruncated !== true && warnings.length === 0)
45
+ return { scope, outcome: "synced", applied };
46
+ return {
47
+ scope,
48
+ outcome: "incomplete",
49
+ why: r.ok ? "truncated" : "conflicts",
50
+ applied,
51
+ conflicts: r.conflicts.map((c) => ({ ...c, reason: text(c.reason) })),
52
+ ...(warnings.length > 0 ? { warnings } : {}),
53
+ };
54
+ }
55
+ function foldCall(before, next) {
56
+ return { ...next, applied: { server: [...before.applied.server, ...next.applied.server], local: [...before.applied.local, ...next.applied.local] } };
57
+ }
58
+ export function memorySyncReportOf(round) {
59
+ const target = requireNamed("target", round.target);
60
+ const sourceRevision = requireNamed("sourceRevision", round.sourceRevision);
61
+ const scopes = requireNames("scopes", round.scopes);
62
+ if (!hasExactlyOne(round, "layers", "refused", "a sync")) {
63
+ const refused = round.refused;
64
+ if (refused?.code === "config.memory_sync_target_mismatch") {
65
+ const reaches = requireNamed("refused.reaches", refused.reaches);
66
+ const message = text(`memory sync: the session goes to ${JSON.stringify(target)}, and this machine's memory sync reaches ${JSON.stringify(reaches)} — ` +
67
+ "no layer was synced: memory sent there would not be where the session reads it");
68
+ return { target, sourceRevision, scopes, refused: { code: refused.code, message } };
69
+ }
70
+ if (refused?.code === "session_active") {
71
+ return { target, sourceRevision, scopes, refused: { code: refused.code, message: text(requireNamed("refused.message", refused.message)) } };
72
+ }
73
+ throw new TypeError(`memory sync report: refused.code must be "config.memory_sync_target_mismatch" or "session_active"`);
74
+ }
75
+ const calls = round.layers;
76
+ if (!Array.isArray(calls))
77
+ throw new TypeError("memory sync report: layers must be an array");
78
+ const byScope = new Map();
79
+ for (const call of calls) {
80
+ const scope = requireNamed("each layer's scope", call?.scope);
81
+ if (!scopes.includes(scope))
82
+ throw new TypeError(`memory sync report: layer ${JSON.stringify(scope)} is not in the session's read set`);
83
+ const report = callReport(call);
84
+ const before = byScope.get(scope);
85
+ byScope.set(scope, before === undefined ? report : foldCall(before, report));
86
+ }
87
+ return { target, sourceRevision, scopes, layers: [...byScope.values()] };
88
+ }
89
+ export function memoryTravelGapOf(report, readAtDestination) {
90
+ if (typeof report !== "object" || report === null)
91
+ throw new TypeError("memory travel gap: report must be a memory sync report");
92
+ const scopes = requireNames("report.scopes", report.scopes);
93
+ const destination = readAtDestination === undefined ? undefined : new Set(requireNames("readAtDestination", readAtDestination));
94
+ if (!hasExactlyOne(report, "layers", "refused", "a sync report"))
95
+ return scopes.map((scope) => ({ scope, why: "refused" }));
96
+ const layers = report.layers;
97
+ if (!Array.isArray(layers))
98
+ throw new TypeError("memory travel gap: report.layers must be an array");
99
+ const byScope = new Map();
100
+ for (const layer of layers) {
101
+ const scope = requireNamed("each layer's scope", layer?.scope);
102
+ const outcome = layer.outcome;
103
+ if (!scopes.includes(scope) || byScope.has(scope) || typeof outcome !== "string" || !OUTCOMES.has(outcome)) {
104
+ throw new TypeError(`memory travel gap: layer ${JSON.stringify(scope)} is not one this engine reports (outside the read set, listed twice, or outcome ${JSON.stringify(outcome)})`);
105
+ }
106
+ byScope.set(scope, layer);
107
+ }
108
+ const gap = [];
109
+ for (const scope of scopes) {
110
+ const layer = byScope.get(scope);
111
+ if (layer === undefined)
112
+ gap.push({ scope, why: "not_replicated" });
113
+ else if (layer.outcome !== "synced")
114
+ gap.push({ scope, why: layer.outcome });
115
+ else if (destination !== undefined && !destination.has(scope))
116
+ gap.push({ scope, why: "not_read_at_destination" });
117
+ }
118
+ return gap;
119
+ }