fix(plugin-security): explain fails closed when a dependency it shares with enforcement throws

[objectstack-fleet]

Fixes #20002

Clause-②: no

The security/explain route promises that it runs 「the same code paths the enforcement middleware runs」. Enforcement does not catch a failure in those calls, so the request fails. The explain engine caught the same failure and turned it into a value that its record matcher reads as an answer. So a request that fails was reported as one that succeeds. This is the same defect class as #19963 and #19986 (PR #19984, PR #20000): explain and enforcement give two different answers. Enforcement is not touched. This PR changes the report only.

Measurement first (on origin/main fc6ddb87a4, before any fix)

The stack is the real SecurityPlugin + SharingService + both middlewares over one in-memory engine, in the shape of PR #20000's test file. For each caught fall-back in explain-engine.ts, the dependency was made to fail, and the same request was run through both middlewares. Commit 02067686d4 adds the test file that pins the fix. On the unfixed engine its 10 fault cells are red and its 6 controls are green. The commit message carries this table.

Site	Caught into	What explain reported when the dependency failed	What enforcement did	Verdict
:848 fetchRecord	null	Record not found: visible: false, no decidedBy	The find throws on the same store fault	Fails toward not visible. Left as is. The plugin's own binding already catches to null, so in this wiring this catch is never reached.
:858 computeLayeredRlsFilter	{ layer0: null, layer1: null }	allowed: false (the object-level catch denies), but record.visible: true for a shared row, an owned row and an org-depth row	The find throws the injected error	Fails OPEN at row level, and contradicts allowed. Changed.
:941 listRecordShares	[]	Verdict unchanged, because the read filter decides it. rules[] is empty	Unaffected: enforcement never calls listShares	Only the attribution changes: it can only drop an admits rule. Left as is.
:958 sharingReadFilter (the card)	null	Share store down, own-depth reader: visible: true on the unshared, shared and owned rows. Sharing is admitted with rowFilter: null	The find throws the store error	Fails OPEN. Changed.
:966 write gate (canEdit / canDelete)	undefined ("no gate wired")	Update on an owned row: visible: true (private and public_read). On a row with only a READ share, sharing reported admitted	The by-id PATCH throws the injected error	Fails OPEN. Changed.
:1128 resolveSets	[]	allowed: false, decidedBy: object_crud	403 PERMISSION_DENIED	Fails toward deny. Left as is.
:1140 resolveDelegatorContext (not on the dispatch list, found by the same sweep)	{ kind: 'none' } ("no delegation")	Delegator's grant store down: allowed: true, principal neutral. The D10 intersection was dropped (a healthy delegator gives allowed: false)	503 SERVICE_UNAVAILABLE	Fails OPEN (object-level allowed). Changed.
:1147 delegator resolveSets	[]	allowed: false, decidedBy: object_crud	The find throws	Fails toward deny. Left as is.

Two storage-level controls from the same probe:

• With the share store down, an org-depth reader's read filter answers null before it reads a share, so both sides admit.
• The per-record gate catches its own store faults (writeGateFailClosed), so an update during the same outage already got the same answer from both sides.

What changed

In packages/plugins/plugin-security/src/explain-engine.ts:

• The helper. A settle helper keeps a failure apart from every value the call can return: it returns a DEPENDENCY_FAULT sentinel instead. It is used only at the four fail-open sites.
• Sharing read filter and write gate. The sharing layer's record outcome is not_evaluated, with no rowFilter and no matchesRecord. Its detail says the layer could not be evaluated and that the request fails on the same call. record.visible is false, with decidedBy: 'sharing'.
  • The call that is checked is the one the operation's verdict depends on: the read filter for a read, and the per-record gate for a write.
  • It is checked before the OWD, because the sharing middleware calls it whatever the OWD is.
• Layered RLS composition. The tenant_isolation and rls record attributions are not_evaluated, with a detail that names the failure. record.visible is false, with decidedBy: 'rls'. This matches the object-level rls layer, which already reports the same failure as a denial.
• Delegator resolution. A new delegatorUnresolved flag fails closed like a missing delegator. principal and object_crud deny with their own wording, and allowed is false.
• Order in the record verdict. Unchanged first: capability, CRUD, missing record, tenant exclusion, RLS exclusion. Then an RLS-composition failure, then a sharing failure. This follows the pipeline, where the RLS composition runs before the sharing middleware.

Outcome vocabulary. ExplainRecordAttributionSchema.outcome in packages/spec/src/security/explain.zod.ts is admitted | excluded | not_evaluated. The engine already uses not_evaluated for "Tenant layer split is unavailable on this engine build" and for a record that is not found. So not_evaluated plus a detail that names the failure says "could not be evaluated". The response has no new value and no new key, and packages/spec is not edited.

Not changed:

• security-plugin.ts. PR fix(plugin-security, objectql)!: a by-id update's row-level check holds for the row it stores #20012 has since landed there, and this branch merges it.
• default-permission-sets.ts.
• packages/spec.
• Enforcement.

Tests

The new file packages/plugins/plugin-security/src/explain-dependency-fault.test.ts uses the real SecurityPlugin + SharingService + both middlewares over one in-memory engine. Each fault cell asserts both sides:

• Explain: record.visible === false with the named decidedBy, and the layer is not_evaluated with no rowFilter and no matchesRecord.
• Enforcement: the same request through both real middlewares fails with the injected fault itself, compared by identity. For the delegator, the cell asserts the ADR-0112 envelope: SERVICE_UNAVAILABLE / 503.

The fault cells:

• Share store down × unshared / shared / owned row (read), and buildReadFilter failing on a public_read object.
• canEdit failing × owned row (private and public_read).
• computeLayeredRlsFilter failing × read-shared / owned / org-depth row. These cells also assert allowed: false.
• Delegator's grant store down (sys_user_position): allowed: false, and principal and object_crud deny.

The controls:

• A healthy shared row: admitted, decidedBy: sharing.
• A healthy unshared row: excluded.
• An org-depth reader whose filter answers null while the share store is down: still admitted, because only a failure is a fault.
• A healthy update gate, a healthy tenant wall, and a healthy delegator (principal neutral).

Ablation of every negative pin, on HEAD e8e677786a. Each leg put one swallowing catch back with scripts/ablation-replace.mjs. The anchor went from 1 hit to 0, and the file's blob changed on disk. The test file then went red on exactly that site's cells. Each leg restored the file: blob fca6431074ac equals HEAD, and git diff HEAD is empty.

Leg	Catch put back	Red	Green
A1	:958 .catch(() => null)	4, the read-filter cells (record.visible: expected true to be false)	12
A2	:966 .catch(() => undefined)	2, the write-gate cells	14
A3	:858 .catch(() => ({ layer0: null, layer1: null }))	3, the layered-RLS cells	13
A4	:1140 .catch(() => ({ kind: 'none' }))	1 (allowed: expected true to be false)	15

The test reaches the code under test through relative src imports (./security-plugin.js → ./explain-engine.js), so no dist sits between the mutation and the run.

Runs on HEAD e8e677786a, after merging origin/main at 44639665ee:

• @objectstack/plugin-security: typecheck exits 0, and tsconfig.test.json lists the new file. The full suite passes: 130 files, 2541 tests.
• Consumers of the explain route, found with grep -rln "security/explain\|explainAccess" packages --include=*.test.ts:
  • rest: security-routes, security-explain-envelope, rest-write-response-internal-fields.tripwire: 45/45.
  • plugin-sharing: sharing-service: 131/131.
  • client: client.test: 217/217.
  • dogfood: api-key-owner-revoke, owd-public-read-write-write-floor, showcase-d7-default-profile: 23/23.
  • spec: type-alias-convention.pin, explain-zero-rows-sentinels.pin: 11/11.
  • objectql: engine-middleware-operation-vocabulary: 5/5.
• Gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands on this HEAD derives 71 commands, and all 71 ran.
  • check-changeset-fixed, check:error-code-casing and check:filter-alias-parity also ran, because their rosters sit under paths this diff touches.
  • Reconciliation, with every line recorded with its exit code: Run reconciliation — 71 derived, 71 run, 0 NOT-MEASURED, 0 UNRUN.
  • check:type-check-debt first answered PREREQUISITE NOT MET, because the plugin-security dist was older than its sources. After a rebuild it answered OK — 4 ledger entr(ies) re-measured … none above its recorded number.
• Lint, narrowed to the changed files. eslint --no-inline-config --format json on the two changed TS files: 2 files, 0 errors, 0 warnings.
  • The changeset and the JSON ledger are outside eslint's configured file set ("File ignored because no matching configuration was supplied").
  • The config never enables type-aware linting (no parserOptions.project), so this diff cannot change the lint result of any other file.

Also in the diff

• scripts/engine-double-contract.pinned.json: one row added (explain-dependency-fault.test.ts, findOne), regenerated with --write. check:engine-double-contract (RETAINED) needs the coverage ledger to record every new pinned double. No row was lost.
• .changeset/20002-explain-sharing-fault.md: @objectstack/plugin-security: patch, Clause-②: no. The report now matches what enforcement already does, and no accept set moves.

Acceptance notes

• No log line is added at the four sites. The suggested route said to log the failure the way enforcement does, but I did not, for two reasons:
  • The explain engine has no logger dependency, and wiring one would mean editing security-plugin.ts, which is out of scope here.
  • AGENTS.md "Degradation log levels" says that a failure delivered to the caller is not a degradation. The report delivers it: not_evaluated, a detail, and a fail-closed verdict. The real request's failure shows up on the request that fails.
• The detail names the failure, not the thrown message. Explaining your own access needs no capability, so a raw store error message would reach an ordinary caller.
• :848 and :941 word a failure imprecisely. They still say "Record not found" or "0 share(s) attached". Their verdicts fail toward not visible, so they are left as is.
• The tenant_isolation layer-level verdict stays not_applicable under a layered-RLS failure. That code is unchanged, and the verdict enum has no "unknown". The record attribution carries the failure.
• A spec describe text does not mention failures. ExplainRecordAttributionSchema.outcome's describe text reads "not_evaluated (skipped/not row-scoped)". The engine already uses the value for "unavailable", so this is a docs detail in packages/spec, and it is not edited here.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

4 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

• 1 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 26550c6603a920c28f04ca94b039388069ecbaad → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 26550c6603a920c28f04ca94b039388069ecbaad

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