better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/slots.zh.md

@@ -0,0 +1,175 @@
+# Web Client Slots
+
+[English](slots.md) | 中文
+
+Slots 是 Web Client 的类型化 React 组合系统。[`dsh-client-ui-slots`](../../packages/client/ui-slots/README.zh.md)定义不依赖 React 的注册表与类型代数；[`dsh-client-ui-renderer`](../../packages/client/ui-renderer/README.zh.md)把可观测源绑定成钩子、渲染整棵树，并在内部拥有 React context。功能插件通过 `ctx.slots.register()` 贡献 UI，绝不导入其他功能插件的组件。
+
+本文记录 slot 的所有权、组件输入、扩展 API 与当前层级。外围的启动、Remote、Client model 与 Conversation 数据通路见 [Web Client 架构](web-client.zh.md)。
+
+## 声明与生命周期
+
+`SlotMap` 是编译期注册表。包通过声明合并写入 key、cardinality（基数）、scope、owner props、keyed props 与可选的 slot 级 inject face。运行时声明则是拥有该渲染位置的组件在 `children` 中给出的对应条目。
+
+声明一个 child 会同时产生三种效果：令该 child key 生效、授权 parent entry 调用 `renderSlot` 或 `renderSlotChain`，以及记录运行时 dispatch 规格。每个声明只能有一个存活 owner。向未声明 slot 注册，或重复声明其他 entry 已拥有的 child，都会在插件激活时失败。
+
+`root` 是唯一内建声明，也是唯一由 Cordis service 自身渲染的 key。`ui-renderer` 调用 `ctx.slots.renderSlot('root', {})`；其余每个后代都通过声明它的 entry 所收到的 `renderSlot` 或 `renderSlotChain` prop 渲染。
+
+注册和声明遵循 Cordis effect 生命周期。销毁一个 entry 会移除其贡献，并递归折叠它声明的 child slots。因此，向其他包的 slot 贡献功能时使用 `ctx.slots.inject(key, callback)`：callback 会在每段声明生命周期内运行，owner 折叠时其 effect 随之移除，owner 再次挂载时则重新运行。
+
+```tsx ignore-check
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'
+import type {} from '@deepseek-ai/dsh-client-ui-session/client'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+
+type HeaderActionProps = PropsRuntime<'conversation.session.header.actions'>
+
+function HeaderAction({ useSession }: HeaderActionProps) {
+  const running = useSession(snapshot => snapshot.running)
+  return <button disabled={running}>Review</button>
+}
+
+export const inject = ['slots']
+
+export function apply(ctx: Context): void {
+  ctx.slots.inject('conversation.session.header.actions', () =>
+    ctx.slots.register({
+      name: 'conversation.session.header.actions',
+      id: 'review',
+      order: 100,
+    }, HeaderAction))
+}
+```
+
+## Cardinality 与 scope
+
+Slot 声明固定两个相互独立的维度。
+
+| 维度 | 值 | 含义 |
+|---|---|---|
+| cardinality | `single` | 单个 cell，渲染当前 priority 胜者；需要并列内容时应声明 child slot，而不是把它当作列表。 |
+| cardinality | `list` | cell 由必填 `id` 定址，先按 `order`、再按注册顺序排列。 |
+| cardinality | `keyed` | owner 传入 `entryKey`；匹配 cell 以该 key 对应的 props 渲染。 |
+| cardinality | `chain` | 每个 entry 提供纯 `select(owner)` 函数；按 priority 顺序遇到的第一个非 null 结果获选，并以 `matched` 传给组件；全部拒绝时渲染 owner fallback。 |
+| scope | `root` | 一个 root 作用域组件和 store 实例。 |
+| scope | `session-maybe` | 跟随当前选择，但没有 Session 时仍可渲染；Session 值是可选的。 |
+| scope | `session` | 要求可解析的 Session binding，并收到确定存在的 Session 值。 |
+
+对于 `single`、`list` 和 `keyed` cell，`priority` 是遮蔽优先级；对于 `chain`，它是选举顺序。数值越小越先运行或渲染。普通增量贡献应选用新的 list `id` 或 keyed `key`；复用已有 cell 表示有意替换其展示。
+
+## 组件输入
+
+注册组件会在 binding 位置收到组装后的输入。组件应从这些类型推导 props，不要重新抄写成员。
+
+| 输入 | 声明者 | 组件类型 |
+|---|---|---|
+| owner 值与标准 scope 值 | `SlotMap` 条目与已安装的 scope adapter | `PropsRuntime<K>` |
+| 获授权的 child renderer | 注册项的 `children` keys | `PropsRenderSlots<S>` |
+| 共享视图状态的 selector hook 与 mutation callback | 注册项的 `store` | `PropsStore<H>` |
+| 私有数据、callback 与 observable hook | 注册项的 `inject` factory | `InjectFace<I>` |
+| 本地化 `t` 函数 | 注册项的 `locale` namespace | `PropsLocale<N>` |
+| chain 选中的值 | 注册项的 `select` 结果 | 通过 `ComposedProps` 提供的 `matched` |
+
+当 entry 声明 strict Session child 时，`PropsRenderSlots` 还会提供 `SessionProvider`。它把子树绑定到当前 Session identity，并在 identity 改变时重新挂载 body。
+
+组件绝不会收到 `ctx`。父组件在某次渲染时已经知道的值通过 `renderSlot` 的 owner 参数进入；共享视图状态使用声明的 store；service 与 model object 留在 `apply` closure 中，只向组件投影 callback 或 observable source。
+
+## 框架提供的 hooks
+
+当前组合中的 adapter 会添加以下标准 props。它们按目标 slot 的 scope 提供，与注册组件来自哪个包无关。
+
+| 可用范围 | Props | Owner |
+|---|---|---|
+| 所有 scope | `useSessions`、`useSessionPendingInteraction` | `ui-session` |
+| 所有 scope | `useWorkspaces` | `ui-workspace` |
+| `session` | `sessionId`、`useSession`、`useProjection` | `ui-session` |
+| `session-maybe` | 结果可选的 `sessionId`、`useSession`、`useProjection` | `ui-session` |
+| `session` | `useConversation`、`useInput`、`inputActions` | `ui-conversation` |
+| `session-maybe` | 结果可选的 `useConversation`、`useInput`、`inputActions` | `ui-conversation` |
+| `session` | `useChat` | `ui-chat` |
+| `session` | `useTrajectory` | `ui-trajectory` |
+
+Renderer 还会根据声明的 store 创建 `useStore`，并根据声明的 locale namespace 创建 `t`。这些是由注册项推导的 props，不属于全局标准 props。
+
+框架与领域 adapter owner 可以通过 `ctx.slots.provideRoot()` 或 `ctx.uiSession.provide()` 扩展标准集合，同时提供对应的 `GlobalStandardProps`、`SessionStandardProps` 或 `SessionMaybeStandardProps` 声明合并。普通功能组件不应自行创建 React hook prop，也不应为 entry 私有数据添加全局标准 prop。
+
+## 开发者提供的 injection
+
+注册项的 `inject` 选项是通常使用的功能私有注入点。它的 factory 在插件的 `apply` 世界中运行，可以闭包捕获已经注入的 Cordis service，并且只返回组件所需的数据与 callback。对于 `session` slot，它会收到 `sessionId`；对于 `session-maybe`，它收到 `sessionId | undefined`；声明 store 后，它还会收到该 store 绑定后的 actions。
+
+返回值中保留的 `hooks` 对象接收裸 `getSnapshot`／`subscribe` source。Renderer 把 `hooks: { status }` 转换为组件 prop `useStatus(selector)`，并按 source identity 缓存绑定。组件不会收到 source 本身，也不直接调用 `useSyncExternalStore`。
+
+当每个 occupant 都需要同一种能力时，slot owner 可以在 child 声明里放置 `inject` face。普通成员会原样交给所有 occupant；其 `hooks` 对象中的函数成员是 hook factory，它会收到 slot 的标准 props 与可选的逐次渲染 `hookContext`，再返回提供给 occupant 的受限 hook。`conversation.chat.node` 正是通过这种机制，为当前渲染的 node 提供 `useTurnData(key)`。
+
+一次渲染时 owner 已知的值走 owner props；单个 entry 的 callback 与私有 observable 走注册项 `inject`；由 slot owner 控制、所有 occupant 共享的能力走 slot 级 `inject`；需要跨 entry 共享或跨重新挂载保留的可变视图状态走声明的 store。React node 通过 child slot 组合，不通过注入值传递。
+
+## 当前层级
+
+下图是当前发布组合的声明树。只有具名 parent entry 已挂载时，其 child 才存在；因此可选功能 entry 可以作为一个生命周期单元让整棵子树出现或消失。
+
+```text
+root
+├─ sidebar
+│  ├─ sidebar.brand.mark
+│  ├─ sidebar.brand.name
+│  ├─ sidebar.footer.action
+│  ├─ sidebar.workspaces
+│  │  └─ sidebar.workspaces.directoryFlow
+│  └─ sidebar.settings
+│     ├─ settings.trigger
+│     ├─ settings.header
+│     ├─ settings.action
+│     ├─ settings.close
+│     ├─ settings.onboarding
+│     └─ settings.section
+│        ├─ settings.general.item
+│        ├─ settings.models.provider-card
+│        ├─ settings.models.footer
+│        └─ settings.plugins.tab
+│           └─ settings.plugin.item
+├─ conversation
+│  ├─ conversation.session
+│  │  └─ conversation.view
+│  │     ├─ conversation.chat.node
+│  │     │  ├─ conversation.chat.assistant-actions
+│  │     │  ├─ conversation.chat.commandview
+│  │     │  ├─ conversation.chat.turnTail
+│  │     │  └─ tool.call.toolview
+│  │     │     ├─ tool.call.images
+│  │     │     └─ tool.view.cordis
+│  │     ├─ conversation.message.images
+│  │     └─ conversation.trajectory.images
+│  ├─ conversation.session.header
+│  │  ├─ conversation.session.header.lineage
+│  │  ├─ conversation.session.header.actions
+│  │  └─ conversation.session.header.utilities
+│  ├─ conversation.composer
+│  │  └─ conversation.approval.detail
+│  ├─ conversation.composer.bar
+│  │  ├─ conversation.input.attachments
+│  │  ├─ conversation.input.plan
+│  │  └─ conversation.input.model
+│  ├─ conversation.input.overlay
+│  ├─ conversation.input.dock
+│  ├─ conversation.composer.dock
+│  ├─ conversation.input.left
+│  ├─ conversation.input.right
+│  ├─ conversation.hero.brand.mark
+│  ├─ conversation.hero.workspace
+│  │  └─ conversation.hero.workspace.directoryFlow
+│  └─ conversation.hero.agentPreset
+├─ details
+│  └─ conversation.details.tool
+└─ shell.overlay
+```
+
+生成的 Client inspect catalog 是每个 key 的完整参考，包含 cardinality、scope、owner props、标准 props、当前 occupant、声明 owner 与替换风险。运行中的动态包可以用 `cordis_inspect what:"client"` 查询实时树与某个精确 key；源码 catalog 由 `pnpm run gen-client-catalog` 根据 `SlotMap` 声明和 `slots.register()` 调用点生成。
+
+## 扩展规则
+
+- 另一个功能包只能通过 `import type` 引入声明；绝不导入或转发它的运行时值。
+- 只在拥有并渲染某个位置的组件中声明新的 child slot。其他包通过 `ctx.slots.inject()` 等待，再通过 `ctx.slots.register()` 贡献内容。
+- 业务与传输状态留在所属 Cordis service 或 Client model 中。Slot store 只承载共享的视图与交互状态。
+- 可观测 source 及其 snapshot identity 在值变化前保持稳定；值变化时通过同一个 source 发布。
+- UI domain 之间只传 JSON 兼容数据和 callback。`hooks` compartment 是裸 observable 的唯一例外；React 内容通过 slot 传递。
+- 将 `single` 和已有 occupant 的 keyed cell 视为替换点。增量扩展使用 list id 或尚未占用的 key。

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/spill.md

@@ -0,0 +1,117 @@
+# Spill Storage
+
+English | [中文](spill.zh.md)
+
+The spill storage seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) that persists a tool's oversized text and returns a model-facing locator plus retrieval guidance, split across packages: Service Definition ([dsh-spill](../../packages/spill/spill), `ctx.spillStore`), Service Provider ([dsh-spill-local](../../packages/spill/spill-local), private session-scoped files on the host filesystem), and Consumer ([dsh-spill-policy](../../packages/spill/spill-policy), the `tools/post-execute` policy). Spill is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Preview mechanics stay in [dsh-output-retention](../../packages/util/output-retention); this seam only saves the final text the policy hands it.
+
+Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
+
+## The save request
+
+`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), the tool and call that produced it (`source`, used for naming and inspection — not access control), and a `suggestedName` the backend may use as a naming hint (it is not a path).
+
+```ts type-equiv
+/** One request to persist text to a spill artifact. */
+interface SaveTextSpill {
+  owner: SpillOwner
+  source: SpillSource
+  /**
+   * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
+   * it to a single safe path segment before use — it is a hint, never a path.
+   */
+  suggestedName: string
+  /** The full text to persist (UTF-8). */
+  content: string
+}
+```
+
+```ts type-equiv
+/**
+ * Save-time storage namespace for a spilled artifact. The session id lets a
+ * backend group storage under the producing session, but the returned
+ * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
+ * locators already present in the seeded log; those artifacts are not copied or
+ * re-owned, and spills produced after the fork use the child session id.
+ */
+interface SpillOwner {
+  sessionId: SessionId
+}
+```
+
+A retention-period cleanup may expire old locators with other old session artifacts; the spill seam does not define a per-session cleanup policy.
+
+```ts type-equiv
+/**
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
+ * filename and inspection. Not interpreted for access control; purely
+ * descriptive.
+ */
+interface SpillSource {
+  /** The tool whose result was spilled (e.g. `web_fetch`). */
+  toolName: string
+  /** The model-issued call id the result belongs to. */
+  callId: ToolCallId
+  /** A short human label for the artifact (e.g. `result`). */
+  label: string
+}
+```
+
+## The result
+
+```ts type-equiv
+/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
+interface SpillRef {
+  locator: SpillLocator
+  bytes: number
+  retrievalHint: string
+}
+```
+
+`SpillLocator` is a [branded](core.md#branded-ids) model-facing handle returned by the backend. The local backend renders it as a filesystem path; a remote or database backend can render a URI, key, or command token. Consumers treat it as opaque and render it with `retrievalHint` instead of assuming `read` is always the right retrieval mechanism.
+
+```ts type-equiv
+/**
+ * Opaque model-facing handle for one spilled artifact. A local backend may use a
+ * filesystem path; a remote or database backend may use a URI or key. Consumers
+ * render it with {@link SpillRef.retrievalHint}, but do not parse it.
+ */
+type SpillLocator = Branded<'SpillLocator'>
+```
+
+## The service
+
+`SpillStore` (`ctx.spillStore`, defined in [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)) is a one-method abstract service: `saveText(input) → Promise<SpillRef>`. It persists the FULL `content` and REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable). The seam owns storage only: no retention policy, no tool-result replacement, no retrieval/search API.
+
+The local backend ([dsh-spill-local](../../packages/spill/spill-local)) writes under `<root>/session-<hash>/<random>-<safeName>` — a configured or lazily-created private (0700) root, a `sha256(sessionId)` session subdir, and an exclusive owner-only (`open(path, 'wx', 0o600)`) write so a planted symlink cannot redirect it. Its `locator` is the local path and its `retrievalHint` tells the model to use `read` or `grep` on that path. The policy consumer ([dsh-spill-policy](../../packages/spill/spill-policy)) replaces an over-`maxInlineBytes` plain-text final result with a retention-library head/tail preview plus the spill reference, best-effort: a save failure keeps the original inline result rather than turning a successful call into an `isError`.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+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).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/subsystems/spill.zh.md

@@ -0,0 +1,117 @@
+# spill 存储
+
+[English](spill.md) | 中文
+
+spill 存储 seam 是一项[能力 seam](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)，它持久保存工具的超大文本，并返回面向模型的定位符与检索指引；该能力拆分到三个包：Service Definition（[dsh-spill](../../packages/spill/spill)，`ctx.spillStore`）、Service Provider（[dsh-spill-local](../../packages/spill/spill-local)，宿主文件系统中会话作用域的私有文件）和 Consumer（[dsh-spill-policy](../../packages/spill/spill-policy)，`tools/post-execute` 策略）。spill 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇记录在此处，而不在 [core.md](core.zh.md) 中。预览机制仍归 [dsh-output-retention](../../packages/util/output-retention) 所有；该 seam 只保存策略交给它的最终文本。
+
+源码：[`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/types.ts)
+
+## 保存请求
+
+`saveText` 是唯一的服务操作：原样持久保存 `content`，并返回不透明的定位符、后端提供的检索提示和准确字节数。请求携带保存时的存储命名空间（`owner`）、生成内容的工具和调用（`source`，用于命名和检查，而非访问控制）以及后端可用作命名提示的 `suggestedName`（它不是路径）。
+
+```ts type-equiv
+/** One request to persist text to a spill artifact. */
+interface SaveTextSpill {
+  owner: SpillOwner
+  source: SpillSource
+  /**
+   * A caller-suggested base name (e.g. `web_fetch.txt`). The backend sanitizes
+   * it to a single safe path segment before use — it is a hint, never a path.
+   */
+  suggestedName: string
+  /** The full text to persist (UTF-8). */
+  content: string
+}
+```
+
+```ts type-equiv
+/**
+ * Save-time storage namespace for a spilled artifact. The session id lets a
+ * backend group storage under the producing session, but the returned
+ * {@link SpillLocator} is the model-facing handle. Forked sessions inherit
+ * locators already present in the seeded log; those artifacts are not copied or
+ * re-owned, and spills produced after the fork use the child session id.
+ */
+interface SpillOwner {
+  sessionId: SessionId
+}
+```
+
+保留期清理可以连同其他旧会话产物一起使旧定位符失效；spill seam 不定义逐会话的清理策略。
+
+```ts type-equiv
+/**
+ * Tool and call that produced one spilled artifact — recorded by the backend for a readable
+ * filename and inspection. Not interpreted for access control; purely
+ * descriptive.
+ */
+interface SpillSource {
+  /** The tool whose result was spilled (e.g. `web_fetch`). */
+  toolName: string
+  /** The model-issued call id the result belongs to. */
+  callId: ToolCallId
+  /** A short human label for the artifact (e.g. `result`). */
+  label: string
+}
+```
+
+## 结果
+
+```ts type-equiv
+/** A saved spill artifact: its locator, byte length, and backend-specific retrieval guidance. */
+interface SpillRef {
+  locator: SpillLocator
+  bytes: number
+  retrievalHint: string
+}
+```
+
+`SpillLocator` 是后端返回的[品牌化](core.zh.md#branded-ids)面向模型句柄。本地后端将它渲染为文件系统路径；远程或数据库后端可以渲染 URI、键或命令 token。消费方将它视为不透明值，并使用 `retrievalHint` 渲染，而不是假定 `read` 始终是正确的检索机制。
+
+```ts type-equiv
+/**
+ * Opaque model-facing handle for one spilled artifact. A local backend may use a
+ * filesystem path; a remote or database backend may use a URI or key. Consumers
+ * render it with {@link SpillRef.retrievalHint}, but do not parse it.
+ */
+type SpillLocator = Branded<'SpillLocator'>
+```
+
+## 服务
+
+`SpillStore`（`ctx.spillStore`，定义于 [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)）是只有一个方法的抽象服务：`saveText(input) → Promise<SpillRef>`。它持久保存完整的 `content`，并在实际存储失败（权限、ENOSPC、后端不可用）时拒绝。该 seam 只负责存储：不负责保留策略、工具结果替换或检索／搜索 API。
+
+本地后端（[dsh-spill-local](../../packages/spill/spill-local)）写入 `<root>/session-<hash>/<random>-<safeName>`：根目录是已配置或延迟创建的私有（0700）目录，会话子目录采用 `sha256(sessionId)`，并通过排他且仅所有者可访问的写入（`open(path, 'wx', 0o600)`）防止预先植入的符号链接重定向写入。其 `locator` 是本地路径，`retrievalHint` 则告知模型在该路径上使用 `read` 或 `grep`。策略消费方（[dsh-spill-policy](../../packages/spill/spill-policy)）会把超过 `maxInlineBytes` 的纯文本最终结果替换为保留库生成的首尾预览和 spill 引用；该过程尽力而为：保存失败时保留原始内联结果，而不会把成功的调用变成 `isError`。
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+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.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxspillstore--spillstore-abstract-seam"></a>
+
+### `ctx.spillStore` — `SpillStore` (abstract seam)
+
+Abstract spill storage service. Subclass, implement saveText, and load the subclass as a plugin — it registers as `ctx.spillStore` (one implementation per context; loading a second throws, cordis' standard duplicate-service behavior).
+
+Semantics every implementation must honor:
+
+- saveText persists the FULL `content` verbatim and returns an opaque locator, exact byte length, and model-facing retrieval guidance.
+- Storage is scoped by the request's SaveTextSpill.owner session; the backend chooses a private (not world-readable) location and a collision-free name derived from — never equal to — the caller's `suggestedName`.
+- `saveText` REJECTS on a real storage failure (permissions, ENOSPC, backend unavailable); the caller decides how to degrade (the spill policy treats a rejection as best-effort and keeps the inline result).
+
+```ts cordis-catalog
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, caller-supplied source fields, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
+abstract saveText(input: SaveTextSpill): Promise<SpillRef>
+```
+
+Source: [`packages/spill/spill/src/index.ts`](../../packages/spill/spill/src/index.ts)
+<!-- END GENERATED cordis-surface -->