fix(plugin-security): explain's record read verdict asks sharing with the caller's read depth

[objectstack-fleet]

Fixes #19986

Clause-②: no

What changes

POST /api/v1/security/explain with { object, operation: 'read', recordId } now asks plugin-sharing's read filter with the same read depth the find path hands it. decision.record.visible for read equals whether the same caller's find returns the row. Enforcement admits and refuses exactly what it did before. Only the explain report changes.

Landing: packages/plugins/plugin-security/src/security-plugin.ts (the explainAccessForCaller dependency wiring only), a new test file, the changeset, and one generated row in scripts/engine-double-contract.pinned.json (see "Surface note"). The step-3.6 post-image block and the seam declaration are untouched. The producer is the explain wiring, as the card says; no other package is involved.

The two sides, quoted on origin/main ccccdcc35e before the change

• Explain (security-plugin.ts:4426): sharingReadFilter: (o: string, c: any) => sharing.buildReadFilter(o, c). The bare context, no __readScope.
• The find path, step 2.6 (security-plugin.ts:2375, :2403): for find / findOne / count / aggregate on a non-delegated context, sc.__readScope is set to this.permissionEvaluator.getEffectiveScope('read', opCtx.object, permissionSets, { isPrivate: secMeta.isPrivate }). permissionSets comes from resolvePermissionSetsForContext and secMeta from getObjectSecurityMeta. plugin-sharing's buildReadFilter then reads it: org gives no owner filter (null), and a unit depth gives the unit's owners.
• The resolver already exists. resolveSharingReadFilter (security-plugin.ts:4490 after this change; it is the analytics path's seam) computes the depth from the same two inputs and the same evaluator call, stamps it, and calls buildReadFilter. Its docblock names the situation explain is in: no middleware runs on this path, so the depth is computed there. The change reuses it. Nothing new is computed.

Reproduced before the change

The new test file was committed first on the unfixed tree (07f447e0c0, base ccccdcc35e). It wires the real SecurityPlugin, the real SharingService and sharing middleware, and the real platform member_default seed. The object has an unset OWD (private). The one variable is the principal's read depth, on the same three rows:

principal (read depth)	row	explain record	find
hr_reviewer (org)	shared to someone else	visible: false, decidedBy: sharing	returns it
hr_reviewer (org)	owned by someone else	visible: false, decidedBy: sharing	returns it
hr_reviewer (org)	unshared	visible: false, decidedBy: sharing	returns it
team_lead (unit)	owned inside the unit	visible: false, decidedBy: sharing	returns it
dept_reporter (own), the control	read-shared / owned / unshared	true / true / false	returns / returns / refuses: agrees

Result: Tests 7 failed | 17 passed (24). The seventh red is a second direction on the old binding. A __readScope: 'org' already present on the explained context decided the report (dept_reporter × unshared: explain true, find refused), because the bare context was passed straight through.

The change

• The non-delegated sharingReadFilter binding calls resolveSharingReadFilter(o, { ...c, __readScope: undefined }). The caller's own key is cleared first, so the depth is always the computed one, the way step 2.6 overwrites it. Where resolution yields nothing (no sets, or a failed resolution), the helper stamps nothing and plugin-sharing reads own, the safe direction.
• On-behalf-of contexts keep sharing.buildReadFilter(o, c) unchanged, as fix(plugin-security): explain's record update/delete verdict uses the by-id write path's inputs #19984 did on the write side. The middleware's delegated read (the agent-leg depth, plus a second filter AND-ed in under the delegator's identity) is not modelled on explain's record path. Stamping the agent's own depth without that second filter could only widen the report.
• delegatedWrite is renamed actsOnBehalfOf: it now guards read and write bindings, and delegated is already a name inside this function (the delegated-admin gate).

Tests: explain-read-verdict-inputs.test.ts (24 cases)

Every cell asserts that record.visible for read equals whether the find returns the row, and it asserts the find's own answer too. A cell cannot go green because both sides drifted. The find runs through both real middlewares, and the engine double evaluates the composed AST where. The double's matcher throws on an operator it does not know, so a refused cell cannot go green because the double silently answered false. Both sides read one hierarchy resolver: unit = the lead and the reporter.

• Read matrix, private OWD: builtin admin × unshared; hr_reviewer (org) × shared / owned / unshared; team_lead (unit) × owned inside the unit / owned outside it / shared to someone else; dept_reporter (own) × read-shared / owned / unshared. Negative control: dept_reporter × unshared, refused by both, and explain names sharing (layer excluded).
• Depth: the org reader's sharing layer is admitted with rowFilter: null. A __readScope the caller brings does not decide the report, in either direction: dept_reporter + 'org' × unshared is refused by both, and hr_reviewer + 'own' × unshared is admitted by both.
• On-behalf-of: the context explain hands plugin-sharing's read filter carries no __readScope.
• OWD control public_read: all nine principal × row cells admit on both sides.

Unfixed tree: Tests 7 failed | 17 passed (24). Fixed (461187a0d2) and at the final head: Tests 24 passed (24).

Ablations

The fix was committed first (461187a0d2). Each mutation used scripts/ablation-replace.mjs: the anchor went from 1 hit to 0, the replacement from 0 to 1, and the blob changed on disk. After each restore the blob matched HEAD (229605a70e3a) and git diff HEAD was empty. The test imports ./security-plugin.js from source, so there is no dist/ hop and ablation-dist-preflight does not apply. Directions were predicted before each run.

ablation	mutation	result
A	the old binding: sharing.buildReadFilter(o, c) for every context	7 failed / 17 passed: hr_reviewer × 3, team_lead × owned inside the unit, the org layer pin, and both caller-depth pins. The widening one reads u_reporter × unshared × read: … expected true to be false. The plain visible: false cells stay green, as predicted: the old binding is narrower and cannot widen.
B	over-widening: every non-delegated context asked at __readScope: 'org'	5 failed / 19 passed: every visible: false pin (team_lead × unshared, team_lead × shared, dept_reporter × unshared, the negative control, the widening caller-depth pin), each expected true to be false.
C	the on-behalf-of guard dropped	1 failed / 23 passed: the on-behalf-of pin (no read depth stamped on a delegated context: expected true to be false).
D	the caller-key clear dropped: resolveSharingReadFilter(o, c)	24 passed, as predicted. The clear matters only where depth resolution yields nothing, and there explain's own CRUD layer already refuses, so record.visible cannot show it. It is declared, unpinned hygiene.

The first C attempt was a no-op. Its replacement text was a substring of its anchor, so ablation-replace saw the replacement count stay at 1, refused with exit 1, and ran no tests. The re-run with a distinct marker is the row above.

Local verification: final head 8644de0cbe

• pnpm --filter '@objectstack/plugin-security...' build: exit 0.
• Full plugin-security vitest run: Test Files 124 passed, Tests 2365 passed, at 6471f5564d. Later commits add only the ledger row and a main merge whose source changes sit in packages/mcp and packages/runtime, outside plugin-security's build closure. The three explain suites re-ran at 8644de0cbe: Tests 138 passed (138).
• pnpm --filter @objectstack/plugin-security typecheck: exit 0. The new test is in tsconfig.test.json's program (--listFiles: 1 hit) and check:test-typecheck is OK.
• dispatch-gates --commands at 8644de0cbe, reconciled with --ran: 70 derived, 68 run with exit 0, 2 NOT MEASURED. check:dual-build-cjs-loads and check:type-check-debt exit 3 (PREREQUISITE NOT MET): they need every workspace package's dist/, which CI's Build Core owns. check:i18n was measured after building its declared closure: exit 0, 9 packages in sync.
• GITHUB_TOKEN=… node scripts/check-issue-citations.mjs: exit 0, 1 citation, resolves.
• Narrowed eslint (--no-inline-config --format json) over the two changed TS files: 2 files, 0 errors, 0 warnings. Both files resolve a non-empty config under --print-config. eslint.config.mjs enables no type-aware linting (no parserOptions.project, no projectService), so this diff cannot move the verdict of any untouched file.
• Two main merges before opening (ccccdcc35e then bfa23a8f49 then 615c0856ef). Neither touched plugin-security, plugin-sharing, the ledger or the lockfile. fix(plugin-security, objectql): a row-level check holds for every row of an array insert and a predicate update #19988 had not landed.

Surface note

scripts/engine-double-contract.pinned.json gains one row (+5 lines: the new test file's findOne double). It was written by node scripts/check-engine-double-contract.mjs --write, which that gate prescribes for a new pinned double ("0 added or grown, 0 lost"). It lies outside the claim's declared file surface, the same as the three rows #19984 added. #19988 does not touch this file.

Acceptance notes

• Explain's record path does not model the on-behalf-of read, before or after this PR. That is the agent-leg depth intersection plus the delegator's filter AND-ed in. It was not measured here. fix(plugin-security): explain's record update/delete verdict uses the by-id write path's inputs #19984 recorded the same boundary for writes.
• Under a sharing-service fault, explain over-reports read visibility. This predates the PR, which does not change it. explain-engine.ts:958 catches a rejected sharingReadFilter into null, and the record matcher reads null as "no filter". A one-off probe on this branch made sys_record_share reads throw. dept_reporter × unshared then got explain visible: true (sharing admitted, rowFilter: null), while the same find threw. The old bare binding rejected into the same catch. This is reported for the seat to judge. It is not fixed here: the site is explain-engine.ts, outside this card's surface.
• The test double's nested reads are not scoped by plugin-sharing's read filter. That boundary is recorded in row-write-widener-composition.test.ts, and no cell here depends on a nested read.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-security, touching 1 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/permissions/system-context.mdx (via explainAccessForCaller (symbol, a method of class SecurityPlugin))

What this run could not see

• 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 e8f163fc3a62cc6c65f91d2197f7b516e3a2c90b → packageMentionDocs.

Which tree this was computed on

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

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

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

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs e8f163fc3a62cc6c65f91d2197f7b516e3a2c90b → pass the list as
args.docs, on the commit named under Which tree this was computed on.