apache / apache/maka

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

Open
#4,452 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

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 #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 #4355 behavior and current `ArchiveRead` refs remain backward compatible.

Contributor guide

Open the contributing guide

Research direction

Start by reading ArchiveRead and the referenced #4355 and #4380 behavior, then trace how plain text, terminal or PTY streams, and structured JSON are represented. Define the canonical coordinate and response-budget ownership boundaries before changing implementation. Done means the listed operations preserve the line-facing contract, make continuation progress, and remain within the configured budget after serialization.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, testing
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.