@@ -0,0 +1,20 @@
+---
+'@objectstack/spec': minor
+'@objectstack/core': minor
+'@objectstack/plugin-security': minor
+'@objectstack/lint': minor
+'@objectstack/plugin-hono-server': minor
+---
+
+feat(spec,security): a field permission entry can carry a row condition (`when`) on its edit vote
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Ruling-ref: 6408558941
+
+- **Before.** A `fields["<object>.<field>"]` entry voted `readable` / `editable` on every row of the object. A lock that should apply on some rows only (the amount of an approved opportunity, say) had no spelling: a validation rule or a hook carried it, outside the permission model and outside `os explain`.
+- **Now.** `FieldPermissionSchema.when` is an optional row condition, authored in the same canonical CEL as `rowLevelSecurity[].using` (`status == 'approved'`, `owner_id == current_user.id`, …). An entry with a `when` votes as declared on the rows the condition names and is **absent** on the others, as if the set had not declared the field; an entry without one votes on every row, as before. The vote reaches the **edit** bit only — reads are row-blind — so `readable: false` beside a `when` is refused at parse, and the message says why. `condition`, `where` and `filter` are refused with a pointer to `when`.
+- **Judged on the row the write changes.** The write gate (the engine middleware's field-level step and `canWriteObject`) judges the **stored** row before an update, read as the caller reads it, and each **incoming** row of an insert — in process, by `RLSCompiler.compileRowPredicate` (the compile, `current_user` context, field guard and comparand faces an RLS `check` clause takes) and the write gate's own stored-form judge. Never a query rewrite. A row that cannot be judged — a predicate update, a stored row the caller cannot read, a condition that does not resolve for the request — applies the entry as its **lock** (no edit grant), and a WARN line says why.
+- **Row-blind readers apply the lock.** `/auth/me/permissions` (`buildEffectiveFieldPermissions`, new in `@objectstack/core`, the one vote `PermissionEvaluator.getFieldPermissions` takes per object), the writable-field projections, the query guard and the result masker hold no row, so a conditioned entry is reported as its lock: no client is told of an edit the gate refuses. `os explain`'s `fls` layer names each row-conditioned entry as such — judged per row by the write gate, applied as the lock elsewhere.
+- **Validated like an RLS predicate.** `@objectstack/lint`'s `validateRlsPredicateEnforceability` walks `permissions[].fields[].when` by the passes `using` / `check` take, against the key's object: `rls-predicate-unenforceable`, `-unparseable`, `-over-budget`, `-unknown-field`, `-unknown-user-variable`, with the cost named (the entry cannot be judged and is applied as its lock on every row).
+- **Unchanged.** Field grants union without deny: a matched conditioned lock is out-voted by a sibling's unconditioned `editable: true` exactly as before, and only declaring entries vote. The `/auth/me/permissions` `fields` merge keeps its most-permissive rule. Recorded under ADR-0066 ⑧ (note of 2026-10-26).
@@ -488,7 +488,7 @@ orthogonal to both, and no cell here can carry it; it is written out in
 | Organization-axis red lines (ADR-0105 D6) | ✓ | ✓ | ✓ | — |
 | Declared enforcement that cannot run, **declared on the object being written** — a validation rule's regex / JSON Schema (#4762) and its `format` names (#5178) | ✓ | ✓ | ✓ | ✓ᵒ |
 | Declared enforcement that cannot run, **declared on another collection** — sharing-rule conditions (#4698) | ✓ | ✓ | ✓ | — |
-| Row-level-security predicates (#4983) — a permission set's policies, an object's `defaultRowScope` and a membership key's `filter`; at the save door also a membership key nothing owns (#25234) | ✓ | ✓ | ✓ | ✓ᵖᵉᵒ |
+| Row-level-security predicates (#4983) — a permission set's policies, an object's `defaultRowScope`, a membership key's `filter` and a field permission entry's `when` (#25866); at the save door also a membership key nothing owns (#25234) | ✓ | ✓ | ✓ | ✓ᵖᵉᵒ |
 | Membership key declarations — `userField` / `valueField` columns, one key on one object, a key the registered resolver also owns (save door only) (#25234) | ✓ | ✓ | ✓ | ✓ᵒ |
 | Platform-schedule `create_record` organization (#6285) | — | — | — | ✓ᶠ |
 | Public-form anonymous intake on this deployment's tenancy posture — advisory only (#21476) | — | — | — | ✓ᵛ |
 
@@ -8,7 +8,8 @@ Control visibility and editability of specific fields.
 
 ## Field Permissions in Permission Sets
 
-Field permissions are keyed `<object>.<field>` and use `readable` / `editable`:
+Field permissions are keyed `<object>.<field>` and use `readable` / `editable`,
+plus an optional `when` — a row condition on the edit vote (below):
 
 ```typescript
 fields: {
@@ -22,6 +23,48 @@ fields: {
 }
 ```
 
+## Row-conditioned edit locks (`when`)
+
+An entry may carry `when`: a row condition in the same canonical CEL as an
+RLS `using` predicate (a field of the object compared with a literal or a
+`current_user.*` value; `==`, `!=`, `<`, `<=`, `>`, `>=`, `in`, combined with
+`&&` / `||`). The entry then votes **only on the rows the condition matches**
+and is absent on every other row, as if the set had not declared the field:
+
+```typescript
+fields: {
+  // Locked from approval onward; a draft is still editable.
+  'opportunity.amount': { readable: true, editable: false, when: "status in ['approved', 'closed']" },
+  // Editable on the caller's own rows only.
+  'task.estimate': { readable: true, editable: true, when: 'assigned_to == current_user.id' },
+}
+```
+
+- **Edit vote only.** Reads are judged row-blind, so `readable: false`
+  beside a `when` is refused at parse time; keep `readable: true` (the
+  default) on a row-conditioned entry.
+- **Which row.** The write gate judges the **stored** row before an update
+  (a lock on `status in [...]` holds on an approved row even when the same
+  write moves `status` back), and each **incoming** row of an insert, as the
+  caller sent it. The condition is evaluated in process against the row —
+  never rewritten into the query.
+- **When no row can be judged** — a predicate (bulk) update with no row
+  address, a stored row the caller cannot read, a condition that does not
+  resolve for the request — the entry is applied as its **lock**: no edit
+  grant on that write, and a WARN line says why.
+- **Readers that hold no row** (`/auth/me/permissions`, the writable-field
+  projections, `os explain`) report a row-conditioned entry as its lock, so
+  a client never advertises an edit the gate refuses. `os explain` names
+  each such entry as a row-conditioned lock in its `fls` layer.
+- **Union without deny is unchanged.** A matched conditioned lock is still
+  out-voted by another set's unconditioned `editable: true`; an entry
+  without `when` votes on every row, as before (ADR-0066 ⑧, note of
+  2026-10-26).
+- **Validated at authoring.** `objectstack validate` judges `when` like an
+  RLS predicate (`rls-predicate-*` findings on `permissions[].fields[].when`):
+  the fields it names must exist on the entry's object, no cross-object
+  reach, no unresolvable `current_user.*` variable.
+
 ## Hidden vs. Read-Only
 
 ```typescript
 
@@ -217,7 +217,7 @@ rowLevelSecurity:
 
 ## 3. Field-Level Security
 
-Field permissions are a map on the permission set keyed by `<object>.<field>`, each with two boolean flags (`FieldPermissionSchema`):
+Field permissions are a map on the permission set keyed by `<object>.<field>`, each with two boolean flags and an optional row condition (`FieldPermissionSchema`):
 
 ```yaml
 # sales_rep.permission.yml (continued)
@@ -256,10 +256,13 @@ fields:
   <object>.<field>:
     readable: true | false   # default true  — can see the field
     editable: true | false   # default false — can modify the field
+    when: "status == 'approved'"   # optional — a row condition on the EDIT vote, in RLS `using`'s CEL
 ```
 
 > There is no separate `create` flag for fields. `editable` governs both create-time and update-time writes; read stripping is governed by `readable`.
 
+> `when` narrows **where** the entry votes: on a matching row it votes as declared, on every other row it is absent (as if the set had not declared the field). The write gate judges the stored row before an update and each incoming row of an insert, in process; a row it cannot judge (a predicate update, a stored row the caller cannot read, a condition that does not resolve for the request) applies the entry as its lock. `readable: false` beside a `when` is refused at parse time, and `objectstack validate` judges the condition like an RLS predicate. Readers that hold no row (`/auth/me/permissions`, `os explain`) report the entry as its lock. See [Field-level security](/docs/permissions/field-level-security#row-conditioned-edit-locks-when).
+
 ### Static `readonly` fields on the write path
 
 `readonly: true` on a field definition is a *schema-level* lock, independent of permission
 
@@ -1633,7 +1633,7 @@ One changed key path of the pending draft, and the last write that changed it.
 | :--- | :--- | :--- | :--- |
 | **object** | `string` | ✅ | Object name |
 | **permissions** | `{ allowCreate?: boolean; allowRead?: boolean; allowEdit?: boolean; allowDelete?: boolean; … }` | ✅ | Object-level permissions |
-| **fieldPermissions** | `Record<string, { readable?: boolean; editable?: boolean }>` | optional | Field-level permissions keyed by field name |
+| **fieldPermissions** | `Record<string, { readable?: boolean; editable?: boolean; when?: string }>` | optional | Field-level permissions keyed by field name |
 
 ### Nested Shape: `GetObjectPermissionsResponse.permissions`
 
@@ -1658,6 +1658,7 @@ One changed key path of the pending draft, and the last write that changed it.
 | :--- | :--- | :--- | :--- |
 | **readable** | `boolean` | optional (default: `true`) | Field read access |
 | **editable** | `boolean` | optional (default: `false`) | Field edit access |
+| **when** | `string` | optional | Row condition narrowing where this entry votes, authored in canonical CEL like `rowLevelSecurity[].using` (a field of this object compared with a literal or a `current_user.*` value using `==`, `!=`, `<`, `<=`, `>`, `>=` or `in`, combined with `&&` / `\|\|`; e.g. status in ["approved", "signing", "active"]). Absent, the entry votes on every row. Present, the entry votes as declared on the rows the condition matches and is ABSENT on every other row, so the most-permissive merge across the caller's sets and the rule that only declaring sets vote are unchanged: a set that locks a field only from a stage onward does not lock the rows before it, and a co-held set that says nothing about the field still lifts nothing. The write gate judges the condition on the stored row BEFORE an update (so a lock on `status in [...]` holds on an approved row even when the write changes `status`) and on the incoming row of an insert, as the caller sent it. It reaches the EDIT vote only — reads are judged row-blind — so `readable: false` beside a `when` is refused at parse time: keep `readable: true` (the default) on a row-conditioned entry. Where no row can be judged (a predicate update with no row address, a stored row the caller cannot read, a condition that does not resolve for the request) the entry is judged as its lock: it contributes no edit grant on that write. Validated like an RLS predicate at authoring and publish time: the fields it names must exist on the entry's object and it may not reach across a relation; a condition that cannot be lowered is refused there, never dropped at runtime. Readers that hold no row (`/auth/me/permissions`, the field projections, the write preview on an update) report a row-conditioned entry as its lock, so a client never advertises an edit the gate refuses. |
 
 
 ---
 
@@ -69,6 +69,7 @@ const result = AdminScopeSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **readable** | `boolean` | optional (default: `true`) | Field read access |
 | **editable** | `boolean` | optional (default: `false`) | Field edit access |
+| **when** | `string` | optional | Row condition narrowing where this entry votes, authored in canonical CEL like `rowLevelSecurity[].using` (a field of this object compared with a literal or a `current_user.*` value using `==`, `!=`, `<`, `<=`, `>`, `>=` or `in`, combined with `&&` / `\|\|`; e.g. status in ["approved", "signing", "active"]). Absent, the entry votes on every row. Present, the entry votes as declared on the rows the condition matches and is ABSENT on every other row, so the most-permissive merge across the caller's sets and the rule that only declaring sets vote are unchanged: a set that locks a field only from a stage onward does not lock the rows before it, and a co-held set that says nothing about the field still lifts nothing. The write gate judges the condition on the stored row BEFORE an update (so a lock on `status in [...]` holds on an approved row even when the write changes `status`) and on the incoming row of an insert, as the caller sent it. It reaches the EDIT vote only — reads are judged row-blind — so `readable: false` beside a `when` is refused at parse time: keep `readable: true` (the default) on a row-conditioned entry. Where no row can be judged (a predicate update with no row address, a stored row the caller cannot read, a condition that does not resolve for the request) the entry is judged as its lock: it contributes no edit grant on that write. Validated like an RLS predicate at authoring and publish time: the fields it names must exist on the entry's object and it may not reach across a relation; a condition that cannot be lowered is refused there, never dropped at runtime. Readers that hold no row (`/auth/me/permissions`, the field projections, the write preview on an update) report a row-conditioned entry as its lock, so a client never advertises an edit the gate refuses. |
 
 
 ---
@@ -121,7 +122,7 @@ const result = AdminScopeSchema.parse(data);
 | **managedBy** | `never` | optional | [REMOVED] `permission.managedBy` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove, ADR-0086 D3) — nothing ever read the authored key: no seeder, package upgrade or lock consulted it, so `package` never made a set upgrade-owned and `platform` or `user` never shielded one from an upgrade. Delete the key; a set's provenance is the package that ships it, decided from that package's artifact and recorded as `packageId`, and a set authored in this system carries neither. Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand. |
 | **isDefault** | `boolean` | optional (default: `false`) | [ADR-0090 D5] App baseline for the everyone position: app-level sets are auto-bound at boot (guarded, idempotent); package-level sets become install-time suggestions an admin confirms |
 | **objects** | `Record<string, { allowCreate?: boolean; allowRead?: boolean; allowEdit?: boolean; allowDelete?: boolean; … }>` | ✅ | Entity permissions |
-| **fields** | `Record<string, { readable?: boolean; editable?: boolean }>` | optional | Field level security |
+| **fields** | `Record<string, { readable?: boolean; editable?: boolean; when?: string }>` | optional | Field level security |
 | **systemPermissions** | `string[]` | optional | System level capabilities |
 | **tabPermissions** | `Record<string, Enum<'visible' \| 'hidden' \| 'default_on' \| 'default_off'>>` | optional | App/tab visibility: visible, hidden, default_on (shown by default), default_off (available but hidden initially) |
 | **rowLevelSecurity** | `{ name: string; label?: string; description?: string; object: string; … }[]` | optional | Row-level security policies (see rls.zod.ts for full spec) |
@@ -158,6 +159,7 @@ const result = AdminScopeSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **readable** | `boolean` | optional (default: `true`) | Field read access |
 | **editable** | `boolean` | optional (default: `false`) | Field edit access |
+| **when** | `string` | optional | Row condition narrowing where this entry votes, authored in canonical CEL like `rowLevelSecurity[].using` (a field of this object compared with a literal or a `current_user.*` value using `==`, `!=`, `<`, `<=`, `>`, `>=` or `in`, combined with `&&` / `\|\|`; e.g. status in ["approved", "signing", "active"]). Absent, the entry votes on every row. Present, the entry votes as declared on the rows the condition matches and is ABSENT on every other row, so the most-permissive merge across the caller's sets and the rule that only declaring sets vote are unchanged: a set that locks a field only from a stage onward does not lock the rows before it, and a co-held set that says nothing about the field still lifts nothing. The write gate judges the condition on the stored row BEFORE an update (so a lock on `status in [...]` holds on an approved row even when the write changes `status`) and on the incoming row of an insert, as the caller sent it. It reaches the EDIT vote only — reads are judged row-blind — so `readable: false` beside a `when` is refused at parse time: keep `readable: true` (the default) on a row-conditioned entry. Where no row can be judged (a predicate update with no row address, a stored row the caller cannot read, a condition that does not resolve for the request) the entry is judged as its lock: it contributes no edit grant on that write. Validated like an RLS predicate at authoring and publish time: the fields it names must exist on the entry's object and it may not reach across a relation; a condition that cannot be lowered is refused there, never dropped at runtime. Readers that hold no row (`/auth/me/permissions`, the field projections, the write preview on an update) report a row-conditioned entry as its lock, so a client never advertises an edit the gate refuses. |
 
 ### Nested Shape: `PermissionSet.rowLevelSecurity[number]`