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

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/create-core-server.ts

@@ -475,7 +475,7 @@ export async function createCoreServer(
   // 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';
@@ -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,30 @@ 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.
+  const workspaceMutex = new WorkspaceMutex();
+  /**
+   * 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 +665,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 +703,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 +775,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 +862,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 +1630,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([]);
+    });
+  });
+});

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -4,6 +4,7 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 
 import type { IAccessControl } from '../access-control.interface.js';
+import { AccessControlService } from '../access-control.service.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { WorkflowService } from '../../workflow/workflow.service.js';
@@ -31,6 +32,10 @@ async function makeHarness(opts: {
   files?: Record<string, string>;
   roles?: string[];
   groups?: string[];
+  /** Whether the caller is an admin, who is offered every group. Defaults to true. */
+  admin?: boolean;
+  /** The groups the caller is a member of — all a non-admin is offered, or may grant to. */
+  memberOf?: string[];
 }): Promise<{ server: Server; baseUrl: string; files: Map<string, string> }> {
   const files = new Map<string, string>(Object.entries(opts.files ?? {}));
 
@@ -46,6 +51,12 @@ async function makeHarness(opts: {
       groups: opts.groups ?? [],
       people: [],
     })),
+    holdsAdminRootWrite: vi.fn(async () => opts.admin ?? true),
+    groupsOfUser: vi.fn(async () => opts.memberOf ?? []),
+    // The real policy over the two stubs above: who sees which group is the
+    // resolver's one answer, not something a route (or this double) decides.
+    visibleGroups: (wsId: string, email: string, groups: readonly string[]) =>
+      AccessControlService.prototype.visibleGroups.call(accessControl, wsId, email, groups),
     eligibleWriters: vi.fn(async () => ({ roles: [], users: [] })),
     eligibleReaders: vi.fn(async () => ({ restricted: true, roles: [], users: [] })),
     eligibleOwners: vi.fn(async () => ({ roles: [], users: [] })),
@@ -213,6 +224,61 @@ describe('group principals on the share surface', () => {
     expect(body.plugins).toEqual(body.roles);
   });
 
+  it("suggest offers someone who is not an admin only the groups they are in, never another group's name", async () => {
+    h = await makeHarness({ roles: ['Everyone'], groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { roles: string[]; groups: string[] };
+    expect(body.groups).toEqual(['Product']);
+    expect(body.roles).toEqual(['Everyone']); // roles are not withheld
+  });
+
+  it('suggest offers someone in no group, who is not an admin, no groups at all', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false });
+    const res = await fetch(`${h.baseUrl}/api/workspace/${encodeURIComponent(WS)}/access/suggest?q=`);
+    const body = (await res.json()) as { groups: string[] };
+    expect(body.groups).toEqual([]);
+  });
+
+  it('a non-admin grants to a group they are in', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'Product' },
+    });
+    expect(res.status).toBe(200);
+    expect(h.files.get(`${KB}/Sales/access.md`)).toContain('- Product');
+  });
+
+  it('a non-admin granting to a group they are not in is refused exactly like an unknown group', async () => {
+    h = await makeHarness({ groups: ['GTM Team', 'Product'], admin: false, memberOf: ['Product'] });
+    const res = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'GTM Team' },
+    });
+    // Same status, same body as a group that does not exist — the WHOLE
+    // answer, message included, with only the name asked about differing —
+    // so the grant route confirms no group name the picker would not have
+    // offered.
+    const ghost = await post('grant', {
+      path: `${KB}/Sales`,
+      kind: 'folder',
+      verb: 'read',
+      principal: { kind: 'group', group: 'Ghost Team' },
+    });
+    expect(res.status).toBe(404);
+    expect(ghost.status).toBe(404);
+    const hiddenBody = (await res.json()) as Record<string, unknown>;
+    const ghostBody = (await ghost.json()) as Record<string, unknown>;
+    expect(hiddenBody).toMatchObject({ kind: 'unknown-group', group: 'GTM Team' });
+    expect(JSON.stringify(hiddenBody).replaceAll('GTM Team', 'Ghost Team')).toBe(JSON.stringify(ghostBody));
+    expect(h.files.has(`${KB}/Sales/access.md`)).toBe(false);
+  });
+
   it('revokes with a group principal (name-based, no existence check)', async () => {
     h = await makeHarness({
       groups: ['GTM Team'],

package/src/modules/access/__tests__/access.routes.unknown-email.test.ts

@@ -55,6 +55,8 @@ async function makeHarness(opts: {
     grantSources: vi.fn(async () => ({ read: [{ kind: 'direct' }] })),
     invalidate: vi.fn(),
     kbPrincipals: vi.fn(async () => ({ roles: [], groups: [], people: opts.kbPeople ?? [] })),
+    // No groups in this source, so the answer is the empty list the service gives for one.
+    visibleGroups: vi.fn(async (_w: string, _e: string, groups: readonly string[]) => [...groups]),
     eligibleWriters: vi.fn(async () => ({ roles: [], users: granted })),
     eligibleReaders: vi.fn(async () => ({ restricted: true, roles: [], users: granted })),
     eligibleOwners: vi.fn(async () => ({ roles: [], users: [] })),

package/src/modules/access/access-control.interface.ts

@@ -234,6 +234,28 @@ export interface IAccessControl {
    */
   canReadAsEveryoneBatch(workspaceId: string, relativePaths: string[]): Promise<Map<string, boolean>>;
 
+  /**
+   * The display names of the groups `userEmail` is a member of, in the
+   * active group source (`groups.yaml`, or the IdP-synced file), spelled as
+   * `kbPrincipals` spells them. Direct membership only: a role that lists a
+   * group does not make its holders members of it. Empty when the person is
+   * in no group.
+   */
+  groupsOfUser(workspaceId: string, userEmail: string): Promise<string[]>;
+
+  /**
+   * Which of `groups` (names from the active group source) `userEmail` may
+   * SEE: every one for an admin, who manages them all, and only the groups
+   * they are a member of ({@link groupsOfUser}) for anyone else. A group's
+   * name is information — on a deployment that gives each client, author or
+   * customer a group of its own, the list of groups is the client list — so
+   * this ONE answer is what the Library's Groups tab lists, what the share
+   * dialog offers as a grantee, and what a grant may name; a group outside it
+   * is treated as one that does not exist. Order and spelling of `groups` are
+   * kept.
+   */
+  visibleGroups(workspaceId: string, userEmail: string, groups: readonly string[]): Promise<string[]>;
+
   /**
    * Batched canWrite for PR diffs and commit-time gating. Returns a map keyed
    * by the input paths, with `true` / `false` for each. Reuses one config