@sema-agent/core 7.67.3 → 7.68.1

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 (501) hide show
  1. package/CHANGELOG.md +1537 -0
  2. package/README.md +18 -9
  3. package/README.zh-CN.md +16 -8
  4. package/dist/agents/agent-definition.d.ts +1 -1
  5. package/dist/agents/agent-definition.js +4 -1
  6. package/dist/agents/cascade.d.ts +2 -2
  7. package/dist/agents/cascade.js +3 -1
  8. package/dist/agents/cumulative-stats.d.ts +2 -1
  9. package/dist/agents/cumulative-stats.js +4 -1
  10. package/dist/agents/list-agents-tool.d.ts +30 -0
  11. package/dist/agents/list-agents-tool.js +45 -3
  12. package/dist/agents/peer-admission.d.ts +2 -2
  13. package/dist/agents/peer-session-drain.d.ts +2 -0
  14. package/dist/agents/peer-session-drain.js +1 -0
  15. package/dist/agents/repair-loop.js +3 -1
  16. package/dist/agents/retain-ledger.d.ts +61 -8
  17. package/dist/agents/retain-ledger.js +25 -3
  18. package/dist/agents/roster-store.d.ts +4 -2
  19. package/dist/agents/send-message-tool.d.ts +1 -1
  20. package/dist/agents/send-message-tool.js +20 -15
  21. package/dist/agents/subagent-steps.js +2 -10
  22. package/dist/agents/subagent.d.ts +3 -0
  23. package/dist/agents/subagent.js +106 -76
  24. package/dist/agents/tool-filter.d.ts +20 -11
  25. package/dist/agents/tool-filter.js +8 -4
  26. package/dist/agents/verify.d.ts +3 -1
  27. package/dist/agents/verify.js +2 -0
  28. package/dist/brain/anthropic.js +4 -4
  29. package/dist/brain/open-responses.js +3 -1
  30. package/dist/brain/openai.js +3 -1
  31. package/dist/brain/reasoning-request.d.ts +73 -19
  32. package/dist/brain/reasoning-request.js +164 -72
  33. package/dist/brain/reasoning-stamp.d.ts +26 -0
  34. package/dist/brain/reasoning-stamp.js +10 -0
  35. package/dist/brain/reasoning.d.ts +95 -162
  36. package/dist/brain/reasoning.js +31 -86
  37. package/dist/brain/route-adjudicator.d.ts +9 -7
  38. package/dist/brain/route-adjudicator.js +12 -10
  39. package/dist/brain/status-sink.d.ts +19 -64
  40. package/dist/brain/status-sink.js +5 -21
  41. package/dist/brain/stream-engine.d.ts +11 -2
  42. package/dist/brain/stream-engine.js +10 -0
  43. package/dist/core/a2a.d.ts +17 -5
  44. package/dist/core/a2a.js +11 -3
  45. package/dist/core/allow-entry.d.ts +35 -15
  46. package/dist/core/allow-entry.js +47 -60
  47. package/dist/core/ask-headline.d.ts +68 -0
  48. package/dist/core/ask-headline.js +23 -0
  49. package/dist/core/ask-origin.d.ts +36 -8
  50. package/dist/core/ask-origin.js +17 -10
  51. package/dist/core/ask-question.d.ts +34 -7
  52. package/dist/core/ask-question.js +10 -1
  53. package/dist/core/ask-unresolvable-notice.d.ts +7 -0
  54. package/dist/core/ask-unresolvable-notice.js +9 -3
  55. package/dist/core/auto-strip.d.ts +53 -0
  56. package/dist/core/auto-strip.js +76 -0
  57. package/dist/core/background-agent-store.d.ts +45 -5
  58. package/dist/core/background-agent-store.js +69 -15
  59. package/dist/core/background-shell.d.ts +2 -2
  60. package/dist/core/caller-text.js +2 -2
  61. package/dist/core/canonical-json.d.ts +13 -0
  62. package/dist/core/canonical-json.js +7 -0
  63. package/dist/core/checkpoint-features.d.ts +66 -20
  64. package/dist/core/checkpoint-features.js +12 -1
  65. package/dist/core/checkpoint-generation.d.ts +1 -1
  66. package/dist/core/checkpoint-queries.d.ts +1 -1
  67. package/dist/core/checkpoint-queries.js +4 -1
  68. package/dist/core/checkpoint-requirements.d.ts +45 -2
  69. package/dist/core/checkpoint-requirements.js +16 -6
  70. package/dist/core/checkpoint-row-verdict.d.ts +1 -0
  71. package/dist/core/checkpoint-row-verdict.js +4 -0
  72. package/dist/core/checkpoint-store.d.ts +66 -38
  73. package/dist/core/checkpoint-store.js +15 -6
  74. package/dist/core/child-clamp-seats.d.ts +6 -0
  75. package/dist/core/child-clamp-seats.js +1 -0
  76. package/dist/core/config-refusal-codes.d.ts +1 -1
  77. package/dist/core/config-refusal-codes.js +1 -0
  78. package/dist/core/delegation-frames.d.ts +9 -12
  79. package/dist/core/delegation-frames.js +9 -8
  80. package/dist/core/engine-capabilities.d.ts +21 -8
  81. package/dist/core/engine-capabilities.js +1 -1
  82. package/dist/core/engine-notice.d.ts +147 -34
  83. package/dist/core/engine-notice.js +27 -16
  84. package/dist/core/engine-storage-backend.d.ts +2 -1
  85. package/dist/core/env-budget.js +3 -3
  86. package/dist/core/env-knob-announce.d.ts +10 -10
  87. package/dist/core/env-knob-announce.js +3 -6
  88. package/dist/core/file-history-store.d.ts +29 -4
  89. package/dist/core/file-history-store.js +13 -0
  90. package/dist/core/frame-settlement.d.ts +2 -1
  91. package/dist/core/gate-fold.js +1 -1
  92. package/dist/core/gate-lanes.js +56 -49
  93. package/dist/core/governance-codes.d.ts +39 -3
  94. package/dist/core/governance-codes.js +61 -3
  95. package/dist/core/hooks.d.ts +29 -11
  96. package/dist/core/hooks.js +5 -2
  97. package/dist/core/human-input-projection.js +3 -3
  98. package/dist/core/input-author.d.ts +17 -3
  99. package/dist/core/input-author.js +15 -3
  100. package/dist/core/leg-identity.d.ts +10 -28
  101. package/dist/core/leg-identity.js +1 -21
  102. package/dist/core/lsp.d.ts +18 -13
  103. package/dist/core/lsp.js +30 -22
  104. package/dist/core/mailbox-store.d.ts +1 -1
  105. package/dist/core/mailbox-store.js +4 -4
  106. package/dist/core/mcp-connection-pool.d.ts +93 -4
  107. package/dist/core/mcp-connection-pool.js +104 -1
  108. package/dist/core/mcp-failure.d.ts +38 -12
  109. package/dist/core/mcp-failure.js +9 -13
  110. package/dist/core/mcp-probe.d.ts +4 -3
  111. package/dist/core/mcp-server-link.d.ts +4 -2
  112. package/dist/core/mcp-server-link.js +4 -5
  113. package/dist/core/mcp-server-spec.d.ts +3 -3
  114. package/dist/core/mcp-server-unavailable-notice.d.ts +22 -8
  115. package/dist/core/mcp-server-unavailable-notice.js +18 -4
  116. package/dist/core/mcp.d.ts +40 -6
  117. package/dist/core/mcp.js +39 -13
  118. package/dist/core/memory-engine/content-origin.js +2 -2
  119. package/dist/core/memory-engine/control-objects.d.ts +2 -4
  120. package/dist/core/memory-engine/control-objects.js +2 -10
  121. package/dist/core/memory-engine/delegation-settlement.js +6 -1
  122. package/dist/core/memory-engine/dual-root.js +3 -0
  123. package/dist/core/memory-engine/engine.d.ts +6 -4
  124. package/dist/core/memory-engine/engine.js +32 -29
  125. package/dist/core/memory-engine/file-backend.d.ts +20 -5
  126. package/dist/core/memory-engine/file-backend.js +21 -31
  127. package/dist/core/memory-engine/frontmatter.d.ts +2 -0
  128. package/dist/core/memory-engine/frontmatter.js +4 -0
  129. package/dist/core/memory-engine/layout.d.ts +114 -20
  130. package/dist/core/memory-engine/layout.js +340 -22
  131. package/dist/core/memory-engine/memory-deployment.d.ts +7 -5
  132. package/dist/core/memory-engine/mount-failed-notice.d.ts +19 -7
  133. package/dist/core/memory-engine/mount-failed-notice.js +43 -10
  134. package/dist/core/memory-engine/sync-client.js +4 -5
  135. package/dist/core/model-fallbacks.d.ts +5 -1
  136. package/dist/core/model-fallbacks.js +3 -3
  137. package/dist/core/model-receipt.d.ts +2 -1
  138. package/dist/core/model-receipt.js +12 -1
  139. package/dist/core/mods/kernel/dispatch.d.ts +2 -2
  140. package/dist/core/mods/kernel/dispatch.js +14 -6
  141. package/dist/core/mods/kernel/events.d.ts +8 -5
  142. package/dist/core/mods/kernel/events.js +2 -2
  143. package/dist/core/mods/kernel/index.d.ts +1 -1
  144. package/dist/core/mods/kernel/registration.d.ts +9 -0
  145. package/dist/core/mods/package.js +1 -1
  146. package/dist/core/mods/session-append.d.ts +4 -2
  147. package/dist/core/mods/session-append.js +3 -0
  148. package/dist/core/mods/stations.d.ts +7 -11
  149. package/dist/core/mods/stations.js +4 -7
  150. package/dist/core/mods/tool-call.d.ts +10 -8
  151. package/dist/core/mods/tool-call.js +15 -18
  152. package/dist/core/mounted-mcp.d.ts +0 -4
  153. package/dist/core/mounted-mcp.js +1 -1
  154. package/dist/core/park-noun.d.ts +24 -0
  155. package/dist/core/park-noun.js +21 -0
  156. package/dist/core/park-resumability.d.ts +60 -0
  157. package/dist/core/park-resumability.js +30 -0
  158. package/dist/core/permission-rule-provider.d.ts +24 -2
  159. package/dist/core/permission-rule-provider.js +11 -8
  160. package/dist/core/permission-rule-store.d.ts +8 -1
  161. package/dist/core/permission-rule-store.js +2 -3
  162. package/dist/core/permission-rules.d.ts +2 -1
  163. package/dist/core/permission-rules.js +8 -4
  164. package/dist/core/persisted-rule-arms.d.ts +3 -0
  165. package/dist/core/persisted-rule-arms.js +2 -1
  166. package/dist/core/present-plan-tool.d.ts +47 -3
  167. package/dist/core/present-plan-tool.js +62 -4
  168. package/dist/core/principal-name.d.ts +1 -1
  169. package/dist/core/principal-name.js +5 -5
  170. package/dist/core/process-identity.js +10 -5
  171. package/dist/core/protocol-http-auth.d.ts +20 -14
  172. package/dist/core/protocol-http-auth.js +70 -50
  173. package/dist/core/read-only-shell.js +9 -5
  174. package/dist/core/redaction-marks.d.ts +4 -26
  175. package/dist/core/redaction-marks.js +9 -21
  176. package/dist/core/remote-env.d.ts +43 -16
  177. package/dist/core/remote-env.js +1 -1
  178. package/dist/core/request-copy-projection.d.ts +1 -1
  179. package/dist/core/request-copy-projection.js +40 -50
  180. package/dist/core/resume-config-judge.js +1 -1
  181. package/dist/core/resume-startup-cause.d.ts +35 -18
  182. package/dist/core/resume-startup-cause.js +13 -10
  183. package/dist/core/retention.d.ts +167 -25
  184. package/dist/core/retention.js +100 -20
  185. package/dist/core/roles.d.ts +6 -0
  186. package/dist/core/roles.js +11 -5
  187. package/dist/core/rule-lane-reads.d.ts +3 -0
  188. package/dist/core/rule-lane-reads.js +5 -1
  189. package/dist/core/rule-store-fault.d.ts +70 -0
  190. package/dist/core/rule-store-fault.js +102 -0
  191. package/dist/core/runner/advertised-writable-dirs.js +16 -31
  192. package/dist/core/runner/announce-once-ledger.d.ts +19 -2
  193. package/dist/core/runner/announce-once-ledger.js +24 -2
  194. package/dist/core/runner/assemble-result.d.ts +6 -0
  195. package/dist/core/runner/assemble-result.js +1 -1
  196. package/dist/core/runner/auto-strip-notice.d.ts +36 -0
  197. package/dist/core/runner/auto-strip-notice.js +59 -0
  198. package/dist/core/runner/branch-window.d.ts +3 -0
  199. package/dist/core/runner/branch-window.js +37 -0
  200. package/dist/core/runner/caller-roster.d.ts +8 -3
  201. package/dist/core/runner/capability-withheld-seat.js +3 -9
  202. package/dist/core/runner/clock-and-limits.d.ts +22 -1
  203. package/dist/core/runner/clock-and-limits.js +30 -0
  204. package/dist/core/runner/contracts.d.ts +58 -35
  205. package/dist/core/runner/credential-refusal-seat.d.ts +2 -0
  206. package/dist/core/runner/credential-refusal-seat.js +47 -0
  207. package/dist/core/runner/cross-boundary-lane.js +6 -4
  208. package/dist/core/runner/decide-continuation.js +1 -1
  209. package/dist/core/runner/file-history-restore.d.ts +53 -2
  210. package/dist/core/runner/file-history-restore.js +29 -10
  211. package/dist/core/runner/forward-sink.d.ts +14 -1
  212. package/dist/core/runner/forward-sink.js +14 -12
  213. package/dist/core/runner/gate-exit.d.ts +8 -7
  214. package/dist/core/runner/gate-exit.js +13 -13
  215. package/dist/core/runner/git-status-frame.js +2 -4
  216. package/dist/core/runner/initial-run-state.js +1 -1
  217. package/dist/core/runner/main-call-account.d.ts +3 -1
  218. package/dist/core/runner/main-call-account.js +5 -3
  219. package/dist/core/runner/mcp-redial.d.ts +2 -5
  220. package/dist/core/runner/mcp-redial.js +2 -2
  221. package/dist/core/runner/nested-memory-content.d.ts +7 -1
  222. package/dist/core/runner/nested-memory-content.js +73 -13
  223. package/dist/core/runner/nested-memory-lane.d.ts +44 -19
  224. package/dist/core/runner/nested-memory-lane.js +152 -76
  225. package/dist/core/runner/park-commit.js +3 -1
  226. package/dist/core/runner/permission-rule-lanes.d.ts +8 -2
  227. package/dist/core/runner/permission-rule-lanes.js +29 -3
  228. package/dist/core/runner/person-path-rows.d.ts +3 -11
  229. package/dist/core/runner/person-path-rows.js +21 -24
  230. package/dist/core/runner/prepare-acquire-reconcile.js +3 -1
  231. package/dist/core/runner/prepare-artifact.d.ts +1 -1
  232. package/dist/core/runner/prepare-artifact.js +20 -14
  233. package/dist/core/runner/prepare-ask-lane.d.ts +9 -6
  234. package/dist/core/runner/prepare-ask-lane.js +6 -5
  235. package/dist/core/runner/prepare-boundary-parks.d.ts +7 -1
  236. package/dist/core/runner/prepare-boundary-parks.js +27 -24
  237. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -2
  238. package/dist/core/runner/prepare-caps-and-workflow.js +4 -3
  239. package/dist/core/runner/prepare-config-doors.d.ts +9 -24
  240. package/dist/core/runner/prepare-config-doors.js +58 -41
  241. package/dist/core/runner/prepare-context-lane.d.ts +2 -2
  242. package/dist/core/runner/prepare-context-lane.js +3 -5
  243. package/dist/core/runner/prepare-defer-classify.d.ts +1 -1
  244. package/dist/core/runner/prepare-defer-classify.js +1 -1
  245. package/dist/core/runner/prepare-delegation-surface.d.ts +2 -2
  246. package/dist/core/runner/prepare-delegation-surface.js +3 -2
  247. package/dist/core/runner/prepare-file-history.d.ts +62 -26
  248. package/dist/core/runner/prepare-file-history.js +117 -46
  249. package/dist/core/runner/prepare-gate-stations.d.ts +4 -0
  250. package/dist/core/runner/prepare-gate-stations.js +6 -5
  251. package/dist/core/runner/prepare-hands-readface.d.ts +9 -4
  252. package/dist/core/runner/prepare-hands-readface.js +8 -4
  253. package/dist/core/runner/prepare-inherited-gate.d.ts +11 -4
  254. package/dist/core/runner/prepare-inherited-gate.js +6 -6
  255. package/dist/core/runner/prepare-listings.d.ts +1 -1
  256. package/dist/core/runner/prepare-listings.js +1 -1
  257. package/dist/core/runner/prepare-memory.js +2 -2
  258. package/dist/core/runner/prepare-offload-wrappers.d.ts +1 -1
  259. package/dist/core/runner/prepare-offload-wrappers.js +1 -1
  260. package/dist/core/runner/prepare-park-ask.d.ts +10 -3
  261. package/dist/core/runner/prepare-park-ask.js +7 -9
  262. package/dist/core/runner/prepare-policy-chain.d.ts +18 -9
  263. package/dist/core/runner/prepare-policy-chain.js +18 -13
  264. package/dist/core/runner/prepare-project-context.d.ts +1 -1
  265. package/dist/core/runner/prepare-project-context.js +5 -3
  266. package/dist/core/runner/prepare-prompt-assembly.js +2 -1
  267. package/dist/core/runner/prepare-prompt-inputs.d.ts +2 -2
  268. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  269. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -5
  270. package/dist/core/runner/prepare-protocol-tools.js +7 -7
  271. package/dist/core/runner/prepare-question-face.d.ts +4 -2
  272. package/dist/core/runner/prepare-run-refs.d.ts +7 -2
  273. package/dist/core/runner/prepare-run-refs.js +8 -7
  274. package/dist/core/runner/prepare-safety-scan.d.ts +4 -3
  275. package/dist/core/runner/prepare-suspend-saga.d.ts +3 -7
  276. package/dist/core/runner/prepare-suspend-saga.js +4 -3
  277. package/dist/core/runner/prepare-task.js +66 -53
  278. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +3 -2
  279. package/dist/core/runner/prepare-tool-disclosure-mount.js +2 -1
  280. package/dist/core/runner/prepare-turn-wiring.d.ts +3 -1
  281. package/dist/core/runner/prepare-turn-wiring.js +1 -1
  282. package/dist/core/runner/prepare-wiring-manifest.d.ts +9 -4
  283. package/dist/core/runner/prepare-wiring-manifest.js +14 -6
  284. package/dist/core/runner/prepare-workspace-restore.d.ts +4 -4
  285. package/dist/core/runner/prepare-workspace-restore.js +15 -6
  286. package/dist/core/runner/remote-env-retry.d.ts +3 -3
  287. package/dist/core/runner/restore-seat.d.ts +41 -0
  288. package/dist/core/runner/restore-seat.js +38 -0
  289. package/dist/core/runner/resume-admission.js +1 -1
  290. package/dist/core/runner/resume-apply.js +4 -3
  291. package/dist/core/runner/resume-checkpoint-screen.js +2 -1
  292. package/dist/core/runner/resume-internals-and-config.js +2 -1
  293. package/dist/core/runner/resume-preflight.js +2 -1
  294. package/dist/core/runner/rewind-files.js +22 -6
  295. package/dist/core/runner/rule-store-unreadable-notice.d.ts +8 -0
  296. package/dist/core/runner/rule-store-unreadable-notice.js +11 -0
  297. package/dist/core/runner/run-brain-sinks.d.ts +3 -6
  298. package/dist/core/runner/run-brain-sinks.js +6 -6
  299. package/dist/core/runner/run-compaction-machinery.d.ts +2 -2
  300. package/dist/core/runner/run-git-lane.d.ts +2 -0
  301. package/dist/core/runner/run-git-lane.js +2 -1
  302. package/dist/core/runner/run-harness-handlers.js +5 -4
  303. package/dist/core/runner/run-identity-wiring.js +20 -12
  304. package/dist/core/runner/run-leg.js +31 -72
  305. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  306. package/dist/core/runner/run-notification-lane.js +2 -4
  307. package/dist/core/runner/run-reasoning-seat.d.ts +5 -6
  308. package/dist/core/runner/run-reasoning-seat.js +13 -18
  309. package/dist/core/runner/run-settle-and-teardown.js +13 -9
  310. package/dist/core/runner/run-terminal-adoption.js +4 -8
  311. package/dist/core/runner/run-turn-boundary.js +6 -3
  312. package/dist/core/runner/runtask.d.ts +9 -4
  313. package/dist/core/runner/runtask.js +29 -22
  314. package/dist/core/runner/session-rule-policy.d.ts +11 -1
  315. package/dist/core/runner/shell-env-withheld.js +2 -7
  316. package/dist/core/runner/side-call-account.d.ts +5 -6
  317. package/dist/core/runner/side-call-account.js +2 -2
  318. package/dist/core/runner/stream-lifecycle-verbs.d.ts +3 -0
  319. package/dist/core/runner/stream-lifecycle-verbs.js +5 -3
  320. package/dist/core/runner/stream-settle-backstop.js +4 -6
  321. package/dist/core/runner/stream-steer-verb.d.ts +1 -1
  322. package/dist/core/runner/stream-steer-verb.js +4 -4
  323. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -3
  324. package/dist/core/runner/sub-agent-deny-lists.js +7 -4
  325. package/dist/core/runner/teardown-bounded.d.ts +7 -0
  326. package/dist/core/runner/teardown-bounded.js +7 -0
  327. package/dist/core/runner/terminal-account.js +41 -13
  328. package/dist/core/runner/terminal-projection.d.ts +1 -5
  329. package/dist/core/runner/tool-end-body.d.ts +9 -3
  330. package/dist/core/runner/tool-end-body.js +6 -3
  331. package/dist/core/runner/tool-output-projection.d.ts +13 -4
  332. package/dist/core/runner/tool-output-projection.js +10 -14
  333. package/dist/core/runner/turn-attachments.d.ts +3 -2
  334. package/dist/core/runner/turn-attachments.js +12 -5
  335. package/dist/core/runner-deps.d.ts +6 -6
  336. package/dist/core/runtime-caps.d.ts +2 -1
  337. package/dist/core/secret-env.d.ts +20 -3
  338. package/dist/core/secret-env.js +13 -15
  339. package/dist/core/session-checkout.d.ts +115 -15
  340. package/dist/core/session-checkout.js +435 -136
  341. package/dist/core/session-policy-store.js +21 -3
  342. package/dist/core/session-reconcile.js +1 -0
  343. package/dist/core/session-store.js +2 -0
  344. package/dist/core/session.d.ts +11 -1
  345. package/dist/core/shell-run-candidates.d.ts +1 -0
  346. package/dist/core/shell-run-candidates.js +1 -1
  347. package/dist/core/shutdown-debug.d.ts +6 -5
  348. package/dist/core/shutdown-debug.js +5 -1
  349. package/dist/core/skill-grant.js +4 -1
  350. package/dist/core/skills-directory.js +5 -3
  351. package/dist/core/spec-contract.d.ts +1 -1
  352. package/dist/core/store-contracts/checkpoint-store-contract.js +2 -7
  353. package/dist/core/store-contracts/file-history-store-contract.js +26 -2
  354. package/dist/core/store-contracts/session-deletion-cascade-contract.js +130 -14
  355. package/dist/core/store-contracts/task-list-store-contract.d.ts +2 -1
  356. package/dist/core/store-contracts/task-list-store-contract.js +28 -1
  357. package/dist/core/task-event.d.ts +48 -27
  358. package/dist/core/task-notification.d.ts +15 -9
  359. package/dist/core/task-notification.js +12 -0
  360. package/dist/core/task-registry-agent.d.ts +24 -22
  361. package/dist/core/task-registry-agent.js +65 -46
  362. package/dist/core/task-registry-shared.d.ts +17 -5
  363. package/dist/core/task-registry.d.ts +17 -6
  364. package/dist/core/task-registry.js +6 -1
  365. package/dist/core/task-result.d.ts +71 -25
  366. package/dist/core/task-spec-members.d.ts +0 -1
  367. package/dist/core/task-spec-members.js +1 -1
  368. package/dist/core/task-spec.d.ts +60 -52
  369. package/dist/core/task-stream.d.ts +45 -12
  370. package/dist/core/terminal-cause.d.ts +45 -8
  371. package/dist/core/terminal-cause.js +5 -0
  372. package/dist/core/tool-card-bound.d.ts +32 -0
  373. package/dist/core/tool-card-bound.js +33 -0
  374. package/dist/core/tool-catalog-entries.d.ts +9 -0
  375. package/dist/core/tool-catalog-entries.js +48 -0
  376. package/dist/core/tool-errors.d.ts +4 -3
  377. package/dist/core/tool-face.d.ts +3 -3
  378. package/dist/core/tool-mount-facts.d.ts +3 -2
  379. package/dist/core/tool-mount-facts.js +1 -1
  380. package/dist/core/tool-mount-static.js +7 -5
  381. package/dist/core/tool-policy.d.ts +21 -19
  382. package/dist/core/tool-policy.js +5 -6
  383. package/dist/core/tool-registry.d.ts +3 -1
  384. package/dist/core/tool-registry.js +15 -1
  385. package/dist/core/tool-result-store.d.ts +9 -3
  386. package/dist/core/tool-result-store.js +14 -1
  387. package/dist/core/tool-roster.d.ts +18 -0
  388. package/dist/core/tool-roster.js +30 -1
  389. package/dist/core/tool-spec.d.ts +17 -8
  390. package/dist/core/trace.d.ts +35 -31
  391. package/dist/core/types.d.ts +2 -2
  392. package/dist/core/untrusted-egress.d.ts +10 -9
  393. package/dist/core/untrusted-egress.js +9 -9
  394. package/dist/core/untrusted-text.d.ts +0 -18
  395. package/dist/core/untrusted-text.js +7 -3
  396. package/dist/core/user-attachment.d.ts +9 -6
  397. package/dist/core/user-attachment.js +12 -10
  398. package/dist/core/user-row-origin.d.ts +44 -25
  399. package/dist/core/user-row-origin.js +30 -20
  400. package/dist/core/wiring-manifest.d.ts +26 -7
  401. package/dist/core/wiring-manifest.js +14 -11
  402. package/dist/core/workspace-snapshot.d.ts +3 -1
  403. package/dist/core/workspace-snapshot.js +1 -0
  404. package/dist/engine/execution-env/node-execution-env.d.ts +23 -16
  405. package/dist/engine/execution-env/node-execution-env.js +127 -67
  406. package/dist/engine/harness/agent-harness.d.ts +4 -5
  407. package/dist/engine/harness/agent-harness.js +2 -7
  408. package/dist/engine/harness/types.d.ts +51 -19
  409. package/dist/engine/harness/types.js +28 -1
  410. package/dist/engine/llm/types.d.ts +26 -14
  411. package/dist/engine/llm/types.js +2 -2
  412. package/dist/engine/loop/agent-loop.d.ts +2 -2
  413. package/dist/engine/loop/agent-loop.js +51 -275
  414. package/dist/engine/loop/types.d.ts +0 -18
  415. package/dist/engine/session/import-validate.d.ts +3 -0
  416. package/dist/engine/session/import-validate.js +34 -2
  417. package/dist/engine/session/repo-utils.d.ts +42 -4
  418. package/dist/engine/session/repo-utils.js +33 -5
  419. package/dist/engine/session/session.d.ts +41 -14
  420. package/dist/engine/session/session.js +96 -25
  421. package/dist/index.d.ts +21 -16
  422. package/dist/index.js +16 -10
  423. package/dist/orchestration/run-spec.d.ts +1 -1
  424. package/dist/orchestration/run-workflow-tool.d.ts +12 -9
  425. package/dist/orchestration/run-workflow-tool.js +15 -19
  426. package/dist/orchestration/workflow-governance.js +13 -21
  427. package/dist/orchestration/workflow-observe.d.ts +4 -3
  428. package/dist/orchestration/workflow-primitives.d.ts +1 -1
  429. package/dist/orchestration/workflow-record-artifact.d.ts +14 -0
  430. package/dist/orchestration/workflow-record-artifact.js +32 -0
  431. package/dist/orchestration/workflow-script-store.d.ts +9 -0
  432. package/dist/orchestration/workflow-script-store.js +20 -1
  433. package/dist/orchestration/workflow-types.d.ts +33 -3
  434. package/dist/orchestration/workflow.d.ts +24 -14
  435. package/dist/orchestration/workflow.js +52 -23
  436. package/dist/prompt-assembly/artifact.js +4 -8
  437. package/dist/prompt-assembly/catalog/engine.d.ts +263 -0
  438. package/dist/prompt-assembly/catalog/engine.js +30 -0
  439. package/dist/prompt-assembly/catalog/index.d.ts +1 -1
  440. package/dist/prompt-assembly/catalog/index.js +2 -2
  441. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.d.ts +1 -1
  442. package/dist/prompt-assembly/catalog/locales/zh-Hans/engine.js +29 -0
  443. package/dist/prompt-assembly/epoch.js +6 -8
  444. package/dist/prompt-assembly/turn-snapshot.js +8 -9
  445. package/dist/stores/file/background-agent-store.js +5 -6
  446. package/dist/stores/file/checkpoint-store.d.ts +0 -4
  447. package/dist/stores/file/checkpoint-store.js +7 -3
  448. package/dist/stores/file/file-history-store.d.ts +8 -0
  449. package/dist/stores/file/file-history-store.js +72 -0
  450. package/dist/stores/file/fs-atomic.js +17 -12
  451. package/dist/stores/file/index.js +11 -5
  452. package/dist/stores/file/mailbox-store.js +13 -4
  453. package/dist/stores/file/permission-rule-store.js +14 -13
  454. package/dist/stores/file/shared-ledger.d.ts +4 -0
  455. package/dist/stores/file/shared-ledger.js +4 -0
  456. package/dist/stores/file/task-list-store.js +12 -3
  457. package/dist/stores/file/workflow-run-store.js +1 -0
  458. package/dist/tools/fs/bash-program-position.d.ts +4 -2
  459. package/dist/tools/fs/bash-program-position.js +1 -1
  460. package/dist/tools/fs/bash-readonly-classifier.js +1 -1
  461. package/dist/tools/fs/bound-open.d.ts +97 -0
  462. package/dist/tools/fs/bound-open.js +103 -0
  463. package/dist/tools/fs/containment-face.d.ts +2 -2
  464. package/dist/tools/fs/fs-pdf.d.ts +7 -1
  465. package/dist/tools/fs/fs-pdf.js +31 -23
  466. package/dist/tools/fs/fs-read.d.ts +24 -17
  467. package/dist/tools/fs/fs-read.js +84 -53
  468. package/dist/tools/fs/fs-shared.d.ts +14 -12
  469. package/dist/tools/fs/fs-shared.js +5 -4
  470. package/dist/tools/fs/fs-write.d.ts +2 -2
  471. package/dist/tools/fs/fs-write.js +20 -12
  472. package/dist/tools/fs/index.d.ts +4 -4
  473. package/dist/tools/fs/index.js +2 -2
  474. package/dist/tools/fs/notebook.d.ts +1 -1
  475. package/dist/tools/fs/pdf.d.ts +12 -3
  476. package/dist/tools/fs/pdf.js +22 -9
  477. package/dist/tools/fs/read-deny-home.d.ts +3 -2
  478. package/dist/tools/fs/read-deny-home.js +8 -11
  479. package/dist/tools/fs/safety.d.ts +3 -2
  480. package/dist/tools/fs/shell-read-check.js +10 -9
  481. package/dist/tools/monitor.d.ts +6 -5
  482. package/dist/tools/task-list.d.ts +16 -6
  483. package/dist/tools/task-list.js +4 -0
  484. package/dist/tools/web.d.ts +9 -1
  485. package/dist/tools/web.js +8 -3
  486. package/dist/tools/worktree.d.ts +7 -5
  487. package/dist/tools/worktree.js +4 -3
  488. package/package.json +4 -3
  489. package/test/export-surface.snapshot.json +93 -7
  490. package/wire-changes/core-stores-sql@7.68.0.json +39 -0
  491. package/wire-changes/core-stores-sql@7.68.1.json +39 -0
  492. package/wire-changes/core@7.68.0.json +4257 -0
  493. package/wire-changes/core@7.68.1.json +95 -0
  494. package/wire-changes/mods-kernel@7.68.0.json +129 -0
  495. package/wire-changes/mods-kernel@7.68.1.json +39 -0
  496. package/wire-changes/primitives@7.68.0.json +253 -0
  497. package/wire-changes/primitives@7.68.1.json +39 -0
  498. package/wire-changes/wiki-gate@7.68.0.json +39 -0
  499. package/wire-changes/wiki-gate@7.68.1.json +39 -0
  500. package/dist/core/runner/credential-origin-seat.d.ts +0 -2
  501. package/dist/core/runner/credential-origin-seat.js +0 -20
@@ -64,9 +64,27 @@ function isStoredRow(value) {
64
64
  return typeof rev === "number" && Number.isInteger(rev) && rev >= 1;
65
65
  }
66
66
  function grammarOf(value) {
67
- const stamp = value.grammar;
67
+ const member = stampMemberOf(value);
68
+ if (member.kind === "not_own_data") {
69
+ return {
70
+ got: member.got,
71
+ sentence: `session rules carry a grammar stamp that is ${member.got} — grammar must be an own data member of the rules (the whole number of the rule grammar the entries are written in): ` +
72
+ `an accessor is never called, and an inherited or non-enumerable member is not the value's own stamp`,
73
+ };
74
+ }
75
+ const stamp = member.kind === "data" ? member.stamp : undefined;
68
76
  return readRuleGrammarStamp(stamp, stamp === undefined && isStoredRow(value) ? 0 : SESSION_RULES_GRAMMAR, { rules: "session rules", held: "entries" });
69
77
  }
78
+ function stampMemberOf(value) {
79
+ const own = Object.getOwnPropertyDescriptor(value, "grammar");
80
+ if (own === undefined)
81
+ return "grammar" in value ? { kind: "not_own_data", got: "an inherited member" } : { kind: "absent" };
82
+ if (!("value" in own))
83
+ return { kind: "not_own_data", got: "an accessor" };
84
+ if (own.enumerable !== true)
85
+ return { kind: "not_own_data", got: "a non-enumerable member" };
86
+ return own.value === undefined ? { kind: "absent" } : { kind: "data", stamp: own.value };
87
+ }
70
88
  export function readRuleGrammarStamp(stamp, absent, words) {
71
89
  if (stamp === undefined)
72
90
  return { grammar: absent };
@@ -128,7 +146,7 @@ function readOperatorPart(value) {
128
146
  return { fault: { field, got: read.fault.got }, sentence: `the session rules' operator part: ${read.sentence}` };
129
147
  }
130
148
  const { operatorRules: nested, ...part } = read.rules;
131
- const unstamped = value.grammar === undefined;
149
+ const unstamped = stampMemberOf(value).kind === "absent";
132
150
  if (unstamped || nested !== undefined) {
133
151
  const got = unstamped ? "rules without a grammar stamp" : "an operator part of its own";
134
152
  return { fault: { field: OPERATOR_PART, got }, sentence: `session rules carry an operator part holding ${got} — the part is the rules the last operator write set, stamped with their grammar by the write judge` };
@@ -450,7 +468,7 @@ function assertEntriesRead(rules, mountedToolNames) {
450
468
  function refuseUndeclaredGrammar(rules) {
451
469
  if (typeof rules !== "object" || rules === null || Array.isArray(rules))
452
470
  return;
453
- if (rules.grammar !== undefined)
471
+ if (stampMemberOf(rules).kind !== "absent")
454
472
  return;
455
473
  throw new SessionPolicyError("grammar_required", `session rules carry no grammar stamp — a write declares the rule grammar its entries are written in (grammar: ${SESSION_RULES_GRAMMAR} is the grammar this engine reads; ` +
456
474
  `a stored row handed back keeps its own stamp, and one stored before the stamp was written in grammar 0); nothing was written`);
@@ -96,6 +96,7 @@ export async function appendInterruptionMarker(session, opts) {
96
96
  },
97
97
  ],
98
98
  provenance: "engine-note",
99
+ origin: "interruption_marker",
99
100
  timestamp: Date.now(),
100
101
  });
101
102
  }
@@ -267,6 +267,8 @@ export class TtlSessionStore {
267
267
  ...(view?.lastTaskId !== undefined ? { lastTaskId: view.lastTaskId } : {}),
268
268
  ...(view?.lastTaskRunId !== undefined ? { lastTaskRunId: view.lastTaskRunId } : {}),
269
269
  ...(forkedFrom !== undefined ? { forkedFrom } : {}),
270
+ incarnation: row.incarnation ?? null,
271
+ forkedFromIncarnation: row.forkedFrom !== undefined ? (row.forkedFromIncarnation ?? null) : null,
270
272
  };
271
273
  }
272
274
  async fork(sourceId, owner, opts) {
@@ -127,6 +127,14 @@ export interface SessionStoreSummary {
127
127
  * Lets a consumer render/reap fork lineage; absent on non-forked sessions and on cache views that
128
128
  * predate the fork. The durable source of truth is the repo's persisted metadata. */
129
129
  forkedFrom?: string;
130
+ /** The row's occupant cell ({@link SessionMetadata.incarnation}), `null` when the row has none — read in the same row read as
131
+ * {@link forkedFrom}. With the session id it names the row's file-history scope (`fileHistoryScopeOf`), which a deletion cascade
132
+ * computes for each fork it carries history into. Store-interface material only: a service never puts it on the wire. */
133
+ incarnation: string | null;
134
+ /** The occupant of {@link forkedFrom} the fork was cut from ({@link SessionMetadata.forkedFromIncarnation}), `null` when the row
135
+ * records none (not a fork, or a fork cut before rows named their occupants) — read in the same row read as {@link forkedFrom}. With
136
+ * `forkedFrom` it names the source's history address the fork carries from. Store-interface material only, never on the wire. */
137
+ forkedFromIncarnation: string | null;
130
138
  }
131
139
  /** The page bounds of {@link SessionStore.list}: a query without `limit` reads `default` rows; an explicit `limit` is an integer in
132
140
  * 1..`max`. */
@@ -412,7 +420,9 @@ export interface SessionStore<S extends SessionStoreSummary = SessionStoreSummar
412
420
  * write refused `log_closed` — the deletion does not wait for children. A store wired with {@link SessionStoreHooks.beforeSessionDelete}
413
421
  * runs it first, only for a row it read as unreadable, and deletes nothing when it rejects (the call rejects with it). An id that is not
414
422
  * a non-empty string is refused (`config.invalid_argument`) before anything is read. Nothing automatic calls it (idle sweep, release,
415
- * retention). **Optional**: absent = this store cannot remove an unreadable row (its repo cannot, or its rows cannot be unreadable).
423
+ * retention). It is the session row's leg of {@link import("./retention.js").RETENTION_CASCADE} for such a session (the leg's `unreadable`
424
+ * verb) and, like {@link delete}, touches no other store: an operator who deletes the session runs the table's legs with it, not this
425
+ * call alone. **Optional**: absent = this store cannot remove an unreadable row (its repo cannot, or its rows cannot be unreadable).
416
426
  */
417
427
  deleteUnreadable?(sessionId: string): Promise<boolean>;
418
428
  /** Number of live/cached sessions (best-effort). */
@@ -86,6 +86,7 @@ export interface ShellCommandShape {
86
86
  readonly strayRedirection: boolean;
87
87
  }
88
88
  export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-table.js";
89
+ export declare const DURATION_RE: RegExp;
89
90
  /** Longer than this and the command is not read at all (one unreadable segment). Upstream's own reader stops at the
90
91
  * same size. */
91
92
  export declare const MAX_SHELL_READ_CHARS = 10000;
@@ -9,7 +9,7 @@ const PREFIX_KEYWORDS = shellWordsOf("stripped_prefix");
9
9
  const CLOSING_KEYWORDS = shellWordsOf("stripped_standalone");
10
10
  const OPAQUE_KEYWORDS = shellWordsOf("opaque");
11
11
  const CONTROL_PREFIXES = shellWordsOf("control_prefix");
12
- const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
12
+ export const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
13
13
  export const MAX_SHELL_READ_CHARS = 10_000;
14
14
  const LEXED_WORDS = new WeakMap();
15
15
  export function lexedWordOf(w) {
@@ -1,7 +1,8 @@
1
- /** shutdown forensics — opt-in (`SEMA_DEBUG_SHUTDOWN=1`) stderr trace of every
2
- * teardown kill/reap action. stderr lands in the host's engine log, so a "who killed my process"
3
- * hunt no longer dead-ends at the drain marker with zero shutdown-phase evidence (test-line pain,
4
- * three times — the reap lane was the blind spot of the first cut).
1
+ /** shutdown forensics — opt-in (`SEMA_DEBUG_SHUTDOWN=1`) trace of every teardown kill/reap action, said as
2
+ * `engine.debug_trace` (`detail.topic: "shutdown"`) on the process's default notice seat, else as one process line.
3
+ * The line lands in the host's engine log, so a "who killed my process" hunt no longer dead-ends at the drain marker
4
+ * with zero shutdown-phase evidence (test-line pain, three times — the reap lane was the blind spot of the first cut).
5
5
  * Zero default noise. Single source: the exec env's kill paths AND the task registry's reap paths
6
- * ride this one function, so the flag can never half-cover the kill surface again. */
6
+ * ride this one function, so the flag can never half-cover the kill surface again. The delivery never throws:
7
+ * forensics must never break the kill path. */
7
8
  export declare function shutdownDebug(msg: string, extra?: Record<string, unknown>): void;
@@ -1,9 +1,13 @@
1
+ import { deliverEngineNotice } from "./engine-notice.js";
1
2
  export function shutdownDebug(msg, extra) {
2
3
  if (process.env.SEMA_DEBUG_SHUTDOWN !== "1")
3
4
  return;
5
+ let message;
4
6
  try {
5
- console.error(`[sema:shutdown] ${msg}${extra !== undefined ? ` ${JSON.stringify(extra)}` : ""}`);
7
+ message = `[sema:shutdown] ${msg}${extra !== undefined ? ` ${JSON.stringify(extra)}` : ""}`;
6
8
  }
7
9
  catch {
10
+ return;
8
11
  }
12
+ deliverEngineNotice(undefined, { code: "engine.debug_trace", message, detail: { ...extra, topic: "shutdown" } });
9
13
  }
@@ -261,7 +261,10 @@ export class SkillGrantTable {
261
261
  }
262
262
  lane(ctx) {
263
263
  return {
264
- allowing: (req, mode) => judge(allowingRows(this.rowsHeld, req, mode, ctx.classifyAllShell === true), req, "allow", ctx),
264
+ allowing: (req, mode) => {
265
+ const told = ctx.onAutoStripped;
266
+ return judge(allowingRows(this.rowsHeld, req, mode, ctx.classifyAllShell === true, told === undefined ? undefined : (r, reason) => told({ entry: r.entry, reason, skill: r.skill }, req)), req, "allow", ctx);
267
+ },
265
268
  denying: (req) => judge(this.rowsHeld, req, "deny", ctx) ?? this.activationRefused(req),
266
269
  };
267
270
  }
@@ -804,11 +804,13 @@ export function createSkillsFromDirectory(dir, options = {}) {
804
804
  };
805
805
  const budget = options.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES;
806
806
  let entries;
807
+ let root;
807
808
  try {
808
809
  const st = statSync(dir);
809
810
  if (!st.isDirectory())
810
811
  throw new Error("not a directory");
811
- entries = readdirSync(dir, { withFileTypes: true });
812
+ root = physicalPathOf(dir);
813
+ entries = readdirSync(root, { withFileTypes: true });
812
814
  }
813
815
  catch (err) {
814
816
  throw new Error(`skills directory could not be read: ${dir} (${errText(err)})`);
@@ -834,7 +836,7 @@ export function createSkillsFromDirectory(dir, options = {}) {
834
836
  if (!e.isSymbolicLink())
835
837
  continue;
836
838
  try {
837
- if (statSync(join(dir, e.name)).isDirectory())
839
+ if (statSync(join(root, e.name)).isDirectory())
838
840
  dirNames.push(e.name);
839
841
  }
840
842
  catch (err) {
@@ -844,7 +846,7 @@ export function createSkillsFromDirectory(dir, options = {}) {
844
846
  dirNames.sort();
845
847
  const skills = [];
846
848
  for (const name of dirNames) {
847
- const skillDir = join(dir, name);
849
+ const skillDir = join(root, name);
848
850
  if (outside(name, skillDir, "its directory") || outside(name, join(skillDir, SKILL_FILE), SKILL_FILE))
849
851
  continue;
850
852
  let text;
@@ -128,7 +128,7 @@ export declare function runOracle(gates: OracleGateSpec[], cwdRoot: string, opts
128
128
  baseline?: OracleBaseline;
129
129
  signal?: AbortSignal;
130
130
  /** Receives the once-per-process `config.secret_env_scrubbed` notice when a gate's scrub withholds names (the
131
- * tool shell's seat and latch); absent ⇒ the console line. */
131
+ * tool shell's seat and latch); absent ⇒ the process's default seat, else the process line. */
132
132
  onNotice?: (notice: EngineNotice) => void;
133
133
  }): Promise<OracleRunReport>;
134
134
  /** Extract the per-gate baseline counts from a (preflight) report — only gates whose parse succeeded. */
@@ -57,16 +57,11 @@ export const POLICY_ALLOWED = Object.freeze({
57
57
  export const POLICY_ALLOW = { ...ALLOW, hostDecision: { decidedBy: "policy", approver: "unattended_class_answer" }, gateOutcome: POLICY_ALLOWED };
58
58
  export async function checkpointStoreContract(make, runAssertion, options = {}) {
59
59
  const { run, settle } = beginContract(runAssertion);
60
- run("kit prerequisites: reopen/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
60
+ run("kit prerequisites: reopen/recordExecutionOutcome/setPendingSteer/listByScope are implemented (REQUIRED by this kit)", async () => {
61
61
  const probe = make();
62
- const missing = ["reopen", "setPendingSteer", "listByScope"].filter((m) => typeof probe[m] !== "function");
62
+ const missing = ["reopen", "recordExecutionOutcome", "setPendingSteer", "listByScope"].filter((m) => typeof probe[m] !== "function");
63
63
  assert.equal(missing.length, 0, `backend does not implement ${missing.join(", ")} — required for the CheckpointStore contract kit`);
64
64
  });
65
- run("execution declaration: the backend declares execution.outcome === true (a REQUIRED member of the contract)", async () => {
66
- const probe = make();
67
- assert.equal(probe.execution?.outcome, true, "backend does not declare `execution = { outcome: true }` — the run refuses the store at its first read");
68
- assert.equal(typeof probe.recordExecutionOutcome, "function", "backend does not implement recordExecutionOutcome — required by the CheckpointStore contract");
69
- });
70
65
  run("recordExecutionOutcome on a resolved row → `recorded`; the record and its stamp ride the row, the decision winner is untouched, executionVerdict reads executed", async () => {
71
66
  const store = make();
72
67
  const cp = createCheckpointFixture();
@@ -1,12 +1,14 @@
1
1
  import { strict as assert } from "node:assert";
2
- import { createHash } from "node:crypto";
2
+ import { createHash, randomUUID } from "node:crypto";
3
3
  import { chmod, mkdtemp, mkdir, rm, stat, symlink, writeFile, readFile } from "node:fs/promises";
4
4
  import { tmpdir } from "node:os";
5
5
  import { join } from "node:path";
6
6
  import { fileHistoryBlobExchangeOf } from "../file-history-store.js";
7
7
  import { isGovernanceRetryClass } from "../governance-codes.js";
8
+ import { physicalPathOfAsync } from "../physical-path.js";
8
9
  import { NodeExecutionEnv } from "../../internal/harness.js";
9
10
  import { beginContract } from "./contract-harness.js";
11
+ import { fileHistoryScopeOf } from "../../engine/session/repo-utils.js";
10
12
  function probeOver(inner) {
11
13
  const calls = new Map();
12
14
  const paths = new Map();
@@ -44,7 +46,7 @@ function assertPermanenceWord(error, what) {
44
46
  assert.ok(error !== undefined && NAMES_A_FAULT[error.code] === true, `${what}: ${error?.code} is not a fault and carries no permanence`);
45
47
  }
46
48
  async function withTree(fn) {
47
- const dir = await mkdtemp(join(tmpdir(), "fh-kit-"));
49
+ const dir = await physicalPathOfAsync(await mkdtemp(join(tmpdir(), "fh-kit-")));
48
50
  try {
49
51
  await fn(dir, new NodeExecutionEnv({ cwd: dir }));
50
52
  }
@@ -234,6 +236,28 @@ export async function fileHistoryStoreContract(make, runAssertion, onOptionalMem
234
236
  assert.equal(await store.canRestore("fresh", "b"), true);
235
237
  });
236
238
  });
239
+ run("deleteUnreadableSessionHistory (optional): every scope of the id — its bare id and each occupant's address — is erased, and no other id's (one it is a prefix of, one carrying `~` of its own); a repeat answers 0", async () => {
240
+ if (make().deleteUnreadableSessionHistory === undefined)
241
+ return;
242
+ await withTree(async (dir, env) => {
243
+ const store = make();
244
+ const minted = () => `${randomUUID()}.2`;
245
+ const id = `s1-${randomUUID().slice(0, 8)}`;
246
+ const own = [fileHistoryScopeOf(id, undefined), fileHistoryScopeOf(id, minted()), fileHistoryScopeOf(id, minted())];
247
+ const others = [`${id}x`, `${id}-x`, `${id}~a`].flatMap((other) => [fileHistoryScopeOf(other, undefined), fileHistoryScopeOf(other, minted())]);
248
+ await writeFile(join(dir, "f.txt"), "v1");
249
+ for (const scope of [...own, ...others]) {
250
+ assert.deepEqual(await store.trackEdit(scope, join(dir, "f.txt"), env, dir), { ok: true, minted: true }, `track under ${scope}`);
251
+ assert.deepEqual(await store.snapshot(scope, "b1", env, dir), { ok: true }, `boundary under ${scope}`);
252
+ }
253
+ assert.ok((await store.deleteUnreadableSessionHistory(id)) > 0, "the id's history was erased and counted");
254
+ for (const scope of own)
255
+ assert.equal(await store.canRestore(scope, "b1"), false, `${scope} is one of ${id}'s scopes and is erased`);
256
+ for (const scope of others)
257
+ assert.equal(await store.canRestore(scope, "b1"), true, `${scope} is another id's scope and keeps its history`);
258
+ assert.equal(await store.deleteUnreadableSessionHistory(id), 0, "a repeat finds nothing");
259
+ });
260
+ });
237
261
  run("structural out-of-scope (cowork guarantee) + T-1 positive control + G4 zero listDir: restore IO lands ONLY on tracked files, and no verb enumerates directories", async () => {
238
262
  await withTree(async (dir, env) => {
239
263
  const store = make();
@@ -1,25 +1,38 @@
1
1
  import { strict as assert } from "node:assert";
2
2
  import { randomUUID } from "node:crypto";
3
3
  import { peerSessionBoxHandle } from "../../agents/peer-directory.js";
4
+ import { SessionError } from "../../internal/harness.js";
5
+ import { thrownText } from "../thrown-value.js";
6
+ import { fileHistoryScopeOf } from "../../engine/session/repo-utils.js";
4
7
  import { RETENTION_CASCADE, RETENTION_SESSION_TREE_STEPS } from "../retention.js";
5
8
  import { beginContract } from "./contract-harness.js";
6
9
  const endOf = (call) => call.end ?? Number.POSITIVE_INFINITY;
7
10
  const lastEnd = (calls) => Math.max(...calls.map(endOf));
8
11
  const firstStart = (calls) => Math.min(...calls.map((call) => call.start));
9
12
  const HEALTHY = { adopt: "ok" };
10
- function freshScene() {
13
+ const tokenOf = (era) => (era === "address" ? `${randomUUID()}.2` : randomUUID());
14
+ function freshScene(era = "address") {
11
15
  const id = (what) => `kit-cascade-${what}-${randomUUID()}`;
12
16
  return {
13
17
  sessionId: id("session"),
14
18
  owner: "kit-owner",
15
19
  scope: "kit-scope",
20
+ occupant: tokenOf(era),
16
21
  fork: id("fork"),
22
+ forkOccupant: tokenOf(era),
23
+ lateFork: id("late-fork"),
24
+ lateForkOccupant: tokenOf(era),
25
+ strayFork: id("stray-fork"),
26
+ strayForkOccupant: tokenOf("address"),
27
+ strayOrigin: tokenOf("address"),
17
28
  other: id("other"),
18
29
  run: id("run"),
19
30
  otherRun: id("other-run"),
20
31
  agent: id("agent"),
21
32
  rosterAgent: id("roster-agent"),
33
+ rosterRootAgent: id("roster-root-agent"),
22
34
  otherRosterAgent: id("other-roster-agent"),
35
+ otherRosterRootAgent: id("other-roster-root-agent"),
23
36
  };
24
37
  }
25
38
  const READS = {
@@ -34,10 +47,20 @@ function filtered(rows, opts, sessionOf) {
34
47
  const kept = rows.filter((row) => (query.status === undefined || row.status === query.status) && (query.session === undefined || sessionOf === undefined || sessionOf(row) === query.session));
35
48
  return typeof query.limit === "number" ? kept.slice(0, query.limit) : kept;
36
49
  }
50
+ const GUARDED = new Set(RETENTION_SESSION_TREE_STEPS.flatMap((leg) => (leg.unreadable === undefined ? [] : [`${leg.store}.${leg.verb}`])));
51
+ const UNREADABLE_VERBS = new Set(RETENTION_SESSION_TREE_STEPS.flatMap((leg) => (leg.unreadable === undefined ? [] : [`${leg.store}.${leg.unreadable}`])));
52
+ const unreadableHead = (sessionId) => new SessionError("corrupt_session", `kit: the head of session "${sessionId}" cannot be read in this case`);
37
53
  function answer(call, scene, variant) {
38
54
  const { seat, verb, args } = call;
39
55
  if (variant.failing === `${seat}.${verb}`)
40
56
  throw new Error(`kit: ${seat}.${verb} fails in this case`);
57
+ if (variant.unreadable === true && args[0] === scene.sessionId && (GUARDED.has(`${seat}.${verb}`) || `${seat}.${verb}` === "sessionStore.headOf"))
58
+ throw unreadableHead(scene.sessionId);
59
+ if (UNREADABLE_VERBS.has(`${seat}.${verb}`)) {
60
+ if (variant.unreadable !== true || args[0] !== scene.sessionId)
61
+ return seat === "sessionStore" ? false : 0;
62
+ return seat === "sessionStore" ? true : 1;
63
+ }
41
64
  switch (`${seat}.${verb}`) {
42
65
  case "workflowRunStore.listByScope": {
43
66
  const runs = [
@@ -49,6 +72,7 @@ function answer(call, scene, variant) {
49
72
  case "workflowRunStore.deleteBySession":
50
73
  return args[0] === scene.sessionId ? [scene.run] : [];
51
74
  case "workflowJournalStore.deleteRun":
75
+ case "workflowScriptStore.deleteRun":
52
76
  case "backgroundAgentStore.delete":
53
77
  case "mailboxStore.retireRecipient":
54
78
  case "sessionStore.delete":
@@ -62,7 +86,9 @@ function answer(call, scene, variant) {
62
86
  case "rosterStore.list":
63
87
  return [
64
88
  { name: "kit-agent", agentId: scene.rosterAgent, sessionId: scene.sessionId, createdAt: 1 },
89
+ { name: "kit-bg-agent", agentId: scene.rosterRootAgent, rootSessionId: scene.sessionId, createdAt: 1 },
65
90
  { name: "kit-other", agentId: scene.otherRosterAgent, sessionId: scene.other, createdAt: 1 },
91
+ { name: "kit-other-bg-agent", agentId: scene.otherRosterRootAgent, rootSessionId: scene.other, createdAt: 1 },
66
92
  ];
67
93
  case "checkpointStore.deleteSessionCheckpoints":
68
94
  case "fileHistoryStore.deleteBySession":
@@ -79,14 +105,19 @@ function answer(call, scene, variant) {
79
105
  const after = args[0]?.after;
80
106
  if (after !== undefined)
81
107
  return [];
108
+ const occupants = (incarnation, forkedFromIncarnation) => (variant.listWithoutOccupants === true ? {} : { incarnation, forkedFromIncarnation });
82
109
  return [
83
- { sessionId: scene.fork, lastActiveAt: 3, forkedFrom: scene.sessionId },
84
- { sessionId: scene.sessionId, lastActiveAt: 2 },
85
- { sessionId: scene.other, lastActiveAt: 1 },
110
+ { sessionId: scene.fork, lastActiveAt: 5, forkedFrom: scene.sessionId, ...occupants(scene.forkOccupant, scene.occupant) },
111
+ { sessionId: scene.lateFork, lastActiveAt: 4, forkedFrom: scene.sessionId, ...occupants(scene.lateForkOccupant, null) },
112
+ { sessionId: scene.strayFork, lastActiveAt: 3, forkedFrom: scene.sessionId, ...occupants(scene.strayForkOccupant, scene.strayOrigin) },
113
+ ...(variant.unreadable === true ? [] : [{ sessionId: scene.sessionId, lastActiveAt: 2, ...occupants(scene.occupant, null) }]),
114
+ { sessionId: scene.other, lastActiveAt: 1, ...occupants(tokenOf("address"), null) },
86
115
  ];
87
116
  }
88
117
  case "sessionStore.headOf":
89
- return [scene.sessionId, scene.fork, scene.other].includes(String(args[0])) ? { owner: scene.owner, incarnation: undefined, leafId: null } : undefined;
118
+ if (args[0] === scene.sessionId)
119
+ return { owner: scene.owner, incarnation: scene.occupant, leafId: null };
120
+ return [scene.fork, scene.lateFork, scene.strayFork, scene.other].includes(String(args[0])) ? { owner: scene.owner, leafId: null } : undefined;
90
121
  default:
91
122
  return undefined;
92
123
  }
@@ -125,11 +156,13 @@ function recordingStores(journal, clock, scene, variant) {
125
156
  if (leg.store !== seat)
126
157
  continue;
127
158
  verbs.add(leg.verb);
159
+ if (leg.unreadable !== undefined)
160
+ verbs.add(leg.unreadable);
128
161
  if (leg.fence !== undefined && variant.withoutFence !== true)
129
162
  for (const v of [leg.fence, ...(FENCE_PARTNERS[leg.fence] ?? [])])
130
163
  verbs.add(v);
131
164
  }
132
- const members = Object.fromEntries([...verbs].map((verb) => [verb, recorder(seat, verb, journal, clock, scene, variant)]));
165
+ const members = Object.fromEntries([...verbs].filter((verb) => variant.without !== `${seat}.${verb}`).map((verb) => [verb, recorder(seat, verb, journal, clock, scene, variant)]));
133
166
  return [seat, Object.assign({}, members)];
134
167
  });
135
168
  return Object.assign({}, Object.fromEntries(entries));
@@ -153,21 +186,26 @@ function names(value, key) {
153
186
  return false;
154
187
  }
155
188
  const ownerOf = (guard) => (typeof guard === "object" && guard !== null ? guard.owner : undefined);
189
+ const historyOf = (scene) => fileHistoryScopeOf(scene.sessionId, scene.occupant);
190
+ const forkScopeOf = (scene) => fileHistoryScopeOf(scene.fork, scene.forkOccupant);
191
+ const untouchedScopesOf = (scene) => [fileHistoryScopeOf(scene.lateFork, scene.lateForkOccupant), fileHistoryScopeOf(scene.strayFork, scene.strayForkOccupant)];
156
192
  function legReadings(scene) {
157
193
  const s = scene.sessionId;
158
194
  const box = peerSessionBoxHandle(s);
159
195
  return {
160
196
  "workflowJournalStore.deleteRun#0": (c) => c.args[0] === scene.run && c.args[1] === scene.scope,
197
+ "workflowScriptStore.deleteRun#0": (c) => c.args[0] === scene.run && c.args[1] === scene.scope,
161
198
  "workflowRunStore.deleteBySession#0": (c) => c.args[0] === s && c.args[1] === scene.scope,
162
199
  "mailboxStore.drop#0": (c) => c.args[0] === scene.scope && c.args[1] === scene.agent,
163
200
  "backgroundAgentStore.delete#0": (c) => c.args[0] === scene.agent && c.args[1] === scene.scope,
164
- "rosterStore.releaseAgent#0": (c) => c.args[0] === scene.rosterAgent,
201
+ "rosterStore.releaseAgent#0": (c) => c.args[0] === scene.rosterAgent || c.args[0] === scene.rosterRootAgent,
165
202
  "checkpointStore.deleteSessionCheckpoints#0": (c) => c.args[0] === s && ownerOf(c.args[1]) === scene.owner,
166
203
  "toolResultStore.deleteBySession#0": (c) => c.args[0] === s,
167
204
  "sessionPolicyStore.deleteBySession#0": (c) => c.args[0] === s,
168
- "fileHistoryStore.adoptScope#0": (c) => c.args[0] === s && c.args[1] === scene.fork,
169
- "fileHistoryStore.deleteBySession#0": (c) => c.args[0] === s,
205
+ "fileHistoryStore.adoptScope#0": (c) => c.args[0] === historyOf(scene) && c.args[1] === forkScopeOf(scene),
206
+ "fileHistoryStore.deleteBySession#0": (c) => c.args[0] === historyOf(scene),
170
207
  "mailboxStore.drop#1": (c) => c.args[0] === scene.scope && c.args[1] === box,
208
+ "taskListStore.drop#0": () => true,
171
209
  "sessionStore.delete#0": (c) => c.args[0] === s && ownerOf(c.args[1]) === scene.owner,
172
210
  };
173
211
  }
@@ -199,7 +237,11 @@ async function drive(coordinator, variant, scene = freshScene()) {
199
237
  const describeJournal = (journal) => journal.map((c, k) => `${k}:${c.seat}.${c.verb}@${c.start}-${c.end ?? "open"}`).join(", ");
200
238
  export async function sessionDeletionCascadeContract(coordinator, runAssertion) {
201
239
  const { run, settle } = beginContract(runAssertion);
202
- const destructive = new Set(RETENTION_SESSION_TREE_STEPS.flatMap((leg) => [`${leg.store}.${leg.verb}`, ...(leg.fence === undefined ? [] : [`${leg.store}.${leg.fence}`])]));
240
+ const destructive = new Set(RETENTION_SESSION_TREE_STEPS.flatMap((leg) => [
241
+ `${leg.store}.${leg.verb}`,
242
+ ...(leg.fence === undefined ? [] : [`${leg.store}.${leg.fence}`]),
243
+ ...(leg.unreadable === undefined ? [] : [`${leg.store}.${leg.unreadable}`]),
244
+ ]));
203
245
  run("every session-tree leg of the table is called, with the keys the leg selects", async () => {
204
246
  const { journal, scene, rejected, ok } = await drive(coordinator, HEALTHY);
205
247
  assert.ok(ok, `the deletion rejected over healthy stores: ${String(rejected)}`);
@@ -207,6 +249,18 @@ export async function sessionDeletionCascadeContract(coordinator, runAssertion)
207
249
  assert.ok(at.length > 0, `leg ${label} (step ${leg.step}: ${leg.selects}) was never called — calls: ${describeJournal(journal)}`);
208
250
  }
209
251
  });
252
+ run("the roster leg releases the agent whose entry names the session as its session and the agent whose entry names it as its root session", async () => {
253
+ const variants = [HEALTHY, { adopt: "ok", unreadable: true }];
254
+ for (const variant of variants) {
255
+ const { journal, scene, rejected, ok } = await drive(coordinator, variant);
256
+ if (variant.unreadable === true && !journal.some((c) => destructive.has(`${c.seat}.${c.verb}`)))
257
+ continue;
258
+ assert.ok(ok, `the deletion rejected: ${String(rejected)}`);
259
+ const released = journal.filter((c) => c.seat === "rosterStore" && c.verb === "releaseAgent").map((c) => c.args[0]);
260
+ assert.ok(released.includes(scene.rosterAgent), `the roster agent whose entry names the session as its session was never released — calls: ${describeJournal(journal)}`);
261
+ assert.ok(released.includes(scene.rosterRootAgent), `the roster agent whose entry names the session as its root session (the only session a plain background agent's entry names) was never released — calls: ${describeJournal(journal)}`);
262
+ }
263
+ });
210
264
  run("every fence settles before the first step, each leg settles before the next begins, and the session row's leg is last — with the carry answering `ok` and `conflict`", async () => {
211
265
  for (const carryAnswer of ["ok", "conflict"]) {
212
266
  const { journal, scene, rejected, ok } = await drive(coordinator, { adopt: carryAnswer });
@@ -235,13 +289,30 @@ export async function sessionDeletionCascadeContract(coordinator, runAssertion)
235
289
  assert.ok("legs" in row, `${call.seat} is exempt (${"exempt" in row ? row.exempt : ""}) and received ${call.verb}`);
236
290
  if (!destructive.has(`${call.seat}.${call.verb}`))
237
291
  continue;
238
- for (const key of [scene.other, scene.otherRun, scene.otherRosterAgent]) {
292
+ for (const key of [scene.other, scene.otherRun, scene.otherRosterAgent, scene.otherRosterRootAgent, scene.lateFork, scene.strayFork, ...untouchedScopesOf(scene)]) {
239
293
  assert.ok(!names(call.args, key), `${call.seat}.${call.verb} named another session's row ${key}`);
240
294
  }
241
- const carry = call.seat === "fileHistoryStore" && call.verb === "adoptScope" && call.args[1] === scene.fork && !names(call.args[0], scene.fork);
242
- assert.ok(carry || !names(call.args, scene.fork), `${call.seat}.${call.verb} named the fork ${scene.fork} — a fork is named only as the file-history carry's target`);
295
+ const forkScope = forkScopeOf(scene);
296
+ const carry = call.seat === "fileHistoryStore" && call.verb === "adoptScope" && call.args[1] === forkScope && !names(call.args[0], forkScope) && !names(call.args[0], scene.fork);
297
+ assert.ok(carry || (!names(call.args, scene.fork) && !names(call.args, forkScope)), `${call.seat}.${call.verb} named the fork ${scene.fork} — a fork is named only as the file-history carry's target, by its own scope`);
243
298
  }
244
299
  });
300
+ run("history is named by its address: a session born before the address epoch has its bare-id scope carried and deleted, and the forks that recorded no source occupant or another occupant receive nothing", async () => {
301
+ for (const era of ["address", "pre-address"]) {
302
+ const { journal, scene, rejected, ok } = await drive(coordinator, HEALTHY, freshScene(era));
303
+ assert.ok(ok, `the deletion rejected over healthy stores (${era} session): ${String(rejected)}`);
304
+ const carries = journal.filter((c) => c.seat === "fileHistoryStore" && c.verb === "adoptScope");
305
+ const erases = journal.filter((c) => c.seat === "fileHistoryStore" && c.verb === "deleteBySession");
306
+ assert.deepEqual(carries.map((c) => c.args.slice(0, 2)), [[historyOf(scene), forkScopeOf(scene)]], `the carry is the session's scope into the one fork that recorded its occupant (${era} session) — calls: ${describeJournal(journal)}`);
307
+ assert.deepEqual(erases.map((c) => c.args[0]), [historyOf(scene)], `step 11 deletes the session's one scope (${era} session) — calls: ${describeJournal(journal)}`);
308
+ }
309
+ });
310
+ run("a session list whose rows lack the occupant keys fails the deletion before any history is carried or deleted, and the row stays", async () => {
311
+ const { journal, ok } = await drive(coordinator, { adopt: "ok", listWithoutOccupants: true });
312
+ assert.ok(!ok, `the deletion completed over list rows without incarnation / forkedFromIncarnation — calls: ${describeJournal(journal)}`);
313
+ const touched = journal.filter((c) => (c.seat === "fileHistoryStore" && (c.verb === "adoptScope" || c.verb === "deleteBySession")) || (c.seat === "sessionStore" && c.verb === "delete"));
314
+ assert.equal(touched.length, 0, `history or the row was touched though the list could not name the forks' scopes — calls: ${describeJournal(journal)}`);
315
+ });
245
316
  run("the session's file history is carried into its fork before it is deleted; a carry refused `conflict` counts as done", async () => {
246
317
  for (const adopt of ["ok", "conflict"]) {
247
318
  const { journal, scene, rejected, ok } = await drive(coordinator, { adopt });
@@ -258,7 +329,7 @@ export async function sessionDeletionCascadeContract(coordinator, runAssertion)
258
329
  run("a carry that fails any other way leaves the session's history and its row in place", async () => {
259
330
  for (const adopt of ["failed", "throws"]) {
260
331
  const { journal, scene } = await drive(coordinator, { adopt });
261
- const left = journal.filter((c) => (c.seat === "fileHistoryStore" && c.verb === "deleteBySession" && c.args[0] === scene.sessionId) || (c.seat === "sessionStore" && c.verb === "delete" && c.args[0] === scene.sessionId));
332
+ const left = journal.filter((c) => (c.seat === "fileHistoryStore" && c.verb === "deleteBySession" && c.args[0] === historyOf(scene)) || (c.seat === "sessionStore" && c.verb === "delete" && c.args[0] === scene.sessionId));
262
333
  assert.equal(left.length, 0, `the carry ${adopt === "failed" ? "answered a failure" : "threw"} and the session's ${left.map((c) => `${c.seat}.${c.verb}`).join(" and ")} still ran — calls: ${describeJournal(journal)}`);
263
334
  }
264
335
  });
@@ -284,5 +355,50 @@ export async function sessionDeletionCascadeContract(coordinator, runAssertion)
284
355
  for (const { label, at } of legCalls(journal, scene))
285
356
  assert.ok(at.length > 0, `leg ${label} was never called over a mailbox without the pair — calls: ${describeJournal(journal)}`);
286
357
  });
358
+ run("a session whose head cannot be read is never half-deleted: refused before any destructive call, or every leg called — a leg with an `unreadable` verb through it, never through its own — the session row's last", async () => {
359
+ const { journal, scene, rejected, ok } = await drive(coordinator, { adopt: "ok", unreadable: true });
360
+ const destroyed = journal.filter((c) => destructive.has(`${c.seat}.${c.verb}`));
361
+ if (destroyed.length === 0)
362
+ return;
363
+ assert.ok(ok, `the coordinator began deleting a session whose head cannot be read and then rejected — it is half-deleted: ${String(rejected)} — calls: ${describeJournal(journal)}`);
364
+ const readings = legReadings(scene);
365
+ const labels = labelsOf(RETENTION_SESSION_TREE_STEPS);
366
+ const spans = [];
367
+ RETENTION_SESSION_TREE_STEPS.forEach((leg, i) => {
368
+ const label = labels[i];
369
+ if (leg.unreadable !== undefined) {
370
+ const own = journal.filter((c) => c.seat === leg.store && c.verb === leg.verb);
371
+ assert.equal(own.length, 0, `leg ${label} was called through its own verb on a session whose head cannot be read — calls: ${describeJournal(journal)}`);
372
+ const twin = journal.filter((c) => c.seat === leg.store && c.verb === leg.unreadable && c.args[0] === scene.sessionId);
373
+ assert.ok(twin.length > 0, `leg ${label} was never called through ${leg.store}.${leg.unreadable} — calls: ${describeJournal(journal)}`);
374
+ spans.push(twin);
375
+ return;
376
+ }
377
+ const reads = readings[label];
378
+ assert.ok(reads !== undefined, `the kit has no reading of the table's session-tree leg ${label} (step ${leg.step}) — the kit is older than the table`);
379
+ const calls = journal.filter((c) => c.seat === leg.store && c.verb === leg.verb && reads(c));
380
+ assert.ok(calls.length > 0, `leg ${label} was never called on a session whose head cannot be read — calls: ${describeJournal(journal)}`);
381
+ spans.push(calls);
382
+ });
383
+ const row = spans[spans.length - 1];
384
+ for (const other of spans.slice(0, -1)) {
385
+ assert.ok(lastEnd(other) < firstStart(row), `the session row's leg began before every other leg had settled on a session whose head cannot be read — calls: ${describeJournal(journal)}`);
386
+ }
387
+ });
388
+ run("a session whose head cannot be read, over a store without its leg's `unreadable` verb, is refused before any destructive call, naming the store and the verb", async () => {
389
+ const offered = (await drive(coordinator, { adopt: "ok", unreadable: true })).journal.some((c) => destructive.has(`${c.seat}.${c.verb}`));
390
+ for (const leg of RETENTION_SESSION_TREE_STEPS) {
391
+ if (leg.unreadable === undefined)
392
+ continue;
393
+ const missing = `${leg.store}.${leg.unreadable}`;
394
+ const { journal, rejected, ok } = await drive(coordinator, { adopt: "ok", unreadable: true, without: missing });
395
+ const destroyed = journal.filter((c) => destructive.has(`${c.seat}.${c.verb}`));
396
+ assert.equal(destroyed.length, 0, `the store carries no ${missing} and the coordinator still made destructive calls on a session whose head cannot be read — the check comes before the first one — calls: ${describeJournal(journal)}`);
397
+ assert.ok(!ok, `the store carries no ${missing} and the deletion of a session whose head cannot be read completed — calls: ${describeJournal(journal)}`);
398
+ const said = thrownText(rejected);
399
+ if (offered)
400
+ assert.ok(said.includes(leg.store) && said.includes(leg.unreadable), `the refusal does not name ${leg.store} and ${leg.unreadable}: ${said}`);
401
+ }
402
+ });
287
403
  await settle();
288
404
  }
@@ -10,7 +10,8 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
10
10
  * Tiers:
11
11
  * - core (every backend): CRUD round trip, detached copies both ways, the entry table's write gate (absent dependency lists stored
12
12
  * as `[]`, a present one that is no list refused), the metadata guard, `allocateId` unique and never reused, the list order (id
13
- * ascending, stable), unknown-id answers, single-call atomicity under concurrent writes;
13
+ * ascending, stable; an id that is no canonical integer placed by `compareTaskIds`), unknown-id answers, single-call atomicity under concurrent writes, and — where the store carries `drop` —
14
+ * the whole list erased with its id high-water;
14
15
  * - durable (`reopen` given — the backend outlives one object): cross-instance visibility and high-water mark, `mutate` as the
15
16
  * transaction boundary, no lost update across instances;
16
17
  * - damaged entries (`plantRow` given): an entry a foreign writer left that does not read is LISTED as its id and verdict, `get`
@@ -1,5 +1,5 @@
1
1
  import { strict as assert } from "node:assert";
2
- import { TASK_LIST_ROW_MALFORMED_CODE, createTaskListTools, } from "../../tools/task-list.js";
2
+ import { TASK_LIST_ROW_MALFORMED_CODE, compareTaskIds, createTaskListTools, } from "../../tools/task-list.js";
3
3
  import { beginContract } from "./contract-harness.js";
4
4
  import { thrownText } from "../thrown-value.js";
5
5
  const row = (id, over = {}) => ({
@@ -107,6 +107,23 @@ export async function taskListStoreContract(hooks, runAssertion) {
107
107
  assert.deepEqual(after.filter((x) => minted.includes(x)), [], "the high-water mark never regresses");
108
108
  assert.equal(new Set(after).size, 2);
109
109
  });
110
+ run("drop (a store that carries it): every entry goes, a damaged one included, the high-water with them — the next id is 1, a repeat is harmless, and another instance over the backend reads the list empty", async () => {
111
+ const s = mk();
112
+ if (s.drop === undefined)
113
+ return;
114
+ for (let i = 0; i < 3; i++) {
115
+ const id = String(await s.allocateId());
116
+ await s.set(id, row(id));
117
+ }
118
+ if (hooks.plantRow !== undefined)
119
+ await hooks.plantRow(s, "9", { id: "9", subject: 1 });
120
+ await s.drop();
121
+ assert.deepEqual(await s.list(), [], "no entry outlives the drop");
122
+ if (hooks.reopen !== undefined)
123
+ assert.deepEqual(await hooks.reopen(s).list(), [], "another instance reads the dropped list empty");
124
+ await s.drop();
125
+ assert.equal(String(await s.allocateId()), "1", "the high-water went with the entries");
126
+ });
110
127
  run("list order: id ascending (numeric), stable across calls, whatever order the ids were written in", async () => {
111
128
  const s = mk();
112
129
  const minted = [];
@@ -126,6 +143,16 @@ export async function taskListStoreContract(hooks, runAssertion) {
126
143
  await t.set("2", row("2"));
127
144
  assert.deepEqual(ids(await t.list()), ["2", "4", "7", "12", "30"]);
128
145
  });
146
+ run("list order: an id that is not a canonical integer (leading zeros, not all digits, longer than an array index) is placed by `compareTaskIds`, not by the backend's own key order", async () => {
147
+ const s = mk();
148
+ const written = ["30", "b", "4", "a", "12", "007", "7", "99999999999", "5000000000"];
149
+ for (const id of written)
150
+ await s.set(id, row(id));
151
+ const expected = ["4", "007", "7", "12", "30", "5000000000", "99999999999", "a", "b"];
152
+ assert.deepEqual([...written].sort(compareTaskIds), expected, "the expectation below is the comparator's own answer");
153
+ assert.deepEqual(ids(await s.list()), expected);
154
+ assert.deepEqual(ids(await s.list()), expected, "a repeated call keeps the order");
155
+ });
129
156
  run("an unknown id: get answers undefined and delete answers false, neither throws", async () => {
130
157
  const s = mk();
131
158
  assert.equal(await s.get("nosuchid"), undefined);