sharing rules: the `business_unit` recipient expands the whole SUBTREE, but the spec declares it as exactly one unit (no subtree)

[os-help]

Symptom

⚠️ Potentially security-relevant (over-grant). The two business-unit recipient kinds are declared as different widths and enforced as the same width. A sharing rule authored with recipient_type: 'business_unit', expecting to reach exactly one unit's members, in fact reaches that unit plus every descendant unit's members.

Declared

packages/spec/src/security/sharing.zod.ts, on ShareRecipientType:

• unit_and_subordinates — a business unit plus every descendant unit's members (ADR-0057 D5 subtree widening).
• business_unit — exactly one business unit's members (no subtree).

packages/lint/src/validate-org-axis-red-lines.ts carries the same table and calls unit_and_subordinates the "strictly WIDER grant" of the pair.

Enforced

SharingRuleService.expandRecipient routes both kinds through the identical call. On origin/main at 098b629, packages/plugins/plugin-sharing/src/sharing-rule-service.ts:

if (rule.recipient_type === 'business_unit') {
 const dept = new BusinessUnitGraphService({ /* … */ });
 return dept.expandUsers(rule.recipient_id);
}
// …
if (rule.recipient_type === 'unit_and_subordinates') {
 const dept = new BusinessUnitGraphService({ /* … */ });
 return dept.expandUsers(rule.recipient_id);
}

BusinessUnitGraphService.expandUsers opens with const units = await this.descendants(businessUnitId) — a BFS over parent_business_unit_id — and then expands members over business_unit_id: { $in: units }. So business_unit walks the subtree. The two branches differ only in their comments.

Consequence: on a three-level tree, a business_unit rule anchored at a division silently grants to every department and office beneath it. The wider of the two declared kinds is not wider at all, which also makes the distinction the lint red-line draws between them unenforceable in practice.

Which way to fix is a decision, not a detail

Both directions are defensible and they are not equivalent:

1. Narrow the runtime to the declaration — business_unit expands members of that unit only. Matches the spec, the lint table and ADR-0057 D5's framing of unit_and_subordinates as the widening. Reduces access for any deployment that already authored business_unit rules and is relying, knowingly or not, on the subtree behaviour, so it needs a release note at minimum.
2. Change the declaration to match the runtime — and then business_unit and unit_and_subordinates are one kind with two names, which raises whether one should be retired under ADR-0049 enforce-or-remove.

Worth checking before either: whether any shipped example app or seeded rule authors business_unit, since that decides how much real pull direction 1's narrowing has to overcome.

Source

Found while implementing #7729 (lazy revocation on BU-tree changes, PR #7806). Out of scope there and deliberately not fixed in that PR: #7729 is a timing defect and its fix must cover whatever expandRecipient reads today, which is why that PR covers both kinds. Covering both stays correct whichever way this issue is decided.

[os-zhuang]

Findings-triage route B: regraded — finding → needs-user-decision, target:v17 stamped (security + domain:identity kept).

• Why decision box, not queue: the card's own bottom half is right — the fix direction is a semantics ruling. Direction 1 (narrow runtime to declaration) silently reduces access for any deployment that authored business_unit rules relying on today's subtree walk; direction 2 (widen declaration to runtime) makes the two recipient kinds one kind with two names and raises an ADR-0049 enforce-or-remove retirement. Neither is a lane call.
• Why target:v17 (binary test, class ② with a class-① edge): the shipped surface grants wider than the public contract declares — a sharing rule reaching a whole subtree its author scoped to one unit is an over-grant users hit today, and the spec + lint red-line table both assert the distinction the runtime does not enforce. Shipping the RC with a declared≠enforced security boundary is the release-note-apology class. The label rides the decision card: whichever direction is ruled, the ruling's execution sub-card inherits it (target follows the work).
• Premise verified as filed: measured on origin/main @ 098b629, still the tip this round; both expandRecipient branches call the identical expandUsers, whose first line BFSes descendants.
• Pre-decision measurement worth attaching (from the card): whether any shipped example app / seeded rule authors business_unit — decides direction 1's real-world blast radius.

Four-lens block (filing requirement for the decision box):
① Platform long-term coherence — direction 1 keeps two genuinely distinct vocabulary widths (shrinks a lie); direction 2 collapses to one kind and should then retire a name (ADR-0049); status quo keeps a lint red-line that is unenforceable.
② Measured business pull — subtree-vs-exact is a real org-modeling distinction (ADR-0057 D5 added the wide form deliberately); pull for exact-unit semantics should be confirmed via the shipped-rule scan the card names.
③ AI-agent error-resistance — direction 1 is strictly safer for AI-authored metadata: an agent choosing business_unit gets the narrow grant it asked for; today the narrow spelling silently over-grants, the worst failure shape for generated security rules.
④ Startup scope discipline — direction 2 is a capability removal (of the distinction) and cheaper to maintain; but keeping a declared key whose behaviour contradicts its declaration is the one option with permanent cost. Recommendation from triage: direction 1, with a release note; sequence after #7729's timing fix (PR #7806) lands, since that PR deliberately covers both kinds either way.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[huangyiirene]

Maintainer ruling — 2026-08-12

裁定:方向 1 —— 收窄运行时以匹配声明。 business_unit 收件人只展开该单位本身的成员;子树展开是 unit_and_subordinates 独有的语义(ADR-0057 D5)。

要点:

• spec、lint 红线表、ADR-0057 三处声明一致,错的是 expandRecipient 的实现;两个 kind 合并成一个才是需要避免的结局(那会再欠一次 ADR-0049 退役)。
• 实测(2026-08-12):树内已发货规则只授权 position 与 unit_and_subordinates(showcase sharing-rules.ts),没有任何在册规则使用 business_unit —— 树内迁移成本为零。
• 需要 changeset + release note:树外部署若依赖 business_unit 的子树行为,本次收窄会减少其可见范围,这是有意的 over-grant 修复。
• 修法:business_unit 分支不再走 descendants BFS,只展开 business_unit_id 等于该单位的成员;两个分支从「只差注释」变成真正两种宽度,并各自加 pin。

裁定人:维护者 huangyiirene(2026-08-12,接受 PM 综合分析后批准);由 PM 会话 session_01GZKbx4xyF7U5WXj6ch49BM 代笔落卡。转 pm:queue。

---

Generated by Claude Code