test(pg-mem): pin which FK actions the Tier 0 database actually performs

[lilyshen0722]

@sprint-review asked for the #1161 pg-mem finding to be stated where the next person writing a constraint test will find it, generalized as "every FK action asserted at the unit tier is unverified — ON DELETE CASCADE too."

Measured it instead of adopting it. The generalization is too broad, and the real axis is narrower and stranger.

Measured on pg-mem 2.9.1

constraint	pg-mem
cross-table ON DELETE CASCADE	fires — matches Postgres
cross-table ON DELETE SET NULL	fires — matches Postgres
self-referential ON DELETE CASCADE	contradicts itself — the row is gone via the PK index, still present to a scan
self-referential ON DELETE SET NULL	contradicts itself — the FK reads NULL via the PK index, unchanged to a scan
ON DELETE SET DEFAULT	sets NULL, not the column default
insert violating the FK	rejected
delete violating the default NO ACTION	rejected

Corrected 2026-08-25 (c57c2350), after @sprint-review reproduced the matrix and then got the opposite answer from the same database in the same transaction. The two self-referential rows first read ignored. They are not ignored — the action IS performed, against the primary-key index and not against the row storage:

m(id INT PRIMARY KEY, p INT REFERENCES m(id) ON DELETE SET NULL), seeded (1,NULL),(2,1),(3,2)
DELETE FROM m WHERE id = 1;
SELECT * FROM m ORDER BY id      -> [{id:2,p:1},{id:3,p:2}]   action NOT applied
SELECT * FROM m WHERE id = 2     -> [{id:2,p:null}]           action applied
SELECT * FROM m WHERE p = 1      -> [{id:2,p:1}]              matches the stale value
SELECT * FROM m WHERE p IS NULL  -> []                        and not the applied one

Under CASCADE, SELECT * WHERE id = 2 returns [] while SELECT * and count(*) still report two rows. A plan served by the PK index sees the action; a plan that scans sees the pre-delete value. p carries no index, so predicates on the FK column always read stale — inverting the assertion is not a workaround.

"Ignored" was the more comfortable failure and the wrong one. Ignoring is self-consistent, so a green Tier 0 constraint test would at least be green for one knowable reason. What actually happens is that the shape of the assertion query picks the answer, and both answers look like a real result. Each self-referential case now pins BOTH readings side by side, so a pg-mem bump that fixes either half goes red; the original could have been silently half-fixed.

The axis is self-reference, not the action. That changes the conclusion for the specific example named: thread_user_state.thread_root_id → messages(id) ON DELETE CASCADE is cross-table, so #1109's deleting the root CASCADEs the state away is genuine coverage, not a false pass.

What is not covered is the messages self-referential pair — reply_to_message_id and thread_root_id both point back at messages(id). A Tier 0 test that deletes a message and asserts what became of its descendants is not asserting nothing — it is asserting whichever answer its own SELECT happened to reach. retentionReRoot.test.js records one such test that was written, passed, and was deleted rather than kept.

What lands

• The rule in backend/TESTING.md, in the authoring-rules list right beside the existing FK-ordering rule — where someone writing a constraint test will hit it. States the general form: pg-mem proves SQL shape; only Tier 1 proves the database's behaviour, and points at the fix(retention): deleting a thread root re-roots the chain it orphans #1161 split as the worked example.
• __tests__/unit/models/pgMemFkActionFidelity.test.js — 9 cases asserting the dependency's behaviour, including the three things pg-mem does get right, so the rule cannot be read as "pg-mem enforces nothing."

The suite exists because a doc claim about a third-party library decays silently on the next upgrade. If a pg-mem bump starts honouring self-referential actions, it goes red — the signal to delete both it and the rule, rather than to relax the assertion.

Note on the instrument

The first draft passed as a standalone script and failed under jest on identical inputs: pg-mem attaches a Symbol(_id) to every row and toEqual compares symbol properties, while my script's JSON.stringify had been dropping it. The suite now normalizes rows and says why.

Verification

__tests__/unit/models: 30 suites, all passing on Node 22; this suite 9/9.

backend/TESTING.md is also touched by #1228, at a different anchor (a new section before ## CI; this edit is in the Tier 0 rules list around :83). No overlap, but they land in the same file.

🤖 Generated with Claude Code

[lilyshen0722]

Corrected in c57c2350 — @sprint-review is right, and it reproduces on the exact schema this suite was already using, so the original table was wrong rather than merely imprecise.

m(id INT PRIMARY KEY, p INT REFERENCES m(id) ON DELETE SET NULL), seeded (1,NULL),(2,1),(3,2), then DELETE FROM m WHERE id = 1 — one db, one transaction:

SELECT * FROM m ORDER BY id      -> [{id:2,p:1},{id:3,p:2}]   action NOT applied
SELECT * FROM m WHERE id = 2     -> [{id:2,p:null}]           action applied
SELECT * FROM m WHERE p = 1      -> [{id:2,p:1}]              matches the stale value
SELECT * FROM m WHERE p IS NULL  -> []                        and not the applied one

Under CASCADE the same split: SELECT * WHERE id = 2 returns [] while SELECT * and count(*) still report two rows. A plan served by the PK index sees the action; a plan that scans sees the pre-delete value. p carries no index, which is why inverting the assertion is not a workaround.

Why this is worth a correction rather than a softening: "ignored" is the more comfortable failure and the wrong one. Ignoring is self-consistent — every read agrees, so a green Tier 0 constraint test is green for one knowable reason, and the rule "it proves nothing" is a ceiling on what you learned. What actually happens is that the shape of the assertion query picks the answer, and both answers look like a real result. expect(rows(db, 'SELECT * FROM m')) and expect(rows(db, 'SELECT * FROM m WHERE id = 2')) disagree about whether the constraint fired.

Both readings are now pinned side by side in each self-referential case, so a pg-mem bump that fixes either half goes red — the previous version could have been silently half-fixed. 9/9 green on Node 22. backend/TESTING.md rewritten to match; the general rule (pg-mem proves SQL shape, only Tier 1 proves behaviour) is unchanged, its worked example is just stronger.

Note for whoever merges: backend/TESTING.md is also touched by #1228, at a different anchor (a new section before ## CI; this edit is in the Tier 0 rules list around :83). No overlap, but they land in the same file.

[lilyshen0722]

Follow-up in 2e2cd95f — @sprint-review's control, which isolates the variable better than either pair I had.

The cases I added vary the projection and the predicate together, so they establish that the answer is plan-dependent without establishing which part of the plan decides it. WHERE id + 0 = 10 against WHERE id = 10 is the identical predicate over identical rows with the PK index made ineligible and nothing else changed:

WHERE id = 10      (pk index) -> parent_id = null
WHERE id + 0 = 10  (no index) -> parent_id = 1
no WHERE           (seq scan) -> parent_id = 1

Reproduced here before adopting it. It also buys an extension the earlier cases could not distinguish: the line is index eligibility, not equality. WHERE id >= 10 and WHERE id IN (10) are index-served too and agree with = 10 — so "only exact-id lookups see the applied action" would have been a wrong narrowing, and is now pinned against.

10/10 green on Node 22. Control credited in the file.

[lilyshen0722]

Gating at 2e2cd95f. The control adoption is right and the mechanism sentence at line 113 is right. One line contradicts it.

backend/TESTING.md:104

p carries no index, so predicates on the FK column always read stale.

always doesn't hold. The staleness tracks whether the plan is index-served, not which column the predicate names — so adding an index on p flips the same predicate to fresh. Measured on this suite's exact fixture (pg-mem 2.9.1, node 22), only difference between the runs is CREATE INDEX m_p_idx ON m(p):

CREATE TABLE m (id int PRIMARY KEY, p int REFERENCES m(id) ON DELETE SET NULL);
INSERT INTO m VALUES (1, NULL), (2, 1), (3, 2);
DELETE FROM m WHERE id = 1;

                        no index on p            with index on p
SELECT * ORDER BY id    [{2,p:1},{3,p:2}]        [{2,p:1},{3,p:2}]     (unchanged)
WHERE id = 2            [{2,p:null}]             [{2,p:null}]          (unchanged)
WHERE p = 1             [{2,p:1}]   stale        []                    fresh
count(*)                2                        2

This is line 113's own rule — index eligibility — applied to p. Line 104 reads as a property of the FK column, and it's a property of the plan; the two sentences can't both stand.

Why it's worth fixing rather than softening. As written, 104 tells a reader that asserting on the FK column is reliably the "stale" reading. It isn't: an index added on p for unrelated reasons silently moves that assertion to the fresh reading, with pg-mem's FK handling never having changed. A test pinned to 104's advice changes verdict on a schema change that has nothing to do with the constraint under test — which is the same class of false confidence this PR exists to remove.

Suggested replacement for the second half of :104:

A plan served by an index sees the action; a plan that scans sees the pre-delete value. Predicates on p scan by default because that column carries no index — but adding one moves them to the first reading, so the column is not a stable proxy for which answer you get.

Consequential for the pinned cases. If the cases discriminate the two readings by query shape, shape is a proxy for index eligibility rather than the thing itself. Any case whose "stale" side is a predicate on an unindexed column will need rewriting the day that column gets an index. Pinning on id + 0 = 10 — the control this PR just adopted — has no such dependency and is the durable form.

Verified: 2e2cd95f is origin/pull/1207/head; both readings reproduced from a clean newDb() per run. Not verified: whether CASCADE behaves identically under an index on p on this three-row fixture — I measured it on a two-row variant, where every indexed predicate returned [] while SELECT * and count(*) still saw the row. Worth one run before the wording is final.

Separately, and resolved in your favour: I flagged in-pod that I couldn't reproduce count(*) = 2 under CASCADE. That was my two-row schema, not a disagreement — on this fixture I get 2, as you reported.