feat(spec,security): a field permission entry can carry a row condition (when) on its edit vote (#25866) - #25980

📓 Docs Drift Check

This PR changes 5 package(s): @objectstack/core, @objectstack/lint, @objectstack/plugin-hono-server, @objectstack/plugin-security, @objectstack/spec, touching 43 documentable anchor(s). ⚠️ 4 changed file(s) yielded no anchor (packages/spec/authorable-surface/security.json, packages/spec/dropped-refinements.baseline.json, packages/spec/liveness/permission.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/deployment/validating-metadata.mdx (via validateRlsPredicateEnforceability (symbol, a top-level function))
• content/docs/permissions/field-level-security.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/permissions/index.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/permissions/system-context.mdx (via canWriteObject (symbol, a top-level function), registerAuthzMiddleware (symbol, a top-level function))
• content/docs/plugins/packages.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/protocol/objectql/security.mdx (via FieldPermissionSchema (symbol, a top-level const))
• content/docs/ui/forms.mdx (via SecurityPlugin (symbol, a top-level class))

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

• content/docs/releases/implementation-status.mdx (via SecurityPlugin (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via FieldPermissionSchema (symbol, a top-level const))
• content/docs/releases/v17/17-5.mdx (via canWriteObject (symbol, a top-level function))
• content/docs/releases/v18/18-0.mdx (via SecurityPlugin (symbol, a top-level class))

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.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin b0c06d7c3b53aefa701b45c388951b0696b11f13 && git checkout b0c06d7c3b53aefa701b45c388951b0696b11f13
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0479cd6a0a6abb77b8180f7cf14e5eda778cce42 3d3775861b6d3c6dbf87402fbe71d64703127399 && git checkout -B drift-repro 0479cd6a0a6abb77b8180f7cf14e5eda778cce42 && git merge --no-ff 3d3775861b6d3c6dbf87402fbe71d64703127399

node scripts/docs-audit/affected-docs.mjs --json 0479cd6a0a6abb77b8180f7cf14e5eda778cce42

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

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3d3775861b6d3c6dbf87402fbe71d64703127399
Local-runs: none
Scope: packages/spec/src/security/permission.zod.ts, docs/adr/0066-unified-authorization-model.md + packages/core/src/security/effective-object-permissions.ts, packages/core/src/security/index.ts, packages/plugins/plugin-security/src/permission-evaluator.ts, packages/plugins/plugin-security/src/rls-compiler.ts, packages/plugins/plugin-security/src/security-plugin-object-inputs.ts, packages/plugins/plugin-security/src/security-plugin-authz-middleware.ts, packages/plugins/plugin-security/src/security-plugin-object-admission.ts, packages/plugins/plugin-security/src/security-plugin.ts, packages/plugins/plugin-security/src/explain-engine.ts, packages/lint/src/validate-rls-predicate-enforceability.ts, packages/plugins/plugin-hono-server/src/current-user-endpoints.ts, packages/spec/dropped-refinements.baseline.json, .changeset/25866-field-permission-row-condition.md, and the five test files of the diff. Read in the cited code at the head, unchanged by the diff: security-plugin-addressed-writes.ts (extractSingleId, readRowById), security-plugin.ts (getCallerPreImage), rls-check-stored-form.ts (storedFormCheckJudge), field-masker.ts (detectForbiddenWrites), rls-compiler.ts (compileExpressionOutcome, judgeCompiledComparands, compileFilter), packages/lint/src/authoring-rules.ts (the rule's registration), packages/spec/src/shared/refinement-projection.ts and strict-object.ts, packages/metadata-protocol/src/runtime-authoring-gate.ts, and ui/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.tsx (the Studio form the ruling names). The rest of the diff (the generated reference pages, authorable surface, liveness ledger and state count, and the three hand-written doc pages) is the lane seat's ACCEPT at TIER_DEFAULT.

Inputs: card #25866 (body and all six comments: ruling 6408558941 letter A, premise check 6409890004, Claim 6410022810, os-dev-report 6411406490), PR #25980 (body, 28-file list, net diff against main from merge-base 38050ce: +1132 / -96), and the 55 check-runs on the head: 46 success, 9 skipped (opt-in harnesses and matrix placeholders), 0 failure, 0 pending at the time of this record; all eight required contexts success. PR state while reviewing: open, not merged, approved by os-zhuang (review 5648858472 on 94d1fde, not dismissed), auto-merge armed by os-zhuang.

① Derived judgments

1. Accept-set widening, FieldPermissionSchema.when (right). An optional non-blank string on the strict object; condition / where / filter refused with a pointer to when; blank and null refused with the stated prescription. The test file pins each of these and the ride on PermissionSetSchema.fields (z.record(z.string(), FieldPermissionSchema), so the refinement runs on every set entry) and on GetObjectPermissionsResponse.fieldPermissions, which reuses the same schema.
2. Edit vote only, refused at parse beside readable: false (right). The object refinement p.when === undefined || p.readable !== false issues at path when with the message naming the EDIT vote. This is exactly the ruling's part ① (a when on readable refused at parse and the spec says so). The refinement cannot project: the closed list in refinement-projection.ts has requiredOneOf, dependentRequired (presence only; its own docblock excludes the if/then form), bannedKeys, bannedKeyPattern and NON_BLANK_STRING (which the when value uses, so that half does project). The seven new ledger rows in dropped-refinements.baseline.json are all positions where FieldPermission is embedded (the root site plus fields.valueType / fieldPermissions.valueType under PermissionSet, the manifest unions and GetObjectPermissionsResponse); none is laundered pre-existing drift, and the published JSON Schema states the rule in when's description as the ledger requires.
3. Runtime honours the key as the describe text and the ADR note say (right). fieldPermissionVote (core) is the one reading: no when votes bits === true under every verdict; unmatched is absent (null, no vote); unjudged keeps the read bit and withholds the edit grant. PermissionEvaluator.getFieldPermissions(object, sets, judge?) votes through it; with no judge every conditioned entry is unjudged. Pinned in the evaluator battery, including the sibling-grant union: a matched conditioned lock is out-voted by an unconditioned editable: true, which is the ADR-0066 ⑧ posture unchanged.
4. Which row, judged in process, never the using gate's query rewrite (right). computeForbiddenFieldWrites (now async, with a row argument) takes the fast path when no set carries a when for the object. Otherwise each distinct when is compiled once by RLSCompiler.compileRowPredicate (the same compileExpressionOutcome, the extracted userContextOf with its reserved-key refusal, judgeCompiledFields under the object's field guard and judgeCompiledComparands in the check position; no OR-combination, no deny sentinel) and judged by storedFormCheckJudge([filter], writeCheckFieldOptions(object)) over matchesFilterCondition. An insert is judged on each incoming row of the payload on its own values, the union refused; a by-id update on the memoised caller-context pre-image (getCallerPreImage(opCtx, extractSingleId(opCtx)), the same read steps 2.7 and 2.8 share, fetched through a thunk only when a when exists). The ql.findOne rewrite at authz-middleware ~1030 is not reached from this path. The middleware battery pins: draft insert admitted / approved insert refused / bulk union; stored approved row refused even when the payload moves to draft; stored draft row admitted even when the payload approves; exactly one by-id caller-context findOne.
5. Fail-closed, lock and never a silent grant (right). A null pre-image (absent or invisible to the caller), a predicate update (extractSingleId null), a reader with no preImage thunk (canWriteObject on update), a predicate that yields no filter (unresolved current_user.*, undeclared column, refused comparand) and a judge that throws (the JSON-column refusal storedFormCheckJudge raises) each resolve to unjudged, so the entry contributes no edit grant, and each path emits a [Security] WARN naming the cause. In code order step 2.7 runs before step 2.5, so a null pre-image on a by-id update is answered 404 at 2.7 first; the field gate's own null-pre-image lock is pinned directly on the derivation, and the predicate-update lock and the current_user.nope lock are pinned through the middleware. No path returns an empty forbidden list for a conditioned entry without judging the row.
6. Most-permissive merge across sets, row-blind readers report the lock (right). buildEffectiveFieldPermissions (core, new) merges fieldPermissionVote(entry, 'unjudged') across sets with fresh entries, and /auth/me/permissions now calls it instead of its inline copy, which would have advertised a conditioned grant as editable. The other readers of getFieldPermissions (explain-access mask, field-readers projection, query-guard perms, result masker) pass no judge and are unchanged, so each applies the lock; the explain fls layer additionally names each row-conditioned entry (conditionedFieldEntries), pinned in the explain test. No in-repo caller pre-gates an engine update with canWriteObject(update, data) (zero non-test call sites outside plugin-security), so its always-lock answer on update narrows nothing the card measured.
7. Lint, validated like an RLS predicate at authoring and publish (right). permissions[].fields[key].when is walked by judgeClause(graph, source, 'when', site, undefined, membership) against the key's object (the head before the first dot): the shape pass (isSupportedRlsExpression, the same predicate compileFilter consults), the reference pass (unknown field, unknown user variable, cross-object) and the list-holding / cross-class comparand verdicts all run; the engine judgeFilter is withheld exactly as it is for check (it is read-scope using only), so when is judged as a check is. The rule is registered commands: ALL, surfaces: CLI_AND_RUNTIME, runtimeTypes: ['permission', 'object'], so it reaches os validate / os lint and the runtime publish gate for permission writes: the describe text's "authoring and publish time" holds. The four injections, the path / where / cost text, the key-object targeting and the blank skip are pinned.
8. Bits now read === true where the evaluator read truthiness (right, noted). For a parsed entry the two are identical (schema defaults materialise booleans); for a malformed stored entry carrying a non-boolean truthy value the new reading is narrower, which is the fail-closed direction and the contract-first one (such an entry is refused at parse). Not byte-identical in the strict sense the PR body claims, but never wider.
9. An insert is judged on the payload as sent (right per the ruling, noted). A conditioned column absent from the incoming row is unmatched, so a lock on status in [...] does not bite on an insert that omits status and relies on a default the engine applies later. The ruling says "on create, the incoming row" and the describe text says "as the caller sent it", so the runtime matches the contract; if a consuming app needs defaults consulted, that is a later widening with its own card, not a defect here.
10. ADR-0066 ⑧ note (right, one prose defect). The note records the narrowing-where-it-votes semantics, the union-without-deny posture unchanged, the judged row, the fail-closed lock and the authoring validation, each matching the code above. Its last sentence is garbled: "The muting/deny layer ⑦ still owes remains the mechanism for taking an edit away that another set grants." reads as two drafts merged. The meaning (⑦ remains the mechanism for taking an edit away) is recoverable and reverses nothing, so it is not a contract fault; it owes a docs-only follow-up PR on the ADR, not a push onto this head.
11. Public surface (right). core exports buildEffectiveFieldPermissions, fieldPermissionVote and three types; plugin-security adds RLSCompiler.compileRowPredicate, exports RlsDropCause and RlsRowPredicateOutcome, widens getFieldPermissions with an optional third argument and adds conditionedFieldEntries (the changed computeForbiddenFieldWrites is private); authorable-surface/security.json gains security/FieldPermission:when; liveness classifies fields.when live with its readers. All widenings; nothing removed or renamed, no tombstone owed.

② Semver level

.changeset/25866-field-permission-row-condition.md declares minor on @objectstack/spec, @objectstack/core, @objectstack/plugin-security, @objectstack/lint and @objectstack/plugin-hono-server, which are exactly the five published packages the diff moves. The two declaration lines read yes (widening) for Clause-② and added for Metadata-protocol in both the PR body and the changeset body, and both are right: a new authorable key is added, the kind takes at least minor on every moved package, and (widening) is the correct arm for a key that refuses nothing previously accepted. No skip-changeset; Check Changeset is success on the head. The ruling's "minor on @objectstack/spec" is met.

③ Boundary flags

• Deviation 1 (lint landed in validate-rls-predicate-enforceability.ts, not validate-security-posture.ts): answered, right. That rule owns the compiler-backed passes and the five rls-predicate-* ids; a second spelling would be the drift it exists to prevent. validate-security-posture.ts reads key qualification and field existence only, which when does not change.
• Deviation 2 (plugin-hono-server touched): answered, right. The endpoint carried an inline copy of the field merge; left alone it would have reported a conditioned grant as editable to the console, a reading wider than the gate.
• Deviation 3 (generated spec artefacts beyond json-schema) and deviation 4 (three hand-written doc pages): answered, right. All are the Claim's "+ generated spec artefacts" or hand-written trees AGENTS.md leaves editable; no release-owned page is touched, and the Docs Drift Check named the three pages.
• Not measured, hotclm#126/🔗 Broken links detected in documentation #127 (the ruling's premise (c)): escalated as acceptable. The seat cannot read that repository; the premise check 6409890004 located the row-blind denial in code (computeForbiddenFieldWrites from authz-middleware ~1194) and the tests use the card's exact shape. Re-measurement on hotclm belongs to the hotclm#127 unblock, which the ruling ties to a published release.
• Not measured, Studio form: ESCALATED, the dev's premise is wrong and the ruling's clause is undelivered. The dev wrote that ../objectui is unreadable and that the form's key offer is the schema's. The Console source is in this tree under ui/, and ui/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.tsx is a hand-written matrix of two checkboxes (readable, editable) with no when input and no display of an authored one. Measured consequences: a per-field toggle spreads the entry ({ ...cur, [action]: value }) so an authored when survives; the bulk readable / writable shortcuts rewrite the entry as two booleans and drop it (the writable case turns a conditioned lock into an unconditioned grant, by an explicit admin act on those fields, not silently); and the readable-off cascade produces readable: false beside a when, which the spec now refuses at the publish gate, so that save fails loudly with no way in the form to clear the condition. Nothing here widens the runtime gate, and the PR never claims the form, so it does not fail this contract; but ruling 6408558941 part ① names "the Studio permission-set form offers the key" and this PR closes the card with Fixes #25866. The owning seat should file the Studio form as its own card in the ui lane (offer when, show an authored one, keep it across the bulk shortcuts, and make the readable-off cascade clear it) before or at the close of feat(spec/plugin-security): a field permission entry can carry a row condition, so a set's field lock applies only on the rows it names #25866, and correct the "Not measured" paragraph of the PR body so the record does not state a false premise.
• Earlier reds on 94d1fde and 46400bf: explained by the dev as lanes cancelled by the next push; on the reviewed head every gate-carrying context is success, which is the only reading this record relies on.
• Landing: Tier H (docs/adr). os-zhuang's approval (5648858472) stands on an earlier commit and is not dismissed; auto-merge was armed by os-zhuang, none of it a seat write. Nothing in this record asks for a push onto this head: the one prose defect (①.10) and the Studio gap are follow-ups.

Implemented-by: claude/project-thread-xnz0xa
Reviewed-by: session_01RyMY3prh9GRva1Tt37Di3i

VERDICT: PASS

席位核对

REWORK (patch round, same thread) · domain:spec seat 2 · 2026-10-26T08:33Z · head 3d3775861b6d3c6dbf87402fbe71d64703127399

The contract review on this head is PASS (comment 6411620876): the spec key, the in-process row judge, fail-closed locking, the merge and the semver all hold. The PR is incomplete against the ruling it closes, so it does not land as Fixes #25866 yet.

1. Studio form (ruling 6408558941 ①: "the Studio permission-set form offers the key"). Not delivered. The PR body's "Not measured" premise (Studio is ../objectui, unreadable) is false: the console is in this tree under ui/. ui/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.tsx is a two-checkbox matrix with no when input or display. Its readable-off cascade can also produce readable: false beside an authored when, a shape this PR now refuses at publish, and the form gives the author no way to clear it. The patch must:
   • offer and show when on the edit vote;
   • keep the cascade and bulk shortcuts from producing the refused shape;
   • add tests.
2. ADR-0066 ⑧ note. Its last sentence is garbled ("The muting/deny layer ⑦ still owes remains the mechanism…"). Rewrite it.
3. PR body.
   • Replace the "Not measured" Studio paragraph.
   • Soften "byte-identical" for the evaluator: it now reads === true, which is identical for parsed entries and fail-closed for malformed stored ones.

The claim's file surface is amended to include the form. After the push, the same-head contract review is re-run on the new head. The maintainer's approval needs a fresh look after the push.