docs: document SessionRawArtifact and fix backpressure claims

The persistence subsystem page gains the SessionRawArtifact section (with a
type-equiv manifest entry and zh counterpart), and the README and Agent Note
describe the drain-based backpressure instead of claiming the archive never
accumulates.

docs/subsystems/persistence.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 docs/subsystems/persistence.md
-persistence.md: 25541139de02d2bd3ea743fe530e47a628002695
-persistence.zh.md: d76ff93f5564e7612fd7107cd74e3138c03542d8
+persistence.md: 363d28034b58d007d1440afcb8fb9137b0048091
+persistence.zh.md: e208720eae1902ad429fa358c112fe9188f8d8dd

docs/subsystems/persistence.md

@@ -118,6 +118,22 @@ interface CreateSessionOptions {
 
 Replay/fork is therefore `ctx.sessions.create(id, { seed: seedEvents })`; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
 
+## `SessionRawArtifact` — verbatim stored artifact text
+
+A backend's own artifact text for one session, byte-identical to what it durably wrote (decoded from its physical encoding). `readRaw` returns it without reconstructing from parsed events, so backend-specific serialization (chunk packing, key order, line breaks) survives; backends without a per-session artifact, such as SQLite, inherit the `undefined` default.
+
+```ts type-equiv
+/** A backend's own raw artifact text for one session, verbatim. */
+interface SessionRawArtifact {
+  /** The session header parsed from the artifact's own first line. */
+  readonly meta: SessionHeader
+  /** The artifact's base filename on disk, without any physical encoding suffix. */
+  readonly filename: string
+  /** The artifact's full text content, decoded from the backend's physical encoding. */
+  readonly content: string
+}
+```
+
 ## Preparation and restoration ownership
 
 `SessionStore.prepare()` accepts ordinary creation options or fresh persistence graphs transferred through `RestoredSessionOptions`. The restoration branch validates and freezes the transferred header and events in place, so callers must retain no mutable aliases. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. Persistence inspection exposes only `SessionInspection`, an immutable logical view borrowed from the same prepared Session.
@@ -250,7 +266,7 @@ abstract locate(meta: SessionHeader): SessionLocation | undefined
  * @returns the raw artifact plus its parsed header, or `undefined` when the
  * session is absent or the backend owns no per-session artifact.
  */
-readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
+async readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
 
 /**
  * Register a new session's metadata. A backend MAY defer the physical write

docs/subsystems/persistence.zh.md

@@ -118,6 +118,22 @@ interface CreateSessionOptions {
 
 因此，回放/fork 的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
 
+## `SessionRawArtifact`——逐字存储工件文本
+
+后端为单个会话自持的工件文本，与其持久化写入的字节逐字一致（按物理编码解码）。`readRaw` 返回它而不从解析后事件重建，因此后端特定的序列化（chunk 打包、键序、换行）得以保留；没有每会话工件的后端（如 SQLite）继承 `undefined` 默认。
+
+```ts type-equiv
+/** A backend's own raw artifact text for one session, verbatim. */
+interface SessionRawArtifact {
+  /** The session header parsed from the artifact's own first line. */
+  readonly meta: SessionHeader
+  /** The artifact's base filename on disk, without any physical encoding suffix. */
+  readonly filename: string
+  /** The artifact's full text content, decoded from the backend's physical encoding. */
+  readonly content: string
+}
+```
+
 ## 准备与恢复所有权
 
 `SessionStore.prepare()` 接收普通创建选项，或通过 `RestoredSessionOptions` 转移所有权的新鲜持久化对象图。恢复分支会直接验证并冻结转移来的 header 与事件，因此调用方不得保留可变别名。`SessionPreparation` 随后持有该精确的未发布 Session，直至发布或回滚；dispose 是同步且幂等的。持久化检查只暴露 `SessionInspection`，即从同一个已准备 Session 借用的不可变逻辑视图。
@@ -250,7 +266,7 @@ abstract locate(meta: SessionHeader): SessionLocation | undefined
  * @returns the raw artifact plus its parsed header, or `undefined` when the
  * session is absent or the backend owns no per-session artifact.
  */
-readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
+async readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
 
 /**
  * Register a new session's metadata. A backend MAY defer the physical write