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

package/src/modules/workspace/__tests__/start-session.default-branch.test.ts

@@ -0,0 +1,152 @@
+import type { Server as HttpServer } from 'node:http';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
+import { toolHandlerFactory } from '../../../__tests__/tool-handler.js';
+import type { KbContext } from '../../../shared/kb-context.js';
+import type { IAccessControl } from '../../access/index.js';
+import type { ToolAuth } from '../../tool-auth/index.js';
+import type { ToolContext } from '../../tool-helpers/index.js';
+import { ToolRegistry } from '../../tool-registry/index.js';
+import { ToolDescriptionNotes } from '../agent-access.gate.js';
+import { DocExtractService } from '../file-readers/doc-extract.service.js';
+import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
+import { STARTER_GUIDE_FILE, firstRunNote } from '../first-run.js';
+import { RoutineWritePolicyService } from '../routine-write-policy.js';
+import { SpillStore } from '../spill-store.js';
+import { registerWorkspaceTools } from '../workspace.tools.js';
+
+/**
+ * The guide's start names the deployment's default branch, but only to an
+ * agent that calls `get_agent_guide`; every file tool asks for "the branch you
+ * are working on", and an agent left to guess guesses `main`. `start_session`, the call every agent is told to make
+ * first, answers it beside the id: this deployment's, which here is not `main`
+ * (`testKbContext`'s default branch is `target-company-state`).
+ */
+
+const KB_DIR = 'knowledge-base';
+
+/** Every read allowed: the `firstRun` note is gated like a read, and these tests are not about the gate. */
+const allowAll = {
+  canRead: async () => true,
+  canReadBatch: async (_w: string, _u: string, paths: string[]) => new Map(paths.map((p) => [p, true])),
+} as unknown as IAccessControl;
+
+let server: HttpServer | undefined;
+let extractor: WorkerDocumentExtractor | undefined;
+let wsDir: string | undefined;
+
+/**
+ * `start_session` mounted as the root mounts it, for an external caller.
+ * `defaultWorkspaceDir` is the default branch's checkout, for the `firstRun`
+ * note; without one the note's check has no workspace and the answer carries
+ * none.
+ */
+async function startSession(kb: KbContext, defaultWorkspaceDir?: string): Promise<{ base: string; registry: ToolRegistry }> {
+  const registry = new ToolRegistry();
+  const resolve = async (auth: ToolAuth, signal: AbortSignal): Promise<ToolContext> => ({
+    user: { id: 'user-42', email: 'e@x', name: 'N' },
+    scope: auth.scope,
+    source: auth.source,
+    abortSignal: signal,
+    workspaceService: (defaultWorkspaceDir
+      ? { hasBootstrappedWorkspace: async () => true, getWorkspacePath: async () => defaultWorkspaceDir }
+      : {}) as never,
+    versionControlService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => ({}) as never,
+    getWriteValidator: async () => ({}) as never,
+  });
+  const auth = (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    req.toolAuth = { source: 'external', userId: 'user-42', scope: 'write' };
+    next();
+  };
+  extractor = new WorkerDocumentExtractor();
+  const router = express.Router();
+  registerWorkspaceTools(
+    registry,
+    router,
+    auth,
+    toolHandlerFactory(resolve),
+    new SpillStore(join(tmpdir(), 'bevel-test-spills')),
+    new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor),
+    allowAll,
+    kb,
+    // No hook runs: `start_session` reads and writes no file.
+    { recoveryBotEmail: 'recovery-bot@bevel.local', hooks: {} as never, notes: new ToolDescriptionNotes() },
+    new RoutineWritePolicyService(),
+    { createSession: async () => ({ sessionId: 'thread-xyz' }) },
+    undefined,
+    undefined,
+    undefined,
+    undefined,
+    undefined /* downloads */,
+    undefined /* starter packs */,
+    realDisk(),
+  );
+  const app = express();
+  app.use(express.json());
+  app.use('/api', router);
+  server = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return { base: `http://127.0.0.1:${(server.address() as { port: number }).port}`, registry };
+}
+
+const call = async (base: string): Promise<Record<string, unknown>> =>
+  (await (
+    await fetch(`${base}/api/agent/tools/start_session`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
+      body: '{}',
+    })
+  ).json()) as Record<string, unknown>;
+
+afterEach(async () => {
+  if (server) await new Promise<void>((r) => server!.close(() => r()));
+  server = undefined;
+  await extractor?.close();
+  extractor = undefined;
+  if (wsDir) await rm(wsDir, { recursive: true, force: true });
+  wsDir = undefined;
+});
+
+describe('start_session names the default branch', () => {
+  it('answers { sessionId, defaultBranch }, the branch being the deployment\'s', async () => {
+    const { base } = await startSession(testKbContext({ kbDirName: KB_DIR }));
+    expect(await call(base)).toEqual({ sessionId: 'thread-xyz', defaultBranch: 'target-company-state' });
+  });
+
+  it('answers firstRun beside them while the knowledge base is empty', async () => {
+    wsDir = await mkdtemp(join(tmpdir(), 'bevel-start-session-'));
+    await mkdir(join(wsDir, KB_DIR, 'KnowledgeBase'), { recursive: true });
+    await writeFile(join(wsDir, KB_DIR, 'KnowledgeBase', STARTER_GUIDE_FILE), '# How to get started\n');
+    const { base } = await startSession(testKbContext({ kbDirName: KB_DIR }), wsDir);
+    expect(await call(base)).toEqual({
+      sessionId: 'thread-xyz',
+      defaultBranch: 'target-company-state',
+      firstRun: firstRunNote(`${KB_DIR}/KnowledgeBase`),
+    });
+  });
+
+  it('names the branch in effect when called, not the one in effect when the tool was registered', async () => {
+    const kb = testKbContext({ kbDirName: KB_DIR });
+    const { base } = await startSession(kb);
+    kb.applyBranchModel({ defaultBranch: 'company-state', protectedBranches: ['company-state'] });
+    expect(await call(base)).toEqual({ sessionId: 'thread-xyz', defaultBranch: 'company-state' });
+  });
+
+  it('says so in its description and declares the field, required, in its output schema', async () => {
+    const { registry } = await startSession(testKbContext({ kbDirName: KB_DIR }));
+    const def = (await registry.listExternal()).find((t) => t.name === 'start_session')!;
+    expect(def.description).toContain('Returns `{ sessionId, defaultBranch }`, plus `firstRun` while the knowledge base is empty');
+    const outputs = def.outputs as { properties: Record<string, { description?: string }>; required: string[] };
+    expect(Object.keys(outputs.properties)).toEqual(['sessionId', 'defaultBranch', 'firstRun']);
+    expect(outputs.properties.defaultBranch.description).toContain('the branch people read');
+    expect(outputs.required).toEqual(['sessionId', 'defaultBranch']);
+  });
+});

package/src/modules/workspace/__tests__/workspace-paths-inside-the-repo.test.ts

@@ -8,10 +8,10 @@ import AdmZip from 'adm-zip';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
@@ -76,7 +76,7 @@ async function makeHarness(): Promise<Harness> {
   } as unknown as IAccessControl;
 
   const locked: string[] = [];
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn(async () => null),
     acquireLock: vi.fn(async (_w: string, _b: string, p: string) => {
       locked.push(p);
@@ -85,7 +85,7 @@ async function makeHarness(): Promise<Harness> {
     releaseLock: vi.fn(async () => undefined as never),
     releaseLockNoCommit: vi.fn(async () => undefined as never),
     releaseLockUntouched: vi.fn(async () => undefined as never),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
   const stubCreatorAccess: ICreatorAccess = {
     planForCreate: async () => null,
@@ -103,8 +103,8 @@ async function makeHarness(): Promise<Harness> {
     createWorkspaceRoutes(
       workspaceService,
       { getUserById: vi.fn(async () => USER) } as unknown as AuthService,
-      workflowService,
-      { emit: vi.fn() } as unknown as WorkflowEventBus,
+      versionControlService,
+      { emit: vi.fn() } as unknown as VersionControlEventBus,
       accessControl,
       testKbContext({ kbDirName: KB }),
       stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace-tmp.tools.test.ts

@@ -10,19 +10,18 @@ import { LocalFilesystem } from '@mastra/core/workspace';
 import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { newWorkspaceService } from '../../../__tests__/workspace-service.js';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import type { ToolContext } from '../../tool-helpers/tool.contract.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import { NodeFs } from '../../kb-fs/node-fs.js';
-import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
-import { agentGuideSections, WORKING_WITH_FILES_SECTION_ID } from '../../agent-guide/agent-guide.js';
+import { ToolRegistry } from '../../tool-registry/index.js';
+import { createToolHandlerFactory, VersionControlHooks } from '../../../__tests__/tool-wiring.js';
+import type { ToolContext } from '../../tool-helpers/index.js';
+import type { ToolAuth } from '../../tool-auth/index.js';
+import type { IAccessControl } from '../../access/index.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
+import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/index.js';
+import { agentGuideSections, WORKING_WITH_FILES_SECTION_ID } from '../../agent-guide/index.js';
 import { PathNotFoundError } from '../../../shared/domain-errors.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
 import { RipgrepPatternMatcher } from '../ripgrep-search.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
@@ -191,7 +190,7 @@ async function start(): Promise<string> {
   root = await mkdtemp(join(tmpdir(), 'ws-tmp-ref-'));
   docCacheDir = await mkdtemp(join(tmpdir(), 'ws-tmp-ref-cache-'));
   for (const branch of [DRAFT, PROTECTED]) await mkdir(join(workspaceDir(branch), KB_DIR), { recursive: true });
-  service = newWorkspaceService(root, 'https://example.invalid/kb.git', testKbContext(), new NodeFs());
+  service = newWorkspaceService(root, 'https://example.invalid/kb.git', testKbContext(), realDisk());
   matcher = new RipgrepPatternMatcher();
   extractor = new WorkerDocumentExtractor();
   const filesystems = new Map<string, LocalFilesystem>();
@@ -210,7 +209,7 @@ async function start(): Promise<string> {
       getWorkspacePath: async (id: string) => join(root, id),
       hasBootstrappedWorkspace: async () => false,
     } as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async (branch: string) => {
       let fs = filesystems.get(branch);
@@ -237,7 +236,7 @@ async function start(): Promise<string> {
     new DocExtractService(docCacheDir, extractor),
     access,
     testKbContext({ kbDirName: KB_DIR }),
-    { recoveryBotEmail: 'bot@x', hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+    { recoveryBotEmail: 'bot@x', hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
     new RoutineWritePolicyService(),
     {} as never,
     undefined,
@@ -911,7 +910,7 @@ describe('the periodic sweep of every workspace\'s tmp folder', () => {
 
 describe('the agent guide\'s file-tools section describes the ref', () => {
   it("states the ref, that it reaches the caller's own files, that it is read-only, copy_file to keep, and up to seven days", async () => {
-    const rule = sharedFileRules(DEFAULT_KB_LAYOUT).find((r) => r.id === 'workspace-tmp')!.body;
+    const rule = sharedFileRules(DEFAULT_KB_LAYOUT, '').find((r) => r.id === 'workspace-tmp')!.body;
     expect(rule).toContain('`__tmp__/<path>`');
     expect(rule).toContain('`tmp/` folder');
     expect(rule).toContain('YOU staged');
@@ -920,7 +919,7 @@ describe('the agent guide\'s file-tools section describes the ref', () => {
     expect(rule).toContain('copy_file it to a repository path');
     expect(rule).toContain('up to seven days');
     for (const tool of ['read_file', 'file_stat', 'grep', 'copy_file']) expect(rule).toContain(tool);
-    expect(sharedFileRulesSection(DEFAULT_KB_LAYOUT)).toContain(rule);
+    expect(sharedFileRulesSection(DEFAULT_KB_LAYOUT, '')).toContain(rule);
     const sections = await agentGuideSections(DEFAULT_KB_LAYOUT);
     const files = sections.find((s) => s.id === WORKING_WITH_FILES_SECTION_ID)!;
     expect(files.body).toContain(rule);

package/src/modules/workspace/__tests__/workspace.routes.at-ref.test.ts

@@ -2,14 +2,14 @@ import { get as httpGet, type Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { VersionNotOnBranchError, VERSION_NOT_ON_BRANCH_MESSAGE } from '../../../shared/domain-errors.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
 import type { WorkspaceService } from '../workspace.service.js';
@@ -53,7 +53,7 @@ async function makeHarness(
   opts: {
     canRead?: boolean;
     canDownload?: boolean;
-    /** What the workflow service answers; default is the past bytes. */
+    /** What the version-control service answers; default is the past bytes. */
     atRef?: () => Promise<{ bytes: Uint8Array; blobId: string } | null>;
   } = {},
 ): Promise<Harness> {
@@ -73,7 +73,7 @@ async function makeHarness(
   const fileBytesAtChange = vi.fn(
     opts.atRef ?? (async () => ({ bytes: PAST_BYTES, blobId: 'deadbeef'.repeat(5) })),
   );
-  const workflowService = { fileBytesAtChange } as unknown as IWorkflowService;
+  const versionControlService = { fileBytesAtChange } as unknown as IVersionControlService;
 
   const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
 
@@ -88,8 +88,8 @@ async function makeHarness(
     createWorkspaceRoutes(
       workspaceService,
       authService,
-      workflowService,
-      {} as unknown as WorkflowEventBus,
+      versionControlService,
+      {} as unknown as VersionControlEventBus,
       accessControl,
       testKbContext({ kbDirName: KB }),
       stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace.routes.branch-errors.test.ts

@@ -4,9 +4,9 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import type { FileTreeEntry, IWorkflowService } from '@bevel-software/platform-shared';
+import type { FileTreeEntry, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
@@ -53,8 +53,8 @@ async function makeHarness(
   app.use('/api', createWorkspaceRoutes(
     workspaceService,
     { getUserById: vi.fn(async () => USER) } as unknown as AuthService,
-    {} as unknown as IWorkflowService,
-    { emit: vi.fn() } as unknown as WorkflowEventBus,
+    {} as unknown as IVersionControlService,
+    { emit: vi.fn() } as unknown as VersionControlEventBus,
     accessControl,
     testKbContext(),
     stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace.routes.create-grant.test.ts

@@ -4,12 +4,12 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
@@ -68,7 +68,7 @@ async function makeHarness(opts: { extracted?: string[]; changeGate?: IChangeRea
     withPathTurn: vi.fn(async (_id: string, _p: string, op: () => Promise<unknown>) => op()),
   } as unknown as WorkspaceService;
 
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn(async () => null),
     acquireLock: vi.fn(async (_w: string, _b: string, p: string) => {
       lockedPaths.push(p);
@@ -76,7 +76,7 @@ async function makeHarness(opts: { extracted?: string[]; changeGate?: IChangeRea
     }),
     releaseLock: vi.fn(async () => null),
     releaseLockNoCommit: vi.fn(async () => undefined),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
   const creatorAccess = {
     planForCreate: vi.fn(async () => null),
@@ -84,7 +84,7 @@ async function makeHarness(opts: { extracted?: string[]; changeGate?: IChangeRea
   };
 
   const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
-  const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+  const eventBus = { emit: vi.fn() } as unknown as VersionControlEventBus;
 
   const app = express();
   app.use(express.json());
@@ -97,7 +97,7 @@ async function makeHarness(opts: { extracted?: string[]; changeGate?: IChangeRea
     createWorkspaceRoutes(
       workspaceService,
       authService,
-      workflowService,
+      versionControlService,
       eventBus,
       {} as unknown as IAccessControl,
       testKbContext({ kbDirName: KB }),

package/src/modules/workspace/__tests__/workspace.routes.delete.test.ts

@@ -7,9 +7,9 @@ import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
@@ -80,20 +80,20 @@ async function makeHarness(): Promise<Harness> {
   };
   const workspaceService = workspaceServiceMock as WorkspaceService;
 
-  const workflowServiceMock: Partial<IWorkflowService> = {
+  const versionControlServiceMock: Partial<IVersionControlService> = {
     getLock: vi.fn(async () => null),
     acquireLock: vi.fn(async () => ({ acquired: true, lock: {} as never })),
     releaseLock: vi.fn(async () => undefined as never),
     releaseLockNoCommit: vi.fn(async () => undefined as never),
   };
-  const workflowService = workflowServiceMock as unknown as IWorkflowService;
+  const versionControlService = versionControlServiceMock as unknown as IVersionControlService;
 
   const authServiceMock: Partial<AuthService> = {
     getUserById: vi.fn(async () => USER),
   };
   const authService = authServiceMock as AuthService;
 
-  const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+  const eventBus = { emit: vi.fn() } as unknown as VersionControlEventBus;
 
   const app = express();
   app.use(express.json());
@@ -104,7 +104,7 @@ async function makeHarness(): Promise<Harness> {
   app.use('/api', createWorkspaceRoutes(
     workspaceService,
     authService,
-    workflowService,
+    versionControlService,
     eventBus,
     accessControl,
     testKbContext({ kbDirName: KB }),
@@ -128,7 +128,7 @@ async function makeHarness(): Promise<Harness> {
     workspaceDir,
     repoDir: path.join(workspaceDir, KB),
     deleteFileMock: workspaceServiceMock.deleteFile as unknown as ReturnType<typeof vi.fn>,
-    acquireLockMock: workflowServiceMock.acquireLock as unknown as ReturnType<typeof vi.fn>,
+    acquireLockMock: versionControlServiceMock.acquireLock as unknown as ReturnType<typeof vi.fn>,
   };
 }
 
@@ -199,7 +199,7 @@ describe('DELETE /workspace/:id/file — recursive folder delete (BEVA-132)', ()
 
 describe('DELETE /workspace/:id/file — one file identity', () => {
   it('deletes the canonical path, whichever accepted spelling was sent', async () => {
-    // The workflow lock row is keyed by this path, so a delete spelled
+    // The version-control lock row is keyed by this path, so a delete spelled
     // `.//note.md` must not coordinate separately from a save on `note.md`.
     const h = await makeHarness();
     try {

package/src/modules/workspace/__tests__/workspace.routes.download-implies-read.test.ts

@@ -8,10 +8,10 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
@@ -101,8 +101,8 @@ describe('GET /file/raw on a download-only path (real resolver)', () => {
       createWorkspaceRoutes(
         workspaceService,
         authService,
-        {} as unknown as IWorkflowService,
-        {} as unknown as WorkflowEventBus,
+        {} as unknown as IVersionControlService,
+        {} as unknown as VersionControlEventBus,
         accessControl,
         testKbContext({ kbDirName: KB }),
         stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace.routes.download.test.ts

@@ -5,9 +5,9 @@ import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { PathTraversalError } from '../../../shared/domain-errors.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { AccessConfigError } from '../../access-model/access-errors.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
@@ -122,8 +122,8 @@ async function makeHarness(opts: {
   authServiceMock.resolveSession = vi.fn(async (token: string) => authServiceMock.verifyToken!(token));
   const authService = authServiceMock as AuthService;
 
-  const workflowService = {} as unknown as IWorkflowService;
-  const eventBus = {} as unknown as WorkflowEventBus;
+  const versionControlService = {} as unknown as IVersionControlService;
+  const eventBus = {} as unknown as VersionControlEventBus;
 
   const app = express();
   app.use(express.json());
@@ -138,7 +138,7 @@ async function makeHarness(opts: {
   app.use('/api', createWorkspaceRoutes(
     workspaceService,
     authService,
-    workflowService,
+    versionControlService,
     eventBus,
     accessControl,
     testKbContext({ kbDirName: KB }),
@@ -226,7 +226,7 @@ describe('GET /workspace/:id/file/raw — ?download=1 gated on Download role', (
     // malformed) and we don't catch it, the async rejection bubbles past
     // Express and the request hangs (or 500s without the helpful
     // config-error payload). The route should surface the
-    // WorkflowDomainError shape — same JSON the per-path /access endpoint
+    // VersionControlDomainError shape — same JSON the per-path /access endpoint
     // returns when it hits the same exception — so the operator can see
     // which access.md file is broken.
     const configErr = new AccessConfigError([

package/src/modules/workspace/__tests__/workspace.routes.file-writes.test.ts

@@ -6,11 +6,11 @@ import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { PathTraversalError } from '../../../shared/domain-errors.js';
 import { EntryExistsError } from '../workspace.service.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
 import type { SkillSaveCheck } from '../workspace.tools.js';
@@ -112,7 +112,7 @@ async function makeHarness(opts: { canRead?: boolean; skillSaveCheck?: SkillSave
     noteAccessFileWritten: () => {},
   } as unknown as ICreatorAccess;
 
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn(async () => null),
     acquireLock: vi.fn(async (_w: string, _b: string, p: string) => {
       lockedPaths.push(p);
@@ -125,7 +125,7 @@ async function makeHarness(opts: { canRead?: boolean; skillSaveCheck?: SkillSave
     releaseLockUntouched: vi.fn(async (_w: string, _b: string, p: string) => {
       untouchedPaths.push(p);
     }),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
   const authService = { getUserById: vi.fn(async () => USER) } as unknown as AuthService;
   const readable = opts.canRead !== false;
@@ -147,8 +147,8 @@ async function makeHarness(opts: { canRead?: boolean; skillSaveCheck?: SkillSave
     createWorkspaceRoutes(
       workspaceService,
       authService,
-      workflowService,
-      { emit: vi.fn() } as unknown as WorkflowEventBus,
+      versionControlService,
+      { emit: vi.fn() } as unknown as VersionControlEventBus,
       accessControl,
       testKbContext({ kbDirName: KB }),
       stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace.routes.folder-zip-access.test.ts

@@ -8,10 +8,10 @@ import AdmZip from 'adm-zip';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { ICreatorAccess } from '../../access-model/creator.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import { AccessControlService } from '../../access/access-control.service.js';
 import { createWorkspaceRoutes } from '../workspace.routes.js';
@@ -109,8 +109,8 @@ describe('GET /folder/zip judges every file it packs (real resolver, real zip)',
       createWorkspaceRoutes(
         workspaceService,
         authService,
-        {} as unknown as IWorkflowService,
-        {} as unknown as WorkflowEventBus,
+        {} as unknown as IVersionControlService,
+        {} as unknown as VersionControlEventBus,
         accessControl,
         testKbContext({ kbDirName: KB }),
         stubCreatorAccess,

package/src/modules/workspace/__tests__/workspace.routes.folders.test.ts

@@ -6,10 +6,10 @@ import os from 'node:os';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import type { FileTreeEntry, IWorkflowService } from '@bevel-software/platform-shared';
+import type { FileTreeEntry, IVersionControlService } from '@bevel-software/platform-shared';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IAdminAccessService } from '../../admin/admin.interface.js';
 import type { ICreatorAccess } from '../../access-model/creator.js';
@@ -65,12 +65,12 @@ async function makeHarness(): Promise<Harness> {
     acquired: true,
     lock: {} as never,
   }));
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn(async () => null),
     acquireLock,
     releaseLock,
     releaseLockNoCommit: vi.fn(async () => undefined as never),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 
   const emit = vi.fn();
   const app = express();
@@ -84,8 +84,8 @@ async function makeHarness(): Promise<Harness> {
     createWorkspaceRoutes(
       workspaceService,
       { getUserById: vi.fn(async () => USER) } as unknown as AuthService,
-      workflowService,
-      { emit } as unknown as WorkflowEventBus,
+      versionControlService,
+      { emit } as unknown as VersionControlEventBus,
       allowAll,
       testKbContext({ kbDirName: KB }),
       stubCreatorAccess,