chore(storage,runtime): retire legacy Task Ledger after SessionTodo migration window

[me2seeks]

Problem

#4351 cut the product over to SessionTodo, but intentionally retained the legacy Task Ledger replay, codecs, tests, and tables for lazy migration and rollback. A SessionTodo document is materialized only when a Session first reads Todo: pending/in-progress Tasks are imported, blocked Tasks become pending, and even an empty document is persisted.

Consequently, directly deleting the legacy tables or replay code would strand old Sessions that have not yet reached readOrBootstrap. #4420 separately repairs the persisted Runtime Host access grant transition from task.ledger.query to session.todo.query; it does not materialize legacy Task data.

Desired outcome

After an explicitly chosen migration window, supported State Roots reach a durable SessionTodo document without any runtime dependency on legacy Task Ledger state. Then remove the retired implementation and database storage without reintroducing a dual writer or a dual product surface.

Scope and acceptance criteria

• Define the supported pre-retirement State Root/version boundary and the backup, restore, and downgrade policy.
• Define and test a deterministic final migration for eligible Sessions that have no SessionTodo document yet, including initialized-empty semantics and the existing blocked-to-pending mapping.
• Treat the fix(desktop): recover managed Runtime Host startup #4420 access-grant compatibility path as release-upgrade evidence before declaring the legacy operation fully retired.
• Remove legacy Task Ledger replay, codecs, stores, operational-backup handling, tests, and SQLite tables only after the final migration is proven.
• Verify no remaining production consumer exposes task_ tools, task.ledger.query, the legacy Task change feed, or a Task Ledger UI projection.
• Add upgrade, backup/restore, removal, and unsupported-downgrade regressions for the final boundary.

Non-goals

• Do not change the SessionTodo contract: it remains a Host-owned current snapshot, read explicitly with todo_read and replaced atomically with todo_write.
• Do not restore Task identity, mutation history, revision/CAS, turn-tail injection, task-to-subagent binding, claim/settle, or a compatibility switch.
• Do not begin physical deletion merely because feat(runtime): cut over SessionTodo to Runtime Host authority #4351 merged; the migration-window and State Root support decisions are required first.

Related

• Parent RFC: RFC: Radically slim the Session Task Ledger #2290
• Product cutover tracker: feat: replace Session Task Ledger with a SessionTodo current snapshot #4338
• SessionTodo foundation: feat(storage): add dormant SessionTodo foundation #4340
• Atomic product cutover: feat(runtime): cut over SessionTodo to Runtime Host authority #4351
• Installed Runtime Host access-grant recovery: fix(desktop): recover managed Runtime Host startup #4420
• Superseded Task mutation-history direction: feat(runtime-host,cli): render Task Ledger mutations as a durable semantic timeline #4179

AI assistance disclosure: Codex helped derive the migration and compatibility acceptance criteria from the merged SessionTodo cutover. I reviewed the scope and own the final position.

[M4n5ter]

English

This issue is over-designed in its current form. It proposes a migration window, release-observation gates, and a broader retirement program for a cutover that the repository’s existing versioned Operational State migration already supports.

A migration window provides no additional safety. Offline State Roots do not migrate while waiting, and they do not need to: they can migrate atomically the first time the next minor release opens them.

The repository already has the required mechanism:

• operational-state-store.ts inspects registered schema versions before exposing the database to Runtime.
• migrateOperationalStateDatabaseInternal migrates all scopes inside one BEGIN IMMEDIATE transaction and rolls everything back on failure.
• operational_schema_migrations records the current workflow version.
• sqlite-legacy-scheduling.ts already demonstrates the intended pattern for decoding released legacy state, validating it, writing its replacement, and retiring the old tables.

Task Ledger retirement should use that existing mechanism:

1. Increment SQLITE_WORKFLOW_SCHEMA_VERSION from 11 to 12 in the next minor release.
2. Add a small, isolated legacy Task Ledger converter to the existing migration chain.
3. For Workflow schema versions that still contain Task Ledger state, materialize the required SessionTodo documents using the already-approved conversion semantics.
4. Drop the Task Ledger tables in the same transaction.
5. Register Workflow schema v12.
6. Remove lazy bootstrap and all legacy Task Ledger Runtime stores, codecs, replay, backup special cases, and product paths.

The converter may remain isolated in the historical schema migration chain so State Roots that skipped releases can still upgrade directly. That is not continued Runtime compatibility, and each State Root executes it only once.

The necessary tests are correspondingly small: one released-schema migration fixture proving conversion and table removal, one rollback case, and the current-schema case. The existing Operational State suite already covers the general transaction and newer-schema rejection contracts.

#4420 is a separate persisted access-grant migration. It should not become a release-observation gate for this storage migration.

There is no need for a migration window or a separate retirement program. I recommend replacing the current body with this bounded Workflow v11 → v12 schema migration.

中文

这个 issue 当前属于过度设计。仓库已有带版本的 Operational State 迁移机制，却又提出了迁移窗口、发布观察门槛和一整套更大的退役计划。

迁移窗口不会增加任何安全性。离线的 State Root 不会因为等待若干版本而自动迁移，也不需要这样做：它在下一 minor 版本首次打开时原子迁移即可。

仓库已经具备所需机制：

• operational-state-store.ts 会在数据库交给 Runtime 前检查已登记的 schema version。
• migrateOperationalStateDatabaseInternal 在一个 BEGIN IMMEDIATE 事务中迁移所有 scope，失败时整体回滚。
• operational_schema_migrations 已经记录 workflow 版本。
• sqlite-legacy-scheduling.ts 已经展示了读取和验证已发布旧状态、写入新结构并删除旧表的现成模式。

Task Ledger 的退役应该直接复用这套机制：

1. 在下一个 minor 版本将 SQLITE_WORKFLOW_SCHEMA_VERSION 从 11 提升到 12。
2. 在现有迁移链中增加一个小型、隔离的旧 Task Ledger 转换器。
3. 对仍包含 Task Ledger 状态的 Workflow schema，按照已经确认的转换语义生成必要的 SessionTodo 文档。
4. 在同一事务中删除 Task Ledger 表。
5. 登记 Workflow schema v12。
6. 删除 lazy bootstrap，以及所有旧 Task Ledger Runtime store、codec、replay、备份特殊处理和产品路径。

为了让跳过版本的 State Root 仍能直接升级，可以将这个转换器隔离保留在历史 schema migration chain 中。这不等于保留 Runtime 兼容，而且每个 State Root 只会执行一次。

所需测试也很少：一个已发布旧 schema fixture 验证转换和删表，一个失败回滚用例，以及当前 schema 用例。现有 Operational State 测试已经覆盖通用事务和拒绝新版本 schema 的合同。

#4420 处理的是另一项持久化 access grant 迁移，不应该成为本次存储迁移的发布观察门槛。

这里不需要迁移窗口，也不需要单独建立一套退役计划。建议将当前正文替换为这个有界的 Workflow v11 → v12 schema migration。

[me2seeks]

Agree. This tracker over-scoped the remaining work: it is a bounded Workflow schema 11 -> 12 migration, not a migration window or release-observation program. The existing Operational State migration transaction is the authority for validating legacy Task Ledger rows, materializing SessionTodo, and dropping the retired tables atomically. #4420 is a separate persisted access-grant compatibility repair and is not a gate for that storage migration. Closing this Issue; #4338 continues to track the remaining legacy retirement, which should land as one self-contained schema-migration PR.