Page get_result by stored byte range without reading the whole stash (#540)

[zackbart]

Closes #540.

#546 already removed the per-page full encode the issue describes: get_result decodes only the page's base64 range. What remained was the storage read. The whole envelope lived under one key, so every page fetched the full stored value (about 1.33 million characters per 1 KB page of a 1 MB result), which documentation/meta-tools.md admitted in as many words.

What changes

• A stashed result is stored as base64 chunks, one key each: 48 KiB of result text per chunk, widening past roughly 1.5 MB so a result never occupies more than 33 keys. get_result reads only the chunks a page covers.
• Measured after: about 131 thousand storage characters per page regardless of total size.
• Trailing chunks are written first, so a write that fails midway leaves no readable header, and expiry reclaims every backing key. An envelope is still one stash entry charged its total ASCII length.
• Offsets, nextOffset, totalBytes, and UTF-8 boundary alignment are unchanged. Entries stashed in the v1 single-key format and as pre-v1 raw text stay readable for the rest of their 15-minute TTL.

Trade-off

One stash write becomes up to 33. fileStorage rewrites its file per write and already reads from memory, so Node deployments pay more per stash and gain nothing on reads; Workers KV is where the read saving lands. The chunk width and key cap (RESULT_CHUNK_BYTES, RESULT_MAX_CHUNKS) are the dials.

Tests

In test/meta-tools-call.test.ts: a structural read-count test (same page against a 300 KB and a 1.2 MB result reads the same amount, within a 33-key bound), byte-exact reassembly across chunk boundaries at a page size coprime with the chunk width, and both pre-chunk formats still paging.

npm run check passes: 120 files, 3274 tests passed, 37 skipped.

🤖 Generated with Claude Code