refactor(runtime): unify ArchiveRead canonical document and response-budget ownership

[liugddx]

Part of #4267. Follow-up to #4355 and #4380.

Motivation

The ArchiveRead retrieval work in #4380 fixes the immediate correctness failures (non-advancing line pagination, Unicode search coordinates, and inspect response overflow), but the review also exposed a structural issue: coordinate semantics and response-budget fitting are currently implemented by several independent branches.

The follow-up should make the invariants explicit without expanding #4380 or breaking its line-facing contract.

Proposed scope

• Introduce one canonical archive-document projection for plain text, terminal pipes, PTY streams, and structured JSON.
• Make internal read/search coordinates derive from that document authority.
• Keep the public unit: "line" / line-offset facade from harness: ArchiveRead search / line reads / section index ergonomics (item 3 of #4267) #4355 while allowing the implementation to use character ranges internally.
• Introduce one field-aware fitArchiveResponse() owner for the final TOOL_RESULT_ARCHIVE_MAX_RESPONSE_CHARS envelope across inspect, read, query, and search.
• Optimize line reads so large windows do not repeatedly materialize and stringify the same content.
• Define the coordinate/ref contract for queryable items[] subdocuments.
• Add operation × payload-shape regression/property tests for the response-size invariant and continuation progress.

Non-goals

• Do not change the shell capture/preservation contract or recover output already dropped before archiving.
• Do not reopen archive threshold policy.
• Do not remove or silently change the line-oriented API in the first iteration.

Acceptance

• Every successful and failure ArchiveRead response stays within the configured response budget after final serialization.
• Search offsets, snippets, and continuations are in the documented canonical coordinate space.
• Line reads either return progress or an actionable bounded failure for an oversized line.
• Long accepted search patterns remain representable without silent truncation.
• Existing harness: ArchiveRead search / line reads / section index ergonomics (item 3 of #4267) #4355 behavior and current ArchiveRead refs remain backward compatible.

[Totoro-qaq]

take

[Totoro-qaq]

I've taken this. I plan to keep the first PR focused on internal convergence rather than expand the public ArchiveRead protocol.

Proposed scope:

• Introduce one internal archive-document projection. Root read/search coordinates remain zero-based UTF-16 offsets into the exact projected text: decoded strings, the existing pipes/PTY stream projection, or the stored structured serialization. query keeps its current item text precedence (summary, then result, then serialized item) and uses (ref, itemId) as a compound document scope.
• Route every success and failure response through one exact fitArchiveResponse() owner. It will start from the minimum valid envelope and grow fields in semantic priority order, then verify the final JSON.stringify length against the 7,500-character limit.
• Treat queryable item IDs as exact addressing tokens, not truncatable metadata. An oversized item projection should degrade to an exact ID-only entry rather than remove the only usable query target.
• Keep the public unit: "line" request/response fields, but derive line windows from the canonical document and materialize only response-budget-scale content instead of repeatedly joining and serializing the requested window.

Initial regression cases on current main:

• an oversized invalid-ref failure exceeds the response budget;
• escaped item_not_found IDs exceed the response budget;
• adversarial query metadata can leave an empty, non-advancing page;
• inspect truncates a valid 200–256 character item ID into a value that cannot be queried.

Tests will also cover operation × payload-shape response bounds, exact inspect→query reachability, monotonic char/line/search cursors, and all Unicode/oversized-line behavior retained from #4380.

Out of scope for this PR: a new item-ref URI, new public inspect fields, ArchiveRead schema or threshold changes, cross-call caching, terminal stream semantics, and code-point/grapheme coordinate changes. I will also keep the existing archive read-instruction bytes unchanged.

If maintainers want first-class item refs instead of the existing (ref, itemId) compound scope, please let me know before that public surface is introduced; otherwise I will preserve the current API and make the compound scope explicit internally and in tests.

AI disclosure: this comment was posted on my behalf by OpenAI Codex (GPT-5.6 Sol). OpenAI Codex and Claude Code (Fable 5.1) assisted with source analysis and drafting. I reviewed the proposed scope and remain the human contributor of record.

[liugddx]

Closing as superseded. #5247 (4cd71ea) removed the ArchiveRead tool entirely: archived tool results are now read through the bounded Read tool with a Maka resource path, and page budgeting has a single owner in packages/runtime/src/read-page.ts. The inspect/query/search coordinate and fitArchiveResponse() unification proposed here therefore no longer has a surface to apply to. @Totoro-qaq thanks for the detailed plan; if a budget or coordinate gap shows up in the new bounded Read path, please open a fresh issue against it.