@@ -0,0 +1,13 @@
+---
+'@objectstack/plugin-sharing': patch
+---
+
+fix(plugin-sharing): position- and team-recipient sharing rules are re-evaluated for the affected user when the membership behind the recipient changes
+
+Clause-②: no
+
+A sharing rule's grants are materialised per user. When a position assignment (`sys_user_position`) or a team membership (`sys_team_member`) is inserted, deleted, or updated in a column the recipient expansion reads (the user, the position or team, the organization, the validity window), every sharing rule whose recipient the row names is now re-evaluated for the user the row names, before the write returns. A new holder gains the rule's grants and a former holder loses them. Other users' grants, and rules naming other recipients, are not touched.
+
+The re-evaluation is scoped to that one user and to the rules naming the recipient: an indexed holder check, that user's grants of the rule, and the rule's criteria read only when the rule reaches the user. A bulk assignment import therefore costs one user-scoped pass per row and never a whole-rule pass. An organization's rule is re-evaluated only for rows of its own organization; a platform-global rule for every row.
+
+`SharingRuleService` gains `reconcileRuleForUser(rule, userId)`, the user-scoped pass these hooks run. No spec key, endpoint or configuration changes.
@@ -173,7 +173,7 @@ Sharing rules extend access beyond ownership and the depth axis. The declarative
 </Callout>
 
 <Callout type="info">
-**Beyond declarative rules:** Two other sharing mechanisms exist but are **not** `SharingRule` types. **Manual sharing** is a runtime grant — `sys_record_share` rows created with `source: 'manual'` (see `packages/plugins/plugin-sharing/src/sharing-service.ts`). **Matrix / territory-shaped access** is served today by multi-position assignment anchored on business units, plus pre-resolved membership sets: a registered `rls-membership-resolver` (ADR-0105 D11) stages e.g. `territory_account_ids` into `ExecutionContext.rlsMembership`, and a policy references it as `account_id IN (current_user.territory_account_ids)`. The aspirational `TerritorySchema` was removed in ADR-0105 D11 — it had no runtime object, stack field or resolver; a generalized dimension-security module will arrive with its own ADR. Criteria rules are re-evaluated on record insert/update via internal sharing rule hooks, on every write to the rule itself, and once per boot — so deactivating or deleting a rule withdraws the grants it materialized (see [Sharing Rules](/docs/permissions/sharing-rules#switching-a-rule-off-withdraws-the-access-it-granted)).
+**Beyond declarative rules:** Two other sharing mechanisms exist but are **not** `SharingRule` types. **Manual sharing** is a runtime grant — `sys_record_share` rows created with `source: 'manual'` (see `packages/plugins/plugin-sharing/src/sharing-service.ts`). **Matrix / territory-shaped access** is served today by multi-position assignment anchored on business units, plus pre-resolved membership sets: a registered `rls-membership-resolver` (ADR-0105 D11) stages e.g. `territory_account_ids` into `ExecutionContext.rlsMembership`, and a policy references it as `account_id IN (current_user.territory_account_ids)`. The aspirational `TerritorySchema` was removed in ADR-0105 D11 — it had no runtime object, stack field or resolver; a generalized dimension-security module will arrive with its own ADR. Criteria rules are re-evaluated on record insert/update via internal sharing rule hooks, on every write to the rule itself, when the business-unit graph or the position or team membership behind a rule's recipient changes, and once per boot — so deactivating or deleting a rule withdraws the grants it materialized (see [Sharing Rules](/docs/permissions/sharing-rules#switching-a-rule-off-withdraws-the-access-it-granted)).
 </Callout>
 
 ### Configuration Example
 
@@ -213,13 +213,14 @@ default organization is bootstrapped (cloud ADR-0081 D1).
 A sharing rule's grants are **materialized** — evaluating a rule writes real
 `sys_record_share` rows with `source: 'rule'` and `source_id` set to the rule.
 Because those rows outlive the evaluation that produced them, withdrawal has to
-be an explicit act, and it happens at **four** moments:
+be an explicit act, and it happens at **five** moments:
 
 | When | What is reconciled |
 |:--|:--|
 | **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 |
 | **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 |
 | **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) |
+| **A `sys_user_position` or `sys_team_member` write** | The grants of rules whose recipient is the position or team the row names, re-evaluated for the user the row names — inserts, deletes, and updates to the user, the recipient, the organization or the validity window. A new holder gains the rule's grants and a former holder loses them **before the write returns**; other users' grants and rules naming other recipients are not touched |
 | **Every boot** | All rules, plus a sweep of `source: 'rule'` rows whose `source_id` no longer resolves to any rule |
 
 Deleting a rule withdraws its grants too, whether you delete it through
 
@@ -51,7 +51,9 @@
  * Everything else is deliberately NOT recomputed. That exclusion is a
  * requirement, not an optimisation: a fix that recomputed every rule on every
  * BU write would close the security hole and replace it with a load problem —
- * see {@link BU_TREE_RECIPIENT_TYPES}.
+ * see {@link BU_TREE_RECIPIENT_TYPES}. The `position` and `team` kinds are
+ * recomputed by writes to THEIR membership tables instead, per affected user —
+ * `recipient-membership-recompute.ts`.
  *
  * ## The design: synchronous revoke, asynchronous re-grant
  *
 
@@ -96,3 +96,64 @@ describe('PositionGraphService (ADR-0090 D3 — flat expansion)', () => {
     expect(calls).toBe(before); // second hit served from cache
   });
 });
+
+describe('PositionGraphService.holdsPosition — the user-scoped twin of the expansion', () => {
+  const past = '2000-01-01T00:00:00Z';
+  const future = '2999-01-01T00:00:00Z';
+  const ASSIGN = [
+    { position: 'rep', user_id: 'u_a', organization_id: 'org_a' },
+    { position: 'rep', user_id: 'u_b', organization_id: 'org_b' },
+    { position: 'rep', user_id: 'u_global', organization_id: null },
+    { position: 'rep', user_id: 'u_expired', organization_id: 'org_a', valid_until: past },
+    { position: 'rep', user_id: 'u_pending', organization_id: 'org_a', valid_from: future },
+    { position: 'rep', user_id: 'u_mixed', organization_id: 'org_a', valid_until: past },
+    { position: 'rep', user_id: 'u_mixed', organization_id: 'org_a', valid_from: past, valid_until: future },
+    { position: 'mgr', user_id: 'u_a', organization_id: 'org_a' },
+  ];
+  const MEMBER = [
+    { role: 'rep', user_id: 'u_role_a', organization_id: 'org_a' },
+    { role: 'rep', user_id: 'u_role_b', organization_id: 'org_b' },
+  ];
+  /** Honours every predicate key both reads send: position / role, organization_id, user_id. */
+  const engine = {
+    async find(object: string, options: any) {
+      const f = options?.filter ?? options?.where ?? {};
+      const rows: any[] = object === 'sys_user_position' ? ASSIGN : object === 'sys_member' ? MEMBER : [];
+      const matches = (row: any, where: any): boolean => {
+        for (const [k, v] of Object.entries(where)) {
+          if (k.startsWith('$')) throw new Error('test double: unsupported logical operator ' + k);
+          if (row[k] !== v) return false;
+        }
+        return true;
+      };
+      return rows.filter((r) => matches(r, f)).slice(0, options?.limit ?? rows.length);
+    },
+  } as any;
+  const USERS = ['u_a', 'u_b', 'u_global', 'u_expired', 'u_pending', 'u_mixed', 'u_role_a', 'u_role_b', 'u_none'];
+
+  it('answers exactly expandPositionUsers(...).includes(user) for every user, position and organization scope', async () => {
+    const verdicts = { holds: 0, not: 0 };
+    for (const org of [undefined, 'org_a', 'org_b']) {
+      for (const position of ['rep', 'mgr', 'nope']) {
+        const expanded = await new PositionGraphService({ engine, organizationId: org ?? null }).expandPositionUsers(position, org);
+        for (const user of USERS) {
+          const g = new PositionGraphService({ engine, organizationId: org ?? null });
+          const holds = await g.holdsPosition(user, position, org);
+          expect({ org, position, user, holds }).toEqual({ org, position, user, holds: expanded.includes(user) });
+          verdicts[holds ? 'holds' : 'not'] += 1;
+        }
+      }
+    }
+    // Both answers occur, so the matrix cannot pass by answering one of them.
+    expect(verdicts.holds).toBeGreaterThan(5);
+    expect(verdicts.not).toBeGreaterThan(5);
+  });
+
+  it('reads one user, never the position\'s whole holder list', async () => {
+    const seen: any[] = [];
+    const spy = { async find(object: string, options: any) { seen.push({ object, f: options?.filter ?? options?.where }); return engine.find(object, options); } } as any;
+    await new PositionGraphService({ engine: spy, organizationId: 'org_a' }).holdsPosition('u_role_a', 'rep', 'org_a');
+    expect(seen.map((s) => s.object)).toEqual(['sys_user_position', 'sys_member']);
+    expect(seen.every((s) => s.f.user_id === 'u_role_a')).toBe(true);
+  });
+});
@@ -3,10 +3,26 @@
 import { isGrantActive } from '@objectstack/core';
 
 import type { SharingEngine } from './sharing-service.js';
-import { TeamGraphService } from './team-graph.js';
+import { TeamGraphService, holdsRole } from './team-graph.js';
 
 const SYSTEM_CTX = { isSystem: true, positions: [], permissions: [] } as const;
 
+/**
+ * The `sys_user_position` predicate "assignments of `positionName`", scoped to
+ * `scopeOrg` when one is given — ONE spelling for the rule-wide expansion
+ * ({@link PositionGraphService.expandPositionUsers}) and the user-scoped check
+ * ({@link PositionGraphService.holdsPosition}), so the two can never disagree
+ * about which assignment rows count.
+ */
+function positionAssignmentPredicate(positionName: string, scopeOrg: string | null | undefined): Record<string, unknown> {
+  const filter: Record<string, unknown> = { position: positionName };
+  if (scopeOrg) filter.organization_id = scopeOrg;
+  return filter;
+}
+
+/** The columns both reads project: the holder and the ADR-0091 D2 validity window. */
+const ASSIGNMENT_FIELDS = ['user_id', 'valid_from', 'valid_until'];
+
 type PositionCache = {
   expand?: Map<string, string[]>;
 };
@@ -73,16 +89,14 @@ export class PositionGraphService {
     const users = new Set<string>();
 
     // 1) Platform assignment table (source of truth).
-    const filter: Record<string, unknown> = { position: positionName };
     const scopeOrg = organizationId ?? this.organizationId;
-    if (scopeOrg) filter.organization_id = scopeOrg;
     try {
       // valid_from / valid_until ride the projection so the ADR-0091 D2
       // validity filter below sees them — expired holders stop receiving
       // position-recipient shares at resolution time, fail-closed.
       const rows = await this.engine.find('sys_user_position', {
-        filter,
-        fields: ['user_id', 'valid_from', 'valid_until'],
+        filter: positionAssignmentPredicate(positionName, scopeOrg),
+        fields: ASSIGNMENT_FIELDS,
         limit: 10000,
         context: SYSTEM_CTX,
       });
@@ -105,4 +119,42 @@ export class PositionGraphService {
     this.cache.expand!.set(key, result);
     return result;
   }
+
+  /**
+   * Does `userId` hold `positionName`? The user-scoped twin of
+   * {@link expandPositionUsers}: the same two sources, the same organization
+   * scope and the same ADR-0091 D2 validity filter, each narrowed to one user,
+   * so the answer is `expandPositionUsers(positionName, organizationId)
+   * .includes(userId)` — pinned in `position-graph.test.ts` — read in two
+   * indexed lookups instead of the position's whole holder list.
+   *
+   * Exists for the recipient-membership recompute
+   * (`recipient-membership-recompute.ts`), which re-evaluates a position rule
+   * for the ONE user whose assignment was written. That runs on the write path,
+   * once per written row, so a full expansion there would make a bulk
+   * assignment import quadratic in the position's holder count.
+   *
+   * Uncached on purpose: the answer is wanted right after a write that may
+   * have changed it. A failed assignment read falls through to the transition
+   * source, as the expansion's does.
+   */
+  async holdsPosition(userId: string, positionName: string, organizationId?: string): Promise<boolean> {
+    if (!userId || !positionName) return false;
+    const scopeOrg = organizationId ?? this.organizationId;
+    try {
+      const rows = await this.engine.find('sys_user_position', {
+        filter: { ...positionAssignmentPredicate(positionName, scopeOrg), user_id: userId },
+        fields: ASSIGNMENT_FIELDS,
+        limit: 1000,
+        context: SYSTEM_CTX,
+      });
+      const nowMs = Date.now();
+      for (const r of (rows ?? []) as any[]) {
+        if (String(r.user_id ?? '') === userId && isGrantActive(r, nowMs)) return true;
+      }
+    } catch {
+      /* table may not exist on minimal stacks — the transition source below still applies */
+    }
+    return holdsRole(this.engine, positionName, userId, scopeOrg);
+  }
 }
Original file line number	Diff line number	Diff line change
`@@ -51,7 +51,9 @@`
`51`	`51`	`* Everything else is deliberately NOT recomputed. That exclusion is a`
`52`	`52`	`* requirement, not an optimisation: a fix that recomputed every rule on every`
`53`	`53`	`* BU write would close the security hole and replace it with a load problem —`
`54`		`- * see {@link BU_TREE_RECIPIENT_TYPES}.`
	`54`	+ * see {@link BU_TREE_RECIPIENT_TYPES}. The `position` and `team` kinds are
	`55`	`+ * recomputed by writes to THEIR membership tables instead, per affected user —`
	`56`	+ * `recipient-membership-recompute.ts`.
`55`	`57`	`*`
`56`	`58`	`* ## The design: synchronous revoke, asynchronous re-grant`
`57`	`59`	`*`