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

package/src/modules/access/__tests__/access-control.colliding-name-cases.test.ts

@@ -0,0 +1,113 @@
+/**
+ * The case table for a name shared by a role and a group (the moved property
+ * of decision #315, "a bare name means the role"). Before this change a bare
+ * name meant the GROUP when both existed; it now means the ROLE. Exactly the
+ * colliding bare spellings change meaning, in grants AND in denials (decided
+ * by Razvan on 2026-10-23: a bare denial means the role exactly as a bare
+ * grant does; a group denial is written `deny group/<Name>`):
+ *
+ *   rule                   | role-only member      | group-only member
+ *   -----------------------|-----------------------|----------------------
+ *   read: Reviewer         | was denied → granted  | was granted → denied
+ *   deny Reviewer          | was allowed → denied  | was denied → allowed
+ *   read: group/Reviewer   | denied (unchanged)    | granted (new token)
+ *   deny group/Reviewer    | allowed (unchanged)   | denied (new token)
+ *   read: role/Reviewer    | granted (unchanged)   | denied (unchanged)
+ *   deny role/Reviewer     | denied (unchanged)    | allowed (unchanged)
+ *
+ * A bare denial never touches the same-named group, so `read: group/Reviewer`
+ * beside `deny Reviewer` lets the group in. A name held by only one kind
+ * resolves as before. Every file with a colliding bare entry is listed by
+ * the groups roster (`bareNameResolvesToRole`) so an Admin can rewrite it as
+ * `group/<Name>` or `role/<Name>`.
+ */
+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 { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import { AccessControlService } from '../access-control.service.js';
+
+const KB_DIR = 'knowledge-base';
+const WS = 'ws-colliding-name';
+
+const ADMIN = 'admin@x.io';
+const ROLE_MEMBER = 'role-member@x.io';
+const GROUP_MEMBER = 'group-member@x.io';
+const DOC = 'Docs/Plan.md';
+
+const ROOT_FILES: Record<string, string> = {
+  'roles.yaml': `roles:\n  Admin:\n    - ${ADMIN}\n  Reviewer:\n    - ${ROLE_MEMBER}\n`,
+  'groups.yaml': `groups:\n  Reviewer:\n    - ${GROUP_MEMBER}\n`,
+  'access.md': '---\nwrite:\n  - Admin\n---\nwrite:\n  - Admin\n',
+  [DOC]: '# Plan\n',
+};
+
+describe('a name shared by a role and a group: grant and deny case table', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-colliding-name-'));
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB_DIR);
+    for (const [rel, text] of Object.entries(ROOT_FILES)) {
+      await fs.mkdir(path.dirname(path.join(repo, rel)), { recursive: true });
+      await fs.writeFile(path.join(repo, rel), text);
+    }
+    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 });
+  });
+
+  /** Who may read DOC when the Docs folder's read list is `entries`. */
+  async function readers(entries: string[]): Promise<{ role: boolean; group: boolean }> {
+    const body = `read:\n${entries.map((e) => `  - ${e}\n`).join('')}`;
+    await fs.writeFile(path.join(repo, 'Docs/access.md'), `---\nwrite:\n  - Admin\n---\n${body}`);
+    svc.invalidate(WS);
+    return {
+      role: await svc.canRead(WS, ROLE_MEMBER, DOC),
+      group: await svc.canRead(WS, GROUP_MEMBER, DOC),
+    };
+  }
+
+  it('a bare grant reaches the role only', async () => {
+    expect(await readers(['Reviewer'])).toEqual({ role: true, group: false });
+  });
+
+  it('a bare denial reaches the role only: the members of the same-named group are untouched', async () => {
+    expect(await readers(['everyone', 'deny Reviewer'])).toEqual({ role: false, group: true });
+  });
+
+  it('a group grant beside a bare denial lets the group in', async () => {
+    expect(await readers(['group/Reviewer', 'deny Reviewer'])).toEqual({ role: false, group: true });
+  });
+
+  it('group/<Name> grants and denies the group only', async () => {
+    expect(await readers(['group/Reviewer'])).toEqual({ role: false, group: true });
+    expect(await readers(['everyone', 'deny group/Reviewer'])).toEqual({ role: true, group: false });
+  });
+
+  it('role/<Name> grants and denies the role only', async () => {
+    expect(await readers(['role/Reviewer'])).toEqual({ role: true, group: false });
+    expect(await readers(['everyone', 'deny role/Reviewer'])).toEqual({ role: false, group: true });
+  });
+
+  it('a bare name held only by a group still means the group, in grants and denials', async () => {
+    await fs.writeFile(
+      path.join(repo, 'roles.yaml'),
+      `roles:\n  Admin:\n    - ${ADMIN}\n`,
+    );
+    expect(await readers(['Reviewer'])).toEqual({ role: false, group: true });
+    expect(await readers(['everyone', 'deny Reviewer'])).toEqual({ role: true, group: false });
+  });
+});

package/src/modules/access/__tests__/access-control.frontmatter-head.test.ts

@@ -0,0 +1,117 @@
+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 { NodeFs } from '../../kb-fs/node-fs.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { AccessControlService } from '../access-control.service.js';
+
+const KB = 'knowledge-base';
+const RULE = 'read:\n  - deny everyone\n  - Product Manager\n';
+const ali = 'ali@bevel.software'; // no role
+const felix = 'felix@example.com'; // Product Manager
+
+/**
+ * A file's own access rules live in its frontmatter, so the read checks read
+ * a file only as far as its frontmatter reaches — a line, for a file with
+ * none. That is what keeps a batch over a tree of large transcripts (grep's,
+ * the explorer's) from reading the whole tree, and these pin that the head
+ * answers exactly as the whole file would, fence rule and all.
+ */
+describe('AccessControlService — a file is read only as far as its frontmatter', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-frontmatter-head';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-fm-head-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, KB);
+    await fs.mkdir(path.join(repo, 'Open'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n  Product Manager:\n    - felix@example.com\n');
+    await fs.writeFile(path.join(repo, 'Open', 'access.md'), '---\nread:\n  - everyone\n---\n');
+    svc = new AccessControlService(
+      { getWorkspacePath: async () => workspaceDir } as unknown as WorkspaceService,
+      KB,
+      new NodeFs(),
+    );
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  const put = (name: string, content: string | Buffer) => fs.writeFile(path.join(repo, 'Open', name), content);
+  const verdicts = async (name: string) => {
+    const rel = `Open/${name}`;
+    const batch = await svc.canReadBatch(workspaceId, ali, [rel]);
+    const felixBatch = await svc.canReadBatch(workspaceId, felix, [rel]);
+    return {
+      ali: batch.get(rel),
+      felix: felixBatch.get(rel),
+      single: await svc.canRead(workspaceId, ali, rel),
+    };
+  };
+
+  it('honours the rules of a file far too large to read whole, at once', async () => {
+    await put('huge.md', `---\n${RULE}---\n`);
+    // 600 MB, sparse: more text than one string can hold, so a read of the
+    // whole file could not even be decoded, and its rule would be missed.
+    await fs.truncate(path.join(repo, 'Open', 'huge.md'), 600 * 1024 * 1024);
+    expect(await verdicts('huge.md')).toEqual({ ali: false, felix: true, single: false });
+  });
+
+  it('reads a frontmatter longer than any one read through to its closing fence', async () => {
+    await put('long-fm.md', `---\nsummary: "${'x'.repeat(200_000)}"\n${RULE}---\nbody\n`);
+    expect(await verdicts('long-fm.md')).toEqual({ ali: false, felix: true, single: false });
+  });
+
+  it('scans a frontmatter line far longer than one read once, not again with every read', async () => {
+    // A long line inside the frontmatter, then the rule; and a closing fence
+    // padded with 3 MB of spaces, which stays a fence however long it runs.
+    const longValue = (chars: number) =>
+      `---\nsummary: "${'x'.repeat(chars)}"\n${RULE}${' '.repeat(3_000_000)}---${' '.repeat(3_000_000)}\nbody\n`;
+    await put('long-value.md', longValue(32_000_000));
+    expect(await verdicts('long-value.md')).toEqual({ ali: false, felix: true, single: false });
+    // How the cost grows, not how long it takes on this machine: a line 16
+    // times longer costs about 16 times as much scanned once, and far more
+    // (about 60 times, measured) scanned again with every read. The slowest
+    // short check against the fastest long one, so noise only helps a scan
+    // that is linear pass.
+    const timed = async (name: string, chars: number): Promise<number> => {
+      await put(name, `---\nsummary: "${'x'.repeat(chars)}"\n${RULE}---\n`);
+      const started = performance.now();
+      await svc.canReadBatch(workspaceId, ali, [`Open/${name}`]);
+      return performance.now() - started;
+    };
+    const short: number[] = [];
+    const long: number[] = [];
+    for (let i = 0; i < 3; i++) {
+      short.push(await timed(`short-${i}.md`, 2_000_000));
+      long.push(await timed(`long-${i}.md`, 32_000_000));
+    }
+    expect(Math.min(...long) / Math.max(...short)).toBeLessThan(32);
+  }, 60_000);
+
+  it('applies the fence rule as the whole-file scan does: CRLF, a BOM, padding around the fence', async () => {
+    await put('crlf.md', `---\r\n${RULE.replace(/\n/g, '\r\n')}---\r\nbody\r\n`);
+    await put('bom.md', `\uFEFF---\n${RULE}---\n`);
+    await put('padded.md', `${' '.repeat(5_000)}---  \n${RULE}  ---\n`);
+    for (const name of ['crlf.md', 'bom.md', 'padded.md']) {
+      expect(await verdicts(name), name).toEqual({ ali: false, felix: true, single: false });
+    }
+  });
+
+  it('finds no rules where the whole-file scan finds none', async () => {
+    // A fenced block that is not at the top is body, not frontmatter.
+    await put('later.md', `# title\n---\n${RULE}---\n`);
+    // An opening fence never closed is no frontmatter either.
+    await put('unclosed.md', `---\n${RULE}`);
+    // A first line that is long, and no fence, ends the read at once.
+    await put('long-line.md', `${'x'.repeat(3_000_000)}\n---\n${RULE}---\n`);
+    await put('empty.md', '');
+    for (const name of ['later.md', 'unclosed.md', 'long-line.md', 'empty.md']) {
+      expect(await verdicts(name), name).toEqual({ ali: true, felix: true, single: true });
+    }
+  });
+});

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' });