fix(spec, lint): state the RLS check default per operation across the applicable policies, as the runtime applies it

[objectstack-fleet]

Fixes #19953
Clause-②: no

Contract text only; no schema shape, accepted value or runtime behaviour changes (triage direction A, 5808181305). The published RowLevelSecurityPolicySchema.check said it "defaults to USING clause if not specified", which reads per policy. The write gate (writeCheckPolicies, since #19952) decides the default once per write operation across the applicable policies. The texts now say so. They also say the check runs on the new row of a single-record insert and of a by-id update. An array insert and a multi: true update are not post-image checked (#19964, #19950). Round 2 made that change after the review FAIL 5813145732, and limited the old 「OR-combine (most permissive wins)」 wording to reads.

• packages/spec/src/security/rls.zod.ts: the check describe and TSDoc. The two reference pages under content/docs/references/security/ are regenerated from the describe.
• content/docs/permissions/rls.mdx: two sentences.
• packages/lint/src/validate-rls-predicate-enforceability.ts (domain:devx, declared on the claim): the header, and the consequence texts for using and check.
• Changeset: @objectstack/spec and @objectstack/lint at patch.

The dev measured the runtime composition before writing; the table is in report 5812757565. The ADR-0058 D4 clarifying note was reverted out of this PR (seat ruling 5812826208), because docs/adr/** is governed; it stays owed separately. Filed from the measurement: #19964 (an array insert runs no row-level check) and #19965 (a check on a select / delete policy is never evaluated).

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sfe5YjBLwB9J3y8fvm2xq1

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/lint, @objectstack/spec, touching 4 documentable anchor(s).

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

• content/docs/protocol/objectql/security.mdx (via RowLevelSecurityPolicySchema (symbol, a top-level const))

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

• content/docs/releases/v13.mdx (via RowLevelSecurityPolicySchema (symbol, a top-level const))
• content/docs/releases/v17/17-0.mdx (via RowLevelSecurityPolicySchema (symbol, a top-level const))

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

• 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 — 136 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 3b5607019f6b1f84b14716c9c5e3359a986de08e → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 3b5607019f6b1f84b14716c9c5e3359a986de08e

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

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: f139546003c519f962ccb662c4d48b5f1b37619f

_{Reviewed and posted 2026-09-24T11:26Z by the at-tier review subagent the domain:spec#5 seat spawned — read: card #19953 with 5808181305 / 5811825631 / 5812757565 / 5812826208, PR #19962 diff · body · 7 commits · 46 head check-runs, #19952, #19964, #19965, ADR-0058 D4, writeCheckPolicies / computeWriteCheckFilter / step 3.6 / compileFilter, the lint rule and its test file, AGENTS.md, contract-review.md / ran: 38 policy sets × 5 write shapes × 2 SQL driver families through the real SecurityPlugin + ObjectQL in a sibling worktree at the head, the runtime's own pins (rls-check-defaults-to-using 22/22, row-write-widener-composition + controlled-by-parent-detail-write-authority 29/29), the lint rule's 86/86 pins, a byte comparison of the describe against both generated rows, a model-identifier sweep of the PR's artefacts / NOT MEASURED: check:generated locally (derived gate family — read from CI's TypeScript Type Check, green); the REST createManyData route (the engine-level array insert was measured)}

① Derived judgments

Runtime under packages/plugins/plugin-security is byte-identical between base 3b5607019f and the head. Cells: fresh engine per policy set, caller usr_a positions [writer] (+manager where named), object qa_ticket (public_read_write), ground truth read back under a system context. Every cell is identical on driver-sql (better-sqlite3) and driver-sqlite-wasm, and cell-for-cell equal to report 5812757565.

1. The composition the describe, TSDoc, both reference rows, permissions/rls.mdx (row + fail-closed item 4) and the changeset state — TRUE as measured.
   • Any applicable policy declares check ⇒ only the declared checks decide, OR-combined, a USING-only sibling adds nothing: C1/C3/C7/H1 (closed admitted, archived 403); the card's mixed case, check: status == 'open' beside USING-only status == 'pending' on insert: pending 403 (inside the sibling's using, outside the declared check); two declared checks == 'open' | == 'pending': both admitted, closed/archived 403.
   • None declares check ⇒ each applicable using stands in, OR-combined: A1/A4 (closed 403 on a single-record insert and a by-id update, open stored); two USING-only == 'open' | == 'pending': both admitted, closed/archived 403.
   • Applicable = not enabled: false (E3: a disabled check-declaring policy does not suppress the default), object match or '*' (E4 suppresses, E5 on another object does not), operation match or all (C4: insert defaulted from the all policy's using, update decided by the update check alone), positions held (E1w writer gets the defaulted using, E1m manager the declared check only; E2w non-holder is unchecked). Blank check = not declared (C8).
   • A check on a select / delete policy is never evaluated and does not suppress the default: B3/B5, C5/C6.
   • Ownership floor "takes part only where the by-id pre-image gate kept it": the runtime's own pins for the kept half (22/22) and the dropped half (29/29) are green at the head.
   • Delegation (the text makes no claim; measured for completeness): each leg is composed by the same selector and the legs AND — caller [declared != 'archived' + USING-only != 'closed'] on behalf of a delegator holding a USING-only != 'pending' set: open ok, pending 403 (the delegator's defaulted using), closed ok (the caller's sibling adds nothing), archived 403 (the caller's declared check); the same caller undelegated admits pending and closed. A missing delegator: 403.
2. Lint header and the six consequence strings — TRUE as measured, and no finding fires differently. using half: D1/D2/G1/G2 (unlowerable shape, unresolved current_user.*, undeclared column on insert / all) refuse every single-record insert, in-scope rows included; D3 the compiling sibling using alone decides; beside a declared check the using takes no part (C cells). check half: D4 (unlowerable check + USING-only sibling) refuses every insert; D5 the compiling declared check alone decides; D7/D8 refuse every by-id update. "Single-record insert and by-id update" is the right qualifier: in every D cell the array insert and the multi-row update were admitted. The diff changes two string constants, their concatenation and comments only; the shipped strings read off the rule at the head match the diff; the pins on RLS_DENY_FILTER / ZERO rows / PermissionDeniedError / blanket refusal hold; no message carries a tracker number.
3. Generated pages: both check rows are byte-equal to the describe (674 chars); CI TypeScript Type Check (runs check:generated) is green.
4. ⛔ FALSE universal, fail-open direction, both drivers. content/docs/permissions/rls.mdx:63 "Predicate the new row must satisfy after an insert or update" and the describe "Validation condition for INSERT/UPDATE, matched against the new row" (→ both reference rows). Measured: B1/B4 — a declared check: record.status != 'archived' on an insert / all policy refuses a single-record insert of archived (403, nothing stored), yet engine.insert('qa_ticket', [{status:'closed'}, {status:'archived'}], {context}) stores both rows; B4 — engine.update('qa_ticket', {status:'archived'}, {where:{title}, multi:true, context}) stores [archived, archived]; A4 (USING-only all) stores [closed, closed] the same way; every D cell that refuses all single-record inserts admits the array insert. This PR's own lint strings carry the exact qualifier; the contract text and the docs row it rewrote do not. Prime Directive chore: version packages #10: the claim stays as narrow as the enforcement, bulk paths included. Fix: one clause on the describe (then regenerate) and on the docs row — "on a single-record insert and a by-id update; an array insert and a multi: true update are not post-image checked" — with [finding] security: a row-level check (declared, or defaulted from using) is never evaluated on an ARRAY insert — engine.insert(object, [rows]), which createManyData calls, stores rows a single-record insert refuses #19964 / security: a check-only row-level policy does not gate a bulk update (update(…, { where, multi: true })): the post-image check is skipped as "governed by the using-scoped where", and no using exists to scope it #19950 as the runtime carriers.
5. Composition residue (non-blocking). (a) The priority [REMOVED] row two rows below the new check row on both reference pages (rls.zod.ts:480; the same sentence in migrations/registry.ts:160) and content/docs/protocol/objectql/security.mdx:144 still say policies "OR-combine (most permissive wins)" — false for the mixed write check (the pending 403 above); fail-closed direction. (b) security-plugin.ts:837-838 and rls-check-defaults-to-using.test.ts:5-6 quote the old describe as "the published contract"; packages/spec/liveness/permission.json:204 quotes check ?? policy.using — stale at the head; the dev listed them, the rewritten PR body dropped them, carrier none. (c) rls.zod.ts:302 and the using describe still present using as a SELECT/UPDATE/DELETE filter "optional for INSERT-only policies" without saying it is the insert check when no check is declared (A1) — incomplete, not contradictory. skills/** states no default (Tier H; nothing to do).

② Semver level

patch for @objectstack/spec and @objectstack/lint; Clause-②: no — consistent. Diff read whole: a .describe() string, TSDoc, two string constants and their concatenation, comments, the two regenerated rows, one docs page, the changeset. No schema shape, accepted value, export or runtime line moves; ADR diff at the head is empty (the note's commit is reverted, not rewritten). Check Changeset green.

③ Boundary flags

Blocking: ①.4 — the universal on permissions/rls.mdx:63 and in the describe (→ references/security/rls.mdx:175, permission.mdx:171) says every insert / update's new row is checked; the array insert and the multi: true update are not, measured on both drivers. Narrow it as above.
Non-blocking: #19964 filed, measured here (B1/B4 and the D cells) ✓ · #19965 filed, measured (B3/B5/C5/C6) ✓ — the describe's "never evaluated" is right · #19950 (multi-row update) measured A4/B4, carried there · dev Q2 (a declared check replaces the defaulted using of USING-only siblings for its holders) measured E1w vs E1m, A4 vs C3 — the text states it; direction B stays the maintainer's · ADR-0058 D4 note reverted (20b8fe95e8), owed to the maintainer with no card — track it · the stale runtime quotes and liveness evidence (①.5b) need a carrier · the "most permissive wins" residue (①.5a) — follow-up card.

CI (46 head check-runs, de-duplicated by name on latest started_at): required — Lint & Repo Gates ✓, TypeScript Type Check ✓, Dogfood Regression Gate ✓ (shards 1–3/3 ✓), Build Core ✓, Temporal Conformance (live PG + MySQL) ✓, Governed Surface Queue Guard ✓, Test Core rollup still in_progress (started 2026-09-24T11:22:30Z; shards 1–6/6 ✓ — the rollup's result is not inferred). Others ✓: the four Type Check · lanes, Build Docs, Dogfood Verify CLI, Check Changeset, Spec property liveness, Flag docs affected by code changes, Check Documentation Links, the four claim / single-writer guards, filter. Skipped: Console Pin Gate (the filter job: no console / pin path in the diff), Packed-tarball smoke (opt-in) (not opted in), the latest Auto Label / Check PR Size (edit-triggered re-runs; their synchronize-run instances ✓). Model identifiers: swept the diff, the 7 commit messages, the changeset and the PR body for every model-identifier spelling — none.

Implemented-by: claude/issue-19953-rls-check-default-text
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1 — at-tier review subagent spawned by the domain:spec#5 seat

VERDICT: FAIL

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 22c9473c86d64d1e29b47548e2264affecd8a792

Read: the 7-file diff 3b5607019f...22c9473c86 whole, the 9 commits, card #19953, triage 5808181305, prior FAIL 5813145732, PR body, dev-flags.json; runtime at the head: security-plugin.ts writeCheckPolicies (:880-889), computeWriteCheckFilter (:6560-6642), step 3.6 (:2996-3090), the select fallback (:6309-6318), rls-compiler.ts policyDeclaresClause (:385-391) and getApplicablePolicies (:733-776), platform-ownership-policies.ts:11, objectql/src/engine.ts:11453-11461; the lint rule and its test file; a byte comparison of the describe against both generated rows. Not run: any gate family (CI on the head is green, 46 runs); no measurement cells re-run — the runtime under plugin-security / objectql is untouched by the diff, so the prior round's cells stand.

① Derived judgments

1. Prior blocking item ①.4 — fixed. Every universal is now narrowed to the two shapes the runtime checks:
   • describe rls.zod.ts:432 "matched against the new row of a single-record INSERT or a by-id UPDATE ... an array insert and a multi: true update are not post-image checked" — TRUE: the middleware only installs the check when !Array.isArray(opCtx.data) (security-plugin.ts:3000), so an array insert never gets the postHookWriteImageCheck seam (:3069); a bulk update with no single id sets postImage = null and skips (:3078-3084, extractSingleId).
   • content/docs/permissions/rls.mdx:57 (row), content/docs/protocol/objectql/security.mdx:144, the lint consequence strings (validate-rls-predicate-enforceability.ts:195-198, 227-229, 246-247, 265-266) carry the same qualifier. The TSDoc (:308-310) too.
2. Composition text — every sentence TRUE of writeCheckPolicies (security-plugin.ts:884-888): declared = applicable.filter(check declared); if (declared.length > 0) return declared; else applicable.filter(using declared && (keepOwnershipFloor || !floor)), then OR-combined by compileFilter(withCheck, ctx, 'check') (:6636). "Applicable = not enabled: false" (rls-compiler.ts:753, exact === false), "object matches or is '*'" (:756), "operation matches or is 'all'" (:771-772), "caller holds one of its positions when it lists any" (:764-768, domain.length > 0 then some(held)), "blank check = not declared" (policyDeclaresClause :390, trim() !== ''). "A check on a select or delete policy is never evaluated": the write set is collected with operation = insert/update (:6597-6602), so a select/delete policy never enters it; the select fallback at :6309-6318 is inside the read/pre-image compiler, not the check path. TSDoc "ownership floor takes part only where the by-id pre-image gate kept it": :6593-6603 (keepOwnershipFloor: !floorReplaced), and owner_only_writes is '*' update only (platform-ownership-policies.ts:11), so it cannot touch an insert.
3. Accepted/refused sets — unchanged. rls.zod.ts diff: one .describe() string, TSDoc, the file-header JSDoc bullets, and the retiredKey prescription text for priority (:476-480; still never, still refused). No z. shape, default, enum or export moves. The old prescription sentence "applicable policies OR-combine (most permissive wins), so there is no conflict to order" was false for the mixed write check; removing it is a text-only fix. No test pins the old sentence (packages/cli/test/migrate-meta.e2e.test.ts:123 is a comment; CHANGELOG.md is history).
4. Lint (validate-rls-predicate-enforceability.ts): no behaviour change — the diff adds two string constants (USING_INSERT_CONSEQUENCE, CHECK_SET_QUALIFIER), appends them to the existing using/check consequence strings at three sites, and rewrites the header comment. No new finding, no changed trigger, no tracker number in a shipped string. The using sentence "on an insert or all policy the same using is also the single-record INSERT check whenever no applicable policy for the insert declares a check" is exactly rule 2 of writeCheckPolicies; the check qualifier is exactly rule 1 plus OR-drop. One precision nit in the header comment (not shipped text): :165-166 "(an array insert and a multi: true update never reach it)" — for a multi: true update computeWriteCheckFilter IS called (:3004, the condition at :2996-3003 does not exclude a bulk update); only the post-image evaluation is skipped (:3078-3084). The array-insert half is exact. The consequence strings authors see are precise, so non-blocking.
5. Docs pages: permissions/rls.mdx:78-81 (fail-closed item 4) states rule 1/2 correctly; :185-187 limits OR-ed admission to reads and points at item 4; references/security/rls.mdx:81 and the removed "Policy Precedence: more permissive wins" bullet match the source JSDoc (:81, :90-92). No leftover "most permissive wins" contradiction on any page the PR touches.
6. Generated pages — regenerated, consistent. Both check rows (references/security/rls.mdx:174, permission.mdx:171) are byte-equal to the describe after unescaping (770 chars, 2/2 match); both priority rows equal the new retiredKey text; the overview bullets and best-practice list on references/security/rls.mdx match the JSDoc header edits. Commit 22c9473 is the regen commit; CI TypeScript Type Check (check:generated) green on the head.
7. Governed surface: no docs/adr/** path in the diff (git diff --name-only filtered for adr → empty; 20b8fe9 is reverted by f139546, net zero).
8. Residue (non-blocking, out of this PR's named scope): (a) packages/spec/src/migrations/registry.ts:159-160 still ships "applicable policies OR-combine (most permissive wins)" in the --from 16 migration prose — the same sentence the PR removed from retiredKey; the prior review named it (①.5a) and it has no carrier. (b) rls.zod.ts:463-465 (TSDoc on priority, not rendered) still says "the doc above ... say most-permissive-wins" while the doc above now limits that to reads. (c) security-plugin.ts:837-838 quotes the old describe as "the published contract" — now stale (prior ①.5b). (d) content/docs/permissions/authorization.mdx:109 unqualified OR-combine (dev flag).

② Semver level

patch for @objectstack/spec and @objectstack/lint — correct. Diff is describe/TSDoc/JSDoc text, a retired-key message, two lint message constants and their concatenation, docs pages and the regenerated reference rows; no schema shape, accepted value, export, diagnostic code or runtime line changes. Changeset prose (.changeset/19953-rls-check-default-composition-text.md) restates rules 1/2, the applicability predicate, the single-record/by-id scope with #19964/#19950 as carriers, and Clause-②: no — every sentence checked above as true. No other package's source is touched, so no other package needs a bump.

③ Boundary flags

• premise_still_valid: true — agreed; writeCheckPolicies at the head is the composition the card describes.
• Out-of-scope (a) authorization.mdx:108-109 — agreed, same class as ①.5a, non-blocking; carrier none; add to the [finding] After PR #19962 rewrites the RLS check describe, three texts still quote the old "defaults to USING clause if not specified" contract, and the using text never says it is the insert check when no check is declared #19967-class follow-up together with migrations/registry.ts:159-160 (①.8a above, which the dev's flags do not list).
• Out-of-scope (b) ①.5b / ①.5c unchanged — agreed and confirmed at security-plugin.ts:837-838, rls-check-defaults-to-using.test.ts:5-6, liveness/permission.json:204, and the using describe (rls.zod.ts:393, "Filter condition for SELECT/UPDATE/DELETE ... Optional for INSERT-only policies") — incomplete, not contradictory with the new check describe; non-blocking.
• Carriers [finding] security: a row-level check (declared, or defaulted from using) is never evaluated on an ARRAY insert — engine.insert(object, [rows]), which createManyData calls, stores rows a single-record insert refuses #19964 / security: a check-only row-level policy does not gate a bulk update (update(…, { where, multi: true })): the post-image check is skipped as "governed by the using-scoped where", and no using exists to scope it #19950 / [finding] A check on a select or delete row-level policy is accepted by RowLevelSecurityPolicySchema and never evaluated — and it does not suppress the using default either; no lint reports it #19965 — cited in the TSDoc, changeset and PR body; consistent with the code paths read (:3000, :3078-3084, :6597-6602).
• Deviation 1 (extra ①.5a edits at rls.zod.ts:81, :95, permissions/rls.mdx:185, security.mdx:144) — each verified true; they sit on pages this PR regenerates/rewrites, so leaving them would have put a contradiction beside the new row. Accepted.
• Deviation 2 (PR body not edited by the dev) — the body as read is accurate about the ADR revert and the round-2 narrowing; nothing false.
• ADR-0058 D4 note — correctly absent from the diff; still owed separately to the maintainer (no card), unchanged from round 1.

Implemented-by: claude/issue-19953-rls-check-default-text
Reviewed-by: session_01EcrTi7s5oDYPHS4Pi7h31d

VERDICT: PASS

_{Isolated at-tier reviewer adopted by the director seat, summon #29, on the maintainer's instruction 「执行契约复审」 · fed only the card(s), the governing rulings, the PR body, the dev's flags and the code}

---

Generated by Claude Code