feat(session): default JSONL writes to packed rows

This commit is contained in:
Tianyi Cui
2026-07-26 23:44:52 +08:00
parent cad2af4741
commit 4ff496c65c
47 changed files with 521 additions and 251 deletions

View File

@@ -0,0 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# 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
2026-07-26-remove-packed-session-fixture-migrator.md: d5f8ff65a38618c5f321f096921f7ce2b8af2d75
2026-07-26-remove-packed-session-fixture-migrator.zh.md: d46e9e035709c26f59cb7f0a6908e38d0da08bbe

View File

@@ -0,0 +1,38 @@
# Agent Note: Remove the packed-session fixture branch migrator
Status: proposed
English | [中文](2026-07-26-remove-packed-session-fixture-migrator.zh.md)
## Problem
The repository's default writers and snapshot check keep session fixtures in the canonical packed-row layout. `pnpm run migrate:packed-session-fixtures` remains alongside that permanent enforcement only so in-flight branches carrying older fixture edits can merge current `master` and mechanically converge without re-recording model output.
Once every such branch is merged, closed, or already canonical, the write command and its branch-convergence instructions have no continuing owner. Keeping a mutation command after its transition ends adds a second apparent maintenance path beside the permanent read-only snapshot check.
## Proposal
Remove the temporary `scripts/migrate-packed-session-fixtures.ts` CLI and the root `migrate:packed-session-fixtures` package command after a live inventory confirms that no open pull request still needs to convert session-format JSONL. Remove the transitional command links from the testing policy, the ACP snapshot README, and the implemented packed-row Agent Note in the same change.
Retain `scripts/session-fixture-layout.ts`, its unit tests, and `scripts/session-fixture-layout.snapshot.ts`. They define and enforce the permanent canonical layout; only the branch-facing writer is temporary.
Before removing the command, each affected branch merges the current `master`, runs the migrator once, commits the resulting fixture-only rewrite separately, and verifies that the repository-wide snapshot layout check passes. Closed or superseded branches require no migration.
## Alternatives considered
**Keep the command indefinitely.** This makes old fixture conversion convenient, but it leaves a repository-wide mutation tool after the only known migration window closes. The read-only gate already supplies the durable behavior and diagnostic.
**Remove the canonicalization module with the CLI.** The module is not transition residue: snapshot CI uses it to discover future fixtures, decode mixed physical records, and compare them with the canonical packed representation. Removing it would also remove enforcement.
**Delete the command immediately when packed rows reach `master`.** Older open branches would then need ad hoc scripts or manual snapshot regeneration after retargeting, increasing conflict risk and making decoded-event preservation harder to review.
## Acceptance criteria
- A live open-PR inventory finds no branch with session-format JSONL changes that still depends on the temporary migration command.
- The temporary CLI, root package command, and every branch-convergence link are absent; the permanent canonicalizer, unit tests, and snapshot check remain.
- `pnpm run test:snapshot`, `pnpm run doc-sync`, lint, and whitespace validation pass without the temporary command.
- Current documentation describes only the packed default and permanent canonical-layout enforcement.
## Risks
An incomplete open-branch inventory could strand a contributor with a large unpacked fixture conflict after the command disappears. The removal therefore depends on live pull-request evidence, not elapsed time. Retaining the command too long has a smaller operational cost but obscures which mechanism is permanent.

View File

@@ -0,0 +1,38 @@
# Agent Note: 移除打包会话 fixture 分支迁移器
Status: proposed
[English](2026-07-26-remove-packed-session-fixture-migrator.md) | 中文
## 问题
仓库的默认写入器和快照检查会使会话 fixture测试前置数据保持规范打包行布局。在永久强制机制之外仍保留 `pnpm run migrate:packed-session-fixtures`,唯一原因是让携带旧版 fixture 改动的在途分支可以合并当前 `master`,并在不重新录制模型输出的情况下通过机械转换收敛。
一旦每个此类分支均已合并、关闭或符合规范,写入命令及其分支收敛指引便不再有持续维护者。过渡结束后继续保留会修改仓库内容的命令,会在永久只读快照检查旁增加第二条看似有效的维护路径。
## 提案
最新清单确认不再有任何开放 PRPull Request需要转换会话格式 JSONL 后,移除临时 CLI `scripts/migrate-packed-session-fixtures.ts`以及根包package提供的 `migrate:packed-session-fixtures` 命令。在同一变更中移除测试政策、ACP 快照 README 和已实现打包行 Agent Noteagent 决策记录)中指向该过渡命令的链接。
保留 `scripts/session-fixture-layout.ts`、其单元测试和 `scripts/session-fixture-layout.snapshot.ts`。它们定义并强制执行永久规范布局;只有面向分支的写入器是临时机制。
移除命令前,每个受影响分支都要合并当前 `master`,运行一次迁移器,单独提交由此产生的仅 fixture 重写,并验证仓库级快照布局检查通过。已关闭或被取代的分支无需迁移。
## 曾考虑的替代方案
**无限期保留该命令。** 这会让旧 fixture 转换更方便,但也会在唯一已知迁移窗口关闭后,留下一个仓库级写入工具。只读门禁已经提供可长期保留的行为与诊断。
**随 CLI 一同移除规范布局转换模块。** 该模块不是过渡残留:快照 CI 使用它发现未来 fixture、解码混合物理记录并与规范打包表示进行比较。移除该模块也会移除强制机制。
**打包行进入 `master` 后立即删除命令。** 较旧的开放分支在重新定向后,只能使用临时脚本或手动重新生成快照,这会增加冲突风险,也会让解码事件保真度更难评审。
## 验收标准
- 最新开放 PR 清单未发现任何仍依赖临时迁移命令处理会话格式 JSONL 改动的分支。
- 临时 CLI、根包命令与所有分支收敛链接均不存在永久规范布局转换器、单元测试和快照检查仍然保留。
- `pnpm run test:snapshot``pnpm run doc-sync`、lint 和空白校验在没有临时命令的情况下通过。
- 当前文档仅描述打包默认值和永久规范布局强制机制。
## 风险
若开放分支清单不完整,命令消失后,贡献者可能会受困于大规模非打包 fixture 冲突。因此,移除操作取决于实时 PR 证据,而不是经过的时间。保留命令过久的运维成本较低,但会模糊哪一种机制才是永久机制。