feat(spec): ShareRecipientType gains field — the record-relative sharing recipient (#14103) (#15084)

* feat(spec): ShareRecipientType gains field — the record-relative sharing recipient

Maintainer ruling 2026-09-02 (B): a criteria sharing rule may name a user-typed
field on the matched record as its recipient; no manager member. Spec half only:
enum member + describes, field-scoped value refinement, stored-row union mirror,
pins, lint partition row, docs, changeset. Executor is the services half.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

* chore(spec): regenerate sharing reference docs; keep the manager refusal pin independent of the accept set

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

* docs(permissions): enforcement-status sentence tells the truth between the field recipient and its executor

The permissions matrix said every authorable recipient type is enforced; between
the field recipient landing and its per-record executor that is false. Say what
is true: it parses, and the declared-rule bootstrap skips it with a logged
warning until the executor lands — never silently, never wider.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174WZTU6XcFcS7g2kykC53i

---------

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

Author: claude[bot]

.changeset/sharing-rule-field-recipient.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `ShareRecipientType` gains `field` — a sharing rule can share each matched record with the user or users a field on that record names (#14103)
+
+Maintainer ruling 2026-09-02 (B): a criteria sharing rule may now be authored as
+`sharedWith: { type: 'field', value: 'assignees' }`, where `value` is the snake_case
+name of a user-typed field on the shared object. Each record the rule's `condition`
+matches is shared with the user or users that column holds on that record; a field
+with `multiple: true` shares with every user it names; an empty column shares with
+nobody (fail-closed). Unlike every other recipient, which resolves once per rule,
+a `field` recipient expands once per matched record, and its grants re-materialise
+when the record's own write changes that column.
+
+There is deliberately **no `manager` member**. "Share with the owner's manager" is
+authored as a user field the application stores on the record (a snapshot or kept
+in sync — the application's explicit choice) plus a `field` recipient naming it. A
+`manager` member would walk `sys_user.manager_id` from the record and re-introduce
+the graph-change re-materialisation obligation that once removed the `owner`
+recipient type; with `field` the recipient stays visible on the record.
+
+What this release ships is the **contract**: the enum member, the `sharedWith`
+describe text, a `field`-scoped refinement on `value` (an empty name or a dotted
+path such as `owner.manager_id` is refused at parse — a field name, never a graph
+walk), the stored-row mirror `SharingRuleRecipientType` in `contracts/sharing-service.ts`
+widened in step, and the generated JSON schema / authorable surface / reference
+docs. The per-record executor (`plugin-sharing` `expandRecipient`, the
+`sys_sharing_rule.recipient_type` select, re-materialisation on the record's own
+update) is the services half, #15072; until it lands the declared-rule bootstrap
+skips a `field` rule with a logged warning rather than seeding it.
+
+Accept-set widening only: every sharing rule that parsed before parses
+identically — the refinement is scoped to `type: 'field'`, and the other members'
+`value` stays the opaque string it was.

content/docs/permissions/permissions-matrix.mdx

@@ -152,7 +152,7 @@ Sharing rules extend access beyond ownership and the depth axis. The declarative
 | **Criteria-Based** | `criteria` | Share records matching a CEL predicate over field values | All opportunities where `record.amount > 100000` are shared with "VP Sales" |
 
 <Callout type="warn">
-**Enforcement status:** every authorable rule and recipient type is enforced. v17 reconciled the surface with the runtime (#1878): `owner`-type rules (`type: 'owner'`, `ownedBy`) and `group` / `guest` recipients — previously declared but skipped at seed time — **no longer parse**; `group` became the enforced `team` and `business_unit` joined the enum. That is a stronger statement than "declared but not enforced": a skipped rule is still authorable and is ignored, whereas a removed one is rejected by `SharingRuleSchema`, so a stale definition fails loudly at authoring time instead of silently doing nothing (ADR-0078). See [Sharing Rules](/docs/permissions/sharing-rules#recipient-types).
+**Enforcement status:** every authorable rule type is enforced, and so is every recipient type but the newest: the `field` recipient (#14103) parses, and until its per-record executor (#15072) lands the declared-rule bootstrap skips such a rule with a logged warning — never silently, never as a wider grant. v17 reconciled the surface with the runtime (#1878): `owner`-type rules (`type: 'owner'`, `ownedBy`) and `group` / `guest` recipients — previously declared but skipped at seed time — **no longer parse**; `group` became the enforced `team` and `business_unit` joined the enum. That is a stronger statement than "declared but not enforced": a skipped rule is still authorable and is ignored, whereas a removed one is rejected by `SharingRuleSchema`, so a stale definition fails loudly at authoring time instead of silently doing nothing (ADR-0078). See [Sharing Rules](/docs/permissions/sharing-rules#recipient-types).
 </Callout>
 
 <Callout type="info">

content/docs/permissions/sharing-rules.mdx

@@ -132,9 +132,9 @@ export const AccountTeamSharingRule = defineSharingRule({
 
 ### Recipient types
 
-`sharedWith` accepts a `{ type, value }` recipient. **Every authorable
-recipient is enforced** — each expands to concrete users at seed time and
-materializes `sys_record_share` grants:
+`sharedWith` accepts a `{ type, value }` recipient. Every recipient expands to
+concrete users and materializes `sys_record_share` grants — once per **rule**
+for the first five, once per **matched record** for `field`:
 
 | `type` | Shares with |
 |:--|:--|
@@ -143,6 +143,7 @@ materializes `sys_record_share` grants:
 | `position` | Everyone assigned that position (flat expansion — positions have no tree) |
 | `unit_and_subordinates` | Everyone in that **business unit and every unit beneath it** (the BU tree is the one hierarchy — ADR-0090 D3) |
 | `business_unit` | Everyone in exactly that business unit (no subtree) |
+| `field` | The user or users named by a **user-typed field on each matched record** — `value` is that field's name (`assignees`). A `multiple: true` field shares with every user it holds; an empty column shares with nobody. There is deliberately no `manager` recipient: "the owner's manager" is a user field the application stores on the record, named here (maintainer ruling 2026-09-02, objectstack#14103). The per-record executor is objectstack#15072 — until it lands, a `field` rule is skipped with a logged warning at seed, never seeded wider |
 
 A criteria `condition` must be compilable by the CEL → filter pushdown
 compiler. A condition the compiler cannot lower is **skipped and logged —

content/docs/protocol/objectql/security.mdx

@@ -377,12 +377,14 @@ object: account
 accessLevel: read           # read | edit
 condition: 'record.account_type == "Enterprise"'
 sharedWith:
-  type: position            # user | team | position | unit_and_subordinates | business_unit
+  type: position            # user | team | position | unit_and_subordinates | business_unit | field
   value: sales_rep
 ```
 
 `unit_and_subordinates` expands a **business-unit subtree**: the unit named by `value` plus every descendant unit's members (ADR-0057 D5 / ADR-0090 D3 — the former position-tree walk was re-homed onto the `sys_business_unit` tree).
 
+`field` is the **record-relative** recipient (#14103, maintainer ruling 2026-09-02): `value` names a user-typed field on the object, and each matched record is shared with the user or users that column holds on it (`multiple: true` shares with every user it names; an empty column shares with nobody). It expands once per matched record, not once per rule. There is no `manager` recipient — "the owner's manager" is a user field the application stores on the record, named by a `field` recipient. The per-record executor is #15072.
+
 ### Owner-Based Sharing — removed in v17
 
 Owner-based rules (`type: 'owner'`, `ownedBy`) were removed from the authoring
@@ -417,7 +419,7 @@ sharedWith:
   value: west_region_managers
 ```
 
-> **Enforcement status.** Every authorable rule and recipient type is enforced. Criteria rules with `user` / `team` / `position` / `unit_and_subordinates` / `business_unit` recipients compile and enforce (the CEL condition lowers to a runtime filter that materializes `sys_record_share` grants, ADR-0058 D3). Owner-type rules and the `group` / `guest` recipients are **not** `[experimental — not enforced]` and are no longer skipped at seed time — v17 removed them from the schema, so they do not parse at all (see above). What is still skipped-and-logged is a `condition` the compiler cannot lower (functions, cross-object traversal): it is never seeded as a permissive match-all (ADR-0049).
+> **Enforcement status.** Criteria rules with `user` / `team` / `position` / `unit_and_subordinates` / `business_unit` recipients compile and enforce (the CEL condition lowers to a runtime filter that materializes `sys_record_share` grants, ADR-0058 D3). The `field` recipient is the contract half of a two-part landing (#14103): it parses, and until its per-record executor (#15072) lands the declared-rule bootstrap skips such a rule with a logged warning — never silently, never as a wider grant. Owner-type rules and the `group` / `guest` recipients are **not** `[experimental — not enforced]` and are no longer skipped at seed time — v17 removed them from the schema, so they do not parse at all (see above). What is still skipped-and-logged is a `condition` the compiler cannot lower (functions, cross-object traversal): it is never seeded as a permissive match-all (ADR-0049).
 
 > `accessLevel` is one of `read` or `edit`. Sharing widens **which rows** a principal reaches, never **which verbs** they may use — an `edit` share opens *update*, not *delete*: delete comes from ownership, the ADR-0057 DEPTH scopes, or the `modifyAllRecords` bypass, enforced by the sharing layer's own `canDelete` gate (distinct from the `canEdit` update gate) on top of the object-level CRUD gate (ADR-0111 D3). A third level `full` ("Full Access — transfer/share/delete") was authorable through protocol 16 but never granted any of those verbs: both enforcement sites matched `edit`/`full` alike, so it was equivalent to `edit` while telling admins otherwise, and it was removed (#3865, ADR-0078). Stacks still authoring it are rewritten to `edit` at load by the `sharing-rule-access-level-full-to-edit` conversion.
 

content/docs/references/security/sharing.mdx

@@ -33,7 +33,7 @@ const result = CriteriaSharingRuleSchema.parse(data);
 | **object** | `string` | ✅ | Target Object Name |
 | **active** | `boolean` | optional (default: `true`) |  |
 | **accessLevel** | `Enum<'read' \| 'edit'>` | optional (default: `"read"`) |  |
-| **sharedWith** | `{ type: Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit'>; value: string }` | ✅ | The recipient of the shared access |
+| **sharedWith** | `{ type: Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit' \| 'field'>; value: string }` | ✅ | The recipient of the shared access: a principal resolved once per rule, or — `type: field` — the user or users named by a field on each matched record |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -48,8 +48,8 @@ const result = CriteriaSharingRuleSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit'>` | ✅ |  |
-| **value** | `string` | ✅ | ID or code of the recipient (user / team / position / business unit) |
+| **type** | `Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit' \| 'field'>` | ✅ |  |
+| **value** | `string` | ✅ | The recipient principal: the id or code of the user / team / position / business unit — or, for `type: 'field'`, the snake_case name of a user-typed field on the record whose value names the user or users to share each matched record with |
 
 
 ---
@@ -75,6 +75,7 @@ const result = CriteriaSharingRuleSchema.parse(data);
 * `position`
 * `unit_and_subordinates`
 * `business_unit`
+* `field`
 
 
 ---
@@ -101,7 +102,7 @@ const result = CriteriaSharingRuleSchema.parse(data);
 | **object** | `string` | ✅ | Target Object Name |
 | **active** | `boolean` | optional (default: `true`) |  |
 | **accessLevel** | `Enum<'read' \| 'edit'>` | optional (default: `"read"`) |  |
-| **sharedWith** | `{ type: Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit'>; value: string }` | ✅ | The recipient of the shared access |
+| **sharedWith** | `{ type: Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit' \| 'field'>; value: string }` | ✅ | The recipient of the shared access: a principal resolved once per rule, or — `type: field` — the user or users named by a field on each matched record |
 | **_lock** | `Enum<'none' \| 'no-overlay' \| 'no-delete' \| 'full'>` | optional | Item-level lock — controls overlay & delete (ADR-0010). |
 | **_lockReason** | `string` | optional | Human-readable reason shown when a write is refused by _lock. |
 | **_lockSource** | `Enum<'artifact' \| 'package' \| 'env-forced'>` | optional | Layer that set _lock (artifact \| package \| env-forced). |
@@ -116,8 +117,8 @@ const result = CriteriaSharingRuleSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit'>` | ✅ |  |
-| **value** | `string` | ✅ | ID or code of the recipient (user / team / position / business unit) |
+| **type** | `Enum<'user' \| 'team' \| 'position' \| 'unit_and_subordinates' \| 'business_unit' \| 'field'>` | ✅ |  |
+| **value** | `string` | ✅ | The recipient principal: the id or code of the user / team / position / business unit — or, for `type: 'field'`, the snake_case name of a user-typed field on the record whose value names the user or users to share each matched record with |
 
 
 ---

packages/lint/src/validate-org-axis-red-lines.test.ts

@@ -434,12 +434,14 @@ describe('validateOrgAxisRedLines — undeclared keys are the schema’s job, no
 /**
  * ── Rule ②'s recipient word list ────────────────────────────────────────────
  *
- * The two BU-tree recipients ② intercepts, and the three it deliberately lets
- * past. Split out here because the drift guard below asserts the two halves
- * partition `ShareRecipientType` exactly — the check whose absence is #4991.
+ * The two BU-tree recipients ② intercepts, and the four it deliberately lets
+ * past (`field` — #14103 — is read off the matched record itself: no tree, so
+ * nothing for ② to scope). Split out here because the drift guard below
+ * asserts the two halves partition `ShareRecipientType` exactly — the check
+ * whose absence is #4991.
  */
 const BU_TREE_RECIPIENTS = ['business_unit', 'unit_and_subordinates'] as const;
-const FLAT_RECIPIENTS = ['user', 'team', 'position'] as const;
+const FLAT_RECIPIENTS = ['user', 'team', 'position', 'field'] as const;
 
 describe('validateOrgAxisRedLines — ② business-unit trees stay org-internal', () => {
   const platformGlobalStack = (

packages/lint/src/validate-org-axis-red-lines.ts

@@ -118,7 +118,7 @@ const ORG_PARENT_FIELD = 'parent_organization_id';
  * Cross-checked word-for-word against the authoring enum `ShareRecipientType`
  * (`@objectstack/spec/security`, `sharing.zod.ts`) — the only vocabulary an
  * author can write, since `sharedWith` is `.strict()` and rejects everything
- * else by name. That enum has FIVE members; this list intercepts two, and the
+ * else by name. That enum has SIX members; this list intercepts two, and the
  * difference is deliberate, not an oversight (it is exactly the oversight
  * #4991 was filed for — ② shipped naming only `business_unit` while ADR-0105
  * D6 ②'s own text names `unit_and_subordinates`):
@@ -130,11 +130,13 @@ const ORG_PARENT_FIELD = 'parent_organization_id';
  * | `user`                  | — | A literal user id, no expansion at all. No tree to resolve, so no org to resolve it in. |
  * | `team`                  | — | `sys_team` is a FLAT collaboration grouping (ADR-0090 D3 renamed `group` → `team`); `TeamGraphService`, not the BU graph. |
  * | `position`              | — | Flat holder expansion (ADR-0090 D3 finalized the retirement of the position hierarchy); `PositionGraphService`, not the BU graph. The BU *depth scopes* D6 ② also names are a SCOPE mechanism, not a sharing-rule recipient. |
+ * | `field`                 | — | RECORD-RELATIVE (#14103, maintainer ruling 2026-09-02): the user or users a user-typed column on the matched record names — read off the row itself, no tree walked, so no organization needed to resolve one in. Per-record expansion is `plugin-sharing`'s (#15072). |
  *
- * The three allowed recipients are the sanctioned way to share a
- * platform-global object (ADR-0066): naming a user, a flat team, or a flat
- * position audience grants those people the catalog, which is the entire point
- * of `tenancy.enabled: false`. What ② forbids is not "sharing a global object"
+ * The four allowed recipients are the sanctioned way to share a
+ * platform-global object (ADR-0066): naming a user, a flat team, a flat
+ * position audience, or the users a column on the record itself names grants
+ * those people the catalog, which is the entire point of
+ * `tenancy.enabled: false`. What ② forbids is not "sharing a global object"
  * but "resolving a BU SUBTREE with no organization to resolve it within".
  *
  * The runtime contract `SharingRuleRecipientType`

packages/spec/src/contracts/sharing-service.test.ts

@@ -63,12 +63,31 @@ describe('Sharing Service Contract — recipient vocabularies (#4539)', () => {
       'position',
       'unit_and_subordinates',
       'business_unit',
+      // [#14103] the record-relative recipient — a user-typed field on the
+      // matched record; per-record expansion is the services half (#15072).
+      'field',
     ]);
     const ruleRecipient: SharingRuleRecipientType = 'queue';
     // @ts-expect-error `queue` is reserved to the runtime rule contract — not authorable
     const notAuthorable: (typeof ShareRecipientType.options)[number] = 'queue';
     expect(ruleRecipient).toBe(notAuthorable);
   });
+
+  it('the stored-row union is exactly the authoring enum plus the reserved `queue` (#14103)', () => {
+    // `plugin-sharing`'s declared-rule bootstrap copies `sharedWith.type` onto
+    // `sys_sharing_rule.recipient_type` member-for-member (an unmapped value is
+    // skipped with a warning), so a member added to one list and not the other
+    // is a rule that parses and is never seeded — the ADR-0078 shape. Pinned at
+    // the TYPE level so the drift is a compile error, not a runtime surprise.
+    type Authorable = (typeof ShareRecipientType.options)[number];
+    const inStep: Assert<Eq<Exclude<SharingRuleRecipientType, 'queue'>, Authorable>> = true;
+    expect(inStep).toBe(true);
+    // And at the VALUE level: every authorable member is assignable to the
+    // stored-row union (a runtime list, so a reader sees the members).
+    const stored: SharingRuleRecipientType[] = [...ShareRecipientType.options, 'queue'];
+    expect(stored).toHaveLength(ShareRecipientType.options.length + 1);
+    expect(stored).toContain('field');
+  });
 });
 
 /**