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

package/src/modules/access/__tests__/access-control.group-named-admin.test.ts

@@ -0,0 +1,122 @@
+/**
+ * QA reproduction (v0.28.0 hunt, decisions #312/#315): a Business user's
+ * agent proposed a group named `Admin` in groups.yaml, an Admin approved the
+ * change request, and every member of the group then received the Admin
+ * role's grants wherever an access rule said `Admin` — because a bare name
+ * meant the GROUP when a group and a role shared it.
+ *
+ * The rule now: a bare name means the ROLE when one of that name exists; the
+ * group is reachable only as `group/<Name>`. This pins that the approved
+ * group gives its members nothing the Admin role is granted.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import { AccessControlService } from '../access-control.service.js';
+
+const execFileAsync = promisify(execFile);
+const KB_DIR = 'knowledge-base';
+const WS = 'ws-group-named-admin';
+
+const ADMIN = 'admin@x.io';
+const BUSINESS = 'business@x.io';
+
+const BEFORE: Record<string, string> = {
+  'roles.yaml': `roles:\n  Admin:\n    - ${ADMIN}\n`,
+  'groups.yaml': `groups:\n  Sales:\n    - ${BUSINESS}\n`,
+  // The root: Admin writes everything, Sales reads.
+  'access.md': '---\nwrite:\n  - Admin\n---\nread:\n  - group/Sales\nwrite:\n  - Admin\n',
+  // An admin-only folder, granted by the bare role name and closed to the rest.
+  'Knowledge/Board/access.md': '---\nwrite:\n  - Admin\n---\nread:\n  - Admin\n  - deny everyone\nwrite:\n  - Admin\nowner:\n  - Admin\n',
+  'Knowledge/Board/Minutes.md': '# Minutes\n',
+};
+
+/** The change request's one edit: a group named Admin, holding the proposer. */
+const PROPOSED_GROUPS = `groups:\n  Sales:\n    - ${BUSINESS}\n  Admin:\n    - ${BUSINESS}\n`;
+
+describe('a group named Admin (QA reproduction)', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const git = (...args: string[]) => execFileAsync('git', ['-C', repo, ...args]);
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-group-admin-'));
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB_DIR);
+    for (const [rel, text] of Object.entries(BEFORE)) {
+      await fs.mkdir(path.dirname(path.join(repo, rel)), { recursive: true });
+      await fs.writeFile(path.join(repo, rel), text);
+    }
+    await git('init', '-b', 'main');
+    await git('config', 'user.email', 'test@x.io');
+    await git('config', 'user.name', 'Test');
+    await git('add', '-A');
+    await git('commit', '-m', 'seed');
+
+    // The Business user's proposal, on its own branch…
+    await git('checkout', '-b', 'proposal/admin-group');
+    await fs.writeFile(path.join(repo, 'groups.yaml'), PROPOSED_GROUPS);
+    await git('commit', '-am', 'Add group Admin');
+    // …approved by an Admin and merged into main.
+    await git('checkout', 'main');
+    await git('merge', '--no-ff', '-m', 'Approve: Add group Admin', 'proposal/admin-group');
+
+    const workspaceService = {
+      getWorkspacePath: async () => workspaceDir,
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    svc = new AccessControlService(workspaceService, KB_DIR, new NodeFs());
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('its members receive none of the Admin role grants', async () => {
+    // Line endings aside (Git may check the merge out with CRLF on Windows),
+    // main now holds the proposed groups file.
+    const merged = await fs.readFile(path.join(repo, 'groups.yaml'), 'utf-8');
+    expect(merged.replace(/\r\n/g, '\n')).toBe(PROPOSED_GROUPS);
+
+    // `read: Admin` / `write: Admin` / `owner: Admin` are the ROLE's.
+    expect(await svc.canRead(WS, BUSINESS, 'Knowledge/Board/Minutes.md')).toBe(false);
+    expect(await svc.canWrite(WS, BUSINESS, 'Knowledge/Board/Minutes.md')).toBe(false);
+    expect(await svc.canWrite(WS, BUSINESS, 'Knowledge/Doc.md')).toBe(false);
+    // …and the gate paths, which read the committed state, agree.
+    expect(await svc.canWriteAtRef(WS, 'main', BUSINESS, 'Knowledge/Board/Minutes.md')).toBe(false);
+    // The Admin capability is the role's alone.
+    expect(await svc.canWrite(WS, BUSINESS, 'roles.yaml')).toBe(false);
+    expect(await svc.adminEmails(WS)).toEqual([ADMIN]);
+
+    // The real Admin keeps everything, and Sales keeps what Sales had.
+    expect(await svc.canRead(WS, ADMIN, 'Knowledge/Board/Minutes.md')).toBe(true);
+    expect(await svc.canWrite(WS, ADMIN, 'Knowledge/Board/Minutes.md')).toBe(true);
+    expect(await svc.canRead(WS, BUSINESS, 'Knowledge/Doc.md')).toBe(true);
+
+    // The dialog's lists name the ROLE, never the group.
+    const readers = await svc.eligibleReaders(WS, 'Knowledge/Board/Minutes.md');
+    expect(readers.principals).toContainEqual({ name: 'Admin', kind: 'role' });
+    expect(readers.principals).not.toContainEqual({ name: 'Admin', kind: 'group' });
+  });
+
+  it('the group is reachable only by its explicit spelling, group/Admin', async () => {
+    await fs.writeFile(
+      path.join(repo, 'Knowledge/Board/access.md'),
+      '---\nwrite:\n  - Admin\n---\nread:\n  - Admin\n  - group/Admin\n  - deny everyone\nwrite:\n  - Admin\n',
+    );
+    svc.invalidate(WS);
+    expect(await svc.canRead(WS, BUSINESS, 'Knowledge/Board/Minutes.md')).toBe(true);
+    // Reading is all `group/Admin` was granted.
+    expect(await svc.canWrite(WS, BUSINESS, 'Knowledge/Board/Minutes.md')).toBe(false);
+    const readers = await svc.eligibleReaders(WS, 'Knowledge/Board/Minutes.md');
+    expect(readers.principals).toContainEqual({ name: 'Admin', kind: 'group' });
+    expect(readers.principals).toContainEqual({ name: 'Admin', kind: 'role' });
+  });
+});

package/src/modules/access/__tests__/access-control.preview-relocation.test.ts

@@ -360,6 +360,56 @@ describe('AccessControlService.previewAccessAfterRelocation', () => {
     expect(await verbsAt(service(), 'Legal/note.md')).toEqual(after);
   });
 
+  /**
+   * A copy whose source is no repository path — a file staged in the
+   * workspace's `tmp/` folder — carries rules in by its text alone
+   * (`sourceContent`), read exactly as a repository file's would be. Checked,
+   * as every other case here, against the gates once the bytes really landed.
+   */
+  describe('a source outside the repository, previewed by its content', () => {
+    const REF = '__tmp__/staged.md';
+
+    it('its own frontmatter governs the file it lands as', async () => {
+      await write({ ...BASE, 'Work/access.md': rules(`write:\n  - Mover <${MOVER}>\n`) });
+      const staged = rules(`read:\n  - deny everyone\n  - Other <other@x.io>\n`) + '# Staged\n';
+
+      const svc = service();
+      expect(await verbsAt(svc, 'Work/staged.md')).toMatchObject({ read: true, write: true });
+      const after = await svc.previewAccessAfterRelocation(
+        workspaceId, MOVER, REF, 'Work/staged.md', { sourceRemains: true, sourceContent: staged },
+      );
+      // The staged file shuts the caller out of what it becomes.
+      expect(after.read).toBe(false);
+
+      await write({ 'Work/staged.md': staged });
+      expect(await verbsAt(service(), 'Work/staged.md')).toEqual(after);
+    });
+
+    it('landing as an access.md, it gives the destination folder its rules', async () => {
+      await write({ ...BASE, 'Legal/note.md': '# Note\n' });
+      const staged = rules(`write:\n  - Mover <${MOVER}>\nowner:\n  - Mover <${MOVER}>\n`);
+
+      const svc = service();
+      expect(await verbsAt(svc, 'Legal/access.md')).toMatchObject({ write: false, owner: false });
+      const after = await svc.previewAccessAfterRelocation(
+        workspaceId, MOVER, REF, 'Legal/access.md', { sourceRemains: true, sourceContent: staged },
+      );
+      expect(after).toMatchObject({ write: true, owner: true });
+
+      await write({ 'Legal/access.md': staged });
+      expect(await verbsAt(service(), 'Legal/access.md')).toEqual(after);
+    });
+
+    it('nothing is read at the ref: a repository path spelled like it is not the source', async () => {
+      await write({ ...BASE, [REF]: rules(`read:\n  - deny everyone\n`) + '# Not the staged file\n' });
+
+      const after = await service().previewAccessAfterRelocation(
+        workspaceId, MOVER, REF, 'Work/staged.md', { sourceRemains: true, sourceContent: '# Staged\n' },
+      );
+      expect(after).toEqual(await verbsAt(service(), 'Work/staged.md'));
+    });
+  });
+
   it('answers the caller\'s own verbs and nothing else, and writes nothing', async () => {
     await write({
       ...BASE,

package/src/modules/access/__tests__/access-declarations.test.ts

@@ -5,6 +5,7 @@ import {
   AccessDeclarationsError,
   DECLARATION_SCAN_FILE_CAP,
 } from '../access-declarations.js';
+import { registerAccessFrontmatterExtensions } from '../../access-model/access-grammar.js';
 
 /**
  * The declaration scan: WHICH files under a folder declare access rules, and
@@ -111,6 +112,24 @@ describe('listAccessDeclarationsUnder', () => {
     ]);
   });
 
+  it("reads verbs out of a distribution's configuration file (an .agent, once its kind is registered), governing the file itself", async () => {
+    // `.agent` is not core's: a distribution registers the kind at boot, as
+    // `registerAccessFrontmatterExtensions` is for, and the scan then reads it.
+    registerAccessFrontmatterExtensions(['.agent']);
+    const { overrides } = await scan({
+      [`${KB}/Agents/ops.agent`]: fm('name: ops\nplatformTools: [read_file]\nwrite:\n  - Developer') + '\nNotes for people.\n',
+    }, 'Agents');
+
+    expect(overrides).toEqual([
+      {
+        path: 'Agents/ops.agent',
+        governs: 'Agents/ops.agent',
+        source: 'frontmatter',
+        entries: [{ verb: 'write', deny: false, principal: { kind: 'role', role: 'Developer' } }],
+      },
+    ]);
+  });
+
   it('ignores nodes whose frontmatter declares no access verb', async () => {
     const { overrides } = await scan({
       [`${KB}/Plugins/GTM/outreach/SKILL.md`]: fm('nodeType: Skill\ndescription: Runs outreach'),

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

@@ -260,43 +260,75 @@ describe('group files as access principals', () => {
     expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(false);
   });
 
-  it('a bare name shared by a group and a role resolves to the GROUP (grant side)', async () => {
+  it('a bare name shared by a group and a role resolves to the ROLE (grant side)', async () => {
     const svc = await makeService({
       'roles.yaml': `roles:\n  Admin:\n    - admin@x.io\n  Engineering:\n    - lead@x.io\n`,
       // The group "Engineering" collides with the ROLE Engineering.
       'groups.yaml': GROUPS_YAML_TEXT,
       'access.md': '---\nread:\n  - Engineering\n---\n',
     });
-    // Group-first precedence: the group's members read; the role's member no
-    // longer resolves through the bare token (use role/Engineering for that).
-    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(true);
-    expect(await svc.canRead(workspaceId, 'lead@x.io', 'Knowledge/Doc.md')).toBe(false);
-    // The display surface resolves the bare token to the group too — and says
-    // WHAT it is, so the dialog badges the row "Group", not "Role".
+    // Role-first precedence: the role's member reads; the group's members do
+    // not resolve through the bare token (group/Engineering is the group).
+    expect(await svc.canRead(workspaceId, 'lead@x.io', 'Knowledge/Doc.md')).toBe(true);
+    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(false);
+    // The display surface resolves the bare token to the role too — and says
+    // WHAT it is, so the dialog badges the row "Role", not "Group".
     const readers = await svc.eligibleReaders(workspaceId, 'Knowledge/Doc.md');
     expect(readers.roles).toContain('Engineering');
+    expect(readers.principals).toContainEqual({ name: 'Engineering', kind: 'role' });
+    expect(readers.principals).not.toContainEqual({ name: 'Engineering', kind: 'group' });
+  });
+
+  it('a bare name with no role of that name still resolves to the group (existing files keep working)', async () => {
+    const svc = await makeService({
+      'roles.yaml': ROLES_YAML,
+      'groups.yaml': GROUPS_YAML_TEXT,
+      'access.md': '---\nread:\n  - Engineering\n---\n',
+    });
+    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(true);
+    const readers = await svc.eligibleReaders(workspaceId, 'Knowledge/Doc.md');
     expect(readers.principals).toContainEqual({ name: 'Engineering', kind: 'group' });
   });
 
-  it('a bare-name DENY resolves to the group; role/<Name> reaches the role (writers included)', async () => {
+  it('group/<Name> always means the group, role/<Name> always the role', async () => {
     const svc = await makeService({
       'roles.yaml': `roles:\n  Admin:\n    - admin@x.io\n  Engineering:\n    - lead@x.io\n`,
       'groups.yaml': GROUPS_YAML_TEXT,
       'access.md':
-        '---\nread:\n  - everyone\n  - deny Engineering\nwrite:\n  - role/Engineering\n---\n',
+        '---\nread:\n  - everyone\n  - deny group/Engineering\nwrite:\n  - role/Engineering\nowner:\n  - group/Sales\n---\n',
     });
-    // The deny bites the GROUP's members, not the role's.
+    // The explicit group deny bites the GROUP's members, not the role's.
     expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(false);
     expect(await svc.canRead(workspaceId, 'lead@x.io', 'Knowledge/Doc.md')).toBe(true);
-    // The explicit token grants the ROLE write.
+    // The explicit role token grants the ROLE write.
     expect(await svc.canWrite(workspaceId, 'lead@x.io', 'Knowledge/Doc.md')).toBe(true);
     expect(await svc.canWrite(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(false);
-    // eligibleWriters resolves the explicit token to the role's display name —
-    // and carries kind 'role': the `role/` alias always means the role, even
-    // with a same-named group in play.
     const writers = await svc.eligibleWriters(workspaceId, 'Knowledge/Doc.md');
-    expect(writers.roles).toContain('Engineering');
     expect(writers.principals).toContainEqual({ name: 'Engineering', kind: 'role' });
+    // An unshared group name spelled group/ is the group too.
+    const owners = await svc.eligibleOwners(workspaceId, 'Knowledge/Doc.md');
+    expect(owners.principals).toContainEqual({ name: 'Sales', kind: 'group' });
+  });
+
+  it('a bare-name DENY resolves to the role when one exists, never the same-named group', async () => {
+    const svc = await makeService({
+      'roles.yaml': `roles:\n  Admin:\n    - admin@x.io\n  Engineering:\n    - lead@x.io\n`,
+      'groups.yaml': GROUPS_YAML_TEXT,
+      'access.md': '---\nread:\n  - everyone\n  - deny Engineering\n---\n',
+    });
+    expect(await svc.canRead(workspaceId, 'lead@x.io', 'Knowledge/Doc.md')).toBe(false);
+    // ada is in the Engineering GROUP only; a bare denial means the role.
+    expect(await svc.canRead(workspaceId, 'ada@x.io', 'Knowledge/Doc.md')).toBe(true);
+  });
+
+  it('a group/<Name> naming no group grants nobody', async () => {
+    const svc = await makeService({
+      'roles.yaml': `roles:\n  Admin:\n    - admin@x.io\n  Reviewer:\n    - rev@x.io\n`,
+      'groups.yaml': GROUPS_YAML_TEXT,
+      'access.md': '---\nread:\n  - group/Reviewer\n---\n',
+    });
+    // A role of that name exists, but group/ never reaches a role.
+    expect(await svc.canRead(workspaceId, 'rev@x.io', 'Knowledge/Doc.md')).toBe(false);
   });
 
   it('role/Admin resolves to the ROLE even when a synced group is named Admin', async () => {
@@ -308,8 +340,9 @@ describe('group files as access principals', () => {
     // The explicit token is the role — the shadowing group gets nothing here.
     expect(await svc.canWrite(workspaceId, 'admin@x.io', 'Knowledge/Doc.md')).toBe(true);
     expect(await svc.canWrite(workspaceId, 'attacker@evil.io', 'Knowledge/Doc.md')).toBe(false);
-    // The BARE token is the group now (group-first): its member reads.
-    expect(await svc.canRead(workspaceId, 'attacker@evil.io', 'Knowledge/Doc.md')).toBe(true);
+    // The BARE token is the role too (role-first): the group's member gets nothing.
+    expect(await svc.canRead(workspaceId, 'attacker@evil.io', 'Knowledge/Doc.md')).toBe(false);
+    expect(await svc.canRead(workspaceId, 'admin@x.io', 'Knowledge/Doc.md')).toBe(true);
     // Admin CAPABILITY never leaks to the group: roles.yaml write is a pure
     // is-admin check keyed on the role, and admin-rescue keeps working.
     expect(await svc.canWrite(workspaceId, 'attacker@evil.io', 'roles.yaml')).toBe(false);
@@ -403,14 +436,14 @@ describe('group files as access principals', () => {
   });
 
   it('eligible holders keep BOTH kinds when a group and a role share a name', async () => {
-    // A group named Engineering shadows the role Engineering. When a file
-    // grants BOTH spellings — the bare token (the group's) and role/… (the
-    // role's) — the eligible list must carry two entries, one per kind:
-    // collapsing them hides the role's live role/<name> grant entirely.
+    // A group named Engineering shares the role Engineering's name. When a
+    // file grants BOTH — group/… (the group's) and the bare or role/… token
+    // (the role's) — the eligible list must carry two entries, one per kind:
+    // collapsing them hides one of the live grants entirely.
     const svc = await makeService({
       'roles.yaml': `roles:\n  Admin:\n    - admin@x.io\n  Engineering:\n    - lead@x.io\n`,
       'groups.yaml': GROUPS_YAML_TEXT,
-      'access.md': '---\nread:\n  - Engineering\n  - role/Engineering\n---\n',
+      'access.md': '---\nread:\n  - group/Engineering\n  - Engineering\n---\n',
     });
     const readers = await svc.eligibleReaders(workspaceId, 'Knowledge/Doc.md');
     expect(readers.principals).toContainEqual({ name: 'Engineering', kind: 'group' });

package/src/modules/access/__tests__/access-mutation.service.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -361,52 +361,47 @@ describe('AccessMutationService', () => {
       expect(await access.canWrite(WS, 'razvan@bevel.software', 'Sales/access.md')).toBe(true);
     });
 
-    it('GROUP deny with a VANISHED group succeeds even when a same-named ROLE keeps a role/<Name> grant', async () => {
-      // The false-negative this pins: the route pins tokenMatch:'exact' for a
-      // GROUP principal, so the deny strips/denies ONLY the bare token. The
-      // post-write effectiveness assert must judge the SAME exact identity —
-      // with the group vanished the name reads "unshadowed", and the
-      // alias-tolerant default would read the surviving `role/Product Team`
-      // grant as the GROUP still having access, roll back a fully effective
+    it('GROUP deny with a VANISHED group succeeds even when a same-named ROLE keeps its grants', async () => {
+      // The false-negative this pins: a role named Product Team exists, so the
+      // service matches the GROUP's revoke/deny 'exact' — it strips and denies
+      // only `group/Product Team`. The post-write effectiveness assert must
+      // judge the SAME exact identity: with the group vanished, an
+      // alias-tolerant check would read the role's surviving bare and role/
+      // grants as the group still having access, roll back a fully effective
       // deny, and answer 409 deny-ineffective.
       await write(
         repo,
         'Sales/access.md',
-        // The bare grant is the (now vanished) GROUP's; the role/ grant is the
-        // same-named ROLE's own. No groups.yaml exists — the group is gone.
-        '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n# Sales folder\n',
+        // The group/ grant is the (now vanished) GROUP's; the bare and role/
+        // grants are the same-named ROLE's. No groups.yaml — the group is gone.
+        '---\nwrite:\n  - group/Product Team\n  - Product Team\n  - role/Product Team\n---\n# Sales folder\n',
       );
       access.invalidate(WS);
 
-      const r = await mutation.denyHere(
-        WS,
-        'folder',
-        'Sales',
-        { kind: 'role', role: 'Product Team' },
-        undefined,
-        { tokenMatch: 'exact' },
-      );
+      const r = await mutation.denyHere(WS, 'folder', 'Sales', { kind: 'role', role: 'group/Product Team' });
       expect(r.changed).toBe(true);
       access.invalidate(WS);
 
       const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
-      // The bare (group) grant became a deny...
-      expect(text).toContain('deny Product Team');
-      // ...and the ROLE's own grant was never touched.
+      // The group's grant became a deny...
+      expect(text).toContain('deny group/Product Team');
+      // ...and the ROLE's own grants were never touched.
+      expect(text).toMatch(/^ {2}- Product Team$/m);
       expect(text).toContain('role/Product Team');
+      expect(text).not.toContain('deny Product Team');
       expect(text).not.toContain('deny role/Product Team');
-      // The role still resolves its grant through the surviving role/ entry.
+      // The role still resolves its grant.
       const roleSources = await access.grantSources(WS, 'folder', 'Sales', {
         kind: 'role',
         role: 'role/Product Team',
       });
       expect(roleSources.write).toEqual([{ kind: 'direct' }]);
-      // The exact bare token — the group's identity — holds nothing anymore.
+      // The group's exact token holds nothing anymore.
       const groupSources = await access.grantSources(
         WS,
         'folder',
         'Sales',
-        { kind: 'role', role: 'Product Team' },
+        { kind: 'role', role: 'group/Product Team' },
         { tokenMatch: 'exact' },
       );
       expect(groupSources).toEqual({});
@@ -548,16 +543,17 @@ describe('AccessMutationService', () => {
 });
 
 
-// The four grant/revoke x shadowed/unshadowed cases, end-to-end through the
-// REAL resolver (kbPrincipals decides shadowing) — the token-kind family.
-describe('token-kind family — shadow-aware revoke, exact-token grant (real resolver)', () => {
+// The grant/revoke x collided/uncollided cases, end-to-end through the REAL
+// resolver (kbPrincipals decides who owns the bare name) — the token-kind family.
+describe('token-kind family — role-first revoke, exact-token grant (real resolver)', () => {
   let root: string;
   let repo: string;
   let access: AccessControlService;
   let mutation: AccessMutationService;
 
   const roleP: Principal = { kind: 'role', role: 'role/Product Team' }; // the ROLE, explicit
-  const bareP: Principal = { kind: 'role', role: 'Product Team' }; // the bare name (group when shadowed)
+  const bareP: Principal = { kind: 'role', role: 'Product Team' }; // the bare name (always the role here)
+  const groupP: Principal = { kind: 'role', role: 'group/Product Team' }; // the GROUP, explicit
 
   beforeEach(async () => {
     root = await mkTmpRoot();
@@ -575,64 +571,94 @@ describe('token-kind family — shadow-aware revoke, exact-token grant (real res
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  /** Shadow on = a GROUP named "Product Team" exists (owns the bare token). */
-  async function shadow(on: boolean): Promise<void> {
+  /** Collision on = a GROUP named "Product Team" exists beside the role. */
+  async function collide(on: boolean): Promise<void> {
     if (on) {
-      await write(repo, 'groups.yaml', 'groups:\n  Product Team:\n    - pat@x.io\n');
+      await write(repo, 'groups.yaml', 'groups:\n  Product Team:\n    - pat@x.io\n  Design:\n    - dee@x.io\n');
     }
     access.invalidate(WS);
   }
 
-  it('GRANT shadowed: the group grant lands even though role/<Name> is already granted', async () => {
-    await shadow(true);
-    await write(repo, 'Sales/access.md', '---\nwrite:\n  - role/Product Team\n---\n');
-    const r = await mutation.grant(WS, 'folder', 'Sales', 'write', bareP);
-    expect(r.changed).toBe(true); // exact-token idempotency: bare and role/ are different principals
+  it('GRANT collided: the group grant lands even though the role is already granted', async () => {
+    await collide(true);
+    await write(repo, 'Sales/access.md', '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n');
+    const r = await mutation.grant(WS, 'folder', 'Sales', 'write', groupP);
+    expect(r.changed).toBe(true); // exact-token idempotency: group/ is a different principal
     const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
-    expect(text).toContain('- role/Product Team');
-    expect(text.split('\n')).toContain('  - Product Team');
-    // The group member now resolves write through the bare token.
+    expect(text.split('\n')).toContain('  - group/Product Team');
+    // The group member now resolves write through group/.
     access.invalidate(WS);
     expect(await access.canWrite(WS, 'pat@x.io', 'Sales/Deal.md')).toBe(true);
   });
 
-  it('GRANT unshadowed: same-spelling grants stay idempotent', async () => {
-    await shadow(false);
+  it('GRANT uncollided: same-spelling grants stay idempotent', async () => {
+    await collide(false);
     await write(repo, 'Sales/access.md', '---\nwrite:\n  - role/Product Team\n---\n');
     const r = await mutation.grant(WS, 'folder', 'Sales', 'write', roleP);
     expect(r.changed).toBe(false);
   });
 
-  it("REVOKE shadowed: revoking the ROLE leaves the group's bare grant intact", async () => {
-    await shadow(true);
+  it("REVOKE on a model-load failure: a ROLE revoke stays exact and keeps the bare token", async () => {
+    await collide(true);
     await write(repo, 'Sales/access.md', '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n');
+    // A failed load answers empty principal lists: nothing says who owns the bare name.
+    vi.spyOn(access, 'kbPrincipals').mockResolvedValue({ roles: [], groups: [], plugins: [] } as never);
+    const r = await mutation.revoke(WS, 'folder', 'Sales', roleP, 'admin@x');
+    expect(r.changed).toBe(true);
+    const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
+    expect(text).not.toContain('role/Product Team');
+    expect(text.split('\n')).toContain('  - Product Team');
+  });
+
+  it("REVOKE collided: revoking the ROLE strips its bare and role/ spellings, never the group's", async () => {
+    await collide(true);
+    await write(
+      repo,
+      'Sales/access.md',
+      '---\nwrite:\n  - Product Team\n  - role/Product Team\n  - group/Product Team\n---\n',
+    );
     const r = await mutation.revoke(WS, 'folder', 'Sales', roleP, 'admin@x');
     expect(r.changed).toBe(true);
     const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
     expect(text).not.toContain('role/Product Team');
-    expect(text.split('\n')).toContain('  - Product Team'); // the GROUP's token survives the role revoke
-    // ...and the group member still resolves.
+    expect(text.split('\n')).not.toContain('  - Product Team');
+    expect(text.split('\n')).toContain('  - group/Product Team'); // the GROUP's token survives
     access.invalidate(WS);
     expect(await access.canWrite(WS, 'pat@x.io', 'Sales/Deal.md')).toBe(true);
+    expect(await access.canWrite(WS, 'felix@example.com', 'Sales/Deal.md')).toBe(false);
   });
 
-  it("REVOKE shadowed: revoking the GROUP leaves the role's explicit grant intact", async () => {
-    await shadow(true);
-    await write(repo, 'Sales/access.md', '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n');
-    const r = await mutation.revoke(WS, 'folder', 'Sales', bareP, 'admin@x');
+  it("REVOKE collided: revoking the GROUP strips group/ only — the bare name is the role's", async () => {
+    await collide(true);
+    await write(
+      repo,
+      'Sales/access.md',
+      '---\nwrite:\n  - Product Team\n  - role/Product Team\n  - group/Product Team\n---\n',
+    );
+    const r = await mutation.revoke(WS, 'folder', 'Sales', groupP, 'admin@x');
     expect(r.changed).toBe(true);
     const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
-    expect(text).toContain('- role/Product Team'); // the ROLE's token survives the group revoke
-    expect(text.split('\n')).not.toContain('  - Product Team');
-    // The role member (felix, per roles.yaml) still resolves via role/.
+    expect(text).not.toContain('group/Product Team');
+    expect(text.split('\n')).toContain('  - Product Team');
+    expect(text).toContain('- role/Product Team');
     access.invalidate(WS);
     expect(await access.canWrite(WS, 'felix@example.com', 'Sales/Deal.md')).toBe(true);
-    // The group member no longer does.
     expect(await access.canWrite(WS, 'pat@x.io', 'Sales/Deal.md')).toBe(false);
   });
 
-  it('REVOKE unshadowed: revoking the role strips BOTH spellings (legacy bare cleanup)', async () => {
-    await shadow(false);
+  it('REVOKE: a group no role shares a name with strips group/ AND its legacy bare spelling', async () => {
+    await collide(true);
+    await write(repo, 'Sales/access.md', '---\nwrite:\n  - Design\n  - group/Design\n---\n');
+    const r = await mutation.revoke(WS, 'folder', 'Sales', { kind: 'role', role: 'group/Design' }, 'admin@x');
+    expect(r.changed).toBe(true);
+    const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
+    expect(text).not.toContain('Design');
+    access.invalidate(WS);
+    expect(await access.canWrite(WS, 'dee@x.io', 'Sales/Deal.md')).toBe(false);
+  });
+
+  it('REVOKE uncollided: revoking the role strips BOTH spellings (legacy bare cleanup)', async () => {
+    await collide(false);
     await write(repo, 'Sales/access.md', '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n');
     const r = await mutation.revoke(WS, 'folder', 'Sales', roleP, 'admin@x');
     expect(r.changed).toBe(true);
@@ -642,12 +668,12 @@ describe('token-kind family — shadow-aware revoke, exact-token grant (real res
     expect(await access.canWrite(WS, 'felix@example.com', 'Sales/Deal.md')).toBe(false);
   });
 
-  it('REVOKE unshadowed: a bare revoke (group since vanished) also strips both spellings', async () => {
-    await shadow(false);
+  it('REVOKE uncollided: a bare revoke also strips both spellings', async () => {
+    await collide(false);
     await write(repo, 'Sales/access.md', '---\nwrite:\n  - Product Team\n  - role/Product Team\n---\n');
     const r = await mutation.revoke(WS, 'folder', 'Sales', bareP, 'admin@x');
     expect(r.changed).toBe(true);
     const text = await fs.readFile(path.join(repo, 'Sales/access.md'), 'utf-8');
-    expect(text).not.toContain('Product Team'); // unshadowed: both spellings are the role
+    expect(text).not.toContain('Product Team'); // both spellings are the role
   });
 });

package/src/modules/access/__tests__/access-restrict-here.test.ts

@@ -123,9 +123,11 @@ describe('restricting below a parent keeps the principal reported', () => {
     principal: Principal,
     picked: Partial<Record<Verb, boolean>> | null,
   ): Promise<void> {
+    // The mutation service derives its matching (no role shares GTM Team's
+    // name, so 'exact'); the read side is told the same.
     const opts = principal.kind === 'role' ? ({ tokenMatch: 'exact' } as const) : undefined;
     if (picked === null) {
-      await mutation.denyHere(WS, 'folder', FOLDER, principal, undefined, opts);
+      await mutation.denyHere(WS, 'folder', FOLDER, principal, undefined);
       access.invalidate(WS);
       return;
     }
@@ -135,11 +137,11 @@ describe('restricting below a parent keeps the principal reported', () => {
       const src = await access.grantSources(WS, 'folder', FOLDER, toGrantPrincipal(principal), opts);
       const list = src[verb] ?? [];
       const localOnly = list.length > 0 && list.every((s) => s.kind === 'direct');
-      if (localOnly) await mutation.revoke(WS, 'folder', FOLDER, principal, 'me@x', verb, opts);
-      else await mutation.denyHere(WS, 'folder', FOLDER, principal, verb, opts);
+      if (localOnly) await mutation.revoke(WS, 'folder', FOLDER, principal, 'me@x', verb);
+      else await mutation.denyHere(WS, 'folder', FOLDER, principal, verb);
       access.invalidate(WS);
       if (localOnly && (await effective(principal))[verb]) {
-        await mutation.denyHere(WS, 'folder', FOLDER, principal, verb, opts);
+        await mutation.denyHere(WS, 'folder', FOLDER, principal, verb);
         access.invalidate(WS);
       }
     }
@@ -153,7 +155,7 @@ describe('restricting below a parent keeps the principal reported', () => {
         opts,
       );
       if (!(denials[verb] ?? []).some((s) => s.kind === 'direct')) continue;
-      await mutation.revoke(WS, 'folder', FOLDER, principal, 'me@x', verb, opts);
+      await mutation.revoke(WS, 'folder', FOLDER, principal, 'me@x', verb);
       access.invalidate(WS);
     }
     for (const verb of minimalGrants(picked)) {

package/src/modules/access/__tests__/access.routes.admins.test.ts

@@ -97,6 +97,7 @@ async function makeHarness(
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       db,
       testKbContext({ kbDirName: KB }),
+      new NodeFs(),
       deploymentAdmins,
     ),
   );

package/src/modules/access/__tests__/access.routes.batch.test.ts

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * HTTP contract for `POST /access/batch` — the verb dispatch. Existing callers
@@ -66,6 +67,7 @@ async function makeHarness(): Promise<Harness> {
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       usersDbDouble(),
       testKbContext({ kbDirName: KB }),
+      new NodeFs(),
     ),
   );