docs: freeze vNext phase 0 contracts - #87
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 81561200ab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - 备份路径必填； | ||
| - 使用同一 Codex Home 的 restore 锁； | ||
| - 备份 metadata 与 session manifest 必须合法并绑定当前 Codex Home； |
There was a problem hiding this comment.
For a normal backup with no pending journal, restore --no-sessions currently validates metadata.json but never reads session-meta-backup.json, because restoreBackup gates that validation on restoreSessions. This line therefore freezes a stricter behavior than v0.5: a missing or malformed session manifest would currently still permit a config/DB-only restore, while future adapters or contract tests following this document may reject it. Qualify the requirement as applying when sessions are selected (or when pending-recovery coverage requires the manifest).
AGENTS.md reference: AGENTS.md:L9-L13
Useful? React with 👍 / 👎.
| | `root-model` | 根级 model、Provider section model 与 turn_context model 不同 | Follow/Keep/Explicit 三种 Switch 语义清晰；非目标字段和换行符不变 | | ||
| | `encrypted-content` | rollout 含来自原 Provider 的 `encrypted_content` | 只同步可见性元数据；保留加密内容字节并返回明确 warning | | ||
| | `large-rollout` | 超大 rollout、超过 64 KiB 的行、Unicode 与特殊 model 字符 | 流式处理且目标字段正确；未修改字节、CRLF 与原 mtime 按合同保持 | | ||
| | `malformed-rollout` | 截断、无效 JSONL、文件扫描期间消失等 | 不读取越界、不覆盖无法证明安全的内容；按操作返回 skip/error 并保留原字节 | |
There was a problem hiding this comment.
When a malformed non-header JSONL line still contains a recognizable turn_context and model field, the current Node implementation rewrites that line using raw regular expressions; for example, a truncated line ending after "model":"old" is changed to the target model rather than preserved. This expected result therefore does not describe v0.5 behavior and would conceal a Node/.NET parity difference. Mark preservation as a target safety change with the current behavior explicitly recorded, or defer this expectation until the implementation and regression test land.
AGENTS.md reference: AGENTS.md:L9-L13
Useful? React with 👍 / 👎.
|
|
||
| | Legacy Code / 状态 | Canonical Code | 映射要求 | | ||
| | --- | --- | --- | | ||
| | `RECOVERY_REQUIRED`、`recovery_required` | `RECOVERY_REQUIRED` | 保留备份路径、operationId 与恢复要求 | |
There was a problem hiding this comment.
When a write is blocked by an already-pending journal, the current RecoveryRequiredError carries the legacy code RECOVERY_REQUIRED, but the canonical table assigns that scenario to PENDING_TRANSACTION. This blanket mapping sends the typed blocker back to RECOVERY_REQUIRED, making PENDING_TRANSACTION effectively unreachable through the planned adapter and conflating a pre-existing recovery blocker with an incomplete automatic rollback. Split the mapping by exception type or operation context so RecoveryRequiredError maps to PENDING_TRANSACTION while genuine rollback failures remain RECOVERY_REQUIRED.
AGENTS.md reference: AGENTS.md:L9-L13
Useful? React with 👍 / 👎.
|
|
||
| | Fixture ID | 运行方式 | 关键预期 / 安全门槛 | | ||
| | --- | --- | --- | | ||
| | `locked-rollout` | 平台真实文件锁 | 锁定文件不被写；其他安全目标可形成 Partial Result；返回 `ROLLOUT_LOCKED` 语义并可重试 | |
There was a problem hiding this comment.
On Linux and macOS, the current Node implementation does not test or honor advisory rollout locks: splitLockedSessionChanges returns every change as writable whenever process.platform !== "win32", and ordinary POSIX reads and renames are not blocked by another process holding flock. Consequently this cross-platform fixture's assertion that a platform-real locked file is never written cannot pass for the current Node baseline. Record the Unix behavior as an unresolved migration gap or scope the current expectation to Windows until compatible Unix lock detection is implemented and tested.
AGENTS.md reference: AGENTS.md:L58-L63
Useful? React with 👍 / 👎.
1 participant
Summary
Scope
Documentation only. This PR does not change runtime code, CLI output, exit codes, error classes, or released behavior.
Validation
git diff --checknpm run web:buildThe full local
npm testwas also attempted. This Work Mode sandbox cannot runps -p <pid> -o lstart=(fatal library error, lookup self), so lock-dependent tests fail before their assertions. GitHub CI is the authoritative full-suite gate.