feat(lint): gate a sharing rule anchored where sharing has nothing to widen (#9698)

`validateSharingRuleEnforceability` gains its second arm. It already judged a
sharing rule's `condition` against the compiler that lowers it; it now judges
the rule's `object` against the verdict that decides whether the grant can
exist at all — `SharingService.inertGrantReason` (ADR-0111 D7), mirrored rather
than modelled, over the two of its arms that are decidable from authored
metadata before anything boots.

Two ids, because the two are not the same failure. Measured against a real
`SharingService`: a `public` OWD refuses the grant and leaves `buildReadFilter`
returning null, so the audience already reads everything and the declaration
advertises a restriction that does not exist; a `controlled_by_parent` anchor
refuses with a different reason and leaves the recipient seeing only what the
MASTER grants, so the author believes a grant exists that does not.

Blast radius measured through `objectstack build` before choosing `error`: 5
sharing rules exist in this repo, 3 fire, all in examples/app-crm, all on
`public_read_write` objects, all failing their boot backfill since they were
written. Removed under ADR-0049 enforce-or-remove, as #9237 did for the two
equivalent showcase rules. The showcase's remaining 2 stay silent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XqDQYVU5smx29ts9pAErja

Author: claude

.changeset/sharing-rule-inert-anchor-gate.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): a sharing rule anchored where sharing has nothing to widen is now an authoring-time error (#9698)
+
+`validateSharingRuleEnforceability` gains its second arm. It already judged a
+sharing rule's `condition` against the compiler that lowers it; it now judges
+the rule's `object` against the verdict that decides whether the grant can
+exist at all.
+
+Two new `error` ids, both decidable from authored metadata before anything
+boots, and both mirroring `SharingService.inertGrantReason` (ADR-0111 D7)
+rather than modelling it:
+
+- **`sharing-rule-object-not-shareable`** — the anchor object's effective
+  sharing model is `public` (an explicit `sharingModel: 'public_read_write'`,
+  or no `sharingModel` on a system object, which ADR-0090 D1 resolves to
+  public). Sharing only ever WIDENS an OWD baseline, so on the widest baseline
+  there is nothing to widen.
+- **`sharing-rule-object-controlled-by-parent`** — the anchor is a
+  master-detail detail, whose visibility is derived from its master
+  (ADR-0055). It gets its own id and its own fix-it ("share the master
+  record instead"), because `effectiveSharingModel` collapses it onto the same
+  `public` verdict while the correct repair is completely different.
+
+Both were previously accepted by `SharingRuleSchema`, accepted by `defineRule`,
+seeded into `sys_sharing_rule`, and only then refused — once per boot, as a
+WARN line inside the boot diagnostics block. That WARN is not a sufficient
+diagnostic, and the reason is measured rather than argued: a rule whose criteria
+match no seeded row never reaches `grant`, so it never throws and warns nothing
+while being exactly as dead. The WARN is a function of the DATA; the defect is a
+property of the DECLARATION.
+
+**Blast radius, measured through `objectstack build` before deciding the
+severity:** 5 sharing rules are declared in this repo. 3 fire, all of them in
+`examples/app-crm` — `share_high_value_opps_with_managers`,
+`share_active_leads_with_manager` and `share_won_deal_activities`, anchored on
+`crm_opportunity`, `crm_lead` and `crm_activity`, every one of them
+`sharingModel: 'public_read_write'`. They have been failing their boot backfill
+on every boot of that app since they were written, and they are removed here
+under ADR-0049 enforce-or-remove — the same call #9237 made for the two
+equivalent rules in `app-showcase`. The other 2 (app-showcase's, both on
+`private` objects) stay silent, which is the direction that had to be proven
+rather than hoped for.
+
+The CRM's smoke test used to assert that these rules existed and were of the
+enforced `criteria` type. Both assertions passed while all three rules enforced
+nothing, so the assertion is replaced by the property their greenness hid: no
+declared rule may be anchored where sharing has nothing to widen.
+
+Deliberately NOT judged, because they are not decidable from authored metadata:
+the `owner_id` arm (`owner_id` is injected by the schema registry, so asserting
+it would fail every object that correctly does not declare it by hand), the
+`bypassObjects` arm (plugin configuration, not stack metadata), and the
+federated phantom-anchor arm (a provenance test over that same injected column).

content/docs/permissions/index.mdx

@@ -25,22 +25,28 @@ is reserved (D3) — if you knew the v1 model, start at
 [Positions](/docs/permissions/positions).
 
 Access rules are metadata like everything else — this is a real sharing rule from
-the CRM example app:
+the showcase example app:
 
 ```typescript
-export const HighValueOpportunitySharingRule = defineSharingRule({
+export const KeyAccountQualifiedContactRule = defineSharingRule({
   type: 'criteria',
-  name: 'share_high_value_opps_with_managers',
-  label: 'High-Value Deals → Sales Managers',
-  description: 'Automatically share opportunities over $100,000 with all Sales Managers.',
-  object: 'crm_opportunity',
-  condition: 'record.amount > 100000',
-  accessLevel: 'edit',
-  sharedWith: { type: 'position', value: 'sales_manager' },
+  name: 'share_key_account_qualified_contacts_with_managers',
+  label: 'Key-Account Qualified Contacts → Managers',
+  description: 'Share qualified contacts at the key account with managers.',
+  object: 'showcase_contact',
+  condition: "record.stage == 'qualified' && record.company == 'Northwind'",
+  accessLevel: 'read',
+  sharedWith: { type: 'position', value: 'manager' },
   active: true,
 });
 ```
 
+Note the object it is anchored on. `showcase_contact` is OWD `private`, which is
+what makes this grant one a read gate actually consults — sharing only ever
+WIDENS a baseline, so a rule on an object that is already `public_read_write`
+grants nothing and is refused at boot. That is an authoring-time build error
+(`sharing-rule-object-not-shareable`), not a runtime surprise.
+
 Because AI agents act through the same permission-aware surface, these rules bound
 agent access exactly as they bound users ([Actions as Tools](/docs/ai/actions-as-tools)).
 

examples/app-crm/objectstack.config.ts

@@ -17,9 +17,6 @@ import {
   FinanceApproverPosition,
   SalesUserPermissionSet,
   GuestPortalProfile,
-  HighValueOpportunitySharingRule,
-  RepLeadSharingRule,
-  WonDealActivitySharingRule,
 } from './src/security/index.js';
 import { registerCrmPositionBindings } from './src/security/bind-position-sets.js';
 import { CrmSeedData } from './src/data/index.js';
@@ -102,11 +99,21 @@ export default defineStack({
   // Security
   positions: [SalesRepPosition, SalesManagerPosition, FinanceApproverPosition],
   permissions: [SalesUserPermissionSet, GuestPortalProfile],
-  sharingRules: [
-    HighValueOpportunitySharingRule,
-    RepLeadSharingRule,
-    WonDealActivitySharingRule,
-  ],
+  // No `sharingRules`. The three this app used to declare
+  // (`share_high_value_opps_with_managers`, `share_active_leads_with_manager`,
+  // `share_won_deal_activities`) were anchored on `crm_opportunity`,
+  // `crm_lead` and `crm_activity` — all three `sharingModel:
+  // 'public_read_write'`. Sharing only ever WIDENS an OWD baseline, so on the
+  // widest baseline there is nothing to widen: `assertNotInertGrant` refused
+  // every grant with SHARING_NOT_ENABLED and the boot backfill failed for each
+  // rule, on every boot, since they were written. They granted nothing and
+  // were removed under ADR-0049 enforce-or-remove (#9698), the same call
+  // #9237 made for app-showcase's two.
+  //
+  // ⛔ Do not re-add one on a public object — `sharing-rule-object-not-shareable`
+  // now fails the build, and its message states the two honest fixes. Giving
+  // this app a LIVE sharing demonstration means giving it a `private` object
+  // first; that is an access-matrix change (ADR-0090 D6 review), not a rider.
 
   // Seed data
   data: CrmSeedData,

examples/app-crm/src/security/index.ts

@@ -8,9 +8,3 @@ export {
   GuestPortalProfile,
 } from './sales-positions.js';
 
-export {
-  HighValueOpportunitySharingRule,
-  RepLeadSharingRule,
-  WonDealActivitySharingRule,
-} from './sharing-rules.js';
-

examples/app-crm/src/security/sharing-rules.ts

@@ -93,11 +93,34 @@ describe('app-crm minimal metadata bundle', () => {
     expect(stack.i18n!.supportedLocales).toContain('zh-CN');
   });
 
-  it('has criteria sharing rules (the enforced form — owner-type was retired)', () => {
-    const rules = stack.sharingRules ?? [];
-    expect(rules.length).toBeGreaterThanOrEqual(2);
-    // `type: 'owner'` no longer parses (never enforced; ADR-0078): every
-    // declared rule is the enforced criteria form.
+  // #9698 — this used to assert `rules.length >= 2` and `every(type ===
+  // 'criteria')`. Both passed, and neither was the property that mattered:
+  // all three declared rules were anchored on `public_read_write` objects, so
+  // `assertNotInertGrant` refused every grant and the boot backfill failed for
+  // each one, on every boot. A test can assert the enforced FORM and stay
+  // green while the rule enforces nothing. The three were removed (ADR-0049
+  // enforce-or-remove); what replaces the assertion is the property their
+  // greenness hid, so re-adding one on a public object goes red HERE as well
+  // as at `objectstack build`.
+  it('no declared sharing rule is anchored where sharing has nothing to widen (#9698)', () => {
+    const rules = (stack.sharingRules ?? []) as Array<{ name?: string; object?: string; type?: string }>;
+    const owdOf = new Map(
+      ((stack.objects ?? []) as Array<{ name?: string; sharingModel?: string }>)
+        .map((o) => [String(o.name), o.sharingModel]),
+    );
+    // `effectiveSharingModel` maps BOTH to 'public'; `controlled_by_parent`
+    // earns its own runtime refusal ("share the master record instead").
+    const INERT_OWD = new Set(['public_read_write', 'controlled_by_parent']);
+    const offenders = rules
+      .filter((r) => INERT_OWD.has(String(owdOf.get(String(r.object)))))
+      .map((r) => `${r.name} → ${r.object} (sharingModel '${owdOf.get(String(r.object))}')`);
+    expect(
+      offenders,
+      `sharing rule(s) whose grant no gate would consult — the boot backfill refuses these with `
+        + `SHARING_NOT_ENABLED: ${offenders.join(', ')}`,
+    ).toEqual([]);
+    // `type: 'owner'` no longer parses (never enforced; ADR-0078): whatever is
+    // declared is the enforced criteria form.
     expect(rules.every((r) => r.type === 'criteria')).toBe(true);
   });
 

examples/app-crm/test/smoke.test.ts

@@ -1306,16 +1306,26 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
     surfaceReason: RUNTIME_NEEDS_FULL_SNAPSHOT,
     run: (stack) => validateOrgAxisRedLines(stack),
   },
-  // #4698 — the "declared but never read" gate, for the one surface where the
-  // predicate is EXACT rather than inferred. A sharing rule's `condition` has a
-  // single runtime consumer (`bootstrapDeclaredSharingRules`) whose only use of
-  // the key is `compileCelToFilter(condition, { variables: {} })`; a condition
-  // that does not lower means the rule is SKIPPED at boot, so the grant is
-  // declared and does not exist. The lint calls that same compiler, from the
-  // same package, with the same options — the verdict cannot drift from the
-  // consumer's. Gating for the ADR-0078 reason `SharingRuleSchema`'s own
-  // docblock states: the whole authorable surface is enforced, and this was the
-  // one field where that sentence was not yet true.
+  // #4698 / #9698 — the "declared but never read" gate, for the two fields of a
+  // sharing rule where the predicate is EXACT rather than inferred.
+  //
+  //  - `condition` has a single runtime consumer
+  //    (`bootstrapDeclaredSharingRules`) whose only use of the key is
+  //    `compileCelToFilter(condition, { variables: {} })`; a condition that
+  //    does not lower means the rule is SKIPPED at boot.
+  //  - `object` decides whether the grant is refused outright: reconcile hands
+  //    each row to `SharingService.grant`, whose ADR-0111 D7 pre-flight THROWS
+  //    `SHARING_NOT_ENABLED` when the anchor's effective sharing model is
+  //    `public` or it is a `controlled_by_parent` detail. Both are decidable
+  //    from authored metadata; the other arms of that verdict (`owner_id`, the
+  //    bypass set, federated anchors) are not, and are excluded by name.
+  //
+  // Either way the grant is declared and does not exist. The lint calls the
+  // same compiler and mirrors the same verdict function, from the same inputs
+  // — the verdict cannot drift from the consumers'. Gating for the ADR-0078
+  // reason `SharingRuleSchema`'s own docblock states: the whole authorable
+  // surface is enforced, and these were the fields where that sentence was not
+  // yet true.
   {
     name: 'validateSharingRuleEnforceability',
     tier: 'gating',
@@ -1324,11 +1334,16 @@ export const AUTHORING_RULES: readonly AuthoringRule[] = [
     source: 'packages/lint/src/validate-sharing-rule-enforceability.ts',
     surfaces: CLI_ONLY,
     surfaceReason:
-      'P2 (#4463): a sharing rule is not a `flow`, and P1 gates `flow` alone. The rule itself is '
-      + 'snapshot-safe — it reads ONLY `stack.sharingRules[].condition` and needs no other collection — '
-      + 'so widening it here is a `runtimeTypes: [\'sharing_rule\']` edit once the gate accepts that type, '
-      + 'not new wiring. Recorded as pending rather than done, because a rule that has never run at a '
-      + 'door should not claim it.',
+      'P2 (#4463): a sharing rule is not a `flow`, and P1 gates `flow` alone. This entry used to add '
+      + 'that the rule reads ONLY `stack.sharingRules[].condition` and needs no other collection, so '
+      + 'crossing was a lone `runtimeTypes` edit. #9698 FALSIFIED that: the anchor arm resolves '
+      + '`sharingRules[].object` against `stack.objects` to read the anchor\'s OWD, so the rule is now '
+      + 'cross-collection. `objects` IS carried by the per-write snapshot (`CONTEXT_STACK_KEYS`, #8309), '
+      + 'so the remaining gap is unchanged in SHAPE — the gate must accept a `sharing_rule` type and the '
+      + 'snapshot must carry `sharingRules`, which it does not — but it is now TWO collections, not one. '
+      + 'Crossing with `sharingRules` uncarried would enforce this id for zero of its inputs while the '
+      + 'entry claimed the door (#7220). Recorded as pending rather than done, because a rule that has '
+      + 'never run at a door should not claim it.',
     run: (stack) => validateSharingRuleEnforceability(stack),
   },
   // #4983 — the sibling surface of the rule above, and ADR-0056 D4's gate,

packages/lint/src/authoring-rules.ts

@@ -261,14 +261,18 @@ export {
 } from './validate-org-axis-red-lines.js';
 export type { OrgAxisFinding, OrgAxisSeverity } from './validate-org-axis-red-lines.js';
 
-// #4698 — "a key that nothing reads should not validate clean", for the one
-// surface where "is it read?" is decidable: a sharing rule's `condition` is
-// read ONLY through `compileCelToFilter`, so the lint calls that same compiler
-// rather than modelling the consumer.
+// #4698 / #9698 — "a key that nothing reads should not validate clean", for the
+// two fields of a sharing rule where "is it read?" is decidable. The
+// `condition` is read ONLY through `compileCelToFilter`, and the `object`
+// decides whether `assertNotInertGrant` would refuse the grant outright — so
+// the lint calls the same compiler and mirrors the same verdict function,
+// rather than modelling either consumer.
 export {
   validateSharingRuleEnforceability,
   SHARING_RULE_UNLOWERABLE_CONDITION,
   SHARING_RULE_RUNTIME_VARIABLE_CONDITION,
+  SHARING_RULE_OBJECT_NOT_SHAREABLE,
+  SHARING_RULE_OBJECT_CONTROLLED_BY_PARENT,
 } from './validate-sharing-rule-enforceability.js';
 export type {
   SharingRuleEnforceabilityFinding,