@bevel-software/platform-core-backend 0.7.5 → 0.9.0

package/src/core/create-core-services.ts

@@ -5,7 +5,7 @@ import {
   configureBranchModel,
   validateBranchModel,
   PROTECTED_BRANCHES,
-  GROUPS_DIR,
+  PLUGINS_DIR,
 } from '@bevel-software/platform-shared';
 import { CoreConfig } from '../core-config.js';
 import { getDb, type Database } from '../modules/database/connection.js';
@@ -13,7 +13,11 @@ import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
 import { WorkspaceService } from '../modules/workspace/workspace.service.js';
 import { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
-import { KbSeedService } from '../modules/workspace/kb-seed.service.js';
+import { KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
+import { GroupsToPluginsStep } from '../modules/workspace/startup/steps/groups-to-plugins.step.js';
+import { TemplateFilesStep } from '../modules/workspace/startup/steps/template-files.step.js';
+import { RolesYamlStep } from '../modules/workspace/startup/steps/roles-yaml.step.js';
+import { buildSeedTree } from '../modules/workspace/startup/steps/seed-tree.js';
 import { DeploymentSettingsService } from '../modules/settings/deployment-settings.service.js';
 
 /** `a.com, b.com` → `['a.com','b.com']`, tolerating a leading `@` or `.`. */
@@ -33,7 +37,8 @@ import { AccessControlService } from '../modules/access/access-control.service.j
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
 import { ToolManualService } from '../modules/tool-manuals/index.js';
-import { GroupIndexService, GroupProvisionService, JoinRequestsService } from '../modules/groups/index.js';
+import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
+import { PluginIndexService, PluginProvisionService, JoinRequestsService } from '../modules/plugins/index.js';
 import {
   DbSecretsVaultService,
   McpOAuthDiscoveryService,
@@ -93,7 +98,12 @@ export interface CoreServices {
   config: CoreConfig;
   db: Database;
   workspaceService: WorkspaceService;
-  kbSeedService: KbSeedService;
+  /**
+   * The KB startup phase (see `startup/on-server-start.ts`): run at the
+   * deployment's two quiet moments — boot, before routes mount, and
+   * first-time setup completion — and never again while the process serves.
+   */
+  kbStartupRunner: KbStartupRunner;
   spillStore: SpillStore;
   accessControl: AccessControlService;
   creatorAccess: CreatorAccessService;
@@ -102,8 +112,9 @@ export interface CoreServices {
   skillService: SkillService;
   pendingSkillsService: PendingSkillsService;
   toolManualService: ToolManualService;
-  groupIndexService: GroupIndexService;
-  groupProvisionService: GroupProvisionService;
+  mcpServerEditService: McpServerEditService;
+  pluginIndexService: PluginIndexService;
+  pluginProvisionService: PluginProvisionService;
   joinRequestsService: JoinRequestsService;
   authService: AuthService;
   authMiddleware: ReturnType<typeof createAuthMiddleware>;
@@ -211,27 +222,39 @@ export async function createCoreServices(
     kbDirName,
     () => settings.resolve('gitUsername') || 'x-access-token',
   );
-  // Seed (or top-up) the KB remote before the first clone so the rest of the app
-  // can keep assuming the remote already carries the protected branches + base
-  // scaffolding — a fresh or partially-populated remote no longer needs to have
-  // been forked from the standalone template.
-  const kbSeedService = new KbSeedService(
-    () => settings.resolve('kbRepoUrl'),
-    config.kbTemplateDir,
-    // Getters, not values: the branch model can arrive from the setup screen
-    // after this object exists, and seeding is the first thing that needs it.
-    () => [...PROTECTED_BRANCHES],
-    () => DEFAULT_BRANCH,
+  // The KB startup phase: every seeding, scaffolding and migration concern,
+  // run through one runner at the deployment's quiet moments (boot + setup
+  // completion) instead of lazily on branch loads. Root folders this
+  // distribution reserves on top of core's two are a plain value, not a
+  // getter: they are named in the composition root rather than collected on
+  // the setup screen, so there is nothing to re-read.
+  const extraDirs = ports.kbExtraRootDirs ?? [];
+  // Core's steps first, in dependency order — the Groups→Plugins migration
+  // reshapes trees the template top-up would otherwise re-scaffold — then
+  // whatever the distribution appends.
+  const kbStartupSteps = [
+    new GroupsToPluginsStep(),
+    new TemplateFilesStep(extraDirs),
+    new RolesYamlStep([config.adminEmail]),
+    ...(ports.kbStartupSteps ?? []),
+  ];
+  const kbStartupRunner = new KbStartupRunner({
+    // Getters, not values: the remote and the branch model can arrive from the
+    // setup screen after this object exists, and the setup-completion run is
+    // the first thing that needs them.
+    kbRepoUrl: () => settings.resolve('kbRepoUrl'),
+    gitUsername: () => settings.resolve('gitUsername') || 'x-access-token',
+    workspacesRoot: config.workspacesRoot,
+    kbDirName,
+    templateDir: config.kbTemplateDir,
+    defaultBranch: () => DEFAULT_BRANCH,
+    protectedBranches: () => [...PROTECTED_BRANCHES],
     // The deployment owner is the initial Admin of a freshly seeded KB — the
     // same answer `SEED_ADMIN_EMAILS` used to ask for a second time.
-    [config.adminEmail],
-    () => settings.resolve('gitUsername') || 'x-access-token',
-    // Root folders this distribution reserves on top of core's two. A plain
-    // value, not a getter: these are named in the composition root rather than
-    // collected on the setup screen, so there is nothing to re-read.
-    ports.kbExtraRootDirs ?? [],
-  );
-  workspaceService.setSeedService(kbSeedService);
+    seedAdminEmails: [config.adminEmail],
+    steps: kbStartupSteps,
+    buildSeedTree: buildSeedTree(config.kbTemplateDir, extraDirs, [config.adminEmail]),
+  });
   // Shared, workspace-independent store for oversized `call_tool_chain` results,
   // read back via `read_file`. Sibling of `workspacesRoot`, never committed.
   const spillStore = new SpillStore(config.spillRoot);
@@ -260,15 +283,15 @@ export async function createCoreServices(
   const routineWritePolicy = new RoutineWritePolicyService();
   // Skills: discovered from the default-branch workspace only (global catalog).
   const skillService = new SkillService(workspaceService, accessControl, kbDirName);
-  // Tool manuals: user-authored `*.tool` files under `Groups/` in the default
+  // Tool manuals: user-authored `*.tool` files under `Plugins/` in the default
   // branch — access-controlled like Skills, served to external agents via
   // `GET /api/agent/all-tools` and registered on the MCP proxy's UTCP client.
   const toolManualService = new ToolManualService(workspaceService, accessControl, kbDirName);
-  // Groups: the folders under `Groups/` that carry a
+  // Plugins: the folders under `Plugins/` that carry a
   // team's skills AND the tools they need. Enumerated for EVERY authenticated
-  // caller — a group they cannot read still exists for them, as a locked one —
+  // caller — a plugin they cannot read still exists for them, as a locked one —
   // with the counts read off the two catalogs above rather than a second scan.
-  const groupIndexService = new GroupIndexService(
+  const pluginIndexService = new PluginIndexService(
     workspaceService,
     accessControl,
     skillService,
@@ -384,16 +407,28 @@ export async function createCoreServices(
     workflowHooks,
   );
 
-  // Join requests: derived entirely from two copies of a group's `access.md`
+  // Join requests: derived entirely from two copies of a plugin's `access.md`
   // (the request's branch vs the default branch), so it holds no state — it
   // only needs to read files at refs and to close a request whose proposals
   // have all landed.
   const joinRequestsService = new JoinRequestsService(workspaceService, workflowService);
-  // Group provisioning — the one privileged door that brings `Groups/<name>/`
-  // folders into existence (named groups and personal folders alike). Commits
+  // Server-scoped MCP editing — the tool page's edit form. One server's truth
+  // spans a plugin's mcp.json AND plugin.json extensions block, and this is
+  // the ONE writer that rewrites both entries and commits them together (see
+  // McpServerEditService).
+  const mcpServerEditService = new McpServerEditService(
+    workspaceService,
+    workflowService,
+    accessControl,
+    toolManualService,
+    kbDirName,
+  );
+
+  // Plugin provisioning — the one privileged door that brings `Plugins/<name>/`
+  // folders into existence (named plugins and personal folders alike). Commits
   // INLINE through the same pipeline the pending-commits worker uses, so the
   // folder's rules are at HEAD before the endpoint answers.
-  const groupProvisionService = new GroupProvisionService(
+  const pluginProvisionService = new PluginProvisionService(
     workspaceService,
     workflowService,
     accessControl,
@@ -422,16 +457,16 @@ export async function createCoreServices(
   // caches are independent, so the split preserves behavior.)
   fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
     if (branch !== DEFAULT_BRANCH) return;
-    // Skills, tools and the group index all live under `Groups/`, so one
+    // Skills, tools and the plugin index all live under `Plugins/`, so one
     // touch check drives all three caches. An access grant lands as a
-    // default-branch change to `Groups/<group>/access.md`, so this is also
-    // what makes a newly-granted group unlock within one round-trip instead
+    // default-branch change to `Plugins/<plugin>/access.md`, so this is also
+    // what makes a newly-granted plugin unlock within one round-trip instead
     // of one TTL.
-    const touched = paths.some((p) => p.startsWith(`${kbDirName}/${GROUPS_DIR}/`));
+    const touched = paths.some((p) => p.startsWith(`${kbDirName}/${PLUGINS_DIR}/`));
     if (touched) {
       toolManualService.invalidate();
       skillService.invalidate();
-      groupIndexService.invalidate();
+      pluginIndexService.invalidate();
     }
   });
 
@@ -448,7 +483,7 @@ export async function createCoreServices(
     if (!('branch' in event) || event.branch !== DEFAULT_BRANCH) return;
     toolManualService.invalidate();
     skillService.invalidate();
-    groupIndexService.invalidate();
+    pluginIndexService.invalidate();
   });
 
   // Admin = `Admin` role in roles.yaml, resolved through the access model on the
@@ -567,7 +602,12 @@ export async function createCoreServices(
   });
   // RFC 9728 pointer carried on every MCP 401 challenge so OAuth-capable
   // clients discover the AS. Single source of truth for the resource id.
+  // Userinfo is stripped for the same reason the server's own copy strips it
+  // (see create-core-server.ts): the pointer rides an unauthenticated 401
+  // challenge, and a `user:pass@` from PUBLIC_BACKEND_URL must not ride along.
   const mcpResourceUrl = new URL('/api/mcp', config.publicBackendUrl);
+  mcpResourceUrl.username = '';
+  mcpResourceUrl.password = '';
   const mcpResourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(mcpResourceUrl);
   const mcpAuthMiddleware = createMcpAuthMiddleware(
     authService,
@@ -675,8 +715,9 @@ export async function createCoreServices(
   return {
     config,
     db,
+    mcpServerEditService,
     workspaceService,
-    kbSeedService,
+    kbStartupRunner,
     settings,
     kbDirName,
     spillStore,
@@ -687,8 +728,8 @@ export async function createCoreServices(
     skillService,
     pendingSkillsService,
     toolManualService,
-    groupIndexService,
-    groupProvisionService,
+    pluginIndexService,
+    pluginProvisionService,
     joinRequestsService,
     authService,
     authMiddleware,

package/src/index.ts

@@ -1,69 +1,69 @@
-/**
- * @bevel-software/platform-core-backend — the open-source core of the Bevel platform:
- * git-backed knowledge workspace, workflow (branches / change requests /
- * locks / SSE), skills, tool manuals + registry + auth, secrets vault, access
- * control, diff/backup ledger, code-mode and the remote MCP surface.
- *
- * Composition entry points:
- *   - `new CoreConfig()`                     — env-driven core configuration
- *   - `createCoreServices(config, ports)`    — construct every core service
- *   - `createCoreServer(core, ext, opts)`    — the Express app (fixed mount order)
- *
- * Importing this package ALSO applies the global Express `Request`
- * augmentation (`req.userId` / `req.userEmail` / token payloads) — the
- * middleware modules re-exported below carry the `declare global` blocks, so
- * consumers get the augmented types without a side-effect import of their own.
- *
- * Finer-grained internals are available via the `./modules/*` subpath exports.
- */
-
-export { CoreConfig } from './core-config.js';
-export { createCoreServices, type CoreServices } from './core/create-core-services.js';
-export {
-  createCoreServer,
-  type ServerExtensions,
-  type ToolSurfaceCtx,
-} from './core/create-core-server.js';
-export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
-
-// Packaged assets (migrations/, kb-template/) + the migration runners.
-export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
-export {
-  runCoreMigrations,
-  runEnterpriseMigrations,
-} from './modules/database/migrate.js';
-export { getDb, type Database } from './modules/database/connection.js';
-
-// Build identity surfaced by GET /api/health.
-export { GIT_SHA, resolveGitSha } from './version.js';
-
-// Express `Request` augmentation carriers (userId/userEmail — auth.middleware;
-// token payloads — tool-auth + external-api-key interface). Re-exported by
-// VALUE/type so the `declare global` blocks land in this package's public
-// declaration graph.
-export { createAuthMiddleware, AUTH_COOKIE_NAME } from './modules/auth/auth.middleware.js';
-export {
-  createToolAuthMiddleware,
-  createManualAuthMiddleware,
-} from './modules/tool-auth/tool-auth.middleware.js';
-export type {
-  IExternalApiKeyService,
-  ExternalApiKeySummary,
-} from './modules/tool-auth/external-api-key.interface.js';
-
-// Key port/seam types an overlay implements.
-export type { ISessionSink } from './modules/workspace/session-sink.js';
-export type {
-  ISystemNoticeSink,
-  RecoveryAgentRunner,
-} from './modules/workflow/pending-commits.worker.js';
-export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
-export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
-export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
-export {
-  WorkflowHooks,
-  type CommitValidationHook,
-  type CommitValidationContext,
-  type PreWriteHook,
-  type PreWriteContext,
-} from './modules/workflow/workflow-hooks.js';
+/**
+ * @bevel-software/platform-core-backend — the open-source core of the Bevel platform:
+ * git-backed knowledge workspace, workflow (branches / change requests /
+ * locks / SSE), skills, tool manuals + registry + auth, secrets vault, access
+ * control, diff/backup ledger, code-mode and the remote MCP surface.
+ *
+ * Composition entry points:
+ *   - `new CoreConfig()`                     — env-driven core configuration
+ *   - `createCoreServices(config, ports)`    — construct every core service
+ *   - `createCoreServer(core, ext, opts)`    — the Express app (fixed mount order)
+ *
+ * Importing this package ALSO applies the global Express `Request`
+ * augmentation (`req.userId` / `req.userEmail` / token payloads) — the
+ * middleware modules re-exported below carry the `declare global` blocks, so
+ * consumers get the augmented types without a side-effect import of their own.
+ *
+ * Finer-grained internals are available via the `./modules/*` subpath exports.
+ */
+
+export { CoreConfig } from './core-config.js';
+export { createCoreServices, type CoreServices } from './core/create-core-services.js';
+export {
+  createCoreServer,
+  type ServerExtensions,
+  type ToolSurfaceCtx,
+} from './core/create-core-server.js';
+export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+
+// Packaged assets (migrations/, kb-template/) + the migration runners.
+export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
+export {
+  runCoreMigrations,
+  runEnterpriseMigrations,
+} from './modules/database/migrate.js';
+export { getDb, type Database } from './modules/database/connection.js';
+
+// Build identity surfaced by GET /api/health.
+export { GIT_SHA, resolveGitSha } from './version.js';
+
+// Express `Request` augmentation carriers (userId/userEmail — auth.middleware;
+// token payloads — tool-auth + external-api-key interface). Re-exported by
+// VALUE/type so the `declare global` blocks land in this package's public
+// declaration graph.
+export { createAuthMiddleware, AUTH_COOKIE_NAME } from './modules/auth/auth.middleware.js';
+export {
+  createToolAuthMiddleware,
+  createManualAuthMiddleware,
+} from './modules/tool-auth/tool-auth.middleware.js';
+export type {
+  IExternalApiKeyService,
+  ExternalApiKeySummary,
+} from './modules/tool-auth/external-api-key.interface.js';
+
+// Key port/seam types an overlay implements.
+export type { ISessionSink } from './modules/workspace/session-sink.js';
+export type {
+  ISystemNoticeSink,
+  RecoveryAgentRunner,
+} from './modules/workflow/pending-commits.worker.js';
+export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
+export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
+export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
+export {
+  WorkflowHooks,
+  type CommitValidationHook,
+  type CommitValidationContext,
+  type PreWriteHook,
+  type PreWriteContext,
+} from './modules/workflow/workflow-hooks.js';

package/src/modules/access/__tests__/access-control.atref-batch.test.ts

@@ -1,98 +1,98 @@
-import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-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 execFileAsync = promisify(execFile);
-const PROCESS_MAP_DIR = 'knowledge-base';
-
-/**
- * `canWriteBatchAtRef` / the batched at-ref own-entries read — backed by ONE
- * `git cat-file --batch` process whose length-prefixed output we parse by
- * hand, so exercise it against a REAL git repo: found blobs, a path missing
- * at the ref (the `<spec> missing` line), a path with spaces, and frontmatter
- * deny resolution — all in one batch, order-aligned.
- */
-describe('AccessControlService — at-ref batch reads (git cat-file --batch)', () => {
-  let root: string;
-  let repo: string;
-  let svc: AccessControlService;
-  const workspaceId = 'ws-atref-1';
-  const admin = 'razvan@bevel.software';
-
-  async function git(...args: string[]): Promise<void> {
-    await execFileAsync('git', ['-C', repo, ...args]);
-  }
-
-  beforeAll(async () => {
-    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-atref-'));
-    const workspaceDir = path.join(root, workspaceId);
-    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
-    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
-
-    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n');
-    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
-    await fs.writeFile(path.join(repo, 'Knowledge/plain.md'), '# plain\n');
-    await fs.writeFile(
-      path.join(repo, 'Knowledge/denied.md'),
-      '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
-    );
-    await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
-
-    await execFileAsync('git', ['init', '-b', 'main', repo]);
-    await git('config', 'user.email', 'test@example.com');
-    await git('config', 'user.name', 'Test');
-    await git('add', '-A');
-    await git('commit', '-m', 'seed');
-
-    const stub = {
-      getWorkspacePath: async () => workspaceDir,
-      // Fixture repo has no remote; at-ref model loading fetches best-effort.
-      ensureRemotesFetched: async () => undefined,
-    } as unknown as WorkspaceService;
-    svc = new AccessControlService(stub, PROCESS_MAP_DIR);
-  });
-
-  afterAll(async () => {
-    await fs.rm(root, { recursive: true, force: true });
-  });
-
-  it('resolves a mixed batch in one pass: grants, frontmatter deny, spaces, and a missing path', async () => {
-    const paths = [
-      'Knowledge/plain.md', // dir-chain Admin grant → true
-      'Knowledge/denied.md', // own frontmatter deny → false
-      'Knowledge/with space.md', // found blob whose SPEC contains spaces → true
-      'Knowledge/not-there.md', // missing at the ref (`<spec> missing` line) → dir-chain verdict
-    ];
-    const map = await svc.canWriteBatchAtRef(workspaceId, 'main', admin, paths);
-    expect(map).not.toBeNull();
-    expect(map!.get('Knowledge/plain.md')).toBe(true);
-    expect(map!.get('Knowledge/denied.md')).toBe(false);
-    expect(map!.get('Knowledge/with space.md')).toBe(true);
-    expect(map!.get('Knowledge/not-there.md')).toBe(true);
-  });
-
-  it('matches the single-path at-ref resolution exactly', async () => {
-    // The batch is a pure performance change — verdicts must be identical to
-    // the per-path `git show` route the single-path helper still uses.
-    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/denied.md')).toBe(false);
-    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/plain.md')).toBe(true);
-  });
-
-  it('eligibleWritersForPathsAtRef honours the same batched own-entries', async () => {
-    const map = await svc.eligibleWritersForPathsAtRef(workspaceId, 'main', [
-      'Knowledge/plain.md',
-      'Knowledge/denied.md',
-    ]);
-    expect(map).not.toBeNull();
-    expect(map!.get('Knowledge/plain.md')!.roles).toContain('Admin');
-    // The per-user deny strips razvan from the expanded email set.
-    expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
-    expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
-  });
-});
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+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 execFileAsync = promisify(execFile);
+const PROCESS_MAP_DIR = 'knowledge-base';
+
+/**
+ * `canWriteBatchAtRef` / the batched at-ref own-entries read — backed by ONE
+ * `git cat-file --batch` process whose length-prefixed output we parse by
+ * hand, so exercise it against a REAL git repo: found blobs, a path missing
+ * at the ref (the `<spec> missing` line), a path with spaces, and frontmatter
+ * deny resolution — all in one batch, order-aligned.
+ */
+describe('AccessControlService — at-ref batch reads (git cat-file --batch)', () => {
+  let root: string;
+  let repo: string;
+  let svc: AccessControlService;
+  const workspaceId = 'ws-atref-1';
+  const admin = 'razvan@bevel.software';
+
+  async function git(...args: string[]): Promise<void> {
+    await execFileAsync('git', ['-C', repo, ...args]);
+  }
+
+  beforeAll(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-atref-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, PROCESS_MAP_DIR);
+    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
+
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'roles:\n  Admin:\n    - razvan@bevel.software\n');
+    await fs.writeFile(path.join(repo, 'access.md'), '---\nwrite:\n  - Admin\n---\n');
+    await fs.writeFile(path.join(repo, 'Knowledge/plain.md'), '# plain\n');
+    await fs.writeFile(
+      path.join(repo, 'Knowledge/denied.md'),
+      '---\nwrite:\n  - deny razvan <razvan@bevel.software>\n---\n# denied\n',
+    );
+    await fs.writeFile(path.join(repo, 'Knowledge/with space.md'), '# spaced\n');
+
+    await execFileAsync('git', ['init', '-b', 'main', repo]);
+    await git('config', 'user.email', 'test@example.com');
+    await git('config', 'user.name', 'Test');
+    await git('add', '-A');
+    await git('commit', '-m', 'seed');
+
+    const stub = {
+      getWorkspacePath: async () => workspaceDir,
+      // Fixture repo has no remote; at-ref model loading fetches best-effort.
+      ensureRemotesFetched: async () => undefined,
+    } as unknown as WorkspaceService;
+    svc = new AccessControlService(stub, PROCESS_MAP_DIR);
+  });
+
+  afterAll(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('resolves a mixed batch in one pass: grants, frontmatter deny, spaces, and a missing path', async () => {
+    const paths = [
+      'Knowledge/plain.md', // dir-chain Admin grant → true
+      'Knowledge/denied.md', // own frontmatter deny → false
+      'Knowledge/with space.md', // found blob whose SPEC contains spaces → true
+      'Knowledge/not-there.md', // missing at the ref (`<spec> missing` line) → dir-chain verdict
+    ];
+    const map = await svc.canWriteBatchAtRef(workspaceId, 'main', admin, paths);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')).toBe(true);
+    expect(map!.get('Knowledge/denied.md')).toBe(false);
+    expect(map!.get('Knowledge/with space.md')).toBe(true);
+    expect(map!.get('Knowledge/not-there.md')).toBe(true);
+  });
+
+  it('matches the single-path at-ref resolution exactly', async () => {
+    // The batch is a pure performance change — verdicts must be identical to
+    // the per-path `git show` route the single-path helper still uses.
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/denied.md')).toBe(false);
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, 'Knowledge/plain.md')).toBe(true);
+  });
+
+  it('eligibleWritersForPathsAtRef honours the same batched own-entries', async () => {
+    const map = await svc.eligibleWritersForPathsAtRef(workspaceId, 'main', [
+      'Knowledge/plain.md',
+      'Knowledge/denied.md',
+    ]);
+    expect(map).not.toBeNull();
+    expect(map!.get('Knowledge/plain.md')!.roles).toContain('Admin');
+    // The per-user deny strips razvan from the expanded email set.
+    expect(map!.get('Knowledge/denied.md')!.emails.has(admin)).toBe(false);
+    expect(map!.get('Knowledge/plain.md')!.emails.has(admin)).toBe(true);
+  });
+});