[jnsdls]

Summary

Follow-up to #39/#40. Upstream 1.11.3 normalizes ASTs at every builder step, which made the query path slower. This wins it back on the query endpoint, mostly by not doing the same work twice for a query the builder already interned.

 handle_query_request
   handler(name, args)            # interned query, often the same object as last time
-  map_ast(query.ast, mapper)
+  mapped_ast(query, mapper)      # kept on the Query, keyed by mapper identity
 starlette /query
-  js_stringify_bytes(response.to_json())          # orjson, then _may_differ scans ~200 KB
+  query_response_bytes(response)
+    QuerySuccess.to_json_bytes()
+      TransformedQuery.to_json_bytes()
+        AST.to_json_bytes()      # js_stringify_bytes(to_json()) once, kept on the AST
 js_stringify_bytes._may_differ
-  10 substring scans, one per digit, for an array-index key
+  digits deleted with translate, one scan for '"":'
 builder
-  _derive(("related_base"/"exists_base", rel), lambda: ...)
+  _find, then _keep only on a miss (no closure per call)
+  _condition_key: column-vs-scalar condition keyed as one flat tuple

ASTs are already immutable by contract (ast.py: "no code changes a node once built"), so caching their mapped form and their text is safe. AST._text is a compare=False, init=False slot and is reset in _copy.

Evidence

Wall clock, python -m bench, same machine, this branch against main (ca665da):

case	main	this PR	Py/TS main	Py/TS now
query.simple.b1	6.9 µs	5.2 µs	1.71	1.26
query.simple.b100	541.5 µs	388.0 µs	2.96	2.15
query.complex.b1	31.9 µs	20.3 µs	3.12	1.97
query.complex.b100	2.86 ms	1.81 ms	3.94	2.33
query_json.simple.b1	15.4 µs	8.0 µs	2.56	1.34
query_json.simple.b100	1.05 ms	543.8 µs	3.53	1.64
query_json.complex.b1	68.8 µs	23.5 µs	3.82	1.31
query_json.complex.b100	6.14 ms	2.05 ms	4.63	1.57
build.complex	14.6 µs	13.7 µs	6.54	5.68
mutate_cpu.put.n1	16.3 µs	14.6 µs	4.63	3.84
parse, parse_json, map, z2s				unchanged (noise)

query_json now times query_response_bytes, which is what the Starlette route sends.

• New differential assertion in test_queries_match_upstream: query_response_bytes(actual) == JSON.stringify(upstream response), byte for byte, over the Hypothesis program corpus (floats, surrogates, errors, userID set/unset).
• uv run pytest: 784 passed, 100% coverage. python -m tests.compat: 54 upstream modules, every port module fully exercised. ruff, ty clean.

The caches pay off when a query repeats (same name, same args), which interning already makes the common case. A query with args that vary per request still maps and stringifies once per distinct query.

Merge Danger

Door: two-way

Blast Radius: query endpoint

Response bytes are unchanged (proven against upstream). Mapped ASTs are now shared between responses for the same interned query, so code that mutates a returned AST would corrupt later responses. Nothing in the SDK does that.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[codspeed]

Merging this PR will improve performance by 48.68%

1 warning

⚠️ Base and head ran on different runner types

Some benchmarks with significant performance changes were compared across different runner types, so the changes might not come from the code. Run base and head on the same runner type, or use CodSpeed Macro Runners for more stable results.

Learn more about Macro Runners

Open the report in CodSpeed to investigate

⚡ 9 improved benchmarks
✅ 37 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_cpu[query_json.complex.b100]	127.2 ms	58.1 ms	×2.2
⚡	test_cpu[query_json.complex.b1]	1,666.7 µs	879.5 µs	+89.5%
⚡	test_cpu[query_json.simple.b100]	25.5 ms	16.2 ms	+57.14%
⚡	test_cpu[query.complex.b100]	72.9 ms	49.7 ms	+46.67%
⚡	test_cpu[query_json.simple.b1]	611.2 µs	438.3 µs	+39.46%
⚡	test_cpu[query.simple.b100]	15.2 ms	11.1 ms	+37.14%
⚡	test_cpu[query.complex.b1]	1,009.6 µs	763.9 µs	+32.17%
⚡	test_cpu[parse_json.transform.q1000]	67.2 ms	55.1 ms	+22.13%
⚡	test_cpu[query.simple.b1]	408.9 µs	339.7 µs	+20.38%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing perf/query-response-text (76c471d) with main (ca665da)}