fix(plugin-sharing): the business_unit recipient expands exactly one unit, not the whole subtree (#7807)

[os-zhuang]

Fixes#7807

Implements the maintainer ruling of 2026-08-12 — direction 1: narrow the runtime to match the declaration.

The defect

The two business-unit recipient kinds were declared as two widths and enforced as one. SharingRuleService.expandRecipient routed both through the identical BusinessUnitGraphService.expandUsers call, whose first act is a BFS over parent_business_unit_id — so the two branches differed only in their comments.

A rule authored recipient_type: 'business_unit', which the spec (ShareRecipientType), the org-axis lint red-line table and ADR-0057 D5 all describe as "exactly one business unit's members (no subtree)", in fact reached that unit plus every descendant unit's members. On a three-level tree a division-anchored rule silently granted to every department and office beneath it — an over-grant, and one that left unit_and_subordinates, documented as the strictly wider grant of the pair, not wider at all.

The fix

business_unit now resolves through a new BusinessUnitGraphService.expandUnitMembers() — members whose business_unit_id equals the named unit, no descent. It keeps every other guarantee the subtree walk had: an inactive or out-of-tenant anchor contributes nobody, and an unreadable unit fails closed rather than granting.

unit_and_subordinates is unchanged and keeps the subtree walk. Both kinds survive; neither is merged into the other or retired, which the ruling names as the outcome to avoid. expandUsers() keeps its IBusinessUnitGraphService contract meaning (the contract declares it as the descendant expansion) for the bu: approver prefix and org rollups.

Two details worth review attention:

• The widths cache separately. Both are keyed by business-unit id, so one shared map would let whichever width ran first answer for the other — the over-grant returning through the cache door. Pinned by a test.
• packages/spec is untouched, per the ruling: the declaration was already right, the runtime was wrong.

Verification — predict-then-mutate ablation

The prediction was written down before either ablation ran.

Ablation A — revert only the narrowing (the defect shape). Predicted: exactly the narrow assertions go red, every wide one stays green. Measured: 8 failures, all narrow-width; the wide control and the whole business-unit-graph suite stayed green.

Ablation B — narrow BOTH branches (the failure mode this PR must not be). Predicted: the wide assertions go red, the narrow ones stay green. Measured: 8 failures, all wide-width, including four in the existing #7729 recompute suite, which turns out to be a second independent control for the wide width.

The symmetry is the point: it shows the wide pin is a real control rather than a tautology that passes because both branches happen to agree.

Tests

• packages/plugins/plugin-sharing — 490 passed (19 files), typecheck clean.
• packages/qa/dogfood — the BU-hierarchy e2e proof: 7 passed, including three new cases proving through the real REST stack that a business_unit rule reaches the anchor unit and a subordinate-unit member is denied. typecheck clean after building the closure.
• Gates re-derived for the final surface with scripts/pm/dispatch-gates.mjs and run green: check:nul-bytes, check:engine-double-contract (the new fake is pinned for both verbs, not debt), check:test-source-alias, check:docs-audit-scope, check:changeset-gate-self-tests, check:objectui-changeset, check-changeset-no-major.

Fixture dispositions

Three existing fixtures spelled the limb this PR removes, and each was judged individually rather than batch re-spelled:

• sharing-rule.test.ts — a test literally named "expands via the BU graph (BFS)" asserted the over-grant as if it were the contract. Replaced wholesale by the pair: the narrow kind expands one unit, and a new sibling case pins unit_and_subordinates expanding the subtree.
• showcase-bu-hierarchy-sharing.dogfood.test.ts — authored business_unit to demonstrate hierarchy widening, which is unit_and_subordinates' own semantics. Re-spelled (its two authz-conformance rows are preserved), plus the narrow half added on the same booted stack.
• bu-tree-recompute.test.ts — its business_unit case was already anchored at the unit the member belongs to directly, so it survives the narrowing unchanged; only its title, which asserted the now-false "they walk the same subtree resolver", was corrected.

Release note

A changeset is included and states plainly that this reduces visible rows for any out-of-tree deployment that authored business_unit rules relying on the subtree behaviour, with the migration path (switch the recipient to unit_and_subordinates if the subtree reach was what you wanted).

Re-measurement of the ruling's shelf-life claim

The ruling's "in-tree migration cost is zero" rested on a 2026-08-12 measurement that no in-tree rule authors business_unit. Re-verified on current origin/main and it still holds — the showcase app authors position and unit_and_subordinates, the CRM app authors position, and no seeded rule authors business_unit. The only in-tree business_unit authors were the two test fixtures dispositioned above.

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 12, 2026 3:18pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/plugin-sharing, @objectstack/dogfood.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/kernel/runtime-services/examples.mdx(via @objectstack/plugin-sharing)
• content/docs/kernel/runtime-services/sharing-service.mdx(via @objectstack/plugin-sharing)
• content/docs/kernel/services-checklist.mdx(via @objectstack/plugin-sharing)
• content/docs/permissions/authorization.mdx(via packages/plugins/plugin-sharing, packages/qa/dogfood)
• content/docs/permissions/delegated-administration.mdx(via packages/qa/dogfood)
• content/docs/permissions/permissions-matrix.mdx(via packages/plugins/plugin-sharing)
• content/docs/plugins/packages.mdx(via @objectstack/plugin-sharing)
• content/docs/protocol/objectql/security.mdx(via packages/plugins/plugin-sharing)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/plugin-sharing)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.