@acryldev/plugin-context 0.0.0-stage → 0.1.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 (284) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/docs/README.md +160 -0
  4. package/docs/delivery/local-live.md +113 -0
  5. package/docs/delivery/marketplace.md +16 -0
  6. package/docs/docs.json +2836 -0
  7. package/docs/extending/agent-preset.md +37 -0
  8. package/docs/extending/chat-command.md +28 -0
  9. package/docs/extending/client-slot.md +135 -0
  10. package/docs/extending/config-schema.md +7 -0
  11. package/docs/extending/cordis-core.md +63 -0
  12. package/docs/extending/desktop-app.md +53 -0
  13. package/docs/extending/desktop-main.md +25 -0
  14. package/docs/extending/event-hook.md +14 -0
  15. package/docs/extending/host-route.md +33 -0
  16. package/docs/extending/llm-adapter.md +38 -0
  17. package/docs/extending/packaging.md +53 -0
  18. package/docs/extending/prompt-contribution.md +9 -0
  19. package/docs/extending/service.md +13 -0
  20. package/docs/extending/skill-provider.md +9 -0
  21. package/docs/extending/state-and-persistence.md +71 -0
  22. package/docs/extending/three-role-capability.md +33 -0
  23. package/docs/extending/tool-plugin.md +24 -0
  24. package/docs/extending/tui-command.md +8 -0
  25. package/docs/extending/tui-components.md +61 -0
  26. package/docs/extending/ui-branding.md +43 -0
  27. package/docs/extending/ui-components.md +56 -0
  28. package/docs/extending/ui-customization.md +41 -0
  29. package/docs/extending/ui-library.md +66 -0
  30. package/docs/extending/ui-theme.md +55 -0
  31. package/docs/extending/workspace-tab.md +50 -0
  32. package/docs/maps/events.md +108 -0
  33. package/docs/maps/mount-points.md +154 -0
  34. package/docs/maps/slot-contracts.md +3376 -0
  35. package/docs/maps/taxonomy.md +306 -0
  36. package/docs/maps/theme-tokens.md +115 -0
  37. package/docs/maps/ui-components.md +26 -0
  38. package/docs/reference/cookbook/adding-a-package.md +174 -0
  39. package/docs/reference/cookbook/adding-a-remote-api.md +199 -0
  40. package/docs/reference/cookbook/adding-a-settings-card.md +74 -0
  41. package/docs/reference/cookbook/adding-a-tool.md +103 -0
  42. package/docs/reference/cookbook/adding-an-llm-adapter.md +45 -0
  43. package/docs/reference/cookbook/extension-cookbook.md +134 -0
  44. package/docs/reference/cordis-api/context.md +366 -0
  45. package/docs/reference/cordis-api/events.md +209 -0
  46. package/docs/reference/cordis-api/fiber.md +377 -0
  47. package/docs/reference/cordis-api/inherited.md +40 -0
  48. package/docs/reference/cordis-api/registry.md +154 -0
  49. package/docs/reference/cordis-api/service.md +104 -0
  50. package/docs/reference/cordis-guides/cordis-usage-cheatsheet.md +167 -0
  51. package/docs/reference/cordis-guides/cordis_system_guide_for_coding_agents.md +4666 -0
  52. package/docs/reference/cordis-guides/development-canvas-plugin.md +109 -0
  53. package/docs/reference/cordis-guides/hello-world-plugin-guide.md +517 -0
  54. package/docs/reference/harness/agent-lifecycle.md +93 -0
  55. package/docs/reference/harness/architecture.md +168 -0
  56. package/docs/reference/harness/capability-seams.md +675 -0
  57. package/docs/reference/harness/config-catalog.md +4523 -0
  58. package/docs/reference/harness/cordis-primer.md +47 -0
  59. package/docs/reference/harness/defensive-patterns.md +35 -0
  60. package/docs/reference/harness/event-producer-consumer.md +111 -0
  61. package/docs/reference/harness/glossary.md +47 -0
  62. package/docs/reference/harness/tool-catalog.md +2721 -0
  63. package/docs/reference/harness/tool-execution-pipeline.md +67 -0
  64. package/docs/reference/subsystems/README.md +75 -0
  65. package/docs/reference/subsystems/agent-team.md +233 -0
  66. package/docs/reference/subsystems/approval.md +172 -0
  67. package/docs/reference/subsystems/attachment.md +363 -0
  68. package/docs/reference/subsystems/boot.md +324 -0
  69. package/docs/reference/subsystems/browser-use.md +69 -0
  70. package/docs/reference/subsystems/client-modules.md +186 -0
  71. package/docs/reference/subsystems/client-resources.md +94 -0
  72. package/docs/reference/subsystems/commands.md +225 -0
  73. package/docs/reference/subsystems/compaction.md +286 -0
  74. package/docs/reference/subsystems/computer-use.md +58 -0
  75. package/docs/reference/subsystems/conversation.md +287 -0
  76. package/docs/reference/subsystems/core.md +1107 -0
  77. package/docs/reference/subsystems/credentials.md +497 -0
  78. package/docs/reference/subsystems/deliverables.md +180 -0
  79. package/docs/reference/subsystems/extensions.md +386 -0
  80. package/docs/reference/subsystems/feedback.md +402 -0
  81. package/docs/reference/subsystems/filesystem.md +532 -0
  82. package/docs/reference/subsystems/goal.md +315 -0
  83. package/docs/reference/subsystems/invariants.md +90 -0
  84. package/docs/reference/subsystems/jobs.md +501 -0
  85. package/docs/reference/subsystems/llm-streaming.md +1131 -0
  86. package/docs/reference/subsystems/lsp.md +204 -0
  87. package/docs/reference/subsystems/mcp.md +141 -0
  88. package/docs/reference/subsystems/office-to-pdf.md +89 -0
  89. package/docs/reference/subsystems/otel.md +46 -0
  90. package/docs/reference/subsystems/permission-presets.md +169 -0
  91. package/docs/reference/subsystems/persistence.md +418 -0
  92. package/docs/reference/subsystems/plan.md +89 -0
  93. package/docs/reference/subsystems/product-telemetry.md +81 -0
  94. package/docs/reference/subsystems/ptc-runtime.md +234 -0
  95. package/docs/reference/subsystems/sandbox.md +223 -0
  96. package/docs/reference/subsystems/schedule.md +545 -0
  97. package/docs/reference/subsystems/scope.md +61 -0
  98. package/docs/reference/subsystems/session-projection.md +358 -0
  99. package/docs/reference/subsystems/session-query.md +511 -0
  100. package/docs/reference/subsystems/session-reference.md +226 -0
  101. package/docs/reference/subsystems/session-telemetry.md +214 -0
  102. package/docs/reference/subsystems/session-title.md +206 -0
  103. package/docs/reference/subsystems/session.md +1300 -0
  104. package/docs/reference/subsystems/settings.md +157 -0
  105. package/docs/reference/subsystems/shell.md +316 -0
  106. package/docs/reference/subsystems/sidebar-right.md +160 -0
  107. package/docs/reference/subsystems/skills.md +354 -0
  108. package/docs/reference/subsystems/slots.md +201 -0
  109. package/docs/reference/subsystems/spill.md +126 -0
  110. package/docs/reference/subsystems/ssh.md +137 -0
  111. package/docs/reference/subsystems/storage.md +262 -0
  112. package/docs/reference/subsystems/subagent.md +762 -0
  113. package/docs/reference/subsystems/subprocess.md +323 -0
  114. package/docs/reference/subsystems/system-prompt.md +226 -0
  115. package/docs/reference/subsystems/terminal.md +186 -0
  116. package/docs/reference/subsystems/todo.md +34 -0
  117. package/docs/reference/subsystems/token-meter.md +108 -0
  118. package/docs/reference/subsystems/tools.md +749 -0
  119. package/docs/reference/subsystems/typert.md +489 -0
  120. package/docs/reference/subsystems/user-questions.md +309 -0
  121. package/docs/reference/subsystems/voice-input.md +166 -0
  122. package/docs/reference/subsystems/web-client.md +102 -0
  123. package/docs/reference/subsystems/web-server.md +228 -0
  124. package/docs/reference/subsystems/web.md +208 -0
  125. package/docs/reference/subsystems/webhook.md +72 -0
  126. package/docs/reference/subsystems/workflow.md +280 -0
  127. package/docs/reference/subsystems/workspace.md +661 -0
  128. package/docs/start-here/blueprints.md +33 -0
  129. package/docs/start-here/this-runtime.md +84 -0
  130. package/docs/start-here/troubleshooting.md +29 -0
  131. package/docs/start-here/trust-and-safety.md +39 -0
  132. package/docs/start-here/verify-before-done.md +46 -0
  133. package/example-plugins/README.md +45 -0
  134. package/example-plugins/packages/agent-preset-reviewer/agent.cordis.yml +18 -0
  135. package/example-plugins/packages/agent-preset-reviewer/preset.yml +3 -0
  136. package/example-plugins/packages/capability-swap-consumer/cordis.patch.yml +3 -0
  137. package/example-plugins/packages/capability-swap-consumer/index.js +14 -0
  138. package/example-plugins/packages/capability-swap-consumer/package.json +25 -0
  139. package/example-plugins/packages/capability-swap-provider-loud/cordis.patch.yml +3 -0
  140. package/example-plugins/packages/capability-swap-provider-loud/index.js +20 -0
  141. package/example-plugins/packages/capability-swap-provider-loud/package.json +25 -0
  142. package/example-plugins/packages/capability-swap-provider-quiet/cordis.patch.yml +3 -0
  143. package/example-plugins/packages/capability-swap-provider-quiet/index.js +20 -0
  144. package/example-plugins/packages/capability-swap-provider-quiet/package.json +25 -0
  145. package/example-plugins/packages/chat-command-basic/cordis.patch.yml +3 -0
  146. package/example-plugins/packages/chat-command-basic/index.js +26 -0
  147. package/example-plugins/packages/chat-command-basic/package.json +25 -0
  148. package/example-plugins/packages/client-chat-message-action/client.js +46 -0
  149. package/example-plugins/packages/client-chat-message-action/cordis.patch.yml +3 -0
  150. package/example-plugins/packages/client-chat-message-action/index.js +9 -0
  151. package/example-plugins/packages/client-chat-message-action/package.json +31 -0
  152. package/example-plugins/packages/client-slot-header-action/client.js +57 -0
  153. package/example-plugins/packages/client-slot-header-action/cordis.patch.yml +3 -0
  154. package/example-plugins/packages/client-slot-header-action/index.js +13 -0
  155. package/example-plugins/packages/client-slot-header-action/package.json +31 -0
  156. package/example-plugins/packages/client-slot-sidebar-tab/client.js +57 -0
  157. package/example-plugins/packages/client-slot-sidebar-tab/cordis.patch.yml +3 -0
  158. package/example-plugins/packages/client-slot-sidebar-tab/index.js +9 -0
  159. package/example-plugins/packages/client-slot-sidebar-tab/package.json +32 -0
  160. package/example-plugins/packages/client-theme-override/client.js +52 -0
  161. package/example-plugins/packages/client-theme-override/cordis.patch.yml +3 -0
  162. package/example-plugins/packages/client-theme-override/index.js +9 -0
  163. package/example-plugins/packages/client-theme-override/package.json +30 -0
  164. package/example-plugins/packages/client-tool-view/client.js +47 -0
  165. package/example-plugins/packages/client-tool-view/cordis.patch.yml +3 -0
  166. package/example-plugins/packages/client-tool-view/index.js +24 -0
  167. package/example-plugins/packages/client-tool-view/package.json +34 -0
  168. package/example-plugins/packages/client-ui-components/client.js +77 -0
  169. package/example-plugins/packages/client-ui-components/cordis.patch.yml +3 -0
  170. package/example-plugins/packages/client-ui-components/index.js +9 -0
  171. package/example-plugins/packages/client-ui-components/package.json +31 -0
  172. package/example-plugins/packages/client-ui-library/client.js +715 -0
  173. package/example-plugins/packages/client-ui-library/cordis.patch.yml +3 -0
  174. package/example-plugins/packages/client-ui-library/index.js +9 -0
  175. package/example-plugins/packages/client-ui-library/package.json +37 -0
  176. package/example-plugins/packages/client-workspace-tab/client.js +72 -0
  177. package/example-plugins/packages/client-workspace-tab/cordis.patch.yml +3 -0
  178. package/example-plugins/packages/client-workspace-tab/index.js +9 -0
  179. package/example-plugins/packages/client-workspace-tab/package.json +30 -0
  180. package/example-plugins/packages/config-schema-basic/cordis.patch.yml +3 -0
  181. package/example-plugins/packages/config-schema-basic/index.js +19 -0
  182. package/example-plugins/packages/config-schema-basic/package.json +25 -0
  183. package/example-plugins/packages/desktop-main-profile-info/cordis.patch.yml +3 -0
  184. package/example-plugins/packages/desktop-main-profile-info/index.js +22 -0
  185. package/example-plugins/packages/desktop-main-profile-info/package.json +25 -0
  186. package/example-plugins/packages/event-hook-basic/cordis.patch.yml +3 -0
  187. package/example-plugins/packages/event-hook-basic/index.js +17 -0
  188. package/example-plugins/packages/event-hook-basic/package.json +22 -0
  189. package/example-plugins/packages/generated-capability-template/cordis.patch.yml +3 -0
  190. package/example-plugins/packages/generated-capability-template/index.js +16 -0
  191. package/example-plugins/packages/generated-capability-template/package.json +42 -0
  192. package/example-plugins/packages/host-route-basic/cordis.patch.yml +3 -0
  193. package/example-plugins/packages/host-route-basic/index.js +20 -0
  194. package/example-plugins/packages/host-route-basic/package.json +29 -0
  195. package/example-plugins/packages/lifecycle-function-basic/cordis.patch.yml +3 -0
  196. package/example-plugins/packages/lifecycle-function-basic/index.js +12 -0
  197. package/example-plugins/packages/lifecycle-function-basic/package.json +15 -0
  198. package/example-plugins/packages/lifecycle-function-hot-shim/cordis.patch.yml +3 -0
  199. package/example-plugins/packages/lifecycle-function-hot-shim/impl.js +5 -0
  200. package/example-plugins/packages/lifecycle-function-hot-shim/index.js +18 -0
  201. package/example-plugins/packages/lifecycle-function-hot-shim/package.json +23 -0
  202. package/example-plugins/packages/lifecycle-hooks-observer/cordis.patch.yml +3 -0
  203. package/example-plugins/packages/lifecycle-hooks-observer/index.js +23 -0
  204. package/example-plugins/packages/lifecycle-hooks-observer/package.json +22 -0
  205. package/example-plugins/packages/llm-adapter-echo/cordis.patch.yml +3 -0
  206. package/example-plugins/packages/llm-adapter-echo/index.js +42 -0
  207. package/example-plugins/packages/llm-adapter-echo/package.json +25 -0
  208. package/example-plugins/packages/prompt-assemble-hook/cordis.patch.yml +3 -0
  209. package/example-plugins/packages/prompt-assemble-hook/index.js +22 -0
  210. package/example-plugins/packages/prompt-assemble-hook/package.json +22 -0
  211. package/example-plugins/packages/prompt-contribution-basic/cordis.patch.yml +3 -0
  212. package/example-plugins/packages/prompt-contribution-basic/index.js +18 -0
  213. package/example-plugins/packages/prompt-contribution-basic/package.json +22 -0
  214. package/example-plugins/packages/service-consumer-greeter/cordis.patch.yml +3 -0
  215. package/example-plugins/packages/service-consumer-greeter/index.js +14 -0
  216. package/example-plugins/packages/service-consumer-greeter/package.json +22 -0
  217. package/example-plugins/packages/service-provider-greeter/cordis.patch.yml +3 -0
  218. package/example-plugins/packages/service-provider-greeter/index.js +22 -0
  219. package/example-plugins/packages/service-provider-greeter/package.json +25 -0
  220. package/example-plugins/packages/settings-section-basic/cordis.patch.yml +3 -0
  221. package/example-plugins/packages/settings-section-basic/index.js +34 -0
  222. package/example-plugins/packages/settings-section-basic/package.json +26 -0
  223. package/example-plugins/packages/skill-provider-basic/cordis.patch.yml +3 -0
  224. package/example-plugins/packages/skill-provider-basic/index.js +31 -0
  225. package/example-plugins/packages/skill-provider-basic/package.json +22 -0
  226. package/example-plugins/packages/state-host-store/client.js +57 -0
  227. package/example-plugins/packages/state-host-store/cordis.patch.yml +3 -0
  228. package/example-plugins/packages/state-host-store/index.js +90 -0
  229. package/example-plugins/packages/state-host-store/package.json +31 -0
  230. package/example-plugins/packages/state-workspace-file/cordis.patch.yml +3 -0
  231. package/example-plugins/packages/state-workspace-file/index.js +52 -0
  232. package/example-plugins/packages/state-workspace-file/package.json +25 -0
  233. package/example-plugins/packages/tool-basic/cordis.patch.yml +3 -0
  234. package/example-plugins/packages/tool-basic/index.js +25 -0
  235. package/example-plugins/packages/tool-basic/package.json +25 -0
  236. package/example-plugins/packages/tool-policy-hook/cordis.patch.yml +3 -0
  237. package/example-plugins/packages/tool-policy-hook/index.js +28 -0
  238. package/example-plugins/packages/tool-policy-hook/package.json +25 -0
  239. package/example-plugins/packages/tui-command-basic/cordis.patch.yml +3 -0
  240. package/example-plugins/packages/tui-command-basic/index.js +24 -0
  241. package/example-plugins/packages/tui-command-basic/package.json +22 -0
  242. package/example-plugins/packages/tui-overlay-themed/cordis.patch.yml +3 -0
  243. package/example-plugins/packages/tui-overlay-themed/index.js +65 -0
  244. package/example-plugins/packages/tui-overlay-themed/package.json +25 -0
  245. package/example-plugins/packages/tui-ui-library/cordis.patch.yml +3 -0
  246. package/example-plugins/packages/tui-ui-library/index.js +73 -0
  247. package/example-plugins/packages/tui-ui-library/package.json +29 -0
  248. package/example-plugins/packages/web-page-branding/cordis.patch.yml +3 -0
  249. package/example-plugins/packages/web-page-branding/index.js +31 -0
  250. package/example-plugins/packages/web-page-branding/package.json +22 -0
  251. package/example-plugins/scenarios.json +11 -0
  252. package/index.js +384 -0
  253. package/lib/blend-apply.js +107 -0
  254. package/lib/blend-capture.js +249 -0
  255. package/lib/blend-ledger.js +76 -0
  256. package/lib/contract.js +5 -0
  257. package/lib/install.js +516 -0
  258. package/lib/lookup.js +67 -0
  259. package/lib/manifest.js +56 -0
  260. package/lib/pack-root.js +22 -0
  261. package/lib/provenance.js +110 -0
  262. package/lib/publish.js +64 -0
  263. package/lib/reconcile.js +83 -0
  264. package/lib/router.js +55 -0
  265. package/lib/scopes.js +82 -0
  266. package/lib/skills.js +54 -0
  267. package/lib/stage.js +157 -0
  268. package/lib/verify.js +77 -0
  269. package/package.json +58 -3
  270. package/scripts/lib/indexes.mjs +45 -0
  271. package/scripts/lib/manifest.mjs +127 -0
  272. package/scripts/lib/maps.mjs +482 -0
  273. package/skills/acryl-add-provider-or-capability/SKILL.md +12 -0
  274. package/skills/acryl-add-ui/SKILL.md +18 -0
  275. package/skills/acryl-build-plugin/SKILL.md +21 -0
  276. package/skills/acryl-change-plugin/SKILL.md +16 -0
  277. package/skills/acryl-desktop-shell/SKILL.md +12 -0
  278. package/skills/acryl-diagnose-plugin/SKILL.md +10 -0
  279. package/skills/acryl-fix-plugin/SKILL.md +12 -0
  280. package/skills/acryl-improve-ui/SKILL.md +10 -0
  281. package/skills/acryl-remove-plugin/SKILL.md +11 -0
  282. package/skills/acryl-restyle-ui/SKILL.md +14 -0
  283. package/skills/acryl-share-plugin/SKILL.md +23 -0
  284. package/skills/acryl-tui-ui/SKILL.md +12 -0
@@ -0,0 +1,358 @@
1
+ <!-- Synced from deepseek-harness:docs/subsystems/session-projection.md @ 639ed01539. Do not edit; run scripts/sync-corpus.mjs. Relative links inside may not resolve here. -->
2
+
3
+ # Session Projections
4
+
5
+ English | [中文](session-projection.zh.md)
6
+
7
+ The session-projection seam - a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-session-controller](../../packages/api/session-controller)'s history tail page and `session/projection` push frame). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events - they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
8
+
9
+ Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
10
+
11
+ ## The unit
12
+
13
+ `SessionProjectionStateMap` is the merge-extensible table of host fold states, while `SessionProjectionMap` retains the client-visible whole values. A domain contributes one `ProjectionDefinition` per state key; a `wire` block makes that key client-visible, and rendering belongs to the slot system, never this layer:
14
+
15
+ ```ts type-equiv
16
+ /**
17
+ * One domain's state-driven computation unit: a pure synchronous fold plus
18
+ * declarations and an optional client view - never an opaque getter. The framework drives
19
+ * `apply` on every committed session event; the domain holds no
20
+ * subscriptions and owns only the computation. All functions MUST be
21
+ * synchronous (an async unit would tear the carriers' consistency cut), and
22
+ * `state` MUST be plain JSON (the persisted-cache precondition).
23
+ */
24
+ interface ProjectionDefinition<
25
+ K extends keyof SessionProjectionStateMap,
26
+ S extends SessionProjectionStateMap[K] = SessionProjectionStateMap[K],
27
+ > {
28
+ /** The projection key this unit owns (its `SessionProjectionStateMap` entry). */
29
+ key: K
30
+ /** Validates persisted state before it seeds a fold. */
31
+ stateSchema: ZodType<S>
32
+ /**
33
+ * State for the empty log and its immutable Session metadata.
34
+ * @param header - immutable metadata for the Session being projected.
35
+ * @param inheritedEventCount - exact fork-inherited prefix length.
36
+ * @returns the initial state.
37
+ */
38
+ init(header: SessionHeader, inheritedEventCount: SessionLogOffset): NoInfer<S>
39
+ /**
40
+ * Pure transition: previous state + one committed event → next state. A
41
+ * unit uninterested in an event MUST return the same state reference - an
42
+ * unchanged reference (`Object.is`) produces zero downstream work.
43
+ * @param state - the state covering all prior events.
44
+ * @param event - the next committed session event.
45
+ * @returns the next state (same reference when the event is not the unit's).
46
+ */
47
+ apply(state: NoInfer<S>, event: SessionEvent): NoInfer<S>
48
+ /** Client view. Omit for host-only units. */
49
+ wire?: K extends keyof SessionProjectionMap ? {
50
+ /** Validates the wire payload before it leaves the host. */
51
+ viewSchema: ZodType<SessionProjectionMap[K]>
52
+ /**
53
+ * State → wire payload (the read-side projection). The live drive keeps
54
+ * the two latest raw results and compares them with `Object.is`; an
55
+ * object-valued view must reuse its reference to suppress publication
56
+ * across internal-only state changes.
57
+ * @param state - the current state.
58
+ * @returns the whole current value for this unit's key.
59
+ */
60
+ view(state: NoInfer<S>): SessionProjectionMap[K]
61
+ } : never
62
+ /**
63
+ * Persisted-cache invalidation version: bump whenever the serialized state fields or the
64
+ * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
65
+ * rows from an older unit are discarded instead of being forward-applied
66
+ * into garbage. Non-negative integer.
67
+ */
68
+ stateVersion: number
69
+ }
70
+ ```
71
+
72
+ Every served projection value is a complete read model. A source event may carry a whole value or a domain-owned operation; the unit's deterministic `apply` owns replay, and checkpoint plus forward tail replay reconstructs the same state.
73
+
74
+ ## The snapshot and the change feed
75
+
76
+ ```ts type-equiv
77
+ /**
78
+ * One consistent read cut over every registered client-visible unit for one session.
79
+ * `asOfSeq` is the shared watermark - the seq of the last event every value
80
+ * reflects (`-1` for an empty log).
81
+ */
82
+ interface ProjectionSnapshot {
83
+ /** Seq of the last event the values reflect; -1 for an empty log. */
84
+ asOfSeq: SessionSeqCursor
85
+ /** Whole current client value per registered key. */
86
+ values: Partial<SessionProjectionMap>
87
+ }
88
+ ```
89
+
90
+ ```ts type-equiv
91
+ /**
92
+ * Change-feed listener: one unit's raw `view` result changed by `Object.is`
93
+ * for one session. `value` is the schema-validated output; `seq` is the
94
+ * unit's watermark at emission (the seq of the event that caused the change).
95
+ */
96
+ type ProjectionChangeListener = (
97
+ session: Session,
98
+ key: Extract<keyof SessionProjectionMap, string>,
99
+ value: unknown,
100
+ seq: SessionSeq,
101
+ ) => void
102
+ ```
103
+
104
+ `snapshot(session)` is fully synchronous: a carrier reads it in the same tick as its page slice, so `asOfSeq` covers both reads at one sequence number. It returns only client views, and every value passes its unit's `viewSchema` before return. `stateOf(session, key)` reads one live host state without computing unrelated views; callers must not mutate the borrowed reference. A state-reference change computes one cached raw view, and the change feed fires only when that result changes by `Object.is`; an object-valued view must preserve its reference to suppress publication across internal-only state changes.
105
+
106
+ ## The registry: `ctx.sessionProjections`
107
+
108
+ `SessionProjectionRegistry` ([signatures](#ctxsessionprojections--sessionprojectionregistry)) owns the drive: one `session/event` subscription, eager `apply` over every registered unit, and per-session per-unit watermark cells. Cells build lazily - a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect whose disposer rides the calling fiber: an unloaded domain plugin's key (with its cached cells) disappears from subsequent drives and snapshots, and clients read that as capability absence; a duplicate key with a different `stateVersion` throws, while same-version registrants share one unit and are counted. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
109
+
110
+ <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) - do not edit between markers -->
111
+
112
+ <a id="cordis-surface"></a>
113
+
114
+ ## Cordis API
115
+
116
+ 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).
117
+
118
+ <a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
119
+
120
+ ### `ctx.sessionProjectionCache` - `SessionProjectionCache`
121
+
122
+ The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus three mandatory points - session creation, `turn/end`, and session disposal (the live-to-cold moment) - and serves the cached rows for a session header. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write.
123
+
124
+ ```ts cordis-catalog
125
+ /**
126
+ * The zero-I/O listing read: whole values viewed straight from the stored
127
+ * rows (version-matching keys only) of the record bound to the caller's
128
+ * lifecycle. The header is the only identity witness a listing holds, so
129
+ * this face matches the lifecycle identity (`formatVersion`, `createdAt`,
130
+ * `cwd`, `isSeeded`) and not the inherited cut: within one format
131
+ * generation the cut is fixed at fork time, so it distinguishes no
132
+ * lifecycle the other fields do not, and a viewed value never seeds a fold.
133
+ * The view is as stale as the last durable checkpoint but never wrong and
134
+ * never from an unrelated log. Its `asOfSeq` is the lowest watermark among
135
+ * the served rows: the stored record's own position, which the header
136
+ * cannot relate to the log the caller later opens. The Session list
137
+ * therefore labels the block as cached, and the client lets every value the
138
+ * connected Session produces supersede it whatever this number says.
139
+ * @param meta - the listed session's header (identity witness; no log read).
140
+ * @param keys - optional projection keys required by the caller's audience.
141
+ * @returns the viewed block, or `undefined` when no usable row exists for
142
+ * this lifecycle at the current Session format.
143
+ */
144
+ cachedSnapshot( meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
145
+
146
+ /**
147
+ * Read only a predecessor checkpoint's title as a zero-I/O listing hint.
148
+ *
149
+ * The authoritative Session header supplies the lifecycle identity. A cache
150
+ * checkpoint can lag that log but cannot lead it because writes flush the
151
+ * log first, so a matching predecessor title is a genuine (possibly stale)
152
+ * fact from this Session. The registry still requires the current title
153
+ * projection's row version and schema. No other predecessor projection is
154
+ * exposed: format normalization can change their current meaning, and the
155
+ * {@link cachedSnapshot} / hydration paths continue to reject them.
156
+ * @param meta - authoritative listed Session header.
157
+ * @returns a title-only block at the stored title row's watermark, or
158
+ * `undefined` when the record is current, newer, unrelated, missing, or
159
+ * incompatible with the title unit.
160
+ */
161
+ cachedPredecessorTitle(meta: SessionHeader): ProjectionSnapshot | undefined
162
+
163
+ /**
164
+ * Hydrate projection cells for an already-prepared Session without another
165
+ * persistence read. The cache seeds matching rows; the supplied exact log
166
+ * advances every unit to the observation cut. No checkpoint is written
167
+ * because the logical observation may contain recovery events not yet durable.
168
+ * @param session - exact unpublished Session retained by persistence.
169
+ * @param events - exact logical event prefix represented by the observation.
170
+ * @returns all projection values at the event cut.
171
+ */
172
+ hydratePrepared( session: Session, events: readonly SessionEvent[], ): ProjectionSnapshot
173
+
174
+ /**
175
+ * Durably checkpoint one live session NOW (all mandatory points call
176
+ * this; tests and carriers may too). The registry cut is snapshotted at
177
+ * this boundary (states are live references), then the session's record is
178
+ * replaced on the domain's write chain. NOT fail-soft - callers on the
179
+ * fail-soft paths contain it.
180
+ * @param session - the live session to checkpoint.
181
+ * @returns resolution after durability and event emission.
182
+ */
183
+ async write(session: Session): Promise<void>
184
+
185
+ /**
186
+ * Cold-read one session's projections from its complete log. Each unit is
187
+ * seeded from the identity-checked cached rows - the registry skips `apply`
188
+ * for the already-folded prefix (events at or below the row's `seq`) - and
189
+ * the refreshed checkpoint is written back (fail-soft, fire-and-forget), so
190
+ * the first cold read creates the cache row and later ones seed from it.
191
+ * The caller supplies the complete log in seq order: this service never
192
+ * consults the persistence layer.
193
+ * @param meta - the stored session header (identity witness).
194
+ * @param inheritedEventCount - exact inherited prefix length for projection initialization and identity.
195
+ * @param events - the session's complete log, in seq order.
196
+ * @returns the projection cut at the log end.
197
+ */
198
+ coldSnapshot( meta: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[], ): ProjectionSnapshot
199
+ ```
200
+
201
+ Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md) · [SessionLogOffset](session.md)
202
+
203
+ Source: [`packages/session/session-projection-cache/src/index.ts`](../../packages/session/session-projection-cache/src/index.ts)
204
+
205
+ <a id="ctxsessionprojections--sessionprojectionregistry"></a>
206
+
207
+ ### `ctx.sessionProjections` - `SessionProjectionRegistry`
208
+
209
+ `ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive). A changed state reference computes the next client view; the change feed is notified only when its raw result changes by `Object.is`. Cells build lazily - a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. A host reader either declares `sessionProjections` in its plugin `inject` or fails explicitly when the registry or required key is absent. Contributors may preserve optional registration through `ctx.inject(['sessionProjections'], ...)`. Registrants sharing a key share one unit and are counted: the same tool package mounted in N agent presets registers N times, and the key survives until the last one unloads.
210
+
211
+ ```ts cordis-catalog
212
+ /**
213
+ * Register one domain's unit. The registration is an effect on the calling
214
+ * context's fiber: disposing the fiber (or calling the returned disposer)
215
+ * removes the key - and the unit's cached cells - from subsequent drives
216
+ * and snapshots.
217
+ * @param definition - key, state schema, pure unit functions, and stateVersion.
218
+ * @returns the exact disposer that unregisters this unit.
219
+ */
220
+ register< K extends keyof SessionProjectionMap, S extends SessionProjectionStateMap[K], >( definition: Omit<ProjectionDefinition<K, S>, 'wire'> & { wire: NonNullable<ProjectionDefinition<K, S>['wire']> }, ): () => void
221
+
222
+ /**
223
+ * Register one host-only unit. Its state is omitted from client snapshots
224
+ * and always checkpointed like every other unit.
225
+ * @param definition - key, state schema, pure unit functions, and stateVersion.
226
+ * @returns the exact disposer that unregisters this unit.
227
+ */
228
+ register< K extends Exclude<keyof SessionProjectionStateMap, keyof SessionProjectionMap>, S extends SessionProjectionStateMap[K], >( definition: Omit<ProjectionDefinition<K, S>, 'wire'>, ): () => void
229
+
230
+ /**
231
+ * Subscribe to the change feed. The registration is an effect on the
232
+ * calling context's fiber.
233
+ * @param listener - called once per client-visible unit whose raw view changed by `Object.is`, per committed event.
234
+ * @returns the exact disposer that unsubscribes.
235
+ */
236
+ onChanged(listener: ProjectionChangeListener): () => void
237
+
238
+ /**
239
+ * Read one unit's current host state after materializing every registered
240
+ * unit at the Session cursor. Unrelated wire views are not produced.
241
+ * The returned value is live; callers must not mutate it.
242
+ * @param session - the session whose state is read.
243
+ * @param key - the registered unit key.
244
+ * @returns current state, or `undefined` when the key is not registered.
245
+ */
246
+ stateOf<K extends keyof SessionProjectionStateMap>( session: Session, key: K, ): SessionProjectionStateMap[K] | undefined
247
+
248
+ /**
249
+ * One consistent cut over every registered client-visible unit for one session, read from
250
+ * the watermark cache (missing cells fold lazily over the in-memory log).
251
+ * Fully synchronous - every value and `asOfSeq` reflect the same log
252
+ * position. Each value passes its unit's `viewSchema` before leaving.
253
+ * @param session - the session whose projection values are read.
254
+ * @param keys - optional client-visible outputs; state materialization remains complete.
255
+ * @returns the snapshot; `values` is empty when no selected client-visible unit is registered.
256
+ */
257
+ snapshot( session: Session, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot
258
+
259
+ /**
260
+ * Read only already-materialized client-visible cells without folding history.
261
+ * Values may trail the live Session and are therefore hints, not a complete
262
+ * baseline. Missing cells are omitted.
263
+ * @param session - attached Session whose cached cells are inspected.
264
+ * @param keys - optional wire keys to view.
265
+ * @returns the lowest common cached cut, or `undefined` when no wire cell exists.
266
+ */
267
+ cachedSnapshot( session: Session, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): ProjectionSnapshot | undefined
268
+
269
+ /**
270
+ * State-level checkpoint of every persisted unit for one session, read
271
+ * from the watermark cache (missing cells fold lazily over the in-memory
272
+ * log). This is the write side of the persisted projection cache: the
273
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
274
+ * `(sessionId, key, ver, seq, val)`
275
+ * rows. Every `val` is a DETACHED structured clone - never the live
276
+ * cell reference: the watermark cache is this registry's authoritative
277
+ * mutable state, and a caller reaching the live reference could corrupt
278
+ * every subsequent snapshot and frame through it (plain JSON by the unit
279
+ * contract, so the clone is total).
280
+ * @param session - the session whose unit states are checkpointed.
281
+ * @returns one row per registered key.
282
+ */
283
+ checkpoint(session: Session): ProjectionCheckpoint
284
+
285
+ /**
286
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
287
+ * at: one event BELOW the lowest usable watermark (a row is usable when
288
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
289
+ * pulls the floor to `0` - that key must refold the full log). The
290
+ * one-below anchor is load-bearing: the tail then proves how far the
291
+ * stored log still extends, so {@link restore} can detect a log that
292
+ * shrank below a row's watermark (crash-repair truncation) instead of
293
+ * serving the stale row as current - an empty tail read from the anchor
294
+ * yields an end below every watermark and the restore rejects for a full
295
+ * re-read.
296
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
297
+ * @returns the offset for the stored-log suffix read (`SessionHandle.read`),
298
+ * or `undefined` when no unit is registered (no read needed -
299
+ * {@link restore} would serve empty values regardless).
300
+ */
301
+ restoreFloor(checkpoint: ProjectionCheckpoint): SessionLogOffset | undefined
302
+
303
+ /**
304
+ * View a checkpoint's rows without any log read: for every registered
305
+ * client-visible unit whose row's `ver` matches, serve the schema-validated
306
+ * `view` of the schema-validated stored state; mismatched, malformed, or absent rows leave their key
307
+ * absent (a cold or listing consumer treats it as not-yet-available and a
308
+ * fuller read path refolds it). The zero-I/O rung of the read ladder -
309
+ * values are as stale as their rows, never wrong.
310
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
311
+ * @param keys - optional wire keys to view.
312
+ * @returns whole values per key with a usable row; empty when none.
313
+ */
314
+ viewCheckpoint( checkpoint: ProjectionCheckpoint, keys?: readonly Extract<keyof SessionProjectionMap, string>[], ): Partial<SessionProjectionMap>
315
+
316
+ /**
317
+ * Cold read: fold every persisted unit over a stored log suffix, seeding
318
+ * each from its checkpoint row when usable - the one read recipe (cached
319
+ * state + forward tail replay + `view`) applied without a live `Session`.
320
+ * Call with the stored events at or past `restoreFloor(checkpoint)` (a
321
+ * `SessionHandle.read` slice) and that same floor as
322
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
323
+ * so a shrunk log is detected here. A row is usable iff its
324
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
325
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
326
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
327
+ * and its key refolds from `init` - which is only sound over the full
328
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
329
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
330
+ * a row's watermark).
331
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
332
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
333
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
334
+ * @param header - immutable metadata for the Session being restored.
335
+ * @param inheritedEventCount - exact fork-inherited prefix length supplied to unit initialization.
336
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
337
+ * supplied event's seq, `baseSeq - 1` for an empty tail) plus the
338
+ * refreshed checkpoint rows at that cut, ready for a durable write-back.
339
+ */
340
+ restore( checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, header: SessionHeader, inheritedEventCount: SessionLogOffset, ): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
341
+
342
+ /**
343
+ * Restore an exact cut and install its states on the supplied prepared Session.
344
+ * A later publication reuses these cells; ordinary live reads and event drive
345
+ * advance any constructor-owned suffix exactly once.
346
+ * @param session - exact prepared Session that owns the restored log prefix.
347
+ * @param checkpoint - persisted rows for this Session lifecycle.
348
+ * @param events - exact events at the observation cut.
349
+ * @param baseSeq - first supplied event sequence.
350
+ * @returns all projection values at the supplied cut.
351
+ */
352
+ hydrate( session: Session, checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: SessionLogOffset, ): ProjectionSnapshot
353
+ ```
354
+
355
+ Types: [Session](session.md) · [SessionEvent](session.md) · [SessionHeader](persistence.md) · [SessionLogOffset](session.md)
356
+
357
+ Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
358
+ <!-- END GENERATED cordis-surface -->