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

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

@@ -3,9 +3,15 @@
  * services (roles + groups) drive for "which access rules name this
  * principal" and "rewrite every reference atomically":
  *
- *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the config-region
- *     parse that decides what IS a principal reference. One source of truth,
- *     so the delete/rename warning and the rename rewrite can never disagree.
+ *   - `resolverRoleRefs`: what IS a principal reference — the resolver's own
+ *     parse of each file, so the reports name every enforced rule.
+ *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the line-level walk
+ *     the rename edits text with. It handles block lists and `key: value`
+ *     entries; quoted and flow-YAML own frontmatter is rewritten by the
+ *     full parser's own tree (`rewriteOwnFrontmatterStructurally`). The
+ *     rewrite re-checks its result with `resolverRoleRefs` and refuses
+ *     when a reference survives, so the warning and the rename can never
+ *     disagree.
  *   - `KbReferenceScanner`: candidate collection (every KB file with an
  *     access-frontmatter extension — `.md` and `.tool`, the resolver's own
  *     set), the advisory reference scan (cached — roster mutations must not
@@ -14,24 +20,37 @@
  *     file's ORIGINAL text too, so rollback snapshots reuse the read the
  *     rewrite already did instead of a second full-KB pass).
  *
- * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (group
- * first, then role) or an explicit `role/<name>`. Callers translate: a ROLE's
- * references are its bare token plus its `role/` token; a GROUP's are its
- * bare token only.
+ * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (the role
+ * when one exists, else the group) or an explicit `role/<name>` /
+ * `group/<name>`. Callers translate: a ROLE's references are its bare token
+ * plus its `role/` token; a GROUP's are its `group/` token, plus the bare
+ * token while no role shares the name.
  */
 
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 
-import { isFrontmatterFence, type FileTreeEntry, type IWorkspaceService } from '@bevel-software/platform-shared';
+import { Scalar, YAMLSeq, isAlias, isMap, isNode, isScalar, isSeq, parseDocument, type Document } from 'yaml';
+import { isFrontmatterFence, type IWorkspaceService } from '@bevel-software/platform-shared';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
+import { logger } from '../../shared/logging.js';
+import { printable, sanitizedPath } from '../../shared/printable.js';
 import {
+  AccessDeniedError,
   KNOWN_VERBS,
   accessMdDeclaresBodyRules,
+  accessMdSelfEntries,
+  canonicalRoleName,
   hasAccessFrontmatterExtension,
   isAccessMdPath,
   parseAccessEntry,
+  parseAccessFile,
+  parseOwnAccessEntries,
   stripComment,
 } from '../access-model/index.js';
+import type { ParsedEntry, Verb } from '../access-model/index.js';
+
+const log = logger('access');
 
 /**
  * Resolve the [start, end) line range that role rewrites may touch — the YAML
@@ -237,8 +256,8 @@ function walkRoleRefs(
 
 /**
  * Every genuine role/group reference in `text`'s rule regions, as
- * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name or
- * `role/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
+ * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name,
+ * `role/<name>` or `group/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
  * rule source in the body-governed format — see {@link ruleLineRanges}.
  */
 export function findRoleRefsInText(
@@ -291,6 +310,115 @@ export function rewriteRoleTokensInText(
   return changed ? lines.join('\n') : text;
 }
 
+/**
+ * The structural rewrite, for the references the line walk cannot edit:
+ * a file's OWN frontmatter is read by the full YAML parser whenever it holds
+ * flow sequences, quoted scalars or other real YAML (`ownEntriesRoot` in the
+ * grammar), and the line walk only knows block lists and `key: value`. So
+ * this edits the same document the resolver reads — the frontmatter's
+ * top-level verb keys, by the full parser's own node tree with the same
+ * FAILSAFE schema — and replaces each scalar entry whose token is in
+ * `oldTokens`, keeping its quoting, its comments and every other node. An
+ * alias the resolver reads as a verb's entries is never edited through: one
+ * that names an old token is replaced by a plain scalar, and one that is the
+ * verb's whole list (`read: *team`, `&team` a list) by a rewritten copy of
+ * that list, so the anchor it points at (which may sit under any other key)
+ * is left alone.
+ *
+ * The other rule sources — a legacy `access.md`'s frontmatter and a
+ * body-governed one's body — are read by the YAML-subset parser only, which
+ * the line walk mirrors, so they never need this.
+ */
+function rewriteOwnFrontmatterStructurally(
+  text: string,
+  oldTokens: ReadonlySet<string>,
+  newDisplayName: string,
+): string {
+  const lines = text.split('\n');
+  const { start, end } = configLineRange(lines, true);
+  if (start >= end) return text;
+  // Typed as an editable document: the rewrite puts new, unparsed scalars in it.
+  const doc: Document = parseDocument(lines.slice(start, end).join('\n'), { schema: 'failsafe' });
+  // A document the full parser rejects is not what the resolver read: it fell
+  // back to the subset parser, whose reading the line walk already covers.
+  if (doc.errors.length > 0 || !isMap(doc.contents)) return text;
+  let changed = false;
+  const rewritten = (node: unknown): Scalar | null => {
+    const target = isAlias(node) ? node.resolve(doc) : node;
+    if (!isScalar(target) || typeof target.value !== 'string') return null;
+    const parsed = parseAccessEntry(target.value);
+    if (!parsed.ok || parsed.entry.kind !== 'role' || !oldTokens.has(parsed.entry.role)) return null;
+    const value = `${parsed.entry.deny ? 'deny ' : ''}${newDisplayName}`;
+    changed = true;
+    if (isAlias(node)) return new Scalar(value);
+    target.value = value;
+    return target;
+  };
+  // The anchored list an alias names, as a rewritten copy — or null when
+  // none of its entries changes, so the alias stays. Each item is cloned
+  // before it is rewritten (the anchor's own items stay as they are) and
+  // loses any anchor of its own (YAML allows one definition of a name).
+  const rewrittenCopy = (seq: YAMLSeq): YAMLSeq | null => {
+    let hit = false;
+    const copy = new YAMLSeq(doc.schema);
+    copy.flow = seq.flow;
+    copy.items = seq.items.map((item) => {
+      const clone = isNode(item) ? item.clone() : item;
+      if (isScalar(clone)) clone.anchor = undefined;
+      const r = rewritten(clone);
+      if (r) hit = true;
+      return r ?? clone;
+    });
+    return hit ? copy : null;
+  };
+  for (const pair of doc.contents.items) {
+    const key = isScalar(pair.key) ? pair.key.value : pair.key;
+    if (typeof key !== 'string' || !VERB_KEYS.has(key)) continue;
+    const aliased = isAlias(pair.value) ? pair.value.resolve(doc) : null;
+    if (isSeq(aliased)) {
+      const copy = rewrittenCopy(aliased);
+      if (copy) pair.value = copy;
+    } else if (isSeq(pair.value)) {
+      pair.value.items = pair.value.items.map((item) => rewritten(item) ?? item);
+    } else {
+      const scalar = rewritten(pair.value);
+      if (scalar) pair.value = scalar;
+    }
+  }
+  if (!changed) return text;
+  // Never fold a long value onto a second line, nor pad a flow list.
+  const frontmatter = doc.toString({ lineWidth: 0, flowCollectionPadding: false }).replace(/\n$/, '');
+  return [...lines.slice(0, start), frontmatter, ...lines.slice(end)].join('\n');
+}
+
+/**
+ * The principal references the RESOLVER reads from one candidate file, by
+ * the resolver's own parsers: an `access.md`'s folder rules
+ * (`parseAccessFile`) and its self-rules (`accessMdSelfEntries`), any other
+ * file's own frontmatter (`parseOwnAccessEntries`). Those parsers read
+ * quoted scalars and flow sequences (`read: ["Admin"]`) the line walker
+ * above does not, so the reports built on this name every rule that is
+ * actually enforced — and nothing the resolver ignores (a broken
+ * `access.md` is dropped from the model, so it references nothing).
+ */
+export function resolverRoleRefs(text: string, repoRel: string): { role: string; verb: string }[] {
+  const out: { role: string; verb: string }[] = [];
+  const add = (entries: Record<Verb, ParsedEntry[]> | null): void => {
+    if (!entries) return;
+    for (const verb of KNOWN_VERBS) {
+      for (const e of entries[verb]) if (e.kind === 'role') out.push({ role: e.role, verb });
+    }
+  };
+  if (isAccessMdPath(repoRel)) {
+    const folder = parseAccessFile(text, repoRel);
+    if (folder.ok) add(folder.file.entries);
+    add(accessMdSelfEntries(text));
+  } else {
+    add(parseOwnAccessEntries(text));
+  }
+  return out;
+}
+
 export interface ReferenceHit {
   path: string;
   verb: string;
@@ -304,6 +432,75 @@ export interface ReferenceRewrite {
   original: string;
 }
 
+/**
+ * Which of the given repo-relative paths the person a refusal is for may
+ * read — `canReadBatch` bound to that person. A path is itself a disclosure,
+ * so a refusal names only these and says nothing of the rest.
+ */
+export type PathVisibility = (repoRelPaths: string[]) => Promise<ReadonlyMap<string, boolean>>;
+
+/**
+ * The one refusal for a rename blocked by a place the renaming person may
+ * not be shown — a folder the walk cannot list, a file it cannot read, or a
+ * file the person may not read that still names the old principal after the
+ * rewrite (a backstop: every form the resolver reads is rewritten). The same
+ * words whatever the cause: no path, no count, no hint of a reference, since
+ * Admin status does not grant read and each of those is a disclosure. The
+ * log names the place.
+ */
+export const UNSHOWN_REFERENCE_REFUSAL =
+  'This rename rewrites access rules across the knowledge base, and part of the knowledge base could not be rewritten, so it may still reference the old principal; rename aborted with no changes. The server log names where.';
+
+/**
+ * The commit's own write gate refusing a rename's rewrite, translated for the
+ * person who asked. The gate judges every file the rewrite touches against the
+ * actor's WRITE rules (a rename's references reach files private to others,
+ * which an Admin may be unable to write), and its refusal names the file. A
+ * file its person may read keeps that refusal: the path and its eligible
+ * writers say whom to ask. A file they may not read gets
+ * `UNSHOWN_REFERENCE_REFUSAL` instead, so the hidden path stays unnamed; the
+ * log names it. Anything else comes back unchanged.
+ *
+ * The one bit left (some file the person cannot see names the old principal)
+ * is the hidden-blocker exception of "A Guard's Answer Is a Disclosure": an
+ * Admin's refused rename of a principal they manage says only that an unshown
+ * place blocks it.
+ */
+export async function translateRewriteWriteRefusal(
+  err: unknown,
+  visible: PathVisibility,
+  makeError: (message: string) => Error,
+): Promise<unknown> {
+  if (!(err instanceof AccessDeniedError)) return err;
+  const p = err.access.path;
+  let shown = false;
+  try {
+    shown = (await visible([p])).get(p) === true;
+  } catch {
+    // Cannot tell whether the person may see it: say nothing of it.
+  }
+  if (shown) return err;
+  log.warn(`reference rewrite: the acting person may not write ${printable(p)}`);
+  const translated = makeError(UNSHOWN_REFERENCE_REFUSAL);
+  // withFileLocks reads the paths whose restore failed off the error it
+  // catches, to discard their partial bytes; the translation must carry them.
+  const unrestored = (err as { unrestoredPaths?: Set<string> }).unrestoredPaths;
+  if (unrestored) (translated as { unrestoredPaths?: Set<string> }).unrestoredPaths = unrestored;
+  return translated;
+}
+
+/**
+ * The rows of `refs` whose file `readable` allows. The rest are dropped
+ * outright, not counted: Admin status does not grant read, so even a count of
+ * rules in content the viewer cannot read is a disclosure.
+ */
+export function readableReferences(
+  refs: readonly ReferenceHit[],
+  readable: ReadonlyMap<string, boolean>,
+): ReferenceHit[] {
+  return refs.filter((r) => readable.get(r.path) === true);
+}
+
 /** How long a cached reference scan may serve after its load. Backstop only —
  *  reference-changing writes invalidate explicitly (the admin services after
  *  their own rewrites, and the event-bus tap below for everyone else's). */
@@ -354,6 +551,8 @@ export class KbReferenceScanner {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
+    /** The resolver's walk (see `collectCandidateFiles`), injected by the composition root. */
+    private readonly disk: ITreeWalker,
     private readonly kbDirName: string,
     eventBus?: ReferenceScanInvalidationBus,
   ) {
@@ -381,37 +580,40 @@ export class KbReferenceScanner {
    * resolver reads access verbs from — the shared
    * `ACCESS_FRONTMATTER_EXTENSIONS` set (`.md` AND `.tool`; a rename that
    * skipped `.tool` would strand a live frontmatter grant there). Sourced
-   * from the workspace file tree (which already skips `.git` and honours
-   * `.bevelignore`), filtered under the KB dir and returned bare
-   * repo-relative. (`roles.yaml` matches no scanned extension, so it's
-   * excluded; callers commit it separately.) Under save=share the working
-   * tree matches the committed set, so this is the same candidate list
-   * git-tracking would give.
+   * from the RESOLVER'S OWN walk (`walkKb`: dot-entries and vendored
+   * dependencies skipped, `.bevelignore` NOT honoured) — the resolver
+   * enforces an `access.md` the explorer hides, so a scan that honoured the
+   * ignore file would leave its rules out of the roster's reports and a
+   * rename would strand them. Paths are relative to the KB dir. (`roles.yaml`
+   * matches no scanned extension, so it's excluded; callers commit it
+   * separately.)
+   *
+   * `holes` names every folder the walk could not list: the candidate set
+   * is INCOMPLETE when it is non-empty, and each caller decides what that
+   * means — the rewrite refuses, the advisory scan says so and does not cache.
    */
-  async collectCandidateFiles(workspaceId: string): Promise<string[]> {
-    const tree = await this.workspaceService.listFiles(workspaceId);
-    const prefix = `${this.kbDirName}/`;
+  async collectCandidateFiles(workspaceId: string): Promise<{ files: string[]; holes: string[] }> {
     const out: string[] = [];
-    const visit = (node: FileTreeEntry): void => {
-      if (node.type === 'file') {
-        if (node.relativePath.startsWith(prefix) && hasAccessFrontmatterExtension(node.relativePath)) {
-          out.push(node.relativePath.slice(prefix.length));
-        }
-        return;
-      }
-      for (const child of node.children ?? []) visit(child);
-    };
-    visit(tree);
-    return out;
+    const { holes } = await this.disk.walkKb(await this.repoDir(workspaceId), [
+      {
+        onFile(dir, name) {
+          const rel = dir ? `${dir}/${name}` : name;
+          if (hasAccessFrontmatterExtension(rel)) out.push(rel);
+        },
+      },
+    ]);
+    return { files: out, holes };
   }
 
   /**
    * Sound scan of EVERY candidate file (folder `access.md` + `.md`/`.tool`
    * node frontmatter) for genuine principal references, indexed by canonical
-   * entry TOKEN. Shares the
-   * candidate set and the config-region parse with the rename rewrite, so the
-   * delete warning and the rewrite see the SAME references. A file we cannot
-   * read is skipped (this is an advisory read, not the atomic write path).
+   * entry TOKEN, read by the resolver's own parse ({@link resolverRoleRefs}).
+   * Shares the candidate set with the rename rewrite, and the rewrite checks
+   * its result against the same parse, so the delete warning and the rewrite
+   * cannot disagree on what references a principal. A file we cannot
+   * read is skipped (this is an advisory read, not the atomic write path),
+   * and the scan that skipped it is not cached.
    * Cached per workspace (see class doc); reads are batched with Promise.all
    * rather than serial per-file awaits.
    */
@@ -428,7 +630,12 @@ export class KbReferenceScanner {
     const startedUnder = flight.gen;
     try {
       const repoDir = await this.repoDir(workspaceId);
-      const candidates = await this.collectCandidateFiles(workspaceId);
+      const { files: candidates, holes } = await this.collectCandidateFiles(workspaceId);
+      if (holes.length > 0) {
+        log.warn(
+          `reference scan: cannot list ${holes.map((h) => printable(h || '.')).join(', ')} — references there are not reported`,
+        );
+      }
       const texts = await Promise.all(
         candidates.map(async (repoRel) => {
           try {
@@ -442,7 +649,7 @@ export class KbReferenceScanner {
       candidates.forEach((repoRel, i) => {
         const text = texts[i];
         if (text === null) return;
-        for (const ref of findRoleRefsInText(text, true, isAccessMdPath(repoRel))) {
+        for (const ref of resolverRoleRefs(text, repoRel)) {
           const list = byToken.get(ref.role);
           if (list) list.push({ path: repoRel, verb: ref.verb });
           else byToken.set(ref.role, [{ path: repoRel, verb: ref.verb }]);
@@ -451,7 +658,10 @@ export class KbReferenceScanner {
       // Cache only when no invalidation landed mid-scan; the caller still gets
       // this snapshot (at worst one write stale — same as the pre-scan world),
       // but a stale snapshot must never STICK for a TTL. The next call re-scans.
-      if (flight.gen === startedUnder) {
+      // An incomplete scan (a folder could not be listed, or a candidate file
+      // could not be read) is never cached either: the next call retries it.
+      const unread = texts.some((t) => t === null);
+      if (flight.gen === startedUnder && holes.length === 0 && !unread) {
         this.cache.set(workspaceId, { loadedAt: Date.now(), byToken });
       }
       return byToken;
@@ -462,22 +672,50 @@ export class KbReferenceScanner {
   }
 
   /**
-   * Find every genuine reference to `oldToken` and rewrite it to
-   * `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
+   * Find every genuine reference to `oldToken` (or any of several spellings
+   * of one principal) and rewrite it to `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
    * the old token, and skipping it would commit a partial rewrite (a
    * half-renamed principal still pointed at by stragglers = silent access
    * drop) — so any read failure aborts via `makeError` with nothing written.
    * Returns the writes WITH each file's original text (rollback snapshots).
+   *
+   * The rename keeps the KB's references to a principal whole, so it rewrites
+   * every candidate, files its person may not read included: a file private
+   * to others blocks nothing here, and no answer of this method depends on
+   * what such a file holds. Whether the person may WRITE each rewritten file
+   * is the commit's gate to decide, not this method's (see
+   * `translateRewriteWriteRefusal`). Every form the resolver reads
+   * is rewritten — block lists and `key: value` by the line walk, quoted and
+   * flow-YAML own frontmatter by the structural rewrite — so there is no
+   * "cannot rewrite" answer for hidden content to give. The writes reach a
+   * caller only through surfaces gated on read (the roster, the event
+   * delivery), never through this method's answer.
+   *
+   * A reference the resolver still sees after both rewrites is refused: named
+   * with how to fix it when `visible` says its person may read the file, with
+   * `UNSHOWN_REFERENCE_REFUSAL` otherwise (no path, no count). Nothing the
+   * resolver reads should reach that, so the refusal is a backstop, not an
+   * answer the content of a hidden file can choose.
    */
   async rewriteReferences(
     workspaceId: string,
-    oldToken: string,
+    oldToken: string | readonly string[],
     newDisplayName: string,
     makeError: (message: string, cause?: string) => Error,
+    visible: PathVisibility,
   ): Promise<ReferenceRewrite[]> {
+    const oldTokens = typeof oldToken === 'string' ? [oldToken] : oldToken;
     const repoDir = await this.repoDir(workspaceId);
     const writes: ReferenceRewrite[] = [];
-    const candidates = await this.collectCandidateFiles(workspaceId);
+    const { files: candidates, holes } = await this.collectCandidateFiles(workspaceId);
+    // A folder we cannot list might hold references to the old token — same
+    // fail-closed rule as an unreadable file below, and never named nor
+    // counted, for the same reason: its own access.md may be just as
+    // unreadable, so `visible` could not see the rules that close it.
+    if (holes.length > 0) {
+      log.warn(`reference rewrite: cannot list ${holes.map((h) => printable(h || '.')).join(', ')}`);
+      throw makeError(UNSHOWN_REFERENCE_REFUSAL);
+    }
     const texts = await Promise.all(
       candidates.map(async (repoRel) => {
         try {
@@ -489,20 +727,55 @@ export class KbReferenceScanner {
     );
     for (const t of texts) {
       if (!t.ok) {
-        throw makeError(
-          `Cannot read ${t.repoRel} while rewriting references; rename aborted with no changes`,
-          t.cause,
-        );
+        // Never named, not even to a reader: `visible` decides from the
+        // file's own rules, and a file we cannot read has none it can see —
+        // an inherited grant would then disclose a path its own rules may
+        // close. The fs cause carries the path too, so it stays in the log.
+        log.warn(`reference rewrite: cannot read ${printable(t.repoRel)}`, { cause: t.cause });
+        throw makeError(UNSHOWN_REFERENCE_REFUSAL);
       }
     }
+    // Old tokens the rename must leave no reference to (the new name's own
+    // token is exempt: it IS the rewrite's result).
+    const newToken = canonicalRoleName(newDisplayName);
+    const gone = new Set(oldTokens.filter((t) => t !== newToken));
+    const stranded: string[] = [];
     candidates.forEach((repoRel, i) => {
       const entry = texts[i];
       if (!entry.ok) return; // unreachable — the loop above threw
-      const rewritten = rewriteRoleTokensInText(entry.text, oldToken, newDisplayName, true, isAccessMdPath(repoRel));
+      let rewritten = entry.text;
+      for (const token of oldTokens) {
+        rewritten = rewriteRoleTokensInText(rewritten, token, newDisplayName, true, isAccessMdPath(repoRel));
+      }
+      // The line rewrite edits block-list and `key: value` entries; the
+      // resolver also reads quoted and flow-YAML own frontmatter, which the
+      // structural rewrite edits by the full parser's own tree.
+      const stillNamed = (t: string) => resolverRoleRefs(t, repoRel).some((r) => gone.has(r.role));
+      if (stillNamed(rewritten)) {
+        rewritten = rewriteOwnFrontmatterStructurally(rewritten, new Set(oldTokens), newDisplayName);
+      }
+      // A reference the resolver still sees would be stranded by the rename.
+      if (stillNamed(rewritten)) {
+        stranded.push(repoRel);
+        return;
+      }
       if (rewritten !== entry.text) {
         writes.push({ repoRelativePath: repoRel, content: rewritten, original: entry.text });
       }
     });
+    if (stranded.length > 0) {
+      const verdicts = await visible(stranded);
+      const shown = stranded.filter((p) => verdicts.get(p) === true);
+      if (shown.length < stranded.length) {
+        log.warn(
+          `reference rewrite: cannot rewrite ${stranded.map((p) => printable(p || '.')).join(', ')}`,
+        );
+        throw makeError(UNSHOWN_REFERENCE_REFUSAL);
+      }
+      throw makeError(
+        `${shown.map((p) => sanitizedPath(p || '.')).join(', ')} name the old principal in a form the rename cannot rewrite; rewrite it as a \`- Name\` list item, then rename again. Rename aborted with no changes`,
+      );
+    }
     return writes;
   }
 

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

@@ -39,15 +39,22 @@ const log = logger('roles.recover');
 import type { WorkflowEventBus } from '../workflow/index.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
   ADMIN_CANONICAL,
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   canonicalEmail,
+  makeRolesYamlWriteValidator,
+  renderRolesYaml,
+  GROUPS_YAML,
+  SYNCED_GROUPS_YAML,
+  validateGroupsFile,
+  GROUP_REF_PREFIX,
+  RESERVED_ROLE_NAMES,
 } from '../access-model/index.js';
 import { loadActiveGroups } from './access-control.service.js';
-import { makeRolesYamlWriteValidator, renderRolesYaml, GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile, GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from '../access-model/index.js';
 import {
   parseRolesModel,
   deleteRole as editDeleteRole,
@@ -67,7 +74,7 @@ import {
 } from './groups-edit.js';
 import { capabilityRoleFor, isLegacyPeopleSetRole } from './capability-registry.js';
 import { AdminLockedCommits } from './admin-locked-commit.js';
-import { KbReferenceScanner } from './reference-scan.js';
+import { KbReferenceScanner, readableReferences } from './reference-scan.js';
 
 /** A mutation that cannot proceed (invariant violation, contention, not found). */
 export class RolesAdminError extends WorkflowDomainError {
@@ -118,11 +125,11 @@ export interface RoleRosterEntry {
   capability: { description: string; groupAssignable: boolean } | null;
   /**
    * Every access rule referencing this ROLE — folder `access.md` AND node
-   * frontmatter. `role/<name>` hits always count; a BARE-token hit counts
-   * only when no group shadows the name (bare tokens resolve group-first, so
-   * a shadowed bare grant is the GROUP's reference, listed on the groups
-   * roster instead). Sound: this is the SAME scan the group rename/delete
-   * rewrites use.
+   * frontmatter. `role/<name>` and BARE-token hits both count — a bare name
+   * is always the role when the role exists, even when a group shares the
+   * name (that group is `group/<name>`). Sound: this is the SAME scan the
+   * group rename/delete rewrites use. Only files the roster's viewer can read
+   * are listed (see `getRoster`).
    */
   referencedBy: { path: string; verb: string }[];
 }
@@ -180,6 +187,8 @@ export class RolesAdminService {
     private readonly workspaceService: IWorkspaceService,
     private readonly workflowService: IWorkflowService,
     private readonly accessControl: IAccessControl,
+    /** The composition root's walk — the one the resolver finds access rules with. */
+    disk: ITreeWalker,
     private readonly kbDirName: string,
     /**
      * The branch whose roles.yaml is authoritative for admin status, read
@@ -223,7 +232,7 @@ export class RolesAdminService {
     // The event bus keeps the roster's `referencedBy` fresh: a share-dialog
     // grant/revoke on any access.md happens outside this service, and the
     // scanner invalidates its cache on those writes' events (TTL as backstop).
-    this.references = new KbReferenceScanner(workspaceService, kbDirName, eventBus);
+    this.references = new KbReferenceScanner(workspaceService, disk, kbDirName, eventBus);
     this.fixedAdminEmails = [
       ...new Set(deploymentAdmins.filter(Boolean).map((e) => canonicalEmail(e)).filter(Boolean)),
     ];
@@ -303,23 +312,24 @@ export class RolesAdminService {
 
   // ---- Read -------------------------------------------------------------
 
-  /** The roster: every role on the default branch with members + references. */
-  async getRoster(): Promise<RoleRosterEntry[]> {
+  /**
+   * The roster: every role on the default branch with members + references.
+   * `viewerEmail` is who the roster is for: `referencedBy` names only the
+   * files that viewer can read and omits the rest entirely, without a count —
+   * being an Admin is not read access to every file, and a path, or even a
+   * count of rules in unreadable content, is itself a disclosure.
+   */
+  async getRoster(viewerEmail: string): Promise<RoleRosterEntry[]> {
     const workspaceId = await this.ensureWorkspace();
     const text = await this.readRolesYaml(workspaceId);
     const model = parseRolesModel(text);
     // ONE sound scan of every candidate file (folder access.md + node
     // frontmatter) — cached in the shared scanner, so mutations returning the
     // fresh roster don't rerun the full-KB sweep — indexed by canonical entry
-    // token. Attribution per spelling: a `role/<name>` hit is ALWAYS the
-    // role's; a BARE hit is the role's only when no group shadows the name —
-    // bare tokens resolve group-first, so a shadowed bare grant belongs to the
-    // GROUP (and the groups roster attributes it there — the mirror image).
-    const [referencesByToken, activeGroups] = await Promise.all([
-      this.references.scan(workspaceId),
-      loadActiveGroups((f) => this.locked.readKbFile(workspaceId, f)),
-    ]);
-    const groupOwnedBareNames = new Set(activeGroups.groups.keys());
+    // token. Attribution per spelling: a `role/<name>` hit and a BARE hit are
+    // both the role's — bare names resolve role-first, so a same-named group
+    // is only ever `group/<name>` (the groups roster's mirror image).
+    const referencesByToken = await this.references.scan(workspaceId);
     const out: RoleRosterEntry[] = [];
     for (const role of model) {
       const canonical = canonicalRoleName(role.displayName);
@@ -342,11 +352,18 @@ export class RolesAdminService {
           ? { description: registryEntry.description, groupAssignable: registryEntry.groupAssignable }
           : null,
         referencedBy: [
-          ...(groupOwnedBareNames.has(canonical) ? [] : referencesByToken.get(canonical) ?? []),
+          ...(referencesByToken.get(canonical) ?? []),
           ...(referencesByToken.get(`${ROLE_TOKEN_PREFIX}${canonical}`) ?? []),
         ],
       });
     }
+    const paths = [...new Set(out.flatMap((r) => r.referencedBy.map((ref) => ref.path)))];
+    if (paths.length > 0) {
+      const readable = await this.accessControl.canReadBatch(workspaceId, viewerEmail, paths);
+      for (const r of out) {
+        r.referencedBy = readableReferences(r.referencedBy, readable);
+      }
+    }
     return out;
   }
 
@@ -450,7 +467,7 @@ export class RolesAdminService {
     );
     this.accessControl.invalidate(workspaceId);
     this.emitWrites(workspaceId, actor, [OLD_ROLES_YAML, ROLES_YAML]);
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   // ---- Mutations --------------------------------------------------------
@@ -484,7 +501,7 @@ export class RolesAdminService {
   ): Promise<RoleRosterEntry[]> {
     this.assertNotFixedAdmin(canonical, email);
     await this.runEdit(actor, (text) => editAddMember(text, canonical, email), opts?.aroundWrite);
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -542,7 +559,7 @@ export class RolesAdminService {
       }
       return editRemoveMember(text, canonical, email);
     });
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -572,12 +589,12 @@ export class RolesAdminService {
       }
       await this.runEdit(actor, (text) => editAddGroupRef(text, canonical, groupName));
     });
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   async unassignGroup(actor: AuthUser, canonical: string, groupName: string): Promise<RoleRosterEntry[]> {
     await this.runEdit(actor, (text) => editRemoveGroupRef(text, canonical, groupName));
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -689,7 +706,7 @@ export class RolesAdminService {
     );
     this.accessControl.invalidate(workspaceId);
     this.emitWrites(workspaceId, actor, [ROLES_YAML, GROUPS_YAML]);
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   // ---- Internals --------------------------------------------------------