docs: reserve seam for complete capabilities

packages/spill/spill-policy/src/index.ts

@@ -69,7 +69,7 @@ export interface Config {
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'spill-policy'
 
-/** Require the tool registry (its `tools/post-execute` waterfall is the seam we transform). */
+/** Require the tool registry (its `tools/post-execute` waterfall is the extension point we transform). */
 export const inject = ['tools']
 
 export const Config: z<Config> = z.object({

packages/spill/spill/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/spill/spill/README.md
-README.md: ecaef9fc53ec3d9017143cfc012abc9cabe77072
-README.zh.md: 5393ccb312245f3bbfcf28ea8e097b0a343966e9
+README.md: a9e3ec7169e0239117f7f9222ad2ba53619e0369
+README.zh.md: 9bfacda928e30a1338bedaef9d39e43cff4c667d

packages/spill/spill/README.md

@@ -8,11 +8,11 @@ This package is one third of the spill capability, split so each concern evolves
 
 | Package | Role |
 |---|---|
-| `@deepseek-ai/dsh-spill` (this) | the interface: abstract service + vocabulary types |
-| `@deepseek-ai/dsh-spill-local` | an implementation: private session-scoped files on the host filesystem |
-| `@deepseek-ai/dsh-spill-policy` | the tool-result policy that spills oversized final results |
+| `@deepseek-ai/dsh-spill` (this) | Service Definition: abstract service + vocabulary types |
+| `@deepseek-ai/dsh-spill-local` | Service provider: private session-scoped files on the host filesystem |
+| `@deepseek-ai/dsh-spill-policy` | Consumer: the tool-result policy that spills oversized final results |
 
-The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this interface without touching the policy plugin.
+The split mirrors the bash/fs seams. A future remote or virtual backend (e.g. a `spill://…` URI, a database key, or a backend-specific retrieval tool) implements this Service Definition without touching the policy plugin.
 
 ## Service API (`ctx.spillStore`)
 

packages/spill/spill/README.zh.md

@@ -8,11 +8,11 @@
 
 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-spill`（本包） | 接口：抽象服务与词汇类型 |
-| `@deepseek-ai/dsh-spill-local` | 实现：位于宿主文件系统中的私有会话级文件 |
-| `@deepseek-ai/dsh-spill-policy` | 对过大最终结果执行 spill 的工具结果策略 |
+| `@deepseek-ai/dsh-spill`（本包） | Service Definition：抽象服务与词汇类型 |
+| `@deepseek-ai/dsh-spill-local` | Service provider：位于宿主文件系统中的私有会话级文件 |
+| `@deepseek-ai/dsh-spill-policy` | Consumer：对过大最终结果执行 spill 的工具结果策略 |
 
-这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此接口，无需修改策略插件。
+这种拆分方式与 bash/fs seam 相同。未来的远程或虚拟后端（例如 `spill://…` URI、数据库键或后端专用取回工具）可实现此 Service Definition，无需修改策略插件。
 
 ## 服务 API（`ctx.spillStore`）
 

packages/spill/spill/src/index.ts

@@ -1,11 +1,11 @@
 /**
- * The spill storage seam (`ctx.spillStore`): an abstract service defining WHAT a
+ * Service Definition for the spill storage capability seam (`ctx.spillStore`): an abstract service defining WHAT a
  * spill backend does — persist a tool's oversized text and return a model-facing
  * locator plus retrieval guidance — without saying HOW. Implementations
  * subclass {@link SpillStore} and register as the `spillStore` service;
  * `@deepseek-ai/dsh-spill-local` (host filesystem) is the first.
  *
- * The seam is deliberately minimal: `saveText` and nothing else. It owns NO
+ * The Service Definition is deliberately minimal: `saveText` and nothing else. It owns NO
  * retention policy (that is `@deepseek-ai/dsh-retention`), NO tool-result
  * replacement (that is `@deepseek-ai/dsh-spill-policy`), and NO retrieval or
  * search API. The backend supplies the locator and retrieval hint appropriate

packages/spill/spill/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * Vocabulary for the spill storage seam. Types only — the abstract service
+ * Vocabulary for the spill storage Service Definition. Types only — the abstract service
  * lives in `./index.ts`, implementations in sibling packages
  * (`@deepseek-ai/dsh-spill-local` first).
  *

packages/spill/spill/tests/service.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for the spill seam INTERFACE: a minimal concrete subclass registers as
+ * Tests for the spill Service Definition: a minimal concrete subclass registers as
  * `ctx.spillStore`, a second load throws (duplicate service), and disposal
  * releases the service. The storage behavior is the implementation's concern
  * (`@deepseek-ai/dsh-spill-local`); here we only pin the seam contract.