@bevel-software/platform-core-backend 0.33.0 → 0.35.0

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

@@ -63,32 +63,38 @@ function parseDomainList(raw: string): string[] {
     .filter((d) => d.length > 0);
 }
 import { SpillStore } from '../modules/workspace/spill-store.js';
+import { TmpSweeper } from '../modules/workspace/workspace-tmp.js';
 import { AgentUploadStore, assertUploadsRootOutsideWorkspaces } from '../modules/workspace/agent-upload.store.js';
 import { AgentDownloadStore, type IAgentDownloadStore } from '../modules/workspace/agent-download.store.js';
 import { createDownloadFetcherIdentifier } from '../modules/workspace/agent-download.routes.js';
-import { WorkerPatternMatcher } from '../modules/workspace/bounded-matcher.js';
-import type { IPatternMatcher } from '../modules/workspace/pattern-matcher.contract.js';
 import type { Request } from 'express';
 import {
+  assertRipgrep,
   DocExtractService,
+  RipgrepPatternMatcher,
   WorkerDocumentExtractor,
   type IDocumentExtractor,
+  type IPatternMatcher,
 } from '../modules/workspace/index.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
 import { AuthService } from '../modules/auth/auth.service.js';
 import { AccountHooks, type IAccountHooks } from '../modules/auth/account-hooks.js';
 import { AccountErasureService } from '../modules/auth/account-erasure.service.js';
 import { OidcAuthProvider, oidcSettingsFrom } from '../modules/auth/oidc-auth-provider.js';
-import { createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
+import { authCookieSecure, createAuthMiddleware, readAuthCookie } from '../modules/auth/auth.middleware.js';
 import { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
 import { AccessMutationService } from '../modules/access/access-mutation.service.js';
 import { CreatorAccessService } from '../modules/access/creator-access.js';
 import { ChangeReadGate } from '../modules/access/change-read-gate.js';
 import { GroupsAdminService } from '../modules/access/groups-admin.service.js';
 import { UserAccessRemovalService } from '../modules/access/user-access-removal.service.js';
-import { makeRolesYamlWriteValidator } from '../modules/access-model/roles-yaml-guard.js';
-import { PendingSkillsService, SkillService } from '../modules/skills/index.js';
-import { PendingToolsService, ToolManualService } from '../modules/tool-manuals/index.js';
+import { makeRolesYamlWriteValidator } from '../modules/access-model/index.js';
+// The implementations, from their files: the module entries offer them as
+// types only, so nothing that imports an entry loads a service.
+import { SkillService } from '../modules/skills/skills.service.js';
+import { PendingSkillsService } from '../modules/skills/pending-skills.service.js';
+import { ToolManualService } from '../modules/tool-manuals/tool-manuals.service.js';
+import { PendingToolsService } from '../modules/tool-manuals/pending-tools.service.js';
 import { McpServerEditService } from '../modules/tool-manuals/mcp-server-edit.service.js';
 import { ToolDeleteService } from '../modules/tool-manuals/tool-delete.service.js';
 import {
@@ -105,6 +111,7 @@ import {
   MarketplaceCompilerService,
   KbPluginSource,
 } from '../modules/plugins/index.js';
+import { noAgentConfigurations, type IAgentScopeResolver } from '../modules/agent-scope/index.js';
 import { MarketplaceRepoService } from '../modules/marketplace/index.js';
 import {
   GitHubFacadeCredentialsService,
@@ -164,6 +171,7 @@ import { AgentAuditService, retentionDaysFrom } from '../modules/audit/agent-aud
 import { readAgentPreamble, type AgentPreambleReader } from '../modules/agent-instructions/index.js';
 import {
   agentGuideSections,
+  guideStartText,
   joinGuideSections,
   type AgentGuideReader,
   type AgentGuideSectionsReader,
@@ -255,7 +263,9 @@ export interface CoreServices {
   agentUploadStore: AgentUploadStore;
   /** The bytes `request_file_download` captured, held until their one-time link is fetched or expires. */
   agentDownloadStore: IAgentDownloadStore;
-  /** Runs a caller's `grep` pattern off the request thread under a budget; its workers end when the graph stops. */
+  /** Sweeps every workspace's `tmp/` folder of entries older than seven days, hourly; started and stopped with the graph. */
+  tmpSweeper: TmpSweeper;
+  /** Runs a caller's `grep` pattern in ripgrep under a budget; its running searches end when the graph stops. */
   patternMatcher: IPatternMatcher;
   /**
    * Every user a download fetch identifies itself as, by its bearer and its
@@ -287,6 +297,12 @@ export interface CoreServices {
    * `read_file` of the guide's name answer. See modules/agent-guide.
    */
   agentGuide: AgentGuideReader;
+  /**
+   * The start of that guide and the list of its sections: what a `read_file`
+   * of the guide's name answers, the same as `get_agent_guide` with no
+   * `section`. See `guideStartText`.
+   */
+  agentGuideStart: AgentGuideReader;
   /** The same guide as its sections, each with its title — what `get_agent_guide` lists and serves one of. */
   agentGuideSections: AgentGuideSectionsReader;
   mcpServerEditService: McpServerEditService;
@@ -309,6 +325,12 @@ export interface CoreServices {
   pluginJoinRequestJobs: PluginJoinRequestJobs;
   /** Which plugins hold which skills (inline or linked) — see `PluginLinkIndex`. */
   pluginLinkIndex: PluginLinkIndex;
+  /**
+   * Connecting as an agent configuration: the choices offered at consent and key
+   * mint, and the scope every agent surface narrows a connection to — see
+   * `modules/agent-scope`.
+   */
+  agentScopeService: IAgentScopeResolver;
   /** Link / unlink / repair shared skills into plugins. */
   pluginLinksService: PluginLinksService;
   pluginRenameService: PluginRenameService;
@@ -432,6 +454,9 @@ export async function createCoreServices(
   // (see `git-version.ts`): every clone, fetch and refresh below depends on it,
   // so an unsupported binary is better surfaced here than at the first merge.
   await assertGitVersion();
+  // The same for ripgrep, which the grep tool searches with and has no
+  // fallback for (see `ripgrep-version.ts`).
+  await assertRipgrep();
   // What tells this knowledge base's locks, migration ledger and secrets
   // loader apart from another's in the same process and database. Empty for
   // the default schema, so a single-tenant deployment keeps the lock ids and
@@ -767,6 +792,10 @@ export async function createCoreServices(
   // 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);
+  // What the chat, the SharePoint reader and tool chains stage in a
+  // workspace's `tmp/` folder lives seven days past its last change; the file
+  // tools read it through the `__tmp__/` ref meanwhile (see workspace-tmp.ts).
+  const tmpSweeper = new TmpSweeper((signal) => workspaceService.sweepTmp(undefined, undefined, signal));
   // The upload route an agent lands files by, so their content never passes
   // through the model. Bytes live BESIDE the workspaces root (never inside
   // one) until the apply commits them or the token expires — checked here
@@ -795,7 +824,7 @@ export async function createCoreServices(
       'captured download bytes wait there for their one-time links, so a root inside a workspace would let the ' +
       'file tools read them. Point AGENT_UPLOADS_ROOT at a directory whose parent is outside WORKSPACES_ROOT.',
   });
-  const patternMatcher = new WorkerPatternMatcher();
+  const patternMatcher = new RipgrepPatternMatcher();
   const agentDownloadStore = new AgentDownloadStore({
     root: agentDownloadsRoot,
     publicBaseUrl: config.publicBackendUrl,
@@ -851,6 +880,17 @@ export async function createCoreServices(
   // The link index resolves manifests against the released catalog, and the
   // plugin index counts through it (inline + linked), so it comes first.
   const pluginLinkIndex = new PluginLinkIndex(workspaceService, skillService, accessControl, kb, pluginSource);
+  // What "Connect as" offers and what a connection made as an agent loads:
+  // the distribution's resolver (`CorePorts.agentScope`), made HERE with the
+  // core services it reads through — its configurations behind the person's
+  // read gate, `plugins:` expanded through the link index above — or core's
+  // default, which offers no agent and loads nothing for a path it cannot
+  // read. Made once, before anything consults it: the tool-context resolver
+  // below captures it, as the routes the server mounts do, so there is one
+  // resolver in effect and no later assignment to miss. Core owns the
+  // mechanism and no configuration (see `modules/agent-scope`).
+  const agentScopeService: IAgentScopeResolver =
+    ports.agentScope?.({ workspaceService, accessControl, kb, disk, pluginLinkIndex }) ?? noAgentConfigurations();
   const pluginIndexService = new PluginIndexService(
     workspaceService,
     accessControl,
@@ -1343,11 +1383,13 @@ export async function createCoreServices(
   // serves the same composition to the local bridge and the frontend card.
   const readPreamble: AgentPreambleReader = () => readAgentPreamble(workspaceService, kb, disk);
   // The guide every agent is told to read first, composed when asked for —
-  // the layout is read per call, so a name the setup save applies lands
-  // without a restart, and the distribution's hook sees every composition.
+  // the layout and the default branch are read per call, so a name the setup
+  // save applies lands without a restart, and the distribution's hook sees
+  // every composition.
   const agentGuideSectionsReader: AgentGuideSectionsReader = () =>
-    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName });
+    agentGuideSections(kb.layout, ports.agentGuide, { kbDirName, defaultBranch: kb.defaultBranch });
   const agentGuide: AgentGuideReader = async () => joinGuideSections(await agentGuideSectionsReader());
+  const agentGuideStart: AgentGuideReader = async () => guideStartText(await agentGuideSectionsReader());
   // The Audit log. Records through the proxy below (every call an external
   // agent makes), reads keys through the key service so their shape is
   // defined once, and prunes past the retention setting — read per sweep, so
@@ -1487,6 +1529,7 @@ export async function createCoreServices(
     kbDirName: kbDirName,
     creatorAccess,
     loadActiveGroups,
+    agentScope: agentScopeService,
   });
   const writeAccess = ports.writeAccess ?? alwaysWritable;
   // The branch every tool call runs on is resolved by the handler, before the
@@ -1496,8 +1539,8 @@ export async function createCoreServices(
     defaultBranch: () => kb.defaultBranch,
     isMissing: (branch) => workspaceService.isBranchMissing(branch),
   });
-  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService);
-  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService);
+  const toolAuthMiddleware = createToolAuthMiddleware(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
+  const verifyToolToken = createTokenVerifier(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
   // Every credential kind this server issues — connection keys, internal
   // tokens and app sessions (bearer or cookie) — so a fetch carrying another
   // user's identity of ANY kind is refused the link.
@@ -1508,7 +1551,7 @@ export async function createCoreServices(
   // Read-only manual endpoints accept the above PLUS a browser JWT, so a
   // logged-in user can browse the catalog with their session. Execution routes
   // keep `toolAuthMiddleware` (no JWT), so a session can read but not invoke.
-  const manualAuthMiddleware = createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService);
+  const manualAuthMiddleware = createManualAuthMiddleware(externalApiKeyService, internalTokenService, authService, mcpOAuthProvider);
 
   // Recovery-bot identity: a synthetic `recovery-bot@bevel.local` user
   // backing (a) the recovery agent's commit authorship and (b) the
@@ -1575,7 +1618,7 @@ export async function createCoreServices(
       settings: () => oidcSettingsFrom(settings),
       publicBackendUrl: config.publicBackendUrl,
       publicFrontendUrl: config.publicFrontendUrl,
-      cookieSecure: config.publicBackendUrl.startsWith('https'),
+      cookieSecure: authCookieSecure(config.publicBackendUrl),
       // A real sign-in proves the values that sign-in used. Recorded against
       // those — under their own key — so it says nothing about any saved
       // since, and cannot overwrite what was recorded about them.
@@ -1619,6 +1662,7 @@ export async function createCoreServices(
     workspaceService,
     workflowService,
     accessControl,
+    disk,
     kbDirName,
     () => kb.defaultBranch,
     eventBus,
@@ -1673,6 +1717,7 @@ export async function createCoreServices(
     spillStore,
     agentUploadStore,
     agentDownloadStore,
+    tmpSweeper,
     patternMatcher,
     agentDownloadFetcher,
     documentExtractor,
@@ -1687,6 +1732,7 @@ export async function createCoreServices(
     pendingToolsService,
     readAgentPreamble: readPreamble,
     agentGuide,
+    agentGuideStart,
     agentGuideSections: agentGuideSectionsReader,
     pluginIndexService,
     pluginProvisionService,
@@ -1694,6 +1740,7 @@ export async function createCoreServices(
     joinRequestsService,
     pluginJoinRequestJobs,
     pluginLinkIndex,
+    agentScopeService,
     pluginLinksService,
     pluginRenameService,
     marketplaceCompiler,

package/src/core/lifecycle.ts

@@ -6,6 +6,7 @@ import { noteBesideCheckout } from '../modules/workspace/startup/beside-checkout
 import { unregisterBevelSecretsVariableLoader } from '../modules/secrets-vault/secrets-variable-loader.js';
 import type { WorkflowService } from '../modules/workflow/workflow.service.js';
 import type { PluginJoinRequestJobs } from '../modules/plugins/join-request-jobs.service.js';
+import type { TmpSweeper } from '../modules/workspace/workspace-tmp.js';
 import { printable } from '../shared/printable.js';
 import { logger } from '../shared/logging.js';
 
@@ -293,6 +294,8 @@ export interface BootableCore {
   kbStartupRunner: Pick<KbStartupRunner, 'runAll' | 'retryUntilMaintained'>;
   workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches' | 'tidyAfterSweep'>;
   pluginJoinRequestJobs: Pick<PluginJoinRequestJobs, 'startSweeping'>;
+  /** The periodic sweep of every workspace's `tmp/` folder, started here and stopped by {@link stopCore}. */
+  tmpSweeper: Pick<TmpSweeper, 'startSweeping'>;
   /**
    * The startup phase's retry, when the boot survived an unreachable remote
    * and is asking again on a timer; null otherwise. Set by {@link startCore},
@@ -336,6 +339,13 @@ export async function startCore<C extends BootableCore>(
     });
   }
 
+  // The seven-day sweep of every workspace's `tmp/` folder (see
+  // `workspace-tmp.ts`), now and hourly. Needs nothing the startup phase
+  // provides — it reads the workspaces root and nothing else — so it is not
+  // held behind it, and a remote that is down does not leave staged files to
+  // pile up. Stopped by `stopCore`.
+  core.tmpSweeper.startSweeping();
+
   // The KB startup phase — AFTER the distribution's onBoot, because a FATAL
   // template finding raised there must stop the boot before anything seeds
   // from that template; the runner then brings every branch up to this build
@@ -448,6 +458,16 @@ export interface CoreStopDeps {
   agentUploadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
   /** The agent download store, whose sweep deletes captured bytes nobody fetched — stopped for the same reason. */
   agentDownloadStore?: { stopSweeping(): void; drainSweep(): Promise<void> };
+  /**
+   * The sweep of the workspaces' `tmp/` folders: stopped with this graph, so
+   * an evicted tenant's graph leaves no timer behind, and its sweep in flight
+   * cancelled (it removes nothing more) and then awaited within the stop's
+   * deadline, so the next graph over the same root does not meet it still
+   * walking there — unless one filesystem call outlasts that deadline, after
+   * which the cancelled sweep still removes nothing. Optional: a caller that
+   * has not built one passes nothing.
+   */
+  tmpSweeper?: { stopSweeping(): void; drainSweep(): Promise<void> };
   /**
    * The grep pattern matcher, whose worker threads are this graph's own: ended
    * here so a graph a tenant host evicts leaves no worker behind. Optional: a
@@ -555,6 +575,7 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // running to stop deleting.
   deps.agentUploadStore?.stopSweeping();
   deps.agentDownloadStore?.stopSweeping();
+  deps.tmpSweeper?.stopSweeping();
   // A startup phase still asking for an unreachable remote stops asking:
   // synchronous, and nothing after it must be able to clone into a
   // workspaces folder that is about to belong to nobody.
@@ -587,15 +608,18 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.agentDownloadStore) {
     await bounded(deps.agentDownloadStore.drainSweep(), remaining(), 'finishing the download sweep', log);
   }
+  if (deps.tmpSweeper) {
+    await bounded(deps.tmpSweeper.drainSweep(), remaining(), "finishing the workspaces' tmp sweep", log);
+  }
   // The tidy-up in flight fetches and deletes branches through the pool and
   // the default branch's checkout: awaited, so the next graph for this
   // tenant cannot find a branch deletion still running under it.
   if (deps.workflowService) {
     await bounded(deps.workflowService.drainTidy(), remaining(), 'finishing the branch tidy-up', log);
   }
-  // Its workers end with the graph; a search still running is answered busy.
+  // Its ripgrep runs end with the graph; a search still running is answered busy or stopped.
   if (deps.patternMatcher) {
-    await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
+    await bounded(deps.patternMatcher.close(), remaining(), 'ending the running searches', log);
   }
   // Likewise: an extraction still running is answered busy, and nothing about its file is remembered.
   if (deps.documentExtractor) {

package/src/index.ts

@@ -26,7 +26,7 @@ export {
   type ServerExtensions,
   type ToolSurfaceCtx,
 } from './core/create-core-server.js';
-export { noopRecoveryAgent, type CorePorts } from './core/core-ports.js';
+export { noopRecoveryAgent, type AgentScopeCollaborators, type CorePorts } from './core/core-ports.js';
 // Logging: the contract, the slot a shell installs its sink into, and the
 // tagged-logger lookup every module logs through. See shared/logging.ts.
 export { setLogger, logger, createConsoleLogger } from './shared/logging.js';

package/src/modules/access/__tests__/access-control.admin-root-floor.test.ts

@@ -242,6 +242,17 @@ describe('Admin write floor at the repository root', () => {
       expect(await fs.readFile(path.join(repo, 'access.md'), 'utf-8')).toContain('write:\n  - Admin');
     });
 
+    it('lets the root drop a GROUP named Admin — group/Admin is never the role', async () => {
+      await write(repo, 'access.md', '---\n---\nwrite:\n  - Admin\n  - group/Admin\n');
+      const group = { kind: 'role' as const, role: 'group/Admin' };
+      await expect(mutation.revoke(WS, 'folder', '', group, ADMIN, 'write')).resolves.toMatchObject({
+        changed: true,
+      });
+      const after = await fs.readFile(path.join(repo, 'access.md'), 'utf-8');
+      expect(after).not.toContain('group/Admin');
+      expect(after).toContain('write:\n  - Admin'); // the role's line is untouched
+    });
+
     it('refuses deny-here on a PERSON who is an admin at the root, with the reason, and writes nothing', async () => {
       const before = await fs.readFile(path.join(repo, 'access.md'), 'utf-8');
       for (const email of [ADMIN, OWNER]) {
@@ -310,6 +321,7 @@ describe('Admin write floor at the repository root', () => {
           { emit: () => {} } as unknown as WorkflowEventBus,
           usersDbDouble(),
           testKbContext({ kbDirName: KB }),
+          new NodeFs(),
         ),
       );
       server = await new Promise<Server>((resolve) => {

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