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

package/src/modules/database/__tests__/migrations-unqualified.test.ts

@@ -1,32 +1,32 @@
-import { describe, it, expect } from 'vitest';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { coreMigrationsDir } from '../../../assets.js';
-
-/**
- * A knowledge base hosted beside others lives in a schema of its own, found
- * through `search_path`. A migration that spells `public.` runs against the
- * wrong schema there — creating the table in `public`, or guarding on a
- * constraint that lives elsewhere — and the tenant that runs it is the first
- * to find out. So no migration may name a schema: this reads every file the
- * runner would, so the rule cannot be forgotten by the next one.
- */
-describe('core migrations', () => {
-  it('never qualify a table with a schema', async () => {
-    const dir = coreMigrationsDir();
-    const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.sql')).sort();
-    expect(files.length).toBeGreaterThan(0);
-    const offenders: string[] = [];
-    for (const name of files) {
-      const text = await fs.readFile(path.join(dir, name), 'utf8');
-      text.split('\n').forEach((line, i) => {
-        // Bare (`public.users`) and quoted (`"public"."users"`) alike: the
-        // quoted spelling is what drizzle generates, and it is what a live
-        // two-tenant run found still pointing every tenant's foreign keys at
-        // a `public.users` that does not exist there.
-        if (/\bpublic"?\./.test(line)) offenders.push(`${name}:${i + 1}: ${line.trim()}`);
-      });
-    }
-    expect(offenders).toEqual([]);
-  });
-});
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { coreMigrationsDir } from '../../../assets.js';
+
+/**
+ * A knowledge base hosted beside others lives in a schema of its own, found
+ * through `search_path`. A migration that spells `public.` runs against the
+ * wrong schema there — creating the table in `public`, or guarding on a
+ * constraint that lives elsewhere — and the tenant that runs it is the first
+ * to find out. So no migration may name a schema: this reads every file the
+ * runner would, so the rule cannot be forgotten by the next one.
+ */
+describe('core migrations', () => {
+  it('never qualify a table with a schema', async () => {
+    const dir = coreMigrationsDir();
+    const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.sql')).sort();
+    expect(files.length).toBeGreaterThan(0);
+    const offenders: string[] = [];
+    for (const name of files) {
+      const text = await fs.readFile(path.join(dir, name), 'utf8');
+      text.split('\n').forEach((line, i) => {
+        // Bare (`public.users`) and quoted (`"public"."users"`) alike: the
+        // quoted spelling is what drizzle generates, and it is what a live
+        // two-tenant run found still pointing every tenant's foreign keys at
+        // a `public.users` that does not exist there.
+        if (/\bpublic"?\./.test(line)) offenders.push(`${name}:${i + 1}: ${line.trim()}`);
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/modules/database/core-schema.ts

@@ -1,5 +1,5 @@
 /**
- * CORE platform tables — the git-backed workspace/workflow, auth, access,
+ * CORE platform tables — the git-backed workspace and version control, auth, access,
  * change requests, locks, the pending-commits queue, connection keys, MCP
  * OAuth, the Secrets Vault, and the embed's Atlassian account links. A
  * core-only deployment migrates and runs on exactly these tables.
@@ -323,7 +323,7 @@ export const fileLocks = pgTable('file_locks', {
   holderName: encryptedText('holder_name').notNull(),
   // How the lock was acquired. 'edit' (the default) is a normal write hold —
   // the holder is editing and the release publishes their bytes.
-  // 'coordination' is a pure-mutex hold (see IWorkflowService.acquireLock)
+  // 'coordination' is a pure-mutex hold (see IVersionControlService.acquireLock)
   // that grants NO write authority. Persisted on the row — not inferred at
   // release time — so the write/checkpoint/commit-enqueue paths can refuse
   // to treat a coordination hold as write possession for as long as the row

package/src/modules/diff/__tests__/diff.routes.read-gate.test.ts

@@ -2,7 +2,7 @@ import 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 type { IAccessControl } from '../../access/access-control.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IDiffService } from '../diff.interface.js';
@@ -46,7 +46,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createDiffRoutes(diffService, authService, {} as unknown as IWorkflowService, accessControl, KB));
+  app.use('/api', createDiffRoutes(diffService, authService, {} as unknown as IVersionControlService, accessControl, KB));
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });

package/src/modules/diff/__tests__/diff.routes.rejectPathsLocked.test.ts

@@ -2,10 +2,10 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IDiffService } from '../diff.interface.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../shared/domain-errors.js';
 import { rejectPathsLocked } from '../diff.routes.js';
 
 /**
@@ -21,7 +21,7 @@ const BRANCH = 'alice/revert-test';
 const WORKSPACE_ID = workspaceIdForBranch(BRANCH);
 
 interface Harness {
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   diff: IDiffService;
   calls: string[];
   workspaceDir: string;
@@ -56,7 +56,7 @@ async function makeHarness(overrides: {
     overrides.commit?.();
     return { sha: 'abc', summary } as never;
   });
-  const workflow = { acquireLock, releaseLockNoCommit, commitChanges } as unknown as IWorkflowService;
+  const versionControl = { acquireLock, releaseLockNoCommit, commitChanges } as unknown as IVersionControlService;
 
   const revertPlan = vi.fn(async (_ws: string, paths: string[]) => ({
     workspaceDir,
@@ -66,7 +66,7 @@ async function makeHarness(overrides: {
     deletes: paths.filter((p) => p.endsWith('added.md')),
   }));
   const diff = { revertPlan } as unknown as IDiffService;
-  return { workflow, diff, calls, workspaceDir };
+  return { versionControl, diff, calls, workspaceDir };
 }
 
 describe('rejectPathsLocked', () => {
@@ -82,7 +82,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
 
-    await rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+    await rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
       'knowledge-base/a.md',
       'knowledge-base/added.md',
     ]);
@@ -104,7 +104,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', []),
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', []),
     ).resolves.toBeUndefined();
     expect(h.calls).toEqual([]);
   });
@@ -119,11 +119,11 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
         'knowledge-base/added.md',
       ]),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
 
     // No commit landed and the disk is untouched — the batch is atomic.
     expect(h.calls.some((c) => c.startsWith('commit:'))).toBe(false);
@@ -131,7 +131,7 @@ describe('rejectPathsLocked', () => {
     await expect(fs.access(path.join(h.workspaceDir, 'knowledge-base/added.md'))).resolves.toBeUndefined();
   }, 15_000);
 
-  it('surfaces a commit failure as a WorkflowValidationError and releases without committing', async () => {
+  it('surfaces a commit failure as a VersionControlValidationError and releases without committing', async () => {
     const h = await makeHarness({
       commit: () => {
         throw new Error('push rejected');
@@ -140,10 +140,10 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
       ]),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
     // Locks were dropped via the no-commit path after the failure.
     expect(h.calls.filter((c) => c.startsWith('releaseNoCommit:'))).toHaveLength(1);
   });

package/src/modules/diff/diff.routes.ts

@@ -1,10 +1,10 @@
 import express from 'express';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IDiffService } from './diff.interface.js';
 import type { AuthService } from '../auth/index.js';
 import type { IAccessControl } from '../access/index.js';
 import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/index.js';
-import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError, VersionControlValidationError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { LockingFilesystem } from '../kb-fs/index.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
@@ -13,7 +13,7 @@ import '../auth/index.js';
 function toHttpError(
   err: unknown,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError) {
+  if (err instanceof VersionControlDomainError) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   const message = err instanceof Error ? err.message : 'Unknown error';
@@ -39,7 +39,7 @@ function toHttpError(
  * the first disk mutation, so a restore can never race a concurrent editor.
  */
 export async function rejectPathsLocked(
-  workflowService: IWorkflowService,
+  versionControlService: IVersionControlService,
   diffService: IDiffService,
   workspaceId: string,
   user: AuthUser,
@@ -53,7 +53,7 @@ export async function rejectPathsLocked(
   if (total === 0) return;
   const lockingFs = new LockingFilesystem(
     { basePath: plan.workspaceDir, contained: true },
-    { workflow: workflowService, workspaceId, branch, user, kbDirName },
+    { versionControl: versionControlService, workspaceId, branch, user, kbDirName },
   );
   try {
     await lockingFs.writeFiles(
@@ -71,7 +71,7 @@ export async function rejectPathsLocked(
     const reason = contended
       ? `"${contended[1]}" is being edited by ${contended[2]}`
       : raw.replace(/\.\s*$/, '');
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `Couldn't revert: ${reason}. No changes were committed — try again when the files are free.`,
     );
   }
@@ -88,7 +88,7 @@ export async function rejectPathsLocked(
 export function createDiffRoutes(
   diffService: IDiffService,
   authService: AuthService,
-  workflowService: IWorkflowService,
+  versionControlService: IVersionControlService,
   accessControl: IAccessControl,
   kbDirName: string,
 ): express.Router {
@@ -268,7 +268,7 @@ export function createDiffRoutes(
           current?.changes.map((c) => c.path) ?? [],
         );
       }
-      await rejectPathsLocked(workflowService, diffService, req.params.id, user, kbDirName, paths);
+      await rejectPathsLocked(versionControlService, diffService, req.params.id, user, kbDirName, paths);
       res.json({ session: await diffService.currentSession(req.params.id) });
     } catch (err) {
       const { status, body } = toHttpError(err);

package/src/modules/embed/__tests__/embed.service.lock.test.ts

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { FileLockService } from '../../workflow/file-lock.service.js';
-import { makeFakeLockDb, type FakeLockDb } from '../../workflow/__tests__/fake-file-lock-db.js';
+import { FileLockService } from '../../version-control/file-lock.service.js';
+import { makeFakeLockDb, type FakeLockDb } from '../../version-control/__tests__/fake-file-lock-db.js';
 import { createFileReaderRegistry } from '../../workspace/file-readers/file-reader.registry.js';
 import type { DocExtractOutcome, DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { makeRolesYamlWriteValidator } from '../../access-model/roles-yaml-guard.js';
@@ -19,8 +19,8 @@ import { EmbedLockedError } from '../embed.errors.js';
  * shares the human's user id, and must not steal their edit). On a real boot
  * every Save from the embed answered 409 against the writer's own Edit lock.
  *
- * So the lock half of the workflow service here is the real `FileLockService`
- * over the in-memory `file_locks` table the workflow suites use — the
+ * So the lock half of the version-control service here is the real `FileLockService`
+ * over the in-memory `file_locks` table the version-control suites use — the
  * contention rules come from the code that enforces them.
  */
 
@@ -55,7 +55,7 @@ function build() {
   };
   // The lock verbs go straight to the real service; release drops the row as
   // the real `releaseLock` does once it has enqueued the commit.
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn((id: string, branch: string, path: string) => locks.get(id, branch, path)),
     acquireLock: vi.fn((id: string, branch: string, path: string, user: AuthUser) =>
       locks.acquire(id, branch, path, user),
@@ -80,13 +80,13 @@ function build() {
       isEmailDomainAllowed: () => true,
       isActive: async () => true,
     } as never,
-    workflowService as never,
+    versionControlService as never,
     { remoteBranchExists: async () => false } as never,
     { getUserId: async () => null } as never,
     createFileReaderRegistry(noDocExtract()),
     makeRolesYamlWriteValidator(KB),
   );
-  return { service, workspaceService, workflowService };
+  return { service, workspaceService, versionControlService };
 }
 
 beforeEach(() => {

package/src/modules/embed/__tests__/embed.service.test.ts

@@ -102,11 +102,11 @@ function build(opts: Opts = {}) {
     isEmailDomainAllowed: vi.fn(() => opts.emailDomainAllowed ?? true),
     isActive: vi.fn(async () => opts.active ?? true),
   };
-  const workflowService = {
+  const versionControlService = {
     // No live lock: a save takes it. The contention rules themselves are
     // exercised against the real lock in embed.service.lock.test.ts.
     getLock: vi.fn(async () => null),
-    // The suggestions branch is created here, under the workflow's own
+    // The suggestions branch is created here, under the version-control service's own
     // branch-lifecycle lock, never straight through git.
     createBranch: opts.createBranch ?? vi.fn(async () => ({})),
     acquireLock: vi.fn(async () => ({
@@ -135,7 +135,7 @@ function build(opts: Opts = {}) {
     workspaceService as never,
     accessControl as never,
     authService as never,
-    workflowService as never,
+    versionControlService as never,
     gitService as never,
     accountLinks as never,
     createFileReaderRegistry(noDocExtract()),
@@ -144,7 +144,7 @@ function build(opts: Opts = {}) {
     makeRolesYamlWriteValidator(KB),
     opts.resolveNodeId ?? null,
   );
-  return { service, workspaceService, accessControl, authService, workflowService, gitService, accountLinks };
+  return { service, workspaceService, accessControl, authService, versionControlService, gitService, accountLinks };
 }
 
 /** The token a mint produced, decoded — so a test can assert on the claims. */
@@ -494,18 +494,18 @@ describe('EmbedService: bytes', () => {
 
 describe('EmbedService: saving as a writer', () => {
   it('writes to the default branch and releases the lock, which commits', async () => {
-    const { service, workspaceService, workflowService } = build();
+    const { service, workspaceService, versionControlService } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await service.acquireLock(token);
     await service.save(token, 'new text');
-    expect(workflowService.acquireLock).toHaveBeenCalledWith(
+    expect(versionControlService.acquireLock).toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       BRANCH,
       WS,
       expect.objectContaining({ id: USER.id }),
     );
     expect(workspaceService.writeFile).toHaveBeenCalledWith(encodeURIComponent(BRANCH), WS, 'new text');
-    expect(workflowService.releaseLock).toHaveBeenCalledWith(
+    expect(versionControlService.releaseLock).toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       BRANCH,
       WS,
@@ -526,12 +526,12 @@ describe('EmbedService: saving as a writer', () => {
    * commit to publish.
    */
   it('writes nothing when the viewer no longer holds the lock', async () => {
-    const { service, workspaceService, workflowService } = build({ acquired: false, holderName: 'Bob' });
+    const { service, workspaceService, versionControlService } = build({ acquired: false, holderName: 'Bob' });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.save(token, 'x')).rejects.toThrow(EmbedLockedError);
     await expect(service.save(token, 'x')).rejects.toThrow('Bob');
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   /**
@@ -541,27 +541,27 @@ describe('EmbedService: saving as a writer', () => {
    * have access.
    */
   it('refuses to keep a lock alive for a viewer who lost write access, and releases it', async () => {
-    const { service, accessControl, workflowService } = build();
+    const { service, accessControl, versionControlService } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     accessControl.canWrite.mockResolvedValue(false);
     await expect(service.heartbeat(token)).rejects.toThrow(EmbedAccessError);
-    expect(workflowService.heartbeatLock).not.toHaveBeenCalled();
-    expect(workflowService.releaseLockNoCommit).toHaveBeenCalledWith(
+    expect(versionControlService.heartbeatLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLockNoCommit).toHaveBeenCalledWith(
       expect.any(String),
       BRANCH,
       `${KB}/${REPO}`,
       expect.objectContaining({ id: USER.id }),
     );
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('releases the lock WITHOUT committing when the write fails, and rethrows', async () => {
-    const { service, workspaceService, workflowService } = build();
+    const { service, workspaceService, versionControlService } = build();
     workspaceService.writeFile.mockRejectedValueOnce(new Error('disk full'));
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.save(token, 'x')).rejects.toThrow('disk full');
-    expect(workflowService.releaseLockNoCommit).toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLockNoCommit).toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('refuses Edit and Save to a viewer without write access', async () => {
@@ -594,12 +594,12 @@ describe('EmbedService: saving as a writer', () => {
 
 describe('EmbedService: proposing as a non-writer', () => {
   it('commits to the viewer OWN suggestions branch and opens a change request', async () => {
-    const { service, workspaceService, workflowService } = build({ canWrite: false });
+    const { service, workspaceService, versionControlService } = build({ canWrite: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     const result = await service.propose(token, 'proposed text');
 
     const branch = 'suggestions/alice-u-1/knowledge';
-    expect(workflowService.createBranch).toHaveBeenCalledWith(encodeURIComponent(BRANCH), branch, BRANCH);
+    expect(versionControlService.createBranch).toHaveBeenCalledWith(encodeURIComponent(BRANCH), branch, BRANCH);
     expect(workspaceService.writeFile).toHaveBeenCalledWith(encodeURIComponent(branch), WS, 'proposed text');
     // The write and its commit run inside the workspace service's own
     // per-path turn — the queue every other write surface takes — so two
@@ -607,7 +607,7 @@ describe('EmbedService: proposing as a non-writer', () => {
     expect(workspaceService.withPathTurn).toHaveBeenCalledWith(encodeURIComponent(branch), WS, expect.any(Function));
     const turn = workspaceService.withPathTurn.mock.invocationCallOrder[0]!;
     expect(workspaceService.writeFile.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
-    expect(workflowService.commitChanges.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
+    expect(versionControlService.commitChanges.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
     /**
      * COMMITTED, and committed BEFORE the request is opened.
      *
@@ -617,7 +617,7 @@ describe('EmbedService: proposing as a non-writer', () => {
      * request has no file changes to approve" about a proposal sitting
      * uncommitted on disk. Found on a real boot, not by a stub.
      */
-    expect(workflowService.commitChanges).toHaveBeenCalledWith(
+    expect(versionControlService.commitChanges).toHaveBeenCalledWith(
       encodeURIComponent(branch),
       expect.objectContaining({ id: USER.id }),
       expect.stringContaining(REPO),
@@ -626,10 +626,10 @@ describe('EmbedService: proposing as a non-writer', () => {
       // in-flight write of theirs in under this message.
       [WS],
     );
-    expect(workflowService.commitChanges.mock.invocationCallOrder[0]).toBeLessThan(
-      workflowService.openChangeRequest.mock.invocationCallOrder[0],
+    expect(versionControlService.commitChanges.mock.invocationCallOrder[0]).toBeLessThan(
+      versionControlService.openChangeRequest.mock.invocationCallOrder[0],
     );
-    expect(workflowService.openChangeRequest).toHaveBeenCalledWith(
+    expect(versionControlService.openChangeRequest).toHaveBeenCalledWith(
       encodeURIComponent(branch),
       expect.objectContaining({ id: USER.id }),
       { sourceBranch: branch, targetBranch: BRANCH, title: 'Changes from Alice. Knowledge' },
@@ -638,10 +638,10 @@ describe('EmbedService: proposing as a non-writer', () => {
   });
 
   it('touches NOTHING on the default branch — no lock, no write there', async () => {
-    const { service, workspaceService, workflowService } = build({ canWrite: false });
+    const { service, workspaceService, versionControlService } = build({ canWrite: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await service.propose(token, 'proposed text');
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       expect.anything(),
@@ -653,10 +653,10 @@ describe('EmbedService: proposing as a non-writer', () => {
     const createBranch = vi.fn(async () => {
       throw new Error('a branch named "suggestions/alice-u-1/knowledge" already exists');
     });
-    const { service, workflowService } = build({ canWrite: false, createBranch });
+    const { service, versionControlService } = build({ canWrite: false, createBranch });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, 'x')).resolves.toMatchObject({ number: 42 });
-    expect(workflowService.openChangeRequest).toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).toHaveBeenCalled();
   });
 
   it('a second proposal finds the branch on origin and does not try to create it again', async () => {
@@ -666,11 +666,11 @@ describe('EmbedService: proposing as a non-writer', () => {
     const createBranch = vi.fn(async () => {
       throw new Error('git push failed: ! [rejected] suggestions/alice-u-1/knowledge (non-fast-forward)');
     });
-    const { service, workflowService } = build({ canWrite: false, createBranch, remoteBranchExists: true });
+    const { service, versionControlService } = build({ canWrite: false, createBranch, remoteBranchExists: true });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, 'again')).resolves.toMatchObject({ number: 42 });
     expect(createBranch).not.toHaveBeenCalled();
-    expect(workflowService.openChangeRequest).toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).toHaveBeenCalled();
   });
 
   /**
@@ -706,16 +706,16 @@ describe('EmbedService: proposing as a non-writer', () => {
     // The same PNG-under-a-markdown-name the save test uses: a proposal is a
     // commit of text, and must not commit text over bytes a Save refuses.
     const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]);
-    const { service, workspaceService, workflowService } = build({
+    const { service, workspaceService, versionControlService } = build({
       canWrite: false,
       files: { [WS]: png },
     });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, '# replaced')).rejects.toThrow(EmbedAccessError);
-    expect(workflowService.createBranch).not.toHaveBeenCalled();
+    expect(versionControlService.createBranch).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
-    expect(workflowService.openChangeRequest).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).not.toHaveBeenCalled();
   });
 });
 
@@ -728,7 +728,7 @@ describe('EmbedService: proposing as a non-writer', () => {
  */
 describe('EmbedService: a switched-off account', () => {
   it('reads, saves and proposes nothing on a token minted for it, and is told why', async () => {
-    const { service, workspaceService, workflowService } = build({ active: false });
+    const { service, workspaceService, versionControlService } = build({ active: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     for (const call of [
       () => service.loadFile(token),
@@ -744,8 +744,8 @@ describe('EmbedService: a switched-off account', () => {
     }
     expect(workspaceService.readFileBinary).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
   });
 });
 
@@ -789,24 +789,24 @@ describe('EmbedService: the roles.yaml write gate', () => {
   const VALID = 'roles:\n  Admin:\n    - a@x.eu\n';
 
   it('refuses to save a roles.yaml that would not parse, writing nothing and taking no lock', async () => {
-    const { service, workspaceService, workflowService } = build({ files: { [ROLES]: VALID } });
+    const { service, workspaceService, versionControlService } = build({ files: { [ROLES]: VALID } });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
     await expect(service.save(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('refuses to propose a roles.yaml that would not parse, before any branch is made', async () => {
-    const { service, workspaceService, workflowService } = build({
+    const { service, workspaceService, versionControlService } = build({
       canWrite: false,
       files: { [ROLES]: VALID },
     });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
     await expect(service.propose(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
-    expect(workflowService.createBranch).not.toHaveBeenCalled();
+    expect(versionControlService.createBranch).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
   });
 
   it('saves a roles.yaml that parses, and any other file untouched by the gate', async () => {

package/src/modules/embed/__tests__/embed.tools.test.ts

@@ -57,7 +57,7 @@ async function serve(opts: Opts = {}) {
       ...(caller.tokenId ? { tokenId: caller.tokenId } : {}),
       abortSignal: new AbortController().signal,
       workspaceService: {} as never,
-      workflowService: {} as never,
+      versionControlService: {} as never,
       events: {} as never,
       getFilesystem: async () => {
         throw new Error('open_page reads through readForTool, not the filesystem');

package/src/modules/embed/embed.routes.ts

@@ -332,7 +332,7 @@ function statusFor(err: unknown): number {
   if (err instanceof EmbedNodeNotFoundError) return 404;
   if (err instanceof EmbedLockedError) return 409;
   if (err instanceof EmbedRefParseError) return 400;
-  // A domain error from the workflow layer (a protected-branch refusal, a
+  // A domain error from the version-control layer (a protected-branch refusal, a
   // duplicate request) already carries the status it deserves.
   const status = (err as { status?: unknown })?.status;
   if (typeof status === 'number' && status >= 400 && status < 600) return status;