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

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

@@ -36,19 +36,25 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('roles.recover');
-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 {
   ADMIN_CANONICAL,
   ROLE_TOKEN_PREFIX,
   canonicalRoleName,
   canonicalEmail,
-} from '../access-model/access-grammar.js';
+  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 } from '../access-model/roles-yaml-guard.js';
-import { renderRolesYaml } from '../access-model/render-roles-yaml.js';
 import {
   parseRolesModel,
   deleteRole as editDeleteRole,
@@ -60,7 +66,6 @@ import {
   RolesEditError,
   type EditResult,
 } from './roles-edit.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
 import {
   GroupsEditError,
   assertSafeGroupDisplayName,
@@ -68,9 +73,8 @@ import {
   parseGroupsModel,
 } from './groups-edit.js';
 import { capabilityRoleFor, isLegacyPeopleSetRole } from './capability-registry.js';
-import { GROUP_REF_PREFIX, RESERVED_ROLE_NAMES } from '../access-model/access-grammar.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 {
@@ -121,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 }[];
 }
@@ -183,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
@@ -226,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)),
     ];
@@ -306,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);
@@ -345,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;
   }
 
@@ -453,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 --------------------------------------------------------
@@ -487,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);
   }
 
   /**
@@ -545,7 +559,7 @@ export class RolesAdminService {
       }
       return editRemoveMember(text, canonical, email);
     });
-    return this.getRoster();
+    return this.getRoster(actor.email);
   }
 
   /**
@@ -575,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);
   }
 
   /**
@@ -692,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 --------------------------------------------------------

package/src/modules/access/roles-edit.ts

@@ -39,7 +39,7 @@ import {
   canonicalEmail,
   EMAIL_REGEX,
   GROUP_REF_PREFIX,
-} from '../access-model/access-grammar.js';
+} from '../access-model/index.js';
 
 /** Bad-input failure when editing roles.yaml (invalid name/email, unknown role). */
 export class RolesEditError extends Error {

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

@@ -3,12 +3,12 @@ import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
-import { SYNCED_GROUPS_YAML } from '../access-model/group-files.js';
-import type { WorkflowEventBus } from '../workflow/event-bus.js';
-import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
+import { SYNCED_GROUPS_YAML } from '../access-model/index.js';
+import type { WorkflowEventBus } from '../workflow/index.js';
+import { LockingFilesystem } from '../kb-fs/index.js';
 import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';

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

@@ -4,8 +4,8 @@ import {
   canonicalEmail,
   canonicalRoleName,
   RESERVED_ROLE_NAMES,
-} from '../access-model/access-grammar.js';
-import { unsafeNameReason } from '../access-model/group-files.js';
+} from '../access-model/index.js';
+import { unsafeNameReason } from '../access-model/index.js';
 import { printable } from '../../shared/printable.js';
 
 /**
@@ -72,7 +72,7 @@ export interface SyncedGroupsSource {
 
 // Name safety is the SHARED predicate in `group-files.ts` (`unsafeNameReason`)
 // — the same rules the manual group editor asserts, including the reserved
-// `role/` prefix. Here the name arrives from the IdP, so an unsafe group is
+// `role/` and `group/` prefixes. Here the name arrives from the IdP, so an unsafe group is
 // SKIPPED with a warning instead of erroring (fail-closed: an unrepresentable
 // group grants nothing).
 

package/src/modules/access/user-access-removal.service.ts

@@ -37,7 +37,7 @@
  */
 
 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 { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
 import type { IAccessControl } from './access-control.interface.js';
@@ -55,11 +55,8 @@ import {
   stripComment,
   type ParsedEntry,
   type Verb,
-} from '../access-model/access-grammar.js';
-import { spliceRevoke } from '../access-model/access-splice.js';
-import { scanFrontmatter } from '../access-model/frontmatter-lines.js';
-import { GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile } from '../access-model/group-files.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
+} from '../access-model/index.js';
+import { spliceRevoke, scanFrontmatter, GROUPS_YAML, SYNCED_GROUPS_YAML, validateGroupsFile, makeRolesYamlWriteValidator } from '../access-model/index.js';
 import { emitRolesModel, isGroupRefMember, parseRolesModel } from './roles-edit.js';
 import { emitGroupsModel, parseGroupsModel } from './groups-edit.js';
 import { AdminLockedCommits, type LockedWrite } from './admin-locked-commit.js';

package/src/modules/access-model/__tests__/access-grammar.test.ts

@@ -6,8 +6,44 @@ import {
   accessFrontmatterExtensionList,
   parseOwnAccessEntries,
   parseRolesYaml,
+  parseAccessEntry,
+  mergeGroupsIntoRoles,
 } from '../access-grammar.js';
-import { parseGroupsFile } from '../group-files.js';
+import { parseGroupsFile, unsafeNameReason } from '../group-files.js';
+
+describe('principal spellings — a bare name is the role, group/<Name> the group', () => {
+  it('parses group/<Name> into the canonical group token, spacing normalised', () => {
+    const r = parseAccessEntry('group/ Product  Team');
+    expect(r).toEqual({ ok: true, entry: { kind: 'role', role: 'group/product team', displayRole: 'group/ Product  Team', deny: false } });
+    const d = parseAccessEntry('deny group/Admin');
+    expect(d.ok && d.entry.kind === 'role' && d.entry.role).toBe('group/admin');
+    expect(parseAccessEntry('group/').ok).toBe(false);
+  });
+
+  it('reserves the group/ prefix for roles and groups alike', () => {
+    const roles = parseRolesYaml('roles:\n  Admin:\n    - a@x.io\n  group/Ops:\n    - b@x.io\n');
+    expect(roles.ok).toBe(false);
+    if (!roles.ok) expect(roles.errors.join(' ')).toMatch(/reserved 'group\/' prefix/);
+    expect(unsafeNameReason('group/Ops')).toMatch(/group\//);
+  });
+
+  it('merging keeps the bare key for the role and registers group/ for every group', () => {
+    const parsed = parseRolesYaml('roles:\n  Admin:\n    - admin@x.io\n');
+    if (!parsed.ok) throw new Error('roles');
+    const groups = parseGroupsFile('groups:\n  Admin:\n    - mallory@x.io\n  Sales:\n    - sam@x.io\n', 'groups.yaml');
+    if (!groups.ok) throw new Error('groups');
+    const warnings = mergeGroupsIntoRoles(parsed.index, groups.groups, 'groups.yaml');
+    const idx = parsed.index.byCanonical;
+    expect(idx.get('admin')?.kind).toBe('role');
+    expect(idx.get('role/admin')).toBe(idx.get('admin'));
+    expect(idx.get('group/admin')?.kind).toBe('group');
+    expect(idx.get('sales')?.kind).toBe('group');
+    expect(idx.get('group/sales')).toBe(idx.get('sales'));
+    // The group's member holds only the group's keys, never the role's.
+    expect([...(parsed.index.byEmail.get('mallory@x.io') ?? [])]).toEqual(['group/admin']);
+    expect(warnings.join(' ')).toMatch(/resolves to the ROLE; use 'group\/admin'/);
+  });
+});
 
 describe('parseYamlSubset — inline empty collections', () => {
   it('reads `key: []` as an empty list, not the scalar "[]"', () => {
@@ -103,6 +139,7 @@ describe('the access-frontmatter extension set', () => {
     expect(accessFrontmatterExtensionList()).toHaveLength(after);
     expect(accessFrontmatterExtensionList()).toContain('.md');
     expect(accessFrontmatterExtensionList()).toContain('.tool');
+    expect(accessFrontmatterExtensionList()).not.toContain('.agent');
   });
 
   it('throws on a malformed extension rather than skipping it', () => {

package/src/modules/access-model/__tests__/access-splice.test.ts

@@ -302,12 +302,13 @@ describe('round-trip — every granted entry parses back', () => {
   });
 });
 
-describe('token-kind family — exact-token grants, shadow-aware revokes', () => {
-  // One name, two spellings, two possible principals: the bare token is the
-  // GROUP's whenever a group shadows the name (group-first precedence), the
-  // `role/` token is always the ROLE's. Grants must be exact-token idempotent;
-  // revokes are alias-tolerant ONLY when unshadowed (the caller passes
-  // tokenMatch: 'exact' when a group owns the bare name).
+describe('token-kind family — exact-token grants, kind-aware revokes', () => {
+  // One name, three spellings, two possible principals: `role/` is always the
+  // ROLE's, `group/` always the GROUP's, and the bare token is the role's when
+  // one exists, else the group's. Grants must be exact-token idempotent;
+  // revokes are alias-tolerant (explicit + bare, never the other kind's
+  // explicit spelling) only when the bare name is the principal's — the
+  // caller passes tokenMatch: 'exact' otherwise.
   const SHARED = `---
 write:
   - role/Sales
@@ -360,10 +361,51 @@ write:
     expect(lines).not.toContain('  - Sales');
   });
 
-  it("REVOKE unshadowed bare principal (group since vanished): 'name' matching strips both spellings", () => {
+  it("REVOKE bare principal: 'name' matching strips both role spellings", () => {
     const r = spliceRevoke(SHARED, 'write', { kind: 'role', role: 'Sales' });
     expect(r.changed).toBe(true);
-    expect(r.text).not.toContain('Sales'); // bare token falls back to the role — same principal
+    expect(r.text).not.toContain('Sales'); // the bare token is the role — same principal
+  });
+
+  const ALL = `---
+write:
+  - role/Sales
+  - Sales
+  - group/Sales
+  - Admin
+---
+`;
+
+  it('GRANT is exact-token: a group/<Name> grant goes through beside the bare and role/ spellings', () => {
+    const md = '---\nwrite:\n  - role/Sales\n  - Sales\n---\n';
+    const r = spliceGrant(md, 'write', { kind: 'role', role: 'group/Sales' });
+    expect(r.changed).toBe(true);
+    expect(r.text.split('\n')).toContain('  - group/Sales');
+    expect(spliceGrant(ALL, 'write', { kind: 'role', role: 'group/Sales' }).changed).toBe(false);
+  });
+
+  it("REVOKE 'name' never crosses kinds: the role's revoke keeps group/, the group's keeps role/", () => {
+    const asRole = spliceRevoke(ALL, 'write', { kind: 'role', role: 'role/Sales' });
+    expect(asRole.text.split('\n')).toEqual(['---', 'write:', '  - group/Sales', '  - Admin', '---', '']);
+
+    // The service asks 'name' for a GROUP only while no role shares the name
+    // (with one, as in ALL, it picks 'exact' — the last test below), so the
+    // group's case is a file where the bare token can only be the group.
+    const GROUP_ONLY = '---\nwrite:\n  - Sales\n  - group/Sales\n  - Admin\n---\n';
+    const asGroup = spliceRevoke(GROUP_ONLY, 'write', { kind: 'role', role: 'group/Sales' });
+    expect(asGroup.text.split('\n')).toEqual(['---', 'write:', '  - Admin', '---', '']);
+  });
+
+  it('REVOKE matches a spaced `group/ <Name>` request against the parsed `group/<name>` entry', () => {
+    const r = spliceRevoke(ALL, 'write', { kind: 'role', role: 'group/ Sales' }, { tokenMatch: 'exact' });
+    expect(r.text.split('\n')).toEqual(['---', 'write:', '  - role/Sales', '  - Sales', '  - Admin', '---', '']);
+    const md = '---\nwrite:\n  - group/ Sales\n---\n';
+    expect(spliceRevoke(md, 'write', { kind: 'role', role: 'group/Sales' }).changed).toBe(true);
+  });
+
+  it("REVOKE 'exact' of group/<Name> strips only that spelling", () => {
+    const r = spliceRevoke(ALL, 'write', { kind: 'role', role: 'group/Sales' }, { tokenMatch: 'exact' });
+    expect(r.text.split('\n')).toEqual(['---', 'write:', '  - role/Sales', '  - Sales', '  - Admin', '---', '']);
   });
 });
 

package/src/modules/access-model/access-grammar.ts

@@ -92,14 +92,47 @@ export const DENY_PREFIX = 'deny ';
 export const GROUP_REF_PREFIX = 'group:';
 /**
  * Explicit ROLE token prefix in access.md entries: `role/<Name>` resolves to
- * the roles.yaml role only, never a group. A BARE name resolves GROUP-FIRST
- * and falls back to the role — so `role/` is the escape hatch when a group
- * shares the role's name. The prefix is reserved in the group name-safety
- * rules (a group may never be named `role/...`), and every role is also
- * registered in the principal index under its `role/<canonical>` alias.
+ * the roles.yaml role only, never a group. A BARE name resolves ROLE-FIRST
+ * and falls back to the group, so a group that shares a role's name is
+ * reached only as `group/<Name>` (see `GROUP_TOKEN_PREFIX`) — a group named
+ * `Admin` never takes over the grants written for the Admin role. The prefix
+ * is reserved in the group name-safety rules (a group may never be named
+ * `role/...`), and every role is also registered in the principal index under
+ * its `role/<canonical>` alias.
  */
 export const ROLE_TOKEN_PREFIX = 'role/';
 
+/**
+ * Explicit GROUP token prefix in access.md entries: `group/<Name>` resolves
+ * to the active source's group only, never a role. Every group is registered
+ * in the principal index under its `group/<canonical>` alias; the bare name
+ * reaches the group only while no role of that name exists. The share dialog
+ * and the access API always write groups this way. Reserved in the group
+ * name-safety rules and in roles.yaml like `role/`.
+ */
+export const GROUP_TOKEN_PREFIX = 'group/';
+
+/**
+ * A canonical role-shaped token split into its explicit kind prefix and its
+ * bare name: `role/admin` → `{ prefix: 'role', name: 'admin' }`, `group/admin`
+ * → `{ prefix: 'group', name: 'admin' }`, anything else (a bare name, a
+ * plugin token, `everyone`) → `{ prefix: null, name: <token> }`. A prefixed
+ * name is canonicalised again, so `group/ admin` splits like `group/admin`
+ * (as `parseAccessEntry` reads it).
+ */
+export function splitPrincipalToken(canonical: string): {
+  prefix: 'role' | 'group' | null;
+  name: string;
+} {
+  if (canonical.startsWith(ROLE_TOKEN_PREFIX)) {
+    return { prefix: 'role', name: canonicalRoleName(canonical.slice(ROLE_TOKEN_PREFIX.length)) };
+  }
+  if (canonical.startsWith(GROUP_TOKEN_PREFIX)) {
+    return { prefix: 'group', name: canonicalRoleName(canonical.slice(GROUP_TOKEN_PREFIX.length)) };
+  }
+  return { prefix: null, name: canonical };
+}
+
 /**
  * PLUGIN-principal token prefix in access.md entries: `plugin/<Name>/<verb>`
  * names everyone who holds `<verb>` on the plugin folder `Plugins/<Name>` —
@@ -585,6 +618,11 @@ export function parseAccessEntry(
     const suffix = canonicalRoleName(role.slice(ROLE_TOKEN_PREFIX.length));
     if (!suffix) return { ok: false, error: `entry '${body}' names no role after '${ROLE_TOKEN_PREFIX}'` };
     role = `${ROLE_TOKEN_PREFIX}${suffix}`;
+  } else if (role.startsWith(GROUP_TOKEN_PREFIX)) {
+    // Explicit group token, normalised the same way to `group/<canonicalName>`.
+    const suffix = canonicalRoleName(role.slice(GROUP_TOKEN_PREFIX.length));
+    if (!suffix) return { ok: false, error: `entry '${body}' names no group after '${GROUP_TOKEN_PREFIX}'` };
+    role = `${GROUP_TOKEN_PREFIX}${suffix}`;
   } else if (role.startsWith(PLUGIN_TOKEN_PREFIX)) {
     // `plugin/<Name>/<verb>`: the name is canonicalised to the plugin's
     // manifest slug, the verb must be one of the three. Anything else is a
@@ -649,6 +687,12 @@ export function parseRolesYaml(
       );
       continue;
     }
+    if (canonical.startsWith(GROUP_TOKEN_PREFIX)) {
+      errors.push(
+        `roles.yaml: role '${displayName}' starts with the reserved '${GROUP_TOKEN_PREFIX}' prefix — that spelling is the explicit group token in access entries`,
+      );
+      continue;
+    }
     // A role spelled `plugin/…` would be overwritten by the synthesised plugin
     // principal of the same key while its members kept the token — plugin
     // access for people who are not plugin members. Refused at parse time,
@@ -730,15 +774,17 @@ export function parseRolesYaml(
  *
  * Rules (the grant-grammar precedence):
  *   - Every role is ALSO registered under its explicit `role/<canonical>`
- *     alias — the token that always resolves to the role.
- *   - A BARE name resolves GROUP-FIRST: when a group's canonical name
- *     collides with a role's, the bare key resolves to the GROUP (warned);
- *     the role stays reachable via `role/<canonical>`.
+ *     alias, and every group under its explicit `group/<canonical>` alias —
+ *     the tokens that always resolve to that kind.
+ *   - A BARE name resolves ROLE-FIRST: when a group's canonical name
+ *     collides with a role's, the bare key stays the ROLE's (warned); the
+ *     group is reachable only via `group/<canonical>`. So a group named
+ *     `Admin` — whoever proposed it — never gains what `Admin` is granted.
  *   - Role `group:<Name>` refs — Admin's included — expand against the
  *     merged groups; an unknown ref contributes nothing (warned).
  *   - `byEmail` is rebuilt so each member holds exactly the tokens that
  *     resolve to a principal they belong to (bare + `role/` alias for roles,
- *     bare for groups).
+ *     `group/` alias plus the bare name when the group owns it for groups).
  */
 export function mergeGroupsIntoRoles(
   index: RolesIndex,
@@ -765,19 +811,18 @@ export function mergeGroupsIntoRoles(
     }
   }
 
-  // 2. Bare-name precedence: groups win the bare token; the role keeps its
-  //    `role/<canonical>` alias registered below.
+  // 2. Bare-name precedence: roles keep the bare token; every group gets its
+  //    `group/<canonical>` alias, and the bare key only when no role owns it.
   for (const [canonical, def] of groups) {
+    const group = { displayName: def.displayName, emails: new Set(def.emails), kind: 'group' as const };
+    index.byCanonical.set(`${GROUP_TOKEN_PREFIX}${canonical}`, group);
     if (roleRecords.has(canonical)) {
       warnings.push(
-        `${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name now resolves to the GROUP; use '${ROLE_TOKEN_PREFIX}${canonical}' to reference the role`,
+        `${sourceFile}: group '${def.displayName}' shares its name with a role — the bare name resolves to the ROLE; use '${GROUP_TOKEN_PREFIX}${canonical}' to reference the group`,
       );
+      continue;
     }
-    index.byCanonical.set(canonical, {
-      displayName: def.displayName,
-      emails: new Set(def.emails),
-      kind: 'group',
-    });
+    index.byCanonical.set(canonical, group);
   }
 
   // 3. Explicit `role/<canonical>` alias for every role (same record — the
@@ -788,8 +833,8 @@ export function mergeGroupsIntoRoles(
   }
 
   // 4. Rebuild the email → tokens map from the final index so membership
-  //    reflects the post-precedence keys (a collided role's members no longer
-  //    hold the bare token unless the group also contains them).
+  //    reflects the post-precedence keys (a collided group's members hold
+  //    only its `group/` alias, never the role's bare token).
   index.byEmail.clear();
   for (const [key, principal] of index.byCanonical) {
     for (const email of principal.emails) {

package/src/modules/access-model/access-splice.ts

@@ -33,6 +33,7 @@ import {
   canonicalEmail,
   canonicalRoleName,
   accessMdDeclaresBodyRules,
+  splitPrincipalToken,
 } from './access-grammar.js';
 import { freshAccessMd } from './access-template.js';
 import { scanFrontmatter } from './frontmatter-lines.js';
@@ -149,15 +150,18 @@ export function validatePrincipal(p: Principal): Principal {
 /**
  * How a role-shaped principal's TOKEN is compared against a file entry:
  *
- *  - `'exact'`: the entry must carry the SAME spelling — a bare token and a
- *    `role/<name>` token are DIFFERENT principals (bare = whoever owns the
- *    bare key under group-first precedence, `role/` = the role). Grants
- *    always use this: granting the group `X` while `role/X` is present (or
- *    vice versa) must NOT be treated as already-granted, or the other
- *    principal silently never receives the grant.
- *  - `'name'`: both spellings of the name match. Revokes use this ONLY when
- *    no group shadows the bare name — then both spellings resolve to the
- *    role, and revoking the role must also remove legacy bare spellings.
+ *  - `'exact'`: the entry must carry the SAME spelling — a bare token, a
+ *    `role/<name>` token and a `group/<name>` token can be DIFFERENT
+ *    principals (bare = the role when one exists, else the group). Grants
+ *    always use this: granting `group/X` while `role/X` or a bare `X` is
+ *    present must NOT be treated as already-granted, or the group silently
+ *    never receives the grant.
+ *  - `'name'`: the principal's explicit spelling AND the bare name match —
+ *    `role/X` (or a bare `X`) matches `X` and `role/X`; `group/X` matches
+ *    `X` and `group/X`. Never across kinds: a role's revoke never touches
+ *    `group/X`, a group's never `role/X`. Revokes use this only when the
+ *    bare name is this principal's (AccessMutationService decides), so
+ *    revoking also removes the legacy bare spelling.
  */
 export type TokenMatch = 'exact' | 'name';
 
@@ -169,11 +173,14 @@ export type TokenMatch = 'exact' | 'name';
 function entryMatches(entry: ParsedEntry, p: Principal, tokenMatch: TokenMatch): boolean {
   if (p.kind === 'user') return entry.kind === 'user' && entry.email === canonicalEmail(p.email);
   if (entry.kind !== 'role') return false;
-  const canonicalPrincipal = canonicalRoleName(p.role);
-  if (tokenMatch === 'exact') return entry.role === canonicalPrincipal;
-  const strip = (token: string): string =>
-    token.startsWith('role/') ? canonicalRoleName(token.slice('role/'.length)) : token;
-  return strip(entry.role) === strip(canonicalPrincipal);
+  // Compare split, canonical halves: `group/ Product` in the request names the
+  // same principal as the `group/product` the parser reads from the file.
+  const own = splitPrincipalToken(canonicalRoleName(p.role));
+  const theirs = splitPrincipalToken(entry.role);
+  if (theirs.name !== own.name) return false;
+  if (tokenMatch === 'exact') return theirs.prefix === own.prefix;
+  // Same family only: a bare principal stands for the role, as `role/` does.
+  return theirs.prefix === null || theirs.prefix === (own.prefix ?? 'role');
 }
 
 // ---------------------------------------------------------------------------
@@ -344,10 +351,10 @@ function blockEntries(fm: string[], block: VerbBlock): { entry: ParsedEntry; lin
  * Add `principal` under `verb`. Idempotent: if an entry with the EXACT same
  * token spelling already exists with the SAME deny-ness (a grant when
  * granting, a deny when denying), returns `changed: false`. Idempotency is
- * deliberately exact-token, never name-level: a bare token and a `role/`
- * token are different principals (group-first precedence gives the bare key
- * to a same-named group), so a bare-`X` GROUP grant must go through even when
- * `role/X` is present, and vice versa. Creates the verb key (and the
+ * deliberately exact-token, never name-level: a bare token, a `role/` token
+ * and a `group/` token can be different principals (the bare key is the
+ * role's when one exists), so a `group/X` grant must go through even when a
+ * bare `X` or `role/X` is present, and vice versa. Creates the verb key (and the
  * frontmatter fence, for a fresh file) as needed. Preserves everything else
  * byte-for-byte.
  *
@@ -445,11 +452,12 @@ export function spliceGrant(
  * Preserves everything else.
  *
  * Token matching for role-shaped principals is `tokenMatch` (default `'name'`:
- * BOTH spellings — revoking the role removes legacy bare spellings too).
- * Callers pass `'exact'` when a GROUP shadows the principal's bare name: the
- * bare token then belongs to the group and the `role/` token to the role, so a
- * revoke of one must never strip the other (see AccessMutationService, which
- * derives the flag from the merged principal index).
+ * the explicit spelling and the bare one — revoking removes legacy bare
+ * spellings too). Callers pass `'exact'` when the bare name belongs to the
+ * OTHER kind (a group revoke while a same-named role owns the bare key, or a
+ * role revoke while only a group of that name exists), so a revoke of one
+ * never strips the other (see AccessMutationService, which derives the flag
+ * from the merged principal index).
  */
 export function spliceRevoke(
   text: string,