Epic: Rust query engine (cldk-query-core) — deferred fluent API core (SDK surface, no schema change)

[rahlk]

SUMMARY

Incubate a DataFusion-inspired, deferred, fluent query engine inside python-sdk, implemented as a Python-independent Rust crate (cldk-query-core) with a PyO3 adapter (cldk-python). Implements the semantics of the fluent-query-core design (#212, Epic B #155) on a Rust core per the incubation RFC. No schema-v2 change — the engine consumes schema 2.0.0 (analysis.json, emitted Neo4j graphs). One new contract is introduced: the versioned LogicalPlan wire format (PlanEnvelope, semver string).

AFFECTED REPOS (from Contract-Impact Triage)

• python-sdk — Rust workspace (root crates/{cldk-query-core,cldk-python}, workspace Cargo.toml at repo root) + fluent facade (cldk/query/) — cldk-sdk-frontend
• python-sdk — packaging/release overhaul (fat maturin wheel) — finishing-cldk-work
• docs — query-API guide + reference — finishing-cldk-work

DESIGN DECISIONS (locked with the user; recorded in .claude/FACADE_DECISIONS.md and docs spec 2026-07-21)

• M1 scope: Epic B success criteria — the two Odoo PoE audit queries, single-language, in-memory + Neo4j, .explain() reproduces the manual audit evidence.
• Identity: can:// is canonical (07-09 spec's cldk:// amended); no parallel service:///proto:// schemes.
• Plan algebra: redesigned fresh via an algebra ADR (inputs: 07-09 six primitives + RFC LogicalOp sketch), locked before the core builds.
• Data plane: core reads schema-2.0.0 analysis.json natively (serde CPG models) and speaks Bolt (neo4rs); cargo-only core tests on fixture JSONs.
• Opaque(fn): plan-split — Rust prefix → URIs → Python lambda → re-enter Rust; explain() marks the split.
• Packaging: fat wheel — cldk becomes a maturin/PyO3 abi3 platform wheel (accepted: not pure-Python anymore; release build matrix; sdist needs a Rust toolchain).
• L3/L4: the Rust core replaces the cldk.graph slice engine (F7: L3/L4 consumption API — shared program-slice engine + five facade verbs (slice/flows/def-use) #270/feat(graph): L3/L4 program-slice engine core (Tasks 1–6 of #270) #271); deprecation gated on exact-set gate parity.
• Extraction boundary: no PyO3 in core; language-neutral results; versioned PlanEnvelope; extract only when independently consumed/released.
• Scope guard: Epic-E cross-service model (service topology, gRPC/proto contracts, across_services(), Go analyzer) is OUT — it is schema-v2 evolution across analyzers and enters designing-cldk-changes separately. The RFC's boutique examples are the north star, not this epic.

CHILDREN (one per rung/PR-unit; checklist updated as they land)

• Rust query engine M1 (algebra ADR → core crate → PyO3 adapter + fluent facade → backends → M1 gate) — python-sdk#280
• Rust slicer replaces cldk.graph (post-M1) — python-sdk#281
• Fat-wheel packaging + release build matrix + verify — python-sdk#282
• docs: fluent query API guide — docs#10

DEFINITION OF DONE (epic-level)

• Every child PR merged and its gate green.
• The two Odoo PoE audit queries run end-to-end on both backends; .explain() output reproduces the manual audit evidence; identical results in-memory vs Neo4j.
• cargo test passes in cldk-query-core with no Python interpreter; serialized plans round-trip independent of Python fluent objects.
• SDK public accessor API unchanged; the fluent API ships additively.
• cldk.graph slicer deprecation only after Rust slicer passes the same exact-set gates.
• Docs / CHANGELOG updated; wheel matrix publishes for all supported platforms.