Add trilean-sql: compile a predicate tree to a parameterised PostgreSQL WHERE fragment

[Mearman]

Stacked on #13 — base is refactor/monorepo-restructure, not main, since this adds a second workspace package and needs the workspace layout that PR introduces. Review/merge #13 first.

What this adds

packages/trilean-sql: takes a trilean PredicateNode and returns { sql, params } — a self-contained parameterised boolean expression you can drop into a WHERE, HAVING, CHECK, or a partial index predicate. The point is to let the database apply a rule across a whole table rather than fetching every row and evaluating the tree once per row.

The three-valued logic isn't reimplemented on top of SQL. PostgreSQL's AND/OR/NOT over TRUE/FALSE/NULL are Kleene's strong tables, which are the tables trilean's own connectives implement, and a comparison against a NULL column yields NULL exactly where the evaluator returns indeterminate from an unresolved reference. A row dropped by WHERE because its condition was unknown is dropped for the same reason a subject the evaluator declines to judge is not accepted. No indeterminacy column, no sentinel, no CASE scaffolding.

Two entry points: compilePredicateNode(node, options), and findUnpushableNodeKind(node, options?) for callers that want to choose between pushdown and in-process evaluation without provoking an exception.

Refusal, not degradation

The guard is an allow-list walk, so a node kind added to trilean later is refused by default rather than falling through to whatever branch happened to be last. some, every, fold, lookup, call, delegate, treeReference, conditional, accumulator, arithmetic, negate, durationLiteral, complexLiteral all throw UnsupportedNodeError with the offending node's real path. There is no best-effort fragment and no silently dropped conjunct — the failure mode where an unbacked kind quietly compiles to nothing, leaving a WHERE clause more permissive than the tree it claims to stand for, is the specific thing this design exists to prevent.

Testing

The unit suite asserts compiled SQL text and parameter arrays. That can't establish anything about three-valued behaviour on its own: ("age" > $1) is only indeterminate-preserving because of what PostgreSQL's planner does with a NULL age, which is a fact about PostgreSQL rather than about the string.

So the integration suite starts a real PostgreSQL container, seeds a table carrying real NULLs, and for every case executes the compiled fragment as a WHERE clause and runs the same tree through evaluatePredicate once per row, asserting the two agree on which rows match and which don't. Agreement on absence matters as much as presence — the case that separates three-valued from two-valued logic is the row appearing in neither a predicate nor its negation. Needs Docker; it's a separate vitest project and a separate CI job for that reason.

One real divergence found and fixed while verifying

NaN. trilean compares numbers with ===, under which NaN equals nothing including itself, so a tree comparing NaN matches no subject at all. PostgreSQL defines NaN as equal to itself and greater than every other double, so the same tree compiled to SQL selected every row — a silent, total inversion. Measured against a real server, then refused in the guard, with the integration test asserting both halves (that it's refused, and that PostgreSQL really does answer NaN = NaN as TRUE, which is what makes refusing it right). Infinities are deliberately not refused alongside it — both engines order them identically.

It's reachable despite NumberLiteralNodeSchema rejecting NaN, because the compiler takes the inferred PredicateNode type and TypeScript's number includes NaN; a tree built in code rather than parsed never meets that schema.

Two limits the docs now state explicitly

The "compiles to SQL that agrees row for row, or throws" guarantee is about the tree's structure. Two things sit outside it, both properties of a string operand's content rather than of any node kind, so neither is reachable by a walk over kinds:

• A matches/notMatches pattern is matched by the server in PostgreSQL's regular-expression language, not ECMAScript's. Measured: \bada\b matches "ada" in ECMAScript and nothing in PostgreSQL (where \b is a backspace); [[:alpha:]]+ matches every name in PostgreSQL and none in ECMAScript. The Regular expressions section already described the hazard — the Refusal section now says that's where the guarantee stops.
• An instantLiteral is parsed by PostgreSQL rather than by Date, so one carrying no UTC offset is read in the database session's time zone where trilean reads it in the Node process's, and one PostgreSQL can't parse raises a query error at execution time rather than UnsupportedNodeError. Pass offset-bearing ISO-8601.

Scope

PostgreSQL only, and options.dialect is the string literal "postgres" rather than a defaulted field, so a second dialect would be a new value there rather than a change of behaviour for callers who never said which one they meant. Nothing claims SQLite, D1, or MySQL support.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-03T11:28:56.884751Z	b2705b3	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.