@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,217 @@
+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 { AccessControlService } from '../access-control.service.js';
+import { CreatorAccessService } from '../creator-access.js';
+
+const KB = 'knowledge-base';
+const WS = 'ws-creator';
+
+const ALICE = { name: 'Alice', email: 'alice@example.com' };
+
+const ROLES_YAML = `roles:
+  Admin:
+    - razvan@bevel.software
+`;
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-creator-access-'));
+}
+
+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 stubWorkspaceService(workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== WS) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+    readFile: async (_id: string, wsRel: string) =>
+      fs.readFile(path.join(workspaceDir, wsRel), 'utf-8'),
+  } as unknown as WorkspaceService;
+}
+
+describe('CreatorAccessService.planForCreate', () => {
+  let root: string;
+  let repo: string;
+  let svc: CreatorAccessService;
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB);
+    await fs.mkdir(path.join(repo, 'KnowledgeBase'), { recursive: true });
+    await write(repo, 'roles.yaml', ROLES_YAML);
+    const ws = stubWorkspaceService(workspaceDir);
+    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB), KB);
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('returns null when the creator can already read via the folder chain', async () => {
+    await write(repo, 'KnowledgeBase/access.md', '---\nread:\n  - everyone\n---\n');
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/note.md`, 'file');
+    expect(plan).toBeNull();
+  });
+
+  it('a write grant folds into read — creating where you can write needs no grant', async () => {
+    await write(repo, 'KnowledgeBase/access.md', '---\nwrite:\n  - Alice <alice@example.com>\n---\n');
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/note.md`, 'file');
+    expect(plan).toBeNull();
+  });
+
+  it('a loose .md in a pre-existing unreadable folder gets a frontmatter grant', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/note.md`, 'file');
+    expect(plan?.kind).toBe('frontmatter');
+    if (plan?.kind !== 'frontmatter') return;
+    const granted = plan.apply('# Hello\n');
+    expect(granted).toBe('---\nread: Alice <alice@example.com>\n---\n# Hello\n');
+  });
+
+  it('frontmatter grant splices into existing frontmatter without touching the body', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/node.md`, 'file');
+    expect(plan?.kind).toBe('frontmatter');
+    if (plan?.kind !== 'frontmatter') return;
+    const granted = plan.apply('---\nnodeType: Process\n---\nBody\n');
+    expect(granted).toContain('nodeType: Process');
+    expect(granted).toContain('read: Alice <alice@example.com>');
+    expect(granted).toContain('Body');
+  });
+
+  it('a new folder gets its own access.md seeded, naming the creator under read:', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects`, 'dir');
+    expect(plan?.kind).toBe('seed-access-md');
+    if (plan?.kind !== 'seed-access-md') return;
+    expect(plan.wsRelPath).toBe(`${KB}/KnowledgeBase/Projects/access.md`);
+    expect(plan.apply('')).toBe('---\nread:\n  - Alice <alice@example.com>\n---\n');
+  });
+
+  it('the seed MERGES into existing access.md text — a concurrent creator grant survives', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Projects`, 'dir');
+    expect(plan?.kind).toBe('seed-access-md');
+    if (plan?.kind !== 'seed-access-md') return;
+    // Simulate the two-creator race: by write time, Bob's seed already landed.
+    const bobs = '---\nread:\n  - Bob <bob@example.com>\n---\n';
+    const merged = plan.apply(bobs);
+    expect(merged).toContain('- Bob <bob@example.com>');
+    expect(merged).toContain('- Alice <alice@example.com>');
+    // Idempotent: applying again changes nothing.
+    expect(plan.apply(merged)).toBe(merged);
+  });
+
+  it('a nested create seeds at the TOPMOST new directory, not the leaf', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/A/B/c.md`, 'file');
+    expect(plan?.kind).toBe('seed-access-md');
+    if (plan?.kind !== 'seed-access-md') return;
+    expect(plan.wsRelPath).toBe(`${KB}/KnowledgeBase/A/access.md`);
+  });
+
+  it('never targets a pre-existing directory: only new dirs are seeded', async () => {
+    await fs.mkdir(path.join(repo, 'KnowledgeBase/Existing'), { recursive: true });
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Existing/new.md`, 'file');
+    // Existing dir → the grant must land in the file's own frontmatter, not
+    // Existing/access.md (that would leak read on all its siblings).
+    expect(plan?.kind).toBe('frontmatter');
+  });
+
+  it('returns null for paths that already exist (an edit, not a create)', async () => {
+    await write(repo, 'KnowledgeBase/existing.md', 'x');
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/existing.md`, 'file');
+    expect(plan).toBeNull();
+  });
+
+  it('returns null for access.md, roles.yaml, .gitkeep, and non-KB paths', async () => {
+    expect(await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/access.md`, 'file')).toBeNull();
+    expect(await svc.planForCreate(WS, ALICE, `${KB}/roles.yaml`, 'file')).toBeNull();
+    expect(await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/.gitkeep`, 'file')).toBeNull();
+    expect(await svc.planForCreate(WS, ALICE, 'reserved-config.json', 'file')).toBeNull();
+  });
+
+  it('returns null (never throws) for a non-markdown loose file in an existing folder', async () => {
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/pic.png`, 'file');
+    expect(plan).toBeNull();
+  });
+
+  it('returns null (never throws) when the access config is unusable', async () => {
+    await fs.rm(path.join(repo, 'roles.yaml'));
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/note.md`, 'file');
+    expect(plan).toBeNull();
+  });
+
+  it('sanitises a display name that would break the Name <email> entry shape', async () => {
+    const evil = { name: 'Al<ce # ', email: 'alice@example.com' };
+    const plan = await svc.planForCreate(WS, evil, `${KB}/KnowledgeBase/Dir`, 'dir');
+    expect(plan?.kind).toBe('seed-access-md');
+    if (plan?.kind !== 'seed-access-md') return;
+    expect(plan.apply('')).toContain('- Al ce <alice@example.com>');
+  });
+
+  it('the seeded grant makes the new folder readable — including via the batched tree check', async () => {
+    const ws = stubWorkspaceService(path.join(root, WS));
+    const access = new AccessControlService(ws, KB);
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/Mine`, 'dir');
+    expect(plan?.kind).toBe('seed-access-md');
+    if (plan?.kind !== 'seed-access-md') return;
+    await write(repo, 'KnowledgeBase/Mine/access.md', plan.apply(''));
+    expect(await access.canRead(WS, ALICE.email, 'KnowledgeBase/Mine')).toBe(true);
+    const batch = await access.canReadBatch(WS, ALICE.email, [
+      'KnowledgeBase/Mine',
+      'KnowledgeBase/Mine/anything.md',
+    ]);
+    expect(batch.get('KnowledgeBase/Mine')).toBe(true);
+    expect(batch.get('KnowledgeBase/Mine/anything.md')).toBe(true);
+  });
+
+  it('the frontmatter grant makes a loose file readable via the FULL check', async () => {
+    const ws = stubWorkspaceService(path.join(root, WS));
+    const access = new AccessControlService(ws, KB);
+    const plan = await svc.planForCreate(WS, ALICE, `${KB}/KnowledgeBase/loose.md`, 'file');
+    expect(plan?.kind).toBe('frontmatter');
+    if (plan?.kind !== 'frontmatter') return;
+    await write(repo, 'KnowledgeBase/loose.md', plan.apply('# Loose\n'));
+    expect(await access.canRead(WS, ALICE.email, 'KnowledgeBase/loose.md')).toBe(true);
+  });
+});
+
+describe('CreatorAccessService.grantInExtractedFile', () => {
+  let root: string;
+  let repo: string;
+  let svc: CreatorAccessService;
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    const workspaceDir = path.join(root, WS);
+    repo = path.join(workspaceDir, KB);
+    await fs.mkdir(path.join(repo, 'KnowledgeBase'), { recursive: true });
+    await write(repo, 'roles.yaml', ROLES_YAML);
+    const ws = stubWorkspaceService(workspaceDir);
+    svc = new CreatorAccessService(ws, new AccessControlService(ws, KB), KB);
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('splices the creator grant into an on-disk .md the creator cannot read', async () => {
+    await write(repo, 'KnowledgeBase/extracted.md', '# From zip\n');
+    const text = await svc.grantInExtractedFile(WS, ALICE, `${KB}/KnowledgeBase/extracted.md`);
+    expect(text).toBe('---\nread: Alice <alice@example.com>\n---\n# From zip\n');
+  });
+
+  it('returns null when the file is already readable, non-markdown, or non-KB', async () => {
+    await write(repo, 'KnowledgeBase/access.md', '---\nread:\n  - everyone\n---\n');
+    await write(repo, 'KnowledgeBase/extracted.md', '# From zip\n');
+    expect(await svc.grantInExtractedFile(WS, ALICE, `${KB}/KnowledgeBase/extracted.md`)).toBeNull();
+    expect(await svc.grantInExtractedFile(WS, ALICE, `${KB}/KnowledgeBase/pic.png`)).toBeNull();
+    expect(await svc.grantInExtractedFile(WS, ALICE, 'reserved.md')).toBeNull();
+  });
+});

package/src/modules/access/__tests__/grant-sources.test.ts

@@ -0,0 +1,204 @@
+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 { AccessControlService } from '../access-control.service.js';
+
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+async function mkTmpRoot(): Promise<string> {
+  return fs.mkdtemp(path.join(os.tmpdir(), 'bevel-grantsrc-'));
+}
+
+async function writeFile(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 stubWorkspaceService(workspaceId: string, workspaceDir: string): WorkspaceService {
+  return {
+    getWorkspacePath: async (id: string) => {
+      if (id !== workspaceId) throw new Error(`unexpected workspace ${id}`);
+      return workspaceDir;
+    },
+  } as unknown as WorkspaceService;
+}
+
+const ROLES_YAML = `roles:
+  Admin:
+    - razvan@bevel.software
+  Engineer:
+    - ali@bevel.software
+`;
+
+const FELIX = { kind: 'user' as const, email: 'felix@example.com' };
+const ALI = { kind: 'user' as const, email: 'ali@bevel.software' };
+const RAZVAN = { kind: 'user' as const, email: 'razvan@bevel.software' };
+
+describe('AccessControlService.grantSources', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-gs';
+
+  beforeEach(async () => {
+    root = await mkTmpRoot();
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(repo, { recursive: true });
+    await writeFile(repo, 'roles.yaml', ROLES_YAML);
+    svc = new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), PROCESS_MAP_DIR);
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('a direct folder grant resolves to [{ kind: direct }]', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', FELIX);
+    expect(src.write).toEqual([{ kind: 'direct' }]);
+  });
+
+  it('an inherited grant resolves to [{ kind: ancestor, path }] (repo-relative)', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    // Resolve for a file UNDER Knowledge — the write grant is inherited from Knowledge/access.md.
+    const src = await svc.grantSources(workspaceId, 'file', 'Knowledge/Deal.md', FELIX);
+    expect(src.write).toEqual([{ kind: 'ancestor', path: 'Knowledge/access.md' }]);
+    // The path is repo-relative — no `knowledge-base/` workspace prefix.
+    const first = src.write![0] as { path: string };
+    expect(first.path.startsWith(`${PROCESS_MAP_DIR}/`)).toBe(false);
+  });
+
+  it('a closer direct grant shadows the ancestor but BOTH scopes are reported (winner first)', async () => {
+    // h3xxit's case: granted on the target AND on an ancestor. The winner is
+    // direct (closest), but the ancestor must ALSO appear so callers can tell
+    // "direct only" apart from "direct + also inherited".
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', FELIX);
+    // Closest-first: Knowledge/access.md (direct) then the root access.md (ancestor).
+    expect(src.write).toEqual([{ kind: 'direct' }, { kind: 'ancestor', path: 'access.md' }]);
+    expect(src.write![0]).toEqual({ kind: 'direct' }); // the effective/winning source
+  });
+
+  it('direct-only is distinguishable from direct+ancestor (just [direct], no tail)', async () => {
+    // Same person, granted ONLY on the target (root grants Admin, not Felix).
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', FELIX);
+    expect(src.write).toEqual([{ kind: 'direct' }]); // no ancestor tail — direct ONLY
+  });
+
+  it('reports per-verb sources: direct on one verb, ancestor on another', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Felix <felix@example.com>\n---\n');
+    // download granted directly on the file's own frontmatter; write inherited from Knowledge.
+    await writeFile(
+      repo,
+      'Knowledge/Deal.md',
+      '---\nnodeType: process\ndownload:\n  - Felix <felix@example.com>\n---\n# body\n',
+    );
+    const src = await svc.grantSources(workspaceId, 'file', 'Knowledge/Deal.md', FELIX);
+    expect(src.download).toEqual([{ kind: 'direct' }]);
+    expect(src.write).toEqual([{ kind: 'ancestor', path: 'Knowledge/access.md' }]);
+  });
+
+  it('a USER who holds a verb only via a group they belong to has NO source (the group row carries it)', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Engineer\n---\n');
+    // Ali is an Engineer (per roles.yaml) — his write flows through the GROUP, not
+    // a per-user file entry. He isn't named in any file, so there's nothing to
+    // remove for HIM here; the Engineering group is the removable principal.
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', ALI);
+    expect(src.write).toBeUndefined();
+    expect(src).toEqual({}); // no verb resolves to a per-user file entry
+  });
+
+  it('the GROUP principal itself resolves to its own file scope (direct/ancestor)', async () => {
+    // The same Engineer grant, asked about as the ROLE principal, IS a removable
+    // file entry — the group is named directly on Knowledge/access.md.
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'Engineer',
+    });
+    expect(src.write).toEqual([{ kind: 'direct' }]);
+  });
+
+  it('a verb a user holds only via everyone has NO source (not a per-user file entry)', async () => {
+    await writeFile(repo, 'access.md', '---\nread:\n  - everyone\nwrite:\n  - Admin\n---\n');
+    const src = await svc.grantSources(workspaceId, 'file', 'Knowledge/Deal.md', FELIX);
+    expect(src.read).toBeUndefined(); // resolves via everyone, but not removable as Felix
+    expect(src.write).toBeUndefined(); // Felix is not an admin and has no write
+    expect(src).toEqual({});
+  });
+
+  it('an admin on an access.md target has NO source (rescue is not a removable file entry)', async () => {
+    // No write entry names Razvan on this access.md; he holds write on it ONLY
+    // via the admin rescue. That isn't a per-target file entry, so grantSources
+    // reports no source — there's nothing to remove for him here. (The share
+    // dialog never targets an access.md directly; this is the defensive path.)
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Engineer\n---\n');
+    const src = await svc.grantSources(workspaceId, 'file', 'access.md', RAZVAN);
+    expect(src.write).toBeUndefined();
+    expect(src).toEqual({});
+  });
+
+  it("a folder-target admin whose access is via the Admin GROUP has NO per-user source", async () => {
+    // Razvan's effective write comes from the `Admin` group grant, not a per-user
+    // entry — so as a USER principal he has no removable source here (the Admin
+    // group row carries it, exactly like any other group).
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', RAZVAN);
+    expect(src.write).toBeUndefined();
+    expect(src).toEqual({});
+  });
+
+  it("a user named DIRECTLY in a file keeps a source even if they're also in a group", async () => {
+    // Razvan is in the Admin group AND named inline on Knowledge — the inline
+    // entry is a removable file grant, so his source is direct (tier-1 email
+    // beats the group at the same scope).
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(
+      repo,
+      'Knowledge/access.md',
+      '---\nwrite:\n  - Razvan <razvan@bevel.software>\n---\n',
+    );
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', RAZVAN);
+    expect(src.write).toEqual([{ kind: 'direct' }]);
+  });
+
+  it('a role principal is matched by its own scope entry, not a role indirection', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nwrite:\n  - Engineer\n---\n');
+    // The Engineer GROUP itself is granted on Knowledge — for the role principal that's a direct grant.
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', {
+      kind: 'role',
+      role: 'Engineer',
+    });
+    expect(src.write).toEqual([{ kind: 'direct' }]);
+  });
+
+  it('a principal with no effective access yields an empty map', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    const src = await svc.grantSources(workspaceId, 'file', 'Knowledge/Deal.md', FELIX);
+    expect(src).toEqual({});
+  });
+
+  it('owner folds in the lower verbs, all sourced from the owner grant', async () => {
+    await writeFile(repo, 'access.md', '---\nwrite:\n  - Admin\n---\n');
+    await writeFile(repo, 'Knowledge/access.md', '---\nowner:\n  - Felix <felix@example.com>\n---\n');
+    const src = await svc.grantSources(workspaceId, 'folder', 'Knowledge', FELIX);
+    // owner is direct; the implied read/write/download also resolve to the same direct scope.
+    expect(src.owner).toEqual([{ kind: 'direct' }]);
+    expect(src.write).toEqual([{ kind: 'direct' }]);
+    expect(src.read).toEqual([{ kind: 'direct' }]);
+    expect(src.download).toEqual([{ kind: 'direct' }]);
+  });
+});

package/src/modules/access/__tests__/kb-read-filter.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi } from 'vitest';
+import { toKbRelative, resolveReadableMap, type ReadBatchFn } from '../kb-read-filter.js';
+
+const KB = 'staging-repo';
+
+describe('toKbRelative', () => {
+  it('strips the kbDir prefix to a repo-relative path', () => {
+    expect(toKbRelative('staging-repo/Product/Knowledge/x.md', KB)).toBe('Product/Knowledge/x.md');
+  });
+
+  it('tolerates a leading ./ or /', () => {
+    expect(toKbRelative('./staging-repo/Product/x.md', KB)).toBe('Product/x.md');
+    expect(toKbRelative('/staging-repo/Product/x.md', KB)).toBe('Product/x.md');
+  });
+
+  it('tolerates a trailing slash (directory path)', () => {
+    expect(toKbRelative('staging-repo/Product/Knowledge/', KB)).toBe('Product/Knowledge');
+  });
+
+  it('returns null for a path outside the KB dir (reserved/non-KB → ungated)', () => {
+    expect(toKbRelative('some-other-file.txt', KB)).toBeNull();
+    expect(toKbRelative('Uploads/x.png', KB)).toBeNull();
+  });
+
+  it('returns null for the KB dir itself (no node)', () => {
+    expect(toKbRelative('staging-repo', KB)).toBeNull();
+    expect(toKbRelative('staging-repo/', KB)).toBeNull();
+  });
+
+  it('does not match a sibling dir that merely starts with the kbDir name', () => {
+    expect(toKbRelative('staging-repo-backup/x.md', KB)).toBeNull();
+  });
+});
+
+describe('resolveReadableMap', () => {
+  it('always allows non-KB paths and never asks the batch fn about them', async () => {
+    const batch = vi.fn<ReadBatchFn>(async () => new Map());
+    const out = await resolveReadableMap(batch, 'ws', 'u@x', KB, ['reserved.txt', 'Uploads/a.png']);
+    expect(out.get('reserved.txt')).toBe(true);
+    expect(out.get('Uploads/a.png')).toBe(true);
+    expect(batch).not.toHaveBeenCalled();
+  });
+
+  it('maps wsPaths through one batched call and keys the result by wsPath', async () => {
+    const batch = vi.fn<ReadBatchFn>(async (_w, _e, rels) => new Map(rels.map((r) => [r, r.startsWith('Product')])));
+    const out = await resolveReadableMap(batch, 'ws', 'u@x', KB, [
+      'staging-repo/Product/a.md',
+      'staging-repo/Platform/b.md',
+    ]);
+    expect(out.get('staging-repo/Product/a.md')).toBe(true);
+    expect(out.get('staging-repo/Platform/b.md')).toBe(false);
+    expect(batch).toHaveBeenCalledTimes(1);
+    expect(batch.mock.calls[0]![2]).toEqual(['Product/a.md', 'Platform/b.md']);
+  });
+
+  it('dedupes repeated KB-relative paths into one batch entry', async () => {
+    const batch = vi.fn<ReadBatchFn>(async (_w, _e, rels) => new Map(rels.map((r) => [r, true])));
+    await resolveReadableMap(batch, 'ws', 'u@x', KB, [
+      'staging-repo/Product/a.md',
+      'staging-repo/Product/a.md',
+    ]);
+    expect(batch.mock.calls[0]![2]).toEqual(['Product/a.md']);
+  });
+
+  it('fails closed: a KB path missing from the verdict resolves to not-readable', async () => {
+    const batch = vi.fn<ReadBatchFn>(async () => new Map()); // verdict omits the path
+    const out = await resolveReadableMap(batch, 'ws', 'u@x', KB, ['staging-repo/Product/a.md']);
+    expect(out.get('staging-repo/Product/a.md')).toBe(false);
+  });
+});