docs: replace vague provenance prose with recorded facts

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: c3434f90a8f7ab30baa6b237beab6dd9763f9bff
-README.zh.md: fc80f8a5fee713a6cba1a5c8173c489bfc2c14d8
+README.md: d3cce987f80c0db5165718b7cc4fd6ada92f2a02
+README.zh.md: 37d6587d08d96c55a36c9b7388f2ae418531a6cd

packages/spill/spill/README.md

@@ -24,7 +24,7 @@ Storage is grouped by the request's `owner` session as a save-time namespace; th
 
 ## Vocabulary
 
-`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` (toolName, callId, label) is descriptive provenance for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
+`SaveTextSpill` (owner, source, suggestedName, content) is the request; `SpillRef` (locator, bytes, retrievalHint) is the result. `SpillLocator` is [branded](../../util/brand) and rendered to the model as an opaque string — a local path for `dsh-spill-local`, but a future backend may return a URI, key, or command token without changing policy/tool consumers. `SpillOwner.sessionId` is the save-time storage namespace: forked sessions inherit existing locators from the seeded log without copying or re-owning them, and new spills after the fork use the child session id. `SpillSource` records the producing `toolName`, `callId`, and `label` for backend naming and inspection, not access control. See `src/types.ts` for the full contracts.
 
 See the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design rationale, including why creation belongs to the runtime spill seam rather than the model-facing `write` tool.
 

packages/spill/spill/README.zh.md

@@ -24,7 +24,7 @@
 
 ## 词汇
 
-`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整约定见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` 记录产生该 spill 的 `toolName`、`callId` 和 `label`，供后端命名和检查使用，不用于访问控制。完整约定见 `src/types.ts`。
 
 设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
 

packages/spill/spill/src/index.ts

@@ -49,7 +49,7 @@ export abstract class SpillStore extends Service {
 
   /**
    * Persist `input.content` to a session-scoped spill artifact.
-   * @param input - the owner, provenance, suggested name, and full text to save.
+   * @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>

packages/spill/spill/src/types.ts

@@ -39,7 +39,7 @@ export interface SpillOwner {
 }
 
 /**
- * Provenance of one spilled artifact — recorded by the backend for a readable
+ * 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.
  */