Skip to content

Query layer: decision on the query-only WASM module (ADR 0021, M5c) - #100

Merged
speedcat merged 4 commits into
mainfrom
query-wasm
Nov 22, 2026
Merged

speedcat merged 4 commits into
mainfrom
query-wasm

Conversation

@speedcat

Copy link
Copy Markdown
Contributor

Stacked on #94 (base query-executor); retarget to main after #94 merges.

What it does

  • Adds arqlet-query-wasm, a query-only WASM module (lw_alloc, lw_free, lw_run): load a graph with its payload, query it. No layout engine. publish = false.
  • Adds arqlet-query-json, the JSON request and answer of the query operation, shared by the runtime and the module so the two cannot drift. The runtime's query now uses it and adds the content revision and the view mapping.
  • Measures the module against the engine (benchmarks/results/query-m5c-20261122.md): 1.02 MB (gzip 0.33 MB) against 7.12 MB (gzip 1.84 MB) for the engine with the query feature, wasm-size profile.
  • Records the decision in ADR 0021 (M5c: the query-only module): the crate stays; an npm package waits for a host that needs it, with the conditions to revisit.
  • Both new crates join the isolation guard (host and wasm32). Specification, changelog and CLAUDE.md updated.

Checks

  • tools/query-wasm.test.mjs runs all 40 supported cases of examples/cypher/ through the built WASM file; all give the oracle's rows. Added to CI.
  • 987 workspace tests (fast profile), the query tests in the debug profile, clippy (0 warnings), isolation guard, native = WASM parity (13 of 13).
  • Not run locally: the Rust 1.94 MSRV job (toolchain not installed; CI covers it).

Not measured

The share of arqlet-model in the module's size, and the time to load a large graph.

…021, M5c, work in progress)

arqlet-query-json holds the JSON request and answer of the query operation; the runtime uses it and adds the content revision and the view mapping. arqlet-query-wasm is a prototype module (lw_alloc, lw_free, lw_run) that holds one graph with its payload and answers queries, to measure its size against the engine's.

Signed-off-by: Benjamin Becker <hello@engtwin.dev>
Measures arqlet-query-wasm against the engine (1.02 MB, gzip 0.33 MB, against 7.12 MB, gzip 1.84 MB with the query feature), tests it against the oracle through the real WASM file (tools/query-wasm.test.mjs, in CI), and joins it and arqlet-query-json to the isolation guard. The ADR records the decision: the crate stays, an npm package waits for a host that needs it. Updates the specification, the changelog and CLAUDE.md.

Signed-off-by: Benjamin Becker <hello@engtwin.dev>
Base automatically changed from query-executor to main November 22, 2026 07:09

@speedcat speedcat left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed: mergeable from my side; CI green. Sharing the JSON answer through arqlet-query-json (runtime and module cannot drift), the size measurement (1.02 MB vs 7.12 MB) and the oracle run in CI are good.

Points, none blocking:

  1. CLAUDE.md now contradicts itself in two places: "Only wasm and the bins may touch those boundaries" and "crates/wasm: … Only adapter that targets WASM". query-wasm should be named in both.
  2. MSRV does not cover the new WASM target. The msrv job checks only -p arqlet-wasm --target wasm32-unknown-unknown (the rule from 449c97e: check the WASM adapter too); add the same line for arqlet-query-wasm. Its Cargo.toml also lacks rust-version.workspace (and the other workspace fields the crates carry).
  3. load copies the whole graph: serde_json::from_value(v["graph"].clone()) holds it twice for a moment. Owning the request and using v["graph"].take(), or reading it in one pass from the text as the engine's load_text does, avoids that; relevant to the "time to load a large graph" left unmeasured.
  4. Nit: the load answer counts unresolved edges (edges: 2), the query answer does not (graph.edges: 1). Count the same way, or name the difference (unresolved).

…b, workspace fields, load read in one pass

CLAUDE.md names query-wasm beside wasm where it says who may target WASM or touch host boundaries. The msrv job also checks arqlet-query-wasm for wasm32, and its manifest carries the workspace fields of the other crates. load is read straight from the request text into its types instead of through a JSON value of the whole request (a test shows it equals the general path), and its answer names the edges a query does not see (unresolvedEdges) so the two counts agree. The module grew by 6 percent with the second reading path; the sizes in the results file, the ADR, the specification and the changelog are measured again.

Signed-off-by: Benjamin Becker <hello@engtwin.dev>
@speedcat

Copy link
Copy Markdown
Contributor Author

Thanks, all four points taken (7cea020):

  1. CLAUDE.md names query-wasm in both places (the crate list and the rule on who may touch host boundaries).
  2. The msrv job also runs cargo +1.94.0 check -p arqlet-query-wasm --target wasm32-unknown-unknown --locked; the manifest carries authors, repository, homepage and rust-version from the workspace. I could not run the 1.94 job locally (toolchain not installed); CI will.
  3. load is read straight from the request text into its types, so the graph is not held as a JSON value beside the graph; anything that path refuses falls back to the general one with the same errors. A test checks both paths give the same answers. I did not measure the peak memory or the load time, so the "time to load a large graph" stays unmeasured. The second reading path made the module 6 % larger (1 082 903 B, gzip 344 983 B); the sizes in the results file, the ADR, the specification and the changelog are corrected.
  4. load now answers unresolvedEdges: edges counts the graph as given, so a query's graph.edges equals edges - unresolvedEdges. Documented in the module and checked in the WASM test.

@speedcat
speedcat merged commit b4c7c8c into main Nov 22, 2026
8 checks passed
@speedcat
speedcat deleted the query-wasm branch November 22, 2026 08:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant