@qilin-agent/session-persistence 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,79 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/session/session-persistence/README.md
+/:
+  en: 99acbd5c1e2a16ce
+  zh: 31342508a4e1bf09
+/qilin-session-persistence:
+  en: 1d719c9c7d11ca70
+  zh: b0a828b200cf9bcd
+/qilin-session-persistence/summary:
+  en: 34c7ee5a75c547e2
+  zh: 3e2e6dfd7819e6cc
+/qilin-session-persistence/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-session-persistence/use-this-package:
+  en: bd48e96d14122170
+  zh: f8a06e7246b55a6f
+/qilin-session-persistence/use-this-package/choosing-a-backend:
+  en: 5ad706685920c2f8
+  zh: ee5f922ae0a95852
+/qilin-session-persistence/use-this-package/what-the-service-provides:
+  en: c10b9c7d9bad305c
+  zh: 0e9c391e9df37da6
+/qilin-session-persistence/use-this-package/ownership-and-visibility:
+  en: 16d4abbb05a67360
+  zh: fc91863169570795
+/qilin-session-persistence/use-this-package/the-live-write-path-and-shutdown-drain:
+  en: 282c5bc8a391159f
+  zh: 96682e345ef301f6
+/qilin-session-persistence/use-this-package/resuming-and-crash-recovery:
+  en: 08b09dce0bcf47c8
+  zh: b6c5926d6e440a7b
+/qilin-session-persistence/use-this-package/failures-and-recovery:
+  en: 6d8beec038b1121a
+  zh: 1f02952eb2a0b386
+/qilin-session-persistence/understand-the-implementation:
+  en: fc8325413af9c66e
+  zh: accf0758248ae9be
+/qilin-session-persistence/understand-the-implementation/design-concept:
+  en: 3d21cded1f7e74ff
+  zh: 5f624aefebb1f63d
+/qilin-session-persistence/understand-the-implementation/the-invariants-every-backend-honors:
+  en: a3b5e0e6747f5ab4
+  zh: fcbcc16c04e15edb
+/qilin-session-persistence/understand-the-implementation/source-map:
+  en: 206eaa18456c97ff
+  zh: 40afc55b378ec11b
+/qilin-session-persistence/understand-the-implementation/the-write-path-at-a-glance:
+  en: c920cf9262f4a563
+  zh: 0f8e3ff17e39c861
+/qilin-session-persistence/understand-the-implementation/stored-record-validation:
+  en: 15c4ae1366d07659
+  zh: d9d3fdea8484df9a
+/qilin-session-persistence/further-exploration:
+  en: a0864feb3bb4b814
+  zh: b1196e3f0100500f
+/qilin-session-persistence/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-session-persistence/model-experience/resumed-conversation-history:
+  en: 062875aab7f3f138
+  zh: c7285918227e6f5c
+/qilin-session-persistence/model-experience/resumed-conversation-history/what-the-model-sees:
+  en: f697ddcf1a13c439
+  zh: a3b5050484be4b9b
+/qilin-session-persistence/model-experience/resumed-conversation-history/token-effect:
+  en: 375253768652244e
+  zh: c5bf6c3dcf707ab2
+/qilin-session-persistence/model-experience/resumed-conversation-history/kv-cache-effect:
+  en: 70a8139de5fd1cec
+  zh: 66dfba4b93e63c55
+/qilin-session-persistence/known-limitations-and-deferred-work:
+  en: 97296c31399996e4
+  zh: 86a5c1e771415e99
+/qilin-session-persistence/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+---
+description: "The durable session-storage seam for users and maintainers choosing a persistence backend, resuming sessions, or building a backend against the shared service contract."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/session-persistence
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package lets applications persist and resume session event logs through a backend-independent API. Readers can create, open, inspect, list, append to, read, flush, and close stored sessions while preserving contiguous append-only history. A completed flush is the durability barrier; readers never receive torn tails or invalid records, and only one writer per session is allowed within a backend instance. Use the shipped [JSONL backend](../session-persistence-jsonl/README.md) for one compressed log per session, or implement another backend with the same observable guarantees.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount one persistence backend to make sessions durable. The backend registers itself as `ctx.sessionPersistence` and routes every published session's live events into that session's active write handle; agent-loop — the production publication point for sessions — acquires each session's write handle before publication, so nothing else in the composition changes.
+
+### Choosing a backend
+
+The seam ships the [JSONL](../session-persistence-jsonl/README.md) backend: one append-only `.jsonl.zstd` log per session. A third-party backend may implement the service directly; the [backend contract](#understand-the-implementation) below is what it must honor.
+
+### What the service provides
+
+With a backend mounted, five service methods address stored sessions:
+
+```text
+const handle = await ctx.sessionPersistence.create(header)     // store a new session, take write ownership
+const handle = await ctx.sessionPersistence.open(id, 'write')  // claim single-writer ownership of an existing session
+const reader = await ctx.sessionPersistence.open(id, 'read')   // observe without ownership
+const snap = await ctx.sessionPersistence.stat(id)             // header + revision (+ eventCount / sizeBytes) without a log read
+const all = await ctx.sessionPersistence.list()                // one snapshot per visible stored session
+await ctx.sessionPersistence.flush()                           // backend-wide durability barrier over every active write handle
+```
+
+Service-level `flush()` drains every active write handle's routed events and materializes its session, exactly as each handle's own `flush` would; failures aggregate per session as an `AggregateError` without abandoning the sweep, and a handle closed mid-sweep counts as flushed because close itself drains durably.
+
+Every log read and write flows through the returned `SessionHandle`; there are no id-addressed append or load methods. `handle.read(offset?, length?)` returns `{ eventState, events }`: the outer slice belongs to the caller, while `eventState` distinguishes an exclusively `detached` event graph from a `shared-frozen` graph that may also reside in a backend cache. The producer establishes this state and slices preserve it even when empty. Both states are safe to adopt without copying; a consumer that needs mutable events clones them first. Reads never include a torn tail, repeated reads on one handle never observe an older state than a prior read, and a write handle reads its own successful appends. `handle.append(events)` appends a contiguous batch whose first `seq` equals the stored next-seq; persistence is best-effort on resolution — the batch is accepted, ordered, and visible to reads on this backend instance, and only a resolved `flush` promises it survives a crash (the shipped JSONL backend happens to persist each batch immediately). `handle.flush()` is the durability barrier and also materializes an empty created session so it becomes durably listable. `handle.close()` is idempotent and uncancellable: a read handle frees local resources; a write handle completes pending durability and releases write ownership. Once an `append` or `flush` resolves, reads started afterwards on the same backend instance — on any handle, or through `stat`/`list` — observe at least that prefix.
+
+### Ownership and visibility
+
+`create` and `open(id, 'write')` take in-process single-writer ownership: a second write open while an owner is active rejects with `SessionAlreadyOwnedError`, `create` on an occupied id rejects with `SessionAlreadyExistsError`, and a mutation on a `read` handle rejects with `SessionReadOnlyError` — one handle type, runtime refusal. Any operation on a closed handle rejects with `SessionHandleClosedError`, and `SessionOwnershipLostError` marks a write handle whose ownership is permanently gone (close it and reopen). A created session is observable in this process from the moment `create` resolves, while the backend may defer physical materialization until the first `append` or `flush`; other processes see only materialized sessions, and a session that never materialized before a crash never existed.
+
+### The live write path and shutdown drain
+
+The backend owns the live write path: it installs the session listeners once and routes every published session's events by id to that session's active write handle — `session/event` copies into a bounded internal batching window, `session/flush` is the immediate durability and error-observation barrier, and `session/disposed` runs the final drain and closes the handle. A published session without an active write handle persists nothing. A background write failure retains its events in order, pauses the automatic path, and is logged; the next explicit flush retries and rejects loudly. `close()` itself drains the routed buffer through the still-open storage before releasing ownership, so backend teardown's close sweep keeps application shutdown lossless even though root-fiber disposal runs fibers' disposers concurrently.
+
+### Resuming and crash recovery
+
+Persistence returns the physically valid log; semantic repair belongs to the reader. A session that crashed mid-turn keeps its open final turn — a single turn can be large, and those events were durably appended before the crash; only the incomplete fragment of a never-acknowledged torn tail is discarded — complete records recovered from it are durably rewritten by the write path before the handle's first new append. Resume (agent-loop) reads the stored log through its write handle, computes `interruptedTurnClosers` — synthetic `tool/result` errors, any open `step/end`, and `turn/end {interrupted}` — and appends them through the same handle as an ordinary batch. Read-only observers (session-query) balance an interrupted cold log with the same closers in memory only.
+
+### Failures and recovery
+
+A stored log the current build cannot faithfully interpret is refused with a direction-aware error, never misread. `SessionHandle` exposes only current logical records identified by `SESSION_FORMAT_VERSION`; a provider must convert any supported historical storage before returning a handle, and the shipped JSONL provider migrates supported historical generations through its static catalog. A newer format instructs the operator to upgrade the harness. An event type unknown to this build refuses unless its envelope marks it `ignorable`, and committed-prefix corruption rejects as `SessionPersistenceCorruptionError`.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the seam realizes durable storage and how backends plug in; the observable contract is covered in [Use this package](#use-this-package) and the generated [Kylin API](../../../docs/subsystems/persistence.md#kylin-surface).
+
+### Design concept
+
+The package is a seam, not a backend framework: it exports the abstract `SessionPersistence` service, the `SessionHandle` contract, the stable error classes consumers catch, the pure stored-record validation helpers (`storage-contract`), and the branded revision — nothing else. Each provider owns its complete storage runtime (handle class, mutation ordering, single-writer bookkeeping, live-event routing, teardown), and two shared test suites — `runPersistenceContract` and `runLiveWritePathContract` under `tests/` — pin the observable behavior every provider must agree on. Deliberate consequence: providers may resemble each other where their storage happens to be similar, but no implementation machinery crosses the package boundary.
+
+### The invariants every backend honors
+
+- **Append-only, contiguous `seq`.** Committed events are never rewritten; `append`'s first `seq` must equal the stored next-seq, and a gap rejects.
+- **A torn physical tail never reaches a reader.** It belongs to an append that never resolved; the write path truncates it durably before its first new append.
+- **Lossless JSON data.** Batches and headers pass the shared one-pass validate-and-snapshot boundary (`materializeAppendBatch`/`materializeCreateHeader`); non-serializable payloads reject at the call site.
+- **Durability.** `append` persists best-effort; `flush` — per handle or service-wide — is the barrier that promises storage and also materializes an empty session.
+- **Fail-closed reads.** `validateStoredEvents` refuses unknown event vocabulary and retired pre-release shapes; `assertVersion` refuses foreign format versions.
+- **Single writer per backend instance.** The provider's in-process claim is taken at `create`/`open('write')` and released at handle close.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: the abstract `SessionPersistence` service and re-exported seam vocabulary |
+| [`src/handle.ts`](src/handle.ts) | The `SessionHandle` contract: read/append/flush/close semantics and freshness rules |
+| [`src/storage-contract.ts`](src/storage-contract.ts) | Shared validation: version gate, fail-closed vocabulary, batch materialization, contiguity |
+| [`src/errors.ts`](src/errors.ts) | Stable handle/ownership failures and format refusals |
+| [`src/revision.ts`](src/revision.ts) | The branded opaque revision token |
+
+### The write path at a glance
+
+Each `session/event` for the writer's session copies into that handle's internal buffer. The first pending event starts a fixed batching window; later events join without resetting its deadline. Expiry drains the pending prefix through the handle's mutation chain; events admitted during a drain coalesce into the next chained batch, in order. `session/flush` cancels the wait and drains through quiescence, then runs `handle.flush()`, so the loop uses it as the ordering and error-observation checkpoint before the next turn. A rejected background drain retains its events and pauses the automatic timer; explicit flush, writer close, or backend teardown retries immediately and rejects loudly. Constructor seed events never emit `session/event`, so a seed appended through the handle before publication is never re-enqueued.
+
+### Stored-record validation
+
+The seam's shared helpers validate current logical records identified by `SESSION_FORMAT_VERSION`, and appends write only the current format ([rationale](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md)). Historical decoding and immutable successor publication belong inside each provider before it returns a handle. Every backend runs `storage-contract` validation on handle reads and write-open priming, refusing an unknown event type as `SessionFormatUnsupportedError` and a malformed current record as `SessionPersistenceCorruptionError`, with the raw-log `SessionLocation` attached when the backend keeps one artifact per session.
+
+</details>
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared durability model to the shipped backends and the decision evidence.
+
+- [Session persistence subsystem](../../../docs/subsystems/persistence.md) — the full service contract, handle semantics, flush checkpoint, crash recovery, and generated Kylin API.
+- [Handle-based persistence Agent Note](../../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) — the seam design and its ownership model.
+- [JSONL persistence backend](../session-persistence-jsonl/README.md) — the shipped per-session-file backend.
+- [Session checkpoint policy](../session-checkpoint-policy/README.md) — the plugin that flushes through `session/flush` at semantic boundaries.
+- [Session package map](../README.md) — adjacent persistence, projection, title, and telemetry packages.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Resumed conversation history
+
+#### What the model sees
+
+The seam adds no prompt or schema. Resume restores stored surface events as message history; stored request headers reconstruct earlier calls, while the new loop composes the current system prompt, tools, and session prefix for its next request. Crash repair marks an assistant request without a durable call as `TOOL_NOT_STARTED`; a durable call without a result becomes `TOOL_OUTCOME_UNKNOWN`, whose text lets the model retry read-only or idempotent work but directs it to verify side effects or ask the user instead of retrying blindly.
+
+#### Token effect
+
+Zero tokens during ordinary persistence. Resume restores retained history cost and pays the current request envelope normally; each repaired call adds the quoted retained error text.
+
+#### KV Cache effect
+
+Persistence does not mutate live request prefixes. A resumed loop can reuse provider cache only when its reconstructed history, current envelope, and model route match; crash-repair results append without rewriting earlier history.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the seam's guarantees stop. They are current package constraints, not a task backlog.
+
+- **The seam guarantees write ownership only within one backend instance** — cross-process exclusion is provider-specific. The shipped JSONL provider adds a kernel-backed lease across instances and processes; another provider must document an equivalent guarantee or require deployments to prevent concurrent writers.
+- **A backend plugin reload under live sessions fails their writers loudly** — a reloaded backend cannot serve handles the old instance issued; writes fail until the sessions restart, and nothing silently re-adopts the logs.
+- **Only handle-acquired sessions persist** — `ctx.sessions.create` + `session/flush` alone stores nothing; agent-loop is the production acquisition point, and tests seed storage through `create`/`append`/`close`.
+- **No deletion or retention API** — pruning stored sessions is out-of-band backend maintenance.
+- **`list()` is unpaginated and unfiltered** — it returns every stored session's snapshot; fine for local stores, unindexed at scale.
+- **Synthetic closers are the only crash story** — resume appends `interruptedTurnClosers` through the write handle; there is no partial-turn resume that continues an interrupted turn instead of closing it.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,163 @@
+---
+description: "面向用户与维护者的持久会话存储 seam 说明，用于选择持久化后端、恢复会话，或按共享服务约定构建后端。"
+kind: "package-reference"
+---
+
+# @qilin-agent/session-persistence
+
+[English](README.md) | 中文
+
+## 概述
+
+本包让应用通过后端无关的 API 持久存储并恢复会话事件日志。读者可以创建、打开、检查、列出、追加、读取、刷新和关闭已存储会话，同时保持连续且仅追加的历史记录。只有完成 flush 才构成持久性屏障；读取方不会收到撕裂尾部或无效记录，并且每个后端实例内每个会话只允许一个写入方。若希望每个会话使用一份压缩日志，可选用随产品交付的 [JSONL 后端](../session-persistence-jsonl/README.zh.md)；也可以实现具备相同可观察保证的其他后端。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+挂载一个持久化后端即可让会话持久化。后端把自己注册为 `ctx.sessionPersistence`，并把每个已发布会话的实时事件路由进该会话的活跃写句柄；agent-loop——会话在生产环境中的发布点——在发布之前获取每个会话的写句柄，因此组合中的其他部分不变。
+
+### 选择后端
+
+seam 随产品交付 [JSONL](../session-persistence-jsonl/README.zh.md) 后端。它为每个会话存储一份仅追加的 `.jsonl.zstd` 日志。第三方后端可以直接实现该服务；必须遵守的[后端约定](#understand-the-implementation)见下文。
+
+### 服务提供什么
+
+挂载后端后，五个服务方法寻址已存储会话：
+
+```text
+const handle = await ctx.sessionPersistence.create(header)     // store a new session, take write ownership
+const handle = await ctx.sessionPersistence.open(id, 'write')  // claim single-writer ownership of an existing session
+const reader = await ctx.sessionPersistence.open(id, 'read')   // observe without ownership
+const snap = await ctx.sessionPersistence.stat(id)             // header + revision (+ eventCount / sizeBytes) without a log read
+const all = await ctx.sessionPersistence.list()                // one snapshot per visible stored session
+await ctx.sessionPersistence.flush()                           // backend-wide durability barrier over every active write handle
+```
+
+服务级 `flush()` 排空每个活跃写句柄已路由的事件并把其会话实体化，效果与各句柄自己的 `flush` 完全相同；失败按会话聚合为一个 `AggregateError` 而不中途放弃清扫，清扫途中被关闭的句柄视同已 flush，因为 close 本身会持久排空。
+
+每一次日志读写都流经返回的 `SessionHandle`；不存在按 id 寻址的 append 或 load 方法。`handle.read(offset?, length?)` 返回 `{ eventState, events }`：外层 slice 属于调用方，`eventState` 则区分由调用方独占的 `detached` 事件图与可能同时位于后端缓存中的 `shared-frozen` 事件图。该状态由生成方确定，即使切片为空也会保留。两种状态都能直接接管而无需复制；需要可变事件的消费方必须先克隆事件。读取绝不包含撕裂尾部，同一句柄上的重复读取绝不会观察到比先前读取更旧的状态，写句柄也能读到自己成功的 append。`handle.append(events)` 追加一个连续批次，其第一个 `seq` 等于已存储 next-seq；完成时的持久化是尽力而为的——批次被接受、有序，并对同一后端实例上的读取可见，只有完成的 `flush` 才承诺它在崩溃后依然存在（交付的 JSONL 后端恰好会立即持久化每个批次）。`handle.flush()` 是持久性屏障，同时把空的已创建会话实体化，使其可被持久列出。`handle.close()` 幂等且不可取消：读句柄释放本地资源；写句柄完成待处理的持久化并释放写所有权。一旦某次 `append` 或 `flush` 完成，其后在同一后端实例上开始的读取——无论经由任何句柄，还是经由 `stat`/`list`——至少能观察到该前缀。
+
+### 所有权与可见性
+
+`create` 与 `open(id, 'write')` 取得进程内单写者所有权：在持有者活跃期间第二次以写模式打开会以 `SessionAlreadyOwnedError` 拒绝，对已占用 id 执行 `create` 会以 `SessionAlreadyExistsError` 拒绝，在 `read` 句柄上执行修改会以 `SessionReadOnlyError` 拒绝——一种句柄类型，运行时拒绝。对已关闭句柄的任何操作会以 `SessionHandleClosedError` 拒绝，`SessionOwnershipLostError` 标记写所有权已永久丢失的写句柄（关闭并重新打开）。已创建的会话自 `create` 完成之刻起即可在本进程内被观察到，而后端可以把物理实体化推迟到第一次 `append` 或 `flush`；其他进程只能看到已实体化的会话，一个在崩溃前从未实体化的会话等于从未存在。
+
+### 实时写路径与关闭排空
+
+实时写路径由后端自持：它一次性安装会话监听器，把每个已发布会话的事件按 id 路由到该会话的活跃写句柄——`session/event` 复制进有界的内部批处理窗口，`session/flush` 是即时的持久性与错误观察屏障，`session/disposed` 执行最终排空并关闭句柄。没有活跃写句柄的已发布会话不做任何持久化。后台写入失败时按序保留其事件、暂停自动路径并记入日志；下一次显式 flush 会重试，并在再次失败时明确返回拒绝。`close()` 本身会先经由仍然打开的存储排空路由缓冲区再释放所有权，因此即便根 fiber 的 dispose（资源释放）并发运行各 fiber 的 disposer，后端拆卸时的关闭清扫也能保证应用关闭不丢数据。
+
+### 恢复与崩溃恢复
+
+持久化返回物理上有效的日志；语义修复属于读方。中途崩溃的会话保留其未闭合的最终轮次——单个轮次可能很大，而这些事件在崩溃前已持久追加；只有从未确认的撕裂尾部中不完整的碎片会被丢弃——从中恢复的完整记录由写路径在句柄的第一次新 append 之前持久重写。恢复（agent-loop）通过其写句柄读取已存储日志，计算 `interruptedTurnClosers`——合成 `tool/result` 错误、任何未闭合的 `step/end`，以及 `turn/end {interrupted}`——并把它们作为普通批次通过同一句柄追加。只读观察方（session-query）仅在内存中用同样的 closer 配平被中断的冷日志。
+
+### 失败与恢复
+
+当前构建无法忠实解读的存储日志会被拒绝，并返回指明拒绝方向的错误，绝不会被误读。`SessionHandle` 只暴露由 `SESSION_FORMAT_VERSION` 标识的当前逻辑记录；提供方必须在返回句柄前转换任何受支持的历史存储，随产品交付的 JSONL 提供方会通过静态 catalog 迁移受支持的历史代际。更新的格式会要求操作者升级 harness。本构建不认识的事件类型会被拒绝，除非其信封标记为 `ignorable`；已提交前缀中的损坏以 `SessionPersistenceCorruptionError` 拒绝。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节说明 seam 如何实现持久存储以及后端如何接入；可观察约定见[使用本包](#use-this-package)与生成的 [Kylin API](../../../docs/subsystems/persistence.zh.md#kylin-surface)。
+
+### 设计理念
+
+本包是 seam，而不是后端框架：它只导出抽象 `SessionPersistence` 服务、`SessionHandle` 约定、消费方捕获的稳定错误类、纯函数的存储记录校验辅助（`storage-contract`）以及带品牌类型的修订值——再无其他。每个提供方拥有自己完整的存储运行时（句柄类、修改排序、单写者记账、实时事件路由、拆卸），`tests/` 下的两套共享测试套件——`runPersistenceContract` 与 `runLiveWritePathContract`——固定所有提供方都必须一致的可观察行为。有意为之的后果：各提供方在存储恰好相似之处可以彼此相像，但没有任何实现机制跨越包边界。
+
+### 每个后端必须遵守的不变量
+
+- **仅追加，连续 `seq`。** 已提交事件绝不重写；`append` 的第一个 `seq` 必须等于已存储 next-seq，缺口会被拒绝。
+- **撕裂的物理尾部绝不到达读取方。** 它属于一次从未完成的 append；写路径在第一次新 append 之前将其持久截断。
+- **无损 JSON 数据。** 批次与 header 经过共享的单遍校验并快照边界（`materializeAppendBatch`/`materializeCreateHeader`）；无法序列化的载荷在调用处被拒绝。
+- **持久性。** `append` 尽力而为地持久化；`flush`——逐句柄或服务级——是承诺存储并同时把空会话实体化的屏障。
+- **遇到未知或无效格式时拒绝读取。** `validateStoredEvents` 拒绝未知事件词汇与已废弃的预发布形态；`assertVersion` 拒绝外来格式版本。
+- **每个后端实例单写者。** 提供方的进程内认领在 `create`/`open('write')` 时取得，在句柄关闭时释放。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：抽象 `SessionPersistence` 服务与重新导出的 seam 词汇 |
+| [`src/handle.ts`](src/handle.ts) | `SessionHandle` 约定：read/append/flush/close 语义与新鲜度规则 |
+| [`src/storage-contract.ts`](src/storage-contract.ts) | 共享校验：版本门禁、未知事件词汇拒绝、批次实体化、连续性 |
+| [`src/errors.ts`](src/errors.ts) | 稳定的句柄/所有权失败与格式拒绝 |
+| [`src/revision.ts`](src/revision.ts) | 带品牌类型的不透明修订值 token |
+
+### 写入路径概览
+
+写入器会话的每个 `session/event` 都复制进该句柄的内部缓冲。第一个待处理事件开启固定批处理窗口；后续事件加入但不重置截止时间。窗口到期后经由句柄的修改链排空待处理前缀；排空期间接纳的事件按顺序合并进下一个链上的批次。`session/flush` 取消等待并排空至完全停稳，随后运行 `handle.flush()`，因此 loop 在下一轮次前把它用作排序与错误观察检查点。失败的后台排空保留其事件并暂停自动计时器；显式 flush、写入器 close 或后端拆卸会立即重试，并在再次失败时明确返回拒绝。构造 seed 事件绝不发出 `session/event`，因此发布前通过句柄追加的 seed 绝不会被重新入队。
+
+### 存储记录校验
+
+seam 的共享辅助函数校验由 `SESSION_FORMAT_VERSION` 标识的当前逻辑记录，append 只写当前格式（[理由](../../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md)）。历史解码与不可变后继发布属于各提供方内部，并在其返回句柄前完成。每个后端都在句柄读取与写 open 预热时运行 `storage-contract` 校验，把未知事件类型作为 `SessionFormatUnsupportedError` 拒绝，把格式错误的当前记录作为 `SessionPersistenceCorruptionError` 拒绝，并在后端为每个会话保留一份产物时附上原始日志的 `SessionLocation`。
+
+</details>
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享持久性模型逐步进入随产品交付的后端与决策证据。
+
+- [会话持久化子系统](../../../docs/subsystems/persistence.zh.md)——完整服务约定、句柄语义、flush 检查点、崩溃恢复与生成的 Kylin API。
+- [基于句柄的持久化 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)——seam 设计及其所有权模型。
+- [JSONL 持久化后端](../session-persistence-jsonl/README.zh.md)——随产品交付、按会话存储文件的后端。
+- [会话检查点策略](../session-checkpoint-policy/README.zh.md)——在语义边界上经由 `session/flush` 刷新的插件。
+- [会话包映射](../README.zh.md)——相邻的持久化、投影、标题与遥测包。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 恢复的对话历史
+
+#### 模型看到什么
+
+seam 不添加提示词或 schema。恢复会将已存储的表层事件还原为消息历史；已存储请求 header 重建较早调用，新 loop 则为下一次请求组合当前系统提示词、工具与会话前缀。崩溃修复将没有持久调用的 assistant 请求标记为 `TOOL_NOT_STARTED`；有持久调用但无结果时变为 `TOOL_OUTCOME_UNKNOWN`，其文本允许模型重试只读或幂等工作，但要求验证副作用或询问用户，而不是盲目重试。
+
+#### Token 影响
+
+普通持久化期间为零 token。恢复后会重新计入保留历史的 token 用量，并照常计入当前请求 envelope 的 token 用量；每个已修复调用都会增加一段以引用形式保留的错误文本。
+
+#### KV Cache 影响
+
+持久化不修改当前请求前缀。只有当重建历史、当前 envelope 与模型路由匹配时，恢复 loop 才能重用提供方缓存；崩溃修复结果仅追加，不重写较早历史。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制界定 seam 保证的终点。它们是当前包约束，不是待办事项。
+
+- **seam 只保证单个后端实例内的写所有权**——跨进程排他由具体提供方负责。随产品交付的 JSONL 提供方通过内核锁在不同实例和进程之间提供租约；其他提供方必须记录等效保证，或要求部署方阻止并发写入。
+- **在有活跃会话时重载后端插件会使其写入器明确报错**——重载后的后端无法服务旧实例签发的句柄；写入会持续失败直到会话重启，没有任何机制静默重新接管日志。
+- **只有通过句柄获取的会话才会持久化**——仅靠 `ctx.sessions.create` + `session/flush` 不存储任何内容；agent-loop 是生产环境的获取点，测试通过 `create`/`append`/`close` 写入初始存储数据。
+- **无删除或保留接口**——剪枝已存储会话属于带外后端维护。
+- **`list()` 无分页且无过滤**——它返回每个已存储会话的快照；适合本地存储，大规模时无索引。
+- **合成 closer 是唯一崩溃方案**——恢复通过写句柄追加 `interruptedTurnClosers`；没有继续中断轮次而不先关闭它的部分轮次恢复。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,269 @@
+import { Service } from "@qilin-agent/kylin";
+import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, adoptSessionEvent } from "@qilin-agent/session";
+import { snapshotJsonValue } from "@qilin-agent/util-values";
+//#region lib/types/revision.js
+/** Opaque revision identity for lightweight persistence observations. */
+/**
+* Brand a backend revision for the provider-neutral persistence contract.
+* @param value - backend-owned opaque revision representation.
+* @returns the same runtime string with persistence-revision identity.
+*/
+function SessionPersistenceRevision(value) {
+	return value;
+}
+//#endregion
+//#region lib/types/errors.js
+/**
+* Stable failures exposed by the session-persistence service and its handles,
+* including the format refusals shared by every backend: a stored log this
+* build cannot faithfully interpret is refused, never misread, and the
+* refusal points at the raw artifact when the backend keeps one per session.
+* @module @qilin-agent/session-persistence/errors
+*/
+/** The requested Session identity has no durable log visible to this caller. */
+var SessionPersistenceNotFoundError = class extends Error {
+	sessionId;
+	/** @param sessionId - absent durable Session identity. */
+	constructor(sessionId) {
+		super(`session "${sessionId}" not found`);
+		this.sessionId = sessionId;
+		this.name = "SessionPersistenceNotFoundError";
+	}
+};
+/** `create` targeted a Session identity that already exists in this backend. */
+var SessionAlreadyExistsError = class extends Error {
+	sessionId;
+	/** @param sessionId - the occupied durable Session identity. */
+	constructor(sessionId) {
+		super(`session "${sessionId}" already exists`);
+		this.sessionId = sessionId;
+		this.name = "SessionAlreadyExistsError";
+	}
+};
+/** A write open found the session already bound to an active write handle. */
+var SessionAlreadyOwnedError = class extends Error {
+	sessionId;
+	/** @param sessionId - the session whose write ownership is taken. */
+	constructor(sessionId) {
+		super(`session "${sessionId}" is already owned by an active write handle`);
+		this.sessionId = sessionId;
+		this.name = "SessionAlreadyOwnedError";
+	}
+};
+/** A mutation (`append`/`flush`) was called on a read handle. */
+var SessionReadOnlyError = class extends Error {
+	sessionId;
+	/**
+	* @param sessionId - the session the read handle observes.
+	* @param operation - the refused mutating operation name.
+	*/
+	constructor(sessionId, operation) {
+		super(`session "${sessionId}": ${operation} is not available on a read handle`);
+		this.sessionId = sessionId;
+		this.name = "SessionReadOnlyError";
+	}
+};
+/**
+* A write handle's ownership is permanently gone: its lease expired, a renewal
+* failed, or the durable ownership record no longer names this handle. The
+* handle never re-acquires ownership — close it and reopen for write.
+*
+* Declared for the cross-process lease layer; the shipped in-process backends
+* never throw it yet.
+*/
+var SessionOwnershipLostError = class extends Error {
+	sessionId;
+	/** @param sessionId - the session whose write ownership this handle lost. */
+	constructor(sessionId) {
+		super(`session "${sessionId}": write ownership was lost; close this handle and reopen`);
+		this.sessionId = sessionId;
+		this.name = "SessionOwnershipLostError";
+	}
+};
+/** An operation was called on a handle after `close()` was called. */
+var SessionHandleClosedError = class extends Error {
+	sessionId;
+	/**
+	* @param sessionId - the session the closed handle addressed.
+	* @param operation - the refused operation name.
+	*/
+	constructor(sessionId, operation) {
+		super(`session "${sessionId}": ${operation} on a closed handle`);
+		this.sessionId = sessionId;
+		this.name = "SessionHandleClosedError";
+	}
+};
+/** Durable session contents failed validation after a successful backend read. */
+var SessionPersistenceCorruptionError = class extends Error {
+	/**
+	* @param message - stable corruption context.
+	* @param options - original validation failure.
+	*/
+	constructor(message, options) {
+		super(message, options);
+		this.name = "SessionPersistenceCorruptionError";
+	}
+};
+/**
+* The stored log is intact but this runtime cannot faithfully interpret it:
+* the header carries an unsupported format version, or an event's type is
+* unknown to this build. Distinct from {@link SessionPersistenceCorruptionError}
+* — nothing is damaged; the raw log remains readable at {@link location} when
+* the backend keeps one artifact per session.
+*/
+var SessionFormatUnsupportedError = class extends Error {
+	location;
+	/**
+	* @param message - stable reason the log cannot be interpreted, already
+	*   including the raw-log path when one exists.
+	* @param location - the backend's artifact location, when one exists.
+	*/
+	constructor(message, location) {
+		super(message);
+		this.location = location;
+		this.name = "SessionFormatUnsupportedError";
+	}
+};
+/**
+* Direction-aware refusal text for a stored session whose format version this
+* build does not read. Shared by load-time checks and by backends that must
+* refuse BEFORE decoding version-dependent structure (a future format may not
+* satisfy this build's structural checks at all, and the user must see
+* "upgrade the harness", never "corrupt").
+* @param id - the stored session id, for message context.
+* @param version - the stored format version.
+* @returns the stable refusal text, without a raw-log path suffix.
+*/
+function sessionFormatVersionRefusal(id, version) {
+	return version > SESSION_FORMAT_VERSION ? `session "${id}" uses log format v${version}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it` : `session "${id}" uses log format v${version}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`;
+}
+//#endregion
+//#region lib/types/storage-contract.js
+/**
+* Backend-shared storage validation: the version gate, the fail-closed event
+* vocabulary, append-batch materialization, and contiguity — one place so
+* every backend refuses the same inputs identically.
+* @module @qilin-agent/session-persistence/storage-contract
+*/
+/** Build a format refusal that points at the raw artifact when the backend has one. */
+function unsupported(reason, location) {
+	return new SessionFormatUnsupportedError(location === void 0 ? reason : `${reason} (raw log: ${location.path})`, location);
+}
+/**
+* Refuse stored metadata that is not bound to the requested session id.
+* @param id - the requested session id.
+* @param meta - the stored header.
+*/
+function assertStoredId(id, meta) {
+	if (meta.id !== id) throw new Error(`stored session identity mismatch: requested "${id}", header contains "${meta.id}"`);
+}
+/**
+* Refuse a header that has not been restored to the current logical format.
+* @param meta - the stored header.
+* @param location - the backend's artifact location for the refusal, when one exists.
+*/
+function assertVersion(meta, location) {
+	if (meta.version !== SESSION_FORMAT_VERSION) throw unsupported(sessionFormatVersionRefusal(meta.id, meta.version), location);
+}
+/**
+* Validate one exclusively owned stored event array in place: adopt each
+* record (validating and freezing it) and refuse any event type this build
+* does not know, unless its writer marked it `ignorable: true` — silently
+* skipping an unknown required event could reconstruct a wrong session (the
+* envelope contract on `SessionEvent.ignorable`). Unknown required types and
+* retired pre-release shapes refuse here; this validator performs no migration.
+* @param meta - the stored header the events belong to.
+* @param events - exclusively owned decoded events; validated in place.
+* @param location - the backend's artifact location for refusals, when one exists.
+* @returns the same array, validated and frozen.
+* @throws {SessionFormatUnsupportedError} for unknown event types.
+* @throws {SessionPersistenceCorruptionError} for records that fail validation.
+*/
+function validateStoredEvents(meta, events, location) {
+	for (const event of events) {
+		if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true) throw unsupported(`session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`, location);
+		if (event.type === "request/header") {
+			const data = event.data;
+			if (typeof data === "object" && data !== null && data["reason"] === "fallback") throw unsupported(`session "${meta.id}" contains a request/header event (seq ${event.seq}) with the unsupported legacy reason "fallback"; refusing to interpret the log — it was written by a retired pre-release harness`, location);
+		}
+	}
+	try {
+		for (const [index, event] of events.entries()) events[index] = adoptSessionEvent(event);
+	} catch (error) {
+		if (error instanceof SessionFormatUnsupportedError) throw error;
+		throw new SessionPersistenceCorruptionError(`stored session "${meta.id}" failed validation: ${String(error)}`, { cause: error });
+	}
+	return events;
+}
+/**
+* Validate and deep-snapshot a header passed to `create` in one traversal.
+* @param header - the caller's header.
+* @returns the detached lossless-JSON header.
+* @throws {TypeError} for non-JSON metadata or an invalid `createdAt`.
+*/
+function materializeCreateHeader(header) {
+	const snapshot = snapshotJsonValue(header);
+	if (snapshot === void 0) throw new TypeError("session metadata must be losslessly JSON-serializable");
+	if (!Number.isSafeInteger(snapshot.createdAt) || snapshot.createdAt < 0) throw new TypeError("session metadata createdAt must be a non-negative safe integer");
+	return snapshot;
+}
+/**
+* Validate and deep-snapshot one append batch in a single traversal, so the
+* checked value is exactly the value persisted (a check followed by a copy
+* could reread accessors into a different record).
+* @param events - the caller's batch.
+* @returns the detached lossless-JSON batch.
+* @throws {TypeError} when any event data is not losslessly JSON-serializable.
+*/
+function materializeAppendBatch(events) {
+	const batch = snapshotJsonValue(events);
+	if (batch === void 0) throw new TypeError("session event batch is not losslessly JSON-serializable because it contains non-JSON-serializable data");
+	return batch;
+}
+/**
+* Refuse a batch that does not contiguously continue the stored log.
+* @param id - the session the batch belongs to.
+* @param events - the batch, in seq order.
+* @param cursor - the stored next-seq.
+*/
+function assertContiguous(id, events, cursor) {
+	for (const [index, event] of events.entries()) if (event.seq !== cursor + index) throw new Error(`append seq mismatch for "${id}": expected ${cursor + index} at index ${index}, got ${event.seq}`);
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* 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; callers address one stored
+* session through a {@link SessionHandle} obtained from `create`/`open`.
+* @module @qilin-agent/session-persistence
+*/
+/**
+* Durable append-only session storage addressed through per-session handles.
+*
+* Storage semantics shared by every backend: events are contiguous from seq 0
+* and never rewritten; a torn physical tail is never returned to a reader and
+* is truncated by the write path before its first append; reads validate
+* current-format records only and refuse unknown vocabulary fail-closed.
+* `append` persists best-effort; `flush` — per handle or service-wide — is
+* the durability barrier.
+*
+* Visibility: a created session is observable through `stat`/`list`/`open`
+* in this process from the moment `create` resolves, even while a backend
+* defers physical materialization (a pure optimization); other processes see
+* the session only once it materializes, and a session that never
+* materialized before a crash never existed. `SessionHandle.flush` forces
+* materialization.
+*
+* Freshness: once an `append` or `flush` resolves, reads started afterwards
+* on this backend instance observe at least that prefix.
+*/
+var SessionPersistence = class extends Service {
+	/** Process-local instance identity, stable through Context proxies and distinct after service replacement. */
+	identity = Symbol("sessionPersistence");
+	constructor(ctx) {
+		super(ctx, "sessionPersistence");
+	}
+};
+//#endregion
+export { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionFormatUnsupportedError, SessionHandleClosedError, SessionOwnershipLostError, SessionPersistence, SessionPersistence as default, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, SessionPersistenceRevision, SessionReadOnlyError, assertContiguous, assertStoredId, assertVersion, materializeAppendBatch, materializeCreateHeader, sessionFormatVersionRefusal, validateStoredEvents };

package/lib/types/errors.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Stable failures exposed by the session-persistence service and its handles,
+ * including the format refusals shared by every backend: a stored log this
+ * build cannot faithfully interpret is refused, never misread, and the
+ * refusal points at the raw artifact when the backend keeps one per session.
+ * @module @qilin-agent/session-persistence/errors
+ */
+import type { SessionId } from '@qilin-agent/session';
+/** The requested Session identity has no durable log visible to this caller. */
+export declare class SessionPersistenceNotFoundError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - absent durable Session identity. */
+    constructor(sessionId: SessionId);
+}
+/** `create` targeted a Session identity that already exists in this backend. */
+export declare class SessionAlreadyExistsError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the occupied durable Session identity. */
+    constructor(sessionId: SessionId);
+}
+/** A write open found the session already bound to an active write handle. */
+export declare class SessionAlreadyOwnedError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the session whose write ownership is taken. */
+    constructor(sessionId: SessionId);
+}
+/** A mutation (`append`/`flush`) was called on a read handle. */
+export declare class SessionReadOnlyError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - the session the read handle observes.
+     * @param operation - the refused mutating operation name.
+     */
+    constructor(sessionId: SessionId, operation: string);
+}
+/**
+ * A write handle's ownership is permanently gone: its lease expired, a renewal
+ * failed, or the durable ownership record no longer names this handle. The
+ * handle never re-acquires ownership — close it and reopen for write.
+ *
+ * Declared for the cross-process lease layer; the shipped in-process backends
+ * never throw it yet.
+ */
+export declare class SessionOwnershipLostError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the session whose write ownership this handle lost. */
+    constructor(sessionId: SessionId);
+}
+/** An operation was called on a handle after `close()` was called. */
+export declare class SessionHandleClosedError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - the session the closed handle addressed.
+     * @param operation - the refused operation name.
+     */
+    constructor(sessionId: SessionId, operation: string);
+}
+/**
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
+ */
+export interface SessionLocation {
+    /** Backend-specific artifact kind, for example `jsonl`. */
+    readonly kind: string;
+    /** Absolute path to this session's backend-owned artifact. */
+    readonly path: string;
+}
+/** Durable session contents failed validation after a successful backend read. */
+export declare class SessionPersistenceCorruptionError extends Error {
+    /**
+     * @param message - stable corruption context.
+     * @param options - original validation failure.
+     */
+    constructor(message: string, options: ErrorOptions);
+}
+/**
+ * The stored log is intact but this runtime cannot faithfully interpret it:
+ * the header carries an unsupported format version, or an event's type is
+ * unknown to this build. Distinct from {@link SessionPersistenceCorruptionError}
+ * — nothing is damaged; the raw log remains readable at {@link location} when
+ * the backend keeps one artifact per session.
+ */
+export declare class SessionFormatUnsupportedError extends Error {
+    readonly location?: SessionLocation | undefined;
+    /**
+     * @param message - stable reason the log cannot be interpreted, already
+     *   including the raw-log path when one exists.
+     * @param location - the backend's artifact location, when one exists.
+     */
+    constructor(message: string, location?: SessionLocation | undefined);
+}
+/**
+ * Direction-aware refusal text for a stored session whose format version this
+ * build does not read. Shared by load-time checks and by backends that must
+ * refuse BEFORE decoding version-dependent structure (a future format may not
+ * satisfy this build's structural checks at all, and the user must see
+ * "upgrade the harness", never "corrupt").
+ * @param id - the stored session id, for message context.
+ * @param version - the stored format version.
+ * @returns the stable refusal text, without a raw-log path suffix.
+ */
+export declare function sessionFormatVersionRefusal(id: string, version: number): string;
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/handle.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The per-session storage handle: one open channel onto a stored session's
+ * append-only event log, returned by `SessionPersistence.create`/`open`.
+ * @module @qilin-agent/session-persistence/handle
+ */
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset, SessionSeedEventState } from '@qilin-agent/session';
+/**
+ * Log access granted by an open. `write` is read-write: the session's single
+ * mutator, which also reads its own log. `read` only observes — it never
+ * takes ownership and works while another handle or process holds `write`.
+ */
+export type SessionAccess = 'read' | 'write';
+/** Options for {@link SessionHandle.read}. */
+export interface SessionHandleReadOptions {
+    /** Optional cancellation for backend read work. */
+    readonly signal?: AbortSignal;
+}
+/** One persistence event slice returned by {@link SessionHandle.read}. */
+export interface SessionHandleReadResult {
+    /**
+     * Whether event values are exclusively owned or shared only after deep
+     * freezing. Slicing preserves the producer's state even when no events remain.
+     */
+    readonly eventState: SessionSeedEventState;
+    /** Event values in a caller-owned outer array. */
+    readonly events: readonly SessionEvent[];
+}
+/** Options for {@link SessionHandle.append}. */
+export interface SessionHandleAppendOptions {
+    /** Optional cancellation observed before the write starts. */
+    readonly signal?: AbortSignal;
+}
+/** Options for {@link SessionHandle.flush}. */
+export interface SessionHandleFlushOptions {
+    /** Optional cancellation observed before the barrier starts. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+export interface SessionHandle extends AsyncDisposable {
+    /** The stored session this handle addresses. */
+    readonly id: SessionId;
+    /** The immutable stored header, fixed at `create`/`open`. */
+    readonly header: SessionHeader;
+    /**
+     * Exact fork-inherited prefix length stored with the log; `0` when
+     * `header.isSeeded` is false. Storage metadata paired with the header for
+     * every body read, never part of the replayable event log.
+     */
+    readonly inheritedEventCount: SessionLogOffset;
+    /** Whether this handle may mutate the log. */
+    readonly access: SessionAccess;
+    /**
+     * Read a slice of the valid contiguous logical log. The slice is a legal log
+     * prefix segment: a torn physical tail is never returned, and repeated reads
+     * on this handle never observe an older state than a prior read.
+     * @param offset - first logical event seq to include; defaults to `0`.
+     * @param length - maximum number of events to return; defaults to the rest
+     *   of the log. An offset at or past the end returns an empty list.
+     * @param options - optional cancellation.
+     * @returns the caller-owned outer slice plus the ownership state of its event values.
+     */
+    read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<SessionHandleReadResult>;
+    /**
+     * Append a contiguous batch continuing the current logical end. The first
+     * event's `seq` MUST equal the stored next-seq; committed events are never
+     * rewritten. Persistence is best-effort: on resolution the batch is
+     * accepted, ordered, and visible to reads on this backend instance, but
+     * only a resolved {@link flush} promises it survives a crash — a backend
+     * may buffer or batch physical writes behind append. Rejects with
+     * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+     * when write ownership is gone.
+     * @param events - the contiguous batch, in seq order.
+     * @param options - optional cancellation observed before the write starts.
+     */
+    append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>;
+    /**
+     * The durability barrier — the one operation that promises storage: on
+     * resolution every acknowledged append is durable and the session is
+     * materialized for other processes; an empty created session becomes
+     * durably listable here. Callers that must survive a crash flush; a backend
+     * whose `append` already persists on resolution treats this as
+     * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+     * handle.
+     * @param options - optional cancellation observed before the barrier starts.
+     */
+    flush(options?: SessionHandleFlushOptions): Promise<void>;
+    /**
+     * Release the handle: a read handle frees local resources; a write handle
+     * completes pending durability and releases write ownership. Idempotent,
+     * asynchronous, and deliberately not cancellable.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=handle.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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; callers address one stored
+ * session through a {@link SessionHandle} obtained from `create`/`open`.
+ * @module @qilin-agent/session-persistence
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@qilin-agent/session';
+import type { SessionHandle, SessionAccess } from './handle.ts';
+import type { SessionPersistenceRevision } from './revision.ts';
+export type { SessionHeader } from '@qilin-agent/session';
+export { SessionPersistenceRevision } from './revision.ts';
+export type { SessionAccess, SessionHandle, SessionHandleAppendOptions, SessionHandleFlushOptions, SessionHandleReadOptions, SessionHandleReadResult, } from './handle.ts';
+export { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionFormatUnsupportedError, SessionHandleClosedError, SessionOwnershipLostError, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, SessionReadOnlyError, sessionFormatVersionRefusal, } from './errors.ts';
+export type { SessionLocation } from './errors.ts';
+export { assertContiguous, assertStoredId, assertVersion, materializeAppendBatch, materializeCreateHeader, validateStoredEvents, } from './storage-contract.ts';
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
+export interface SessionPersistenceSnapshot {
+    /** Detached metadata for one stored session. */
+    readonly header: SessionHeader;
+    /** Opaque change token; see {@link SessionPersistence.stat}. */
+    readonly revision: SessionPersistenceRevision;
+    /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+    readonly eventCount?: number;
+    /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+    readonly sizeBytes?: number;
+}
+/** Options for {@link SessionPersistence.create}. */
+export interface SessionPersistenceCreateOptions {
+    /** Optional cancellation observed before backend work starts. */
+    readonly signal?: AbortSignal;
+    /**
+     * Exact fork-inherited prefix length. Required when `header.isSeeded` is
+     * true and must be omitted (or `0`) otherwise; the backend refuses a
+     * mismatch at create.
+     */
+    readonly inheritedEventCount?: SessionLogOffset;
+}
+/**
+ * Logical Session header paired with its exact inherited cut for body-bearing
+ * storage operations. `isSeeded` marks fork lineage on the header; the
+ * numeric cut travels beside it, never inside the replayable event log.
+ */
+export interface SessionStorageMetadata {
+    /** Validated immutable Session header. */
+    readonly meta: SessionHeader;
+    /** Number of leading events inherited from the Session's fork parent. */
+    readonly inheritedEventCount: SessionLogOffset;
+}
+/** Immutable logical session read: storage metadata plus the complete validated event log. */
+export interface SessionInspection extends SessionStorageMetadata {
+    /** Contiguous validated events from seq 0. */
+    readonly events: readonly SessionEvent[];
+}
+/** Options for {@link SessionPersistence.open}. */
+export interface SessionPersistenceOpenOptions {
+    /** Optional cancellation observed before backend work starts. */
+    readonly signal?: AbortSignal;
+}
+/** Options for {@link SessionPersistence.stat}. */
+export interface SessionPersistenceStatOptions {
+    /** Optional cancellation for backend metadata reads. */
+    readonly signal?: AbortSignal;
+}
+/** Options for {@link SessionPersistence.list}. */
+export interface SessionPersistenceListOptions {
+    /** Optional cancellation for backend listing work. */
+    readonly signal?: AbortSignal;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        sessionPersistence: SessionPersistence;
+    }
+}
+/**
+ * Durable append-only session storage addressed through per-session handles.
+ *
+ * Storage semantics shared by every backend: events are contiguous from seq 0
+ * and never rewritten; a torn physical tail is never returned to a reader and
+ * is truncated by the write path before its first append; reads validate
+ * current-format records only and refuse unknown vocabulary fail-closed.
+ * `append` persists best-effort; `flush` — per handle or service-wide — is
+ * the durability barrier.
+ *
+ * Visibility: a created session is observable through `stat`/`list`/`open`
+ * in this process from the moment `create` resolves, even while a backend
+ * defers physical materialization (a pure optimization); other processes see
+ * the session only once it materializes, and a session that never
+ * materialized before a crash never existed. `SessionHandle.flush` forces
+ * materialization.
+ *
+ * Freshness: once an `append` or `flush` resolves, reads started afterwards
+ * on this backend instance observe at least that prefix.
+ */
+export declare abstract class SessionPersistence extends Service {
+    /** Process-local instance identity, stable through Context proxies and distinct after service replacement. */
+    readonly identity: symbol;
+    constructor(ctx: Context);
+    /**
+     * Create a new stored session and take its write ownership.
+     * @param header - the immutable header (id, version, cwd, lineage) to store.
+     * @param options - optional cancellation.
+     * @returns a `write` handle owned by the caller; close it to release ownership.
+     * @throws {SessionAlreadyExistsError} when the id already exists.
+     */
+    abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>;
+    /**
+     * Open an existing stored session.
+     *
+     * `read` never takes ownership and works while another handle (or process)
+     * holds write ownership. `write` atomically claims single-writer ownership;
+     * an existing active owner rejects.
+     * @param id - the stored session to open.
+     * @param access - `read` or `write`.
+     * @param options - optional cancellation.
+     * @returns the open handle.
+     * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+     * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
+     */
+    abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>;
+    /**
+     * Flush every active write handle owned by this service instance in one
+     * durability barrier: each handle's routed live events drain durably and
+     * its session materializes, exactly as that handle's own
+     * `SessionHandle.flush` would. Read handles buffer nothing and are
+     * untouched. A handle closed concurrently counts as flushed — close itself
+     * drains durably.
+     * @returns resolution once every write handle active at the call has flushed.
+     * @throws {AggregateError} naming each session whose flush failed; the
+     *   remaining handles still flush.
+     */
+    abstract flush(): Promise<void>;
+    /**
+     * Observe one stored session without reading its event log or taking
+     * ownership.
+     *
+     * The snapshot's `revision` is an opaque change token comparable only
+     * against revisions from the same service instance and session id: equal
+     * revisions may be treated as an unchanged log; unequal revisions promise
+     * nothing. Write-ownership churn does not change a revision. It exists for
+     * derived read-model caches keyed off `stat`/`list`; it plays no part in
+     * open, read, or resume.
+     * @param id - the stored session to observe.
+     * @param options - optional cancellation.
+     * @returns the snapshot, or `undefined` when the session does not exist.
+     */
+    abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>;
+    /**
+     * List every stored session visible to this process, in no promised order.
+     * @param options - optional cancellation.
+     * @returns one snapshot per stored session.
+     */
+    abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>;
+}
+export default SessionPersistence;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/revision.d.ts

@@ -0,0 +1,14 @@
+/** Opaque revision identity for lightweight persistence observations. */
+import type { Branded } from '@qilin-agent/brand';
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+export type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>;
+/**
+ * Brand a backend revision for the provider-neutral persistence contract.
+ * @param value - backend-owned opaque revision representation.
+ * @returns the same runtime string with persistence-revision identity.
+ */
+export declare function SessionPersistenceRevision(value: string): SessionPersistenceRevision;
+//# sourceMappingURL=revision.d.ts.map

package/lib/types/storage-contract.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Backend-shared storage validation: the version gate, the fail-closed event
+ * vocabulary, append-batch materialization, and contiguity — one place so
+ * every backend refuses the same inputs identically.
+ * @module @qilin-agent/session-persistence/storage-contract
+ */
+import type { SessionEvent, SessionHeader, SessionId } from '@qilin-agent/session';
+import { type SessionLocation } from './errors.ts';
+/**
+ * Refuse stored metadata that is not bound to the requested session id.
+ * @param id - the requested session id.
+ * @param meta - the stored header.
+ */
+export declare function assertStoredId(id: SessionId, meta: SessionHeader): void;
+/**
+ * Refuse a header that has not been restored to the current logical format.
+ * @param meta - the stored header.
+ * @param location - the backend's artifact location for the refusal, when one exists.
+ */
+export declare function assertVersion(meta: {
+    readonly id: SessionId;
+    readonly version: number;
+}, location?: SessionLocation): void;
+/**
+ * Validate one exclusively owned stored event array in place: adopt each
+ * record (validating and freezing it) and refuse any event type this build
+ * does not know, unless its writer marked it `ignorable: true` — silently
+ * skipping an unknown required event could reconstruct a wrong session (the
+ * envelope contract on `SessionEvent.ignorable`). Unknown required types and
+ * retired pre-release shapes refuse here; this validator performs no migration.
+ * @param meta - the stored header the events belong to.
+ * @param events - exclusively owned decoded events; validated in place.
+ * @param location - the backend's artifact location for refusals, when one exists.
+ * @returns the same array, validated and frozen.
+ * @throws {SessionFormatUnsupportedError} for unknown event types.
+ * @throws {SessionPersistenceCorruptionError} for records that fail validation.
+ */
+export declare function validateStoredEvents(meta: SessionHeader, events: SessionEvent[], location?: SessionLocation): SessionEvent[];
+/**
+ * Validate and deep-snapshot a header passed to `create` in one traversal.
+ * @param header - the caller's header.
+ * @returns the detached lossless-JSON header.
+ * @throws {TypeError} for non-JSON metadata or an invalid `createdAt`.
+ */
+export declare function materializeCreateHeader(header: SessionHeader): SessionHeader;
+/**
+ * Validate and deep-snapshot one append batch in a single traversal, so the
+ * checked value is exactly the value persisted (a check followed by a copy
+ * could reread accessors into a different record).
+ * @param events - the caller's batch.
+ * @returns the detached lossless-JSON batch.
+ * @throws {TypeError} when any event data is not losslessly JSON-serializable.
+ */
+export declare function materializeAppendBatch(events: readonly SessionEvent[]): readonly SessionEvent[];
+/**
+ * Refuse a batch that does not contiguously continue the stored log.
+ * @param id - the session the batch belongs to.
+ * @param events - the batch, in seq order.
+ * @param cursor - the stored next-seq.
+ */
+export declare function assertContiguous(id: SessionId, events: readonly SessionEvent[], cursor: number): void;
+//# sourceMappingURL=storage-contract.d.ts.map

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@qilin-agent/session-persistence",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Abstract durable session persistence seam (ctx.sessionPersistence) for the QiLin",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/session/session-persistence"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/brand": "3.1.3",
+    "@qilin-agent/timeout": "3.1.3",
+    "@qilin-agent/session": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/scope": "3.1.3",
+    "@qilin-agent/session": "3.1.3",
+    "@qilin-agent/timeout": "3.1.3",
+    "@qilin-agent/brand": "3.1.3"
+  },
+  "dependencies": {
+    "@qilin-agent/util-values": "3.1.3"
+  }
 }