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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.35.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.",
+  "version": "0.37.0",
+  "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, version control (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -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.35.0",
-    "@bevel-software/platform-shared": "0.35.0"
+    "@bevel-software/platform-mcp-core": "0.37.0",
+    "@bevel-software/platform-shared": "0.37.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/account-admin.ts

@@ -0,0 +1,27 @@
+import type express from 'express';
+import { AdminAccessService } from '../modules/admin/admin-access.service.js';
+import { createAccountRoutes } from '../modules/auth/account.routes.js';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+
+/**
+ * The deployment admin check and the account admin routes, composed the way
+ * the composition root composes them (`core/create-core-services.ts` and
+ * `core/create-core-server.ts`). A module's suite that drives those routes
+ * end to end takes them from HERE rather than constructing another module's
+ * implementation itself: the admin and auth entries hold their contracts,
+ * and the classes and routers behind them are the root's to wire — as
+ * `real-disk.ts` stands in for the root for the filesystem.
+ */
+export function realAdminAccess(
+  access: IAccessControl,
+  workspace: WorkspaceService,
+  defaultBranch: string,
+  owners: string[],
+): AdminAccessService {
+  return new AdminAccessService(access, workspace, defaultBranch, owners);
+}
+
+export function realAccountRoutes(...args: Parameters<typeof createAccountRoutes>): express.Router {
+  return createAccountRoutes(...args);
+}

package/src/__tests__/capturing-logger.ts

@@ -0,0 +1,36 @@
+import type { ILogger, LogFields } from '../shared/logger.contract.js';
+
+/** One line a capturing logger kept: its level, message, and fields with the child bindings folded in. */
+export interface CapturedLine {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  fields: LogFields;
+}
+
+/**
+ * A logger that keeps every line instead of printing it — the one capturing
+ * implementation a suite installs through `setLogger` (restoring the previous
+ * one in `finally`) or hands to code that takes an `ILogger`, when what is
+ * logged is the behaviour under test. Children fold their bindings into each
+ * line's fields, so `module: 'database'` is asserted like any other field.
+ */
+export function capturingLogger(): { logger: ILogger; lines: CapturedLine[] } {
+  const lines: CapturedLine[] = [];
+  const make = (bindings: LogFields): ILogger => {
+    const line = (level: CapturedLine['level']) => (message: string, fields: LogFields = {}) => {
+      // Like the production sink, the child's `module` is the logger's own and
+      // a call cannot rename it; every other field a call passes wins.
+      const folded: LogFields = { ...bindings, ...fields };
+      if (bindings.module !== undefined) folded.module = bindings.module;
+      lines.push({ level, message, fields: folded });
+    };
+    return {
+      debug: line('debug'),
+      info: line('info'),
+      warn: line('warn'),
+      error: line('error'),
+      child: (more) => make({ ...bindings, ...more }),
+    };
+  };
+  return { logger: make({}), lines };
+}

package/src/__tests__/hexis-catalog.ts

@@ -11,11 +11,11 @@ import { agentGuideSections, registerAgentGuideTool } from '../modules/agent-gui
 import {
   RoutineWritePolicyService,
   UuidSessionSink,
-  WorkflowHooks,
+  VersionControlHooks,
   createToolHandlerFactory,
   registerChangeRequestReadTools,
   registerEmbedTools,
-  registerWorkflowTools,
+  registerVersionControlTools,
   registerWorkspaceTools,
 } from './tool-wiring.js';
 
@@ -72,7 +72,7 @@ export async function hexisCatalog(
   const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
   const toolHandler = createToolHandlerFactory(unused());
   const kb = testKbContext();
-  const gate = { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() };
+  const gate = { recoveryBotEmail: 'bot@x', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() };
 
   // The change-request readers come first, as the root mounts them: they
   // gate their whole payload on the caller's read access and take the access
@@ -106,7 +106,7 @@ export async function hexisCatalog(
     undefined,
     new RipgrepPatternMatcher(),
   );
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
+  registerVersionControlTools(registry, router, toolAuth, toolHandler, kb, async () => true, { canRead: async () => true, canReadAtRef: async () => true, canReadBatch: async () => new Map(), canReadBatchAtRef: async () => new Map(), canWrite: async () => true } as never, { recoveryBotEmail: 'recovery@x', hooks: { runAgentRead: async () => undefined }, notes: { onChange: () => undefined } } as never);
   registerPluginsTools(registry, kb);
   registerSkillsTools(registry, router, toolAuth, toolHandler, skills);
   registerToolManualsTools(registry, router, toolAuth, toolHandler, emptyManuals, {

package/src/__tests__/kb-context.ts

@@ -1,30 +1,30 @@
-import {
-  DEFAULT_KB_LAYOUT,
-  resolveBranchModel,
-  type BranchModel,
-  type KbLayout,
-} from '@bevel-software/platform-shared';
-import { KbContext } from '../shared/kb-context.js';
-
-/**
- * The knowledge-base context suites hand to the services they construct: the
- * historical two-branch pair `vitest.config.ts` pins (and `test-setup.ts`
- * mirrors onto the shared bindings, for the fixtures that still spell a
- * branch by its binding), the default layout, and `knowledge-base` as the
- * checkout folder. Override any part for a suite that needs another.
- */
-export const TEST_BRANCH_MODEL: BranchModel = {
-  defaultBranch: 'target-company-state',
-  protectedBranches: ['current-company-state', 'target-company-state'],
-};
-
-export function testKbContext(
-  overrides: { kbDirName?: string; branchModel?: BranchModel | null; layout?: KbLayout } = {},
-): KbContext {
-  const model = overrides.branchModel === undefined ? TEST_BRANCH_MODEL : overrides.branchModel;
-  return new KbContext(
-    overrides.kbDirName ?? 'knowledge-base',
-    model === null ? KbContext.branchModelOrUnconfigured({ defaultBranch: '', protectedBranches: [] }) : resolveBranchModel(model),
-    overrides.layout ?? DEFAULT_KB_LAYOUT,
-  );
-}
+import {
+  DEFAULT_KB_LAYOUT,
+  resolveBranchModel,
+  type BranchModel,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The knowledge-base context suites hand to the services they construct: the
+ * historical two-branch pair `vitest.config.ts` pins (and `test-setup.ts`
+ * mirrors onto the shared bindings, for the fixtures that still spell a
+ * branch by its binding), the default layout, and `knowledge-base` as the
+ * checkout folder. Override any part for a suite that needs another.
+ */
+export const TEST_BRANCH_MODEL: BranchModel = {
+  defaultBranch: 'target-company-state',
+  protectedBranches: ['current-company-state', 'target-company-state'],
+};
+
+export function testKbContext(
+  overrides: { kbDirName?: string; branchModel?: BranchModel | null; layout?: KbLayout } = {},
+): KbContext {
+  const model = overrides.branchModel === undefined ? TEST_BRANCH_MODEL : overrides.branchModel;
+  return new KbContext(
+    overrides.kbDirName ?? 'knowledge-base',
+    model === null ? KbContext.branchModelOrUnconfigured({ defaultBranch: '', protectedBranches: [] }) : resolveBranchModel(model),
+    overrides.layout ?? DEFAULT_KB_LAYOUT,
+  );
+}

package/src/__tests__/kb-layout-config.test.ts

@@ -16,6 +16,7 @@ import {
   validateKbLayout,
   validateKbRootName,
   normalizeSkillRoot,
+  WORKFLOWS_DIR,
   type KbLayout,
 } from '@bevel-software/platform-shared';
 
@@ -71,6 +72,26 @@ describe('KB layout — validation', () => {
     ).toMatch(/reserved folder name/);
   });
 
+  test('reserves Data, Agents and Workflows, in any letter case, and names them in the refusal', () => {
+    for (const name of ['Data', 'agents', 'Workflows', 'WORKFLOWS']) {
+      expect(
+        validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: name, pluginsDir: 'Plugins' }),
+        name,
+      ).toBe(`"${name.toLowerCase()}" is a reserved folder name (Data, Agents, Workflows).`);
+    }
+    expect(WORKFLOWS_DIR).toBe('Workflows');
+    expect([...reservedRootDirNames(DEFAULT_KB_LAYOUT)]).toEqual(
+      expect.arrayContaining(['Data', 'Agents', 'Workflows']),
+    );
+  });
+
+  test('no longer knows Pipelines: not reserved, and free to be a root', () => {
+    expect(reservedRootDirNames(DEFAULT_KB_LAYOUT).has('Pipelines')).toBe(false);
+    expect(
+      validateKbLayout({ knowledgeBaseDir: 'KnowledgeBase', skillsDir: 'Pipelines', pluginsDir: 'Plugins' }),
+    ).toBeNull();
+  });
+
   test('renders placeholders without interpreting $-patterns in a folder name', () => {
     expect(
       renderKbLayoutPlaceholders('a {{skillsDir}} b', { knowledgeBaseDir: 'K', skillsDir: 'Sales$&', pluginsDir: 'P' }),

package/src/__tests__/open-change-gate.ts

@@ -2,7 +2,7 @@ import type { IChangeReadGate } from '../modules/access-model/change-gate.js';
 
 /**
  * A read-before-write gate that lets every change through — for tests whose
- * subject is something else. `WorkflowService` refuses to exist without a
+ * subject is something else. `VersionControlService` refuses to exist without a
  * gate (see its constructor), so a harness that only exercises branches,
  * change requests or commits passes this one. Never wired in production: the
  * composition root builds the real `ChangeReadGate`.

package/src/__tests__/real-access.ts

@@ -0,0 +1,16 @@
+import type { ITreeWalker } from '../shared/fs.contract.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import { AccessControlService } from '../modules/access/access-control.service.js';
+
+/**
+ * The access resolver over a real tree, wired the way the composition root
+ * wires it (`core/create-core-services.ts`). A module's suite whose
+ * assertions are what the real rules answer after its service ran — who may
+ * read, who may write — takes it from HERE rather than constructing another
+ * module's implementation itself: the service is on no module entry, by
+ * design (a module receives `IAccessControl` by injection), and this fixture
+ * stands in for the root, as `real-disk.ts` does for the disk.
+ */
+export function realAccessControl(workspace: WorkspaceService, kbDirName: string, disk: ITreeWalker): AccessControlService {
+  return new AccessControlService(workspace, kbDirName, disk);
+}

package/src/__tests__/real-auth.ts

@@ -0,0 +1,13 @@
+import { AuthService } from '../modules/auth/auth.service.js';
+
+/**
+ * The auth service, constructed the way the composition root constructs it
+ * (`core/create-core-services.ts`). A module's suite that drives routes which
+ * take the real service — the access routes, which it guards — takes it from
+ * HERE rather than constructing another module's implementation itself: the
+ * auth entry holds the service's contract and the class behind it is the
+ * root's to wire, as `real-disk.ts` stands in for the root for the disk.
+ */
+export function realAuthService(...args: ConstructorParameters<typeof AuthService>): AuthService {
+  return new AuthService(...args);
+}

package/src/__tests__/real-readers.ts

@@ -0,0 +1,27 @@
+import type { FileReaderRegistry } from '../modules/workspace/index.js';
+import { createFileReaderRegistry } from '../modules/workspace/file-readers/file-reader.registry.js';
+import type { DocExtractOutcome, DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
+
+/**
+ * The file readers, composed the way the composition root composes them
+ * (`core/create-core-services.ts`) over a document extractor. A module's suite
+ * that reads real files through them takes them from HERE rather than
+ * composing another module's internals itself: the registry factory is on no
+ * module entry, by design (a module receives the registry by injection), and
+ * this fixture stands in for the root, as `real-disk.ts` does for the disk.
+ */
+export function realFileReaders(docExtract: DocExtractService = noDocExtract()): FileReaderRegistry {
+  return createFileReaderRegistry(docExtract);
+}
+
+/**
+ * A document extractor that extracts nothing: a suite that reads no
+ * document-format file gets this typed refusal, not a silent empty text.
+ */
+export function noDocExtract(): DocExtractService {
+  const extract = async (): Promise<DocExtractOutcome> => ({
+    ok: false,
+    message: 'this suite reads no document-format file',
+  });
+  return { extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService;
+}

package/src/__tests__/real-version-control.ts

@@ -0,0 +1,22 @@
+import type { KbContext } from '../shared/kb-context.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import { GitService } from '../modules/version-control/git/git.service.js';
+import { VersionControlHooks } from '../modules/version-control/version-control-hooks.js';
+
+/**
+ * The version-control collaborators, wired the way the composition root wires
+ * them (`core/create-core-services.ts`): the git service over a workspace and
+ * the lifecycle hooks it consults — where every commit it lands is reported
+ * (`onCommitLanded`). A module's suite that commits to a real repository
+ * takes them from HERE rather than constructing another module's
+ * implementation itself: none of them is on a module entry, by design — they
+ * arrive by injection — and this fixture stands in for the root, as
+ * `real-disk.ts` does for the disk.
+ */
+export function realVersionControlHooks(): VersionControlHooks {
+  return new VersionControlHooks();
+}
+
+export function realGitService(workspace: WorkspaceService, hooks: VersionControlHooks, kb: KbContext): GitService {
+  return new GitService(workspace, hooks, kb);
+}

package/src/__tests__/tool-handler.ts

@@ -0,0 +1,15 @@
+import { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+import type { ToolHandlerFactory } from '../modules/tool-helpers/index.js';
+
+/**
+ * The tool-handler factory, wired the way the composition root wires it
+ * (`core/create-core-services.ts`) minus the write-access and branch ports a
+ * suite about one tool's answer does not exercise. A module's suite that
+ * mounts its tools takes the factory from HERE rather than constructing it
+ * from `tool-helpers`' file: the factory is on no module entry (only its type
+ * is — a handler factory arrives by injection), and this fixture stands in
+ * for the root, as `real-disk.ts` does for the disk.
+ */
+export function toolHandlerFactory(resolve: Parameters<typeof createToolHandlerFactory>[0]): ToolHandlerFactory {
+  return createToolHandlerFactory(resolve);
+}

package/src/__tests__/tool-wiring.ts

@@ -3,7 +3,8 @@
  * that builds a tool surface the way `core/create-core-server.ts` does: the
  * handler factory and context resolver, the tool-auth middleware, the two
  * registrars that take their dependencies by hand, the session sink, the
- * routine write policy, the access resolver and the workflow hooks.
+ * routine write policy, the access resolver, the version-control hooks, the
+ * manual auth middleware and the auth cookie reader, and the MCP routes and service.
  *
  * A module's entry holds its contracts, and a suite asserts through entries.
  * These are not contracts: they are what the root composes, so a suite that
@@ -16,10 +17,15 @@ export { createToolContextResolver } from '../modules/tool-helpers/tool-context.
 export { createToolAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
 export { InternalTokenService } from '../modules/tool-auth/internal-token.service.js';
 export { registerWorkspaceTools } from '../modules/workspace/workspace.tools.js';
-export { registerWorkflowTools } from '../modules/workflow/agent-tools/workflow.tools.js';
-export { registerChangeRequestReadTools } from '../modules/workflow/agent-tools/change-request-read.tools.js';
+export { registerVersionControlTools } from '../modules/version-control/agent-tools/version-control.tools.js';
+export { registerChangeRequestReadTools } from '../modules/version-control/agent-tools/change-request-read.tools.js';
 export { registerEmbedTools } from '../modules/embed/embed.tools.js';
 export { UuidSessionSink } from '../modules/workspace/session-sink.js';
 export { RoutineWritePolicyService } from '../modules/workspace/routine-write-policy.js';
 export { AccessControlService, loadActiveGroups } from '../modules/access/access-control.service.js';
-export { WorkflowHooks, type AgentOperationContext } from '../modules/workflow/workflow-hooks.js';
+export { VersionControlHooks, type AgentOperationContext } from '../modules/version-control/version-control-hooks.js';
+export { createManualAuthMiddleware } from '../modules/tool-auth/tool-auth.middleware.js';
+export { readAuthCookie } from '../modules/auth/auth.middleware.js';
+export type { ToolBranchPort } from '../modules/tool-helpers/tool-handler.js';
+export { createMcpRoutes } from '../modules/mcp/mcp.routes.js';
+export { McpService } from '../modules/mcp/mcp.service.js';

package/src/__tests__/workspace-service.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { NodeGitRunner } from '../modules/workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../modules/version-control/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';

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js';
-import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
+import { VersionControlEventBus } from '../../modules/version-control/event-bus.js';
 import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { testKbContext } from '../../__tests__/kb-context.js';
@@ -15,7 +15,7 @@ const USER = {
 } as unknown as Parameters<Parameters<FileChangeNotifier['onFilesChanged']>[0]>[0]['byUser'];
 
 function setup() {
-  const eventBus = new WorkflowEventBus();
+  const eventBus = new VersionControlEventBus();
   const fileChangeNotifier = new FileChangeNotifier();
   const catalogs = [
     { invalidate: vi.fn() },
@@ -132,7 +132,7 @@ describe('registerCatalogCacheInvalidation', () => {
      * working-tree write does — NOT as a `change-request-merged` special
      * case. That a pull of the default workspace actually emits this event
      * (only after it resolves, and only when it changed the tree's content) is the emitter's
-     * own contract, pinned in workflow.service.releaseLock.test.ts under
+     * own contract, pinned in version-control.service.releaseLock.test.ts under
      * "the tree-change announcement".
      */
     it('drops the catalogs when the default tree changes (write or post-merge pull alike)', () => {

package/src/core/__tests__/commit-announcements-wired-once.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * A landed commit is announced from ONE place. The git service reports every
+ * commit it lands through `VersionControlHooks.commitLanded`; the composition
+ * root hands that to the file-change notifier with one registration; nothing
+ * else emits on the notifier or calls the hook. A second announcer is how a
+ * batch gets announced twice, and a committer that announces on its own is how
+ * the next one forgets to — both were real findings on the release that made
+ * this rule, so the rule is pinned at the source level.
+ */
+const SRC = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const ROOT = path.join(SRC, 'core', 'create-core-services.ts');
+
+async function shippedSources(dir: string, out: string[] = []): Promise<string[]> {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== '__tests__') await shippedSources(full, out);
+    } else if (/\.ts$/.test(entry.name) && !/\.test\.ts$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+async function filesContaining(needle: RegExp): Promise<string[]> {
+  const hits: string[] = [];
+  for (const file of await shippedSources(SRC)) {
+    if (needle.test(await fs.readFile(file, 'utf8'))) hits.push(path.relative(SRC, file).replace(/\\/g, '/'));
+  }
+  return hits.sort();
+}
+
+describe('commit announcements are wired once', () => {
+  it('the composition root hands the git layer\'s landed commits to the notifier with one registration', async () => {
+    const source = await fs.readFile(ROOT, 'utf8');
+    const registrations = source.match(/versionControlHooks\.onCommitLanded\(/g) ?? [];
+    expect(registrations).toHaveLength(1);
+    expect(source).toContain('versionControlHooks.onCommitLanded((change) => fileChangeNotifier.emit(change));');
+  });
+
+  it('only the git service reports a landed commit, and only the root registers for it', async () => {
+    expect(await filesContaining(/\.commitLanded\(/)).toEqual(['modules/version-control/git/git.service.ts']);
+    expect(await filesContaining(/\.onCommitLanded\(/)).toEqual(['core/create-core-services.ts']);
+  });
+
+  it('nothing but the root emits on the notifier, and no committer announces on its own', async () => {
+    expect(await filesContaining(/fileChangeNotifier\.emit\(|fileChanges\??\.emit\(/)).toEqual(['core/create-core-services.ts']);
+    expect(await filesContaining(/announceCommitted|announceReleased/)).toEqual([]);
+  });
+});

package/src/core/__tests__/compose-embed.test.ts

@@ -26,7 +26,7 @@ function deps(): EmbedComposition {
     },
     accessControl: { canRead: vi.fn(async () => true), canWrite: vi.fn(async () => true) } as never,
     authService: { getUserById: vi.fn(async () => USER), isEmailDomainAllowed: () => true, isActive: async () => true },
-    workflowService: {} as never,
+    versionControlService: {} as never,
     gitService: {} as never,
     accountLinks: { getUserId: async () => null, link: async () => undefined, listForUser: async () => [], unlink: async () => true },
     readers: createFileReaderRegistry({ extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService),

package/src/core/__tests__/damaged-document.tools.test.ts

@@ -13,7 +13,7 @@ import type { ToolContext } from '../../modules/tool-helpers/tool.contract.js';
 import type { ToolAuth } from '../../modules/tool-auth/tool-auth.middleware.js';
 import { registerWorkspaceTools } from '../../modules/workspace/workspace.tools.js';
 import { RoutineWritePolicyService } from '../../modules/workspace/routine-write-policy.js';
-import { WorkflowHooks } from '../../modules/workflow/workflow-hooks.js';
+import { VersionControlHooks } from '../../modules/version-control/version-control-hooks.js';
 import { ToolDescriptionNotes } from '../../modules/workspace/agent-access.gate.js';
 import { SpillStore } from '../../modules/workspace/spill-store.js';
 import { RipgrepPatternMatcher } from '../../modules/workspace/index.js';
@@ -92,7 +92,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
     sessionId,
     abortSignal: signal,
     workspaceService: { getWorkspacePath: async () => tempDir } as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async () => fs,
   });
@@ -123,7 +123,7 @@ async function startPlatform(extractorOpts: WorkerDocumentExtractorOptions = {})
     docExtract,
     allowAll,
     testKbContext({ kbDirName: KB }),
-    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,
     undefined,

package/src/core/__tests__/erasure-slices-wired-once.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Account erasure runs two kinds of slice: core's own (the vault's managed
+ * sign-ins, revoked with their provider before the user row and its rows
+ * cascade away) and the distribution's, from `CorePorts.erasureParticipants`.
+ * The port's array is held by reference so a root may fill it AFTER
+ * construction, and core never writes into it: a root that builds a graph
+ * over the same array more than once (a tenant brought back after eviction)
+ * would otherwise accumulate every past graph's vault slice, each pointing
+ * at that graph's closed pool.
+ *
+ * Read off the source, as `set-aside-root-is-one-place.test.ts` reads it:
+ * the composition root cannot be built in a unit test (it wants a database,
+ * a git host and a disk), and the invariant is about the TEXT — the service
+ * is constructed once, the port's array is passed as it is, core's slice
+ * travels beside it, and nothing pushes into or copies the port's array.
+ * `AccountErasureService`'s own suite pins what that argument order means.
+ */
+
+const compositionRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../create-core-services.ts');
+
+describe('the erasure slices the composition root wires', () => {
+  it('passes the port’s array untouched and the vault’s slice beside it, once', async () => {
+    const source = await fs.readFile(compositionRoot, 'utf8');
+
+    const constructions = source.match(/new AccountErasureService\(/g) ?? [];
+    expect(constructions).toHaveLength(1);
+
+    // The one construction: the port's array as the root received it (or an
+    // empty one of core's own), then core's slices with the vault's first.
+    const call = source.slice(source.indexOf('new AccountErasureService('));
+    const args = call.slice(0, call.indexOf(');') + 2);
+    expect(args).toMatch(/ports\.erasureParticipants \?\? \[\]/);
+    expect(args).toMatch(/\[\s*managedSignInErasure\(secretsVaultService\),?\s*\]/);
+    expect(args.indexOf('ports.erasureParticipants')).toBeLessThan(args.indexOf('managedSignInErasure'));
+
+    // Never written into, never copied: the array a root fills after
+    // construction is the array erasure reads, with nothing of core's in it.
+    expect(source).not.toMatch(/erasureParticipants\s*\.\s*(push|unshift|splice)\(/);
+    expect(source).not.toMatch(/\.\.\.\s*\(?\s*ports\.erasureParticipants/);
+  });
+});

package/src/core/__tests__/gated-boot.test.ts

@@ -48,10 +48,10 @@ function bootable(runAll: () => Promise<void>) {
         return { stop() {} };
       },
     } as BootableCore['kbStartupRunner'],
-    workflowService: {
+    versionControlService: {
       closeChangeRequestsWithDeletedBranches: async () => 0,
       tidyAfterSweep: async () => ({ closedEmpty: 0, removedLeftovers: 0 }),
-    } as BootableCore['workflowService'],
+    } as BootableCore['versionControlService'],
     pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
     tmpSweeper: {
       startSweeping() {

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

@@ -460,12 +460,12 @@ describe('stopCore', () => {
             order.push('startupRetry.stop');
           },
         },
-        workflowService: {
+        versionControlService: {
           stopTidying() {
-            order.push('workflowService.stopTidying');
+            order.push('versionControlService.stopTidying');
           },
           async drainTidy() {
-            order.push('workflowService.drainTidy');
+            order.push('versionControlService.drainTidy');
           },
         },
         db: {
@@ -488,10 +488,10 @@ describe('stopCore', () => {
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -550,10 +550,10 @@ describe('stopCore', () => {
     expect(g.order).toEqual([
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'commitWorker.stop',
       'db.end',
     ]);
@@ -594,10 +594,10 @@ describe('stopCore', () => {
       'pluginJoinRequestJobs.stopSweeping',
       'agentUploadStore.stopSweeping',
       'startupRetry.stop',
-      'workflowService.stopTidying',
+      'versionControlService.stopTidying',
       'pluginJoinRequestJobs.drain',
       'agentUploadStore.drainSweep',
-      'workflowService.drainTidy',
+      'versionControlService.drainTidy',
       'db.end',
     ]);
   });

package/src/core/catalog-cache-invalidation.ts

@@ -1,5 +1,5 @@
 import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
-import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
+import type { VersionControlEventBus } from '../modules/version-control/event-bus.js';
 import type { KbContext } from '../shared/kb-context.js';
 
 /**
@@ -23,7 +23,7 @@ export interface InvalidatableCatalog {
  * Returns an unsubscribe that detaches all three.
  */
 export function registerCatalogCacheInvalidation(deps: {
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   fileChangeNotifier: FileChangeNotifier;
   /**
    * The KB folder inside the workspace (`paths` are workspace-relative), the