Design: bounded query execution — kernel fix for the /v1/query OOM (LLP 0054-0057)

[philcunliffe]

What

Design docs (LLP) capturing the settled 1+2+3 kernel fix for the /v1/query OOM — hyparam/hypaware-server#9. Docs only; no code.

Unbounded ORDER BY / high-cardinality GROUP BY / COUNT(DISTINCT …) over the ~495k-row ai_gateway_messages buffer the whole scan, then collect() re-materializes it, and the daemon is OOM-killed mid-request. These docs make peak execution memory a function of a per-query budget, not the scanned row count.

Documents

• 0054 spec — bounded query execution: execution budget + threaded AbortSignal added to ExecuteSqlOptions on the public hypaware/core/query surface — explicitly distinct from the output-shaped ContextControls. Extends LLP 0015. This is the reusable budget primitive the server's LLP 0006 #result-caps V1 note named.
• 0055 decision — stream scalar/distinct aggregates via scanColumn over row-buffering (lights squirreling's dormant fast path on icebird + the core unionSources + ai-gateway's schema wrapper).
• 0056 decision — refuse over spill/truncate on budget exceed (spill = deferred follow-up; truncate is a wrong answer for aggregates).
• 0057 plan — phased implementation across hypaware / squirreling / icebird / ai-gateway, with the @ref-to-add map and a bounded_query_refusal smoke.
• 0015 — forward-ref to 0054 (Active doc — forward-ref only, no body rewrite).
• 0038 — captures the daemon-isolation todo as the defense-in-depth sibling (bounding caps the common case; isolation contains the residual).

Paired PR

Server-side placement decision (fix-in-kernel as a named extension) + the LLP 0006 forward-ref: hyparam/hypaware-server#31.

Scope note

Signal-threading is a spec requirement (no real chose-X-over-Y), so it is folded into 0054 rather than minted as its own decision. The engine-side parts (#1 signal, #3 budget in squirreling; #2 scanColumn in icebird) land as upstream PRs to those first-party hyparam packages + a pinned kernel version bump — tracked in the 0057 plan.

Validation

ref-check-equivalent: filename types match **Type:**, all inter-LLP links + Related targets resolve, new numbers unique (the only duplicate in the tree is the pre-existing 0026 collision on master, untouched here).

🤖 Generated with Claude Code