@bevel-software/platform-core-backend 0.9.1 → 0.11.0

package/src/modules/access/__tests__/synced-groups-committer.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { AccessControlService } from '../access-control.service.js';
+import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import { createSyncedGroupsCommitter } from '../synced-groups-committer.js';
+import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../workflow/workflow.errors.js';
+
+const KB = 'knowledge-base';
+const BOT: AuthUser = { id: 'bot-1', email: 'directory-sync@bevel.local', name: 'Directory Sync Bot' };
+
+describe('createSyncedGroupsCommitter.persist — post-commit push failures', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-sg-committer-'));
+    await fs.mkdir(path.join(root, KB), { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  function makeDeps(
+    workflowOverrides: Partial<
+      Record<'commitChanges' | 'releaseLock' | 'hasQueuedCommit' | 'hasUnpushedCommits', unknown>
+    > = {},
+  ) {
+    const workspaceService = {
+      getOrCreateForBranch: vi.fn(async () => ({})),
+      getWorkspacePath: vi.fn(async () => root),
+      readFile: vi.fn(async (_id: string, wsRel: string) =>
+        fs.readFile(path.join(root, wsRel), 'utf-8'),
+      ),
+    } as unknown as WorkspaceService;
+    const releaseLock = vi.fn(async () => undefined);
+    const releaseLockNoCommit = vi.fn(async () => undefined);
+    const releaseLockUntouched = vi.fn(async () => undefined);
+    const hasQueuedCommit = vi.fn(async () => false);
+    // Default: the branch still carries the landed-but-unpushed commit — the
+    // truthful answer everywhere except the worker-won-the-race scenario.
+    const hasUnpushedCommits = vi.fn(async () => true);
+    const workflowService = {
+      acquireLock: vi.fn(async () => ({ acquired: true, lock: {} })),
+      releaseLock,
+      releaseLockNoCommit,
+      releaseLockUntouched,
+      hasQueuedCommit,
+      hasUnpushedCommits,
+      commitChanges: vi.fn(async () => ({})),
+      ...workflowOverrides,
+    } as unknown as IWorkflowService;
+    const accessControl = { invalidate: vi.fn() } as unknown as AccessControlService;
+    const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+    const committer = createSyncedGroupsCommitter({
+      workspaceService,
+      workflowService,
+      accessControl,
+      eventBus,
+      kbDirName: KB,
+      bot: BOT,
+      defaultBranchOf: () => 'main',
+    });
+    return { committer, releaseLock, releaseLockNoCommit, hasQueuedCommit };
+  }
+
+  it('resolves (edit is saved) when only the PUSH failed after a landed commit', async () => {
+    // The regression this pins: a push failure after a successful local commit
+    // used to reject persist — the next sync then read the committed bytes,
+    // saw a no-op, and the update stayed unpublished forever. A landed commit
+    // is a saved edit; the pending-commits ladder retries the share.
+    const { committer, releaseLock, releaseLockNoCommit } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).resolves.toBeUndefined();
+    // The bytes landed on disk (write happened before the commit attempt)...
+    expect(await fs.readFile(path.join(root, KB, 'synced-groups.yaml'), 'utf-8')).toContain('a@x.io');
+    // ...and the lock released through the RETRY-ARMING path, never the discard.
+    expect(releaseLock).toHaveBeenCalled();
+    expect(releaseLockNoCommit).not.toHaveBeenCalled();
+  });
+
+  it('verifies the QUEUE when the arm probe answers lock-not-held, and resolves on a live row', async () => {
+    // In production the writeFiles push-retry release has usually SUCCEEDED —
+    // enqueue first, then drop the row — so the committer's verification
+    // release finds no lock to release. But lock-not-held alone proves
+    // nothing: a release that died BEFORE its enqueue (expired/stolen lock)
+    // leaves the exact same answer. Only the queue itself can prove the
+    // vehicle — persist must consult it and resolve when a row exists.
+    const releaseLock = vi
+      .fn()
+      // writeFiles' own push-retry release: succeeded (row enqueued + dropped).
+      .mockResolvedValueOnce(undefined)
+      // The committer's arm probe: nothing left to release.
+      .mockRejectedValue(
+        new WorkflowValidationError('Cannot release lock: not held by you.', {
+          kind: 'lock-not-held',
+        }),
+      );
+    const hasQueuedCommit = vi.fn(async () => true);
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+      hasQueuedCommit,
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).resolves.toBeUndefined();
+    expect(releaseLock).toHaveBeenCalledTimes(2);
+    expect(hasQueuedCommit).toHaveBeenCalledWith('main', 'main', `${KB}/synced-groups.yaml`);
+  });
+
+  it('REJECTS on lock-not-held with NO live queue row (release died before its enqueue)', async () => {
+    // The inference hole this pins: the ORIGINAL push-retry release hit an
+    // expired/stolen lock — releaseLock throws lock-not-held BEFORE its
+    // enqueue, writeFiles swallows it — and the committer's probe then gets
+    // the same lock-not-held. The old "lock gone ⇒ armed" inference reported
+    // success while NO pending row existed and the landed commit stayed
+    // unpublished forever. With the queue consulted directly, an empty queue
+    // must surface the original push failure.
+    const releaseLock = vi.fn().mockRejectedValue(
+      new WorkflowValidationError('Cannot release lock: not held by you.', {
+        kind: 'lock-not-held',
+      }),
+    );
+    const hasQueuedCommit = vi.fn(async () => false);
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+      hasQueuedCommit,
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+    expect(hasQueuedCommit).toHaveBeenCalled();
+  });
+
+  it('resolves when the worker DRAINED the row between release and probe (nothing left unpushed)', async () => {
+    // The race the unpushed check closes: the pending-commits worker grabbed
+    // the freshly enqueued row and pushed it in the window between writeFiles'
+    // release and the committer's probe. The queue answers "no live row" —
+    // truthfully — but rethrowing would report a directory-sync failure AFTER
+    // successful publication. A branch with nothing left unpushed proves the
+    // worker won; persist must resolve.
+    const releaseLock = vi
+      .fn()
+      .mockResolvedValueOnce(undefined) // writeFiles' release: enqueued + dropped
+      .mockRejectedValue(
+        new WorkflowValidationError('Cannot release lock: not held by you.', {
+          kind: 'lock-not-held',
+        }),
+      );
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+      hasQueuedCommit: vi.fn(async () => false),
+      hasUnpushedCommits: vi.fn(async () => false),
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).resolves.toBeUndefined();
+  });
+
+  it('REJECTS when the queue itself cannot be read (armed must be PROVEN, never assumed)', async () => {
+    const releaseLock = vi.fn().mockRejectedValue(
+      new WorkflowValidationError('Cannot release lock: not held by you.', {
+        kind: 'lock-not-held',
+      }),
+    );
+    const hasQueuedCommit = vi.fn(async () => {
+      throw new Error('db down');
+    });
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+      hasQueuedCommit,
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+  });
+
+  it('re-arms the retry itself when the push-retry release could not enqueue its row', async () => {
+    // writeFiles' release swallows an enqueue failure (warn + continue), so
+    // without the committer's own arm the landed commit would have NO retry
+    // vehicle: the next sync reads the committed bytes, sees a no-op, and the
+    // update stays unpublished forever. The committer must retry the release
+    // (which enqueues the pending-commit row) before reporting success.
+    const releaseLock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('pending_commits insert failed')) // writeFiles' release
+      .mockResolvedValueOnce(undefined); // the committer's re-arm succeeds
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).resolves.toBeUndefined();
+    expect(releaseLock).toHaveBeenCalledTimes(2);
+  });
+
+  it('REJECTS when no retry vehicle can be proven (both the release and the re-arm fail)', async () => {
+    // The one shape that may not report success: the commit landed, the push
+    // needs help, and no pending-commit row could be enqueued. Resolving here
+    // would tell the writer the update is published-or-retried when nothing
+    // will ever retry it — the failure signal must survive to the caller.
+    const releaseLock = vi.fn().mockRejectedValue(new Error('pending_commits insert failed'));
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new PushNeedsAgentResolutionError('main', '(batch)', 'non-fast-forward', 'rebase failed');
+      }),
+      releaseLock,
+    });
+    await expect(committer.persist('groups:\n  Team:\n    - a@x.io\n')).rejects.toBeInstanceOf(
+      PushNeedsAgentResolutionError,
+    );
+  });
+
+  it('still rejects on a genuine pre-commit failure (nothing landed)', async () => {
+    const { committer } = makeDeps({
+      commitChanges: vi.fn(async () => {
+        throw new Error('commit exploded');
+      }),
+    });
+    await expect(committer.persist('groups: {}\n')).rejects.toThrow('commit exploded');
+  });
+});

package/src/modules/access/__tests__/synced-groups-writer.test.ts

@@ -0,0 +1,249 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { parseGroupsFile } from '../group-files.js';
+import {
+  SyncedGroupsWriter,
+  renderSyncedGroupsYaml,
+  type SyncedGroupMember,
+  type SyncedGroupRecord,
+} from '../synced-groups-writer.js';
+
+function member(overrides: Partial<SyncedGroupMember> = {}): SyncedGroupMember {
+  return {
+    email: 'ada@x.io',
+    active: true,
+    ...overrides,
+  };
+}
+
+function group(
+  displayName: string,
+  members: SyncedGroupMember[],
+  externalId = `ext-${displayName}`,
+): SyncedGroupRecord {
+  return {
+    externalId,
+    displayName,
+    members,
+  };
+}
+
+describe('renderSyncedGroupsYaml', () => {
+  it('renders deterministically: sorted groups, sorted emails, stable bytes', () => {
+    const groups = [
+      group('Sales', [member({ email: 'zoe@x.io' }), member({ email: 'bo@x.io' })]),
+      group('Engineering', [member()]),
+    ];
+    const a = renderSyncedGroupsYaml(groups);
+    const b = renderSyncedGroupsYaml([...groups].reverse());
+    expect(a.text).toBe(b.text);
+    expect(a.groupCount).toBe(2);
+    // Engineering sorts before Sales; emails sort within a group.
+    const engineeringAt = a.text.indexOf('Engineering:');
+    const salesAt = a.text.indexOf('Sales:');
+    expect(engineeringAt).toBeGreaterThan(-1);
+    expect(engineeringAt).toBeLessThan(salesAt);
+    expect(a.text.indexOf('bo@x.io')).toBeLessThan(a.text.indexOf('zoe@x.io'));
+  });
+
+  it('round-trips through the resolver-side parser', () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Engineering', [member(), member({ email: 'bo@x.io' })]),
+      group('Empty Team', []),
+    ]);
+    const parsed = parseGroupsFile(rendered.text, 'synced-groups.yaml');
+    expect(parsed.ok).toBe(true);
+    if (parsed.ok) {
+      expect(parsed.warnings).toEqual([]);
+      expect([...parsed.groups.keys()].sort()).toEqual(['empty team', 'engineering']);
+      expect([...parsed.groups.get('engineering')!.emails].sort()).toEqual(['ada@x.io', 'bo@x.io']);
+      expect(parsed.groups.get('empty team')!.emails.size).toBe(0);
+    }
+  });
+
+  it('excludes inactive and email-less members, with a warning', () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Engineering', [
+        member(),
+        member({ email: 'gone@x.io', active: false }),
+        member({ email: null }),
+      ]),
+    ]);
+    expect(rendered.text).toContain('ada@x.io');
+    expect(rendered.text).not.toContain('gone@x.io');
+    expect(rendered.warnings.join(' ')).toContain('2 members not materialized');
+  });
+
+  it('refuses malformed emails from the directory (YAML corruption / injection)', () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Engineering', [
+        member(),
+        // A newline-bearing "email" would smuggle extra member lines into the file.
+        member({ email: 'evil@x.io\n    - attacker@evil.io' }),
+        member({ email: 'not an email' }),
+        // Passes the shape regex but would read back as a YAML comment.
+        member({ email: '#tag@x.io' }),
+        member({ email: '  ADA@X.IO  ' }), // canonicalized, deduped with ada@x.io
+      ]),
+    ]);
+    expect(rendered.text).toContain('ada@x.io');
+    expect(rendered.text).not.toContain('attacker@evil.io');
+    expect(rendered.text).not.toContain('not an email');
+    expect(rendered.text).not.toContain('#tag');
+    expect(rendered.text.match(/ada@x\.io/g)).toHaveLength(1);
+    expect(rendered.warnings.join(' ')).toContain('malformed email');
+  });
+
+  it("refuses the reserved 'group:' prefix as a member email (the read side skips it as a ref token)", () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Engineering', [member(), member({ email: 'group:lee@x.io' })]),
+    ]);
+    expect(rendered.text).toContain('ada@x.io');
+    expect(rendered.text).not.toContain('group:lee@x.io');
+    expect(rendered.warnings.join(' ')).toContain('malformed email');
+    // The emitted file round-trips warning-free through the parser.
+    const parsed = parseGroupsFile(rendered.text, 'synced-groups.yaml');
+    expect(parsed.ok && parsed.warnings).toEqual([]);
+  });
+
+  it('renders IdP names ESCAPED into warnings — control characters never reach the log verbatim', () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Evil\u001b[31mTeam\nFAKE LOG LINE', [member()]),
+    ]);
+    expect(rendered.groupCount).toBe(0);
+    expect(rendered.warnings).toHaveLength(1);
+    // The raw control chars must not appear; their JSON escapes must.
+    expect(rendered.warnings[0]).not.toContain('\n');
+    expect(rendered.warnings[0]).not.toContain('\u001b');
+    expect(rendered.warnings[0]).toContain('\\n');
+    expect(rendered.warnings[0]).toContain('\\u001b');
+  });
+
+  it('also escapes C1 controls and U+2028/U+2029 — the ranges JSON.stringify leaves raw', () => {
+    // JSON.stringify only escapes C0 (U+0000–U+001F): the one-byte CSI
+    // U+009B starts an ANSI sequence on its own, DEL (U+007F) is a control
+    // too, and U+2028/U+2029 are line breaks to JS consumers — all four
+    // would otherwise reach the log stream verbatim.
+    const raw = { csi: '\u009B', del: '\u007F', ls: '\u2028', ps: '\u2029' };
+    // C1/2028/2029 do NOT make a name unsafe (only C0 does), so the group
+    // is emitted — the name reaches the log through a MEMBER warning.
+    const rendered = renderSyncedGroupsYaml([
+      group(`Csi${raw.csi}31mTeam${raw.del}${raw.ls}${raw.ps}FAKE`, [member({ active: false })]),
+    ]);
+    expect(rendered.groupCount).toBe(1);
+    expect(rendered.warnings).toHaveLength(1);
+    const warning = rendered.warnings[0];
+    for (const c of Object.values(raw)) {
+      expect(warning).not.toContain(c);
+    }
+    expect(warning).toContain('\\u009b');
+    expect(warning).toContain('\\u007f');
+    expect(warning).toContain('\\u2028');
+    expect(warning).toContain('\\u2029');
+  });
+
+  it('full-key duplicate tie-break is collision-proof (JSON member key, not a delimiter join)', () => {
+    // Crafted so the OLD delimiter-joined keys collide: one malformed "email"
+    // containing the join delimiters serializes identically to two real
+    // members. A collision pushed the tie onto input order — the two renders
+    // below would then disagree on which duplicate wins first-wins dedup.
+    const a = group('Team', [member({ email: 'a@x.io:true,b@x.io' })], 'ext-1');
+    const b = group('Team', [member({ email: 'a@x.io' }), member({ email: 'b@x.io' })], 'ext-1');
+    const forward = renderSyncedGroupsYaml([a, b]);
+    const reversed = renderSyncedGroupsYaml([b, a]);
+    expect(forward.text).toBe(reversed.text);
+  });
+
+  it('sorts by code units, not locale (byte-stable across deployments)', () => {
+    // localeCompare in most locales collates 'é' before 'z'; code units put
+    // 'z' (0x7a) before 'é' (0xe9). Pin the code-unit order so the rendered
+    // bytes never depend on the process's ambient locale/ICU build.
+    const rendered = renderSyncedGroupsYaml([
+      group('équipe', [member()]),
+      group('z team', [member()]),
+    ]);
+    const z = rendered.text.indexOf('z team:');
+    const e = rendered.text.indexOf('équipe:');
+    expect(z).toBeGreaterThan(-1);
+    expect(z).toBeLessThan(e);
+  });
+
+  it('skips YAML-unsafe, reserved, and name-colliding groups (fail-closed)', () => {
+    const rendered = renderSyncedGroupsYaml([
+      group('Ops: West', [member()]),
+      group('everyone', [member()]),
+      group('Engineering', [member()], 'ext-a'),
+      group('engineering', [member({ email: 'bo@x.io' })], 'ext-b'),
+    ]);
+    expect(rendered.groupCount).toBe(1);
+    expect(rendered.text).not.toContain('Ops: West');
+    expect(rendered.text).not.toContain('everyone');
+    const joined = rendered.warnings.join('\n');
+    expect(joined).toContain('"Ops: West" skipped');
+    expect(joined).toContain('reserved');
+    expect(joined).toContain('collides');
+  });
+});
+
+describe('SyncedGroupsWriter', () => {
+  const GROUPS = [group('Engineering', [member()])];
+
+  function makeWriter(overrides: { current?: string | null; debounceMs?: number } = {}) {
+    const persisted: string[] = [];
+    const written: unknown[] = [];
+    let current = overrides.current ?? null;
+    const writer = new SyncedGroupsWriter({
+      source: { listGroups: async () => GROUPS },
+      readCurrent: async () => current,
+      persist: async (content) => {
+        persisted.push(content);
+        current = content;
+      },
+      onWritten: (result) => written.push(result),
+      debounceMs: overrides.debounceMs ?? 50,
+    });
+    return { writer, persisted, written };
+  }
+
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  it('writeNow persists changed content and fires onWritten', async () => {
+    const { writer, persisted, written } = makeWriter();
+    const result = await writer.writeNow();
+    expect(result.changed).toBe(true);
+    expect(result.groupCount).toBe(1);
+    expect(persisted).toHaveLength(1);
+    expect(persisted[0]).toContain('Engineering:');
+    expect(written).toHaveLength(1);
+  });
+
+  it('is a no-op (no commit, no events) when the content is unchanged', async () => {
+    const { writer, persisted, written } = makeWriter({
+      current: renderSyncedGroupsYaml(GROUPS).text,
+    });
+    const result = await writer.writeNow();
+    expect(result.changed).toBe(false);
+    expect(persisted).toHaveLength(0);
+    expect(written).toHaveLength(0);
+  });
+
+  it('debounces a burst of mutations into one write', async () => {
+    const { writer, persisted } = makeWriter({ debounceMs: 50 });
+    writer.notifyMutation();
+    await vi.advanceTimersByTimeAsync(30);
+    writer.notifyMutation(); // burst continues → timer re-arms
+    await vi.advanceTimersByTimeAsync(30);
+    expect(persisted).toHaveLength(0); // still inside the burst window
+    writer.notifyMutation();
+    await vi.advanceTimersByTimeAsync(60); // burst goes quiet → fire once
+    expect(persisted).toHaveLength(1);
+  });
+
+  it('dispose cancels a pending debounce', async () => {
+    const { writer, persisted } = makeWriter({ debounceMs: 50 });
+    writer.notifyMutation();
+    writer.dispose();
+    await vi.advanceTimersByTimeAsync(200);
+    expect(persisted).toHaveLength(0);
+  });
+});

package/src/modules/access/access-control.interface.ts

@@ -1,7 +1,8 @@
 /**
- * Access-control service interface. The implementation reads `roles.yaml`
- * and the `access.md` tree from the per-user `knowledge-base` clone and
- * resolves write permissions against them.
+ * Access-control service interface. The implementation reads `roles.yaml`,
+ * the active group file (`synced-groups.yaml` / `groups.yaml`), and the
+ * `access.md` tree from the workspace's `knowledge-base` clone and resolves
+ * the access verbs (read / write / download / owner) against them.
  *
  * All `relativePath` arguments are repo-relative POSIX paths inside the KB
  * repo (e.g. `Knowledge/Sales/Foo.md`, `roles.yaml`) — NOT workspace-relative
@@ -20,8 +21,8 @@
  *
  * Only a principal NAMED in a file (a direct user grant `Name <email>`, or a
  * group/role token) produces sources. A USER who merely RESOLVES to access via a
- * plugin they belong to, the built-in `everyone`, or admin-rescue is NOT a
- * per-target file entry and produces NO source (the plugin itself shows as its own
+ * group or role they belong to, the built-in `everyone`, or admin-rescue is NOT a
+ * per-target file entry and produces NO source (the group/role itself shows as its own
  * row instead).
  */
 export type GrantSource =
@@ -50,6 +51,24 @@ export type GrantPrincipal =
   | { kind: 'user'; email: string }
   | { kind: 'role'; role: string };
 
+/**
+ * One collective principal in a resolved eligible list, with WHAT it is: a
+ * ROLE (an app-defined capability) or a GROUP (a grant audience from the
+ * active group source). The resolver knows the kind from the merged principal
+ * index — a `role/<canonical>` alias hit is always the role; a bare token is
+ * whatever owns it under group-first precedence — and the share dialog needs
+ * it to badge each grantee row honestly ("Role" vs "Group") and to round-trip
+ * the row's principal with the right kind.
+ *
+ * Additive: `principals` rides NEXT TO the legacy `roles: string[]` (the same
+ * names, kind erased), which many name-only consumers (banners, owner
+ * contact lines, PR-routing messages) still read. It is optional in the
+ * interface so existing test doubles stay valid; the real service always
+ * returns it, and payload consumers fall back to `roles` (all treated as
+ * roles) when absent.
+ */
+export type ResolvedPrincipal = { name: string; kind: 'role' | 'group' };
+
 /**
  * Per-verb sources of a principal's access on a target. Only verbs the principal
  * actually holds (via a named file entry) appear; each maps to the closest-first
@@ -155,7 +174,11 @@ export interface IAccessControl {
   eligibleOwners(
     workspaceId: string,
     relativePath: string,
-  ): Promise<{ roles: string[]; users: { name: string; email: string }[] }>;
+  ): Promise<{
+    principals?: ResolvedPrincipal[];
+    roles: string[];
+    users: { name: string; email: string }[];
+  }>;
 
   /**
    * The set of principals (roles + direct users) with `write` on this path.
@@ -167,7 +190,11 @@ export interface IAccessControl {
   eligibleWriters(
     workspaceId: string,
     relativePath: string,
-  ): Promise<{ roles: string[]; users: { name: string; email: string }[] }>;
+  ): Promise<{
+    principals?: ResolvedPrincipal[];
+    roles: string[];
+    users: { name: string; email: string }[];
+  }>;
 
   /**
    * Answers the file viewer's "who can see this?" affordance. `restricted` is
@@ -181,7 +208,12 @@ export interface IAccessControl {
   eligibleReaders(
     workspaceId: string,
     relativePath: string,
-  ): Promise<{ restricted: boolean; roles: string[]; users: { name: string; email: string }[] }>;
+  ): Promise<{
+    restricted: boolean;
+    principals?: ResolvedPrincipal[];
+    roles: string[];
+    users: { name: string; email: string }[];
+  }>;
 
   /**
    * The set of principals (roles + direct users) with `download` on this path.
@@ -194,7 +226,11 @@ export interface IAccessControl {
   eligibleDownloaders(
     workspaceId: string,
     relativePath: string,
-  ): Promise<{ roles: string[]; users: { name: string; email: string }[] }>;
+  ): Promise<{
+    principals?: ResolvedPrincipal[];
+    roles: string[];
+    users: { name: string; email: string }[];
+  }>;
 
   /**
    * Finite expanded email set for configured users who could approve this path
@@ -237,12 +273,22 @@ export interface IAccessControl {
    *
    * Returns only the verbs the principal effectively holds; a verb with no
    * access is omitted. A principal with no access anywhere yields an empty map.
+   *
+   * `opts.tokenMatch: 'exact'` pins a ROLE-shaped principal to its literal
+   * token spelling: only the exact token (bare, or `role/<name>`) counts as
+   * the principal's own entry, regardless of group shadowing. The mutation
+   * layer uses this so a check runs against the SAME identity a pinned
+   * exact-token splice edited — e.g. verifying a GROUP deny whose group has
+   * vanished, where the default (alias-tolerant when unshadowed) matching
+   * would misattribute a same-named role's surviving `role/<name>` grant to
+   * the group. Omitted (or `'name'`) → the shadowing-derived default.
    */
   grantSources(
     workspaceId: string,
     kind: AccessTargetKind,
     relativePath: string,
     principal: GrantPrincipal,
+    opts?: { tokenMatch?: 'exact' | 'name' },
   ): Promise<GrantSources>;
 
   /**
@@ -264,34 +310,22 @@ export interface IAccessControl {
    */
   validateRolesYaml(text: string): { ok: true } | { ok: false; errors: string[] };
 
-  /**
-   * Find every folder-`access.md` reference to a role, by canonical name, in the
-   * cached model. ADVISORY ONLY — it powers the delete-confirmation "N rules
-   * will be ignored" warning, and it may UNDERCOUNT: `collectAccessFiles` only
-   * walks files literally named `access.md`, so a role granted in a node's OWN
-   * frontmatter is a real grant this scan misses. That is acceptable for a
-   * non-fatal warning. It must NOT be used to gate the rename rewrite — that
-   * needs the sound git-grep scan in `roles-admin.service.ts`, which also covers
-   * node frontmatter. An undercount there would silently orphan access.
-   */
-  referencesToRole(
-    workspaceId: string,
-    canonicalRole: string,
-  ): Promise<{ path: string; verb: string }[]>;
-
   /**
    * Enumerate the grantable principals known to the KB, for the share-dialog
-   * autocomplete. `plugins` are the built-in `everyone` role plus the declared
-   * `roles.yaml` role display names (`everyone` is surfaced so the UI can
-   * grant public read; the grant route gates it to the `read` verb only).
-   * `people` are every email named in `roles.yaml` (name defaults to the local
-   * part) unioned with every `Name <email>` grant in any `access.md` (named).
-   * The login-only `users` table is unioned in by the caller — this method
-   * covers the KB-canonical people the users table misses.
+   * autocomplete. `roles` are the built-in `everyone` role plus the declared
+   * `roles.yaml` role display names — ROLE principals only, never groups
+   * (`everyone` is surfaced so the UI can grant public read; the grant route
+   * gates it to the `read` verb only). `groups` are the ACTIVE group source's
+   * display names as merged into the resolver's cached model — served from
+   * that cache precisely so suggest/grant don't re-read the files per call.
+   * `people` are every email named in `roles.yaml` (name defaults to the
+   * local part) unioned with every `Name <email>` grant in any `access.md`
+   * (named). The login-only `users` table is unioned in by the caller — this
+   * method covers the KB-canonical people the users table misses.
    */
   kbPrincipals(
     workspaceId: string,
-  ): Promise<{ plugins: string[]; people: { name: string; email: string }[] }>;
+  ): Promise<{ roles: string[]; groups: string[]; people: { name: string; email: string }[] }>;
 
   /**
    * Reverse-lookup an email by its SHA-256 hash (per `hashEmail` semantics)