feat(trilean-sql): compile a real SQLite dialect alongside PostgreSQL

[Mearman]

Adds a real SQLite dialect to trilean-sql, so SqlCompileOptions.dialect becomes "postgres" | "sqlite" rather than a single literal. D1 is SQLite, which is the domain that motivated this package existing, so this is the second dialect the field's doc comment was always anticipating.

What actually differs between the two

Three things, and nothing else, which is why this is a small DialectConfig record in options.ts rather than a module per dialect or a Dialect interface with a method per node kind:

• matches/notMatches emit REGEXP/NOT REGEXP instead of ~/!~
• placeholders are a bare ? instead of $N::type — SQLite binds by position in emission order and has no type to cast to
• the bare NULL in an empty memberOf loses its ::boolean annotation, since SQLite has no boolean type to annotate

Everything else the compiler emits is ANSI-standard and identical in both engines: the connectives, the six comparison operators, =/<>, IN/NOT IN, IS NOT NULL, and double-quoted identifiers with an embedded quote doubled. Branching anywhere else would be a branch that can never change the output.

PostgreSQL's compiled output is unchanged, byte for byte. Beyond the existing unit assertions (which assert exact SQL text) and the existing container-backed postgres.test.ts still passing untouched, this was checked differentially: 40,000 randomly generated trees compiled through main's built dist and this branch's, comparing both the compiled {sql, params} and every findUnpushableNodeKind result, with and without options — 80,000 comparisons, zero differences.

Why the guard refuses the same set for both

The refusal set carries over from PostgreSQL unchanged in structure, and that inheritance is the part that needed evidence rather than assertion — it would be worth nothing if SQLite happened to agree with trilean where PostgreSQL does not. Each one was measured against a real better-sqlite3 connection, and test/integration/sqlite.test.ts keeps measuring it:

• Text under compare. A TEXT-affinity column compared against the number 5 is compared as text: '9' > 5 is true, '10' > 5 is not. SQLite's coercion is worse here than PostgreSQL's, not better — no error, no warning, just the wrong rows.
• Ordered booleans. SQLite stores them as the integers 0 and 1 and orders them as integers, so gt answers definitely where trilean has no ordering at all.
• Cross-kind comparison. 'abc' > 5, with no column or affinity involved, answers true rather than erroring.
• NaN — the same refusal for a genuinely different reason. SQLite has no NaN, and a driver binding one substitutes SQL NULL: typeof(?) bound with NaN answers 'null', and NaN = NaN is therefore indeterminate rather than definitely false. That looks like agreement until you negate it, at which point trilean's definite true matches every row and SQLite's NULL still matches none. So the SQLite refusal carries its own wording rather than PostgreSQL's "NaN is equal to itself and greater than every other double", which would be simply false about SQLite.

The refusal structure is shared: guard.ts keeps one walk and one refusal per divergence, parameterised by a DialectDivergence record supplying only the reason text. There is no second copy of the walk.

Infinities are still deliberately not refused, and that was checked rather than assumed: better-sqlite3 binds them as real, Inf = Inf is 1, and ordering against finite values matches trilean's.

What a SQLite caller has to supply

Two things, both of which fail loudly rather than silently, and both documented in the README:

• A REGEXP function, if the tree uses matches/notMatches. SQLite reserves REGEXP as syntax for a regexp(pattern, value) function it does not itself provide. An unregistered one is a query error — no such function: REGEXP — never a fragment that quietly matches nothing, which is what makes leaving it to the caller acceptable rather than a hole in the guarantee. The README gives the concrete db.function("regexp", ...) registration, including the two load-bearing details: return null for a NULL argument (SQLite does not propagate NULL through a user function on its own, and one answering 0 would make NOT REGEXP true for a row whose value is unknown — exactly the two-valued collapse this package exists to avoid), and return 1/0 rather than a JS boolean, which better-sqlite3 rejects from a user function.
• Booleans bound as 0/1. params carries the tree's own literals unchanged in every dialect, and better-sqlite3 rejects a JS boolean outright.

Instants are the caveat to be deliberate about: SQLite has no timestamp type, so an instantLiteral is compared as text. Offset-bearing ISO-8601 in a single common offset sorts chronologically and compares correctly; mixed offsets do not. This is the SQLite counterpart of the existing PostgreSQL session-time-zone caveat, and the same advice ("pass offset-bearing ISO-8601") resolves both.

One fix on top of the dialect work

bbb4b58 fixes a defect the dialect dispatch introduced. Both entry points index a per-dialect table with options.dialect and neither checked the dialect has an entry, so a name outside the union — unreachable from TypeScript source naming a dialect literally, but entirely reachable from a dialect read from configuration and asserted into the union at the boundary — surfaced as TypeError: Cannot read properties of undefined (reading 'matches') from compilePredicateNode, and, worse, as the answer undefined from findUnpushableNodeKind for a tree the compiler then failed on. Reporting a tree as pushable is a promise that it will compile; under a dialect that does not exist it cannot. Both now refuse by name with UnknownDialectError, which carries the offending name and the implemented ones and takes its list from DIALECT_CONFIG's own keys, so implementing a dialect cannot leave the check behind. Before this branch there was nothing to get wrong here — main ignored the field entirely — so it is a regression this branch introduced rather than a pre-existing gap.

Out of scope, deliberately

No third dialect. No ORDER BY/JOIN/collection-quantifier support — some/every/fold stay refused for both. No bundled or auto-registered regexp function; that stays the caller's documented responsibility.

Verification

Run from a clean clone of this branch, not from cached state:

• pnpm build, pnpm typecheck, pnpm lint clean
• pnpm test — 89 unit tests in trilean-sql (the pre-existing PostgreSQL string assertions untouched and passing), 444 in trilean
• pnpm test:integration — 42 in trilean-sql: postgres.test.ts unchanged and green against a real container, sqlite.test.ts green in memory
• the differential main-vs-branch PostgreSQL comparison described above
• a randomised parity fuzz outside the test suite: 3,000 generated trees compiled for SQLite, executed as real WHERE clauses against a seeded better-sqlite3 table, and compared row for row against evaluatePredicate over the same rows — zero disagreements
• injection re-checked by execution rather than string assertion: a hostile value stays a bound parameter, and a hostile columnFor name (both an OR-injection and a statement-break attempt) becomes one quoted identifier the engine rejects as missing, with the table still standing

.tool-versions pins Node 22, which is what CI uses, so better-sqlite3 resolves a prebuilt binary rather than compiling from source. Its install script is allowed in pnpm-workspace.yaml for that reason — it is a native addon, and refusing the script would leave the package installed and unloadable.

[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-03T15:38:47.622518Z	bbb4b58	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.

[github-actions]

🎉 This PR is included in version 1.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀