docs: reserve seam for complete capabilities

packages/session/session-persistence/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/session/session-persistence/README.md
-README.md: 29ee219a55d0823f03bb512c0fa37b7e249817eb
-README.zh.md: c750d2f85fd267a94c36770452f1e5c7e647a2fb
+README.md: c64826db1e9c7339f43a64ad7c13f01a2a39638e
+README.zh.md: 651d920404300fa602f77cee63b0f31aec837919

packages/session/session-persistence/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
+The durable session-persistence Service Definition (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, and list sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)): an abstract service here, a Service provider in a sibling package, and Consumers that inject the service.
 
 The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage, seed boundary, origin, delegation depth) travels separately as `SessionHeader`, owned by `dsh-session` and re-exported here.
 
@@ -41,7 +41,7 @@ When a live session emits `session/disposed`, the coordinator waits for its cont
 
 The side-effect-free `locate`, lightweight `listSnapshots`, and per-id `readStoredRevision` queries remain backend-owned because they describe storage topology and revision identity rather than write orchestration. `listSnapshots(signal?)` passes the caller's exact signal into backend discovery so observers can cancel that work without detaching it.
 
-The `PersistenceBackend<TornMarker>` hooks (the only seam between the coordinator and storage):
+The `PersistenceBackend<TornMarker>` hooks (the only contract between the coordinator and storage):
 
 | Hook | Role |
 |---|---|

packages/session/session-persistence/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-这是用于持久保存会话的抽象 seam（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供具体实现，消费方注入接口。
+这是用于持久保存会话的 Service Definition（`ctx.sessionPersistence`）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)）：本包提供抽象服务，同级包提供 Service provider，Consumer 注入服务。
 
 持久化单元就是现有 `SessionEvent`（事件溯源模型：日志是唯一真源），因此不存在另一套并行的「持久消息」类型。不属于可回放对话状态的元数据（格式版本、cwd、血缘、种子边界、origin、委托深度）作为 `SessionHeader` 单独传输，该类型归 `dsh-session` 所有，并在此重新导出。
 
@@ -41,7 +41,7 @@
 
 无副作用 `locate`、轻量 `listSnapshots` 和按 id 查询的 `readStoredRevision` 仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个信号传给后端发现流程，使观察者可在不脱离该工作的情况下取消。
 
-`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam）：
+`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一约定）：
 
 | 钩子 | 职责 |
 |---|---|

packages/session/session-persistence/src/coordinator.ts

@@ -78,7 +78,7 @@ export interface StoredSuffix {
 }
 
 /**
- * The storage seam between {@link PersistenceCoordinator} and a concrete
+ * The storage contract between {@link PersistenceCoordinator} and a concrete
  * backend: the minimal set of durable primitives the orchestration calls. A
  * backend implements these (over files, rows, an object store, …); the
  * coordinator supplies everything else (buffering, serialization, cursors,

packages/session/session-persistence/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * Durable session-persistence seam (`ctx.sessionPersistence`). Backends store
+ * Durable session-persistence Service Definition (`ctx.sessionPersistence`). Backends store
  * {@link SessionEvent}s as the event-sourced log and carry non-replayable
  * {@link SessionHeader} metadata separately.
  * @module @deepseek-ai/dsh-session-persistence
@@ -10,7 +10,7 @@ import { SessionPreparation } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session'
 import type { SessionPersistenceRevision } from './revision.ts'
 
-// Re-export the metadata vocabulary so consumers import it from the seam.
+// Re-export the metadata vocabulary so Consumers import it from the Service Definition.
 export type { SessionHeader } from '@deepseek-ai/dsh-session'
 export { SessionPersistenceRevision } from './revision.ts'
 

packages/session/session-persistence/tests/persistence.spec.ts

@@ -1279,7 +1279,7 @@ describe('PersistenceCoordinator observation cancellation', () => {
       }
       const suffix = await coordinator.readFrom(id, 3)
       expect(suffix.events).toEqual(log.slice(3))
-      // The hook's undefined is the seam's not-found.
+      // The hook's `undefined` is the backend contract's not-found result.
       await expect(coordinator.readFrom(SessionId('missing-seek'), 0)).rejects.toThrow('not found')
 
       // A hook failure with no cancellation in play propagates as-is.