@bevel-software/platform-core-backend 0.10.0 → 0.11.1

package/src/modules/access/__tests__/roles-capabilities.test.ts

@@ -0,0 +1,325 @@
+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 type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { WorkflowService } from '../../workflow/workflow.service.js';
+import type { AuthUser, FileTreeEntry } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { AccessControlService } from '../access-control.service.js';
+import { RolesAdminService } from '../roles-admin.service.js';
+
+const KB = 'knowledge-base';
+const ADMIN: AuthUser = { id: 'u-admin', email: 'admin@x.io', name: 'Admin' } as AuthUser;
+
+const ROLES = `roles:
+  Admin:
+    - admin@x.io
+  Plugin Creator:
+    - jane@x.io
+    - group:engineering
+  Product:
+    - felix@x.io
+    - sara@x.io
+`;
+
+async function write(repo: string, rel: string, contents: string): Promise<void> {
+  const abs = path.join(repo, rel);
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await fs.writeFile(abs, contents);
+}
+
+function stubWorkspace(workspaceDir: string): WorkspaceService {
+  const resolve = (wsRel: string) => path.join(workspaceDir, wsRel);
+  const buildTree = async (absDir: string): Promise<FileTreeEntry> => {
+    const rel = path.relative(workspaceDir, absDir).replace(/\\/g, '/');
+    const children: FileTreeEntry[] = [];
+    for (const e of await fs.readdir(absDir, { withFileTypes: true })) {
+      if (e.name === '.git') continue;
+      const childAbs = path.join(absDir, e.name);
+      if (e.isDirectory()) children.push(await buildTree(childAbs));
+      else if (e.isFile()) {
+        children.push({
+          name: e.name,
+          relativePath: path.relative(workspaceDir, childAbs).replace(/\\/g, '/'),
+          type: 'file',
+        });
+      }
+    }
+    return { name: path.basename(absDir), relativePath: rel || '.', type: 'directory', children };
+  };
+  return {
+    getWorkspacePath: async () => workspaceDir,
+    getOrCreateForBranch: async () => ({}) as unknown,
+    listFiles: async () => buildTree(workspaceDir),
+    readFile: async (_id: string, wsRel: string) => fs.readFile(resolve(wsRel), 'utf-8'),
+    writeFile: async (_id: string, wsRel: string, content: string) => {
+      await fs.mkdir(path.dirname(resolve(wsRel)), { recursive: true });
+      await fs.writeFile(resolve(wsRel), content);
+    },
+    deleteFile: async (_id: string, wsRel: string) => {
+      await fs.rm(resolve(wsRel));
+    },
+  } as unknown as WorkspaceService;
+}
+
+function stubWorkflow() {
+  const commits: { summary: string }[] = [];
+  // Strict per-path locks — a live row is contended even for the same user,
+  // exactly like FileLockService (nesting bugs must fail here too).
+  const locks = new Map<string, AuthUser>();
+  const lockRow = (h: AuthUser) => ({ holderUserId: h.id, holderName: h.name });
+  const acquireCalls: { path: string; coordination: boolean }[] = [];
+  const svc = {
+    getLock: async (_w: string, _b: string, p: string) => {
+      const h = locks.get(p);
+      return h ? lockRow(h) : null;
+    },
+    acquireLock: async (
+      _w: string,
+      _b: string,
+      p: string,
+      user: AuthUser,
+      opts?: { coordination?: boolean },
+    ) => {
+      acquireCalls.push({ path: p, coordination: !!opts?.coordination });
+      // Mirror the production lock-time write gate on the machine-owned file:
+      // synced-groups.yaml refuses every non-bot WRITE-intent acquire on the
+      // (always protected) default branch. Only a coordination acquire — a
+      // pure mutex claiming no write authority — may hold it for a human.
+      if (p === `${KB}/synced-groups.yaml` && !opts?.coordination) {
+        throw new Error(`Access denied: no write permission on "${p}" (machine-owned)`);
+      }
+      const h = locks.get(p);
+      if (h) return { acquired: false, lock: lockRow(h) };
+      locks.set(p, user);
+      return { acquired: true, lock: lockRow(user) };
+    },
+    releaseLock: async (_w: string, _b: string, p: string) => {
+      locks.delete(p);
+    },
+    releaseLockNoCommit: async (_w: string, _b: string, p: string) => {
+      locks.delete(p);
+    },
+    commitChanges: async (_ws: string, _user: AuthUser, summary: string) => {
+      commits.push({ summary });
+      return {} as unknown;
+    },
+  } as unknown as WorkflowService;
+  return { svc, commits, acquireCalls };
+}
+
+describe('RolesAdminService — capabilities, group assignment, conversion', () => {
+  let root: string;
+  let repo: string;
+  let service: RolesAdminService;
+  let commits: { summary: string }[];
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-roles-cap-'));
+    repo = path.join(root, KB);
+    await write(repo, 'roles.yaml', ROLES);
+    // Assignable groups must exist in the ACTIVE source — assignGroup
+    // validates against it (a ref to a missing group is a dead grant).
+    await write(repo, 'groups.yaml', 'groups:\n  GTM Team:\n    - sara@x.io\n');
+    await write(repo, 'access.md', '---\nwrite:\n  - Admin\nread:\n  - Product\n---\n');
+    const workspace = stubWorkspace(root);
+    const workflow = stubWorkflow();
+    commits = workflow.commits;
+    service = new RolesAdminService(
+      workspace,
+      workflow.svc,
+      new AccessControlService(workspace as never, KB),
+      KB,
+      () => DEFAULT_BRANCH,
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  const rolesYaml = () => fs.readFile(path.join(repo, 'roles.yaml'), 'utf-8');
+  const groupsYaml = () => fs.readFile(path.join(repo, 'groups.yaml'), 'utf-8');
+
+  it('roster: capability metadata, legacy flag, and members/groups split', async () => {
+    const roster = await service.getRoster();
+    const admin = roster.find((r) => r.canonical === 'admin')!;
+    expect(admin.capability).toMatchObject({ groupAssignable: true });
+    expect(admin.capability?.description).toContain('configuration');
+
+    const creator = roster.find((r) => r.canonical === 'plugin creator')!;
+    expect(creator.members).toEqual(['jane@x.io']); // group ref split out
+    expect(creator.groups).toEqual(['engineering']);
+    expect(creator.capability).toBeNull(); // not in the registry (yet)
+
+    const product = roster.find((r) => r.canonical === 'product')!;
+    expect(product.capability).toBeNull(); // legacy people-set role
+    expect(product.referencedBy).toEqual([{ path: 'access.md', verb: 'read' }]);
+  });
+
+  it('assigns and unassigns a group on a non-Admin role', async () => {
+    await service.assignGroup(ADMIN, 'product', 'GTM Team');
+    expect(await rolesYaml()).toContain('- group:gtm team');
+
+    const roster = await service.unassignGroup(ADMIN, 'product', 'GTM Team');
+    expect(await rolesYaml()).not.toContain('group:gtm team');
+    expect(roster.find((r) => r.canonical === 'product')?.groups).toEqual([]);
+  });
+
+  it('refuses to assign a group the active source does not know (dead grant)', async () => {
+    const before = await rolesYaml();
+    await expect(service.assignGroup(ADMIN, 'product', 'Ghost Team')).rejects.toMatchObject({
+      status: 404,
+      payload: { kind: 'unknown-group', group: 'Ghost Team' },
+    });
+    expect(await rolesYaml()).toBe(before);
+  });
+
+  it('assigns a group to Admin (NEW) — the invariant lives in the direct-email rule, not a ban', async () => {
+    await service.assignGroup(ADMIN, 'admin', 'GTM Team');
+    expect(await rolesYaml()).toContain('- group:gtm team');
+    const roster = await service.getRoster();
+    expect(roster.find((r) => r.canonical === 'admin')?.groups).toEqual(['gtm team']);
+    // But Admin can never drop its LAST direct email — group refs don't count.
+    await expect(
+      service.removeMember(ADMIN, 'admin', 'admin@x.io', true),
+    ).rejects.toMatchObject({ status: 422, message: expect.stringContaining('direct email') });
+    expect(await rolesYaml()).toContain('- admin@x.io');
+  });
+
+  it('converts a legacy role to a group atomically; grants keep the name', async () => {
+    const roster = await service.convertRoleToGroup(ADMIN, 'product');
+
+    expect(roster.some((r) => r.canonical === 'product')).toBe(false);
+    expect(await rolesYaml()).not.toContain('Product');
+    expect(await groupsYaml()).toContain('Product:\n    - felix@x.io\n    - sara@x.io');
+    expect(commits).toHaveLength(1);
+    expect(commits[0].summary).toContain('Convert role Product to a group');
+    // The grant text was never touched — the name carries over.
+    const accessMd = await fs.readFile(path.join(repo, 'access.md'), 'utf-8');
+    expect(accessMd).toContain('- Product');
+  });
+
+  it('manual-mode conversion works for a HUMAN admin: the synced file is held as a COORDINATION lock', async () => {
+    // synced-groups.yaml is machine-owned — the lock-time write gate refuses
+    // every human actor (the stub's acquireLock enforces this exactly like
+    // production). The conversion still needs the file's lock to serialize
+    // with a provisioning push, so it must take it as a coordination hold
+    // that claims no write authority. A write-intent acquire here would fail
+    // EVERY manual-mode conversion at lock acquisition.
+    const workspace = stubWorkspace(root);
+    const workflow = stubWorkflow();
+    const svc = new RolesAdminService(
+      workspace,
+      workflow.svc,
+      new AccessControlService(workspace as never, KB),
+      KB,
+      () => DEFAULT_BRANCH,
+    );
+    const roster = await svc.convertRoleToGroup(ADMIN, 'product');
+    expect(roster.some((r) => r.canonical === 'product')).toBe(false);
+    expect(await groupsYaml()).toContain('Product:');
+    // The synced file WAS locked (the serialization is real), via coordination;
+    // the written files keep their write-gated acquires.
+    expect(workflow.acquireCalls).toContainEqual({
+      path: `${KB}/synced-groups.yaml`,
+      coordination: true,
+    });
+    expect(workflow.acquireCalls).toContainEqual({ path: `${KB}/roles.yaml`, coordination: false });
+    expect(workflow.acquireCalls).toContainEqual({ path: `${KB}/groups.yaml`, coordination: false });
+  });
+
+  it('conversion refusals: capability role, group-assigned role, IdP mode', async () => {
+    await expect(service.convertRoleToGroup(ADMIN, 'admin')).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining('capability role'),
+    });
+    await expect(service.convertRoleToGroup(ADMIN, 'plugin creator')).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining('assigned to groups'),
+    });
+
+    await write(repo, 'synced-groups.yaml', 'groups:\n  Engineering:\n    - ada@x.io\n');
+    await expect(service.convertRoleToGroup(ADMIN, 'product')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'idp-mode' },
+    });
+  });
+
+  it('conversion re-checks IdP mode UNDER the synced file lock (TOCTOU: a sync landing mid-flight refuses)', async () => {
+    // The pre-lock IdP check passes (no synced file yet). Directory sync then
+    // materializes synced-groups.yaml just before the conversion gets its
+    // locks — the same interleaving the synced file's lock serializes in
+    // production. The under-lock recheck must refuse with the typed 409 and
+    // write nothing (committing a groups.yaml group in IdP mode writes a
+    // retired file).
+    const workspace = stubWorkspace(root);
+    const workflow = stubWorkflow();
+    const wf = workflow.svc as unknown as {
+      acquireLock: (
+        w: string,
+        b: string,
+        p: string,
+        u: AuthUser,
+        opts?: { coordination?: boolean },
+      ) => Promise<unknown>;
+    };
+    const origAcquire = wf.acquireLock.bind(workflow.svc);
+    wf.acquireLock = async (w, b, p, u, opts) => {
+      if (p === `${KB}/synced-groups.yaml`) {
+        // The sync's provisioning push won the race for this lock and landed.
+        await write(repo, 'synced-groups.yaml', 'groups:\n  Engineering:\n    - ada@x.io\n');
+      }
+      return origAcquire(w, b, p, u, opts);
+    };
+    const svc = new RolesAdminService(
+      workspace,
+      workflow.svc,
+      new AccessControlService(workspace as never, KB),
+      KB,
+      () => DEFAULT_BRANCH,
+    );
+    await expect(svc.convertRoleToGroup(ADMIN, 'product')).rejects.toMatchObject({
+      status: 409,
+      payload: { kind: 'idp-mode' },
+    });
+    // Nothing moved.
+    expect(await rolesYaml()).toBe(ROLES);
+    expect(await groupsYaml()).not.toContain('Product');
+    expect(workflow.commits).toHaveLength(0);
+  });
+
+  it('a failed conversion with NO pre-existing groups.yaml leaves no groups.yaml behind', async () => {
+    await fs.rm(path.join(repo, 'groups.yaml'));
+    const workspace = stubWorkspace(root);
+    const workflow = stubWorkflow();
+    (workflow.svc as unknown as { commitChanges: unknown }).commitChanges = async () => {
+      throw new Error('commit exploded');
+    };
+    const svc = new RolesAdminService(
+      workspace,
+      workflow.svc,
+      new AccessControlService(workspace as never, KB),
+      KB,
+      () => DEFAULT_BRANCH,
+    );
+    await expect(svc.convertRoleToGroup(ADMIN, 'product')).rejects.toThrow('commit exploded');
+    // groups.yaml was CREATED by this conversion → rollback deletes it
+    // instead of publishing an empty file as a brand-new artifact.
+    await expect(groupsYaml()).rejects.toMatchObject({ code: 'ENOENT' });
+    // …and roles.yaml got its original bytes back: the role survives.
+    expect(await rolesYaml()).toBe(ROLES);
+  });
+
+  it('conversion refuses a groups.yaml name collision', async () => {
+    await write(repo, 'groups.yaml', 'groups:\n  Product:\n    - other@x.io\n');
+    await expect(service.convertRoleToGroup(ADMIN, 'product')).rejects.toMatchObject({
+      status: 422,
+      message: expect.stringContaining('already exists'),
+    });
+    // Nothing moved: the role survives an aborted conversion.
+    expect(await rolesYaml()).toContain('Product:');
+  });
+});

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

@@ -3,12 +3,12 @@ import { describe, it, expect } from 'vitest';
 import {
   parseRolesModel,
   emitRolesModel,
-  createRole,
   deleteRole,
   addMember,
   removeMember,
-  renameRoleDisplay,
-  assertSafeRoleDisplayName,
+  removeGroupRefsEverywhere,
+  removeRoleGroupRef,
+  renameGroupRefs,
   RolesEditError,
 } from '../roles-edit.js';
 import { parseYamlSubset } from '../access-control.service.js';
@@ -64,19 +64,6 @@ describe('roles-edit: parse + emit', () => {
   });
 });
 
-describe('roles-edit: name guard', () => {
-  it('rejects structurally unsafe names', () => {
-    for (const bad of ['Sales: West', '#temp', 'a<b', 'a>b', '-leading', '']) {
-      expect(() => assertSafeRoleDisplayName(bad)).toThrow(RolesEditError);
-    }
-  });
-
-  it('allows ordinary multi-word names', () => {
-    expect(() => assertSafeRoleDisplayName('Product Team')).not.toThrow();
-    expect(() => assertSafeRoleDisplayName('GTM Team')).not.toThrow();
-  });
-});
-
 describe('roles-edit: mutations', () => {
   it('addMember is idempotent (no-op when already a member)', () => {
     const r = addMember(BASE, 'admin', 'JUAN@bevel.software');
@@ -100,12 +87,11 @@ describe('roles-edit: mutations', () => {
     expect(removeMember(BASE, 'admin', 'ghost@x.eu').changed).toBe(false);
   });
 
-  it('createRole appends `Name: []`, rejects reserved + duplicate', () => {
-    const r = createRole(BASE, 'Marketing');
-    expect(r.text).toContain('Marketing: []');
-    expect(() => createRole(BASE, 'everyone')).toThrow(RolesEditError);
-    expect(() => createRole(BASE, 'deny')).toThrow(RolesEditError);
-    expect(() => createRole(BASE, 'admin')).toThrow(RolesEditError); // duplicate canonical
+  it("addMember rejects a 'group:'-prefixed value with an actionable message", () => {
+    // 'group:lee@x.io' passes the email regex — without the guard it would
+    // land a dead group ref the resolver reads as an unknown group.
+    expect(() => addMember(BASE, 'admin', 'group:lee@x.io')).toThrow(/group assignment/);
+    expect(() => addMember(BASE, 'admin', 'group:gtm team')).toThrow(RolesEditError);
   });
 
   it('deleteRole removes the role; 404 when absent', () => {
@@ -114,14 +100,104 @@ describe('roles-edit: mutations', () => {
     expect(() => deleteRole(BASE, 'ghost')).toThrow(/not found/);
   });
 
-  it('renameRoleDisplay: casing-only keeps members, changes label', () => {
-    const r = renameRoleDisplay(BASE, 'product team', 'PRODUCT TEAM');
-    const role = parseRolesModel(r.text).find((x) => x.members.includes('felix@example.com'))!;
-    expect(role.displayName).toBe('PRODUCT TEAM');
+  it('removeGroupRefsEverywhere strips every ref to the group across roles', () => {
+    const text = [
+      'roles:',
+      '  Admin:',
+      '    - razvan@bevel.software',
+      '  Product Team:',
+      '    - felix@example.com',
+      '    - group:gtm team',
+      '  Ops:',
+      '    - group:GTM  Team', // un-normalized hand edit — canonical matching must catch it
+      '',
+    ].join('\n');
+    const r = removeGroupRefsEverywhere(text, 'gtm team');
+    expect(r.changed).toBe(true);
+    expect(r.text).not.toContain('gtm');
+    const model = parseRolesModel(r.text);
+    expect(model.find((x) => x.displayName === 'Product Team')?.members).toEqual(['felix@example.com']);
+    expect(model.find((x) => x.displayName === 'Ops')?.members).toEqual([]);
+    expect(removeGroupRefsEverywhere(BASE, 'gtm team').changed).toBe(false);
+  });
+
+  it('renameGroupRefs: rewrites group:<ref> members across roles, deduping an existing target', () => {
+    const text = [
+      'roles:',
+      '  Admin:',
+      '    - razvan@bevel.software',
+      '  Product Team:',
+      '    - felix@example.com',
+      '    - group:gtm team',
+      '  Ops:',
+      '    - group:gtm team',
+      '    - group:go to market', // target already present → dedupe, not duplicate
+      '',
+    ].join('\n');
+    const r = renameGroupRefs(text, 'gtm team', 'go to market');
+    expect(r.changed).toBe(true);
+    expect(r.text).not.toContain('group:gtm team');
+    const model = parseRolesModel(r.text);
+    expect(model.find((x) => x.displayName === 'Product Team')?.members).toContain('group:go to market');
+    expect(
+      model.find((x) => x.displayName === 'Ops')?.members.filter((m) => m === 'group:go to market'),
+    ).toHaveLength(1);
+    // Untouched role stays untouched.
+    expect(model.find((x) => x.displayName === 'Admin')?.members).toEqual(['razvan@bevel.software']);
+  });
+
+  it('renameGroupRefs: no-op when nothing references the old name', () => {
+    const r = renameGroupRefs(BASE, 'gtm team', 'go to market');
+    expect(r.changed).toBe(false);
   });
 
-  it('renameRoleDisplay: rejects collision with another existing role', () => {
-    expect(() => renameRoleDisplay(BASE, 'product team', 'Admin')).toThrow(/already exists/);
+  it('renameGroupRefs rewrites EVERY matching ref in a role, collapsing to one', () => {
+    // Two differently-formatted refs to the same group: both must follow the
+    // rename (a straggler would point at the renamed-away name forever), and
+    // only one ref to the new name survives.
+    const text = 'roles:\n  Ops:\n    - group:gtm team\n    - group:gtm  team\n';
+    const r = renameGroupRefs(text, 'gtm team', 'go to market');
+    expect(r.changed).toBe(true);
+    const ops = parseRolesModel(r.text).find((x) => x.displayName === 'Ops')!;
+    expect(ops.members.filter((m) => m === 'group:go to market')).toHaveLength(1);
+    expect(ops.members.some((m) => m.includes('gtm'))).toBe(false);
+  });
+
+  it('group-ref matching is canonical: an un-normalized hand-written ref still matches', () => {
+    // The resolver canonicalizes the ref's suffix (collapsing runs of
+    // spaces), so a hand-written `group:gtm  team` grants — the editors must
+    // find it too, or unassign/rename no-op while the roster still shows the
+    // group. (Parse lowercases members but keeps the double space.)
+    const text = 'roles:\n  Ops:\n    - group:GTM  Team\n';
+    const removed = removeMember(text, 'ops', 'nobody@x.io'); // sanity: parse keeps the un-collapsed ref
+    expect(removed.text).toContain('group:gtm  team');
+    const renamed = renameGroupRefs(text, 'gtm team', 'go to market');
+    expect(renamed.changed).toBe(true);
+    expect(renamed.text).toContain('group:go to market');
+    expect(renamed.text).not.toContain('gtm  team');
+  });
+
+  it('removeRoleGroupRef strips EVERY duplicate ref to the group, not just the first', () => {
+    // A hand-edited file may carry several differently-formatted refs to the
+    // same group. Removing only the first leaves stragglers the resolver
+    // still honors — the role silently keeps the group after an
+    // apparently-successful unassign.
+    const text = [
+      'roles:',
+      '  Ops:',
+      '    - lead@x.io',
+      '    - group:gtm team',
+      '    - group:GTM  Team', // un-normalized duplicate — must go too
+      '',
+    ].join('\n');
+    const r = removeRoleGroupRef(text, 'ops', 'gtm team');
+    expect(r.changed).toBe(true);
+    const ops = parseRolesModel(r.text).find((x) => x.displayName === 'Ops')!;
+    expect(ops.members).toEqual(['lead@x.io']);
+    // Idempotent afterwards.
+    expect(removeRoleGroupRef(r.text, 'ops', 'gtm team').changed).toBe(false);
+    // Other roles/refs untouched.
+    expect(() => removeRoleGroupRef(text, 'ghost', 'gtm team')).toThrow(/not found/);
   });
 
   it('only the changed role moves in the diff (other roles untouched)', () => {

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

@@ -17,10 +17,11 @@ import { createAccessRoutes } from '../access.routes.js';
 
 /**
  * HTTP-level contract tests for the /api/access/roles routes: the admin gate
- * (non-admin → 403), the GET roster shape, and that service-layer invariant
- * errors (reserved name → 422, self-admin-removal → 409 { kind }) surface with
- * the right status. The CRUD logic itself is covered by roles-admin.service.test;
- * here we pin the route wiring + error mapping.
+ * (non-admin → 403), the GET roster shape, the REMOVED role-CRUD endpoints
+ * (404 — roles are app-defined capabilities), and that service-layer
+ * invariant errors (self-admin-removal → 409 { kind }) surface with the
+ * right status. The membership logic itself is covered by
+ * roles-admin.service.test; here we pin the route wiring + error mapping.
  */
 
 const KB = 'knowledge-base';
@@ -64,7 +65,6 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
     eligibleWriters: vi.fn(async () => ({ roles: ['Admin'], users: [] })),
     invalidate: vi.fn(),
     validateRolesYaml: (t: string) => realAccess.validateRolesYaml(t),
-    referencesToRole: vi.fn(async () => []),
   } as unknown as IAccessControl;
 
   const resolve = (wsRel: string) => path.join(workspaceDir, wsRel);
@@ -103,17 +103,23 @@ async function makeHarness(opts: { isAdmin?: boolean } = {}): Promise<{ server:
 
   // Lock holder tracked so the service's getLock pre-check passes; the single-
   // file write itself lands on disk via LockingFilesystem → LocalFilesystem.
-  let holder: { id: string; name: string } | null = null;
+  // Strict per-path locks — a live row is contended even for the same user,
+  // exactly like FileLockService (nesting bugs must fail here too).
+  const locks = new Map<string, { id: string; name: string }>();
   const lockRow = (h: { id: string; name: string }) => ({ holderUserId: h.id, holderName: h.name });
   const workflowService = {
-    getLock: vi.fn(async () => (holder ? lockRow(holder) : null)),
-    acquireLock: vi.fn(async (_w: string, _b: string, _p: string, user: { id: string; name: string }) =>
-      holder && holder.id !== user.id
-        ? { acquired: false, lock: lockRow(holder) }
-        : ((holder = user), { acquired: true, lock: lockRow(user) }),
-    ),
-    releaseLock: vi.fn(async () => void (holder = null)),
-    releaseLockNoCommit: vi.fn(async () => void (holder = null)),
+    getLock: vi.fn(async (_w: string, _b: string, p: string) => {
+      const h = locks.get(p);
+      return h ? lockRow(h) : null;
+    }),
+    acquireLock: vi.fn(async (_w: string, _b: string, p: string, user: { id: string; name: string }) => {
+      const h = locks.get(p);
+      if (h) return { acquired: false, lock: lockRow(h) };
+      locks.set(p, user);
+      return { acquired: true, lock: lockRow(user) };
+    }),
+    releaseLock: vi.fn(async (_w: string, _b: string, p: string) => void locks.delete(p)),
+    releaseLockNoCommit: vi.fn(async (_w: string, _b: string, p: string) => void locks.delete(p)),
     // Write-free: the lock-aware filesystem writes to disk; this just commits the
     // dirty tree. Not exercised by these route tests (no rename), but kept honest.
     commitChanges: vi.fn(async () => ({})),
@@ -166,35 +172,58 @@ describe('/api/access/roles routes', () => {
     expect(res.status).toBe(403);
   });
 
-  it('a non-admin is refused on every mutating route (403)', async () => {
+  it('a non-admin is refused on the surviving mutating routes (403)', async () => {
     const h = await makeHarness({ isAdmin: false });
     server = h.server;
-    const post = await fetch(`${h.baseUrl}/api/access/roles`, {
+    const addMember = await fetch(`${h.baseUrl}/api/access/roles/sales/members`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ displayName: 'Marketing' }),
+      body: JSON.stringify({ email: 'x@example.com' }),
     });
-    expect(post.status).toBe(403);
-    const del = await fetch(`${h.baseUrl}/api/access/roles/sales`, { method: 'DELETE' });
-    expect(del.status).toBe(403);
-  });
-
-  it('create with a reserved name → 422', async () => {
-    const h = await makeHarness();
-    server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/access/roles`, {
+    expect(addMember.status).toBe(403);
+    const assignGroup = await fetch(`${h.baseUrl}/api/access/roles/sales/groups`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ displayName: 'everyone' }),
+      body: JSON.stringify({ group: 'GTM Team' }),
+    });
+    expect(assignGroup.status).toBe(403);
+    const removeMember = await fetch(
+      `${h.baseUrl}/api/access/roles/sales/members/${encodeURIComponent('felix@example.com')}`,
+      { method: 'DELETE' },
+    );
+    expect(removeMember.status).toBe(403);
+    const unassignGroup = await fetch(
+      `${h.baseUrl}/api/access/roles/sales/groups/${encodeURIComponent('GTM Team')}`,
+      { method: 'DELETE' },
+    );
+    expect(unassignGroup.status).toBe(403);
+    const convert = await fetch(`${h.baseUrl}/api/access/roles/sales/convert-to-group`, {
+      method: 'POST',
     });
-    expect(res.status).toBe(422);
+    expect(convert.status).toBe(403);
   });
 
-  it('delete Admin → 422', async () => {
+  it('role CRUD endpoints are GONE: create/rename/delete answer 404 even for admins', async () => {
     const h = await makeHarness();
     server = h.server;
-    const res = await fetch(`${h.baseUrl}/api/access/roles/admin`, { method: 'DELETE' });
-    expect(res.status).toBe(422);
+    const created = await fetch(`${h.baseUrl}/api/access/roles`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ displayName: 'Marketing' }),
+    });
+    expect(created.status).toBe(404);
+    const renamed = await fetch(`${h.baseUrl}/api/access/roles/sales`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ newDisplayName: 'Sales Team' }),
+    });
+    expect(renamed.status).toBe(404);
+    const deleted = await fetch(`${h.baseUrl}/api/access/roles/sales`, { method: 'DELETE' });
+    expect(deleted.status).toBe(404);
+    // The roster is untouched by the dead endpoints.
+    const roster = await fetch(`${h.baseUrl}/api/access/roles`);
+    const body = (await roster.json()) as { roles: { canonical: string }[] };
+    expect(body.roles.map((r) => r.canonical)).toEqual(['admin', 'sales']);
   });
 
   it('removing own last Admin membership → 409 { kind: self-admin-removal }', async () => {
@@ -213,22 +242,16 @@ describe('/api/access/roles routes', () => {
     expect(body.kind).toBe('self-admin-removal');
   });
 
-  it('create a role then add a member → 200 fresh roster', async () => {
+  it('add a member to an existing (legacy) role → 200 fresh roster', async () => {
     const h = await makeHarness();
     server = h.server;
-    const created = await fetch(`${h.baseUrl}/api/access/roles`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ displayName: 'Marketing' }),
-    });
-    expect(created.status).toBe(200);
-    const add = await fetch(`${h.baseUrl}/api/access/roles/marketing/members`, {
+    const add = await fetch(`${h.baseUrl}/api/access/roles/sales/members`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ email: 'mkt@example.com' }),
     });
     expect(add.status).toBe(200);
     const body = (await add.json()) as { roles: { canonical: string; members: string[] }[] };
-    expect(body.roles.find((r) => r.canonical === 'marketing')!.members).toContain('mkt@example.com');
+    expect(body.roles.find((r) => r.canonical === 'sales')!.members).toContain('mkt@example.com');
   });
 });