|
| 1 | +# Facade decisions — python-sdk |
| 2 | + |
| 3 | +Decision log for SDK-surface design (per designing-cldk-changes, sdk-facade-design-loop). |
| 4 | +One line per locked decision; newest section first. |
| 5 | + |
| 6 | +## 2026-07-21 — Rust query engine (fluent API core) |
| 7 | + |
| 8 | +- **M1 scope:** Epic B success criteria — the two Odoo PoE audit queries (#155), single-language, |
| 9 | + in-memory + Neo4j backends, `.explain()` reproduces the manual audit evidence. Cross-service |
| 10 | + (services/gRPC/proto, the RFC's boutique examples) is Epic E, out of scope; requires an |
| 11 | + analyzer-side schema design that has not happened. |
| 12 | +- **Identity scheme:** `can://` (what analyzers emit today), extended as needed. The 2026-07-09 |
| 13 | + fluent-query spec's `cldk://` is amended to `can://`; no parallel `service://`/`proto://` |
| 14 | + schemes — Epic E extends the `can://` grammar instead. |
| 15 | +- **Plan algebra:** redesigned fresh, taking the 2026-07-09 spec's six primitives |
| 16 | + (Descend/Ascend/Relate/Filter/PathQuery/Project) and the RFC's LogicalOp sketch as inputs. |
| 17 | + Deliverable: an algebra ADR locked before the Rust core builds. |
| 18 | +- **Data plane:** `cldk-query-core` consumes schema-2.0.0 `analysis.json` natively (serde CPG |
| 19 | + models) AND speaks Bolt directly (neo4rs) for the Neo4j backend. Core tests are cargo-only on |
| 20 | + fixture JSONs; no Python in the core. |
| 21 | +- **Opaque(fn):** plan-split semantics — Rust executes the prefix, returns URIs, Python applies |
| 22 | + the lambda, execution re-enters Rust for remaining steps; `explain()` marks the split point. |
| 23 | +- **Packaging:** fat wheel — `cldk` itself becomes a maturin/PyO3 platform wheel (abi3). |
| 24 | + Consequence accepted: `cldk` is no longer pure-Python; release workflow becomes a per-platform |
| 25 | + build matrix; platforms without a prebuilt wheel need a Rust toolchain for the sdist. |
| 26 | +- **L3/L4 slicer:** the Rust core REPLACES the `cldk.graph` slice engine (#270/#271); the Python |
| 27 | + engine is deprecated once the Rust slicer passes the same exact-set gates. Single dataflow |
| 28 | + semantics owner; replacement staged post-M1. |
| 29 | +- **Extraction boundary:** no PyO3 types/exceptions/callbacks in `cldk-query-core`; versioned |
| 30 | + `PlanEnvelope` wire format (semver string, house convention, not u32); language-neutral result |
| 31 | + structs; extraction only when independently consumed/released (per RFC criteria). |
| 32 | +- **Repo layout (amends the RFC's `rust/crates/` sketch):** root-level `crates/` with the |
| 33 | + workspace `Cargo.toml` at the repo root (polars/ruff idiom; canonical Cargo layout, zero-config |
| 34 | + rust-analyzer, maturin driven from the root pyproject via |
| 35 | + `tool.maturin.manifest-path = "crates/cldk-python/Cargo.toml"`). The extension module compiles |
| 36 | + to the private submodule `cldk._native` — users import `cldk.query`; the public namespace never |
| 37 | + admits Rust exists. Crate names unchanged: `cldk-query-core` (survives extraction), |
| 38 | + `cldk-python` (bindings). |
0 commit comments