@acryldev/plugin-context 0.0.0-stage → 0.1.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 (284) hide show
  1. package/LICENSE +21 -0
  2. package/docs/README.md +160 -0
  3. package/docs/delivery/local-live.md +113 -0
  4. package/docs/delivery/marketplace.md +16 -0
  5. package/docs/docs.json +2836 -0
  6. package/docs/extending/agent-preset.md +37 -0
  7. package/docs/extending/chat-command.md +28 -0
  8. package/docs/extending/client-slot.md +135 -0
  9. package/docs/extending/config-schema.md +7 -0
  10. package/docs/extending/cordis-core.md +63 -0
  11. package/docs/extending/desktop-app.md +53 -0
  12. package/docs/extending/desktop-main.md +25 -0
  13. package/docs/extending/event-hook.md +14 -0
  14. package/docs/extending/host-route.md +33 -0
  15. package/docs/extending/llm-adapter.md +38 -0
  16. package/docs/extending/packaging.md +53 -0
  17. package/docs/extending/prompt-contribution.md +9 -0
  18. package/docs/extending/service.md +13 -0
  19. package/docs/extending/skill-provider.md +9 -0
  20. package/docs/extending/state-and-persistence.md +71 -0
  21. package/docs/extending/three-role-capability.md +33 -0
  22. package/docs/extending/tool-plugin.md +24 -0
  23. package/docs/extending/tui-command.md +8 -0
  24. package/docs/extending/tui-components.md +61 -0
  25. package/docs/extending/ui-branding.md +43 -0
  26. package/docs/extending/ui-components.md +56 -0
  27. package/docs/extending/ui-customization.md +41 -0
  28. package/docs/extending/ui-library.md +66 -0
  29. package/docs/extending/ui-theme.md +55 -0
  30. package/docs/extending/workspace-tab.md +50 -0
  31. package/docs/maps/events.md +108 -0
  32. package/docs/maps/mount-points.md +154 -0
  33. package/docs/maps/slot-contracts.md +3376 -0
  34. package/docs/maps/taxonomy.md +306 -0
  35. package/docs/maps/theme-tokens.md +115 -0
  36. package/docs/maps/ui-components.md +26 -0
  37. package/docs/reference/cookbook/adding-a-package.md +174 -0
  38. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  39. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  40. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  41. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  42. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  43. package/docs/reference/cordis-api/context.md +366 -0
  44. package/docs/reference/cordis-api/events.md +209 -0
  45. package/docs/reference/cordis-api/fiber.md +377 -0
  46. package/docs/reference/cordis-api/inherited.md +40 -0
  47. package/docs/reference/cordis-api/registry.md +154 -0
  48. package/docs/reference/cordis-api/service.md +104 -0
  49. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  50. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  51. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  52. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  53. package/docs/reference/harness/agent-lifecycle.md +93 -0
  54. package/docs/reference/harness/architecture.md +168 -0
  55. package/docs/reference/harness/capability-seams.md +675 -0
  56. package/docs/reference/harness/config-catalog.md +4523 -0
  57. package/docs/reference/harness/cordis-primer.md +47 -0
  58. package/docs/reference/harness/defensive-patterns.md +35 -0
  59. package/docs/reference/harness/event-producer-consumer.md +111 -0
  60. package/docs/reference/harness/glossary.md +47 -0
  61. package/docs/reference/harness/tool-catalog.md +2721 -0
  62. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  63. package/docs/reference/subsystems/README.md +75 -0
  64. package/docs/reference/subsystems/agent-team.md +233 -0
  65. package/docs/reference/subsystems/approval.md +172 -0
  66. package/docs/reference/subsystems/attachment.md +363 -0
  67. package/docs/reference/subsystems/boot.md +324 -0
  68. package/docs/reference/subsystems/browser-use.md +69 -0
  69. package/docs/reference/subsystems/client-modules.md +186 -0
  70. package/docs/reference/subsystems/client-resources.md +94 -0
  71. package/docs/reference/subsystems/commands.md +225 -0
  72. package/docs/reference/subsystems/compaction.md +286 -0
  73. package/docs/reference/subsystems/computer-use.md +58 -0
  74. package/docs/reference/subsystems/conversation.md +287 -0
  75. package/docs/reference/subsystems/core.md +1107 -0
  76. package/docs/reference/subsystems/credentials.md +497 -0
  77. package/docs/reference/subsystems/deliverables.md +180 -0
  78. package/docs/reference/subsystems/extensions.md +386 -0
  79. package/docs/reference/subsystems/feedback.md +402 -0
  80. package/docs/reference/subsystems/filesystem.md +532 -0
  81. package/docs/reference/subsystems/goal.md +315 -0
  82. package/docs/reference/subsystems/invariants.md +90 -0
  83. package/docs/reference/subsystems/jobs.md +501 -0
  84. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  85. package/docs/reference/subsystems/lsp.md +204 -0
  86. package/docs/reference/subsystems/mcp.md +141 -0
  87. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  88. package/docs/reference/subsystems/otel.md +46 -0
  89. package/docs/reference/subsystems/permission-presets.md +169 -0
  90. package/docs/reference/subsystems/persistence.md +418 -0
  91. package/docs/reference/subsystems/plan.md +89 -0
  92. package/docs/reference/subsystems/product-telemetry.md +81 -0
  93. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  94. package/docs/reference/subsystems/sandbox.md +223 -0
  95. package/docs/reference/subsystems/schedule.md +545 -0
  96. package/docs/reference/subsystems/scope.md +61 -0
  97. package/docs/reference/subsystems/session-projection.md +358 -0
  98. package/docs/reference/subsystems/session-query.md +511 -0
  99. package/docs/reference/subsystems/session-reference.md +226 -0
  100. package/docs/reference/subsystems/session-telemetry.md +214 -0
  101. package/docs/reference/subsystems/session-title.md +206 -0
  102. package/docs/reference/subsystems/session.md +1300 -0
  103. package/docs/reference/subsystems/settings.md +157 -0
  104. package/docs/reference/subsystems/shell.md +316 -0
  105. package/docs/reference/subsystems/sidebar-right.md +160 -0
  106. package/docs/reference/subsystems/skills.md +354 -0
  107. package/docs/reference/subsystems/slots.md +201 -0
  108. package/docs/reference/subsystems/spill.md +126 -0
  109. package/docs/reference/subsystems/ssh.md +137 -0
  110. package/docs/reference/subsystems/storage.md +262 -0
  111. package/docs/reference/subsystems/subagent.md +762 -0
  112. package/docs/reference/subsystems/subprocess.md +323 -0
  113. package/docs/reference/subsystems/system-prompt.md +226 -0
  114. package/docs/reference/subsystems/terminal.md +186 -0
  115. package/docs/reference/subsystems/todo.md +34 -0
  116. package/docs/reference/subsystems/token-meter.md +108 -0
  117. package/docs/reference/subsystems/tools.md +749 -0
  118. package/docs/reference/subsystems/typert.md +489 -0
  119. package/docs/reference/subsystems/user-questions.md +309 -0
  120. package/docs/reference/subsystems/voice-input.md +166 -0
  121. package/docs/reference/subsystems/web-client.md +102 -0
  122. package/docs/reference/subsystems/web-server.md +228 -0
  123. package/docs/reference/subsystems/web.md +208 -0
  124. package/docs/reference/subsystems/webhook.md +72 -0
  125. package/docs/reference/subsystems/workflow.md +280 -0
  126. package/docs/reference/subsystems/workspace.md +661 -0
  127. package/docs/start-here/blueprints.md +33 -0
  128. package/docs/start-here/this-runtime.md +84 -0
  129. package/docs/start-here/troubleshooting.md +29 -0
  130. package/docs/start-here/trust-and-safety.md +39 -0
  131. package/docs/start-here/verify-before-done.md +46 -0
  132. package/example-plugins/README.md +45 -0
  133. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  134. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  135. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  137. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  138. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  141. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  144. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  145. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  146. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  147. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  148. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  149. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  150. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  151. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  152. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  153. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  154. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  155. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  159. package/example-plugins/packages/client-theme-override/client.js +52 -0
  160. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  161. package/example-plugins/packages/client-theme-override/index.js +9 -0
  162. package/example-plugins/packages/client-theme-override/package.json +30 -0
  163. package/example-plugins/packages/client-tool-view/client.js +47 -0
  164. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  165. package/example-plugins/packages/client-tool-view/index.js +24 -0
  166. package/example-plugins/packages/client-tool-view/package.json +34 -0
  167. package/example-plugins/packages/client-ui-components/client.js +77 -0
  168. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  169. package/example-plugins/packages/client-ui-components/index.js +9 -0
  170. package/example-plugins/packages/client-ui-components/package.json +31 -0
  171. package/example-plugins/packages/client-ui-library/client.js +715 -0
  172. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  173. package/example-plugins/packages/client-ui-library/index.js +9 -0
  174. package/example-plugins/packages/client-ui-library/package.json +37 -0
  175. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  176. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  177. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  178. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  179. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  180. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  181. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  182. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  183. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  184. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  185. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  186. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  187. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  188. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  189. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  190. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  191. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  192. package/example-plugins/packages/host-route-basic/index.js +20 -0
  193. package/example-plugins/packages/host-route-basic/package.json +29 -0
  194. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  195. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  196. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  197. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  201. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  204. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  205. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  206. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  207. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  208. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  209. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  210. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  211. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  212. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  213. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  214. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  215. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  216. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  217. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  218. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  219. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  220. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  221. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  222. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  223. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  224. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  225. package/example-plugins/packages/state-host-store/client.js +57 -0
  226. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  227. package/example-plugins/packages/state-host-store/index.js +90 -0
  228. package/example-plugins/packages/state-host-store/package.json +31 -0
  229. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  230. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  231. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  232. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  233. package/example-plugins/packages/tool-basic/index.js +25 -0
  234. package/example-plugins/packages/tool-basic/package.json +25 -0
  235. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  236. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  237. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  238. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  239. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  240. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  241. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  242. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  243. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  244. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  245. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  246. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  247. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  248. package/example-plugins/packages/web-page-branding/index.js +31 -0
  249. package/example-plugins/packages/web-page-branding/package.json +22 -0
  250. package/example-plugins/scenarios.json +11 -0
  251. package/index.js +384 -0
  252. package/lib/blend-apply.js +107 -0
  253. package/lib/blend-capture.js +249 -0
  254. package/lib/blend-ledger.js +76 -0
  255. package/lib/contract.js +5 -0
  256. package/lib/install.js +516 -0
  257. package/lib/lookup.js +67 -0
  258. package/lib/manifest.js +56 -0
  259. package/lib/pack-root.js +22 -0
  260. package/lib/provenance.js +110 -0
  261. package/lib/publish.js +64 -0
  262. package/lib/reconcile.js +83 -0
  263. package/lib/router.js +55 -0
  264. package/lib/scopes.js +82 -0
  265. package/lib/skills.js +54 -0
  266. package/lib/stage.js +157 -0
  267. package/lib/verify.js +77 -0
  268. package/package.json +56 -3
  269. package/scripts/lib/indexes.mjs +45 -0
  270. package/scripts/lib/manifest.mjs +127 -0
  271. package/scripts/lib/maps.mjs +482 -0
  272. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  273. package/skills/acryl-add-ui/SKILL.md +18 -0
  274. package/skills/acryl-build-plugin/SKILL.md +21 -0
  275. package/skills/acryl-change-plugin/SKILL.md +16 -0
  276. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  277. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  278. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  279. package/skills/acryl-improve-ui/SKILL.md +10 -0
  280. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  281. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  282. package/skills/acryl-share-plugin/SKILL.md +23 -0
  283. package/skills/acryl-tui-ui/SKILL.md +12 -0
  284. package/README.md +0 -3
@@ -0,0 +1,169 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/permission-presets.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Permission Presets
4
+
5
+ English | [中文](permission-presets.zh.md)
6
+
7
+ The permission-preset layer of [dsh-permission-presets](../../packages/interaction/permission-presets) (`ctx.permissionPresets`, `PermissionPresetService`) bundles the two independent enforcement knobs - [sandbox mode](sandbox.md) (`sandbox/mode`) and [approval policy](approval.md) (`approval/policy`) - into named presets a client offers as one Permissions selector. The configured table owns future-session defaults, while the fixed `registerAuto(admit)` hook lets the [Auto review](../../packages/experimental/auto-review/README.md) integration publish its current-session-only option for one effect lifetime. The layer is optional and owns no execution policy: prompt narration and replay keep reading their knob folds, while Auto review owns the additional enforcement. The [package README](../../packages/interaction/permission-presets/README.md) owns composition status and limitations; the [sandbox switching design](../../.agents/notes/implemented/feature/2026-07-06-sandbox.md) owns the original knob rationale.
8
+
9
+ Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
10
+
11
+ ## The preset table
12
+
13
+ A preset maps one stable key to a sandbox/approval bundle plus optional client presentation. The default configured table ships `workspace-write` (`workspace-write` + `ask`) and `danger-full-access` (`danger-full-access` + `never`); `custom` and `auto` are reserved and cannot be configured.
14
+
15
+ ```ts type-equiv
16
+ /** One preset's sandbox/approval bundle and optional client presentation. */
17
+ interface PresetSpec {
18
+ /** The `sandbox/mode` value the preset writes through. */
19
+ sandbox: SandboxMode
20
+ /** The `approval/policy` value the preset writes through. */
21
+ approval: ApprovalPolicy
22
+ /** The display label a client shows for this preset; the raw table key when omitted. */
23
+ name?: string
24
+ /** One user-facing sentence on what the preset means; omitted when not configured. */
25
+ description?: string
26
+ }
27
+ ```
28
+
29
+ ```ts type-equiv
30
+ /** The {@link PermissionPresetService} config: preset table and composition default. */
31
+ interface Config {
32
+ /**
33
+ * The preset table: name → knob bundle. Defaults to `workspace-write`
34
+ * (workspace-write + ask) and `danger-full-access` (danger-full-access +
35
+ * never). The names `custom` and `auto` are reserved for derived state and
36
+ * the Auto review integration respectively.
37
+ */
38
+ presets: Record<string, PresetSpec>
39
+ /**
40
+ * Default for new sessions. When omitted, the preset matching the composed
41
+ * sandbox and approval defaults is used.
42
+ */
43
+ defaultPreset: Volatile<string | undefined>
44
+ }
45
+ ```
46
+
47
+ The service requires a confining `ctx.shell` executor and `ctx.approval`, and misconfiguration fails at plugin load: configured entries named `custom` or `auto` throw, and composing over a bash executor that does not confine (no `sandboxMode` capability fact) throws because presets bundle a sandbox mode.
48
+
49
+ ## Fixed current-session Auto registration
50
+
51
+ The Auto integration calls `registerAuto(admit)` for its effect lifetime. This service fixes the `auto` identity and its `danger-full-access` plus `ask` bundle, and a recorded Auto selection also matches the `never` policy that delegated children pin; the shipped client locale dictionaries own Auto's label and description, while configured preset presentation remains Host-owned. Callers cannot publish another preset through a generic contribution API. Auto appears after configured presets, never enters the `permission.defaultPreset` settings schema, and disappears when the effect is disposed. The synchronous `admit` callback runs before Auto selection mutates the Session and before a stored Auto Session publishes, so a missing or closing integration does not rewrite the durable identity.
52
+
53
+ Registering or removing Auto emits the payload-free `permission-presets/catalog-changed` notification. Process consumers subscribe before calling `catalog()`, then re-read the complete selectable catalog after each notification. The `permissions` Session projection contains only `currentValue`, so catalog changes append no Session event, publish no Session projection frame, and leave the Session sequence unchanged.
54
+
55
+ ## Current preset and the derived `custom`
56
+
57
+ `current(session)` derives the effective preset from the required `permissions` projection. The unit folds the session's sandbox mode, approval policy, and recorded selection; values absent within that state fall back to the executor's configured mode and the approval service config, then `ask`. A missing projection key fails explicitly. The service prefers a still-matching selection, including a recorded Auto selection under the `never` approval policy, then the first matching configured entry, and otherwise returns `CUSTOM_PRESET` (`'custom'`). `custom` is derived-only: clients may display it as the current value, but it is never a switch target or an event payload.
58
+
59
+ `names` lists configured presets in declaration order followed by Auto while its integration is live. `catalog()` returns those selectable entries as one process-level snapshot. `optionOf(name)` builds an available entry (its label falls back to the key) or the derived `custom` presentation, and throws for any other name. Clients join the catalog with the Session projection; `custom` may label the current value but never becomes a catalog entry.
60
+
61
+ ```ts type-equiv
62
+ /** Presentation for an available preset or the derived `custom` current value. */
63
+ interface PresetOption {
64
+ /** Stable option value: a configured preset key, live `auto`, or derived `custom`. */
65
+ value: string
66
+ /** The display label. */
67
+ name: string
68
+ /** One user-facing sentence on what the value means; omitted when not configured. */
69
+ description?: string
70
+ }
71
+ ```
72
+
73
+ ## Switching and the `permission/preset` event
74
+
75
+ `set(session, name)` resolves the preset (unknown names throw), runs Auto admission when applicable, appends a log-only `permission/preset` event unless `name` is already the effective preset, then writes each knob through its own setter - `setSandboxMode` from [dsh-sandbox-policy](../../packages/sandbox/sandbox-policy) and `setApprovalPolicy` from [dsh-user-approval](../../packages/interaction/user-approval) - only when that knob's effective value changes. The selection event precedes the knob events in the same turn, and re-selecting the effective preset appends nothing.
76
+
77
+ `permission/preset` is durable, log-only user intent: it stays out of the model transcript (the knob events own the model-visible consequences through their consumers), and it exists so `current()` can preserve which preset the user chose when two presets share a bundle. The `permissions` projection folds that selection with both knob events and retains the `session/end-seed` boundary used to distinguish a restored empty seed from a fresh session; replay needs no catch-up state or raw-log rescan. A restored `auto` selection requires the live Auto registration before Agent publication. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md); the method signatures are in the generated [service catalog](#ctxpermissionpresets--permissionpresetservice).
78
+
79
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
80
+
81
+ <a id="cordis-surface"></a>
82
+
83
+ ## Cordis API
84
+
85
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
86
+
87
+ <a id="ctxpermissionpresets--permissionpresetservice"></a>
88
+
89
+ ### `ctx.permissionPresets` - `PermissionPresetService`
90
+
91
+ Owns the deployment's configured permission presets, the fixed Auto integration hook, and their write path. Requires a confining `ctx.shell` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.
92
+
93
+ ```ts cordis-catalog
94
+ /**
95
+ * Read the complete process-level catalog exposed to current-session UI.
96
+ * @returns every currently selectable preset in contribution order.
97
+ */
98
+ @Remote('catalog') catalog(): PermissionCatalog
99
+
100
+ /**
101
+ * Publish the fixed current-session Auto preset for the calling
102
+ * integration's effect lifetime.
103
+ * @param admit - synchronous gate run before live Auto selection or restore.
104
+ * @returns the async effect disposer that removes Auto.
105
+ */
106
+ registerAuto(admit: () => void): () => Promise<void>
107
+
108
+ /**
109
+ * Resolve the preset matching the effective knob values. A still-matching
110
+ * last selection wins shared-bundle ties, and a still-selected Auto also
111
+ * matches the `never` approval policy; otherwise the first configured
112
+ * match wins. Returns
113
+ * {@link CUSTOM_PRESET} when no available preset matches.
114
+ * @param session - the session whose knob state is read.
115
+ * @returns the effective preset name, or `custom` when nothing matches.
116
+ */
117
+ current(session: Session): string
118
+
119
+ /**
120
+ * Resolve an available preset's knob bundle.
121
+ * @param name - the preset name to resolve.
122
+ * @returns the configured bundle.
123
+ * @throws when `name` is neither configured nor the currently live Auto preset.
124
+ */
125
+ resolve(name: string): PresetSpec
126
+
127
+ /**
128
+ * Build the client option for an available preset or {@link CUSTOM_PRESET}.
129
+ * A missing label falls back to the preset key.
130
+ * @param name - a configured preset key, live `auto`, or `custom`.
131
+ * @returns the option a client renders.
132
+ * @throws when `name` is neither a configured preset, live `auto`, nor `custom`.
133
+ */
134
+ optionOf(name: string): PresetOption
135
+
136
+ /**
137
+ * Record a changed preset, then update each changed knob through its own
138
+ * setter. Selecting the effective preset again appends nothing.
139
+ * @param session - the session the switch belongs to.
140
+ * @param name - the preset to switch to; unknown names throw.
141
+ */
142
+ set(session: Session, name: string): void
143
+ ```
144
+
145
+ Types: [Session](session.md)
146
+
147
+ Source: [`packages/interaction/permission-presets/src/index.ts`](../../packages/interaction/permission-presets/src/index.ts)
148
+
149
+ <a id="permission-presets-events"></a>
150
+
151
+ ### `permission-presets/*` events
152
+
153
+ <a id="permission-presetscatalog-changed--emit"></a>
154
+
155
+ #### `permission-presets/catalog-changed` - emit
156
+
157
+ The selectable process catalog changed. Payload-free by design: consumers subscribe first, then re-read the complete catalog.
158
+
159
+ ```ts cordis-catalog
160
+ /**
161
+ * The selectable process catalog changed. Payload-free by design:
162
+ * consumers subscribe first, then re-read the complete catalog.
163
+ * @mode emit
164
+ */
165
+ 'permission-presets/catalog-changed'(): void
166
+ ```
167
+
168
+ Source: [`packages/interaction/permission-presets/src/types.ts`](../../packages/interaction/permission-presets/src/types.ts)
169
+ <!-- END GENERATED cordis-surface -->
@@ -0,0 +1,418 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/persistence.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Session Persistence
4
+
5
+ English | [中文](persistence.zh.md)
6
+
7
+ The **durability seam** for the event log. [session.md](session.md) describes the in-memory `Session` - the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its provider model and shipped JSONL backend, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
8
+
9
+ The seam is a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](../../packages/session/session-persistence), `ctx.sessionPersistence`) exposing `create`/`open`/`stat`/`list` over the existing `SessionEvent` - **no parallel persisted event type** - where `create` and `open` return a per-session `SessionHandle` (`read`/`append`/`flush`/`close`) that carries all log access and single-writer ownership. The repository ships [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) as its provider; out-of-tree providers may implement the same service contract. See the [handle-based persistence Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) and the [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
10
+
11
+ ## `SessionHandle` - one open channel onto a stored session
12
+
13
+ Every log read and write flows through a handle, never through id-addressed service methods: the handle is the single door the cross-process write lease guards. A read returns a caller-owned outer slice and the producer-established aliasing state of its event values. One handle type serves both accesses - a mutation on a `read` handle is a runtime `SessionReadOnlyError` rather than a typed split - and in-process single-writer ownership makes a second `open(id, 'write')` reject with `SessionAlreadyOwnedError` while an owner is active.
14
+
15
+ ```ts type-equiv
16
+ /** One persistence event slice returned by {@link SessionHandle.read}. */
17
+ interface SessionHandleReadResult {
18
+ /**
19
+ * Whether event values are exclusively owned or shared only after deep
20
+ * freezing. Slicing preserves the producer's state even when no events remain.
21
+ */
22
+ readonly eventState: SessionSeedEventState
23
+ /** Event values in a caller-owned outer array. */
24
+ readonly events: readonly SessionEvent[]
25
+ }
26
+ ```
27
+
28
+ ```ts type-equiv
29
+ /**
30
+ * One open channel onto a stored session. A handle is single-owner state, not
31
+ * a shared service: `read` never backtracks below what this handle already
32
+ * observed, a `write` handle reads its own successful appends, and `close()`
33
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
34
+ * delegates to it). Every operation on a closed handle rejects with
35
+ * `SessionHandleClosedError`.
36
+ *
37
+ * Freshness across handles: once an `append` or `flush` resolves on a write
38
+ * handle, every read STARTED afterwards on the same backend instance - on any
39
+ * handle, or through `stat`/`list` - observes at least that prefix.
40
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
41
+ * contiguous prefix.
42
+ */
43
+ interface SessionHandle extends AsyncDisposable {
44
+ /** The stored session this handle addresses. */
45
+ readonly id: SessionId
46
+ /** The immutable stored header, fixed at `create`/`open`. */
47
+ readonly header: SessionHeader
48
+ /**
49
+ * Exact fork-inherited prefix length stored with the log; `0` when
50
+ * `header.isSeeded` is false. Storage metadata paired with the header for
51
+ * every body read, never part of the replayable event log.
52
+ */
53
+ readonly inheritedEventCount: SessionLogOffset
54
+ /** Whether this handle may mutate the log. */
55
+ readonly access: SessionAccess
56
+
57
+ /**
58
+ * Read a slice of the valid contiguous logical log. The slice is a legal log
59
+ * prefix segment: a torn physical tail is never returned, and repeated reads
60
+ * on this handle never observe an older state than a prior read.
61
+ * @param offset - first logical event seq to include; defaults to `0`.
62
+ * @param length - maximum number of events to return; defaults to the rest
63
+ * of the log. An offset at or past the end returns an empty list.
64
+ * @param options - optional cancellation.
65
+ * @returns the caller-owned outer slice plus the ownership state of its event values.
66
+ */
67
+ read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<SessionHandleReadResult>
68
+
69
+ /**
70
+ * Append a contiguous batch continuing the current logical end. The first
71
+ * event's `seq` MUST equal the stored next-seq; committed events are never
72
+ * rewritten. Persistence is best-effort: on resolution the batch is
73
+ * accepted, ordered, and visible to reads on this backend instance, but
74
+ * only a resolved {@link flush} promises it survives a crash - a backend
75
+ * may buffer or batch physical writes behind append. Rejects with
76
+ * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
77
+ * when write ownership is gone.
78
+ * @param events - the contiguous batch, in seq order.
79
+ * @param options - optional cancellation observed before the write starts.
80
+ */
81
+ append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
82
+
83
+ /**
84
+ * The durability barrier - the one operation that promises storage: on
85
+ * resolution every acknowledged append is durable and the session is
86
+ * materialized for other processes; an empty created session becomes
87
+ * durably listable here. Callers that must survive a crash flush; a backend
88
+ * whose `append` already persists on resolution treats this as
89
+ * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
90
+ * handle.
91
+ * @param options - optional cancellation observed before the barrier starts.
92
+ */
93
+ flush(options?: SessionHandleFlushOptions): Promise<void>
94
+
95
+ /**
96
+ * Release the handle: a read handle frees local resources; a write handle
97
+ * completes pending durability and releases write ownership. Idempotent,
98
+ * asynchronous, and deliberately not cancellable.
99
+ */
100
+ close(): Promise<void>
101
+ }
102
+ ```
103
+
104
+ A created session is observable in this process from the moment `create` resolves, while a backend may defer physical materialization (a pure optimization) until the first `append` or `flush`; other processes see only materialized sessions, and a session that never materialized before a crash never existed.
105
+
106
+ ## The flush checkpoint
107
+
108
+ `session/event` is a *synchronous* notification; the mounted backend routes it by session id into the active write handle's bounded write-behind window without blocking the producer (the backend installs these listeners once, because persistence already enforces one active write handle per id). The first pending event starts a fixed internal batching window, and later events join without resetting its deadline. Expiry starts one durable `append` through the session's write handle; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events in order, pauses the automatic path, and is reported through the logger; the next explicit flush retries and rejects loudly to its caller. `session/disposed` performs the same final drain and closes the handle, and `close()` itself drains the routed buffer through the still-open storage, so backend teardown's close sweep loses nothing. The window bounds only intentional batching wait, not event-loop scheduling or backend durability latency.
109
+
110
+ ## Crash recovery preserves an interrupted turn
111
+
112
+ A log crashed mid-turn ends with an open `turn/start` and no `turn/end`. Persistence does **not** truncate or repair it - a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. It returns the physically valid contiguous log; only the incomplete fragment of a torn physical tail, belonging to an append that never resolved, is discarded - complete records recovered from it (the JSONL backend partially decodes a torn Zstandard frame) are durably rewritten by the write path before the handle's first new append. Repair is the reader's job: resume (agent-loop) reads the stored log through its write handle, computes `interruptedTurnClosers` - missing tool errors, any open `step/end`, and a synthetic `turn/end { reason: { kind: 'interrupted' } }` - and appends them through the same handle as an ordinary batch before publishing the Session. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](session.md#why-a-turn-ended-turnendreasonmap)).
113
+
114
+ Repair therefore writes only under write ownership: a live session's write handle is held by its lifecycle owner, so a concurrent `open(id, 'write')` rejects with `SessionAlreadyOwnedError` instead of racing repair against a live turn. Read-only observers (session-query) balance an interrupted cold log with the same closers in memory only, writing nothing back.
115
+
116
+ Read-only observation is `open(id, 'read')`: the handle serves validated contiguous prefix slices, never a torn tail, and repeated reads on one handle never observe an older state than a prior read. There is no persistence-side prepared-Session cache: session-query owns its cold-read cache, keying one balanced cold Session per id on the `stat().revision` change token and re-reading only when the token changes. The [handle-based persistence Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) owns this lifecycle; the archived [Session preparation record](../../.agents/notes/archived/architecture/2026-08-05-session-preparation.md) documents the original publication-boundary `SessionPreparation` decision.
117
+
118
+ ## `SessionLocation` - refusal-diagnostics artifact target
119
+
120
+ `SessionLocation` is not a consumer-facing query: log access goes through a session handle's `read`. It survives only as refusal diagnostics, letting a `SessionFormatUnsupportedError` name the raw log a build refused to interpret. JSONL supplies the absolute transcript path inside its project/session directory; a backend without one artifact per session supplies nothing.
121
+
122
+ ```ts type-equiv
123
+ /**
124
+ * A backend-resolved, per-session local artifact location. Carried only by
125
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
126
+ * find the raw log a build refused to interpret; it is not a consumer-facing
127
+ * query - log access goes through a session handle's `read`.
128
+ */
129
+ interface SessionLocation {
130
+ /** Backend-specific artifact kind, for example `jsonl`. */
131
+ readonly kind: string
132
+ /** Absolute path to this session's backend-owned artifact. */
133
+ readonly path: string
134
+ }
135
+ ```
136
+
137
+ <a id="sessionheader--metadata-beside-the-log"></a>
138
+
139
+ ## `SessionHeader` - metadata beside the log
140
+
141
+ Per-session metadata travels **separately** from the event log: the header carries format version, cwd, and the `isSeeded` lineage bit, while body-bearing storage values carry the exact inherited cut beside it. Neither belongs to `SessionEventMap` or reaches `deriveMessages()`. The logical header is attached through `session.header`; the Session exposes its cut as `inheritedEventCount`.
142
+
143
+ Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
144
+
145
+ ```ts type-equiv
146
+ /**
147
+ * Immutable validated storage metadata, kept outside the conversation event log.
148
+ */
149
+ interface SessionHeader {
150
+ /**
151
+ * Current logical format version, stamped from {@link SESSION_FORMAT_VERSION}.
152
+ * Historical physical headers are translated before entering this interface.
153
+ */
154
+ readonly version: typeof SESSION_FORMAT_VERSION
155
+ /** The session's id (mirrors the {@link Session}'s id). */
156
+ readonly id: SessionId
157
+ /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
158
+ readonly createdAt: number
159
+ /** Absolute working directory the session was created in (if any). */
160
+ readonly cwd?: string
161
+ /** The session this one was forked from (seed lineage), if any. */
162
+ readonly parentSession?: SessionId
163
+ /**
164
+ * Whether this Session contains a fork-inherited event prefix. The exact prefix
165
+ * length is Session state rather than ordinary header metadata.
166
+ */
167
+ readonly isSeeded: boolean
168
+ /**
169
+ * Coarse product classification for a session created as a subagent child.
170
+ * This is presentation metadata, not proof that the child is continuable.
171
+ */
172
+ readonly origin?: 'subagent'
173
+ /**
174
+ * Delegation depth: absent (zero) for a top-level session, parent depth + 1
175
+ * for a subagent child. Persisted so a recursion budget survives restart and
176
+ * resume - a runtime-only depth would reset a resumed child to top-level.
177
+ */
178
+ readonly delegationDepth?: number
179
+ /**
180
+ * Id of the agent preset this session's agent was composed from, when the
181
+ * deployment composes per session. Durable because the preset decides the
182
+ * session's tools and prompt: a resume that restored a different composition
183
+ * would replay history the model can no longer act on.
184
+ */
185
+ readonly agentPreset?: string
186
+ }
187
+ ```
188
+
189
+ ## Format refusal - logs a build cannot faithfully read
190
+
191
+ A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. `stat` and `list` classify the highest canonical generation and translate a supported historical header without reading or mutating its body. Historical `open` calls share one per-session migration preparation before returning current logical values and leave every source path, byte, and inode unchanged. The JSONL provider returns a read handle from that in-memory result without publishing; a write open holds its single-writer claim and file lease while it reuses the preparation, exclusively publishes the final current generation, and only then returns the writable handle. A future highest generation refuses even when an older readable generation remains. Current-format restoration retains installed extensions and unknown events carrying `ignorable: true`; historical v0/v1/v2 migration refuses an unknown type even when marked ignorable. The message appends the selected raw log path when the backend keeps one artifact per session. An out-of-tree backend must enforce equivalent current-only handle values and direction-aware refusals at its physical-format entry. The [released-format migration decision](../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md) owns the chain and immutable-publication rules.
192
+
193
+ ## `CreateSessionOptions` - seeding and metadata
194
+
195
+ Creating a `Session` through the store takes a `seed` (initial replay or fork history), an optional exact `inheritedEventCount`, and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller may supply the validated absolute `cwd`, `parentSession` lineage, `isSeeded` lineage bit, optional coarse `origin`, `delegationDepth`, `agentPreset`, and an existing `createdAt`. A seeded creation requires an explicit seed equal to its inherited prefix and an exact cut; the constructor appends the child-owned tagged end-seed marker at that cut before setup adds child-owned events. `origin: 'subagent'` lets product navigation hide duplicate child rows; it does not prove that a descriptor is valid or that the child can resume.
196
+
197
+ ```ts type-equiv
198
+ /**
199
+ * Options for creating a {@link Session} via the store. `seed` replays/forks
200
+ * an existing event log; `meta` carries the caller-supplied storage fields the
201
+ * store folds into a {@link SessionHeader}.
202
+ */
203
+ interface CreateSessionOptions {
204
+ /** Initial replay or fork history supplied at construction. */
205
+ readonly seed?: readonly SessionEvent[]
206
+ /**
207
+ * Exact fork-inherited prefix length when `meta.isSeeded` is true. The
208
+ * constructor appends the child-owned tagged marker at the cut unless
209
+ * the seed already includes it followed by child-owned fork closers.
210
+ */
211
+ readonly inheritedEventCount?: SessionLogOffset
212
+ /**
213
+ * Storage metadata read once before publication. `isSeeded` marks fork
214
+ * lineage; supplying replay history alone does not make it inherited.
215
+ */
216
+ readonly meta?: {
217
+ readonly cwd?: string
218
+ readonly parentSession?: SessionId
219
+ readonly createdAt?: number
220
+ readonly isSeeded?: boolean
221
+ readonly origin?: 'subagent'
222
+ readonly delegationDepth?: number
223
+ readonly agentPreset?: string
224
+ }
225
+ }
226
+ ```
227
+
228
+ Replay/fork is therefore `ctx.agents.create({ sessionId, seed, meta })` - a fork additionally supplies `inheritedEventCount` with `meta.isSeeded: true`, and only agent-loop-published sessions persist, and the loop stores the seed through the new session's write handle before publication; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
229
+
230
+ ## Preparation and restoration ownership
231
+
232
+ `SessionStore.prepare()` accepts ordinary creation options or an adoptable seed through `RestoredSessionOptions`. Its `eventState` says whether event values are independently owned or shared only after deep freezing; the producer establishes that state, and slicing does not infer a different state from result length. Restoration validates and adopts those values without another copy or freeze pass. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. agent-loop's resume reads this result through the session's write handle and appends independently owned `interruptedTurnClosers` before preparation.
233
+
234
+ ```ts type-equiv
235
+ /**
236
+ * Aliasing state of an adoptable Session seed. `shared-frozen` permits deeply
237
+ * frozen aliases plus independently owned unfrozen values in the same seed.
238
+ */
239
+ type SessionSeedEventState = 'detached' | 'shared-frozen'
240
+ ```
241
+
242
+ ```ts type-equiv
243
+ /**
244
+ * Adoptable storage values transferred to {@link SessionStore.prepare}
245
+ * without another copy or freeze pass.
246
+ */
247
+ interface RestoredSessionOptions {
248
+ /** Events that are independently owned or already deeply frozen. */
249
+ readonly seed: SessionEvent[]
250
+ /** Independently owned storage metadata to validate and freeze in place. */
251
+ readonly meta: SessionHeader
252
+ /** Exact number of fork-inherited leading events decoded from storage. */
253
+ readonly inheritedEventCount: SessionLogOffset
254
+ /** Aliasing state carried from the operation that produced the seed. */
255
+ readonly eventState: SessionSeedEventState
256
+ }
257
+ ```
258
+
259
+ ```ts type-equiv
260
+ /** Inputs accepted while constructing an unpublished Session. */
261
+ type PrepareSessionOptions =
262
+ | (CreateSessionOptions & { readonly eventState?: undefined })
263
+ | RestoredSessionOptions
264
+ ```
265
+
266
+ ```ts type-equiv
267
+ /** Options for a preparation whose provider retains unpublished state. */
268
+ interface SessionPreparationOptions {
269
+ /** Release provider-owned state when the Session was not published. */
270
+ readonly release?: () => void
271
+ }
272
+ ```
273
+
274
+ ```ts public-api
275
+ /**
276
+ * One exact unpublished Session and the provider state that keeps it usable.
277
+ * Disposal is synchronous and idempotent. Providers decide whether release
278
+ * returns the Session to a cache or discards it; publication may consume that
279
+ * state before disposal, making the callback a no-op.
280
+ */
281
+ declare class SessionPreparation implements Disposable {
282
+ /** The exact Session to use for setup and publication. */
283
+ readonly session: Session;
284
+ /**
285
+ * Wrap an unpublished Session in one preparation lifetime.
286
+ * @param session - exact unpublished Session.
287
+ * @param options - optional provider release behavior.
288
+ * @returns a preparation disposed after publication or rollback.
289
+ */
290
+ static create(session: Session, options?: SessionPreparationOptions): SessionPreparation;
291
+ /** Release provider state once when this preparation leaves its caller. */
292
+ [Symbol.dispose](): void;
293
+ }
294
+ ```
295
+
296
+ ## Lightweight source revisions
297
+
298
+ Consumers of derived read models compare a cheap opaque revision before loading a full event log. The revision is a per-backend-instance change token from `stat`/`list`: equal revisions may be treated as an unchanged log; unequal revisions promise nothing, and write-ownership churn never changes one. session-query keys its cold-read cache on it; the token plays no part in open, read, or resume.
299
+
300
+ ```ts type-equiv
301
+ /**
302
+ * Backend-owned token that identifies both one storage source and one revision
303
+ * of a persisted session log.
304
+ */
305
+ type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
306
+ ```
307
+
308
+ ```ts type-equiv
309
+ /**
310
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
311
+ * and {@link SessionPersistence.list} without reading the full event log.
312
+ */
313
+ interface SessionPersistenceSnapshot {
314
+ /** Detached metadata for one stored session. */
315
+ readonly header: SessionHeader
316
+ /** Opaque change token; see {@link SessionPersistence.stat}. */
317
+ readonly revision: SessionPersistenceRevision
318
+ /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
319
+ readonly eventCount?: number
320
+ /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
321
+ readonly sizeBytes?: number
322
+ }
323
+ ```
324
+
325
+ The optional `eventCount`/`sizeBytes` fields remain cheap backend observations for consumers that explicitly need them. Session listing does not use either field to open cold logs: it reads headers plus identity-checked projection-cache hints only, so a cache or Session-format upgrade never turns startup into a body scan.
326
+
327
+ ## The backend
328
+
329
+ The shipped provider implements the abstract `SessionPersistence` contract (`create`/`open`/`stat`/`list`, with per-session `SessionHandle`s carrying `read`/`append`/`flush`/`close` and optional cancellation throughout) and passes the shared persistence contract suite:
330
+
331
+ - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)** - an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic materialization, per-batch `fsync` appends, and torn-tail truncation before the first new append. `stat`/`list` carry `sizeBytes` and a best-effort `fs.stat`-derived revision.
332
+
333
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
334
+
335
+ <a id="cordis-surface"></a>
336
+
337
+ ## Cordis API
338
+
339
+ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) - the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
340
+
341
+ <a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
342
+
343
+ ### `ctx.sessionPersistence` - `SessionPersistence` (abstract seam)
344
+
345
+ Durable append-only session storage addressed through per-session handles.
346
+
347
+ Storage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` - per handle or service-wide - is the durability barrier.
348
+
349
+ Visibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.
350
+
351
+ Freshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.
352
+
353
+ ```ts cordis-catalog
354
+ /**
355
+ * Create a new stored session and take its write ownership.
356
+ * @param header - the immutable header (id, version, cwd, lineage) to store.
357
+ * @param options - optional cancellation.
358
+ * @returns a `write` handle owned by the caller; close it to release ownership.
359
+ * @throws {SessionAlreadyExistsError} when the id already exists.
360
+ */
361
+ abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
362
+
363
+ /**
364
+ * Open an existing stored session.
365
+ *
366
+ * `read` never takes ownership and works while another handle (or process)
367
+ * holds write ownership. `write` atomically claims single-writer ownership;
368
+ * an existing active owner rejects.
369
+ * @param id - the stored session to open.
370
+ * @param access - `read` or `write`.
371
+ * @param options - optional cancellation.
372
+ * @returns the open handle.
373
+ * @throws {SessionPersistenceNotFoundError} when the session does not exist.
374
+ * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
375
+ */
376
+ abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
377
+
378
+ /**
379
+ * Flush every active write handle owned by this service instance in one
380
+ * durability barrier: each handle's routed live events drain durably and
381
+ * its session materializes, exactly as that handle's own
382
+ * `SessionHandle.flush` would. Read handles buffer nothing and are
383
+ * untouched. A handle closed concurrently counts as flushed - close itself
384
+ * drains durably.
385
+ * @returns resolution once every write handle active at the call has flushed.
386
+ * @throws {AggregateError} naming each session whose flush failed; the
387
+ * remaining handles still flush.
388
+ */
389
+ abstract flush(): Promise<void>
390
+
391
+ /**
392
+ * Observe one stored session without reading its event log or taking
393
+ * ownership.
394
+ *
395
+ * The snapshot's `revision` is an opaque change token comparable only
396
+ * against revisions from the same service instance and session id: equal
397
+ * revisions may be treated as an unchanged log; unequal revisions promise
398
+ * nothing. Write-ownership churn does not change a revision. It exists for
399
+ * derived read-model caches keyed off `stat`/`list`; it plays no part in
400
+ * open, read, or resume.
401
+ * @param id - the stored session to observe.
402
+ * @param options - optional cancellation.
403
+ * @returns the snapshot, or `undefined` when the session does not exist.
404
+ */
405
+ abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
406
+
407
+ /**
408
+ * List every stored session visible to this process, in no promised order.
409
+ * @param options - optional cancellation.
410
+ * @returns one snapshot per stored session.
411
+ */
412
+ abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
413
+ ```
414
+
415
+ Types: [SessionId](core.md)
416
+
417
+ Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
418
+ <!-- END GENERATED cordis-surface -->