@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/src/modules/access/access.routes.ts

@@ -17,15 +17,14 @@ import type {
   GrantPrincipal,
   GrantSources,
 } from './access-control.interface.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { KbContext } from '../../shared/kb-context.js';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { AuthService } from '../auth/auth.service.js';
-import type { IAccountSwitchGuard } from '../auth/account-switch-guard.js';
-import type { WorkflowService } from '../workflow/workflow.service.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+import type { AuthService, IAccountSwitchGuard } from '../auth/index.js';
+import type { WorkflowService, WorkflowEventBus } from '../workflow/index.js';
 import { WorkflowDomainError } from '../../shared/domain-errors.js';
-import { AccessDeniedError } from '../access-model/access-errors.js';
+import { AccessDeniedError } from '../access-model/index.js';
 import {
   AccessMutationService,
   AccessMutationError,
@@ -41,19 +40,21 @@ import {
   PLUGIN_TOKEN_PREFIX,
   PLUGIN_TOKEN_VERBS,
   ROLE_TOKEN_PREFIX,
+  GROUP_TOKEN_PREFIX,
+  splitPrincipalToken,
   type PluginTokenVerb,
+  type Principal,
   type Verb,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 import { listAccessDeclarationsUnder } from './access-declarations.js';
 import { emailsInView, holderPrincipals, labelAccountHolders, resolveAccessView } from './access-view.js';
 import type { AccessView, LabelledAccessView } from './access-view.js';
 import { toHttpError as sharedToHttpError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import { RolesAdminService } from './roles-admin.service.js';
-import type { Principal } from '../access-model/access-splice.js';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 import { canonicalEmail } from '../../shared/email-identity.js';
-import '../auth/auth.middleware.js';
+import '../auth/index.js';
 
 /** Verbs the share UI may grant. Verbs are independent — `download` is grantable on its own. */
 const GRANTABLE_VERBS = new Set<string>(['read', 'write', 'owner', 'download']);
@@ -93,6 +94,8 @@ export function createAccessRoutes(
   eventBus: WorkflowEventBus,
   db: Database,
   kb: KbContext,
+  /** The composition root's walk, for the roles admin's reference scan. */
+  disk: ITreeWalker,
   /** This deployment's configured admins — the break-glass recovery roster. */
   recoveryAdmins: readonly string[] = [],
 ): express.Router {
@@ -103,6 +106,7 @@ export function createAccessRoutes(
     workspaceService,
     workflowService,
     accessControl,
+    disk,
     kbDirName,
     () => kb.defaultBranch,
     eventBus,
@@ -163,10 +167,10 @@ export function createAccessRoutes(
   /**
    * What the mutation routes accept as a principal. `group` and `plugin`
    * exist only at this boundary: in the access.md entry grammar a group grant
-   * is a bare-name token (bare names resolve GROUP-FIRST, then fall back to
-   * the role) and a plugin grant is the `plugin/<Name>/<verb>` token, so both
-   * are spliced as role-shaped principals — the separate kinds buy validation
-   * against the right namespace and honest 404s.
+   * is the `group/<Name>` token and a plugin grant is the
+   * `plugin/<Name>/<verb>` token, so both are spliced as role-shaped
+   * principals — the separate kinds buy validation against the right
+   * namespace and honest 404s.
    */
   type RoutePrincipal =
     | Principal
@@ -175,14 +179,16 @@ export function createAccessRoutes(
 
   /**
    * The role-shaped principal the splice layer actually writes/matches.
-   *   - group     → its bare name (group-first precedence resolves it).
-   *   - role      → the explicit `role/<Name>` token — the grant route WRITES
-   *                 roles that way from now on (bare role tokens remain
-   *                 read-compatible). The built-in `everyone` stays bare: it
-   *                 is not a roles.yaml role and has no `role/` alias.
+   *   - group     → the explicit `group/<Name>` token. Never the bare name:
+   *                 a bare name is the ROLE whenever one of that name exists,
+   *                 so a bare group grant could silently mean someone else.
+   *   - role      → the explicit `role/<Name>` token. Bare spellings in
+   *                 existing files remain read-compatible. The built-in
+   *                 `everyone` stays bare: it is not a roles.yaml role and
+   *                 has no `role/` alias.
    */
   const asSplicePrincipal = (p: RoutePrincipal): Principal => {
-    if (p.kind === 'group') return { kind: 'role', role: p.group };
+    if (p.kind === 'group') return { kind: 'role', role: `${GROUP_TOKEN_PREFIX}${groupName(p.group)}` };
     // Written with the folder's own casing; `parseAccessEntry` canonicalises
     // the name half to the manifest slug on the way back in.
     if (p.kind === 'plugin') return { kind: 'role', role: `${PLUGIN_TOKEN_PREFIX}${p.plugin.trim()}/${p.verb}` };
@@ -211,6 +217,14 @@ export function createAccessRoutes(
     return p;
   };
 
+  /** A group as the caller named it, without a `group/` prefix it may carry (casing kept). */
+  function groupName(group: string): string {
+    const raw = group.trim();
+    return splitPrincipalToken(canonicalRoleName(raw)).prefix === 'group'
+      ? raw.slice(GROUP_TOKEN_PREFIX.length).trim()
+      : raw;
+  }
+
   // Authentication gate only. Per PLAN §3 the workspace `:id` is a branch
   // identifier — any authenticated user can read its access tree.
   async function requireUser(
@@ -513,8 +527,8 @@ export function createAccessRoutes(
    * signed in — so the dialog can label them; it withholds nobody.
    *
    * A name shared by a group and a role is offered as BOTH — nothing is
-   * withheld: grant precedence resolves the collision (bare token = the
-   * group; the role is written as `role/<Name>`).
+   * withheld: each is written with its own prefix (`group/<Name>`,
+   * `role/<Name>`), so the collision never reaches the file.
    */
   router.get('/workspace/:id/access/suggest', async (req, res) => {
     const user = await requireUser(req, res);
@@ -950,10 +964,10 @@ export function createAccessRoutes(
         // uses — and one the caller may see (`visibleGroups`): a group hidden
         // from the picker is refused here with the same words as one that
         // does not exist, so the grant route is no oracle for group names.
-        // No role-collision refusal: bare tokens resolve GROUP-FIRST, so the
-        // written bare name IS the group.
+        // No role-collision refusal: the grant is written `group/<Name>`,
+        // which always resolves to the group.
         const groups = await visibleGroups(user.email, (await defaultBranchPrincipals()).groups);
-        const canonical = canonicalRoleName(principal.group);
+        const canonical = canonicalRoleName(groupName(principal.group));
         if (!groups.some((g) => canonicalRoleName(g) === canonical)) {
           throw new AccessMutationError(
             `No group named "${principal.group}". Pick an existing group.`,
@@ -978,8 +992,8 @@ export function createAccessRoutes(
           );
         }
       }
-      // Splice shape: group → bare token (group-first precedence); role →
-      // explicit `role/<Name>` token (see asSplicePrincipal).
+      // Splice shape: group → explicit `group/<Name>` token; role → explicit
+      // `role/<Name>` token (see asSplicePrincipal).
       const splicePrincipal = asSplicePrincipal(principal);
 
       const { gatePath } = gateAndEditPaths(kind, repoRelTarget);
@@ -1047,18 +1061,12 @@ export function createAccessRoutes(
     try {
       const mode = (req.body as { mode?: unknown }).mode;
       const { repoRelTarget, kind, principal: routePrincipal } = parseMutationBody(req.body);
-      // A group principal converts straight to the role-shaped bare token —
-      // no existence check (revoking a grant whose group has since vanished
-      // must keep working).
+      // A group principal converts straight to its `group/<Name>` token — no
+      // existence check (revoking a grant whose group has since vanished must
+      // keep working). Which spellings a revoke strips is the mutation
+      // service's call: `group/<Name>` never matches `role/<Name>`, and the
+      // bare name only when no role of that name owns it.
       const principal = asSplicePrincipal(routePrincipal);
-      // GROUP revokes match the EXACT bare token only. The service's own
-      // shadow probe decides exact-vs-name for roles, but it cannot know a
-      // bare token was a GROUP once that group vanished from the active
-      // source — the name would read "unshadowed" and name-level matching
-      // would strip a same-named role's live `role/<Name>` grant. The route
-      // still knows the caller's kind, so it pins the matching here.
-      const revokeOpts =
-        routePrincipal.kind === 'group' ? ({ tokenMatch: 'exact' } as const) : undefined;
       // Optional `verb` scopes ALL three paths to a single verb: a default revoke
       // strips just that verb; remove-from-parent removes just that verb on the
       // ancestor; deny-here denies just that verb at the target. Absent ⇒ the
@@ -1114,7 +1122,7 @@ export function createAccessRoutes(
             );
           }
           // Scope the ancestor revoke to the same verb the user acted on (if any).
-          await mutation.revoke(workspaceId, 'folder', ancestorDir, principal, user.email, verb, revokeOpts);
+          await mutation.revoke(workspaceId, 'folder', ancestorDir, principal, user.email, verb);
         });
 
         accessControl.invalidate(workspaceId);
@@ -1133,7 +1141,7 @@ export function createAccessRoutes(
         await mutation.assertTargetHoldsText(workspaceId, kind, repoRelTarget);
         await withEditLock(workspaceId, branch, gatePath, user, async () => {
           // Scope the deny to the same verb the user acted on (if any).
-          await mutation.denyHere(workspaceId, kind, repoRelTarget, principal, verb, revokeOpts);
+          await mutation.denyHere(workspaceId, kind, repoRelTarget, principal, verb);
         });
         accessControl.invalidate(workspaceId);
         logger('access.revoke.deny-here').info(
@@ -1152,7 +1160,7 @@ export function createAccessRoutes(
       const editPath = gatePath;
       let changed = false;
       await withEditLock(workspaceId, branch, editPath, user, async () => {
-        const r = await mutation.revoke(workspaceId, kind, repoRelTarget, principal, user.email, verb, revokeOpts);
+        const r = await mutation.revoke(workspaceId, kind, repoRelTarget, principal, user.email, verb);
         changed = r.changed;
       });
 
@@ -1249,7 +1257,7 @@ export function createAccessRoutes(
       // surface). The frontend hides the page, but the API must gate too — the
       // roster exposes every role + member email.
       await assertRolesAdmin(user.email);
-      res.json({ roles: await rolesAdmin.getRoster() });
+      res.json({ roles: await rolesAdmin.getRoster(user.email) });
     } catch (err) {
       const { status, body } = toHttpError(err);
       res.status(status).json(body);

package/src/modules/access/admin-locked-commit.ts

@@ -48,8 +48,9 @@
 import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
-import { LockingFilesystem, type WriteValidator } from '../kb-fs/locking-filesystem.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { type WriteValidator, LockingFilesystem } from '../kb-fs/index.js';
+import type { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
 

package/src/modules/access/capability-registry.ts

@@ -18,7 +18,7 @@
  * really a group; the roles admin surface flags it with a convert action.
  */
 
-import { ADMIN_CANONICAL, canonicalRoleName } from '../access-model/access-grammar.js';
+import { ADMIN_CANONICAL, canonicalRoleName } from '../access-model/index.js';
 
 /** A capability an app surface gates on. Grow this union with the gates. */
 export type Capability =

package/src/modules/access/change-read-gate.ts

@@ -18,12 +18,10 @@ import path from 'node:path';
 import { creatableRootDirNames, type KbLayout } from '@bevel-software/platform-shared';
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { AccessConfigError, AccessDeniedError } from '../access-model/access-errors.js';
-import { SYNCED_GROUPS_YAML } from '../access-model/group-files.js';
-import { toKbRelative } from '../access-model/kb-read-filter.js';
-import type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from '../access-model/change-gate.js';
+import { AccessConfigError, AccessDeniedError, SYNCED_GROUPS_YAML, toKbRelative } from '../access-model/index.js';
+import type { ChangeReadVerdict, ChangeTargetKind, IChangeReadGate } from '../access-model/index.js';
 
 /**
  * Whether `kbRel` (repo-relative) is, or lies inside, a folder directly under

package/src/modules/access/creator-access.ts

@@ -34,17 +34,15 @@ const log = logger('creator-access');
 
 import type { IFsProbe } from '../../shared/fs.contract.js';
 import type { KbContext } from '../../shared/kb-context.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import type { IAccessControl } from './access-control.interface.js';
-import { spliceGrant, type Principal } from '../access-model/access-splice.js';
-import { isAccessMdPath } from '../access-model/access-grammar.js';
-import { toKbRelative } from '../access-model/kb-read-filter.js';
+import { spliceGrant, type Principal, isAccessMdPath, toKbRelative } from '../access-model/index.js';
 import {
   creatorPrincipal,
   type CreationGrantPlan,
   type Creator,
   type ICreatorAccess,
-} from '../access-model/creator.js';
+} from '../access-model/index.js';
 
 export class CreatorAccessService implements ICreatorAccess {
   constructor(

package/src/modules/access/directory-sync-bot.ts

@@ -3,8 +3,8 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
 import type { AuthUser } from '@bevel-software/platform-shared';
-import type { Database } from '../database/connection.js';
-import { users } from '../database/core-schema.js';
+import type { Database } from '../database/index.js';
+import { users } from '../database/index.js';
 
 /**
  * Synthetic identity for the synced-groups materializer's commits: every

package/src/modules/access/groups-admin.routes.ts

@@ -1,10 +1,10 @@
 import express from 'express';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { canonicalRoleName } from '../access-model/access-grammar.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import { canonicalRoleName } from '../access-model/index.js';
 import { sendError as sharedSendError, requireNonEmptyString as sharedRequireNonEmptyString } from './admin-route-helpers.js';
 import type { GroupsAdminService } from './groups-admin.service.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import '../auth/index.js'; // Express Request augmentation
 
 /**
  * Admin surface for GROUPS — the "who you are" half of the roles/groups
@@ -50,9 +50,11 @@ export function createGroupsAdminRoutes(deps: {
   // role assignments) + `groupsHealth` (the broken-source banner marker; a
   // broken MANUAL groups.yaml instead answers 422 with the parse message so
   // the operator sees what to fix).
-  router.get('/admin/groups', requireAdmin, async (_req, res) => {
+  router.get('/admin/groups', requireAdmin, async (req, res) => {
     try {
-      res.json(await groupsAdmin.getRoster());
+      // A read needs no commit attribution: the roster is filtered for the
+      // email `requireAdmin` just checked, with no second user lookup to fail.
+      res.json(await groupsAdmin.getRoster(req.userEmail!));
     } catch (err) {
       sendError(res, err);
     }

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

@@ -12,10 +12,12 @@
  *     provider then; a second write surface would fragment org management —
  *     which is the thing the mode model exists to prevent.
  *   - COLLISION GATE: create/rename refuse a name whose canonical form is a
- *     roles.yaml role. Bare-name precedence would let the group win, but a
- *     deliberately-created shadow of a capability role is far more likely a
- *     mistake than an intent — the IdP can still produce collisions, which
- *     precedence then resolves (group first, `role/<name>` for the role).
+ *     roles.yaml role — a group sharing a role's name is reachable only as
+ *     `group/<name>` and is far more likely a mistake than an intent. The IdP
+ *     (or a hand-edited groups.yaml) can still produce collisions, which
+ *     precedence then resolves: the bare name is the ROLE, `group/<name>` the
+ *     group. The roster names every rule that spells such a group bare
+ *     (`bareNameResolvesToRole`) so an Admin can rewrite it.
  *   - DEGRADE LOUDLY: a broken groups source never fails access resolution
  *     closed — groups contribute nothing and the model carries a
  *     `groupsHealth` marker, which the roster exposes so the Groups & Members page can
@@ -26,19 +28,23 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
+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 {
   GROUP_REF_PREFIX,
+  GROUP_TOKEN_PREFIX,
   canonicalRoleName,
   hasAccessFrontmatterExtension,
-} from '../access-model/access-grammar.js';
+  GROUPS_YAML,
+  SYNCED_GROUPS_YAML,
+  validateGroupsFile,
+  makeRolesYamlWriteValidator,
+} from '../access-model/index.js';
 import { loadActiveGroups, type GroupsHealth } from './access-control.service.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
 import { parseRolesModel, removeGroupRefsEverywhere, renameGroupRefs, isGroupRefMember } from './roles-edit.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
 import {
   GroupsEditError,
   parseGroupsModel,
@@ -50,7 +56,7 @@ import {
   type GroupsEditResult,
 } from './groups-edit.js';
 import { AdminLockedCommits, type LockedWrite } from './admin-locked-commit.js';
-import { KbReferenceScanner } from './reference-scan.js';
+import { KbReferenceScanner, readableReferences, translateRewriteWriteRefusal } from './reference-scan.js';
 
 /** Where role→group assignments live (`group:<canonical>` member entries). */
 const ROLES_YAML = 'roles.yaml';
@@ -70,8 +76,20 @@ export interface GroupRosterEntry {
   canonical: string;
   displayName: string;
   members: string[];
-  /** Every access rule referencing this group — same scan the rename uses. */
+  /**
+   * Every access rule referencing this group — same scan the rename uses —
+   * in a file the roster's viewer can read (see `getRoster`).
+   */
   referencedBy: { path: string; verb: string }[];
+  /**
+   * The access rules that name this group's name BARE while a ROLE of the same
+   * name exists. A bare name is the role, so these rules grant the role, not
+   * this group — rules written while bare names still meant the group change
+   * meaning here. An Admin rewrites each as `group/<Name>` if the group was
+   * meant. Empty when no role shares the name. Only files the roster's
+   * viewer can read are listed (see `getRoster`).
+   */
+  bareNameResolvesToRole: { path: string; verb: string }[];
   /**
    * Canonical names of roles carrying a `group:<canonical>` assignment to
    * this group — so the delete confirm can warn that those roles will lose
@@ -102,6 +120,8 @@ export class GroupsAdminService {
     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,
     /** Live-binding thunk — see RolesAdminService's identical note. */
     private readonly defaultBranchOf: () => string,
@@ -122,7 +142,7 @@ export class GroupsAdminService {
     // 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);
   }
 
   private get defaultBranch(): string {
@@ -167,8 +187,13 @@ export class GroupsAdminService {
    *     fallback to manual, which would resurrect retired groups).
    *   - Manual mode, broken groups.yaml: 422 with the parse message — the
    *     repair path must show the operator what to fix, never a dead page.
+   *
+   * `viewerEmail` is who the roster is for: `referencedBy` and
+   * `bareNameResolvesToRole` name only the files that viewer can read. Being
+   * an Admin is not read access to every file, and a path is itself a
+   * disclosure.
    */
-  async getRoster(): Promise<GroupsRoster> {
+  async getRoster(viewerEmail: string): Promise<GroupsRoster> {
     const workspaceId = await this.ensureWorkspace();
     const active = await loadActiveGroups((f) => this.locked.readKbFile(workspaceId, f));
     if (active.sourceFile === GROUPS_YAML && !active.health.ok) {
@@ -178,7 +203,7 @@ export class GroupsAdminService {
         reason: active.health.reason,
       });
     }
-    const [referencesByToken, assignedByGroup] = await Promise.all([
+    const [referencesByToken, { byGroup: assignedByGroup, roles }] = await Promise.all([
       this.references.scan(workspaceId),
       this.rolesReferencingGroups(workspaceId),
     ]);
@@ -191,19 +216,44 @@ export class GroupsAdminService {
         // IdP members render sorted (machine-generated file, no author order
         // to honour); manual members keep file order (the editor's view).
         members: mode === 'idp' ? [...def.emails].sort() : [...def.emails],
-        // A group's references are its BARE-token hits, unconditionally: this
-        // group exists in the active source, so under group-first precedence
-        // it owns the bare key — even when a role shares the name (the roles
-        // roster is the mirror image: it then skips the bare hits and counts
-        // only `role/<name>`). Explicit `role/<name>` hits are never a group
+        // A group's references are its `group/<name>` hits, plus its BARE
+        // hits while no role shares the name — a bare name is the role when
+        // one exists (the roles roster is the mirror image: it counts the
+        // bare hits then). Explicit `role/<name>` hits are never a group
         // reference.
-        referencedBy: referencesByToken.get(canonical) ?? [],
+        referencedBy: [
+          ...(referencesByToken.get(`${GROUP_TOKEN_PREFIX}${canonical}`) ?? []),
+          ...(roles.has(canonical) ? [] : referencesByToken.get(canonical) ?? []),
+        ],
+        bareNameResolvesToRole: roles.has(canonical) ? referencesByToken.get(canonical) ?? [] : [],
         assignedToRoles: assignedByGroup.get(canonical) ?? [],
       });
     }
+    await this.keepReadableReferences(workspaceId, viewerEmail, groups);
     return { mode, groups, groupsHealth: active.health };
   }
 
+  /**
+   * Drop every `referencedBy` and `bareNameResolvesToRole` row whose file the
+   * viewer cannot read. Dropped, not counted: Admin status does not grant
+   * read, so a count of rules in unreadable content would be a disclosure.
+   */
+  private async keepReadableReferences(
+    workspaceId: string,
+    viewerEmail: string,
+    groups: GroupRosterEntry[],
+  ): Promise<void> {
+    const paths = [
+      ...new Set(groups.flatMap((g) => [...g.referencedBy, ...g.bareNameResolvesToRole].map((r) => r.path))),
+    ];
+    if (paths.length === 0) return;
+    const readable = await this.accessControl.canReadBatch(workspaceId, viewerEmail, paths);
+    for (const g of groups) {
+      g.referencedBy = readableReferences(g.referencedBy, readable);
+      g.bareNameResolvesToRole = readableReferences(g.bareNameResolvesToRole, readable);
+    }
+  }
+
   /**
    * Display names from the ACTIVE group source (synced in IdP mode, manual
    * otherwise). Malformed files degrade to an empty list, matching the
@@ -231,7 +281,7 @@ export class GroupsAdminService {
     await this.assertManualMode(await this.ensureWorkspace());
     await this.assertRoleNameFree(displayName);
     await this.runEdit(actor, (text) => editCreateGroup(text, displayName));
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -281,17 +331,17 @@ export class GroupsAdminService {
       );
       this.afterWrite(workspaceId, actor, files.map((f) => f.repoRel));
     });
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   async addMember(actor: AuthUser, canonical: string, email: string): Promise<GroupsRoster> {
     await this.runEdit(actor, (text) => editAddMember(text, canonical, email));
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   async removeMember(actor: AuthUser, canonical: string, email: string): Promise<GroupsRoster> {
     await this.runEdit(actor, (text) => editRemoveMember(text, canonical, email));
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -311,7 +361,7 @@ export class GroupsAdminService {
     await this.locked.withFileLocks(workspaceId, actor, [GROUPS_YAML, ROLES_YAML], () =>
       this.renameGroupLocked(workspaceId, actor, canonical, newCanonical, newDisplayName),
     );
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   private async renameGroupLocked(
@@ -329,16 +379,20 @@ export class GroupsAdminService {
       files.push({ repoRel: GROUPS_YAML, content: groupsEdit.text, original: text });
     }
     if (newCanonical !== canonical) {
-      // Grant references (bare tokens in access.md + node frontmatter). The
-      // rewrite returns each file's ORIGINAL text alongside the new content,
-      // so the rollback snapshots reuse the read it already did — no second
-      // full-KB pass. Explicit `role/<name>` tokens are untouched by design:
-      // they reference the ROLE, not this group.
+      // Grant references (`group/<name>` tokens in access.md + node
+      // frontmatter, and the bare name while no role owns it), rewritten to
+      // the explicit `group/<New Name>`. The rewrite returns each file's
+      // ORIGINAL text alongside the new content, so the rollback snapshots
+      // reuse the read it already did — no second full-KB pass. Explicit
+      // `role/<name>` tokens, and a bare name a role owns, are untouched by
+      // design: they reference the ROLE, not this group.
+      const { roles } = await this.rolesReferencingGroups(workspaceId);
       const refWrites = await this.references.rewriteReferences(
         workspaceId,
-        canonical,
-        newDisplayName.trim(),
+        [`${GROUP_TOKEN_PREFIX}${canonical}`, ...(roles.has(canonical) ? [] : [canonical])],
+        `${GROUP_TOKEN_PREFIX}${newDisplayName.trim()}`,
         (message, cause) => new GroupsAdminError(message, 422, { cause }),
+        (paths) => this.accessControl.canReadBatch(workspaceId, actor.email, paths),
       );
       for (const w of refWrites) {
         files.push({ repoRel: w.repoRelativePath, content: w.content, original: w.original });
@@ -374,12 +428,22 @@ export class GroupsAdminService {
     // Roster locks are already ours (withFileLocks; strict same-user acquire
     // forbids LockingFilesystem here). Grant-reference candidates are written
     // unlocked — same exposure every reference rewrite has always had.
-    await this.locked.writeAndCommitLocked(
-      workspaceId,
-      actor,
-      files,
-      `Rename group ${canonical} → ${newDisplayName.trim()}`,
-    );
+    // The commit gates every file on the actor's write rules and restores all
+    // of them on a refusal; a refused file the actor may not read goes unnamed.
+    try {
+      await this.locked.writeAndCommitLocked(
+        workspaceId,
+        actor,
+        files,
+        `Rename group ${canonical} → ${newDisplayName.trim()}`,
+      );
+    } catch (err) {
+      throw await translateRewriteWriteRefusal(
+        err,
+        (paths) => this.accessControl.canReadBatch(workspaceId, actor.email, paths),
+        (message) => new GroupsAdminError(message, 422),
+      );
+    }
     this.afterWrite(workspaceId, actor, files.map((f) => f.repoRel));
   }
 
@@ -442,12 +506,12 @@ export class GroupsAdminService {
   }
 
   /**
-   * Refuse a group name that IS a role. Bare-name precedence (group-first)
-   * would make the group win resolution, so this is deliberate FRICTION, not
-   * a correctness need: an admin naming a group after a capability role is
-   * far more likely shadowing by accident than by intent. IdP-sourced
-   * collisions still happen (the sync writer doesn't consult roles.yaml) and
-   * precedence resolves them.
+   * Refuse a group name that IS a role. Bare-name precedence (role-first)
+   * keeps the role safe either way, so this is deliberate FRICTION, not a
+   * correctness need: a group named after a role is reachable only as
+   * `group/<name>`, which is far more likely a surprise than an intent.
+   * IdP-sourced collisions still happen (the sync writer doesn't consult
+   * roles.yaml) and precedence resolves them.
    */
   private async assertRoleNameFree(displayName: string): Promise<void> {
     const workspaceId = await this.ensureWorkspace();
@@ -463,7 +527,7 @@ export class GroupsAdminService {
     }
     if (roles.some((r) => canonicalRoleName(r.displayName) === canonical)) {
       throw new GroupsAdminError(
-        `'${displayName.trim()}' is a role name — name the group something else (a role can be referenced explicitly as 'role/${canonical}').`,
+        `'${displayName.trim()}' is a role name — name the group something else (in access rules the bare name '${displayName.trim()}' means the role).`,
         422,
       );
     }
@@ -474,17 +538,22 @@ export class GroupsAdminService {
    * Advisory (feeds the roster's `assignedToRoles` warning field): a broken
    * roles.yaml yields an empty map rather than failing the roster.
    */
-  private async rolesReferencingGroups(workspaceId: string): Promise<Map<string, string[]>> {
+  private async rolesReferencingGroups(
+    workspaceId: string,
+  ): Promise<{ byGroup: Map<string, string[]>; roles: Set<string> }> {
     const rolesText = (await this.locked.readKbFile(workspaceId, ROLES_YAML)) ?? '';
     const byGroup = new Map<string, string[]>();
+    // Every role's canonical name — who owns a bare name (role-first).
+    const roleNames = new Set<string>();
     let roles;
     try {
       roles = parseRolesModel(rolesText);
     } catch {
-      return byGroup;
+      return { byGroup, roles: roleNames };
     }
     for (const role of roles) {
       const roleCanonical = canonicalRoleName(role.displayName);
+      roleNames.add(roleCanonical);
       for (const member of role.members) {
         if (!isGroupRefMember(member)) continue;
         const groupCanonical = canonicalRoleName(member.slice(GROUP_REF_PREFIX.length));
@@ -496,7 +565,7 @@ export class GroupsAdminService {
         }
       }
     }
-    return byGroup;
+    return { byGroup, roles: roleNames };
   }
 
   private async runEdit(actor: AuthUser, pre: (text: string) => GroupsEditResult): Promise<void> {