fix(plugin-security): explain credits read depth, not sharing, for a row only the depth admits

[objectstack-fleet]

Fixes #21726

Clause-②: no

The explain answer now produces decidedBy: 'depth', a member the published decidedBy enum (packages/spec/src/security/explain.zod.ts, about :331-:341) already declares. No access decision changes.

What changed

All runtime changes are in packages/plugins/plugin-security/src/explain-engine.ts, in the record-grained pass (applyRecordAttribution).

• A row only read depth admits now explains as decidedBy: 'depth'. The decision tree ranks depth with sharing: after a decisive bypass, after a share, and before rls. These are the two layers that widen a private baseline past its owner.
• The depth layer carries a record block on record-grained requests. It is admitted when the read depth admits the row, and it names the depth and, below org, the owner it reached. It is excluded when the owner is outside the depth. It is not_evaluated with a reason when the depth adds nothing (own, a non-private baseline, no record), when the depth cannot be separated (a share admits the row too, below org), or when the depth is not in play (an on-behalf-of read, a write).
• The sharing layer reports admitted only when a share or rule matched. For a row that only the depth admits, it is not_evaluated, and its detail says that no share grants the row and that read depth already admits it.
• The sharing detail states a grant only when one exists. "N share(s) attached; access is granted for this record." is kept for a share that names the caller. When the sharing filter admits a row with no such share, the detail names the part of the sharing service that let it through.
• visible comes from the same disjunction as before. depthAdmitsRow is the part of the old sharingMatches === true admission that the sharing layer no longer claims, so sharingAdmitted || depthAdmitsRow equals the old sharingAdmitted.

How the depth admission is judged (measured, not re-derived)

The sharing read filter is one predicate with two grants: the owner-match, which read depth widens, OR-ed with the ids of the caller's own shares. Measured in plugin-sharing's buildReadFilter: at org depth it returns null and composes no owner-match at all. Below org it returns the owner-match over the depth's owners, OR-ed with id IN (granted ids) when the caller holds shares.

The engine does not parse that shape and does not call the filter a second time. It reads facts the pass already holds:

• the depth the depth layer published (depthScope);
• ownership;
• the share rows naming the caller (the grant disjunct's population);
• whether the filter matched.

Two cases are deliberately not credited to the depth. On an on-behalf-of read, security-plugin.ts hands the filter the delegated context with no depth stamped. Below org, a null filter means the sharing service imposes no owner-match on that object.

Precedence when a share and the depth both admit

This case is not named on the card. decidedBy's published contract decides it: "the layer whose record.outcome excluded it, or the last one to admit it" (explain.zod.ts about :390, and the .describe at :342). In pipeline order, depth comes before sharing, so a row a share admits keeps decidedBy: 'sharing'. That is also the answer before this change. The hand-written explain page (content/docs/permissions/explain.mdx) does not describe record verdict precedence, so no docs sentence became false.

Tests

Tests were added or updated in plugin-security:

• explain-engine.test.ts, unit harness:

  • org depth and unit depth explain as depth, with a depth record block;
  • an owner outside the unit is excluded by both layers;
  • a criteria rule's share still explains as sharing with exactly "1 share(s) attached; access is granted for this record.";
  • share plus depth, at org and at unit;
  • the two guards (a null filter below org, and an on-behalf-of read).

• explain-engine.test.ts, enumeration: decidedBy is read from ExplainDecisionSchema in @objectstack/spec/security. The test fails by name for any member that no scenario produces and no ledger entry explains. Today principal and fls are ledgered with reasons, and every other member is produced by a scenario that drives its branch.

• explain-read-verdict-inputs.test.ts, real SecurityPlugin plus real SharingService:

  • decider cells: depth for org and unit readers; sharing for a manual share, a rule-sourced share row, and share plus depth; owd_baseline for the owner;
  • the depth record block;
  • the rule row's exact detail.

  The existing test that asserted the sharing layer admitted an org-depth row was re-judged and replaced: it pinned the behaviour this change removes. Each cell still asserts explain visible equals the find's outcome.

• explain-dependency-fault.test.ts: the "a null filter is an answer, not a fault" test now asserts decidedBy: 'depth', with the filter published and judged. A faulted layer publishes neither.

Runs at head 8998a647:

• pnpm --filter @objectstack/plugin-security exec vitest run --maxWorkers=2 (full package): 164 files, 3562 passed, 45 skipped, 0 failed.
• pnpm --filter @objectstack/plugin-security typecheck: exit 0. This includes check:test-typecheck over tsconfig.test.json, which compiles the test layer.

Ablations (each red, then restored and proven: blob equals HEAD, git diff HEAD empty)

• A0, the whole file put back at the merge base (ff29410e): 15 failed out of 161 in the three explain files. Examples: expected 'sharing' to be 'depth', and expected '0 share(s) attached; access is grante…' to contain ….
• A1, depthAdmitsRow forced false: 9 red. These are every depth decider cell and the 'depth' is produced enumeration case.
• A2, the detail names a grant without a share: 2 red (the null-filter and on-behalf-of guards' detail assertions).
• A3, the on-behalf-of guard removed: 1 red.
• A4, the null-below-org guard removed: 1 red.
• A5, the fls ledger entry renamed: 1 red, with decidedBy member 'fls' is produced by no branch and carries no ledger reason.

The subject resolves from src (relative imports), so no dist rebuild was involved.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 66 commands from this branch, and all 66 ran at 8998a647 with exit 0. check:i18n and check:dual-build-cjs-loads first answered PREREQUISITE NOT MET (exit 3). Each was re-run green after its stated build (turbo cache hits). The --ran reconciliation: 66 derived, 66 run, 0 NOT-MEASURED, 0 UNRUN.

Lint was narrowed to the 4 touched .ts files. ① They are in the population of eslint.config.mjs's packages/** objects (--print-config resolves for each). ② --format json reports 4 files, 0 errors, 0 warnings. ③ The config enables no type-aware linting (no parserOptions.project, no typed rules), so this diff cannot move any untouched file's verdict.

Acceptance notes

• The write path has the same attribution shape and is left as it is. For update/delete, the row verdict is the sharing service's per-record gate, which judges write depth, ownership and shares together. A write admitted by write depth still reads decidedBy: 'sharing', with the gate detail naming ownership or a share. The new depth record block on a write says that this report does not separate the write depth. Carrier: none named.
• The owner's row keeps its sharing-layer detail, "Caller owns the record — visible without a share." It still decides as owd_baseline, which was already the case.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/permissions/authorization.mdx (via object_crud (literal, a string literal in applyRecordAttribution), owd_baseline (literal, a string literal in applyRecordAttribution))
• content/docs/permissions/explain.mdx (via object_crud (literal, a string literal in applyRecordAttribution), owd_baseline (literal, a string literal in applyRecordAttribution))
• content/docs/permissions/index.mdx (via tenant_isolation (literal, a string literal in applyRecordAttribution))
• content/docs/permissions/rls.mdx (via object_crud (literal, a string literal in applyRecordAttribution), owd_baseline (literal, a string literal in applyRecordAttribution), tenant_isolation (literal, a string literal in applyRecordAttribution))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via tenant_isolation (literal, a string literal in applyRecordAttribution))
• content/docs/releases/v13.mdx (via object_crud (literal, a string literal in applyRecordAttribution), owd_baseline (literal, a string literal in applyRecordAttribution))
• content/docs/releases/v15.mdx (via tenant_isolation (literal, a string literal in applyRecordAttribution))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

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 — 16 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 ea7ff394b6d802de9ad0448130bef86d4407760d → packageMentionDocs.

Which tree this was computed on

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

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

⚠️ 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 ea7ff394b6d802de9ad0448130bef86d4407760d → pass the list as
args.docs, on the commit named under Which tree this was computed on.