docs: propose attachment read quarantine

2026-08-29 04:26:38 +00:00 · 2026-08-21 15:02:10 +08:00
parent 118f244420
commit c1bdac6939
6 changed files with 86 additions and 2 deletions
@@ -2,5 +2,5 @@
 # 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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
-2026-07-05-reconstructable-requests.md: 63146fa2d392a45543daa32ce2b00158782fddb2
-2026-07-05-reconstructable-requests.zh.md: 94c1d323be0107eb8b6072a05d1e8832ebd1fffc
+2026-07-05-reconstructable-requests.md: 3f49ba71a6b98a84b05530c900e902b0cf9f6449
+2026-07-05-reconstructable-requests.zh.md: 8eee44449140d656a669ac506057e4fa09c2f747
@@ -51,5 +51,6 @@ Like MiniCode, the conversation advances append-only and resets only when model-
 - What still costs full price at the provider is inherent and logged: compaction (its `compaction/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side.
 - `agent/pre-step` is the current-request message channel; direct inbox mutation is the eventual later-request channel.
 - Tool-result trimming needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic.
+- Unreadable referenced attachment objects still fail model requests; [automatic attachment quarantine](../../proposed/bug-fix/2026-08-20-attachment-read-quarantine.md) records the proposed recovery without weakening byte-exact reconstruction.
 - Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated.
 - Snapshot expected outputs changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths.
@@ -51,5 +51,6 @@ Status: implemented
 - 在提供方处仍需全价计算的内容是固有的且已记录的：压缩（其 `compaction/*` 事件和替换条目）、真正的提示词、工具或配置变更（reason 为 `change` 的 `request/header`），或带漂移的进程边界（不同的 `resume` 快照）。提供方自身的 reasoning-content 排除由服务端管理。
 - `agent/pre-step` 是当前请求的消息通道；直接修改 inbox 则是最终进入后续请求的通道。
 - 工具结果裁剪无需新机制：一个已记录的单条目 surface replace（`start === end`），携带同一 `callId` 下裁剪后的 `tool/result`——属压缩家族，回放正确，缓存失效由相同的压力逻辑批量处理。
+- 无法读取的被引用附件对象仍会让模型请求失败；[附件自动隔离](../../proposed/bug-fix/2026-08-20-attachment-read-quarantine.md)记录了不削弱字节精确重建的拟议恢复方案。
 - 会话日志每个循环实例增长一个 `request/header` 快照，并在真正变更时增加快照。它比 delta 编解码器更大，但相对分片密集型日志仍然很小，并只保留一种回放表示。`SESSION_FORMAT_VERSION` 保持 `0`；旧的 delta 事件被拒绝而非迁移。
 - 快照预期输出变更一次（每个 transcript（文本记录）增加其 header 事件）；写入文件系统的 fixture（测试前置数据）以规范化的撰写形式存储，工具参数使用 cwd 相对路径，因为回放只对 cwd 无关的参数路径做往返。
@@ -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 .agents/notes/proposed/bug-fix/2026-08-20-attachment-read-quarantine.md
+2026-08-20-attachment-read-quarantine.md: 28e0f26cee2ec1e257fd4d43b4edc4300e2c6f23
+2026-08-20-attachment-read-quarantine.zh.md: bdc1d580a5159edcd288552e1bde9d80ea1eafd8
@@ -0,0 +1,38 @@
+# Agent Note: Quarantine unreadable historical attachments
+
+Status: proposed
+
+English | [中文](2026-08-20-attachment-read-quarantine.zh.md)
+
+## Problem
+
+An admitted `ImageAttachmentRef` remains in durable history and therefore participates in every later request until compaction replaces it. `AttachmentStore.readImage()` fails with `ATTACHMENT_NOT_FOUND`, `ATTACHMENT_CORRUPT`, or `ATTACHMENT_READ_FAILED` when the referenced object disappears, fails integrity verification, or cannot be read. The unchanged history then makes every later model request fail on the same object, leaving the session unable to continue even though the remaining messages are usable. This is the unavailable-object case left fail-loud by [reconstructable requests](../../implemented/architecture/2026-07-05-reconstructable-requests.md).
+
+## Proposal
+
+A session-backed image-request projection records unreadable references before provider dispatch. `ATTACHMENT_NOT_FOUND` and `ATTACHMENT_CORRUPT` immediately append `attachment/quarantine`; `ATTACHMENT_READ_FAILED` receives one cancellation-aware read retry and appends the same event with a retryable reason if the retry fails. Cancellation and unclassified failures do not quarantine data.
+
+The quarantine event identifies the attachment and failure class. Projection replaces each quarantined image with deterministic text containing its display name when present, attachment-id prefix, and failure class. Later requests derive the same replacement from the log and skip `readImage()` for that reference, while the original image block remains in append-only history. A request that discovers and records a quarantine reprojects before calling the provider, so the failed read does not become a terminal model-request attempt.
+
+Explicit recovery calls `readImage()` and appends `attachment/recovered` only after digest and metadata verification succeeds. Projection then restores the original image reference. Missing or corrupt bytes are never overwritten automatically, and clearing quarantine without verification is invalid.
+
+The shared request-projection consumer owns this policy. Attachment storage continues to report exact read failures, and provider adapters do not invent independent placeholders or recovery state.
+
+## Alternatives considered
+
+- **Keep failing every request.** This preserves strict error reporting but makes an otherwise usable durable session permanently unavailable after one storage fault.
+- **Delete or rewrite the historical image block.** That loses evidence, violates append-only history, and prevents a repaired content-addressed object from restoring the original request.
+- **Catch the error independently in each adapter.** An unlogged placeholder would make replay depend on which adapter and storage state happened to be present, while duplicated policies would drift.
+- **Replace missing or corrupt bytes automatically.** The reference names verified immutable content; substituting different bytes under that identity would defeat integrity checking.
+
+## Acceptance criteria
+
+- A missing or corrupt historical image produces one durable quarantine transition and a stable placeholder; later model requests do not read that object or fail because of it.
+- A general read failure is retried once without ignoring cancellation, then follows the retryable quarantine path.
+- Restart and fork reconstruct the same quarantined request from the session log.
+- Recovery restores image projection only after the original reference passes complete read verification.
+- Package tests cover error classification, idempotent quarantine, cancellation, retry, recovery, and nested tool-result images; a keyless runnable snapshot pins the model-visible placeholder and durable events.
+
+## Risks
+
+Quarantine and recovery each change the provider prefix once. The implementation must identify the exact failing reference before recording state and must coordinate concurrent requests so duplicate failures produce one effective transition. Auxiliary calls without a live session cannot record recovery state; their failure policy remains explicit implementation scope rather than an adapter fallback.
@@ -0,0 +1,38 @@
+# Agent Note: 隔离无法读取的历史附件
+
+Status: proposed
+
+[English](2026-08-20-attachment-read-quarantine.md) | 中文
+
+## 问题
+
+已接纳的 `ImageAttachmentRef` 会留在持久历史中，因此在被压缩替换前都会参与之后的每次请求。引用对象丢失、完整性校验失败或无法读取时，`AttachmentStore.readImage()` 会返回 `ATTACHMENT_NOT_FOUND`、`ATTACHMENT_CORRUPT` 或 `ATTACHMENT_READ_FAILED`。未变化的历史随后会让之后每次模型请求在同一对象上失败，使会话无法继续，即使其余消息仍可使用。这是[可重建请求](../../implemented/architecture/2026-07-05-reconstructable-requests.md)保留为明确失败的对象不可用情况。
+
+## 提案
+
+由会话支撑的图片请求投影在分派给提供方之前记录无法读取的引用。`ATTACHMENT_NOT_FOUND` 和 `ATTACHMENT_CORRUPT` 立即追加 `attachment/quarantine`；`ATTACHMENT_READ_FAILED` 先执行一次服从取消信号的读取重试，重试仍失败时追加同一事件并标记为可重试原因。取消和未分类失败不会隔离数据。
+
+隔离事件标识附件和失败类别。投影把每张已隔离图片替换为确定性文本，包含可用时的显示名称、附件 ID 前缀和失败类别。之后的请求从日志派生相同替换结果，并跳过该引用的 `readImage()`，原始图片块仍留在仅追加历史中。请求发现并记录隔离后，会在调用提供方前重新投影，因此读取失败不会成为终止性的模型请求尝试。
+
+显式恢复会调用 `readImage()`，且仅在内容摘要和元数据校验成功后追加 `attachment/recovered`。投影随后恢复原始图片引用。系统绝不会自动覆盖丢失或损坏的字节，也不允许未经验证就清除隔离。
+
+共享请求投影消费方拥有这项策略。附件存储继续报告准确的读取失败，提供方适配器不会各自生成占位或恢复状态。
+
+## 考虑过的替代方案
+
+- **让每次请求继续失败。** 这保留了严格错误报告，但一次存储故障会让其他部分仍可使用的持久会话永久不可用。
+- **删除或重写历史图片块。** 这会丢失证据、违反仅追加历史，并使修复后的内容寻址对象无法恢复原始请求。
+- **由每个适配器分别捕获错误。** 未记录的占位会让回放取决于当时存在的适配器和存储状态，重复策略也会发生偏差。
+- **自动替换丢失或损坏的字节。** 引用标识经过验证的不可变内容；在该身份下替换成其他字节会破坏完整性校验。
+
+## 接受标准
+
+- 缺失或损坏的历史图片产生一次持久隔离转换和稳定占位；之后的模型请求不再读取该对象，也不会因它失败。
+- 一般读取失败会在服从取消信号的前提下重试一次，随后进入可重试隔离路径。
+- 重启和 fork 后会从会话日志重建相同的隔离请求。
+- 仅在原始引用通过完整读取校验后，恢复操作才恢复图片投影。
+- 包测试覆盖错误分类、幂等隔离、取消、重试、恢复和嵌套工具结果图片；一个无需密钥的可运行快照钉住模型可见占位和持久事件。
+
+## 风险
+
+隔离和恢复各会改变一次提供方前缀。实现必须在记录状态前识别准确的失败引用，并协调并发请求，使重复失败只产生一次有效转换。没有活跃会话的辅助调用无法记录恢复状态；它们的失败策略属于明确的实现范围，不能退回到适配器自行处理。