Skip to content

Commit 8f5b14b

Browse files
committed
docs(permissions): add the business-unit write as the fourth withdrawal moment
`sharing-rules.mdx` enumerated withdrawal as happening at exactly THREE moments, in a definitive table. This change adds a fourth — a `sys_business_unit` / `sys_business_unit_member` write — so an author reasoning about revocation timing from that table was reading an incomplete list, on the one topic the change is about. The new row states the asymmetry rather than flattening it: recipients the rule no longer reaches are revoked before the write returns, while the grant direction is queued and coalesced per rule. It also scopes itself to the two recipient kinds whose expansion reads the BU graph, so nobody infers that every rule now recomputes on every business-unit write. Deliberately unchanged, both checked rather than assumed: - The "always recoverable from the API surface" paragraph below the table. Its subject is an over-granting RULE recovered by switching it off or deleting it — the rule-write axis, which this change does not touch — so it stays exactly true, and its "not on the next time somebody happens to touch the record" phrasing is the same line the new row echoes. - The recipient table's `business_unit` row ("exactly that business unit (no subtree)"). That states the DECLARED contract, matching the spec enum and the ADR-0105 lint red-line. The runtime diverges by walking the subtree for both BU kinds, which is filed as #7807 — rewriting the doc to match would document an over-grant as intended behaviour. The new row is consistent with it either way: a unit-only expansion still reads `sys_business_unit` for its own active flag and `sys_business_unit_member` for its members, so it needs the recompute under both readings. `sharing-service.mdx` says nothing about recipient kinds or the BU graph; absent is not wrong, so it is left alone. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 060617d commit 8f5b14b

1 file changed

Lines changed: 2 additions & 1 deletion

File tree

‎content/docs/permissions/sharing-rules.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,12 +166,13 @@ unaffected.
166166
A sharing rule's grants are **materialized** — evaluating a rule writes real
167167
`sys_record_share` rows with `source: 'rule'` and `source_id` set to the rule.
168168
Because those rows outlive the evaluation that produced them, withdrawal has to
169-
be an explicit act, and it happens at **three** moments:
169+
be an explicit act, and it happens at **four** moments:
170170

171171
| When | What is reconciled |
172172
|:--|:--|
173173
| **The write that deactivates or edits the rule** | That rule's grants, immediately — deactivating with `active: false` (or `POST {basePath}/sharing/rules` with the same name) revokes them before the call returns |
174174
| **The next insert/update of a matching record** | That record's grants for every rule on the object — an inactive rule desires nothing, so its rows are revoked |
175+
| **A `sys_business_unit` or `sys_business_unit_member` write** | The grants of rules whose recipients read the BU graph — `unit_and_subordinates` and `business_unit`, and only those two. Recipients the rule no longer reaches are revoked **before the write returns**; the grant direction (a unit moved *into* a shared subtree) is queued and coalesced per rule (objectstack#7729) |
175176
| **Every boot** | All rules, plus a sweep of `source: 'rule'` rows whose `source_id` no longer resolves to any rule |
176177

177178
Deleting a rule withdraws its grants too, whether you delete it through

0 commit comments

Comments
 (0)