@bevel-software/platform-core-backend 0.29.0 → 0.31.0

package/migrations/meta/_journal.json

@@ -127,6 +127,13 @@
       "when": 1791359019161,
       "tag": "0017_atlassian_account_links",
       "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1792106401545,
+      "tag": "0018_agent_events_page",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.29.0",
-    "@bevel-software/platform-shared": "0.29.0"
+    "@bevel-software/platform-shared": "0.31.0",
+    "@bevel-software/platform-mcp-core": "0.31.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/test-repositories.ts

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises';
+
+/**
+ * The repository roots `testKbRepository` placed beside a suite's workspaces
+ * root (`<workspacesRoot>.repository`). A suite removes its fixture root, not
+ * what sits next to it, so `test-setup.ts` removes these once the file's
+ * suites are done. Kept free of imports so the setup file can load it without
+ * pulling in a module a suite means to mock.
+ */
+const roots = new Set<string>();
+
+export function recordTestRepositoryRoot(root: string): void {
+  roots.add(root);
+}
+
+export async function removeTestRepositoryRoots(): Promise<void> {
+  const pending = [...roots];
+  roots.clear();
+  await Promise.all(
+    pending.map((root) => fs.rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })),
+  );
+}

package/src/__tests__/workspace-service.ts

@@ -0,0 +1,69 @@
+import path from 'node:path';
+import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
+import type { IGitRunner } from '../shared/git.contract.js';
+import type { ITreeWalker } from '../shared/fs.contract.js';
+import type { KbContext } from '../shared/kb-context.js';
+import { KbRepository, repositoryDirFor } from '../modules/workspace/kb-repository.js';
+import type { IKbRepository } from '../modules/workspace/kb-repository.contract.js';
+import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { KbStartupRunner, type KbStartupRunnerOptions } from '../modules/workspace/startup/kb-startup-runner.js';
+import { recordTestRepositoryRoot } from './test-repositories.js';
+
+/**
+ * The repository a suite's services share when it builds them by hand: one
+ * next to the workspaces root (see `repositoryDirFor`), as the composition
+ * root would place it there for a deployment with no backups root. Removed
+ * once the file's suites are done (see `test-repositories.ts`): a suite's
+ * teardown removes its fixture root, not what sits beside it.
+ */
+export function testKbRepository(
+  workspacesRoot: string,
+  kbDirName: string,
+  kbRepoUrl: string | (() => string),
+  gitRunner?: IGitRunner,
+): IKbRepository {
+  const dir = repositoryDirFor(workspacesRoot, kbDirName);
+  recordTestRepositoryRoot(path.dirname(dir));
+  return new KbRepository({
+    dir,
+    kbRepoUrl: typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl,
+    gitRunner: gitRunner ?? new NodeGitRunner(),
+  });
+}
+
+/**
+ * A WorkspaceService as a suite builds it: the constructor's arguments, with
+ * the repository — which only the composition root builds in the product —
+ * made here when the suite passes none.
+ */
+export function newWorkspaceService(
+  workspacesRoot: string,
+  kbRepoUrl: string | (() => string),
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch'>,
+  disk: ITreeWalker,
+  gitRunner: IGitRunner = new NodeGitRunner(),
+  setAsideRoot?: string,
+  aroundSetAside?: (workspaceId: string, move: () => Promise<void>) => Promise<void>,
+  repository?: IKbRepository,
+): WorkspaceService {
+  return new WorkspaceService(
+    workspacesRoot,
+    kbRepoUrl,
+    kb,
+    disk,
+    gitRunner,
+    setAsideRoot,
+    aroundSetAside,
+    repository ?? testKbRepository(workspacesRoot, kb.kbDirName, kbRepoUrl, gitRunner),
+  );
+}
+
+/** A KbStartupRunner as a suite builds it — the repository made here when the suite passes none. */
+export function newKbStartupRunner(
+  opts: Omit<KbStartupRunnerOptions, 'repository'> & { repository?: IKbRepository },
+): KbStartupRunner {
+  return new KbStartupRunner({
+    ...opts,
+    repository: opts.repository ?? testKbRepository(opts.workspacesRoot, opts.kbDirName, opts.kbRepoUrl, opts.gitRunner),
+  });
+}

package/src/core/__tests__/lifecycle.test.ts

@@ -5,6 +5,7 @@ import { createShutdown, stopCore, withStartupTask, type LeasedWorker } from '..
 import { holdCommitWorkerLease, holdable } from '../lifecycle.js';
 import { BevelSecretsVariableLoader, registerBevelSecretsVariableLoader } from '../../modules/secrets-vault/secrets-variable-loader.js';
 import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
+import { WorkerPatternMatcher } from '../../modules/workspace/bounded-matcher.js';
 
 /** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
 function fakeLease(answers: boolean[]) {
@@ -537,6 +538,21 @@ describe('stopCore', () => {
     ]);
   });
 
+  it('ends the grep matcher\'s workers, so an evicted graph leaves no search running behind it', async () => {
+    const g = graph();
+    const patternMatcher = new WorkerPatternMatcher();
+    // A search holding a worker for its whole 5 s budget when the graph is stopped.
+    const running = patternMatcher.search('^(a+)+$', '').matchingLines([`${'a'.repeat(39)}!`], 1);
+    await new Promise((r) => setTimeout(r, 100));
+    const started = Date.now();
+    await stopCore({ ...g.core, patternMatcher } as never);
+    await expect(running).rejects.toMatchObject({ status: 503, details: { code: 'search_busy' } });
+    expect(Date.now() - started).toBeLessThan(1_000);
+    // Closed for good: nothing after the stop starts a worker.
+    await expect(patternMatcher.search('b', '').matchingLines(['b'], 1)).rejects.toMatchObject({ status: 503 });
+    expect(g.order.at(-1)).toBe('db.end');
+  });
+
   it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {
     const g = graph();
     const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };

package/src/core/catalog-revision.ts

@@ -12,9 +12,9 @@ const log = logger('catalog-revision');
  * skill the default branch serves them, right now.
  *
  * It exists for a client that holds a long-lived connection and cannot be told
- * anything: the local `hexis-mcp` server. The hosted endpoint is stateless, so
- * every request there already rebuilds its surface from the live registry
- * (`mcp.routes.stateless.test.ts` pins that). A process on someone's laptop
+ * anything: the local `hexis-mcp` server. The hosted endpoint reads it too, on
+ * every request, to pick the caller's cached tool client: a new revision is a
+ * new build (`mcp.surface-cache.test.ts` pins that). A process on someone's laptop
  * registered the deployment's manual ONCE, at startup, and would otherwise
  * serve that startup's toolset until it is restarted. Polling this tells it —
  * cheaply, and without a second way for the catalogs to be read — exactly when

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

@@ -470,12 +470,13 @@ export async function createCoreServer(
   // `get_skill`. Warnings only; it never refuses a save.
   const allowedToolsChecker = new AllowedToolsChecker(core.toolRegistry, core.toolManualService, core.kb);
   // `delete_branch` sees change requests as `get_change_request` does.
-  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee);
+  // The history tools take the per-file read the file itself takes (`accessControl`).
+  registerWorkflowTools(core.toolRegistry, toolsRouter, ta, th, core.kb, changeRequestScope(core.accessControl, core.kb).maySee, core.accessControl, agentAccessGate);
   // The five read tools over change requests. Separate from the workflow tools
   // because they are the only ones that gate their whole payload on the
   // caller's read access, so they take the access service and nothing else.
   registerChangeRequestReadTools(core.toolRegistry, toolsRouter, ta, th, core.accessControl, core.kb);
-  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk);
+  const workspaceTools = registerWorkspaceTools(core.toolRegistry, toolsRouter, ta, th, core.spillStore, core.docExtractService, core.accessControl, core.kb, agentAccessGate, core.routineWritePolicy, core.sessionSink, allowedToolsChecker, core.changeGate, core.agentUploadStore, core.agentGuide, core.agentDownloadStore, core.starterPackService, core.disk, core.patternMatcher);
   // `open_page` — the knowledge-base page shown inside a chat. Registered
   // here, on the same router as the file tools, because it answers with
   // `read_file`'s own read: the read hook, the access gate and the

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

@@ -17,6 +17,8 @@ import { getDb, type Database } from '../modules/database/connection.js';
 import { runCoreMigrations } from '../modules/database/migrate.js';
 import { coreMigrationsDir } from '../assets.js';
 import { WorkspaceService } from '../modules/workspace/workspace.service.js';
+import { KbRepository, repositoryDirFor } from '../modules/workspace/kb-repository.js';
+import type { IKbRepository } from '../modules/workspace/kb-repository.contract.js';
 import { AccountLinkService } from '../modules/embed/account-link.service.js';
 import type { EmbedService } from '../modules/embed/embed.service.js';
 import { composeEmbedService } from './compose-embed.js';
@@ -62,6 +64,8 @@ import { SpillStore } from '../modules/workspace/spill-store.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 { DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
 import { UuidSessionSink, type ISessionSink } from '../modules/workspace/session-sink.js';
@@ -113,7 +117,7 @@ import { ConnectionProbeService } from '../modules/connection-probe/index.js';
 import { GitService } from '../modules/workflow/git/git.service.js';
 import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
 import { PullRequestService } from '../modules/workflow/git/pull-request.service.js';
-import { WorkspaceMutex } from '../modules/kb-fs/mutex.js';
+import { WorkspaceIdMutex, WorkspaceMutex } from '../modules/kb-fs/mutex.js';
 import { assertGitVersion } from '../modules/workflow/git/git-version.js';
 import { DiffService } from '../modules/diff/diff.service.js';
 import { ReviewWorkflowService } from '../modules/workflow/review-workflow/review-workflow.service.js';
@@ -243,6 +247,8 @@ 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. */
+  patternMatcher: IPatternMatcher;
   /**
    * Every user a download fetch identifies itself as, by its bearer and its
    * session cookie — none when it carries none that verifies — so the
@@ -570,6 +576,32 @@ export async function createCoreServices(
    * Under the backups root: a persistent volume of its own, and one nothing
    * sweeps (see the runner's `reconcileClonesWithConfiguredRepository`).
    */
+  // Shared mutex so git and diff operations on the same workspace serialize
+  // against each other — a backup-reseed races a concurrent commit otherwise.
+  // Keyed by the CANONICAL workspace id: a route's Express-decoded `:id` and
+  // a tool's encoded one reserve the same clone (see `WorkspaceIdMutex`).
+  const workspaceMutex = new WorkspaceIdMutex();
+  /**
+   * The knowledge base's ONE repository: every branch workspace is a worktree
+   * of it (see `kb-repository.ts`). One instance, handed to the workspace
+   * service, the startup phase and (through the workspace service) the git
+   * layer, so one fetch serves every workspace and the writes to its one
+   * config file are serialized in one place. Git operations in the worktrees
+   * are not serialized against each other beyond the workspace mutex: git's
+   * own locks cover a repository shared by worktrees.
+   *
+   * Under the backups root, like the set-aside copies: a persistent volume in
+   * every shipped compose file, so no new mount is needed, and outside the
+   * workspaces root, where the orphan sweep never sees it. The folder name
+   * starts with a dot, which no branch — and so no backup ledger's workspace
+   * id — can. On hexis-cloud every tenant has its own backups root: one
+   * repository per tenant.
+   */
+  const kbRepository: IKbRepository = new KbRepository({
+    dir: repositoryDirFor(config.workspacesRoot, kbDirName, path.join(config.backupsRoot, '.kb-repository')),
+    kbRepoUrl: () => repositorySource.url(),
+    gitRunner,
+  });
   const replacedWorkingCopiesRoot = path.join(config.backupsRoot, 'replaced-working-copies');
   /**
    * What must leave with a working copy that is set aside, whoever sets it
@@ -635,6 +667,7 @@ export async function createCoreServices(
             );
           });
       }),
+    kbRepository,
   );
   // The KB startup phase: every seeding, scaffolding and migration concern,
   // run through one runner at the deployment's quiet moments (boot + setup
@@ -672,6 +705,9 @@ export async function createCoreServices(
     // The same folder the workspace service sets aside into — see
     // `replacedWorkingCopiesRoot` above for why the two must agree.
     setAsideRoot: replacedWorkingCopiesRoot,
+    // The one repository every branch workspace is a worktree of — the same
+    // instance the workspace service holds (see `kbRepository` above).
+    repository: kbRepository,
     kbDirName,
     templateDir: config.kbTemplateDir,
     defaultBranch: () => kb.defaultBranch,
@@ -741,6 +777,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 agentDownloadStore = new AgentDownloadStore({
     root: agentDownloadsRoot,
     publicBaseUrl: config.publicBackendUrl,
@@ -827,9 +864,6 @@ export async function createCoreServices(
   // registers its listener here, after this returns (see `AccountHooks`).
   const accountHooks = new AccountHooks();
 
-  // Shared mutex so git and diff operations on the same workspace serialize
-  // against each other — a backup-reseed races a concurrent commit otherwise.
-  const workspaceMutex = new WorkspaceMutex();
   // Workflow lifecycle hooks — the ONE registry this composition shares
   // between GitService (advisory commit validation), the agent-access gate
   // (the blocking agentRead / preWrite hooks), and the composition root,
@@ -1598,6 +1632,7 @@ export async function createCoreServices(
     spillStore,
     agentUploadStore,
     agentDownloadStore,
+    patternMatcher,
     agentDownloadFetcher,
     docExtractService,
     accessControl,

package/src/core/lifecycle.ts

@@ -448,6 +448,12 @@ 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 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
+   * caller that has not built one passes nothing.
+   */
+  patternMatcher?: { close(): Promise<void> };
   /**
    * The workflow service, for the tidy-up it runs after each sweep (closing
    * empty requests, removing leftover branches): detached from whatever
@@ -581,6 +587,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   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.
+  if (deps.patternMatcher) {
+    await bounded(deps.patternMatcher.close(), remaining(), 'ending the search workers', log);
+  }
   await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
   if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
   await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);

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

@@ -129,6 +129,11 @@ function lsTreeBuilds(): number {
   return spawnLog.filter((argv) => argv.includes('ls-tree')).length;
 }
 
+/** Ref resolutions through git: none, since the ref files answer. */
+function revParses(): number {
+  return spawnLog.filter((argv) => argv.includes('rev-parse')).length;
+}
+
 /** Batched reads of a commit's access tree: one per build. */
 function catFileBatches(): number {
   return spawnLog.filter((argv) => argv.includes('cat-file')).length;
@@ -190,6 +195,7 @@ describe('AccessControlService — at-ref model cache', () => {
   let repo: string;
   let other: string;
   let svc: AccessControlService;
+  let stub: WorkspaceService;
   const workspaceId = 'ws-atref-cache';
   const admin = 'razvan@bevel.software';
   const DOC = 'Team/Doc.md';
@@ -242,7 +248,7 @@ describe('AccessControlService — at-ref model cache', () => {
     await git(other, 'config', 'user.email', 'other@example.com');
     await git(other, 'config', 'user.name', 'Other');
 
-    const stub = {
+    stub = {
       getWorkspacePath: async () => workspaceDir,
       // The real service TTLs this at 30s; the stub always fetches so a push
       // from `other` is visible on the next gate call.
@@ -386,9 +392,11 @@ describe('AccessControlService — at-ref model cache', () => {
     // The seed holds roles.yaml and two access.md files; a read per file was
     // what the build used to cost, and what a server forking a large heap
     // cannot afford.
+    // One listing and one batch build the model; a second batch reads the
+    // asked path's own entries, once per commit and path (see the memo test).
     expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
     expect(lsTreeBuilds()).toBe(1);
-    expect(catFileBatches()).toBe(1);
+    expect(catFileBatches()).toBe(2);
     expect(fileShows()).toBe(0);
     // Both access files were read through the batch: Team's denial is seen.
     await pushFromOther('deny Admin in Team', () =>
@@ -396,7 +404,7 @@ describe('AccessControlService — at-ref model cache', () => {
     );
     expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(false);
     expect(lsTreeBuilds()).toBe(2);
-    expect(catFileBatches()).toBe(2);
+    expect(catFileBatches()).toBe(4);
     expect(fileShows()).toBe(0);
   });
 
@@ -534,7 +542,139 @@ describe('AccessControlService — at-ref model cache', () => {
     // ...and nothing was pinned: the next call, with git answering in full,
     // builds again and answers.
     expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
-    expect(catFileBatches()).toBe(batchesBefore + 2);
+    // Three batches: the refused build, then the build that answered and the
+    // asked path's own entries.
+    expect(catFileBatches()).toBe(batchesBefore + 3);
+  });
+
+  it('resolves refs from the ref files and remembers own entries at a commit: a repeated gate call starts no git', async () => {
+    // First call at this commit: the model is built (two git calls) and the
+    // asked path's own entries are read (one batch). The refs themselves —
+    // `origin/main`, and the candidates a short name tries — come from the
+    // ref files, so no `rev-parse` runs at all.
+    expect(await svc.canWriteBatchAtRef(workspaceId, 'origin/main', admin, [DOC])).toEqual(new Map([[DOC, true]]));
+    expect(revParses()).toBe(0);
+    expect(lsTreeBuilds()).toBe(1);
+    expect(catFileBatches()).toBe(2);
+
+    // The same gate again, and the single-path gate for the same path: the
+    // model and the own entries are both remembered, so apart from the
+    // fixture's own fetch nothing is started.
+    spawnLog.length = 0;
+    expect(await svc.canWriteBatchAtRef(workspaceId, 'origin/main', admin, [DOC])).toEqual(new Map([[DOC, true]]));
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    expect(await svc.canWriteAtRef(workspaceId, 'main', admin, DOC)).toBe(true);
+    expect(spawnLog.filter((argv) => !argv.includes('fetch'))).toEqual([]);
+
+    // A path not asked before at this commit is read, and only that path.
+    spawnLog.length = 0;
+    expect(await svc.canWriteBatchAtRef(workspaceId, 'origin/main', admin, [DOC, QUOTED_DOC])).toEqual(
+      new Map([
+        [DOC, true],
+        [QUOTED_DOC, false],
+      ]),
+    );
+    expect(catFileBatches()).toBe(1);
+    expect(revParses()).toBe(0);
+  });
+
+  it('asks git for a ref the files cannot decide, instead of reading it as missing', async () => {
+    // An annotated tag names a tag object, not a commit; the reader steps
+    // aside and the gate resolves it through `rev-parse <tag>^{commit}` —
+    // one process, the answer git gives, never "no such ref".
+    await git(repo, 'tag', '-a', 'v1', '-m', 'v1', 'origin/main');
+    expect(await svc.canWriteAtRef(workspaceId, 'v1', admin, DOC)).toBe(true);
+    expect(revParses()).toBe(1);
+    expect(lsTreeBuilds()).toBe(1);
+    // The same commit under its branch name: resolved from the files, the
+    // model already held.
+    spawnLog.length = 0;
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    expect(revParses()).toBe(0);
+    expect(lsTreeBuilds()).toBe(0);
+  });
+
+  it('knows from the tree that a path is absent at a commit, and reads nothing for it', async () => {
+    // A change request that adds a file asks about it at the base, where it
+    // does not exist yet. The model's listing already named every path the
+    // commit carries, so the absence is a fact about the commit: remembered,
+    // and not read — on the first call or any later one.
+    const NEW = 'Team/New.md';
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    spawnLog.length = 0;
+    expect(await svc.canWriteBatchAtRef(workspaceId, 'origin/main', admin, [NEW])).toEqual(new Map([[NEW, true]]));
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, NEW)).toBe(true);
+    expect(catFileBatches()).toBe(0);
+    expect(spawnLog.filter((argv) => !argv.includes('fetch'))).toEqual([]);
+  });
+
+  it("keeps a commit's tree up to the cap and not past it, as an absent path's cost shows", async () => {
+    // The seed carries seven paths. A service that may hold seven keeps the
+    // tree, so an absent path is answered without a read; one that may hold
+    // six does not keep it, so the same path is read on every call.
+    const NEW = 'Team/New.md';
+    const limited = (treeIndexMaxPaths: number) =>
+      new AccessControlService(stub, PROCESS_MAP_DIR, new NodeFs(), [], undefined, undefined, { treeIndexMaxPaths });
+    const keeps = limited(7);
+    expect(await keeps.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    spawnLog.length = 0;
+    expect(await keeps.canWriteAtRef(workspaceId, 'origin/main', admin, NEW)).toBe(true);
+    expect(await keeps.canWriteAtRef(workspaceId, 'origin/main', admin, NEW)).toBe(true);
+    expect(catFileBatches()).toBe(0);
+    const drops = limited(6);
+    expect(await drops.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    spawnLog.length = 0;
+    expect(await drops.canWriteAtRef(workspaceId, 'origin/main', admin, NEW)).toBe(true);
+    expect(await drops.canWriteAtRef(workspaceId, 'origin/main', admin, NEW)).toBe(true);
+    expect(catFileBatches()).toBe(2);
+  });
+
+  it('lets the oldest models give their tree up past the budget, and they still answer', async () => {
+    // Seven paths at the first commit, eight at the second, a budget of ten:
+    // remembering the second puts the first past the budget. The first
+    // model keeps answering gates without a rebuild; only an absent path at
+    // it is read again, while at the second it costs nothing.
+    const NEW = 'Team/New.md';
+    const budgeted = new AccessControlService(stub, PROCESS_MAP_DIR, new NodeFs(), [], undefined, undefined, {
+      treeIndexBudget: 10,
+    });
+    const first = await git(repo, 'rev-parse', 'origin/main');
+    expect(await budgeted.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    await pushFromOther('a later page', () => fs.writeFile(path.join(other, 'Team/Later.md'), '# later\n'));
+    expect(await budgeted.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    const second = await git(repo, 'rev-parse', 'origin/main');
+    expect(second).not.toBe(first);
+    spawnLog.length = 0;
+    expect(await budgeted.canWriteAtRef(workspaceId, second, admin, NEW)).toBe(true);
+    expect(lsTreeBuilds()).toBe(0);
+    expect(catFileBatches()).toBe(0);
+    spawnLog.length = 0;
+    expect(await budgeted.canWriteAtRef(workspaceId, first, admin, NEW)).toBe(true);
+    expect(lsTreeBuilds()).toBe(0);
+    expect(catFileBatches()).toBe(1);
+  });
+
+  it('remembers what a blob declares for itself, never a blob the batch could not read', async () => {
+    const SECRET = 'Team/Secret.md';
+    await pushFromOther('a page that denies the admin for itself', () =>
+      fs.writeFile(path.join(other, SECRET), '---\nwrite:\n  - deny Admin\n---\n# secret\n'),
+    );
+    // Build the model first, so the next batch is the own-entries read.
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, DOC)).toBe(true);
+    // The own-entries batch loses the blob (a lost object reads as missing,
+    // exactly like an absent path): answered as no own entries, as before —
+    // the inherited write stands — but NOT remembered for the commit.
+    injected.rewriteNext = (argv) => (argv.includes('cat-file') ? rewriteBatchRecord(/:Team\/Secret\.md$/, 'missing') : null);
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, SECRET)).toBe(true);
+    expect(injected.rewriteNext).toBeNull();
+    // The next call reads the blob again, and its own denial now holds...
+    spawnLog.length = 0;
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, SECRET)).toBe(false);
+    expect(catFileBatches()).toBe(1);
+    // ...and that answer, a fact about the commit, is remembered.
+    spawnLog.length = 0;
+    expect(await svc.canWriteAtRef(workspaceId, 'origin/main', admin, SECRET)).toBe(false);
+    expect(catFileBatches()).toBe(0);
   });
 
   it('holds the models of far more commits than one listing resolves', async () => {

package/src/modules/access/__tests__/access-control.group-read.test.ts

@@ -161,3 +161,76 @@ describe('canReadAsGroupBatch', () => {
     expect(verdict?.get('Plugins/GTM')).toBe(false);
   });
 });
+
+describe('groupsOfUser', () => {
+  let root: string;
+  const workspaceId = 'ws-groups-of-user-1';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-groups-of-user-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  async function makeService() {
+    const workspaceDir = path.join(root, workspaceId);
+    const repo = path.join(workspaceDir, KB_DIR);
+    await fs.mkdir(repo, { recursive: true });
+    // `lee@x.io` holds Leads, the role that lists `group:Sales Team`, without
+    // being in the group: the role reaches the group, not the other way round.
+    await fs.writeFile(path.join(repo, 'roles.yaml'), ROLES_YAML.replace('    - group:Sales Team\n', '    - group:Sales Team\n    - lee@x.io\n'));
+    await fs.writeFile(
+      path.join(repo, 'groups.yaml'),
+      `groups:\n  Sales Team:\n    - sam@x.io\n    - sue@x.io\n  Design:\n    - dee@x.io\n    - sue@x.io\n`,
+    );
+    await fs.writeFile(path.join(repo, 'access.md'), rules('write:\n  - Admin\n'));
+    return new AccessControlService(stubWorkspaceService(workspaceId, workspaceDir), KB_DIR, new NodeFs());
+  }
+
+  it('names the groups a person is in, as groups.yaml spells them', async () => {
+    const svc = await makeService();
+    expect(await svc.groupsOfUser(workspaceId, 'sam@x.io')).toEqual(['Sales Team']);
+    expect((await svc.groupsOfUser(workspaceId, 'sue@x.io')).sort()).toEqual(['Design', 'Sales Team']);
+  });
+
+  it('matches the email in any case', async () => {
+    const svc = await makeService();
+    expect(await svc.groupsOfUser(workspaceId, 'Sam@X.io')).toEqual(['Sales Team']);
+  });
+
+  it('is empty for someone in no group, however many roles they hold', async () => {
+    const svc = await makeService();
+    expect(await svc.groupsOfUser(workspaceId, 'eng@x.io')).toEqual([]);
+    expect(await svc.groupsOfUser(workspaceId, 'admin@x.io')).toEqual([]);
+  });
+
+  it('does not count holding a role that names a group as being in it', async () => {
+    const svc = await makeService();
+    expect(await svc.groupsOfUser(workspaceId, 'lee@x.io')).toEqual([]);
+  });
+
+  describe('visibleGroups: the one answer the Groups tab, the share dialog and a grant use', () => {
+    // The active source's groups, in the order a caller happens to hold them.
+    const listed = ['Sales Team', 'Design'];
+
+    it('is every group, as given, for an admin', async () => {
+      const svc = await makeService();
+      expect(await svc.visibleGroups(workspaceId, 'admin@x.io', listed)).toEqual(listed);
+    });
+
+    it('is only the groups a person is in, in the order given, for anyone else', async () => {
+      const svc = await makeService();
+      expect(await svc.visibleGroups(workspaceId, 'sue@x.io', listed)).toEqual(['Sales Team', 'Design']);
+      expect(await svc.visibleGroups(workspaceId, 'sam@x.io', listed)).toEqual(['Sales Team']);
+      expect(await svc.visibleGroups(workspaceId, 'dee@x.io', listed)).toEqual(['Design']);
+    });
+
+    it('is empty for someone in no group, a role that names a group included', async () => {
+      const svc = await makeService();
+      expect(await svc.visibleGroups(workspaceId, 'eng@x.io', listed)).toEqual([]);
+      expect(await svc.visibleGroups(workspaceId, 'lee@x.io', listed)).toEqual([]);
+      expect(await svc.visibleGroups(workspaceId, 'admin@x.io', [])).toEqual([]);
+    });
+  });
+});