@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.34.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.36.1",
+  "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.34.0",
-    "@bevel-software/platform-shared": "0.34.0"
+    "@bevel-software/platform-mcp-core": "0.36.1",
+    "@bevel-software/platform-shared": "0.36.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",
@@ -68,6 +68,7 @@
     "@types/pg": "^8.20.0",
     "@types/qs": "^6.15.1",
     "drizzle-kit": "^0.31.10",
+    "js-tiktoken": "^1.0.21",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",
     "vitest": "^3.2.6"

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__/hexis-catalog.ts

@@ -0,0 +1,144 @@
+import express from 'express';
+import { codeModeMetaTools } from '@bevel-software/platform-mcp-core';
+import { testKbContext } from './kb-context.js';
+import { EXTERNAL_KB_MANUAL_NAME, registerToolManualsTools } from '../modules/tool-manuals/index.js';
+import { ToolRegistry, guideFirstDescription, type UtcpTool } from '../modules/tool-registry/index.js';
+import type { ToolAuth } from '../modules/tool-auth/index.js';
+import { RipgrepPatternMatcher, ToolDescriptionNotes } from '../modules/workspace/index.js';
+import { registerPluginsTools } from '../modules/plugins/index.js';
+import { registerSkillsTools } from '../modules/skills/index.js';
+import { agentGuideSections, registerAgentGuideTool } from '../modules/agent-guide/index.js';
+import {
+  RoutineWritePolicyService,
+  UuidSessionSink,
+  VersionControlHooks,
+  createToolHandlerFactory,
+  registerChangeRequestReadTools,
+  registerEmbedTools,
+  registerVersionControlTools,
+  registerWorkspaceTools,
+} from './tool-wiring.js';
+
+/**
+ * The tool catalog Hexis itself registers, built on stand-ins for the tests
+ * that read what an agent is TOLD: the description caps, the guide checks and
+ * the guide's budgets. Every registrar Hexis owns is mounted, because the
+ * definitions are the only thing under test: a stand-in that is never called
+ * is honest about that. Tools PROXIED from connected MCP servers are not here:
+ * their text is the other server's.
+ */
+
+/** Dependencies the registrars take but never touch while they are only building defs. */
+export const unused = <T,>(): T => ({}) as T;
+
+/** A `.tool` catalog with nothing in it: the shortest honest answer for a listing. */
+const emptyManuals = {
+  listLocalOnly: async () => [],
+  listAll: async () => [],
+  list: async () => [],
+  listInvalid: async () => [],
+} as unknown as Parameters<typeof registerToolManualsTools>[4];
+
+/** A skill catalog with nothing in it — the per-user skill line is then one fixed sentence. */
+export const emptySkills = { listSkills: async () => [] } as unknown as Parameters<typeof registerSkillsTools>[4];
+
+/**
+ * The meta-tools as the hosted endpoint builds them (`mcp.service.ts`):
+ * examples written against the namespace it registers the knowledge-base tools
+ * under and against the catalog it serves, and the chain without the rules it
+ * states only in the shared places. So the chain description measured here
+ * carries the worked call a client is really sent, which is its longest form.
+ */
+export function servedMetaTools(external: readonly UtcpTool[]) {
+  return codeModeMetaTools(
+    EXTERNAL_KB_MANUAL_NAME,
+    external.map((t) => ({ utcpName: `${EXTERNAL_KB_MANUAL_NAME}.${t.name}`, inputSchema: t.inputs })),
+    { sharedRulesPointer: '' },
+    // As the hosted endpoint serves them: opening with the guide-first
+    // sentence, through the one helper the endpoint itself uses.
+  ).map((t) => ({ ...t, description: guideFirstDescription(t.description) }));
+}
+
+/**
+ * Every tool Hexis itself registers, by surface: what the in-process agent is
+ * handed, what the hosted endpoint lists to an MCP client, and the three
+ * meta-tools it lists beside them.
+ */
+export async function hexisCatalog(
+  skills: Parameters<typeof registerSkillsTools>[4] = emptySkills,
+): Promise<{ internal: UtcpTool[]; external: UtcpTool[]; metaTools: ReturnType<typeof servedMetaTools> }> {
+  const registry = new ToolRegistry();
+  const router = express.Router();
+  const toolAuth = ((_req, _res, next) => next()) as unknown as ToolAuth;
+  const toolHandler = createToolHandlerFactory(unused());
+  const kb = testKbContext();
+  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
+  // service and nothing else.
+  registerChangeRequestReadTools(registry, router, toolAuth, toolHandler, unused(), kb);
+  const workspaceTools = registerWorkspaceTools(
+    registry,
+    router,
+    toolAuth,
+    toolHandler,
+    unused(),
+    unused(),
+    unused(),
+    kb,
+    gate,
+    new RoutineWritePolicyService(),
+    new UuidSessionSink(),
+    undefined,
+    undefined,
+    // The two upload tools are mounted only when a store is supplied, and
+    // every real composition supplies one: without it they would be the two
+    // descriptions this suite never measured.
+    unused(),
+    // The guide reader, not needed to build defs; then the download store,
+    // mounted on the same terms as the upload one.
+    undefined,
+    unused(),
+    // Starter packs and the tree walk, not needed; then the grep matcher,
+    // mounted on the same terms (it spawns no worker until a search runs).
+    undefined,
+    undefined,
+    new RipgrepPatternMatcher(),
+  );
+  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, {
+    accessControl: unused(),
+    variableStatus: unused(),
+    kb,
+  });
+  // `open_page`, on the file tools' router with `read_file`'s own read, as the
+  // root mounts it; its stand-ins answer nothing, since only its def is read.
+  registerEmbedTools(registry, router, toolAuth, toolHandler, {
+    embedService: unused(),
+    kb,
+    readForTool: workspaceTools.readForTool,
+    canBeReached: () => true,
+    appUrlFor: () => '',
+    notes: gate.notes,
+  });
+  // The guide's own tool, with the platform's sections: the one description
+  // that lists the sections is measured with the list it really carries.
+  registerAgentGuideTool(registry, router, toolAuth, toolHandler, () => agentGuideSections(kb.layout));
+
+  // The meta-tools as a client is served them (`mcp.service.ts` opens each
+  // with the guide-first sentence at the mount), so the catalog measured here
+  // is the catalog that goes out rather than the bare constant.
+  const external = (await registry.listExternal()) as UtcpTool[];
+  return { internal: (await registry.listInternal()) as UtcpTool[], external, metaTools: servedMetaTools(external) };
+}
+
+/** Every tool Hexis itself registers, on both surfaces, deduplicated by name. */
+export async function hexisTools(skills: Parameters<typeof registerSkillsTools>[4] = emptySkills): Promise<UtcpTool[]> {
+  const { internal, external, metaTools } = await hexisCatalog(skills);
+  const byName = new Map<string, UtcpTool>();
+  for (const tool of [...internal, ...external, ...metaTools]) byName.set(tool.name, tool as UtcpTool);
+  return [...byName.values()];
+}

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-disk.ts

@@ -0,0 +1,21 @@
+import { NodeFs } from '../modules/kb-fs/node-fs.js';
+import { KbPluginSource } from '../modules/plugins/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The real disk, and the plugin source that reads it, wired the way the
+ * composition root wires them (`core/create-core-services.ts`: one `NodeFs`,
+ * one `KbPluginSource` over it). A module's suite that drives its service over
+ * real files takes them from HERE rather than constructing another module's
+ * implementation itself: the root is the one place that knows those files
+ * (`NodeFs` is on no module entry, by design — a filesystem arrives by
+ * injection), and this fixture stands in for the root, as `kb-context.ts`
+ * does for the knowledge-base context.
+ */
+export function realDisk(): NodeFs {
+  return new NodeFs();
+}
+
+export function realPluginSource(disk: NodeFs, kb: KbContext): KbPluginSource {
+  return new KbPluginSource(disk, kb);
+}

package/src/__tests__/tokens.ts

@@ -0,0 +1,19 @@
+import { Tiktoken } from 'js-tiktoken/lite';
+import o200kBase from 'js-tiktoken/ranks/o200k_base';
+import { GUIDE_TOKEN_ENCODING } from '../modules/agent-guide/index.js';
+
+/**
+ * Token counts for the tests that hold agent-facing text to a budget
+ * (`modules/agent-guide/guide-budget.ts`): a real BPE tokenizer, offline and
+ * deterministic, so a count in CI is the count on a laptop. Built once: the
+ * rank table is large and the counts never change between calls.
+ */
+const encoder = new Tiktoken(o200kBase);
+
+if (GUIDE_TOKEN_ENCODING !== 'o200k_base') {
+  throw new Error(`The budgets name ${GUIDE_TOKEN_ENCODING}, but the counter is built on o200k_base.`);
+}
+
+export function countTokens(text: string): number {
+  return encoder.encode(text).length;
+}

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-manuals.ts

@@ -0,0 +1,32 @@
+import { ToolManualService, type McpAuthDiscoveryPort } from '../modules/tool-manuals/tool-manuals.service.js';
+import type { IAccessControl } from '../modules/access/index.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import type { KbContext } from '../shared/kb-context.js';
+import { realDisk, realPluginSource } from './real-disk.js';
+
+export type { McpAuthDiscoveryPort };
+
+/**
+ * The tool-manual service over real files, wired the way the composition root
+ * wires it (`core/create-core-services.ts`): the real disk, the plugin source
+ * reading that same disk, and the discovery port set afterwards. A suite that
+ * drives the service over real tool files takes it from HERE and never
+ * constructs the class from its file — the class is on no module entry (a
+ * service arrives by injection), and this fixture stands in for the root, as
+ * `kb-context.ts` and `real-disk.ts` do for what they wire.
+ */
+export function realToolManualService(
+  deps: {
+    workspaceService: WorkspaceService;
+    accessControl: IAccessControl;
+    kb: KbContext;
+    /** The disk the suite writes its files to; the service reads the same one. */
+    disk?: ReturnType<typeof realDisk>;
+  },
+  discovery?: McpAuthDiscoveryPort,
+): ToolManualService {
+  const disk = deps.disk ?? realDisk();
+  const svc = new ToolManualService(deps.workspaceService, deps.accessControl, deps.kb, disk, realPluginSource(disk, deps.kb));
+  if (discovery) svc.setMcpAuthDiscovery(discovery);
+  return svc;
+}

package/src/__tests__/tool-wiring.ts

@@ -0,0 +1,31 @@
+/**
+ * The pieces the composition root wires from module internals, for a suite
+ * 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, 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
+ * needs them reaches them here, the one root fixture that imports past the
+ * entries, as the root itself does. A suite that imports one of these files
+ * directly is a second wiring that drifts from the root's.
+ */
+export { createToolHandlerFactory } from '../modules/tool-helpers/tool-handler.js';
+export { createToolContextResolver } from '../modules/tool-helpers/tool-context.js';
+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 { 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 { 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__/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',
     ]);
   });