fix(plugin-security): security/explain answers enforcement's refusal for a row-level policy comparing two fields of no shared comparison class

[objectstack-fleet]

Fixes #20431

Clause-②: no

What was wrong

A row-level policy can compare two fields that share no comparison class, for example a text field against a number field. Enforcement refuses every request such a policy scopes. The find answers INVALID_FILTER / 400. A by-id update or delete fails closed at its row-level gate (403), because that gate's pre-image read is the same refused read.

The record-grained explanation judged the same predicate in-process without the object's declared columns. It compared the two raw values and reported a record verdict: visible: true for one ordering of a pair, and visible: false (rls excluded) for the other. Both answers covered a request that enforcement refuses.

What changed

The landing point is packages/plugins/plugin-security/src/explain-engine.ts, as the dispatch expected; the other files are the pin file and the changeset. There are no changes to security-plugin.ts, packages/formula, packages/spec, the REST layer, or enforcement.

• The record matcher (matchesFilterCondition) now receives the object's declared columns (options.fields), as the RLS write check does. They are read from ql.getSchema(object): the schema the engine already reads for the OWD, and the ObjectQL registry that the find's driver compiles against. A schema that cannot be read hands over no columns, and the matcher judges values only, as before.
• With the columns, the matcher refuses the comparison. Explain answers with that refusal: the explanation fails with INVALID_FILTER / 400 (the matcher's code and status, the envelope the find answers with), and no record verdict is reported. The message names the policy and both fields with their declared types. The matcher's own error rides as cause.
• Naming the fields discloses nothing new. The report explain gives the same caller for the same object already publishes that predicate (readFilter, or the rls layer's rowFilter).

Why a refusal and not a fail-closed report: dispatch assumption A3 did not hold

A3 said to reuse PR #20030's shape (layer not_evaluated, record.visible: false) for "enforcement refuses this read". Measurement on main says otherwise:

• Explain already answers the matcher's other INVALID_FILTER refusals as a refusal.
• rls-stored-list-ordering-fails-closed.test.ts (landed in de091b50, PR fix(formula)!: refuse an ordering comparison whose stored operand holds a list or an object #20310) pins it: "explain read 400 = find 400; explain update 400, the by-id update 403". One of its cells is a field-to-field comparison against a list-holding field.
• PR fix(plugin-security): explain fails closed when a dependency it shares with enforcement throws #20030's shape covers a dependency call that fails, not a predicate the matcher refuses.

My first commit used the report shape. The full plugin-security suite then turned 2 cells of that landed pin red, because its field-to-field cell is now caught first by the comparison-class rule. Keeping the report shape would have added the second refusal dialect the dispatch forbids. So this PR follows the ruling's intent: "the read is refused … both orderings answer the same refusal as find".

Measurement: before and after (better-sqlite3, the same stack as the pins)

policy class	find	by-id update / delete	explain read / update / delete, before	after
text vs number	400 INVALID_FILTER	403 PERMISSION_DENIED	visible: true, decidedBy: 'rls', rls admitted	refused, 400 INVALID_FILTER
number vs text (the other ordering)	400 INVALID_FILTER	403 PERMISSION_DENIED	visible: false, decidedBy: 'rls', rls excluded	refused, 400 INVALID_FILTER
text vs text (control)	the row	admitted	visible: true, decidedBy: 'rls'	unchanged

Tests

New file: packages/plugins/plugin-security/src/explain-cross-class-refusal.test.ts. It uses the real SecurityPlugin, ObjectQL and SQL drivers (better-sqlite3 and sqlite-wasm; PostgreSQL when OS_TEST_POSTGRES_URL is set), on PR #20427's harness. Every refused cell asserts both halves with their envelope code and status: explain's answer, and the caller's real request.

• Five cells: text vs number, text vs image, text vs formula, text vs json, and number vs text. Each checks read, update and delete. Explain answers { code: 'INVALID_FILTER', status: 400 } and its message names the policy and both fields. Find answers INVALID_FILTER / 400, update and delete answer PERMISSION_DENIED / 403, and nothing is stored.
• Both orderings of one pair get { find: INVALID, explain: INVALID }.
• Control, same class: find returns only the matching row. Explain reports visible: true / admitted for it and visible: false / excluded for the other row. The update is admitted and matches explain.

Pre-fix run: main's explain-engine.ts restored from the base blob 92716c91, under a trap whose restore is proven by the HEAD blob and an empty git diff HEAD. Result: Tests 12 failed | 2 passed | 7 skipped (21). The 2 passes are the controls.

Ablation: only the declared-columns argument was removed, through scripts/ablation-replace.mjs. The anchor hit 1 → 0 and the blob went a46456db → 5a314958. Result: Tests 12 failed | 2 passed | 7 skipped (21). Every refused cell on both drivers failed:

AssertionError: expected 'answered' not to be 'answered' // Object.is equality
AssertionError: expected { find: { …(2) }, explain: 'admitted' } to deeply equal { find: { …(2) }, explain: { …(2) } }

Restore: ok restored: blob == HEAD (a46456db6b87) and git diff HEAD is empty.

All figures below were measured at 5e48f52c, the head after merging origin/main c876a742:

• pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2: Test Files 144 passed (144), Tests 3066 passed | 23 skipped (3089).
• pnpm --filter @objectstack/plugin-security typecheck: exit 0, with the test layer OK. tsc -p tsconfig.test.json --listFiles counts the new file once.
• Gates: node scripts/pm/dispatch-gates.mjs --commands derived 64 commands, and all 64 ran with exit 0. Three first answered exit 3 PREREQUISITE NOT MET (check:dual-build-cjs-loads, check:i18n, check:type-check-debt). I rebuilt with turbo run build --filter='./packages/*' --filter='./packages/*/*' (71/71 tasks) and re-ran them; all three answered exit 0. dispatch-gates --ran: 64 derived, 64 run, 0 NOT-MEASURED, 0 UNRUN.
• Lint, narrowed: eslint --no-inline-config --format json over the two touched .ts files gives 2 files, 0 errors, 0 warnings. eslint --print-config shows no parserOptions.project / projectService. Linting is not type-aware, so this diff cannot move any untouched file's verdict.

Acceptance notes

• The REST door answers 500 for this refusal. The explain route's catch maps only PERMISSION_DENIED → 403 and OBJECT_NOT_FOUND → 404; every other throw becomes 500 EXPLAIN_FAILED. I measured it through the real handler (security-explain-envelope.test.ts harness): a service refusal carrying INVALID_FILTER / 400 comes back as { status: 500, error: { code: 'EXPLAIN_FAILED', message: … } }. The refusal's message survives. PR fix(formula)!: refuse an ordering comparison whose stored operand holds a list or an object #20310's refusals were already answered this way. It lives in packages/rest/src/rest-server.ts, outside this card's surface, so it is reported, not fixed here.
• The object-level answer is unchanged. An explanation without a recordId runs no record matcher. For a read under such a policy, it still reports allowed: true and rls narrows, where the find answers 400. This PR does not change that; it is reported separately.
• Missing record, not measured. When the record does not exist, the matcher never runs, so explain keeps its missing-record answer (visible: false, no decidedBy) for a policy the find would refuse.
• Duplicated attribution. The policy-name attribution (refusedPolicyNamesOf) copies the RLS write check's attribution in security-plugin.ts. That file is held by security: with no active organization, resolvePermissionSetsForContext reads the principal's position names as permission-set names organization-less, and sys_permission_set.name has no reserved-identity guard (NOT MEASURED; from PR #20540's review) #20555, so one shared helper is left to whoever next touches both files.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

9 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 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 15 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 e666636fd99a363d76753f5455a5708b9c9876cb → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bde09535620e3aa3330d88bf71a4c88065713447 — the merge of head 5e48f52c2464ecb8c6b1cded5103f1f3151d695a into base e666636fd99a363d76753f5455a5708b9c9876cb, 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 bde09535620e3aa3330d88bf71a4c88065713447 && git checkout bde09535620e3aa3330d88bf71a4c88065713447
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin e666636fd99a363d76753f5455a5708b9c9876cb 5e48f52c2464ecb8c6b1cded5103f1f3151d695a && git checkout -B drift-repro e666636fd99a363d76753f5455a5708b9c9876cb && git merge --no-ff 5e48f52c2464ecb8c6b1cded5103f1f3151d695a

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

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 5e48f52c2464ecb8c6b1cded5103f1f3151d695a
Local-runs: none

PR #20598 for card #20431, fix(plugin-security): security/explain answers enforcement's refusal for a row-level policy comparing two fields of no shared comparison class. Inputs: the card body and its six comments (triage direction, the shape-2 pointer and its retriage answer, the unlock reading, the claim, the os-dev-report), the PR body and file list, the net diff against main at the merge base (3 files, +396 / −6: .changeset/20431-explain-cross-class-refusal.md, packages/plugins/plugin-security/src/explain-cross-class-refusal.test.ts new, packages/plugins/plugin-security/src/explain-engine.ts), and the check-runs on the head. Check-runs as read: 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke — path and opt-in skips), 0 failed, 0 in progress. Governed Surface Queue Guard success: none of the three paths is a governed surface.

① Derived judgments

1. Public surface of @objectstack/plugin-security: unchanged — RIGHT. src/index.ts re-exports explainAccess, buildContextForUser and the types ExplainEngineDeps, ExplainInput from explain-engine.ts; none of them moves. The four new functions (declaredColumnsOf, refusedPolicyNamesOf, crossFieldRefusalForExplain, and the try/catch inside matches) and the new declaredColumns member sit on module-private symbols (RecordAttributionContext is not exported). ExplainDecision in @objectstack/spec is untouched: no field, no variant, no new error code. Nothing widens.
2. The explain service's answer for a record-grained request under a cross-class policy: 200 with a record verdict becomes a refusal carrying INVALID_FILTER / 400 — RIGHT, and the refusal route (not a not_evaluated report) is the right route. The card's direction (triage comment 5871369352) is in its own words "the read is refused … report the refusal with enforcement's code … never report a visible verdict for a read that enforcement cannot run"; the fail-closed report shape was a dispatch assumption, not a ruling. On main a matcher throw inside matches() already propagates out of applyRecordAttribution as a refusal — the settle/DEPENDENCY_FAULT machinery catches dependency calls (computeLayeredRlsFilter, sharingReadFilter), never the matcher — and the landed pin rls-stored-list-ordering-fails-closed.test.ts (stage 2e) fixes that dialect: "explain read 400 = find 400; explain update 400, the by-id update 403". A report shape here would have been a second dialect for the same matcher family and would have reddened that pin; the dev measured exactly that and reverted.
3. Column source — RIGHT, with one residual named. declaredColumnsOf(schema) reads fields off the schema the engine already takes from ql.getSchema(object) for the OWD, the ObjectQL registry the find's driver compiles against. It accepts only the record shape and has no metadata-service fallback, where the write check's writeCheckFieldOptions (security-plugin.ts) also accepts array-shaped fields, falls back to metadata.get, and projects { type, multiple }. For parity with the find this is sound: an object the registry does not know is refused earlier as OBJECT_NOT_FOUND, the registry keeps fields as a record, and a schema with no readable fields yields values-only judging — the same "a schema that cannot be loaded must not manufacture refusals" posture the write check documents. The changeset states it under Unchanged. Not a defect; the normalisation belongs in the shared helper flagged in ③ F3.
4. The columns are handed to every matches() call (tenant layer 0, sharing read filter, business layer 1), not only layer 1 — RIGHT. The comparison-class rule is driver-sql's query compiler's and is source-agnostic, so a cross-class field comparison arriving through a sharing-rule predicate refuses the find the same way. For a non-policy filter refusedPolicyNamesOf returns nothing (the WeakMap in rls-compiler.ts tags compiled policy filters only) and the message falls back to "A row-level filter on …" — graceful, no wrong attribution.
5. Envelope — RIGHT. crossFieldRefusalForExplain copies code and status from the matcher's own error (crossFieldClassError always sets INVALID_FILTER / 400) and rides the original as cause; it wraps only when crossFieldClassRefusalCarriedBy(e) answers and columns were supplied, re-throwing everything else unchanged, so the matcher's other refusals (#5240 zero-operator constraint, #19886 array comparand and stored-list ordering) keep their existing envelope and message. Policy attribution mirrors the compiler's composition exactly: one policy's filter, or { $or: [...] } of them, each member identity-tagged by RLSCompiler.compileFilter. Test Core green on the head confirms the tagged identity survives the layered split (the pins assert the policy name in the message).
6. Disclosure, described abstractly — acceptable on this surface, boundary stated. The message carries the matcher's diagnostic (both columns with declared types) and the policy name, where @objectstack/formula documents the diagnostic as server-side only. On explain — and only there — the same principal already receives the composed predicate: rowFilter on the rls layer's record attribution, readFilter for read/export, and rules[].predicate. Both column names are therefore already published to that caller; the declared types and the policy name are the increment, and explain is the disclosure surface by construction (the card: explain exists to tell a builder or an admin what enforcement will do). The enforcement paths (the find, the write check) keep withholding. ⛔ The boundary: this wording must not travel into the find's or the write check's envelope.
7. Object-level explain (no recordId) is byte-identical — RIGHT for this card's scope. It runs no matcher, so it still answers allowed: true and rls narrows with the refused predicate as readFilter. The card scoped the record attribution; the dev reported the object-level gap rather than folding it in (③ F2).
8. Pins — RIGHT. explain-cross-class-refusal.test.ts drives the real SecurityPlugin, ObjectQL, driver-sql (better-sqlite3) and driver-sqlite-wasm, PostgreSQL opt-in. Every refused cell asserts both halves with code and status: explain's refusal (message naming the policy and both columns), the find's INVALID_FILTER / 400, the by-id update and delete PERMISSION_DENIED / 403, and nothing stored. Five pairs cover the cross-class verdict (text vs number, and the reversed ordering) and the three no-class kinds (file, formula, json); both orderings get one answer; the same-class control keeps its row verdict on both sides for read and update. The pre-fix and ablation runs in the PR body (12 failed / 2 controls passed in both) are the dev's readings, not re-run here. tsconfig.test.json includes src/**/*, and typecheck names it through check:test-typecheck, so the file is compiled by a tsc program. No cross-package reads.
9. Changeset prose (a reviewed surface) — accurate. The refused classes it names are exactly the cross-class and no-class verdicts of findCrossFieldClassRefusal; the Unchanged list (enforcement's accept set, same-class verdicts, unreadable schema, object-level answer) matches the diff.

② Semver level

• @objectstack/plugin-security is published (version 17.4.0, exports map, not private), so a changeset is owed and skip-changeset does not apply. The declared level is patch — RIGHT: a bug fix in a released package, no new export, field, variant or registration, nothing authorable removed or renamed.
• The Clause-② line reads no with no arm, at line start in both the PR body and the changeset — RIGHT on both halves. no: none of the four widening tells appears in the diff and the public surface is unchanged (①1). No (narrowing) arm — the dev's flagged question, answered: the arm marks a diff that narrows a published accept set. The accept set at issue — row-level policies comparing two columns of no shared comparison class — is narrowed by .changeset/20355-rls-write-check-cross-class.md (Clause-②: yes (narrowing), BREAKING banner, adr-0087 registered rls-predicate-cross-class-field-comparison-refused), pending at this head in the same unreleased version of @objectstack/plugin-security; that changeset already states every read such a policy scopes is refused INVALID_FILTER / 400 on the SQL drivers. This diff refuses no spelling the declared contract accepts; it pulls the reporting face back to that contract, which the directional ruling (check-widening-tells.mjs header: pulling code back to the declared contract does not trigger the clause) excludes. The prescription a consumer needs — compare a field only with a field of the same class, or fix the declaration — is the registered one, and the new message repeats it. In-tree precedent agrees: .changeset/19886-stored-list-ordering-refused.md declared its narrowing once, on the matcher, and described explain's 400 as a consequence ("Explain itself is unchanged"); the explain-correction changesets 19963, 19986 and 20002 are patch with no. A no (narrowing) here would register the same narrowing a second time and demand a BREAKING banner for a change that adds no narrowing of its own.
• ADR-0087: no breaking signal (no major, no BREAKING banner, no narrowing arm), so no disposition marker is owed and the gate is not triggered. Check Changeset is success on the head.
• Wire note for the seat, not a semver fact of this diff: at the REST door this refusal surfaces as 500 EXPLAIN_FAILED (③ F1), as PR fix(formula)!: refuse an ordering comparison whose stored operand holds a list or an object #20310's refusals already do.

③ Boundary flags

open_questions: none. Deviations (5) and out-of-scope findings (4) from os-dev-report 5884664237, each answered or escalated:

• D1 — route: refusal instead of the A3 fail-closed report shape. ANSWERED, accepted (①2). The refusal is the card's ruling in its own words; the report shape covers a dependency call that fails, not a predicate the matcher refuses.
• D2 — Clause-②: no versus no (narrowing). ANSWERED in ②: no arm; patch stands.
• D3 — pin harness: PR fix(security)!: the RLS write check refuses a field-to-field comparison the read refuses — one comparison class, one answer per policy (#20355) #20427's real-driver harness instead of the in-memory double. ANSWERED, accepted. The double cannot produce the driver's refusal, so only the real stack can assert both halves of a cell; the both-halves-per-cell shape is kept.
• D4 — history: superseded first commit and a merge commit on the branch. ANSWERED: landing mechanics only; the queue's squash folds both. Nothing to act on.
• D5 — no labels written. ANSWERED, correct: skip-changeset does not apply to a diff that publishes from a released package; the labels on the PR are the Auto Label job's.
• F1 — the REST door answers a service refusal carrying INVALID_FILTER / 400 as 500 EXPLAIN_FAILED. Verified on the head: the explain handler's catch in packages/rest/src/rest-server.ts maps only PERMISSION_DENIED (403) and OBJECT_NOT_FOUND (404) and sends every other throw to 500; the batch form (recordIds) fails the whole batch on one refused record. Pre-existing for PR fix(formula)!: refuse an ordering comparison whose stored operand holds a list or an object #20310's refusals; outside this card's file surface. ESCALATE: its own card in the explain-versus-enforce family (class a, public door). Not a blocker: the service contract is right and the door owns the transport mapping.
• F2 — object-level explain still reports allowed: true / rls narrows for a predicate the find refuses. ESCALATE to triage: same file, a different pass than the record attribution this card scoped; fold into the family (plugin-security: security.explain shows a member removed from an organization that organization's grants, which enforcement refuses since PR #20540 (explain ≠ enforce, split from #20431) #20580) or a separate card. Not a blocker.
• F3 — refusedPolicyNamesOf duplicates the write check's attribution in security-plugin.ts, held by security: with no active organization, resolvePermissionSetsForContext reads the principal's position names as permission-set names organization-less, and sys_permission_set.name has no reserved-identity guard (NOT MEASURED; from PR #20540's review) #20555. ANSWERED, accepted as noted; carrier security: with no active organization, resolvePermissionSetsForContext reads the principal's position names as permission-set names organization-less, and sys_permission_set.name has no reserved-identity guard (NOT MEASURED; from PR #20540's review) #20555 / plugin-security: security.explain shows a member removed from an organization that organization's grants, which enforcement refuses since PR #20540 (explain ≠ enforce, split from #20431) #20580. The column-source normalisation gap in ①3 belongs to the same shared helper.
• F4 — a missing record under a cross-class policy keeps the missing-record answer (visible: false, no decidedBy), where the find is refused. ANSWERED, accepted as not measured; the matcher never runs on a missing record. Low severity, a residual asymmetry — fold into F2's card.

Implemented-by: claude/issue-20431-explain-cross-class-refusal
Reviewed-by: session_01XY5uCwTjZj7884yYtyur4H

VERDICT: PASS

---

Generated by Claude Code