query_engine_plugin: HTTP paging options and result.page (schema 1.1)

[jglanz]

Summary

query.execute now accepts the per-call options the C++ engine already implemented (query_options), and every result reports the page it covers, so HTTP clients page on the server instead of downloading everything.

Param	Type	Rule
limit	integral JSON number, 0 … 2^53-1	rows in this page = min(rows after offset, SQL LIMIT, limit); 0 returns no rows (columns and page still present); the page is still capped by query-max-result-rows (QUERY_LIMIT, never truncated)
offset	integral JSON number, 0 … 2^53-1	rows skipped after complete evaluation and ordering — applied before the SQL LIMIT, which acts as a page-size cap
timeout_ms	integral JSON number, 1 … query-timeout-ms	may only lower the configured deadline, still measured from request start; above the configured value → INVALID_PARAMS with data.limit = "query-timeout-ms"

Every result carries a required page: { offset, limit, returned_rows, total_rows, has_more } (counters as decimal strings, limit string-or-null). schema_version is 1.1.

Implementation

• One exact lexical integer parser shared by id and the request integers (no host floats); the preflight records the number-vs-string token kind of each request member.
• One member scanner for the root envelope and params; the request field list is declared once in request_field.
• query_budget::apply_request_options with a single deadline helper used by the constructor too; the HTTP handler applies it once the request has parsed.
• Draft-04 schemas (shared requestInteger / unsignedDecimal definitions), new examples/request-paged.json and examples/response-paged.json, and a README Paging section.

Tests

• test_query_engine_plugin: params parsing (accepted forms incl. exponent spellings; every rejection is INVALID_PARAMS), page semantics for detail and grouped queries, offset beyond the end, limit 0, page.returned_rows == stats.returned_rows, deadline lowering (never raising) with an injected clock, schema validation of the new examples and negatives.
• test_query_engine_plugin_http: pages 1..N reassemble the full ordered output, a total above query-max-result-rows readable page by page while one unpaged request fails QUERY_LIMIT, limit above the cap fails, timeout_ms lowering yields QUERY_TIMEOUT.

./build/claude/plugins/query_engine_plugin/test/test_query_engine_plugin       → *** No errors detected
./build/claude/plugins/query_engine_plugin/test/test_query_engine_plugin_http  → *** No errors detected
ctest -R test_query_engine_plugin                                              → 100% tests passed, 0 tests failed out of 2

Consumers: the wql CLI/TUI and the desktop workbench in wire-tools-ts (feature/wql-tools-and-app) page through these options; their engine-contract test validates these schemas and examples.

🤖 Generated with Claude Code

[heifner]

Rebased onto master. The PR had been retargeted onto feature/pivot-doc-updates, the already-merged #667 branch, and every CI failure (multisig_review_test, deep_mind, savanna_misc) came from that base. The two original commits are unchanged.

Two commits on top:

• The preflight recorded every params key in a std::set before unknown names were rejected. It now records the token kind only for the four known members; a 102 KB body of distinct unknown keys goes from 3.7 ms to reject back to 1.2 ms.
• The leftover "complete for the submitted SQL" sentence in schema/README.md, the catch in submit that could not fire, the query-timeout-ms help text, and a few test gaps.

Paging with a SQL LIMIT is unchanged: the LIMIT caps the page, and total_rows and has_more describe the complete output.