v0.2.0-rc.1

v0.2.0-rc.1

适配 dsh 0.2.0-rc.1 接缝（SESSION_FORMAT_VERSION 3→4），并保持对 0.1.5 存量数据的可读性。预发布版（prerelease）。

适配

• peer/dev 升至 @deepseek-ai/dsh-session / dsh-session-persistence ^0.2.0-rc.1（cordis ^4.0.4，0.2.0 要求 ~4.0.4）。
• 读路径按运行时 SESSION_FORMAT_VERSION 盖章（headerFromRow），存量 sessions.version=3 行不阻塞；事件词汇表向后包含，0.1.5 事件在 v4 校验下仍被接受。
• 新增集成测试 test/integration/format-compat.test.ts：遗留 version=3 头 + 0.1.5 兼容事件，经后端读与 open('read') 均可读出。
• SCHEMA_VERSION 保持 3：本次无 DDL 变更，与会话日志格式版本已解耦。
• 兼容边界：v4 新增事件类型（developer/message / image/offload / workspace/changes）与 forked turn 结束原因；反向用旧运行时读 v4 日志仍 fail-closed。

门禁

• lint / typecheck / build 全绿；86 测试通过；coverage lines 97.24%。

完整变更：v0.1.5-rc.2...v0.2.0-rc.1

v0.1.5-rc.2

v0.1.5-rc.2

新增跨进程租约模式（cluster/lease，opt-in），并修复类型声明未随包发布的问题。预发布版（prerelease）。

新特性：跨进程租约

• 新增 opt-in cluster.lease.*（默认 enabled=false，关闭时行为与单实例逐字节一致）。
• 新增 leases 表与 SCHEMA_VERSION 2→3；open('write')/create 原子认领写所有权：活跃持有抛 SessionAlreadyOwnedError，过期以更高 fence 接管。
• append/flush 在写事务内、幂等 no-op 判定之前校验围栏；不符抛 SessionOwnershipLostError。
• 心跳续租；close 非删除式释放（保留 fence，防复位）。
• 暂缓：多主 lease-primary 连接与租约行清扫（TD-008，见 README「已知限制与待办」）。

修复

• 类型声明实际产物为 lib/index.d.ts，修正 package.json 的 types/exports/files；此前版本的类型声明未随包发布。

门禁

• lint / typecheck / build 全绿；85 测试通过；coverage lines 97.1%。

完整变更：v0.1.5-rc.1...v0.1.5-rc.2

v0.1.5-rc.1

v0.1.5-rc.1

适配 dsh 0.1.5-rc.1 接缝（SessionPersistence 改为 create/open/flush/stat/list + SessionHandle），并修复共享 MySQL 下的 append 重复主键问题。预发布版（prerelease）。

适配

• peer/dev 升至 @deepseek-ai/dsh-session / dsh-session-persistence ^0.1.5-rc.1（cordis ^4.0.2）。
• 去掉 PersistenceCoordinator 中介，子类直接实现 0.1.5 抽象方法；新增 MysqlBackendTracker（单写者 + live event 路由）与 MysqlSessionHandle。
• 会话头格式 v3；schema v1→v2 迁移（旧 v0 行刷到 v3）。
• 移除空的 invariants 伴生入口与 dsh-invariants 依赖（对齐官方 dsh-session-persistence-jsonl）。
• 清理已失效配置（packChunks、WRITE_BATCH_DELAY_MS、PREPARED_CACHE_SIZE）。

修复

• append 重复主键幂等：重复键（errno 1062）时按「同 seq 内容逐条一致」判定——内容一致 → 幂等 no-op（“提交成功但 ack 丢失”的 at-least-once 重放）；同 seq 不同内容 → 明确冲突错误。
• 导出 501 由上游承接：0.1.5 的 dsh-session-log-export 改为经 open(id,"read") + SessionHandle.read() 读取并自行序列化 canonical JSONL；本插件无需实现 raw-artifact。

门禁

• test 75/75；coverage lines 97.95%；typecheck / lint / build / smoke 全绿。

依赖 dsh 0.1.5-rc.1，请与 @deepseek-ai/dsh-session / @deepseek-ai/dsh-session-persistence 同步升级。

v0.1.2-rc.1

v0.1.2-rc.1

将本插件对齐到 dsh 0.1.2-rc.1（dsh 家族锁步发布，当前 latest）的持久化接缝契约。预发布版（prerelease）。

主要变更

• 依赖对齐：peer/dev @deepseek-ai/dsh-session / dsh-session-persistence / dsh-invariants → ^0.1.2-rc.1；@deepseek-ai/cordis → ^4.0.2；新增 dev dsh-brand / dsh-timeout / dsh-scope。
• 持久化 hooks：appendBatch / commitRepair 首参改为 SessionStorageMetadata{meta, inheritedEventCount}；新增后端 hook materializeHeader（空会话 header 持久化）。
• 数据模型：SessionHeader 移除 seedLength、新增必填 isSeeded。seed_length 列保留为 fork 继承前缀编码（isSeeded 由列非空推导，镜像官方 JSONL 编码）→ 零 DDL 迁移，存量数据向后兼容；事件格式仍为 SESSION_FORMAT_VERSION v0。
• 插件子类：实现 0.1.2 新增抽象 borrowSession / ensureMaterialized；create 支持 inheritedEventCount?；readFrom 返回 SessionEventSuffix、按 SessionLogOffset 寻址。

验证

• typecheck 0 错误；biome / build 通过。
• 测试 10 文件 / 47 例全绿（契约一致性 9、安全 6、e2e 1、bench 2 等）。
• 覆盖率：lines 95.6% / funcs 91.7% / branches 86.2%。

文档

• docs/TECH_DEBT.md|json：TD-005 → resolved。
• CHANGELOG.md、docs/tasks/T6（迁移交接）已更新。

备注：对外以真实 @deepseek-ai/dsh@0.1.2-rc.1 harness 的挂载 e2e 属后续 release 阶段。

v0.1.1

🚀 v0.1.1 — MySQL 会话持久化后端

• 中文 · English

---

DeepSeek Harness（dsh）的 MySQL 会话持久化后端——dsh-session-persistence 能力接缝的一个具体 Provider。以插件加载后注册 ctx.sessionPersistence，把 event-sourced 的 SessionEvent 日志持久化到 MySQL，与 JSONL 后端行为契约等价，并支持读写分离。

新增

• MySQL SessionPersistence 后端插件（@sandersyao/dsh-session-persistence-mysql）：
  • 复用 PersistenceCoordinator，实现 PersistenceBackend hooks（loadStored / readStoredRevision / loadStoredFrom / appendBatch / commitRepair / list / close）。
  • 两表（sessions + events）+ _meta 版本表：幂等建表 + 版本校验/迁移，fail-closed。
  • Lazy materialization：会话头与首批事件同一事务原子提交。
  • 无撕裂尾部：写路径单事务，tornMarker 恒为 undefined。
  • 读写分离：写池 / 读池；读库缺省复用写库。
  • Chunk run 折叠（MYSQL_PACK_CHUNKS，默认开启）。
  • 死锁（ER_LOCK_DEADLOCK）有限退避重试。
  • readFrom seek（loadStoredFrom，WHERE seq >= ?）。
• 打包为 dsh 组合包（bundle）：dsh.bundle + 随包 cordis.patch.yml，dsh plugin add 一行安装即替换默认 JSONL 后端。
• 发布流水线：GitHub Actions 打 tag 自动发布到 npmjs。

安全

• 全部参数化占位符；会话 id 不作 SQL 标识符拼接；表前缀字符集校验。
• 凭据仅来自环境变量 / .env；日志脱敏，配置不回显。
• 明文默认 + ENCRYPTION_KEY 预留扩展位（字段加密暂缓）。

测试

• 单元 20 例 + 契约一致性 9 例 + 安全 6 例 + 后端集成 2 例 + e2e 1 例 + 基准 2 例。
• 覆盖率门禁：lines ≥ 90（当前约 94%）。

已知限制 / 待办

• 无删除/归档 API；list() 不分页；TLS 暂缓；v0.1.2-alpha.3 兼容为后续工作（详见 docs/TECH_DEBT.md）。

---

The MySQL durable session-persistence backend for the DeepSeek Harness — a concrete SessionPersistence provider behind the dsh-session-persistence seam. Load it as a plugin; it registers ctx.sessionPersistence and persists the event-sourced SessionEvent log into MySQL, behavior-contract-equivalent to the JSONL backend, with read/write split support.

Features

• MySQL SessionPersistence backend plugin (@sandersyao/dsh-session-persistence-mysql):
  • Reuses PersistenceCoordinator; implements the PersistenceBackend hooks (loadStored / readStoredRevision / loadStoredFrom / appendBatch / commitRepair / list / close).
  • Two tables (sessions + events) + a _meta version table: idempotent schema bootstrap + version check/migration, fail-closed.
  • Lazy materialization: session header and first event batch committed atomically in one transaction.
  • No torn tail: single-transaction write path, tornMarker is always undefined.
  • Read/write split: write pool / read pool; read DB falls back to the write pool.
  • Chunk-run folding (MYSQL_PACK_CHUNKS, enabled by default).
  • Deadlock (ER_LOCK_DEADLOCK) retry with bounded backoff.
  • readFrom seek (loadStoredFrom, WHERE seq >= ?).
• Shipped as a dsh bundle: dsh.bundle + a bundled cordis.patch.yml; one-command dsh plugin add replaces the default JSONL backend.
• Release pipeline: GitHub Actions publishes to npmjs on tag push.

Security

• All SQL uses parameterized placeholders; session ids are never concatenated as SQL identifiers; table-prefix charset validation.
• Credentials come only from environment variables / .env; logs are sanitized, config is never echoed.
• Plaintext by default + reserved ENCRYPTION_KEY extension slot (field encryption deferred).

Tests

• 20 unit + 9 conformance + 6 security + 2 backend integration + 1 e2e + 2 benchmark cases.
• Coverage gate: lines ≥ 90 (currently ~94%).

Known limitations / TODO

• No delete/archive API; list() is not paginated; TLS deferred; v0.1.2-alpha.3 compatibility is future work (see docs/TECH_DEBT.md).