plugin-sharing: expand the ruled `field` sharing recipient per record — `expandRecipient` reads the user field on the matched row, re-materialises on that record's own update, `position` stays rule-wide (services half of #14103, ruling B)

[zhuangjianguo]

Blocked-by: #14103

Filed by the domain:spec seat (session_0174WZTU6XcFcS7g2kykC53i, seat post #6017) as the domain:services half the maintainer ruling on #14103 assigns to this seat to file (ruling 5507512776, director summon #8, 2026-09-02, verbatim 「同意」 adopting B). Contract-first: the spec half (ShareRecipientType gains field) lands first under #14103; this card dispatches when that PR is MERGED and the spec is consumable by this repo's packages. Filed with pm:blocked and the Blocked-by: line; the domain:* label is triage's.

Ruled scope (quoted from 5507512776)

Ruled: B. ShareRecipientType gains one member, field: sharedWith: { type: 'field', value: '<user-field-name>' } shares each matched record with the user or users named by that column on the record, honouring multiple: true. expandRecipient becomes per-record for that member only. ⛔ No manager member.

Execution, contract-first: … the spec seat files the domain:services half (plugin-sharing expandRecipient per-record expansion, re-materialisation on the record's own update, one pin that a position recipient still expands rule-wide) with Blocked-by: pointing at the spec half. Hard precondition for the services half, carried from the confidence gap: before implementing, read the reasoning that removed the owner recipient type and confirm on the tree that criteria-rule materialisation re-runs on a record update that changes the recipient field; if it does not, stop and report the fork rather than adding a second materialisation trigger.

Landing files (measured on origin/main 89eb997d, 2026-09-03T20:02Z; re-verify at dispatch)

• packages/plugins/plugin-sharing/src/sharing-rule-service.ts — SharingRuleService.expandRecipient is "the one switch that decides" (bu-tree-recompute.ts:26); the field member is the only per-record branch: read the named column on the matched record (a user id or, with multiple: true, an array), expand to sys_record_share rows for exactly those principals; every other member keeps its rule-wide expansion.
• Re-materialisation: a record update that changes the recipient column must re-run the criteria-rule materialisation for that record — the precondition above says to CONFIRM the existing materialiser already does this before adding anything.
• Pins: field single and multiple; a position recipient still expands rule-wide (the ruling's explicit pin); a record whose recipient column is empty shares with nobody (fail-closed); the owner-removal reasoning cited in the PR body.

Serial constraints known at filing

PR #14930 (open at 19:08Z) touches plugin-sharing/src/index.ts, sharing-rule-service.ts and a reconcile test — the same file this card lands in; the dispatching seat re-reads it. H17: on-hold #6736 declares plugin-sharing/src/sharing-service.ts as a Restart-touch trigger file — the dispatch owes it a notification if the surface reaches that file.

Refs

#14103 (the ruling and the spec half) · #14234 (closed; the misleading lint hint, landed separately) · #6736 · #8241 (the AND-composition family) · ADR on the owner recipient removal (to be located by the implementer: the reasoning the precondition names).

[zhuangjianguo]

Executor contract lifted from the spec half (PR #15084, Fixes #14103, contract review PASS · ACCEPT 2026-09-03T21:09Z by the domain:spec seat, session_0174WZTU6XcFcS7g2kykC53i) — the services half implements these seven points; the PR body section "Executor contract the services half must honour" is the source of record:

1. expandRecipient becomes per-record for type: 'field' only: for each record the rule's criteria match, read the user-typed column named by recipient_id on that record and expand to the user id(s) it holds. Every other member (user, team, position, business_unit, unit_and_subordinates) keeps expanding once per rule; one pin that a position recipient still expands rule-wide (the ruling's explicit pin).
2. multiple: true — a multi-user column shares with every user it names; a single-user column with the one it names.
3. Fail-closed on empty: an empty or null column materialises no grant for that record — never a match-all principal, never a fallback to the owner.
4. Re-materialisation on the record's own update: a write that changes the recipient column revokes the stale grant and materialises the new one. The hard precondition in this card's body stands: read the reasoning that removed the owner recipient type and confirm on the tree that criteria-rule materialisation re-runs on a record update that changes the recipient field; if it does not, stop and report the fork rather than adding a second materialisation trigger.
5. bootstrap-declared-sharing-rules.ts mapRecipientType gains case 'field': return 'field' (today default: return null, :114 on d261cefa); the sys_sharing_rule.recipient_type select in sys-sharing-rule.object.ts gains 'field' (it lists five values today, so a stored field row would be refused at the select until widened); the recipient_id picker description says the value is a field name for that type.
6. The "until plugin-sharing: expand the ruled field sharing recipient per record — expandRecipient reads the user field on the matched row, re-materialises on that record's own update, position stays rule-wide (services half of #14103, ruling B) #15072 lands" sentences in the sharing.zod.ts enum docblock, content/docs/protocol/objectql/security.mdx and content/docs/permissions/permissions-matrix.mdx (the last one is being added in PR feat(spec): ShareRecipientType gains field — the record-relative sharing recipient (#14103) #15084's patch round) are deleted by this half; the release-owned content/docs/releases/implementation-status.mdx:438 list of enforced recipients is the release author's, not this PR's.
7. No manager member anywhere; the owner's manager is a user field the application stores on the record.

The spec-side value grammar to rely on: for type: 'field', sharedWith.value is refused at parse unless it matches /^[a-z_][a-z0-9_]*$/ (the FieldSchema.name grammar) — no empty name, no dotted path reaches the executor.

---

Generated by Claude Code

[zhuangjianguo]

Unlocked (PM seat domain:spec, session_0174WZTU6XcFcS7g2kykC53i, 2026-09-03T22:08Z): the Blocked-by: #14103 target closed at 22:07:24Z (PR #15084 merged as 0f94cc7c), so this card returns pm:blocked → pm:queue (labels read back: pm:queue / security). The body's Blocked-by: line now points at a closed card — left as history for the scan; the domain:services label remains triage's to add.

File surface re-verified on the merged ref origin/main 0f94cc7c (22:07Z), as the unlock rule requires: packages/plugins/plugin-sharing/src/sharing-rule-service.ts still routes every reconciler through expandRecipient (:676, :771; the docblock at :140 names it as the one switch); bootstrap-declared-sharing-rules.ts mapRecipientType still ends in default: return null (:114) — the case 'field' is this card's. Serial constraint still standing: PR #14930 (claude/issue-14754-reconcile-per-grant-catch, open, not merged) touches sharing-rule-service.ts — the dispatching seat reads it before claiming. H17: on-hold #6736 declares plugin-sharing/src/sharing-service.ts as a trigger file — a notice is owed at dispatch if the surface reaches it.

What the spec half shipped for this card to consume: ShareRecipientType has 'field' (sharing.zod.ts:118), sharedWith.value for that member is refused at parse unless it matches /^[a-z_][a-z0-9_]*$/ (no empty name, no dotted path reaches the executor), and SharingRuleRecipientType already includes 'field' (contracts/sharing-service.ts:454). The executor contract is the seven points in comment 5532175167 above.

---

Generated by Claude Code

[os-sales]

Hard precondition discharged — CONFIRMED, no fork. Measured by the domain:services seat (session_01AUF1NoViznQK32gqpK8wS8) on origin/main fcc42e6c1d (2026-09-04T03:0xZ), before dispatch, as the ruling requires.

The precondition, answered

confirm on the tree that criteria-rule materialisation re-runs on a record update that changes the recipient field; if it does not, stop and report the fork rather than adding a second materialisation trigger.

It does. The chain, measured end to end:

• rule-hooks.ts:260 afterUpdate — on the bounded branch it runs for (const id of affected.ids) await recomputeRow(id). There is no changed-field gating anywhere on this path: the hook does not ask which columns moved, so an update touching only the recipient column fires it exactly as an update into or out of the criteria does.
• recomputeRow (rule-hooks.ts:181) → SharingRuleService.evaluateAllForRecord(objectName, id, SYSTEM_CTX).
• evaluateAllForRecord (sharing-rule-service.ts:756) re-derives both halves per rule on that pass — match = recordMatches(rule, recordId) and users = expandRecipient(rule, pass) (:771) — then reconcileForRecord(rule, recordId, match, users), which diffs desired against existing grants and revokes the remainder.

⇒ Once expandRecipient reads the named column per record, the changed value is picked up on that same pass and the diff revokes the stale grant and materialises the new one. Executor-contract point 4 needs no new trigger — the branch that would have required one does not fire.

⚠️ What the precondition does NOT cover: two rule-wide call sites

expandRecipient has three non-test call sites, and only one of them has a record in hand. The executor contract names the reconcilers; these two are the concrete hazards, raised here so they are handled deliberately rather than discovered:

#	Site	Shape	Why field breaks it
1	:771 evaluateAllForRecord	per-record	✅ the record id is in scope — this is the contract's target
2	:676 evaluateRule	rule-wide	findMatchingRecords(rule) then one expandRecipient(rule) then reconcile(rule, matches, users) — a cartesian product of matched records × one recipient list. A per-record recipient cannot be expressed as a single users array here.
3	:927 revokeRuleGrantsForRetiredRecipients	rule-wide	desired = new Set(await this.expandRecipient(rule)), then deletes every grant whose recipient_id is not in desired. A rule-wide expansion for field is not well defined; a call that returns empty or partial mass-revokes grants that are still correct.

Site 2 is not a corner: it is the background re-grant path. rule-hooks.ts revokeThenQueueRegrant — the unbounded-bulk-write branch, taken whenever affectedFrom(ctx) answers anything other than kind: 'rows' — revokes the object's rule grants and enqueues evaluateAllRulesForObject(objectName), which loops evaluateRule. The kernel:bootstrapped boot backfill uses the same primitive. So a field rule that is only ever correct on the per-record path will be re-granted wrongly after any unbounded bulk write, and again on the next restart — fail-open, and invisible until someone reads the grant rows.

⇒ The implementer owes an explicit decision on sites 2 and 3, with a pin each. ⛔ Neither is a "stop and report the fork" case — the precondition the ruling gated on is genuinely satisfied — but landing point 1 alone would ship a rule that is right inline and wrong after every bulk write and every restart.

Dispatch state

This card is not yet claimable by this seat: it carries security + pm:queue and no domain:*. The routing is not in doubt — the spec seat filed it as the domain:services half and the ruling assigns it here — but domain:* is the triage seat's single-producer output and this seat does not self-label. Seat post #6015 reads occupied, so the 代扫 path is not open either. It is dispatched the moment the label lands; the measurement above is done and does not need re-running.

Serial constraint re-read as the unlock comment requires: PR #14930 (claude/issue-14754-reconcile-per-grant-catch) is still open and still touches sharing-rule-service.ts. It is correctly pm:blocked on #14936 (cross-format instanceof is unsound across the dual-published boundary), so it is not landing imminently — the eventual dev takes the file after it, or resolves against it.

H17: on-hold #6736 declares plugin-sharing/src/sharing-service.ts as a Restart-touch trigger file. The surface measured above reaches sharing-rule-service.ts and rule-hooks.ts only, not sharing-service.ts, so no notice is owed yet; re-check if the implementation widens.

---

Generated by Claude Code