feat(plugin-sharing): backfill rule grants at boot (#2926 ③)

Sharing-rule grants are materialized by write hooks that deliberately skip
isSystem writes, so seed-loader records never got sys_record_share rows —
demo data with matching rules was broken on a fresh deploy until each record
was touched at runtime. Reconcile every active rule once per boot (idempotent,
best-effort per rule) right after the rule hooks bind.

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

Author: claude

.changeset/sharing-2926-boot-backfill.md

@@ -0,0 +1,5 @@
+---
+'@objectstack/plugin-sharing': patch
+---
+
+fix(plugin-sharing): reconcile every active sharing rule once at boot (#2926 ③). Rule grants are materialized by write hooks, which deliberately skip `isSystem` writes — so seed-loader records never produced `sys_record_share` rows and demo data shipping with matching sharing rules was broken out of the box until each record was touched at runtime. The new boot backfill runs after the rule hooks bind, is idempotent (diff-based reconcile), and is best-effort per rule so one broken rule cannot block startup.

packages/plugins/plugin-sharing/src/boot-backfill.test.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#2926 ③] Boot backfill of sharing-rule grants.
+ *
+ * Rule grants are materialized by write hooks, which deliberately skip
+ * `isSystem` writes (rule-hooks.ts) — so records created by the boot-time
+ * seed loader (always `isSystem`) never produced `sys_record_share` rows:
+ * demo data shipping with matching sharing rules was broken out of the box
+ * until an admin "touched" each record at runtime. `backfillRuleGrants`
+ * reconciles every active rule once per boot, idempotently.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { SharingService } from './sharing-service.js';
+import { SharingRuleService } from './sharing-rule-service.js';
+import { backfillRuleGrants } from './sharing-plugin.js';
+
+interface Row { [k: string]: any }
+
+const SYS = { isSystem: true } as any;
+
+function makeEngine() {
+  const tables: Record<string, Row[]> = {};
+  const ensure = (n: string) => (tables[n] ??= []);
+  function matches(row: Row, f: any): boolean {
+    if (!f || typeof f !== 'object') return true;
+    if (Array.isArray(f.$or)) return f.$or.some((x: any) => matches(row, x));
+    if (Array.isArray(f.$and)) return f.$and.every((x: any) => matches(row, x));
+    for (const [k, v] of Object.entries(f)) {
+      if (k === '$or' || k === '$and') continue;
+      const rv = row[k];
+      if (v != null && typeof v === 'object' && '$in' in (v as any)) {
+        if (!(v as any).$in.includes(rv)) return false;
+        continue;
+      }
+      if (v != null && typeof v === 'object' && '$gte' in (v as any)) {
+        if (!(rv >= (v as any).$gte)) return false;
+        continue;
+      }
+      if (rv !== v) return false;
+    }
+    return true;
+  }
+  return {
+    _tables: tables,
+    getSchema() { return undefined; },
+    async find(o: string, opts?: any) {
+      const f = opts?.filter ?? opts?.where;
+      return ensure(o).filter((r) => matches(r, f)).slice(0, opts?.limit ?? 10000);
+    },
+    async insert(o: string, data: any) { const row = { ...data }; ensure(o).push(row); return row; },
+    async update(o: string, idOrData: any, dataOrOpts?: any) {
+      const data = typeof idOrData === 'object' ? idOrData : dataOrOpts;
+      const id = typeof idOrData === 'object' ? idOrData.id : idOrData;
+      const t = ensure(o); const i = t.findIndex((r) => r.id === id);
+      if (i >= 0) t[i] = { ...t[i], ...data };
+      return t[i];
+    },
+    async delete(o: string, opts?: any) {
+      const t = ensure(o); const where = opts?.where ?? {};
+      for (let i = t.length - 1; i >= 0; i--) if (matches(t[i], where)) t.splice(i, 1);
+      return { ok: true };
+    },
+  };
+}
+
+describe('backfillRuleGrants (#2926 ③ — seed rows materialize at boot)', () => {
+  let engine: ReturnType<typeof makeEngine>;
+  let sharing: SharingService;
+  let rules: SharingRuleService;
+
+  beforeEach(async () => {
+    engine = makeEngine();
+    sharing = new SharingService({ engine: engine as any });
+    rules = new SharingRuleService({ engine: engine as any, sharing });
+    // Seed-loader analog: records written directly (isSystem path) — the
+    // write hooks never ran, so sys_record_share is empty.
+    engine._tables.showcase_inquiry = [
+      { id: 'inq_new', status: 'new', owner_id: 'priya' },
+      { id: 'inq_won', status: 'won', owner_id: 'priya' },
+    ];
+    await rules.defineRule({
+      name: 'new_inquiries_to_wes', label: 'New inquiries → wes', object: 'showcase_inquiry',
+      criteria: { status: 'new' },
+      recipientType: 'user', recipientId: 'wes', accessLevel: 'read',
+    }, SYS);
+  });
+
+  it('materializes grants for seed records that match an active rule', async () => {
+    expect(engine._tables.sys_record_share ?? []).toHaveLength(0);
+    const active = await rules.listRules({ activeOnly: true }, SYS);
+    const reconciled = await backfillRuleGrants(rules, active);
+    expect(reconciled).toBe(1);
+    const shares = engine._tables.sys_record_share ?? [];
+    expect(shares).toHaveLength(1);
+    expect(shares[0]).toMatchObject({ record_id: 'inq_new', recipient_id: 'wes' });
+  });
+
+  it('is idempotent across repeated boots (no duplicate grants)', async () => {
+    const active = await rules.listRules({ activeOnly: true }, SYS);
+    await backfillRuleGrants(rules, active);
+    await backfillRuleGrants(rules, active);
+    expect(engine._tables.sys_record_share ?? []).toHaveLength(1);
+  });
+
+  it('one broken rule does not block the others (best-effort per rule)', async () => {
+    await rules.defineRule({
+      name: 'zzz_broken', label: 'Broken', object: 'showcase_inquiry',
+      criteria: { status: 'new' },
+      recipientType: 'user', recipientId: 'someone', accessLevel: 'read',
+    }, SYS);
+    const active = await rules.listRules({ activeOnly: true }, SYS);
+    // Blow up evaluation of the broken rule only.
+    const realEvaluate = rules.evaluateRule.bind(rules);
+    vi.spyOn(rules, 'evaluateRule').mockImplementation(async (idOrName: string, context: any) => {
+      const rule = await rules.getRule(idOrName, context);
+      if (rule?.name === 'zzz_broken') throw new Error('boom');
+      return realEvaluate(idOrName, context);
+    });
+    const warn = vi.fn();
+    const reconciled = await backfillRuleGrants(rules, active, { warn });
+    expect(reconciled).toBe(1);
+    expect(warn).toHaveBeenCalledOnce();
+    // The healthy rule still materialized.
+    expect((engine._tables.sys_record_share ?? []).some((s) => s.record_id === 'inq_new')).toBe(true);
+  });
+});

packages/plugins/plugin-sharing/src/sharing-plugin.ts

@@ -36,6 +36,44 @@ export interface SharingPluginOptions {
   shareLinkBasePath?: string;
 }
 
+/**
+ * [#2926 ③] Boot backfill: rule grants are materialized by the write hooks,
+ * but seed rows are written with `isSystem` (which the hooks deliberately
+ * skip — see rule-hooks.ts), so a fresh deploy's seed data carried no
+ * `sys_record_share` rows until each record was touched at runtime.
+ * Reconcile every active rule once per boot: `evaluateRule` is idempotent
+ * (diff-based grant/update/revoke), so repeated boots are no-ops.
+ * Best-effort per rule — one broken rule must not block startup or its
+ * siblings. Returns the number of rules successfully reconciled.
+ */
+export async function backfillRuleGrants(
+  ruleService: SharingRuleService,
+  rules: Array<{ id?: string; name?: string }>,
+  logger?: { info?: (msg: string, meta?: any) => void; warn?: (msg: string, meta?: any) => void },
+): Promise<number> {
+  const start = Date.now();
+  let reconciled = 0;
+  for (const rule of rules) {
+    try {
+      await ruleService.evaluateRule((rule.id ?? rule.name) as string, { isSystem: true } as any);
+      reconciled += 1;
+    } catch (err: any) {
+      logger?.warn?.('SharingServicePlugin: boot rule backfill failed for rule', {
+        rule: rule.name ?? rule.id,
+        error: err?.message,
+      });
+    }
+  }
+  if (rules.length > 0) {
+    logger?.info?.('SharingServicePlugin: boot rule backfill done', {
+      rules: rules.length,
+      reconciled,
+      ms: Date.now() - start,
+    });
+  }
+  return reconciled;
+}
+
 /**
  * SharingServicePlugin — registers `sys_record_share`, the `sharing`
  * service, and the engine middleware that enforces
@@ -262,6 +300,8 @@ export class SharingServicePlugin implements Plugin {
             unbindAllRuleHooks(engine);
             bindRuleHooks(engine, this.ruleService, rules, ctx.logger as any);
             this.bindRuleRebindTriggers(engine, ctx);
+
+            await backfillRuleGrants(this.ruleService, rules, ctx.logger as any);
           } else {
             ctx.logger.warn('SharingServicePlugin: engine has no hook API — sharing rule auto-evaluation disabled');
           }