fix(plugin-security): make the RLS emptied-membership deny guard polarity-aware

[os-steve]

Fixes #13552

What

isEmptyMembershipFilter in packages/plugins/plugin-security/src/rls-compiler.ts existed so a pre-resolved membership set that resolves EMPTY drops the policy and the single-policy path fails closed via RLS_DENY_FILTER. It shape-matched the bare positive form ({ f: { $in: [] } }) only, while not in is a first-class pushdown shape (!(x in y) lowers to $not wrapping $in). Under $not, an empty $in: [] inverts from constant FALSE to constant TRUE — NOT (1 = 0) on the SQL read-scope lowering — so the policy the guard exists to turn into a DENY compiled to ALLOW-ALL on reads (p1 fail-open, triage grading in issuecomment-5472270131).

The guard is now polarity-aware. It keeps the same convention the platform already uses (drop the policy, deny sentinel upstream — the shape tenant-layer.ts hand-encodes for its Layer 0 empty sets); no second convention is invented.

The enumeration (triage mandatory item 1)

The guard fires — policy dropped, RLS_DENY_FILTER on the single-policy path — for an emptied membership at ODD effective polarity ANYWHERE in the compiled tree, and for the legacy solely-empty positive case:

1. bare positive { f: { $in: [] } } — pre-existing behaviour, preserved;
2. direct wrap { $not: { f: { $in: [] } } } — was allow-all, measured 5 of 5 fixture rows;
3. $not arm nested inside $or — the constant-TRUE arm made the whole $or allow-all (measured 5 of 5);
4. $not arm nested inside $and — the membership restriction silently evaporated (measured 3 of 5 where deny was intended);
5. $not over a composite containing the emptied membership ($and case is constant TRUE by De Morgan, measured 5 of 5; $or case reduces to the negation of the other arm — degenerate restriction, fail closed);
6. multi-level $not, odd depth (triple — measured 5 of 5);
7. multi-level $not, even depth, solely — constant FALSE; returns the sentinel instead of an always-false filter (same zero rows, one recognisable shape);
8. multi-key implicit AND under $not — constant TRUE by De Morgan;
9. defensively, empty $nin: [] (intrinsically constant TRUE — the read-scope SQL lowering renders it 1 = 1). Not emitted by cel-to-filter today; recognised so a future lowering cannot fail open through the same blind spot.

Deliberately NOT firing, matching pre-fix behaviour: a NON-empty membership under $not (the working not in feature, row-level pinned); an emptied POSITIVE membership nested in a composite ($or arm is inert — owner in empty-set || owner == me keeps granting own rows; $and arm is already constant FALSE); literal true (deliberate allow-all, compiles to {}); even-$not emptied membership nested inside a composite (inert constant-FALSE arm).

Before/after control (triage mandatory item 2)

Reverse-verified from the committed state, with the mutation and both restore legs proven on disk:

• restored rls-compiler.ts to base ff37576 (worktree only), proved the mutation landed (new-guard marker grep-count 0, old-docblock marker count 1), then ran a scratch harness asserting the BUGGY behaviour. It PASSED on base — measured: direct $not compiles {"$not":{"owner":{"$in":[]}}} and admits 5 of 5 rows via matchesFilterCondition; $or-nested 5/5; $and-nested 3/5; composite 5/5; triple-$not 5/5; bare-positive control already denied (0/5, the half that was green).
• restore leg proven by blob hash: disk blob equals HEAD blob 9360869c63f7554b34afcf015addf84ac35c053e, git status clean; the same harness against the fixed HEAD then FAILS 5 of 6 (every negated pin now gets the deny sentinel; only the unchanged positive control passes). The harness was deleted; the committed suite (rls-empty-membership-polarity.test.ts, 19 tests) asserts the AFTER state including row-level zero-admission for every enumerated shape.

No rebuild was needed for either leg: the suite imports ./rls-compiler.js relative source under vitest transform (no dist resolution for the mutated subject); @objectstack/formula (unmutated) resolves to its freshly built workspace dist.

Blast radius (triage mandatory item 3)

Declared in the changeset (.changeset/rls-empty-membership-polarity-guard.md): callers relying on the allow-all stop seeing rows — if a negated-membership policy was the only applicable policy and its set resolves empty, reads go from every row to zero rows. That prior behaviour was a defect, not a contract. Own-rows access that must survive an emptied set belongs in a separate OR'd policy (per-policy grants compile independently — pinned in the suite); deliberate allow-all remains authorable as literal true.

PM mechanism assumptions, measured

1. Fix belongs in the guard — in-repo, the analytics lowering's scope input is StrategyContext.getReadScope, wired to security.getReadFilter, i.e. this compiler's output, so post-fix the emptied-negated shape no longer reaches read-scope-sql.ts through the RLS path. The lowering site itself still carries the same polarity-dependent inference ($in: [] folds to FALSE_CLAUSE with a bare "safe" comment; $nin: [] folds to 1 = 1), and the contract type is fillable by non-RLS providers — reported as an out-of-scope finding rather than absorbed (see issue linked from the report).
2. tenant-layer.ts is the model — confirmed; it returns the spread deny sentinel on empty access sets. This fix reaches the identical sentinel through the existing drop-the-policy channel; no second convention.
3. No pin asserts the buggy behaviour — confirmed. Existing pins assert positive-polarity deny (security-plugin.test.ts: "should fail-closed for IN when org_user_ids is empty", "should fail-closed when a §7.3.1 membership set is empty"), and the formula-level pin ("empty membership array still compiles to $in:[] (caller decides)") explicitly delegates the decision to this caller. Full plugin-security suite: 91 files / 1684 tests green.

Verification (all at f7347eb)

• pnpm --filter @objectstack/plugin-security test — 91 files, 1684 passed (includes the new 19).
• pnpm --filter @objectstack/plugin-security typecheck — green; --listFiles confirms both rls-compiler.ts and the new test file are inside the tsc programs (1 hit each).
• All 35 gate families derived by scripts/pm/dispatch-gates.mjs from this diff: 33 green (incl. check:engine-double-contract, check:where-matcher, check:type-check-debt re-measure with zero surplus, check:i18n, check:cross-package-test-inputs); 2 NOT MEASURED by design per their own exit-3 text (check-test-completeness grades a saved CI turbo log; check-half-states needs a GitHub credential this container lacks). check:nul-bytes green. Repo-wide pnpm lint (eslint, no-inline-config) exit 0.
• Census disjointness re-confirmed on this tree: zero isSystem reads in rls-compiler.ts, zero census anchors on it.

The isEmptyMembershipFilter export is for direct shape tests only; index.ts deliberately does not re-export it, so the package surface is unchanged.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

6 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 14 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json b9972720f843033d24ec657f3d17b75435fca74a → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 10353670aaac809e0e383f394ef281acd726fde5 — the merge of head f7347eb7675479afbdd01f5c39e883151a360e96 into base b9972720f843033d24ec657f3d17b75435fca74a, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 10353670aaac809e0e383f394ef281acd726fde5 && git checkout 10353670aaac809e0e383f394ef281acd726fde5
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin b9972720f843033d24ec657f3d17b75435fca74a f7347eb7675479afbdd01f5c39e883151a360e96 && git checkout -B drift-repro b9972720f843033d24ec657f3d17b75435fca74a && git merge --no-ff f7347eb7675479afbdd01f5c39e883151a360e96

node scripts/docs-audit/affected-docs.mjs --json b9972720f843033d24ec657f3d17b75435fca74a

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.