@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/access/__tests__/reference-scan.test.ts

@@ -8,7 +8,18 @@ import {
   KbReferenceScanner,
   findRoleRefsInText,
   rewriteRoleTokensInText,
+  UNSHOWN_REFERENCE_REFUSAL,
+  translateRewriteWriteRefusal,
+  type PathVisibility,
 } from '../reference-scan.js';
+import type { ITreeWalker } from '../../../shared/fs.contract.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import { AccessDeniedError } from '../../access-model/access-errors.js';
+
+/** A renaming person who may read every path. */
+const ALL_VISIBLE: PathVisibility = async (paths) => new Map(paths.map((p) => [p, true]));
+/** A renaming person who may read none of them. */
+const NONE_VISIBLE: PathVisibility = async (paths) => new Map(paths.map((p) => [p, false]));
 
 /**
  * Unit tests for the shared reference scanner's parse rules (comments,
@@ -158,6 +169,31 @@ async function write(repo: string, rel: string, contents: string): Promise<void>
   await fs.writeFile(abs, contents);
 }
 
+describe('translateRewriteWriteRefusal — the lock scope still sees what a failed restore left', () => {
+  function refusal(unrestored?: Set<string>): AccessDeniedError {
+    const err = new AccessDeniedError({ path: 'Hidden/secret.md', eligibleRoles: [], eligibleUsers: [] });
+    if (unrestored) (err as { unrestoredPaths?: Set<string> }).unrestoredPaths = unrestored;
+    return err;
+  }
+
+  it('a refusal on a hidden file carries unrestoredPaths onto the generic refusal', async () => {
+    const unrestored = new Set(['KnowledgeBase/Hidden/secret.md']);
+    const out = await translateRewriteWriteRefusal(refusal(unrestored), NONE_VISIBLE, (m) => new Error(m));
+    expect((out as Error).message).toBe(UNSHOWN_REFERENCE_REFUSAL);
+    expect((out as { unrestoredPaths?: Set<string> }).unrestoredPaths).toBe(unrestored);
+  });
+
+  it('a refusal with every file restored adds no unrestoredPaths', async () => {
+    const out = await translateRewriteWriteRefusal(refusal(), NONE_VISIBLE, (m) => new Error(m));
+    expect((out as { unrestoredPaths?: Set<string> }).unrestoredPaths).toBeUndefined();
+  });
+
+  it('a refusal on a readable file comes back as it was', async () => {
+    const err = refusal(new Set(['x']));
+    expect(await translateRewriteWriteRefusal(err, ALL_VISIBLE, (m) => new Error(m))).toBe(err);
+  });
+});
+
 describe('KbReferenceScanner — .tool frontmatter is scanned and rewritten like .md', () => {
   it('finds a .tool frontmatter grant and a rename rewrites it (body untouched)', async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-'));
@@ -166,13 +202,13 @@ describe('KbReferenceScanner — .tool frontmatter is scanned and rewritten like
       const toolBody = 'name: crm\ntype: mcp\n# not frontmatter below\n';
       await write(repo, 'Plugins/GTM/crm.tool', `---\nread:\n  - GTM Team\n---\n${toolBody}`);
       await write(repo, 'Plugins/GTM/notes.md', '---\nowner: GTM Team\n---\n# notes\n');
-      const scanner = new KbReferenceScanner(stubWorkspace(root), KB);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
 
       const byToken = await scanner.scan('ws-1');
       const hits = (byToken.get('gtm team') ?? []).map((h) => h.path).sort();
       expect(hits).toEqual(['Plugins/GTM/crm.tool', 'Plugins/GTM/notes.md']);
 
-      const writes = await scanner.rewriteReferences('ws-1', 'gtm team', 'Go To Market', (m) => new Error(m));
+      const writes = await scanner.rewriteReferences('ws-1', 'gtm team', 'Go To Market', (m) => new Error(m), ALL_VISIBLE);
       const toolWrite = writes.find((w) => w.repoRelativePath === 'Plugins/GTM/crm.tool')!;
       expect(toolWrite.content).toContain('  - Go To Market');
       // The .tool body below the frontmatter is byte-for-byte intact.
@@ -184,6 +220,321 @@ describe('KbReferenceScanner — .tool frontmatter is scanned and rewritten like
   });
 });
 
+describe('KbReferenceScanner — candidates are the resolver\'s walk, not the explorer\'s', () => {
+  it('scans and rewrites an access.md that .bevelignore hides from the explorer', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-ignore-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, '.bevelignore', 'Archive/\n');
+      // The resolver walks past .bevelignore, so this rule is ENFORCED.
+      await write(repo, 'Archive/access.md', '---\nwrite:\n  - Admin\n---\n');
+      // The explorer's listing, as the real one answers: what .bevelignore
+      // hides is not in it. A scan built on it would miss Archive/access.md.
+      const base = stubWorkspace(root);
+      const ws = {
+        ...base,
+        listFiles: async (id: string) => {
+          const tree = await base.listFiles(id);
+          const prune = (n: FileTreeEntry): FileTreeEntry => ({
+            ...n,
+            children: n.children
+              ?.filter((c) => c.relativePath !== `${KB}/Archive`)
+              .map(prune),
+          });
+          return prune(tree);
+        },
+      } as unknown as IWorkspaceService;
+      const scanner = new KbReferenceScanner(ws, new NodeFs(), KB);
+
+      expect((await scanner.scan('ws-1')).get('admin')).toEqual([{ path: 'Archive/access.md', verb: 'write' }]);
+      const writes = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), ALL_VISIBLE);
+      expect(writes.map((w) => w.repoRelativePath)).toEqual(['Archive/access.md']);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('KbReferenceScanner — references are what the resolver parses', () => {
+  // A body-governed access.md: the body is the folder's rules, the
+  // frontmatter the file's own — here a FLOW sequence, which only the
+  // resolver's full-YAML fallback reads. And a node whose owner is QUOTED.
+  const FLOW_ACCESS_MD = '---\nread: ["Admin"]\n---\nwrite:\n  - Admin\n';
+  const QUOTED_NODE = "---\nowner: 'Admin'\n---\n# Doc\n";
+
+  it('the scan reports quoted and flow-YAML rules the resolver enforces', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-yaml-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'Team/access.md', FLOW_ACCESS_MD);
+      await write(repo, 'Team/Doc.md', QUOTED_NODE);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+
+      const hits = (await scanner.scan('ws-1')).get('admin') ?? [];
+      expect(hits).toEqual(
+        expect.arrayContaining([
+          { path: 'Team/access.md', verb: 'write' },
+          { path: 'Team/access.md', verb: 'read' },
+          { path: 'Team/Doc.md', verb: 'owner' },
+        ]),
+      );
+      expect(hits).toHaveLength(3);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('an access.md the resolver drops as broken references nothing', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-broken-'));
+    try {
+      // A scalar where the verb needs a list: a hard parse error, so the
+      // resolver ignores the whole file.
+      await write(path.join(root, KB), 'Team/access.md', '---\nread: Admin\nwrite:\n  - Admin\n---\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      expect((await scanner.scan('ws-1')).get('admin')).toBeUndefined();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a rename rewrites quoted and flow-YAML references in place, quoting and comments kept', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-structural-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'Team/access.md', FLOW_ACCESS_MD);
+      await write(repo, 'Team/Doc.md', "---\nnodeType: Doc # kept\nowner: 'Admin'\nread: [Sales, \"deny Admin\"]\n---\n# Doc\n");
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      const writes = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), ALL_VISIBLE);
+      const byPath = new Map(writes.map((w) => [w.repoRelativePath, w.content]));
+      expect(byPath.get('Team/access.md')).toBe('---\nread: ["Admins"]\n---\nwrite:\n  - Admins\n');
+      expect(byPath.get('Team/Doc.md')).toBe(
+        "---\nnodeType: Doc # kept\nowner: 'Admins'\nread: [Sales, \"deny Admins\"]\n---\n# Doc\n",
+      );
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('an alias under a verb key is rewritten without touching the anchor it points at', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-alias-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'Team/Doc.md', '---\nteam: &t Admin\nread: [*t]\n---\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      const [w] = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), ALL_VISIBLE);
+      expect(w.content).toBe('---\nteam: &t Admin\nread: [Admins]\n---\n');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  // Stated Contracts Are Checked, Not Trusted: the resolver reads `read: *team`
+  // as the anchored list's entries, so the rename rewrites them there — on a
+  // copy, leaving the anchor and its other uses as they were.
+  it.each([
+    [
+      'the whole verb value',
+      '---\nteam: &team\n  - Admin\n  - Sales\nread: *team\n---\n# Doc\n',
+      '---\nteam: &team\n  - Admin\n  - Sales\nread:\n  - Admins\n  - Sales\n---\n# Doc\n',
+    ],
+    [
+      'beside a quoted verb, an aliased item inside it',
+      "---\nlead: &lead Admin\nteam: &team\n  - *lead\n  - deny Admin\nread: *team\nowner: 'Sales'\n---\n",
+      "---\nlead: &lead Admin\nteam: &team\n  - *lead\n  - deny Admin\nread:\n  - Admins\n  - deny Admins\nowner: 'Sales'\n---\n",
+    ],
+  ])('an alias to an anchored list is rewritten as a copy (%s)', async (_label, before, after) => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-alias-list-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'Team/Doc.md', before);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      const writes = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), ALL_VISIBLE);
+      expect(writes.map((w) => [w.repoRelativePath, w.content])).toEqual([['Team/Doc.md', after]]);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  // A Guard's Answer Is a Disclosure, and Widening a Primitive Traces Its
+  // Consequences: a file the renaming person cannot read (another person's
+  // private plugin) neither blocks the rename nor changes its answer —
+  // whatever it holds, the rename completes and the file is rewritten like
+  // any other, so no reference to the old name is stranded there.
+  it.each([
+    ['no reference', '---\nread:\n  - Sales\n---\n', null],
+    ['a block-list reference', '---\nread:\n  - Admin\n---\n', '---\nread:\n  - Admins\n---\n'],
+    ['a flow-YAML reference', FLOW_ACCESS_MD, '---\nread: ["Admins"]\n---\nwrite:\n  - Admins\n'],
+  ])('a file the renaming person cannot read never blocks the rename (%s)', async (_label, secret, expected) => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-hidden-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'Team/access.md', '---\nread:\n  - Admin\n---\n');
+      await write(repo, 'Secret/access.md', secret);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      const onlyTeam: PathVisibility = async (paths) => new Map(paths.map((p) => [p, p.startsWith('Team/')]));
+      const writes = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), onlyTeam);
+      const byPath = new Map(writes.map((w) => [w.repoRelativePath, w.content]));
+      expect(byPath.get('Team/access.md')).toBe('---\nread:\n  - Admins\n---\n');
+      expect(byPath.get('Secret/access.md') ?? null).toBe(expected);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a rename by someone who can read nothing still completes', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-none-visible-'));
+    try {
+      await write(path.join(root, KB), 'Team/access.md', FLOW_ACCESS_MD);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB);
+      const writes = await scanner.rewriteReferences('ws-1', 'admin', 'Admins', (m) => new Error(m), NONE_VISIBLE);
+      expect(writes.map((w) => w.repoRelativePath)).toEqual(['Team/access.md']);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('KbReferenceScanner — a folder the walk cannot list', () => {
+  /** The real walk, reporting `Locked` as a folder it could not list. */
+  function walkerWithHole(hole = 'Locked'): ITreeWalker & { walks: number } {
+    const disk = new NodeFs();
+    const walker = {
+      walks: 0,
+      walk: (r: string, o: Parameters<NodeFs['walk']>[1], l: Parameters<NodeFs['walk']>[2]) => disk.walk(r, o, l),
+      walkFiles: (r: string, m: (b: string) => boolean, o?: { strict?: boolean }) => disk.walkFiles(r, m, o),
+      walkKb: async (r: string, l: Parameters<NodeFs['walkKb']>[1], o?: Parameters<NodeFs['walkKb']>[2]) => {
+        walker.walks++;
+        const result = await disk.walkKb(r, l, o);
+        return { holes: [...result.holes, hole] };
+      },
+    };
+    return walker;
+  }
+
+  it('a rename refuses with nothing written: the folder may hold references', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-hole-'));
+    try {
+      await write(path.join(root, KB), 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walkerWithHole(), KB);
+      await expect(
+        scanner.rewriteReferences('ws-1', 'sales', 'Revenue', (m) => new Error(m), ALL_VISIBLE),
+      ).rejects.toThrow(UNSHOWN_REFERENCE_REFUSAL);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  // The folder's own access.md may be as unreadable as its listing, so the
+  // visibility check cannot see the rules that close it: never named.
+  it('the refusal neither names nor counts the folder, even to someone who could read every path', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-hole-hidden-'));
+    try {
+      await write(path.join(root, KB), 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walkerWithHole(), KB);
+      const err = await scanner
+        .rewriteReferences('ws-1', 'sales', 'Revenue', (m) => new Error(m), ALL_VISIBLE)
+        .catch((e: Error) => e);
+      expect((err as Error).message).toBe(UNSHOWN_REFERENCE_REFUSAL);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a folder name with a line break cannot forge a second line in the refusal', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-hole3-'));
+    try {
+      await write(path.join(root, KB), 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walkerWithHole('Lo\nFAKE: line'), KB);
+      const err = await scanner
+        .rewriteReferences('ws-1', 'sales', 'Revenue', (m) => new Error(m), ALL_VISIBLE)
+        .catch((e: Error) => e);
+      expect((err as Error).message).not.toContain('\n');
+      expect((err as Error).message).not.toContain('FAKE');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a file the rewrite cannot read is neither named nor counted, and its fs cause stays out of the error', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-unreadable-'));
+    try {
+      const repo = path.join(root, KB);
+      await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      // The walk lists team/Ghost.md, but there is no file to read.
+      const disk = new NodeFs();
+      const walker: ITreeWalker = {
+        walk: (r, o, l) => disk.walk(r, o, l),
+        walkFiles: (r, m, o) => disk.walkFiles(r, m, o),
+        walkKb: async (r, l, o) => {
+          const result = await disk.walkKb(r, l, o);
+          for (const listener of l) listener.onFile?.('team', 'Ghost.md');
+          return result;
+        },
+      };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walker, KB);
+      const causes: (string | undefined)[] = [];
+      const err = await scanner
+        .rewriteReferences(
+          'ws-1',
+          'sales',
+          'Revenue',
+          (m, cause) => {
+            causes.push(cause);
+            return new Error(m);
+          },
+          ALL_VISIBLE,
+        )
+        .catch((e: Error) => e);
+      expect((err as Error).message).toBe(UNSHOWN_REFERENCE_REFUSAL);
+      expect(causes).toEqual([undefined]);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('the advisory scan still answers what it read, but never caches an incomplete result', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-hole2-'));
+    try {
+      await write(path.join(root, KB), 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      const walker = walkerWithHole();
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walker, KB);
+      expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
+      await scanner.scan('ws-1');
+      // Not served from cache: the second scan retried the listing.
+      expect(walker.walks).toBe(2);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('a scan that could not read a candidate file is not cached', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-unread-'));
+    try {
+      await write(path.join(root, KB), 'team/access.md', '---\nread:\n  - Sales\n---\n');
+      // The walk lists team/Ghost.md, but there is no file to read.
+      const disk = new NodeFs();
+      let walks = 0;
+      const walker: ITreeWalker = {
+        walk: (r, o, l) => disk.walk(r, o, l),
+        walkFiles: (r, m, o) => disk.walkFiles(r, m, o),
+        walkKb: async (r, l, o) => {
+          walks++;
+          const result = await disk.walkKb(r, l, o);
+          for (const listener of l) listener.onFile?.('team', 'Ghost.md');
+          return result;
+        },
+      };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walker, KB);
+      expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
+      await scanner.scan('ws-1');
+      // Not served from cache: the second scan walked and read again.
+      expect(walks).toBe(2);
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('KbReferenceScanner — event-bus cache invalidation', () => {
   it('drops the cached scan when a scanned-extension file changes in the workspace', async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-refscan-bus-'));
@@ -192,7 +543,7 @@ describe('KbReferenceScanner — event-bus cache invalidation', () => {
       await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
       const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
       const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
-      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB, bus);
 
       expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
 
@@ -216,22 +567,23 @@ describe('KbReferenceScanner — event-bus cache invalidation', () => {
     try {
       const repo = path.join(root, KB);
       await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
-      // The workspace stub invalidates DURING the first scan's tree listing —
+      // The walker invalidates DURING the first scan's tree listing —
       // modelling a write that lands after the scan started reading.
-      const base = stubWorkspace(root);
+      const disk = new NodeFs();
       let armed = true;
-      const ws = {
-        ...base,
-        listFiles: async (id: string) => {
-          const tree = await base.listFiles(id);
+      const walker: ITreeWalker = {
+        walk: (r, o, l) => disk.walk(r, o, l),
+        walkFiles: (r, m, o) => disk.walkFiles(r, m, o),
+        walkKb: async (r, l, o) => {
+          const result = await disk.walkKb(r, l, o);
           if (armed) {
             armed = false;
             scanner.invalidate('ws-1');
           }
-          return tree;
+          return result;
         },
-      } as unknown as IWorkspaceService;
-      const scanner = new KbReferenceScanner(ws, KB);
+      };
+      const scanner = new KbReferenceScanner(stubWorkspace(root), walker, KB);
 
       // The caller still gets the snapshot it asked for...
       expect((await scanner.scan('ws-1')).get('sales')).toHaveLength(1);
@@ -252,7 +604,7 @@ describe('KbReferenceScanner — event-bus cache invalidation', () => {
       await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
       const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
       const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
-      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB, bus);
 
       const first = await scanner.scan('ws-1');
       for (const l of listeners) {
@@ -272,7 +624,7 @@ describe('KbReferenceScanner — event-bus cache invalidation', () => {
       await write(repo, 'team/access.md', '---\nread:\n  - Sales\n---\n');
       const listeners: ((e: { kind: string; workspaceId?: string; path?: string }) => void)[] = [];
       const bus = { onEmit: (l: (typeof listeners)[number]) => (listeners.push(l), () => undefined) };
-      const scanner = new KbReferenceScanner(stubWorkspace(root), KB, bus);
+      const scanner = new KbReferenceScanner(stubWorkspace(root), new NodeFs(), KB, bus);
 
       const first = await scanner.scan('ws-1');
       for (const l of listeners) {

package/src/modules/access/__tests__/roles-admin.security.test.ts

@@ -127,7 +127,7 @@ describe('SECURITY: Admin-role removal takes effect on the next request', () =>
     // cache and could pass this test while production still served stale
     // verdicts, which is the failure mode worth guarding.
     access = new AccessControlService(ws, KB, new NodeFs(), [OWNER]);
-    rolesAdmin = new RolesAdminService(ws, stubWorkflow(), access, KB, () => DEFAULT_BRANCH, undefined, [
+    rolesAdmin = new RolesAdminService(ws, stubWorkflow(), access, new NodeFs(), KB, () => DEFAULT_BRANCH, undefined, [
       OWNER,
     ]);
     const adminAccess = new AdminAccessService(access, ws, DEFAULT_BRANCH, [OWNER]);

package/src/modules/access/__tests__/roles-admin.service.test.ts

@@ -21,6 +21,8 @@ const WS = workspaceIdForBranch(DEFAULT_BRANCH);
 
 const ADMIN: AuthUser = { id: 'u-admin', email: 'razvan@bevel.software', name: 'Razvan' } as AuthUser;
 const OTHER_ADMIN: AuthUser = { id: 'u-2', email: 'juan@bevel.software', name: 'Juan' } as AuthUser;
+/** A Sales member: reads the Sales-governed files the roster tests reference. */
+const SALES_VIEWER = 'felix@example.com';
 
 const ROLES = `roles:
   Admin:
@@ -169,7 +171,7 @@ describe('RolesAdminService', () => {
     access = new AccessControlService(ws, KB, new NodeFs());
     workflow = stubWorkflow();
     bus = stubEventBus();
-    svc = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus, [
+    svc = new RolesAdminService(ws, workflow.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH, bus.bus, [
       'recovery-admin@example.com',
     ]);
   });
@@ -179,7 +181,7 @@ describe('RolesAdminService', () => {
   });
 
   it('getRoster lists roles, marks Admin, dedupes members', async () => {
-    const roster = await svc.getRoster();
+    const roster = await svc.getRoster(ADMIN.email);
     expect(roster.map((r) => r.canonical)).toEqual(['admin', 'sales']);
     expect(roster.find((r) => r.canonical === 'admin')!.isAdmin).toBe(true);
     expect(roster.find((r) => r.canonical === 'sales')!.members).toEqual(['felix@example.com']);
@@ -191,9 +193,9 @@ describe('RolesAdminService', () => {
     // `DEFAULT_BRANCH` and froze it — every roles route then failed branch
     // validation with `Invalid branch name "": empty name` until a restart.
     let branch = '';
-    const late = new RolesAdminService(ws, workflow.svc, access, KB, () => branch, bus.bus);
+    const late = new RolesAdminService(ws, workflow.svc, access, new NodeFs(), KB, () => branch, bus.bus);
     branch = DEFAULT_BRANCH;
-    const roster = await late.getRoster();
+    const roster = await late.getRoster(ADMIN.email);
     expect(roster.map((r) => r.canonical)).toEqual(['admin', 'sales']);
   });
 
@@ -255,7 +257,7 @@ describe('RolesAdminService', () => {
     const corrupt = 'roles:\n  Admin:\n    - a@x.eu\n  Admin:\n    - b@x.eu\n';
     await write(repo, 'roles.yaml', corrupt);
     access.invalidate(WS);
-    const adminless = new RolesAdminService(ws, workflow.svc, access, KB, () => DEFAULT_BRANCH, bus.bus);
+    const adminless = new RolesAdminService(ws, workflow.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH, bus.bus);
     // 409, not 500: the route helper hides >=500 bodies behind a generic
     // message, and this break-glass refusal must reach the operator verbatim.
     await expect(adminless.recover(ADMIN)).rejects.toMatchObject({
@@ -273,13 +275,24 @@ describe('RolesAdminService', () => {
     // ...AND a grant that lives ONLY in a node's own frontmatter (the gap).
     await write(repo, 'team/deal.md', '---\nowner: Sales\n---\n# Deal\n');
 
-    const sales = (await svc.getRoster()).find((r) => r.canonical === 'sales')!;
+    const sales = (await svc.getRoster(SALES_VIEWER)).find((r) => r.canonical === 'sales')!;
     const paths = sales.referencedBy.map((r) => r.path).sort();
     expect(paths).toEqual(['team/access.md', 'team/deal.md']);
     // The frontmatter ref carries its verb, so the warning can name it.
     expect(sales.referencedBy).toContainEqual({ path: 'team/deal.md', verb: 'owner' });
     // An unreferenced role still shows nothing.
-    expect((await svc.getRoster()).find((r) => r.canonical === 'admin')!.referencedBy).toEqual([]);
+    expect((await svc.getRoster(SALES_VIEWER)).find((r) => r.canonical === 'admin')!.referencedBy).toEqual([]);
+  });
+
+  it("getRoster names only files the viewer can read and leaves the rest out, uncounted — an Admin can't read Sales's files", async () => {
+    await write(repo, 'team/access.md', '---\nread:\n  - deny everyone\n  - Sales\n---\n');
+    await write(repo, 'team/deal.md', '---\nowner: Sales\n---\n# Deal\n');
+
+    const asAdmin = (await svc.getRoster(ADMIN.email)).find((r) => r.canonical === 'sales')!;
+    expect(asAdmin.referencedBy).toEqual([]);
+    expect(asAdmin).not.toHaveProperty('referencesHidden');
+    const asMember = (await svc.getRoster(SALES_VIEWER)).find((r) => r.canonical === 'sales')!;
+    expect(asMember.referencedBy).toHaveLength(2);
   });
 
   it('addMember persists + is idempotent', async () => {
@@ -560,6 +573,7 @@ describe('roster referencedBy under group shadowing', () => {
       ws,
       stubWorkflow().svc,
       new AccessControlService(ws, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
       stubEventBus().bus,
@@ -570,20 +584,26 @@ describe('roster referencedBy under group shadowing', () => {
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  it('a bare-token hit is the GROUP’s when a group shadows the role name; role/<name> hits stay the role’s', async () => {
-    // A group named Sales shadows the Sales role: bare tokens resolve to the
-    // GROUP, so the roles roster must not claim them as role references.
+  it('a bare-token hit stays the ROLE’s when a group shares the name; group/<name> hits never are', async () => {
+    // A group named Sales shares the Sales role's name: bare tokens still
+    // resolve to the ROLE, so the roles roster claims them; group/ is the group.
     await write(repo, 'groups.yaml', 'groups:\n  Sales:\n    - pat@x.io\n');
-    await write(repo, 'team/access.md', '---\nread:\n  - Sales\nwrite:\n  - role/Sales\n---\n');
+    await write(
+      repo,
+      'team/access.md',
+      '---\nread:\n  - Sales\nwrite:\n  - role/Sales\nowner:\n  - group/Sales\n---\n',
+    );
 
-    const sales = (await svc.getRoster()).find((r) => r.canonical === 'sales')!;
-    // Only the explicit spelling counts for the ROLE.
-    expect(sales.referencedBy).toEqual([{ path: 'team/access.md', verb: 'write' }]);
+    const sales = (await svc.getRoster(SALES_VIEWER)).find((r) => r.canonical === 'sales')!;
+    expect(sales.referencedBy).toEqual([
+      { path: 'team/access.md', verb: 'read' },
+      { path: 'team/access.md', verb: 'write' },
+    ]);
   });
 
-  it('unshadowed: bare hits still count for the role (both spellings)', async () => {
+  it('with no group of the name: bare hits count for the role (both spellings)', async () => {
     await write(repo, 'team/access.md', '---\nread:\n  - Sales\nwrite:\n  - role/Sales\n---\n');
-    const sales = (await svc.getRoster()).find((r) => r.canonical === 'sales')!;
+    const sales = (await svc.getRoster(SALES_VIEWER)).find((r) => r.canonical === 'sales')!;
     expect(sales.referencedBy).toEqual([
       { path: 'team/access.md', verb: 'read' },
       { path: 'team/access.md', verb: 'write' },
@@ -611,6 +631,7 @@ describe('Admin fixed members — the deployment admin', () => {
       ws,
       workflow.svc,
       new AccessControlService(ws, KB, new NodeFs()),
+      new NodeFs(),
       KB,
       () => DEFAULT_BRANCH,
       stubEventBus().bus,
@@ -632,7 +653,7 @@ describe('Admin fixed members — the deployment admin', () => {
   });
 
   it('lists the deployment admin as a fixed member of Admin, and of no other role', async () => {
-    const roster = await serviceWith([OWNER]).getRoster();
+    const roster = await serviceWith([OWNER]).getRoster(ADMIN.email);
     expect(roster.find((r) => r.canonical === 'admin')!.fixedMembers).toEqual([OWNER]);
     expect(roster.find((r) => r.canonical === 'sales')!.fixedMembers).toEqual([]);
   });
@@ -641,7 +662,7 @@ describe('Admin fixed members — the deployment admin', () => {
     // The page prints `fixedMembersNote` as sent, so this is the one copy of
     // the wording: the note and the API refusal cannot drift apart.
     const svc = serviceWith([OWNER]);
-    const roster = await svc.getRoster();
+    const roster = await svc.getRoster(ADMIN.email);
     const note = roster.find((r) => r.canonical === 'admin')!.fixedMembersNote;
     expect(note).toBe('Owner; cannot be removed here');
     expect(roster.find((r) => r.canonical === 'sales')!.fixedMembersNote).toBeNull();
@@ -652,10 +673,10 @@ describe('Admin fixed members — the deployment admin', () => {
   it('canonicalises the configured address and drops a blank one', async () => {
     // The composition root passes `[config.adminEmail]` unconditionally, so an
     // unset ADMIN_EMAIL arrives as [''] — that must not become a member "".
-    expect((await serviceWith(['']).getRoster()).find((r) => r.canonical === 'admin')!.fixedMembers)
+    expect((await serviceWith(['']).getRoster(ADMIN.email)).find((r) => r.canonical === 'admin')!.fixedMembers)
       .toEqual([]);
     expect(
-      (await serviceWith(['  Owner@Bevel.Software  ']).getRoster()).find((r) => r.canonical === 'admin')!
+      (await serviceWith(['  Owner@Bevel.Software  ']).getRoster(ADMIN.email)).find((r) => r.canonical === 'admin')!
         .fixedMembers,
     ).toEqual([OWNER]);
   });
@@ -664,7 +685,7 @@ describe('Admin fixed members — the deployment admin', () => {
     // The seeded roles.yaml names ADMIN_EMAIL, so overlap is the normal case.
     // `members` must keep it — the Admin >=1-direct-email invariant counts the
     // FILE — and the page is what renders the overlap once.
-    const admin = (await serviceWith(['razvan@bevel.software']).getRoster()).find(
+    const admin = (await serviceWith(['razvan@bevel.software']).getRoster(ADMIN.email)).find(
       (r) => r.canonical === 'admin',
     )!;
     expect(admin.members).toContain('razvan@bevel.software');
@@ -710,7 +731,7 @@ describe('Admin fixed members — the deployment admin', () => {
   });
 
   it('with no ADMIN_EMAIL configured, no role has a fixed member', async () => {
-    const roster = await serviceWith([]).getRoster();
+    const roster = await serviceWith([]).getRoster(ADMIN.email);
     expect(roster.every((r) => r.fixedMembers.length === 0)).toBe(true);
     expect(roster.every((r) => r.fixedMembersNote === null)).toBe(true);
     // ...and ordinary Admin membership stays editable.