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

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-requests.routes.test.ts

@@ -49,7 +49,8 @@ interface HarnessOpts {
   lastClosed?: { number: number; state: 'closed' | 'merged' } | null;
   liveRules?: string | null;
   branchRules?: string | null;
-  detailBody?: string;
+  /** What `getChangeRequestDetail` answers for every request: the body, and the access request's own facts. */
+  detail?: { body?: string; accessRequest?: { level: 'write' | 'owner'; note?: string } };
 }
 
 async function makeHarness(opts: HarnessOpts = {}) {
@@ -62,7 +63,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     lastClosed = null,
     liveRules = '---\n---\nwrite:\n  - Ed <ed@x.io>\n',
     branchRules = null,
-    detailBody = '',
+    detail = {},
   } = opts;
 
   const absent = Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
@@ -92,7 +93,7 @@ async function makeHarness(opts: HarnessOpts = {}) {
     }),
     latestClosedChangeRequest: vi.fn(async () => lastClosed),
     getChangeRequest: vi.fn(async (n: number) => ({ number: n, state: 'open' })),
-    getChangeRequestDetail: vi.fn(async () => ({ body: detailBody })),
+    getChangeRequestDetail: vi.fn(async () => ({ body: '', ...detail })),
   } as unknown as IWorkflowService;
 
   const workspaceService = {
@@ -345,13 +346,14 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
   it('reports the open request, taking the level off the REQUEST rather than the branch', async () => {
     // The branch is where the proposal lives, but a clone whose refs are
     // seconds stale cannot read a branch cut moments ago. "Requested: Owner"
-    // is a promise about a request, so it is answered from the request — here
-    // the branch is deliberately unreadable and the line is still right.
+    // is a promise about a request, so it is answered from the request's own
+    // row — here the branch is deliberately unreadable and the line is still
+    // right.
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
       proposals: null,
-      detailBody: '<!--hexis:access-request-level:owner-->\nRita asked for Owner.',
+      detail: { body: 'Rita asked for Owner.', accessRequest: { level: 'owner' } },
     });
     server = h.server;
     expect(await (await status(h)).json()).toEqual({ state: 'pending', level: 'owner', number: 31 });
@@ -361,7 +363,7 @@ describe('GET /workspace/:id/access/request — what the requester is told', ()
     const branch = joinBranchFor(RITA.email, FOLDER);
     const h = await makeHarness({
       openCrs: [{ number: 31, branch, state: 'open' }],
-      detailBody: 'Opened before the level was recorded.',
+      detail: { body: 'Opened before the level was recorded.' },
     });
     server = h.server;
     expect(await (await status(h)).json()).toMatchObject({ state: 'pending', level: 'write' });
@@ -410,12 +412,14 @@ describe('the editors\' side', () => {
   const listUrl = (base: string) =>
     `${base}/${LIVE_WS}/access/requests?path=${encodeURIComponent(`${KB}/${FOLDER}`)}&kind=folder`;
 
-  it('lists the item\'s open requests for an editor, with the note read back as plain text', async () => {
+  it("lists the item's open requests for an editor, with the note off the request's own row", async () => {
     const h = await makeHarness({
       writable: [`${FOLDER}/access.md`],
       proposals: [proposalFor('owner')],
-      detailBody:
-        'x\n\n<!--hexis:access-request-note-->\n> I maintain these pages now\n<!--/hexis:access-request-note-->\n',
+      detail: {
+        body: 'x\n\nNote from Rita:\n\n> I maintain these pages now',
+        accessRequest: { level: 'owner', note: 'I maintain these pages now' },
+      },
     });
     server = h.server;
     const body = await (await fetch(listUrl(h.base))).json();
@@ -565,19 +569,29 @@ describe('a branch left over from an answered request', () => {
     // request asking for Owner.
     const h = await makeHarness({
       openCrs: [{ number: 31, branch: stale, state: 'open' }],
-      detailBody: '<!--hexis:access-request-level:owner-->',
+      detail: { accessRequest: { level: 'owner' } },
     });
     server = h.server;
     const res = await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
     expect(await res.json()).toEqual({ ok: true, state: 'pending', number: 31, level: 'owner' });
   });
 
-  it('records the level on the request itself, so it can be read back', async () => {
+  it('records the level and the note on the request itself, never hidden in its description', async () => {
     const h = await makeHarness();
     server = h.server;
-    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner' });
-    const { description } = h.opened[0] as { description: string };
-    expect(description).toContain('<!--hexis:access-request-level:owner-->');
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'owner', note: 'For the Q3 review' });
+    const { description, accessRequest } = h.opened[0] as { description: string; accessRequest: unknown };
+    expect(accessRequest).toEqual({ level: 'owner', note: 'For the Q3 review' });
+    // The description is prose for the people who read it: no marker, no fence.
+    expect(description).not.toMatch(/<!--/);
+    expect(description).toContain('For the Q3 review');
+  });
+
+  it('records no note when none was written', async () => {
+    const h = await makeHarness();
+    server = h.server;
+    await post(`${h.base}/${LIVE_WS}/access/request`, { ...folderBody, level: 'write' });
+    expect((h.opened[0] as { accessRequest: unknown }).accessRequest).toEqual({ level: 'write' });
   });
 });
 

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(),
     ),
   );
 

package/src/modules/access/__tests__/access.routes.folder-governs.test.ts

@@ -16,6 +16,7 @@ import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
 import { AccessMutationError, AccessMutationService } from '../access-mutation.service.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * A file that cannot carry frontmatter is never written by an access mutation.
@@ -161,6 +162,7 @@ describe('access mutations on a file that cannot carry frontmatter', () => {
         { emit: vi.fn() } as unknown as WorkflowEventBus,
         usersDbDouble(),
         testKbContext({ kbDirName: KB }),
+        new NodeFs(),
       ),
     );
     server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -12,6 +12,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-level contract tests for GROUP and ROLE principals on the share
@@ -99,7 +100,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
@@ -126,7 +127,7 @@ describe('group principals on the share surface', () => {
       body: JSON.stringify(body),
     });
 
-  it('grants read to a known group — spliced as the bare-name token', async () => {
+  it('grants read to a known group — spliced as the explicit group/<Name> token', async () => {
     h = await makeHarness({ groups: ['GTM Team', 'Product'] });
     const res = await post('grant', {
       path: `${KB}/Sales`,
@@ -136,8 +137,8 @@ describe('group principals on the share surface', () => {
     });
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
-    expect(md).toContain('- GTM Team');
-    expect(md).not.toContain('role/'); // a GROUP grant is the bare token
+    expect(md.split('\n')).toContain('  - group/GTM Team'); // never the bare name
+    expect(md).not.toContain('role/');
   });
 
   it('grants a ROLE as the explicit role/<Name> token', async () => {
@@ -190,7 +191,7 @@ describe('group principals on the share surface', () => {
     expect(await res.json()).toMatchObject({ kind: 'unknown-role', role: 'Ghost Role' });
   });
 
-  it('a group sharing a role name is grantable — precedence resolves it (no refusal)', async () => {
+  it('a group sharing a role name is grantable — each kind is written with its prefix (no refusal)', async () => {
     h = await makeHarness({ roles: ['Everyone', 'Product'], groups: ['Product'] });
     const asGroup = await post('grant', {
       path: `${KB}/Sales`,
@@ -199,7 +200,7 @@ describe('group principals on the share surface', () => {
       principal: { kind: 'group', group: 'Product' },
     });
     expect(asGroup.status).toBe(200);
-    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- group/Product');
     // The ROLE of the same name grants as the explicit token, side by side.
     const asRole = await post('grant', {
       path: `${KB}/Sales`,
@@ -249,7 +250,19 @@ describe('group principals on the share surface', () => {
       principal: { kind: 'group', group: 'Product' },
     });
     expect(res.status).toBe(200);
-    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- group/Product');
+  });
+
+  it('a group named with its group/ prefix is written once-prefixed', async () => {
+    h = await makeHarness({ groups: ['GTM Team'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'group/GTM Team' },
+    });
+    expect(res.status).toBe(200);
+    expect(h.files.get(`${KB}/Sales/access.md`)!.split('\n')).toContain('  - group/GTM Team');
   });
 
   it('a non-admin granting to a group they are not in is refused exactly like an unknown group', async () => {
@@ -281,9 +294,11 @@ describe('group principals on the share surface', () => {
 
   it('revokes with a group principal (name-based, no existence check)', async () => {
     h = await makeHarness({
+      roles: ['Everyone'],
       groups: ['GTM Team'],
       files: {
-        [`${KB}/Sales/access.md`]: '---\nread:\n  - Vanished Team\n---\n',
+        // Both spellings: the legacy bare one and the explicit one.
+        [`${KB}/Sales/access.md`]: '---\nread:\n  - Vanished Team\n  - group/Vanished Team\n---\n',
       },
     });
     const res = await post('revoke', {
@@ -369,11 +384,11 @@ describe('token-kind family at the route boundary', () => {
     expect(md).toContain('- Admin');
   });
 
-  it('granting a GROUP that shadows an already-granted role/<Name> is NOT swallowed as idempotent', async () => {
+  it('granting a GROUP that shares an already-granted role name is NOT swallowed as idempotent', async () => {
     h = await makeHarness({
       roles: ['Everyone', 'Product'],
       groups: ['Product'],
-      files: { [`${KB}/Sales/access.md`]: '---\nread:\n  - role/Product\n---\n' },
+      files: { [`${KB}/Sales/access.md`]: '---\nread:\n  - role/Product\n  - Product\n---\n' },
     });
     const res = await post('grant', {
       path: `${KB}/Sales`,
@@ -384,15 +399,15 @@ describe('token-kind family at the route boundary', () => {
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
     expect(md).toContain('- role/Product');
-    expect(md.split('\n')).toContain('  - Product'); // the group's bare token landed
+    expect(md.split('\n')).toContain('  - group/Product'); // the group's token landed
   });
 
-  it('revoking the ROLE while a same-named GROUP is granted leaves the bare token (kbPrincipals-driven shadowing)', async () => {
+  it("revoking the ROLE while a same-named GROUP is granted leaves the group's token", async () => {
     h = await makeHarness({
       roles: ['Everyone', 'Product'],
       groups: ['Product'],
       files: {
-        [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n---\n',
+        [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n  - group/Product\n---\n',
       },
     });
     const res = await post('revoke', {
@@ -403,6 +418,27 @@ describe('token-kind family at the route boundary', () => {
     expect(res.status).toBe(200);
     const md = h.files.get(`${KB}/Sales/access.md`)!;
     expect(md).not.toContain('role/Product');
-    expect(md.split('\n')).toContain('  - Product'); // the GROUP's grant survives
+    expect(md.split('\n')).not.toContain('  - Product'); // the bare name was the role's
+    expect(md.split('\n')).toContain('  - group/Product'); // the GROUP's grant survives
+  });
+
+  it("revoking the GROUP while a same-named ROLE is granted leaves the role's spellings", async () => {
+    h = await makeHarness({
+      roles: ['Everyone', 'Product'],
+      groups: ['Product'],
+      files: {
+        [`${KB}/Sales/access.md`]: '---\nwrite:\n  - Product\n  - role/Product\n  - group/Product\n---\n',
+      },
+    });
+    const res = await post('revoke', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      principal: { kind: 'group', group: 'Product' },
+    });
+    expect(res.status).toBe(200);
+    const md = h.files.get(`${KB}/Sales/access.md`)!;
+    expect(md).not.toContain('group/Product');
+    expect(md.split('\n')).toContain('  - Product');
+    expect(md).toContain('- role/Product');
   });
 });

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

@@ -12,6 +12,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 `GET /access/overrides`. The scan itself is covered in
@@ -98,7 +99,7 @@ async function makeHarness(opts: {
   });
   app.use(
     '/api',
-    createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })),
+    createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()),
   );
 
   const server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts

@@ -139,6 +139,7 @@ describe('access routes on a proposal branch (real git)', () => {
         { emit: () => {} } as unknown as WorkflowEventBus,
         usersDbDouble(),
         testKbContext({ kbDirName: KB }),
+        new NodeFs(),
       ),
     );
     server = await new Promise<Server>((resolve) => {

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

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 
 /**
  * HTTP contract for `GET /access/prospective` — what the move confirmation
@@ -69,6 +70,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,
       testKbContext({ kbDirName: KB }),
+      new NodeFs(),
     ),
   );