@quereus/quereus 4.20.1 → 4.20.2

package/test/logic/11.1-join-using.sqllogic

@@ -0,0 +1,267 @@
+-- adapted from SQLite test/join.test, joinB.test, joinH.test
+-- USING clause: Quereus parses USING as an equi-join shortcut but does NOT merge
+-- the shared column into a single output projection (SQLite-specific semantics).
+-- Tests qualify all column references; an unqualified shared name is ambiguous.
+
+create table u_a (id integer primary key, k integer, va text);
+create table u_b (id integer primary key, k integer, vb text);
+
+insert into u_a values (1, 100, 'a1'), (2, 200, 'a2'), (3, 300, 'a3');
+insert into u_b values (10, 100, 'b1'), (20, 200, 'b2'), (40, 999, 'b4');
+
+-- Single-column USING: filters on shared key; both tables' columns remain selectable
+select u_a.id as aid, u_a.k as ak, va, u_b.id as bid, u_b.k as bk, vb from u_a join u_b using (k) order by u_a.id;
+→ [{"aid":1,"ak":100,"va":"a1","bid":10,"bk":100,"vb":"b1"},{"aid":2,"ak":200,"va":"a2","bid":20,"bk":200,"vb":"b2"}]
+
+-- Unqualified shared-key reference is ambiguous (SQLite would merge USING column;
+-- Quereus does not).
+select k, va, vb from u_a join u_b using (k) order by u_a.id;
+-- error: ambiguous column name: k
+
+-- select * over a USING join exposes both sides' columns with `:N` disambiguation
+-- (matches the same shape as `inner join ... on u_a.k = u_b.k`).
+select * from u_a join u_b using (k) order by u_a.id;
+→ [{"id":1,"k":100,"va":"a1","id:1":10,"k:1":100,"vb":"b1"},{"id":2,"k":200,"va":"a2","id:1":20,"k:1":200,"vb":"b2"}]
+
+-- LEFT JOIN with USING preserves left rows; right side is null on miss
+select u_a.id as aid, u_a.k as ak, u_b.id as bid, vb from u_a left join u_b using (k) order by u_a.id;
+→ [{"aid":1,"ak":100,"bid":10,"vb":"b1"},{"aid":2,"ak":200,"bid":20,"vb":"b2"},{"aid":3,"ak":300,"bid":null,"vb":null}]
+
+-- select * over a LEFT JOIN ... USING also disambiguates and keeps unmatched right side as nulls.
+select * from u_a left join u_b using (k) order by u_a.id;
+→ [{"id":1,"k":100,"va":"a1","id:1":10,"k:1":100,"vb":"b1"},{"id":2,"k":200,"va":"a2","id:1":20,"k:1":200,"vb":"b2"},{"id":3,"k":300,"va":"a3","id:1":null,"k:1":null,"vb":null}]
+
+drop table u_a;
+drop table u_b;
+-- run
+
+-- Multi-column USING (a, b): both keys must match
+create table mu_l (a integer, b integer, vl text, primary key (a, b));
+create table mu_r (a integer, b integer, vr text, primary key (a, b));
+
+insert into mu_l values (1, 10, 'l1'), (2, 20, 'l2'), (3, 10, 'l3');
+insert into mu_r values (1, 10, 'r1'), (2, 30, 'r2'), (3, 10, 'r3');
+
+-- Inner USING join on (a, b) with qualified references
+select mu_l.a as la, mu_l.b as lb, vl, vr from mu_l join mu_r using (a, b) order by mu_l.a, mu_l.b;
+→ [{"la":1,"lb":10,"vl":"l1","vr":"r1"},{"la":3,"lb":10,"vl":"l3","vr":"r3"}]
+
+-- LEFT JOIN with multi-column USING
+select mu_l.a as la, mu_l.b as lb, vl, vr from mu_l left join mu_r using (a, b) order by mu_l.a, mu_l.b;
+→ [{"la":1,"lb":10,"vl":"l1","vr":"r1"},{"la":2,"lb":20,"vl":"l2","vr":null},{"la":3,"lb":10,"vl":"l3","vr":"r3"}]
+
+drop table mu_l;
+drop table mu_r;
+-- run
+
+-- USING with TEXT keys uses default binary collation
+create table cu_a (id integer primary key, name text);
+create table cu_b (id integer primary key, name text);
+
+insert into cu_a values (1, 'alice'), (2, 'BOB'), (3, 'carol');
+insert into cu_b values (10, 'alice'), (20, 'bob'), (30, 'carol');
+
+-- Default binary collation: 'BOB' != 'bob'
+select cu_a.id as aid, cu_a.name as aname, cu_b.id as bid from cu_a join cu_b using (name) order by cu_a.id;
+→ [{"aid":1,"aname":"alice","bid":10},{"aid":3,"aname":"carol","bid":30}]
+
+drop table cu_a;
+drop table cu_b;
+
+-- USING with COLLATE NOCASE TEXT keys folds case: the join honors the columns'
+-- collation, so 'BOB' matches 'bob'
+-- (unique-collation-name-case-insensitive-normalization).
+create table cn_a (id integer primary key, name text collate nocase);
+create table cn_b (id integer primary key, name text collate nocase);
+
+insert into cn_a values (1, 'alice'), (2, 'BOB'), (3, 'carol');
+insert into cn_b values (10, 'alice'), (20, 'bob'), (30, 'carol');
+
+select cn_a.id as aid, cn_a.name as aname, cn_b.id as bid from cn_a join cn_b using (name) order by cn_a.id;
+→ [{"aid":1,"aname":"alice","bid":10},{"aid":2,"aname":"BOB","bid":20},{"aid":3,"aname":"carol","bid":30}]
+
+drop table cn_a;
+drop table cn_b;
+-- run
+
+-- ===== USING collation precedence (both spellings) + conflict =====
+-- (ticket join-key-collation-resolution-alignment) A USING pair resolves its
+-- comparison collation through the shared provenance lattice
+-- (explicit > declared > default > BINARY), SYMMETRICALLY: a declared NOCASE on
+-- EITHER side governs the join regardless of which side spells it, matching the
+-- equivalent `l.name = r.name`. Fixtures are chosen so BINARY yields 0 matches
+-- and NOCASE yields 3 — the row count alone pins which collation is in effect.
+
+-- Left declares NOCASE, right defaults to BINARY → NOCASE wins (folds case).
+create table up_l (id integer primary key, name text collate nocase);
+create table up_r (id integer primary key, name text);
+insert into up_l values (1, 'Alice'), (2, 'BOB'), (3, 'carol');
+insert into up_r values (10, 'alice'), (20, 'bob'), (30, 'CAROL');
+select up_l.id as lid, up_r.id as rid from up_l join up_r using (name) order by up_l.id;
+→ [{"lid":1,"rid":10},{"lid":2,"rid":20},{"lid":3,"rid":30}]
+
+-- Mirror spelling: left defaults to BINARY, right declares NOCASE → still NOCASE.
+-- The pre-alignment left-only rule (`leftType ?? BINARY`) would have compared
+-- under BINARY here and matched nothing; the symmetric lattice folds case.
+create table um_l (id integer primary key, name text);
+create table um_r (id integer primary key, name text collate nocase);
+insert into um_l values (1, 'Alice'), (2, 'BOB'), (3, 'carol');
+insert into um_r values (10, 'alice'), (20, 'bob'), (30, 'CAROL');
+select um_l.id as lid, um_r.id as rid from um_l join um_r using (name) order by um_l.id;
+→ [{"lid":1,"rid":10},{"lid":2,"rid":20},{"lid":3,"rid":30}]
+
+drop table up_l;
+drop table up_r;
+drop table um_l;
+drop table um_r;
+-- run
+
+-- Conflicting DECLARED collations on a USING pair → plan-time ambiguous-collation
+-- error, raised at build: `using (name)` desugars to the `l.name = r.name`
+-- BinaryOpNode, whose type generation reports the conflict. The spelled-out ON
+-- form must error IDENTICALLY (uniformity between USING and ON).
+create table cf_a (id integer primary key, name text collate nocase);
+create table cf_b (id integer primary key, name text collate rtrim);
+insert into cf_a values (1, 'bob');
+insert into cf_b values (10, 'BOB');
+-- run
+
+select cf_a.id from cf_a join cf_b using (name);
+-- error: ambiguous collation
+
+select cf_a.id from cf_a join cf_b on cf_a.name = cf_b.name;
+-- error: ambiguous collation
+
+-- An explicit COLLATE on the comparison resolves the ambiguity (rank-3 explicit
+-- outranks both declared collations), so the same join builds and runs. USING has
+-- no per-column COLLATE syntax, so pin the resolution via the ON form: under the
+-- explicit NOCASE, 'bob' matches 'BOB'.
+select cf_a.id as aid, cf_b.id as bid from cf_a join cf_b on cf_a.name = cf_b.name collate nocase order by cf_a.id;
+→ [{"aid":1,"bid":10}]
+
+drop table cf_a;
+drop table cf_b;
+-- run
+
+-- ===== NULL USING keys never match =====
+-- `using (k)` is `l.k = r.k`, and `null = null` is UNKNOWN, so two NULL keys do
+-- NOT join — on either physical path. The nested-loop emitter compares through an
+-- ORDERING comparator, which ranks NULL/NULL as equal, so it carries its own NULL
+-- guard; the hash path drops NULL keys by construction. The two must agree with
+-- each other and with the spelled-out ON form.
+create table nu_l (id integer primary key, k text null);
+create table nu_r (id integer primary key, k text null);
+insert into nu_l values (1, null), (2, 'a');
+insert into nu_r values (10, null), (20, 'a');
+
+select nu_l.id as lid, nu_r.id as rid from nu_l join nu_r using (k) order by nu_l.id;
+→ [{"lid":2,"rid":20}]
+
+select nu_l.id as lid, nu_r.id as rid from nu_l join nu_r on nu_l.k = nu_r.k order by nu_l.id;
+→ [{"lid":2,"rid":20}]
+
+-- LEFT JOIN: the NULL-keyed left row survives, null-extended, rather than pairing
+-- with the NULL-keyed right row.
+select nu_l.id as lid, nu_r.id as rid from nu_l left join nu_r using (k) order by nu_l.id;
+→ [{"lid":1,"rid":null},{"lid":2,"rid":20}]
+
+drop table nu_l;
+drop table nu_r;
+-- run
+
+-- ===== Cross-type USING pairs coerce exactly as the ON form does =====
+-- (ticket bug-using-join-skips-cross-type-coercion) `using (k)` desugars to
+-- `l.k = r.k`, so `insertCrossTypeCoercion` reconciles the pair: a JSON column
+-- against a TEXT one compares structurally (key order irrelevant), and an INTEGER
+-- against a TEXT one compares numerically. Before the desugar USING compared raw
+-- storage classes and returned 0 rows where the ON spelling returned the row.
+create table xj_l (id integer primary key, k json);
+create table xj_r (id integer primary key, k text);
+insert into xj_l values (1, '{"a":1,"b":2}');
+insert into xj_r values (10, '{"b":2,"a":1}');
+
+select xj_l.id as lid, xj_r.id as rid from xj_l join xj_r using (k);
+→ [{"lid":1,"rid":10}]
+
+select xj_l.id as lid, xj_r.id as rid from xj_l join xj_r on xj_l.k = xj_r.k;
+→ [{"lid":1,"rid":10}]
+
+create table xn_l (id integer primary key, k integer);
+create table xn_r (id integer primary key, k text);
+insert into xn_l values (1, 5), (2, 6);
+insert into xn_r values (10, '5'), (20, 'six');
+
+select xn_l.id as lid, xn_r.id as rid from xn_l join xn_r using (k);
+→ [{"lid":1,"rid":10}]
+
+select xn_l.id as lid, xn_r.id as rid from xn_l join xn_r on xn_l.k = xn_r.k;
+→ [{"lid":1,"rid":10}]
+
+-- A cross-type USING pair runs as nested loop (the coerced operand is a CastNode, so
+-- no equi-pair is extracted), which is the path an outer join's null-extension takes.
+-- The unmatched left row must still survive, and the ON form must agree.
+select xn_l.id as lid, xn_r.id as rid from xn_l left join xn_r using (k) order by xn_l.id;
+→ [{"lid":1,"rid":10},{"lid":2,"rid":null}]
+
+select xn_l.id as lid, xn_r.id as rid from xn_l left join xn_r on xn_l.k = xn_r.k order by xn_l.id;
+→ [{"lid":1,"rid":10},{"lid":2,"rid":null}]
+
+drop table xj_l;
+drop table xj_r;
+drop table xn_l;
+drop table xn_r;
+-- run
+
+-- Multi-column USING where only ONE column is cross-type: the same-type column still
+-- keys the join and the coerced one is evaluated as a residual predicate. Both must
+-- apply — row (2,'7') differs on the coerced column and must not join.
+create table xm_l (id integer primary key, a integer, b integer);
+create table xm_r (id integer primary key, a integer, b text);
+insert into xm_l values (1, 100, 5), (2, 200, 6);
+insert into xm_r values (10, 100, '5'), (20, 200, '7');
+
+select xm_l.id as lid, xm_r.id as rid from xm_l join xm_r using (a, b) order by xm_l.id;
+→ [{"lid":1,"rid":10}]
+
+select xm_l.id as lid, xm_r.id as rid from xm_l join xm_r on xm_l.a = xm_r.a and xm_l.b = xm_r.b order by xm_l.id;
+→ [{"lid":1,"rid":10}]
+
+drop table xm_l;
+drop table xm_r;
+-- run
+
+-- ===== A USING column absent from a side is an error, not a silent empty result =====
+-- Formerly the emitter's USING comparator returned false for an unresolved column
+-- index, so the join produced zero rows and raised nothing.
+create table mi_l (id integer primary key, k integer);
+create table mi_r (id integer primary key, k integer);
+insert into mi_l values (1, 10);
+insert into mi_r values (10, 10);
+-- run
+
+select mi_l.id from mi_l join mi_r using (zzz);
+-- error: USING column not found on left side of join: zzz
+
+drop table mi_l;
+drop table mi_r;
+-- run
+
+-- ===== Three-way USING: first-match-per-side pairing =====
+-- The second join's left side (the a-b join) carries TWO `k` attributes. The pair
+-- is formed from the FIRST match on each side, i.e. `t3a.k = t3c.k` — pinned by
+-- making the first join a LEFT join so a null-extended row has `t3b.k` NULL while
+-- `t3a.k` still holds 20. Pairing on `t3b.k` would drop that row.
+create table t3a (id integer primary key, k integer);
+create table t3b (id integer primary key, k integer);
+create table t3c (id integer primary key, k integer);
+insert into t3a values (1, 10), (2, 20);
+insert into t3b values (11, 10);
+insert into t3c values (111, 10), (222, 20);
+
+select t3a.id as aid, t3b.id as bid, t3c.id as cid
+  from t3a left join t3b using (k) join t3c using (k) order by t3a.id;
+→ [{"aid":1,"bid":11,"cid":111},{"aid":2,"bid":null,"cid":222}]
+
+drop table t3a;
+drop table t3b;
+drop table t3c;

package/test/logic/11.2-comma-join.sqllogic

@@ -0,0 +1,35 @@
+-- adapted from SQLite test/join3.test, join.test
+-- Quereus does NOT support SQLite's comma syntax in FROM (implicit cross join).
+-- Use explicit JOIN instead. This file pins the rejection.
+
+create table cj_a (id integer primary key, va text);
+create table cj_b (id integer primary key, vb text);
+create table cj_c (id integer primary key, vc text);
+
+insert into cj_a values (1, 'a1'), (2, 'a2');
+insert into cj_b values (10, 'b1'), (20, 'b2'), (30, 'b3');
+insert into cj_c values (100, 'c1'), (200, 'c2');
+-- run
+
+-- Two-table comma list: not supported
+select count(*) as cnt from cj_a, cj_b;
+-- error: multiple FROM sources
+
+-- Two-table comma list with WHERE join condition: not supported
+select cj_a.id, cj_b.id from cj_a, cj_b where cj_a.id = cj_b.id - 9;
+-- error: multiple FROM sources
+
+-- Three-table comma list: not supported
+select cj_a.id, cj_b.id, cj_c.id from cj_a, cj_b, cj_c
+  where cj_a.id = cj_b.id - 9 and cj_b.id = cj_c.id - 90;
+-- error: multiple FROM sources
+
+-- Comma mixed with explicit JOIN: still rejected because of the leading comma list
+select cj_a.id, cj_b.id, cj_c.id
+  from cj_a, cj_b join cj_c on cj_b.id = cj_c.id - 90
+  where cj_a.id = 2;
+-- error: multiple FROM sources
+
+drop table cj_a;
+drop table cj_b;
+drop table cj_c;

package/test/logic/11.3-index-nested-loop-join.sqllogic

@@ -0,0 +1,305 @@
+-- 11.3-index-nested-loop-join.sqllogic
+-- Result-equality coverage for the index-nested-loop join (rule-join-physical-selection
+-- + rules/join/index-nested-loop.ts): a small outer joined to a large indexed inner
+-- replaces the inner walk with one IndexSeek per outer row. Every assertion here is
+-- pure row equality, so it holds whichever physical join the optimizer picks — the
+-- plan-shape assertions (that these shapes DO pick the seek) live in
+-- test/optimizer/index-nested-loop.spec.ts.
+
+-- Small outer: one row with a NULL join key, one with a key matching nothing.
+CREATE TABLE inl_s (id INTEGER PRIMARY KEY, k INTEGER NULL);
+INSERT INTO inl_s VALUES (1, 5), (2, 7), (3, 500), (4, NULL);
+
+-- Large inner: v secondary-indexed; one row with a NULL v (must never match).
+CREATE TABLE inl_big (id INTEGER PRIMARY KEY, v INTEGER NULL, w INTEGER);
+CREATE INDEX inl_idx_v ON inl_big(v);
+INSERT INTO inl_big VALUES
+	(1, 1, 1), (2, 2, 2), (3, 3, 3), (4, 4, 4), (5, 5, 0), (6, 6, 1), (7, 7, 2), (8, 8, 3),
+	(9, 9, 4), (10, 10, 0), (11, 11, 1), (12, 12, 2), (13, 13, 3), (14, 14, 4), (15, 15, 0),
+	(16, 16, 1), (17, 17, 2), (18, 18, 3), (19, 19, 4), (20, 20, 0), (21, 21, 1), (22, 22, 2),
+	(23, 23, 3), (24, 24, 4), (25, 25, 0), (26, 26, 1), (27, 27, 2), (28, 28, 3), (29, 29, 4),
+	(30, 30, 0), (31, 31, 1), (32, 32, 2), (33, 33, 3), (34, 34, 4), (35, 35, 0), (36, 36, 1),
+	(37, 37, 2), (38, 38, 3), (39, 39, 4), (40, 40, 0), (41, NULL, 0);
+ANALYZE;
+
+-- INNER: only the two matching outer rows survive
+SELECT s.id, b.id AS bid FROM inl_s s JOIN inl_big b ON b.v = s.k ORDER BY s.id;
+→ [{"id":1,"bid":5},{"id":2,"bid":7}]
+
+-- LEFT: unmatched (k=500) and NULL-key outer rows null-pad — `NULL = v` is UNKNOWN
+SELECT s.id, b.id AS bid FROM inl_s s LEFT JOIN inl_big b ON b.v = s.k ORDER BY s.id;
+→ [{"id":1,"bid":5},{"id":2,"bid":7},{"id":3,"bid":null},{"id":4,"bid":null}]
+
+-- SEMI (EXISTS): first-match short-circuit; NULL key drops
+SELECT s.id FROM inl_s s WHERE EXISTS (SELECT 1 FROM inl_big b WHERE b.v = s.k) ORDER BY s.id;
+→ [{"id":1},{"id":2}]
+
+-- ANTI (NOT EXISTS): unmatched AND NULL-key outer rows are kept
+SELECT s.id FROM inl_s s WHERE NOT EXISTS (SELECT 1 FROM inl_big b WHERE b.v = s.k) ORDER BY s.id;
+→ [{"id":3},{"id":4}]
+
+-- The inner NULL-v row (id 41) matches nothing: NULL keys miss from BOTH sides
+SELECT count(*) AS n FROM inl_s s JOIN inl_big b ON b.v = s.k;
+→ [{"n":2}]
+
+-- `exists … as` flag joins keep the nested-loop driver, so they CAN take the seek
+-- path — the flag bit must survive and report per-row match truthfully
+SELECT s.id, has_b FROM inl_s s LEFT JOIN inl_big b ON b.v = s.k EXISTS RIGHT AS has_b ORDER BY s.id;
+→ [{"id":1,"has_b":true},{"id":2,"has_b":true},{"id":3,"has_b":false},{"id":4,"has_b":false}]
+
+-- Self-join: two access sites on the same table must not share a cursor (the
+-- outer walk and the per-row inner seek are distinct scan sites)
+SELECT a.id, b.id AS bid FROM inl_big a JOIN inl_big b ON b.v = a.w WHERE a.id <= 3 ORDER BY a.id;
+→ [{"id":1,"bid":1},{"id":2,"bid":2},{"id":3,"bid":3}]
+
+-- Three-way left-deep spine where the seek key comes from the INNER-MOST relation:
+-- at the final join the outer row is the composite [t1, t2] row and the t1
+-- attribute must still resolve inside the seek
+CREATE TABLE inl_t1 (id INTEGER PRIMARY KEY, k INTEGER);
+CREATE TABLE inl_t2 (id INTEGER PRIMARY KEY, t1_id INTEGER);
+INSERT INTO inl_t1 VALUES (1, 5), (2, 7);
+INSERT INTO inl_t2 VALUES (10, 1), (20, 2);
+ANALYZE;
+SELECT t1.id, t2.id AS t2id, b.id AS bid
+FROM inl_t1 t1 JOIN inl_t2 t2 ON t2.t1_id = t1.id JOIN inl_big b ON b.v = t1.k
+ORDER BY t1.id;
+→ [{"id":1,"t2id":10,"bid":5},{"id":2,"t2id":20,"bid":7}]
+
+-- ===== Composite and partial-composite keys =====
+
+CREATE TABLE inl_c (a INTEGER, b INTEGER, val TEXT, PRIMARY KEY (a, b));
+INSERT INTO inl_c VALUES
+	(1, 1, 'c1'), (2, 2, 'c2'), (3, 3, 'c3'), (4, 4, 'c4'), (0, 5, 'c5'),
+	(1, 6, 'c6'), (2, 7, 'c7'), (3, 8, 'c8'), (4, 9, 'c9'), (0, 10, 'c10'),
+	(1, 11, 'c11'), (2, 12, 'c12'), (3, 13, 'c13'), (4, 14, 'c14'), (0, 15, 'c15'),
+	(1, 16, 'c16'), (2, 17, 'c17'), (3, 18, 'c18'), (4, 19, 'c19'), (0, 20, 'c20'),
+	(1, 21, 'c21'), (2, 22, 'c22'), (3, 23, 'c23'), (4, 24, 'c24'), (0, 25, 'c25'),
+	(1, 26, 'c26'), (2, 27, 'c27'), (3, 28, 'c28'), (4, 29, 'c29'), (0, 30, 'c30');
+CREATE TABLE inl_s2 (id INTEGER PRIMARY KEY, x INTEGER NULL, y INTEGER NULL, name TEXT);
+INSERT INTO inl_s2 VALUES (1, 3, 3, 'c3'), (2, 2, 7, 'c12'), (3, 4, 999, 'zzz'), (4, NULL, 1, 'c1');
+ANALYZE;
+
+-- Both equi pairs covered by the composite PK: one composite seek per outer row
+SELECT s2.id, c.val FROM inl_s2 s2 JOIN inl_c c ON c.a = s2.x AND c.b = s2.y ORDER BY s2.id;
+→ [{"id":1,"val":"c3"},{"id":2,"val":"c7"}]
+
+-- Partial composite: the index covers only the `a = x` pair; `val = name` stays
+-- enforced by the retained condition (id 2: x=2 candidates are c2,c7,c12,… — only
+-- c12's val matches its name)
+SELECT s2.id, c.b AS cb FROM inl_s2 s2 JOIN inl_c c ON c.a = s2.x AND c.val = s2.name ORDER BY s2.id;
+→ [{"id":1,"cb":3},{"id":2,"cb":12}]
+
+-- ===== LATERAL with an ON equality (the sibling-reference guard) =====
+-- Before the guard in rule-join-physical-selection, a LATERAL right side reading
+-- the left side's columns with an equality ON was converted to a hash join,
+-- which drains the right side before any left row exists — "No row context
+-- found" at runtime. The guard keeps the nested-loop driver.
+
+CREATE TABLE inl_lt (k INTEGER PRIMARY KEY, v INTEGER);
+CREATE TABLE inl_lu (k INTEGER PRIMARY KEY, v INTEGER);
+INSERT INTO inl_lt VALUES (1, 10), (2, 20);
+INSERT INTO inl_lu VALUES (1, 10), (2, 99);
+
+SELECT t.k AS tk, x.k AS xk, x.v AS xv
+FROM inl_lt t JOIN LATERAL (SELECT * FROM inl_lu u WHERE u.k = t.k) x ON x.v = t.v;
+→ [{"tk":1,"xk":1,"xv":10}]
+
+SELECT t.k AS tk, x.k AS xk
+FROM inl_lt t LEFT JOIN LATERAL (SELECT * FROM inl_lu u WHERE u.k = t.k) x ON x.v = t.v
+ORDER BY tk;
+→ [{"tk":1,"xk":1},{"tk":2,"xk":null}]
+
+-- ===== Collation: both directions of a NOCASE / BINARY join =====
+
+-- Inner column declared NOCASE (its index inherits NOCASE); outer defaulted
+-- BINARY. Declared beats defaulted, so the join compares NOCASE and the index
+-- cover matches — the seek path is eligible, and 'n3' must match 'N3'.
+CREATE TABLE inl_cs (id INTEGER PRIMARY KEY, name TEXT COLLATE NOCASE);
+CREATE INDEX inl_idx_cs ON inl_cs(name);
+INSERT INTO inl_cs VALUES
+	(1, 'N1'), (2, 'N2'), (3, 'N3'), (4, 'N4'), (5, 'N5'), (6, 'N6'), (7, 'N7'), (8, 'N8'),
+	(9, 'N9'), (10, 'N10'), (11, 'N11'), (12, 'N12'), (13, 'N13'), (14, 'N14'), (15, 'N15'),
+	(16, 'N16'), (17, 'N17'), (18, 'N18'), (19, 'N19'), (20, 'N20');
+CREATE TABLE inl_co (id INTEGER PRIMARY KEY, name TEXT);
+INSERT INTO inl_co VALUES (1, 'n3'), (2, 'N5'), (3, 'zzz');
+ANALYZE;
+SELECT o.id, i.id AS iid FROM inl_co o JOIN inl_cs i ON i.name = o.name ORDER BY o.id;
+→ [{"id":1,"iid":3},{"id":2,"iid":5}]
+
+-- Reverse direction: outer declared NOCASE, inner index BINARY — a raw seek
+-- would under-fetch, so the rule declines and the surviving hash join must
+-- return BOTH case variants of 'A1'.
+CREATE TABLE inl_bs (id INTEGER PRIMARY KEY, name TEXT);
+CREATE INDEX inl_idx_bs ON inl_bs(name);
+INSERT INTO inl_bs VALUES
+	(1, 'B1'), (2, 'B2'), (3, 'B3'), (4, 'B4'), (5, 'B5'), (6, 'B6'), (7, 'B7'), (8, 'B8'),
+	(9, 'B9'), (10, 'B10'), (11, 'B11'), (12, 'B12'), (13, 'B13'), (14, 'B14'), (15, 'B15'),
+	(16, 'B16'), (17, 'B17'), (18, 'B18'), (19, 'B19'), (20, 'B20'), (21, 'a1'), (22, 'A1');
+CREATE TABLE inl_no (id INTEGER PRIMARY KEY, name TEXT COLLATE NOCASE);
+INSERT INTO inl_no VALUES (1, 'A1');
+ANALYZE;
+SELECT o.id, b.id AS bid FROM inl_no o JOIN inl_bs b ON b.name = o.name ORDER BY bid;
+→ [{"id":1,"bid":21},{"id":1,"bid":22}]
+
+-- ===== Seek-side election: the index-nested-loop is offered in BOTH orientations =====
+-- The parent/child rollup from ticket feat-index-nested-loop-seek-side-election: a
+-- filtered parent (`txn`, ≈10 rows per entity) and an FK-indexed child (`entry`).
+-- Whichever table is named first, the optimizer drives from the filtered parent and
+-- seeks the child — the second spelling below is rebuilt as a JoinNode with its
+-- children exchanged. Both must return the rows a plain nested loop returns, which
+-- the third query forces (`+ 0` on the key is not a bare column, so no equi pair is
+-- extracted and no physical join algorithm — hash, merge, or seek — competes).
+
+CREATE TABLE inl_txn (id INTEGER PRIMARY KEY, entity_id INTEGER, date TEXT);
+CREATE TABLE inl_entry (id INTEGER PRIMARY KEY, txn_id INTEGER, amount REAL);
+CREATE INDEX inl_txn_entity ON inl_txn (entity_id, date);
+CREATE INDEX inl_entry_txn ON inl_entry (txn_id);
+INSERT INTO inl_txn VALUES
+	(1, 1, '2024-01-01'), (2, 2, '2024-01-02'), (3, 3, '2024-01-03'), (4, 1, '2024-01-04'),
+	(5, 2, '2024-01-05'), (6, 3, '2024-01-06'), (7, 1, '2024-01-07'), (8, 2, '2024-01-08'),
+	(9, 3, '2024-01-09'), (10, 1, '2024-01-10'), (11, 2, '2024-01-11'), (12, 3, '2024-01-12'),
+	(13, 1, '2024-01-13'), (14, 2, '2024-01-14'), (15, 3, '2024-01-15'), (16, 1, '2024-01-16'),
+	(17, 2, '2024-01-17'), (18, 3, '2024-01-18'), (19, 1, '2024-01-19'), (20, 2, '2024-01-20'),
+	(21, 3, '2024-01-21'), (22, 1, '2024-01-22'), (23, 2, '2024-01-23'), (24, 3, '2024-01-24');
+INSERT INTO inl_entry VALUES
+	(1, 1, 1.5), (2, 2, 3.0), (3, 3, 4.5), (4, 4, 6.0), (5, 5, 7.5), (6, 6, 9.0), (7, 7, 10.5),
+	(8, 8, 12.0), (9, 9, 13.5), (10, 10, 15.0), (11, 11, 16.5), (12, 12, 18.0), (13, 13, 19.5),
+	(14, 14, 21.0), (15, 15, 22.5), (16, 16, 24.0), (17, 17, 25.5), (18, 18, 27.0), (19, 19, 28.5),
+	(20, 20, 30.0), (21, 21, 31.5), (22, 22, 33.0), (23, 23, 34.5), (24, 24, 36.0),
+	(25, 1, 0.5), (26, 4, 0.5), (27, 7, 0.5), (28, 10, 0.5), (29, 13, 0.5), (30, 16, 0.5),
+	(31, 19, 0.5), (32, 22, 0.5), (33, 2, 100.0), (34, 999, 1.0);
+ANALYZE;
+
+-- Filtered parent named first (the un-mirrored orientation)
+SELECT e.txn_id, sum(e.amount) AS total
+FROM inl_txn t JOIN inl_entry e ON t.id = e.txn_id
+WHERE t.entity_id = 1 GROUP BY e.txn_id ORDER BY e.txn_id;
+→ [{"txn_id":1,"total":2},{"txn_id":4,"total":6.5},{"txn_id":7,"total":11},{"txn_id":10,"total":15.5},{"txn_id":13,"total":20},{"txn_id":16,"total":24.5},{"txn_id":19,"total":29},{"txn_id":22,"total":33.5}]
+
+-- Child named first (the mirrored orientation: same plan shape, sides exchanged)
+SELECT e.txn_id, sum(e.amount) AS total
+FROM inl_entry e JOIN inl_txn t ON t.id = e.txn_id
+WHERE t.entity_id = 1 GROUP BY e.txn_id ORDER BY e.txn_id;
+→ [{"txn_id":1,"total":2},{"txn_id":4,"total":6.5},{"txn_id":7,"total":11},{"txn_id":10,"total":15.5},{"txn_id":13,"total":20},{"txn_id":16,"total":24.5},{"txn_id":19,"total":29},{"txn_id":22,"total":33.5}]
+
+-- Forced away from every equi-join rewrite: the plain nested-loop answer
+SELECT e.txn_id, sum(e.amount) AS total
+FROM inl_entry e JOIN inl_txn t ON t.id = e.txn_id + 0
+WHERE t.entity_id = 1 GROUP BY e.txn_id ORDER BY e.txn_id;
+→ [{"txn_id":1,"total":2},{"txn_id":4,"total":6.5},{"txn_id":7,"total":11},{"txn_id":10,"total":15.5},{"txn_id":13,"total":20},{"txn_id":16,"total":24.5},{"txn_id":19,"total":29},{"txn_id":22,"total":33.5}]
+
+-- Non-aggregated projection through the exchanged sides: values follow the
+-- attribute the projection names, not the slot it used to occupy
+SELECT t.id AS tid, t.date, e.id AS eid, e.amount
+FROM inl_entry e JOIN inl_txn t ON t.id = e.txn_id
+WHERE t.entity_id = 1 ORDER BY eid;
+→ [{"tid":1,"date":"2024-01-01","eid":1,"amount":1.5},{"tid":4,"date":"2024-01-04","eid":4,"amount":6},{"tid":7,"date":"2024-01-07","eid":7,"amount":10.5},{"tid":10,"date":"2024-01-10","eid":10,"amount":15},{"tid":13,"date":"2024-01-13","eid":13,"amount":19.5},{"tid":16,"date":"2024-01-16","eid":16,"amount":24},{"tid":19,"date":"2024-01-19","eid":19,"amount":28.5},{"tid":22,"date":"2024-01-22","eid":22,"amount":33},{"tid":1,"date":"2024-01-01","eid":25,"amount":0.5},{"tid":4,"date":"2024-01-04","eid":26,"amount":0.5},{"tid":7,"date":"2024-01-07","eid":27,"amount":0.5},{"tid":10,"date":"2024-01-10","eid":28,"amount":0.5},{"tid":13,"date":"2024-01-13","eid":29,"amount":0.5},{"tid":16,"date":"2024-01-16","eid":30,"amount":0.5},{"tid":19,"date":"2024-01-19","eid":31,"amount":0.5},{"tid":22,"date":"2024-01-22","eid":32,"amount":0.5}]
+
+-- `SELECT *` is the sharpest test of the swap: with no projection naming columns,
+-- the result's COLUMN ORDER is whatever the star expanded to at build time. It must
+-- stay the spelled order — entry's three columns then txn's — even though the first
+-- query below plans with the sides exchanged and the second does not.
+SELECT * FROM inl_entry e JOIN inl_txn t ON t.id = e.txn_id WHERE t.entity_id = 1 ORDER BY e.id;
+→ [{"id":1,"txn_id":1,"amount":1.5,"id:1":1,"entity_id":1,"date":"2024-01-01"},{"id":4,"txn_id":4,"amount":6,"id:1":4,"entity_id":1,"date":"2024-01-04"},{"id":7,"txn_id":7,"amount":10.5,"id:1":7,"entity_id":1,"date":"2024-01-07"},{"id":10,"txn_id":10,"amount":15,"id:1":10,"entity_id":1,"date":"2024-01-10"},{"id":13,"txn_id":13,"amount":19.5,"id:1":13,"entity_id":1,"date":"2024-01-13"},{"id":16,"txn_id":16,"amount":24,"id:1":16,"entity_id":1,"date":"2024-01-16"},{"id":19,"txn_id":19,"amount":28.5,"id:1":19,"entity_id":1,"date":"2024-01-19"},{"id":22,"txn_id":22,"amount":33,"id:1":22,"entity_id":1,"date":"2024-01-22"},{"id":25,"txn_id":1,"amount":0.5,"id:1":1,"entity_id":1,"date":"2024-01-01"},{"id":26,"txn_id":4,"amount":0.5,"id:1":4,"entity_id":1,"date":"2024-01-04"},{"id":27,"txn_id":7,"amount":0.5,"id:1":7,"entity_id":1,"date":"2024-01-07"},{"id":28,"txn_id":10,"amount":0.5,"id:1":10,"entity_id":1,"date":"2024-01-10"},{"id":29,"txn_id":13,"amount":0.5,"id:1":13,"entity_id":1,"date":"2024-01-13"},{"id":30,"txn_id":16,"amount":0.5,"id:1":16,"entity_id":1,"date":"2024-01-16"},{"id":31,"txn_id":19,"amount":0.5,"id:1":19,"entity_id":1,"date":"2024-01-19"},{"id":32,"txn_id":22,"amount":0.5,"id:1":22,"entity_id":1,"date":"2024-01-22"}]
+
+SELECT * FROM inl_txn t JOIN inl_entry e ON t.id = e.txn_id WHERE t.entity_id = 1 ORDER BY e.id;
+→ [{"id":1,"entity_id":1,"date":"2024-01-01","id:1":1,"txn_id":1,"amount":1.5},{"id":4,"entity_id":1,"date":"2024-01-04","id:1":4,"txn_id":4,"amount":6},{"id":7,"entity_id":1,"date":"2024-01-07","id:1":7,"txn_id":7,"amount":10.5},{"id":10,"entity_id":1,"date":"2024-01-10","id:1":10,"txn_id":10,"amount":15},{"id":13,"entity_id":1,"date":"2024-01-13","id:1":13,"txn_id":13,"amount":19.5},{"id":16,"entity_id":1,"date":"2024-01-16","id:1":16,"txn_id":16,"amount":24},{"id":19,"entity_id":1,"date":"2024-01-19","id:1":19,"txn_id":19,"amount":28.5},{"id":22,"entity_id":1,"date":"2024-01-22","id:1":22,"txn_id":22,"amount":33},{"id":1,"entity_id":1,"date":"2024-01-01","id:1":25,"txn_id":1,"amount":0.5},{"id":4,"entity_id":1,"date":"2024-01-04","id:1":26,"txn_id":4,"amount":0.5},{"id":7,"entity_id":1,"date":"2024-01-07","id:1":27,"txn_id":7,"amount":0.5},{"id":10,"entity_id":1,"date":"2024-01-10","id:1":28,"txn_id":10,"amount":0.5},{"id":13,"entity_id":1,"date":"2024-01-13","id:1":29,"txn_id":13,"amount":0.5},{"id":16,"entity_id":1,"date":"2024-01-16","id:1":30,"txn_id":16,"amount":0.5},{"id":19,"entity_id":1,"date":"2024-01-19","id:1":31,"txn_id":19,"amount":0.5},{"id":22,"entity_id":1,"date":"2024-01-22","id:1":32,"txn_id":22,"amount":0.5}]
+
+-- A third relation above the exchanged pair: the upper join consumes the mirrored
+-- join's attributes in their NEW order, so a stale positional mapping there would
+-- surface as swapped values rather than as an error
+CREATE TABLE inl_ent (id INTEGER PRIMARY KEY, name TEXT);
+INSERT INTO inl_ent VALUES (1, 'alpha'), (2, 'beta'), (3, 'gamma');
+ANALYZE;
+SELECT n.name, t.id AS tid, e.id AS eid
+FROM inl_entry e JOIN inl_txn t ON t.id = e.txn_id JOIN inl_ent n ON n.id = t.entity_id
+WHERE t.entity_id = 1 ORDER BY eid;
+→ [{"name":"alpha","tid":1,"eid":1},{"name":"alpha","tid":4,"eid":4},{"name":"alpha","tid":7,"eid":7},{"name":"alpha","tid":10,"eid":10},{"name":"alpha","tid":13,"eid":13},{"name":"alpha","tid":16,"eid":16},{"name":"alpha","tid":19,"eid":19},{"name":"alpha","tid":22,"eid":22},{"name":"alpha","tid":1,"eid":25},{"name":"alpha","tid":4,"eid":26},{"name":"alpha","tid":7,"eid":27},{"name":"alpha","tid":10,"eid":28},{"name":"alpha","tid":13,"eid":29},{"name":"alpha","tid":16,"eid":30},{"name":"alpha","tid":19,"eid":31},{"name":"alpha","tid":22,"eid":32}]
+
+-- Self-join that mirrors: `b` (filtered to 8 rows) drives and `a` is seeked by
+-- primary key, the reverse of how it is spelled. The two sides are distinct scan
+-- instances of one table, so the swap must not make them share a cursor.
+SELECT a.id AS aid, b.id AS bid FROM inl_big a JOIN inl_big b ON a.id = b.v WHERE b.w = 3 ORDER BY aid;
+→ [{"aid":3,"bid":3},{"aid":8,"bid":8},{"aid":13,"bid":13},{"aid":18,"bid":18},{"aid":23,"bid":23},{"aid":28,"bid":28},{"aid":33,"bid":33},{"aid":38,"bid":38}]
+
+-- Both sides indexed on the join key, large table named first: the swap drives from
+-- the small side and seeks the large one; rows are what an inner join returns
+CREATE TABLE inl_pa (id INTEGER PRIMARY KEY, k INTEGER NULL);
+CREATE INDEX inl_idx_pa_k ON inl_pa(k);
+INSERT INTO inl_pa VALUES (1, 3), (2, 7), (3, 40), (4, NULL);
+ANALYZE;
+SELECT b.id AS bid, a.id AS aid FROM inl_big b JOIN inl_pa a ON b.v = a.k ORDER BY aid;
+→ [{"bid":3,"aid":1},{"bid":7,"aid":2},{"bid":40,"aid":3}]
+
+-- ===== Join-key seek combined with a predicate the module already claimed =====
+-- `status` is indexed, so `b.status = 'x'` is pushed into the inner leaf as a seek
+-- the module enforces alone — it is nowhere else in the tree. The index-nested-loop
+-- rule re-offers that predicate together with the join key and re-applies whatever
+-- the module declines as a Filter directly above the new seek (or the module takes
+-- both on a composite index). Every outer key below matches an inner row by id, so
+-- the status predicate is what decides each row: k=5 hits id 5 (status 'y') and
+-- must be dropped — a redundant filter would prove nothing.
+CREATE TABLE inl_ps (id INTEGER PRIMARY KEY, k INTEGER NULL);
+INSERT INTO inl_ps VALUES (1, 5), (2, 8), (3, 12), (4, NULL), (5, 500);
+CREATE TABLE inl_pb (id INTEGER PRIMARY KEY, v INTEGER, status TEXT);
+CREATE INDEX inl_idx_pb_v ON inl_pb(v);
+CREATE INDEX inl_idx_pb_status ON inl_pb(status);
+INSERT INTO inl_pb VALUES
+	(1, 1, 'y'), (2, 2, 'y'), (3, 3, 'y'), (4, 4, 'x'), (5, 5, 'y'), (6, 6, 'y'), (7, 7, 'y'), (8, 8, 'x'),
+	(9, 9, 'y'), (10, 10, 'y'), (11, 11, 'y'), (12, 12, 'x'), (13, 13, 'y'), (14, 14, 'y'), (15, 15, 'y'),
+	(16, 16, 'x'), (17, 17, 'y'), (18, 18, 'y'), (19, 19, 'y'), (20, 20, 'x'), (21, 21, 'y'), (22, 22, 'y'),
+	(23, 23, 'y'), (24, 24, 'x'), (25, 25, 'y'), (26, 26, 'y'), (27, 27, 'y'), (28, 28, 'x'), (29, 29, 'y'),
+	(30, 30, 'y'), (31, 31, 'y'), (32, 32, 'x'), (33, 33, 'y'), (34, 34, 'y'), (35, 35, 'y'), (36, 36, 'x'),
+	(37, 37, 'y'), (38, 38, 'y'), (39, 39, 'y'), (40, 40, 'x');
+ANALYZE;
+
+-- INNER on the primary key: id 5 is status 'y' → dropped by the re-applied predicate
+SELECT s.id, b.id AS bid FROM inl_ps s JOIN inl_pb b ON b.id = s.k WHERE b.status = 'x' ORDER BY s.id;
+→ [{"id":2,"bid":8},{"id":3,"bid":12}]
+
+-- INNER on the secondary index: same answer through idx_v
+SELECT s.id, b.id AS bid FROM inl_ps s JOIN inl_pb b ON b.v = s.k WHERE b.status = 'x' ORDER BY s.id;
+→ [{"id":2,"bid":8},{"id":3,"bid":12}]
+
+-- LEFT with the predicate in the ON clause: the inner Filter sits inside the inner
+-- pipeline, so a row it rejects makes the seek look empty → null-pad (k=5), as do
+-- the NULL key and the unmatched key
+SELECT s.id, b.id AS bid FROM inl_ps s LEFT JOIN inl_pb b ON b.id = s.k AND b.status = 'x' ORDER BY s.id;
+→ [{"id":1,"bid":null},{"id":2,"bid":8},{"id":3,"bid":12},{"id":4,"bid":null},{"id":5,"bid":null}]
+
+-- ANTI (NOT EXISTS): a seek hit rejected by the Filter counts as "no inner row" → kept
+SELECT s.id FROM inl_ps s WHERE NOT EXISTS (SELECT 1 FROM inl_pb b WHERE b.id = s.k AND b.status = 'x') ORDER BY s.id;
+→ [{"id":1},{"id":4},{"id":5}]
+
+-- SEMI (EXISTS): the mirror of the anti answer
+SELECT s.id FROM inl_ps s WHERE EXISTS (SELECT 1 FROM inl_pb b WHERE b.id = s.k AND b.status = 'x') ORDER BY s.id;
+→ [{"id":2},{"id":3}]
+
+-- A pushed range on the join-key column itself: `b.id = s.k` wins the column as the
+-- seek and `b.id > 10` comes back as the residual (id 5 and 8 are out)
+SELECT s.id, b.id AS bid FROM inl_ps s JOIN inl_pb b ON b.id = s.k WHERE b.id > 10 ORDER BY s.id;
+→ [{"id":3,"bid":12}]
+
+-- A pushed BETWEEN re-applied as its single node: id 12 is outside the range
+SELECT s.id, b.id AS bid FROM inl_ps s JOIN inl_pb b ON b.v = s.k WHERE b.id BETWEEN 2 AND 9 ORDER BY s.id;
+→ [{"id":1,"bid":5},{"id":2,"bid":8}]
+
+-- Composite index covering both: the module takes the status equality AND the join
+-- key as one seek, so no residual is needed — rows identical to the single-index form
+CREATE TABLE inl_cb (id INTEGER PRIMARY KEY, v INTEGER, status TEXT);
+CREATE INDEX inl_idx_cb ON inl_cb(status, v);
+CREATE INDEX inl_idx_cb1 ON inl_cb(status);
+INSERT INTO inl_cb SELECT id, v, status FROM inl_pb;
+ANALYZE;
+SELECT s.id, c.id AS cid FROM inl_ps s JOIN inl_cb c ON c.v = s.k WHERE c.status = 'x' ORDER BY s.id;
+→ [{"id":2,"cid":8},{"id":3,"cid":12}]
+
+-- The module keeps its own seek (a unique primary-key equality) and refuses the join
+-- key: the plan is left alone and the rows are still right
+SELECT s.id, b.id AS bid FROM inl_ps s JOIN inl_pb b ON b.v = s.k WHERE b.id = 8 ORDER BY s.id;
+→ [{"id":2,"bid":8}]
+
+-- The predicate's column is not selected by the derived table: the re-applied Filter
+-- goes below the peeled Project, where `status` is still in scope
+SELECT s.id FROM inl_ps s JOIN (SELECT id, v FROM inl_pb WHERE status = 'x') t ON t.v = s.k ORDER BY s.id;
+→ [{"id":2},{"id":3}]