@rindle/query-compiler

Compiles a Rindle query Ast into one SQL SELECT whose single column "rindle_result" is the entire nested result tree as JSON — the server-side realization of 203-MUTATOR-READS-DESIGN.md Phase 2, specified in POSTGRES-READ-COMPILER-DESIGN.md.

A server mutator runs the compiled SELECT on its already-open Postgres transaction, so it reads its own uncommitted writes for free (read-your-writes). Compilation is a pure function of (Ast, Catalog) — no database round-trip to plan a read, only to run it.

compile(ast, catalog, { dialect: "postgres" })  →  { sql, params }

Site docs — the mutator reads (yield tx.query) this compiler serves: rindle.sh/docs/mutators · for agents: llms.txt

Design shape

• Port. The walker skeleton is ported from rindle-d2s (rust/rindle-d2s/, the SQLite AST→SELECT compiler that matches our exact Ast and shares complete_ordering with the engine's builder). The Postgres leaves and the ::text::<type> cast strategy are ported from mono's z2s. rindle-d2s stays the differential oracle (§9), never a runtime dep.
• Two dialects, one product. postgres is the product target. sqlite exists only as the offline oracle: it lets the whole walker be proven end-to-end against Node's built-in node:sqlite with zero infrastructure. It is never wired to a product consumer.
• Driver-free. Emits { sql, params } and imports no Postgres driver — the app's driver runs it through the plugger seam (Invariant 7).
• The catalog (src/catalog.ts) carries column order, primary key, relationship cardinality, and per-column native type detail ({ type, isEnum, isArray }) for the cast switch. It is a pure input — the compiler never touches a database. Hand-authored for tests. Where it comes from in production for the Postgres dialect is not yet settled in code: designs/416-POSTGRES-READ-CATALOG-DESIGN.md specifies one published Rindle-owned row read over the mutator's open transaction, superseding §7's static artifact. Until that ships, tx.query on postgresBackend refuses rather than compiling against a stub — a stub catalog compiles cleanly and returns wrong rows.

Status

Both dialects compile. The sqlite dialect is wired and drives the daemon backend's session reads (packages/api-server/src/index.ts). The postgres dialect is not yet wired to a consumer: tx.query on postgresBackend refuses until design 416 supplies the column-type catalog (above).

Its SQL is pinned offline by golden tests (test/golden-pg.test.ts) and by the read-parity battery (test/parity-battery-pg.test.ts), which prove that every query in the battery lowers for Postgres and carries the ordering the engine implies. But the only dialect whose output is executed in tests is sqlite (the node:sqlite oracle, which is what proves the shared walker). Execution parity against a live Postgres is still owed.

Test

pnpm --filter @rindle/query-compiler test   # tsc --noEmit + node --test (node:sqlite oracle)