docs(permissions): a write widener reaches only rows the caller can read (#19880)

Closes #7401
Clause-②: no

Docs-only. Zero code changes, zero `packages/spec` edits, nothing under
`content/docs/releases/**`.

## What changed

The maintainer ruled reading 1 on this card: a caller may not write a
row they cannot read, even when an app-authored write policy admits it
by predicate. The `plugin-security` by-id write pre-image gate keeps
re-reading the target under the caller's own read scope. The docs said
the opposite ("widens exactly as written"), so authors following them
hit a 403 on `private` objects. This PR brings the four named spots onto
the ruled behaviour.

1. `content/docs/permissions/rls.mdx`: the "widens exactly as written"
sentence now says it decides the update *filter* alone. A new paragraph
states the read floor: a single-record `update` / `delete` re-reads its
target under the caller's own read scope. On `private` OWD, an `update`
widener therefore reaches only rows the caller can already read. A
`warn` callout carries the known limitation and names the read grants
that actually work.
2. `content/docs/permissions/sharing-rules.mdx`: the recipe "owners edit
their own records, supervisors edit all" now says it needs a matching
read grant on `private` objects. It shows the paired spelling (object
permission with `viewAllRecords` plus the `update` RLS policy in the
same set), and it names a read-level sharing rule or record share as the
alternative read half.
3. The owed known-limitations note ("app-authored wideners do not
function on `private` OWD without a matching read grant") is written
into both pages above. It is not in release notes.
4. `content/docs/permissions/permissions-matrix.mdx`: the bypass-posture
paragraph now covers deployment posture too. Under the default wall-less
`single` posture, `auto-org-admin-grant` gives org owners and admins
`organization_admin_no_bypass` (ADR-0105 D4), not `organization_admin`.
So on `single` an org admin is not short-circuited, even on a
better-auth-managed object.

## Verified against source (at base `b940f32a56`)

- The pre-image gate is in
`packages/plugins/plugin-security/src/security-plugin.ts`, step 2.7. It
calls `this.ql.findOne(object, { where: { $and: [{ id }, ...writeParts]
}, context: opCtx.context })` under the caller's context, and a null
result throws `PermissionDeniedError`. The dogfood pin
`packages/qa/dogfood/test/authored-row-write-scope.dogfood.test.ts` case
`[E2E private]` asserts that 403.
- The read scope on `private` comes from
`packages/plugins/plugin-sharing/src/sharing-service.ts`
`buildReadFilter`. It is owner-match at the caller's `__readScope`
depth, OR record shares whose recipient is that user. It returns null
when the read depth is `org`, and `permission-evaluator.ts`
`getEffectiveScope('read')` answers `org` for `viewAllRecords` /
`modifyAllRecords`. Sharing rules expand a position recipient to users
(`sharing-rule-service.ts` `expandRecipient`).
- Item 4 comes from
`packages/plugins/plugin-security/src/objects/default-permission-sets.ts`
`deriveWallLessOrgAdmin`, which strips both bits from the wildcard, and
from `auto-org-admin-grant.ts` `orgAdminSetNameForPosture`, which
returns the no-bypass set unless the posture enforces a wall. The
posture defaults to `single` when no org-scoping service is registered
(`security-plugin.ts`, the `tenancyPosture` field).

## One deviation from the ruling's wording (please confirm)

The ruling lists three read grants as its examples: a `select` policy,
`viewAllRecords`, or sharing. On a `private` object a `select` policy is
**not** a read grant. The sharing read filter and the RLS read filter
both AND into the query (`sharing-plugin.ts` read branch, `composeAnd`),
and nothing defers the sharing read filter to an authored `select`
policy. RLS only narrows, as `rls.mdx` already says in "RLS narrows what
the earlier layers already allowed; it never widens". Documenting
`select` as the fix would send authors into the same 403. So the pages
name `viewAllRecords` or a `readScope` depth, or a read-level sharing
rule or record share, and they say explicitly that an extra `select`
policy does not work. The ruling's substance is unchanged: widen read to
match.

## Acceptance notes

- Out of scope, per the ruling: #6736 (the batch-write half) remains
open and on hold. #7497 is not addressed here. The new text describes
single-record writes only and makes no claim about bulk writes.
- Noted, not fixed (class a, a doc error reachable today): the same
`permissions-matrix.mdx` callout still says "The built-in
`admin_full_access` / `organization_admin` sets therefore carry
`allowExport: true`". `default-permission-sets.ts` says neither set
grants export any more (the `allowExport` comments on the admin wildcard
and the org-admin set). It is left for a separate card so this PR stays
within the ruled four items.

## Tests

Local gates were derived by `node scripts/pm/dispatch-gates.mjs
--commands --repo objectstack-ai/objectstack` at head `3fc2c9acc9`.
There were 44 commands, all run, and all exit 0.
`check:docs-transcript-drift` and `check:skill-examples` first refused
with exit 3 (PREREQUISITE NOT MET) and were re-run green after building
`@objectstack/lint...` and `@objectstack/client-react...` under the
verify lock. `--ran` reconciliation: 44 derived, 44 run, 0 unrun. The
page-relevant gates are `check:doc-anchors`, `check:doc-authoring`,
`check:docs`, `check:doc-security-posture`, `check:docs-single-h1`,
`check:nul-bytes` and `check:doc-frontmatter`, all green. Build Docs and
the typecheck lanes are left to CI.

No changeset. `content/docs/**` ships only in the private `apps/docs`
package, so this PR carries `skip-changeset`.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01AhQASwqJr2Z7XfGWUdvnbF)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

content/docs/permissions/permissions-matrix.mdx

@@ -47,6 +47,22 @@ owner-scoped write policies keep `org_member` holders owner-scoped on
 Layer 0 tenant wall always ANDs on top. See
 [Sharing & OWD](/docs/permissions/sharing-rules#how-viewallrecords--modifyallrecords-interact-with-the-owd)
 and `plugin-security/src/security-plugin.ts` (`computeLayeredRlsFilter`).
+
+The bypass is **also gated by the deployment's tenancy posture** (ADR-0105
+D4), because a principal is short-circuited only if some set it holds carries
+the bits at all. Under the default wall-less `single` posture there is no
+organization wall to bound them, so the membership-driven auto-grant
+(`auto-org-admin-grant`) gives org owners and admins
+`organization_admin_no_bypass` — `organization_admin` without
+`viewAllRecords` / `modifyAllRecords` — instead of `organization_admin`.
+On a `single` deployment an org admin is therefore **not** short-circuited,
+not even on a posture-permitting object (a better-auth-managed one included):
+the object's RLS policies apply to them as to any other holder. The walled
+postures (`group` / `isolated`) grant the full `organization_admin` unless the
+deployment suppresses it. A deployment-wide data superuser needs
+`admin_full_access` or an explicit set carrying the bits. See
+`plugin-security/src/objects/default-permission-sets.ts`
+(`deriveWallLessOrgAdmin`).
 </Callout>
 
 <Callout type="warn">

content/docs/permissions/rls.mdx

@@ -77,11 +77,37 @@ to a caller on an object, the `update` / `delete` scope is derived from that
 caller's `select` policies — a record they cannot read is one they cannot
 modify, by id or in bulk. Authoring a write-class policy switches the
 derivation off for that class: an authored `update` predicate then decides
-`update` alone and widens exactly as written. Nothing is derived for `insert`
+the `update` *filter* alone, widening past the platform's owner-scoped write
+floor exactly as written. Nothing is derived for `insert`
 (there is no pre-existing row to be visible), and a caller holding the
 read-side superuser bypass (`viewAllRecords` on a private or platform-global
 object) is not narrowed, because their readable set is already unbounded.
 
+**A write widener never reaches a row the caller cannot read.** "You may not
+modify what you cannot see" is a floor, not a default the write filter
+overrides: before a single-record `update` / `delete` runs, the target row is
+re-read under the caller's **own read scope** together with the write filter,
+and a row that read cannot see is refused with `403 PERMISSION_DENIED`. On a
+`public_read` object that read scope is every row (minus any `select`
+narrowing you authored), so an `update` widener works as written. On a
+**`private`** object — the default OWD — the read scope is the caller's own
+records, their access depth and the records shared with them, so an `update`
+widener reaches **only rows the caller can already read**; everything else it
+admits by predicate is still refused.
+
+<Callout type="warn">
+**Known limitation — an app-authored write widener does nothing on a
+`private` object without a matching read grant.** To let a position edit
+*other people's* records on a `private` object, grant read reach to the same
+rows as well: `viewAllRecords` (or a wider `readScope` depth) on the
+object in the same permission set, or a
+[sharing rule or record share](/docs/permissions/sharing-rules) that shares
+those rows with the position. An additional `select` policy is **not** a read
+grant — RLS only narrows, so it cannot make a `private` row visible. The
+paired spelling is shown in the
+[supervisor recipe](/docs/permissions/sharing-rules#how-viewallrecords--modifyallrecords-interact-with-the-owd).
+</Callout>
+
 ## The expression grammar
 
 RLS predicates are **canonical CEL**, lowered into a query filter by the shared

content/docs/permissions/sharing-rules.mdx

@@ -83,6 +83,44 @@ supervisors widen to the org) — or model the object with `access: {
 default: 'private' }` + explicit grants, where `modifyAllRecords` bypasses
 RLS by design.
 
+**On a `private` OWD object this recipe needs a matching read grant.** A
+caller may not write a row they cannot read: a single-record `update` first
+re-reads its target under the caller's **own read scope**, and on a `private`
+object that scope is the supervisor's own records, their depth and their
+shares — so the `update` policy above would admit a colleague's record by
+predicate and the write would still be refused (`403 PERMISSION_DENIED`).
+Pair the widener with read reach over the same rows, in the same permission
+set:
+
+```typescript
+objects: {
+  // `viewAllRecords` (or a `readScope` depth) makes the rows readable;
+  // the RLS policy below decides which of them the supervisor may edit.
+  project: { allowRead: true, allowEdit: true, viewAllRecords: true },
+},
+rowLevelSecurity: [
+  {
+    name: 'supervisor_edit_org',
+    object: 'project',
+    operation: 'update',
+    using: 'organization_id == current_user.organization_id',
+    positions: ['supervisor'],
+  },
+],
+```
+
+A criteria sharing rule that shares those records with the supervisor
+position, or a record share to the supervisor, works as the read half too
+(`accessLevel: 'read'` is enough — the policy supplies the edit). An extra `select` policy does **not**: RLS
+only narrows, so it cannot make a `private` row visible. On `public_read` and
+`public_read_write` objects every row is already readable (unless an authored
+`select` policy hides it), and the recipe works as written.
+
+> **Known limitation.** App-authored write wideners (`update` / `delete`
+> `rowLevelSecurity` policies) do not function on a `private` OWD object without
+> a matching read grant — the rows they admit stay unwritable until the caller
+> can also read them. See [RLS — write targets](/docs/permissions/rls#anatomy-of-a-policy).
+
 ## The external dial — `externalSharingModel` (ADR-0090 D11)
 
 Portal/partner scenarios get a second, independent dial with the same enum: