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

package/src/modules/kb-fs/__tests__/locking-filesystem.test.ts

@@ -2,15 +2,11 @@ import { describe, it, expect, beforeEach, afterEach, vi } 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 { LocalFilesystem } from '@mastra/core/workspace';
 import { LockingFilesystem } from '../locking-filesystem.js';
-import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../../shared/domain-errors.js';
-import {
-  makeAgentRolesYamlWriteValidator,
-  RolesYamlInvalidError,
-  RolesYamlNewRoleError,
-} from '../../access-model/roles-yaml-guard.js';
+import { PushNeedsAgentResolutionError, VersionControlValidationError } from '../../../shared/domain-errors.js';
+import { makeAgentRolesYamlWriteValidator } from '../../access-model/index.js';
 
 /** The clone folder at the workspace root: every path the filesystem mutates lives under it. */
 const KB = 'knowledge-base';
@@ -21,7 +17,7 @@ const USER: AuthUser = {
   name: 'Alice',
 };
 
-function makeWorkflow(): IWorkflowService {
+function makeVersionControl(): IVersionControlService {
   return {
     acquireLock: vi.fn().mockResolvedValue({
       acquired: true,
@@ -42,7 +38,7 @@ function makeWorkflow(): IWorkflowService {
     getLock: vi.fn(),
     commitFileWhileLocked: vi.fn(),
     commitChanges: vi.fn().mockResolvedValue({}),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 }
 
 async function mkTmpRoot(): Promise<string> {
@@ -61,29 +57,29 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
   });
 
   it('writeFile acquires, writes through to disk, then releases', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fsLayer.writeFile('knowledge-base/Knowledge/Foo.md', 'hello\n');
 
-    expect(workflow.acquireLock).toHaveBeenCalledWith(
+    expect(versionControl.acquireLock).toHaveBeenCalledWith(
       'ws-feat',
       'feat',
       'knowledge-base/Knowledge/Foo.md',
       USER,
     );
-    expect(workflow.releaseLock).toHaveBeenCalledWith(
+    expect(versionControl.releaseLock).toHaveBeenCalledWith(
       'ws-feat',
       'feat',
       'knowledge-base/Knowledge/Foo.md',
       USER,
     );
     // Acquire fires before release.
-    const acquireOrder = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock
+    const acquireOrder = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock
       .invocationCallOrder[0];
-    const releaseOrder = (workflow.releaseLock as ReturnType<typeof vi.fn>).mock
+    const releaseOrder = (versionControl.releaseLock as ReturnType<typeof vi.fn>).mock
       .invocationCallOrder[0];
     expect(acquireOrder).toBeLessThan(releaseOrder);
     // The bytes actually landed on disk.
@@ -94,33 +90,33 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
     const filePath = path.join(root, 'knowledge-base/a.md');
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, 'x', 'utf-8');
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fsLayer.deleteFile('knowledge-base/a.md');
-    expect(workflow.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
-    expect(workflow.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
+    expect(versionControl.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
+    expect(versionControl.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
     await expect(fs.access(filePath)).rejects.toBeDefined();
   });
 
   it('mkdir drops a .gitkeep through the lock-aware writeFile so the empty folder is committed', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fsLayer.mkdir('knowledge-base/empty');
     // .gitkeep got written through the lock path. The lock is on the
     // .gitkeep path (that's the file the commit attaches to).
-    expect(workflow.acquireLock).toHaveBeenCalledWith(
+    expect(versionControl.acquireLock).toHaveBeenCalledWith(
       'ws-feat',
       'feat',
       'knowledge-base/empty/.gitkeep',
       USER,
     );
-    expect(workflow.releaseLock).toHaveBeenCalledWith(
+    expect(versionControl.releaseLock).toHaveBeenCalledWith(
       'ws-feat',
       'feat',
       'knowledge-base/empty/.gitkeep',
@@ -132,37 +128,37 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
   it('mkdir of an already-populated dir does NOT drop a .gitkeep', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/has-content'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/has-content/real.md'), 'hi', 'utf-8');
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fsLayer.mkdir('knowledge-base/has-content', { recursive: true });
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
     // The existing file is untouched.
     expect(await fs.readFile(path.join(root, 'knowledge-base/has-content/real.md'), 'utf-8')).toBe('hi');
   });
 
   it('rmdir is refused with a clear error — one-change-per-file invariant', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/doomed'), { recursive: true });
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await expect(fsLayer.rmdir('knowledge-base/doomed')).rejects.toThrow(
       /Recursive directory removal is not supported/i,
     );
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
   });
 
   it(
     'retries acquire on contention then surfaces a skip error after 3 attempts',
     async () => {
       // 3 attempts × 2s ≈ 6s — bump vitest's default timeout for this one test.
-      const workflow = makeWorkflow();
-      (workflow.acquireLock as ReturnType<typeof vi.fn>).mockResolvedValue({
+      const versionControl = makeVersionControl();
+      (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockResolvedValue({
         acquired: false,
         lock: {
           branch: 'feat',
@@ -176,23 +172,23 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
       });
       const fsLayer = new LockingFilesystem(
         { basePath: root, contained: true },
-        { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+        { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
       );
 
       await expect(fsLayer.writeFile('knowledge-base/Locked.md', 'x')).rejects.toThrow(
         /Skipped editing "knowledge-base\/Locked\.md" — locked by Bob/,
       );
-      expect(workflow.acquireLock).toHaveBeenCalledTimes(3);
-      expect(workflow.releaseLock).not.toHaveBeenCalled();
+      expect(versionControl.acquireLock).toHaveBeenCalledTimes(3);
+      expect(versionControl.releaseLock).not.toHaveBeenCalled();
     },
     10_000,
   );
 
   it('drops the lock without committing when the underlying write throws', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     // The underlying write dies (disk full, permissions, whatever). The lock
     // must still go away so the next caller can edit a different file, but
@@ -207,13 +203,13 @@ describe('LockingFilesystem — every mutating op runs acquire → super → rel
     } finally {
       spy.mockRestore();
     }
-    expect(workflow.acquireLock).toHaveBeenCalled();
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.acquireLock).toHaveBeenCalled();
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
   });
 });
 
-describe('LockingFilesystem.writeFiles — batch with deletes + one batched change event', () => {
+describe('LockingFilesystem.writeFiles — batch with deletes', () => {
   let root: string;
 
   beforeEach(async () => {
@@ -224,20 +220,18 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  it('locks writes AND deletes, applies both, emits ONE batched onFilesChanged', async () => {
+  it('locks writes AND deletes, applies both, returns the commit', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/Tools'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Tools/old.tool'), '{}');
 
-    const workflow = makeWorkflow();
-    const emitted: unknown[] = [];
+    const versionControl = makeVersionControl();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
-        workflow,
+        versionControl,
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -248,36 +242,26 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     );
 
     // Both paths locked; both mutations landed; commit returned.
-    expect(workflow.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/new.tool', USER);
-    expect(workflow.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/old.tool', USER);
+    expect(versionControl.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/new.tool', USER);
+    expect(versionControl.acquireLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/old.tool', USER);
     expect(await fs.readFile(path.join(root, 'knowledge-base/Tools/new.tool'), 'utf-8')).toContain('http');
     await expect(fs.access(path.join(root, 'knowledge-base/Tools/old.tool'))).rejects.toThrow();
     expect(change).toEqual({});
-    // ONE event carrying the whole batch (sorted), attributed to the user.
-    expect(emitted).toHaveLength(1);
-    expect(emitted[0]).toMatchObject({
-      workspaceId: 'ws-feat',
-      branch: 'feat',
-      paths: ['knowledge-base/Tools/new.tool', 'knowledge-base/Tools/old.tool'],
-      byUser: USER,
-    });
   });
 
-  it('a failing commit releases every lock WITHOUT committing and emits nothing', async () => {
+  it('a failing commit releases every lock WITHOUT committing', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/Tools'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Tools/old.tool'), '{}');
 
-    const workflow = makeWorkflow();
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('push exploded'));
-    const emitted: unknown[] = [];
+    const versionControl = makeVersionControl();
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('push exploded'));
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
-        workflow,
+        versionControl,
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -291,12 +275,11 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
 
     // Every acquired path goes through the NO-COMMIT release — which is what
     // discards the uncommitted bytes (write reverted, delete restored) in the
-    // real WorkflowService via git.discardPath. The committing release must
-    // never run, and no change event fires for a failed batch.
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/new.tool', USER);
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/old.tool', USER);
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
-    expect(emitted).toHaveLength(0);
+    // real VersionControlService via git.discardPath. The committing release must
+    // never run.
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/new.tool', USER);
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Tools/old.tool', USER);
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
   });
 
   it('a POST-commit push failure releases WITH commit-on-release (arms the worker retry), never the discard path', async () => {
@@ -307,19 +290,17 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
     // forever. The batch must releaseLock (the enqueued release commit no-ops
     // on the clean tree and the worker's unpushed-commits check re-runs the
     // push ladder) and still propagate the error.
-    const workflow = makeWorkflow();
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+    const versionControl = makeVersionControl();
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
       new PushNeedsAgentResolutionError('feat', 'knowledge-base/A.md', 'non-fast-forward', 'rebase failed'),
     );
-    const emitted: unknown[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
-        workflow,
+        versionControl,
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
       },
     );
 
@@ -327,27 +308,8 @@ describe('LockingFilesystem.writeFiles — batch with deletes + one batched chan
       fsLayer.writeFiles([{ path: 'knowledge-base/A.md', content: 'x' }], 'batch'),
     ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
 
-    expect(workflow.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/A.md', USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(emitted).toHaveLength(0);
-  });
-
-  it('emits nothing on a no-op commit (clean tree)', async () => {
-    const workflow = makeWorkflow();
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockResolvedValue(null);
-    const emitted: unknown[] = [];
-    const fsLayer = new LockingFilesystem(
-      { basePath: root, contained: true },
-      {
-        workflow,
-        workspaceId: 'ws-feat',
-        branch: 'feat',
-        user: USER, kbDirName: KB,
-        fileChanges: { emit: (c: unknown) => emitted.push(c) } as never,
-      },
-    );
-    await fsLayer.writeFiles([{ path: 'knowledge-base/A.md', content: 'same' }], 'noop');
-    expect(emitted).toHaveLength(0);
+    expect(versionControl.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/A.md', USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
   });
 });
 
@@ -362,24 +324,24 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  const layer = (workflow: IWorkflowService): LockingFilesystem =>
+  const layer = (versionControl: IVersionControlService): LockingFilesystem =>
     new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
 
   it('writeFile runs the check with the lock HELD and before any byte lands', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'before\n');
 
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const order: string[] = [];
-    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
       order.push('acquire');
       return { acquired: true, lock: { holderName: 'Alice' } };
     });
 
-    await layer(workflow).writeFile('knowledge-base/Foo.md', 'after\n', undefined, async () => {
+    await layer(versionControl).writeFile('knowledge-base/Foo.md', 'after\n', undefined, async () => {
       order.push('check');
       // The check reads the state the write is about to replace.
       expect(await fs.readFile(path.join(root, 'knowledge-base/Foo.md'), 'utf-8')).toBe('before\n');
@@ -393,10 +355,10 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'theirs\n');
 
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const refusal = new Error('already exists');
     await expect(
-      layer(workflow).writeFile('knowledge-base/Foo.md', 'mine\n', undefined, () => {
+      layer(versionControl).writeFile('knowledge-base/Foo.md', 'mine\n', undefined, () => {
         throw refusal;
       }),
     ).rejects.toBe(refusal);
@@ -404,30 +366,30 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     expect(await fs.readFile(path.join(root, 'knowledge-base/Foo.md'), 'utf-8')).toBe('theirs\n');
     // Untouched, never no-commit: a discard would reset the path to HEAD and
     // destroy whatever save left those bytes there.
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
   });
 
   it('rewriteFile reads, computes and writes with the lock HELD, from the bytes on disk at that moment', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'owner: \n');
 
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const order: string[] = [];
-    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
       order.push('acquire');
       // Another writer lands while this call waits for the lock.
       await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'owner: alice\n');
       return { acquired: true, lock: { holderName: 'Alice' } };
     });
-    (workflow.releaseLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+    (versionControl.releaseLock as ReturnType<typeof vi.fn>).mockImplementation(async () => {
       order.push('release');
       return null;
     });
 
     let seen = '';
-    await layer(workflow).rewriteFile('knowledge-base/Foo.md', (current) => {
+    await layer(versionControl).rewriteFile('knowledge-base/Foo.md', (current) => {
       order.push('rewrite');
       seen = current!.toString('utf8');
       return `${seen}note: kept\n`;
@@ -437,32 +399,32 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     // It was handed what the other writer left, not what was there when the call began.
     expect(seen).toBe('owner: alice\n');
     expect(await fs.readFile(path.join(root, 'knowledge-base/Foo.md'), 'utf-8')).toBe('owner: alice\nnote: kept\n');
-    expect(workflow.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
+    expect(versionControl.releaseLock).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
   });
 
   it('a rewriteFile that throws writes nothing, releases UNTOUCHED, and gives the caller its own error', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'theirs\n');
 
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const refusal = new Error('old text is gone');
     await expect(
-      layer(workflow).rewriteFile('knowledge-base/Foo.md', () => {
+      layer(versionControl).rewriteFile('knowledge-base/Foo.md', () => {
         throw refusal;
       }),
     ).rejects.toBe(refusal);
 
     expect(await fs.readFile(path.join(root, 'knowledge-base/Foo.md'), 'utf-8')).toBe('theirs\n');
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/Foo.md', USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
   });
 
   it('rewriteFile hands over null when nothing is at the path', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     let seen: Buffer | null | undefined;
-    await layer(workflow).rewriteFile('knowledge-base/New.md', (current) => {
+    await layer(versionControl).rewriteFile('knowledge-base/New.md', (current) => {
       seen = current;
       return 'made\n';
     });
@@ -473,13 +435,13 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
   it('rewriteFile judges the bytes it is about to write with the pre-disk validator, under the lock', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Foo.md'), 'ok\n');
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const refusal = new Error('refused by the validator');
     const judged: string[] = [];
     const guarded = new LockingFilesystem(
       { basePath: root, contained: true },
       {
-        workflow,
+        versionControl,
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER,
@@ -493,19 +455,19 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     await expect(guarded.rewriteFile('knowledge-base/Foo.md', () => 'bad\n')).rejects.toBe(refusal);
     expect(judged).toEqual(['bad\n']);
     expect(await fs.readFile(path.join(root, 'knowledge-base/Foo.md'), 'utf-8')).toBe('ok\n');
-    expect(workflow.releaseLockUntouched).toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalled();
   });
 
   it('rewriteFile refuses a path outside the repository before any lock', async () => {
-    const workflow = makeWorkflow();
-    await expect(layer(workflow).rewriteFile('elsewhere/Foo.md', () => 'x')).rejects.toThrow();
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
+    const versionControl = makeVersionControl();
+    await expect(layer(versionControl).rewriteFile('elsewhere/Foo.md', () => 'x')).rejects.toThrow();
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
   });
 
   it('writeFiles runs its check once EVERY lock is held, and lands only what the check keeps', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const acquired: string[] = [];
-    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w, _b, p: string) => {
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w, _b, p: string) => {
       acquired.push(p);
       return { acquired: true, lock: { holderName: 'Alice' } };
     });
@@ -515,7 +477,7 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
       { path: 'knowledge-base/b.md', content: 'B' },
       { path: 'knowledge-base/c.md', content: 'C' },
     ];
-    await layer(workflow).writeFiles(writes, 'batch', [], async (pending) => {
+    await layer(versionControl).writeFiles(writes, 'batch', [], async (pending) => {
       // Every path of the batch is locked before the check gets to judge any.
       expect([...acquired].sort()).toEqual(['knowledge-base/a.md', 'knowledge-base/b.md', 'knowledge-base/c.md']);
       expect(pending.map((w) => w.path)).toEqual(writes.map((w) => w.path));
@@ -528,16 +490,16 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     // The dropped path stays OUT of the commit's scope — an unscoped commit
     // there would sweep in whatever another save left dirty on it — and
     // releases untouched, because this batch never wrote a byte to it.
-    expect(workflow.commitChanges).toHaveBeenCalledWith('ws-feat', USER, 'batch', [
+    expect(versionControl.commitChanges).toHaveBeenCalledWith('ws-feat', USER, 'batch', [
       'knowledge-base/a.md',
       'knowledge-base/c.md',
     ]);
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/b.md', USER);
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/b.md', USER);
   });
 
   it('a writeFiles check that drops EVERY write commits nothing and releases everything untouched', async () => {
-    const workflow = makeWorkflow();
-    const change = await layer(workflow).writeFiles(
+    const versionControl = makeVersionControl();
+    const change = await layer(versionControl).writeFiles(
       [{ path: 'knowledge-base/a.md', content: 'A' }],
       'batch',
       [],
@@ -546,15 +508,15 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
 
     expect(change).toBeNull();
     await expect(fs.access(path.join(root, 'knowledge-base/a.md'))).rejects.toThrow();
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/a.md', USER);
   });
 
   it('a writeFiles check that THROWS refuses the whole batch, untouched', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const refusal = new Error('nope');
     await expect(
-      layer(workflow).writeFiles(
+      layer(versionControl).writeFiles(
         [{ path: 'knowledge-base/a.md', content: 'A' }, { path: 'knowledge-base/b.md', content: 'B' }],
         'batch',
         [],
@@ -565,8 +527,8 @@ describe('LockingFilesystem — the caller judges under the lock', () => {
     ).rejects.toBe(refusal);
 
     await expect(fs.access(path.join(root, 'knowledge-base/a.md'))).rejects.toThrow();
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledTimes(2);
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(2);
   });
 });
 
@@ -589,11 +551,11 @@ describe('LockingFilesystem — creator read grants on creation', () => {
   }
 
   it('writeFile asks the planner about the new file and lands the content untouched', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFile('knowledge-base/KnowledgeBase/new.md', '# New\n');
     expect(creatorAccess.planForCreate).toHaveBeenCalledWith(
@@ -608,7 +570,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
   });
 
   it('writeFile seeds a subtree access.md (own lock cycle) before the file itself', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockImplementation(async (_w, _u, p: string) =>
       p === 'knowledge-base/KnowledgeBase/Mine/doc.md'
@@ -622,10 +584,10 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     );
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFile('knowledge-base/KnowledgeBase/Mine/doc.md', 'body');
-    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map(
+    const locked = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map(
       (c) => c[2],
     );
     expect(locked).toEqual(['knowledge-base/KnowledgeBase/Mine/access.md', 'knowledge-base/KnowledgeBase/Mine/doc.md']);
@@ -638,7 +600,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
   });
 
   it('mkdir seeds the new folder access.md and then skips the .gitkeep (dir not empty)', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockImplementation(async (_w, _u, p: string, kind: string) =>
       kind === 'dir'
@@ -651,7 +613,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     );
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.mkdir('knowledge-base/KnowledgeBase/Projects');
     expect(
@@ -663,7 +625,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
   });
 
   it('writeFiles folds seeds into the same atomic batch, deduped across files', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
@@ -672,7 +634,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFiles(
       [
@@ -685,8 +647,8 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     expect(
       await fs.readFile(path.join(root, 'knowledge-base/KnowledgeBase/Mine/access.md'), 'utf-8'),
     ).toContain('Alice <alice@example.com>');
-    expect(workflow.commitChanges).toHaveBeenCalledTimes(1);
-    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map(
+    expect(versionControl.commitChanges).toHaveBeenCalledTimes(1);
+    const locked = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map(
       (c) => c[2],
     );
     expect(locked).toEqual([
@@ -707,34 +669,31 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase/Mine'), { recursive: true });
     const seedContent = '---\nread:\n  - Alice <alice@example.com>\n---\n';
     await fs.writeFile(path.join(root, 'knowledge-base/KnowledgeBase/Mine/access.md'), seedContent);
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
       wsRelPath: 'knowledge-base/KnowledgeBase/Mine/access.md',
       apply: (current: string) => current, // grant already present → no-op
     });
-    const emitted: { paths: string[] }[] = [];
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
       {
-        workflow,
+        versionControl,
         workspaceId: 'ws-feat',
         branch: 'feat',
         user: USER, kbDirName: KB,
         creatorAccess,
-        fileChanges: { emit: (c: { paths: string[] }) => emitted.push(c) } as never,
       },
     );
     await fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
 
     // The seed's lock cycle still ran (acquired + released)...
-    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2]);
+    const locked = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2]);
     expect(locked).toContain('knowledge-base/KnowledgeBase/Mine/access.md');
     // ...but the commit is scoped to the caller's path only.
-    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    const commitPaths = (versionControl.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
     expect(commitPaths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
-    expect(emitted[0].paths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
     // The seeded file is untouched.
     expect(await fs.readFile(path.join(root, 'knowledge-base/KnowledgeBase/Mine/access.md'), 'utf-8')).toBe(
       seedContent,
@@ -756,7 +715,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase/Mine'), { recursive: true });
     const priorSave = '---\nread:\n  - Alice <alice@example.com>\n---\nprior queued bytes\n';
     await fs.writeFile(path.join(root, 'knowledge-base/KnowledgeBase/Mine/access.md'), priorSave);
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
@@ -765,21 +724,21 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
 
     // The batch's OWN committed path releases no-commit (clean — discard no-ops)...
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith(
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith(
       'ws-feat', 'feat', 'knowledge-base/KnowledgeBase/Mine/doc.md', USER,
     );
     // ...but the merely-locked seed path releases UNTOUCHED — never the
     // enqueue, never the discard.
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith(
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith(
       'ws-feat', 'feat', 'knowledge-base/KnowledgeBase/Mine/access.md', USER,
     );
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalledWith(
       'ws-feat', 'feat', 'knowledge-base/KnowledgeBase/Mine/access.md', USER,
     );
   });
@@ -788,13 +747,13 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     // First path acquires, second is contended: nothing has been written, so
     // the first path may hold ONLY someone else's still-queued bytes — the
     // unwind must neither discard them nor enqueue them under this user.
-    const workflow = makeWorkflow();
-    (workflow.acquireLock as ReturnType<typeof vi.fn>)
+    const versionControl = makeVersionControl();
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>)
       .mockResolvedValueOnce({ acquired: true, lock: { holderUserId: 'user-1', holderName: 'Alice' } })
       .mockResolvedValue({ acquired: false, lock: { holderUserId: 'bob', holderName: 'Bob' } });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await expect(
       fsLayer.writeFiles(
@@ -805,9 +764,9 @@ describe('LockingFilesystem — creator read grants on creation', () => {
         'batch',
       ),
     ).rejects.toThrow(/locked by Bob/);
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/A.md', USER);
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', 'knowledge-base/A.md', USER);
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
   }, 10_000);
 
   it('a DELETE batch whose later lock is contended deletes nothing — a folder never half-disappears', async () => {
@@ -817,13 +776,13 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     await fs.mkdir(path.join(root, 'knowledge-base/Archive'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/Archive/a.md'), 'a');
     await fs.writeFile(path.join(root, 'knowledge-base/Archive/b.md'), 'b');
-    const workflow = makeWorkflow();
-    (workflow.acquireLock as ReturnType<typeof vi.fn>)
+    const versionControl = makeVersionControl();
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>)
       .mockResolvedValueOnce({ acquired: true, lock: { holderUserId: 'user-1', holderName: 'Alice' } })
       .mockResolvedValue({ acquired: false, lock: { holderUserId: 'bob', holderName: 'Bob' } });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
 
     await expect(
@@ -832,7 +791,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
 
     expect(await fs.readFile(path.join(root, 'knowledge-base/Archive/a.md'), 'utf-8')).toBe('a');
     expect(await fs.readFile(path.join(root, 'knowledge-base/Archive/b.md'), 'utf-8')).toBe('b');
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
   }, 10_000);
 
   it('a seed write that dies MID-WRITE restores the pre-image and releases UNTOUCHED', async () => {
@@ -845,7 +804,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     const priorBytes = 'prior queued bytes\n';
     const seedPath = 'knowledge-base/KnowledgeBase/Mine/access.md';
     await fs.writeFile(path.join(root, seedPath), priorBytes);
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
@@ -854,7 +813,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     // Fail the SEED write once (simulating a mid-write death that left
     // partial bytes); every other write — including the restore — passes
@@ -879,13 +838,13 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     // Pre-image restored — the partial bytes did not outlive the batch.
     expect(await fs.readFile(path.join(root, seedPath), 'utf-8')).toBe(priorBytes);
     // The failed seed stays OUT of the commit scope and releases untouched.
-    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    const commitPaths = (versionControl.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
     expect(commitPaths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalledWith(
       'ws-feat', 'feat', seedPath, USER,
     );
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
   });
 
   it('a LANDED seed rolls back to its pre-image when the batch commit fails — grant bytes must not outlive the batch uncommitted', async () => {
@@ -899,8 +858,8 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     const priorBytes = 'prior queued bytes\n';
     const seedPath = 'knowledge-base/KnowledgeBase/Mine/access.md';
     await fs.writeFile(path.join(root, seedPath), priorBytes);
-    const workflow = makeWorkflow();
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+    const versionControl = makeVersionControl();
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
       new Error('commit exploded'),
     );
     const creatorAccess = makeCreatorAccess();
@@ -911,7 +870,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await expect(
       fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch'),
@@ -920,11 +879,11 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     expect(await fs.readFile(path.join(root, seedPath), 'utf-8')).toBe(priorBytes);
     // …and the seed releases UNTOUCHED (the prior queued bytes are not this
     // batch's to discard), while the caller's own write releases via discard.
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith(
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith(
       'ws-feat', 'feat', 'knowledge-base/KnowledgeBase/Mine/doc.md', USER,
     );
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalledWith(
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalledWith(
       'ws-feat', 'feat', seedPath, USER,
     );
   });
@@ -937,7 +896,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase/Mine'), { recursive: true });
     const seedPath = 'knowledge-base/KnowledgeBase/Mine/access.md';
     await fs.writeFile(path.join(root, seedPath), 'prior\n');
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
@@ -946,7 +905,7 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     const original = LocalFilesystem.prototype.writeFile;
     const spy = vi
@@ -962,12 +921,12 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     }
     // The unrecoverable seed path releases via the discard, everything else
     // untouched-or-no-commit as usual; the batch itself still succeeds.
-    expect(workflow.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
-    expect(workflow.releaseLockUntouched).not.toHaveBeenCalledWith(
+    expect(versionControl.releaseLockNoCommit).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(versionControl.releaseLockUntouched).not.toHaveBeenCalledWith(
       'ws-feat', 'feat', seedPath, USER,
     );
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
-    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    const commitPaths = (versionControl.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
     expect(commitPaths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md']);
   });
 
@@ -980,8 +939,8 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase/Mine'), { recursive: true });
     const seedPath = 'knowledge-base/KnowledgeBase/Mine/access.md';
     await fs.writeFile(path.join(root, seedPath), 'grant already present\n');
-    const workflow = makeWorkflow();
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
+    const versionControl = makeVersionControl();
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValue(
       new PushNeedsAgentResolutionError('feat', '(batch)', 'non-fast-forward', 'rebase failed'),
     );
     const creatorAccess = makeCreatorAccess();
@@ -992,21 +951,21 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await expect(
       fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch'),
     ).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
-    expect(workflow.releaseLock).toHaveBeenCalledWith(
+    expect(versionControl.releaseLock).toHaveBeenCalledWith(
       'ws-feat', 'feat', 'knowledge-base/KnowledgeBase/Mine/doc.md', USER,
     );
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
-    expect(workflow.releaseLock).not.toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(versionControl.releaseLock).not.toHaveBeenCalledWith('ws-feat', 'feat', seedPath, USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
   });
 
   it('a LANDED seed rides the commit scope with the caller paths', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockResolvedValue({
       kind: 'seed-access-md',
@@ -1015,20 +974,20 @@ describe('LockingFilesystem — creator read grants on creation', () => {
     });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFiles([{ path: 'knowledge-base/KnowledgeBase/Mine/doc.md', content: 'body' }], 'batch');
-    const commitPaths = (workflow.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
+    const commitPaths = (versionControl.commitChanges as ReturnType<typeof vi.fn>).mock.calls[0][3];
     expect(commitPaths).toEqual(['knowledge-base/KnowledgeBase/Mine/doc.md', 'knowledge-base/KnowledgeBase/Mine/access.md']);
   });
 
   it('a planner failure never blocks the write', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const creatorAccess = makeCreatorAccess();
     creatorAccess.planForCreate.mockRejectedValue(new Error('planner down'));
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess },
     );
     await fsLayer.writeFile('knowledge-base/KnowledgeBase/new.md', 'x');
     expect(await fs.readFile(path.join(root, 'knowledge-base/KnowledgeBase/new.md'), 'utf-8')).toBe('x');
@@ -1064,50 +1023,50 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
     };
   }
 
-  function layer(workflow: IWorkflowService) {
+  function layer(versionControl: IVersionControlService) {
     const creatorAccess = makeCreatorAccess();
     const validateWrite = vi.fn();
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess, validateWrite },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, creatorAccess, validateWrite },
     );
     return { fsLayer, creatorAccess, validateWrite };
   }
 
   async function expectRefused(
     op: Promise<unknown>,
-    workflow: IWorkflowService,
+    versionControl: IVersionControlService,
     creatorAccess: ReturnType<typeof makeCreatorAccess>,
     validateWrite: ReturnType<typeof vi.fn>,
   ): Promise<void> {
-    await expect(op).rejects.toBeInstanceOf(WorkflowValidationError);
+    await expect(op).rejects.toBeInstanceOf(VersionControlValidationError);
     // The corrected path is spelled out, under the clone folder.
     await expect(op).rejects.toThrow('"knowledge-base/KnowledgeBase/Reviews');
     // Refused before any side effect.
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
     expect(creatorAccess.planForCreate).not.toHaveBeenCalled();
     expect(validateWrite).not.toHaveBeenCalled();
     await expect(fs.access(path.join(root, 'KnowledgeBase'))).rejects.toBeDefined();
   }
 
   it('writeFile', async () => {
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
-    await expectRefused(fsLayer.writeFile(STRAY, '<p>review</p>'), workflow, creatorAccess, validateWrite);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
+    await expectRefused(fsLayer.writeFile(STRAY, '<p>review</p>'), versionControl, creatorAccess, validateWrite);
   });
 
   it('appendFile', async () => {
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
-    await expectRefused(fsLayer.appendFile('KnowledgeBase/Reviews/review.log', 'line\n'), workflow, creatorAccess, validateWrite);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
+    await expectRefused(fsLayer.appendFile('KnowledgeBase/Reviews/review.log', 'line\n'), versionControl, creatorAccess, validateWrite);
   });
 
   it('writeFiles refuses the whole batch when one path is outside: nothing written, nothing locked', async () => {
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
     await expectRefused(
       fsLayer.writeFiles(
         [
@@ -1116,7 +1075,7 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
         ],
         'batch',
       ),
-      workflow,
+      versionControl,
       creatorAccess,
       validateWrite,
     );
@@ -1124,19 +1083,19 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
   });
 
   it('mkdir', async () => {
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
-    await expectRefused(fsLayer.mkdir('KnowledgeBase/Reviews'), workflow, creatorAccess, validateWrite);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
+    await expectRefused(fsLayer.mkdir('KnowledgeBase/Reviews'), versionControl, creatorAccess, validateWrite);
   });
 
   it('moveFile refuses a destination outside the repository and leaves the source in place', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/KnowledgeBase/PR-12.html'), 'x');
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
     await expectRefused(
       fsLayer.moveFile('knowledge-base/KnowledgeBase/PR-12.html', STRAY),
-      workflow,
+      versionControl,
       creatorAccess,
       validateWrite,
     );
@@ -1146,11 +1105,11 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
   it('copyFile refuses a destination outside the repository', async () => {
     await fs.mkdir(path.join(root, 'knowledge-base/KnowledgeBase'), { recursive: true });
     await fs.writeFile(path.join(root, 'knowledge-base/KnowledgeBase/PR-12.html'), 'x');
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
     await expectRefused(
       fsLayer.copyFile('knowledge-base/KnowledgeBase/PR-12.html', STRAY),
-      workflow,
+      versionControl,
       creatorAccess,
       validateWrite,
     );
@@ -1160,20 +1119,20 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
     // Containment is checked against the WORKSPACE dir, so the underlying
     // filesystem would happily resolve `knowledge-base/../stray.md` to a file
     // next to the clone. The prefix alone is not proof of being inside.
-    const workflow = makeWorkflow();
-    const { fsLayer, creatorAccess, validateWrite } = layer(workflow);
-    await expect(fsLayer.writeFile('knowledge-base/../stray.md', 'x')).rejects.toBeInstanceOf(WorkflowValidationError);
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
+    const versionControl = makeVersionControl();
+    const { fsLayer, creatorAccess, validateWrite } = layer(versionControl);
+    await expect(fsLayer.writeFile('knowledge-base/../stray.md', 'x')).rejects.toBeInstanceOf(VersionControlValidationError);
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
     expect(creatorAccess.planForCreate).not.toHaveBeenCalled();
     expect(validateWrite).not.toHaveBeenCalled();
     await expect(fs.access(path.join(root, 'stray.md'))).rejects.toBeDefined();
   });
 
   it('the folder is matched as a whole segment: `knowledge-based/x.md` is outside too', async () => {
-    const workflow = makeWorkflow();
-    const { fsLayer } = layer(workflow);
-    await expect(fsLayer.writeFile('knowledge-based/x.md', 'x')).rejects.toBeInstanceOf(WorkflowValidationError);
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
+    const versionControl = makeVersionControl();
+    const { fsLayer } = layer(versionControl);
+    await expect(fsLayer.writeFile('knowledge-based/x.md', 'x')).rejects.toBeInstanceOf(VersionControlValidationError);
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
   });
 
   it('deleteFile still removes a file the old behaviour left beside the repository', async () => {
@@ -1181,8 +1140,8 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
     // created before this guard existed must be able to clean it up.
     await fs.mkdir(path.join(root, 'KnowledgeBase/Reviews'), { recursive: true });
     await fs.writeFile(path.join(root, STRAY), 'stray');
-    const workflow = makeWorkflow();
-    const { fsLayer } = layer(workflow);
+    const versionControl = makeVersionControl();
+    const { fsLayer } = layer(versionControl);
     await fsLayer.deleteFile(STRAY);
     await expect(fs.access(path.join(root, STRAY))).rejects.toBeDefined();
   });
@@ -1191,8 +1150,8 @@ describe('LockingFilesystem refuses to create anything outside the repository fo
     await fs.mkdir(path.join(root, 'KnowledgeBase/Reviews'), { recursive: true });
     await fs.writeFile(path.join(root, STRAY), 'stray');
     await fs.mkdir(path.join(root, 'knowledge-base'), { recursive: true });
-    const workflow = makeWorkflow();
-    const { fsLayer } = layer(workflow);
+    const versionControl = makeVersionControl();
+    const { fsLayer } = layer(versionControl);
     await fsLayer.moveFile(STRAY, CORRECTED);
     expect(await fs.readFile(path.join(root, CORRECTED), 'utf-8')).toBe('stray');
     await expect(fs.access(path.join(root, STRAY))).rejects.toBeDefined();
@@ -1217,85 +1176,85 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
     await fs.rm(root, { recursive: true, force: true });
   });
 
-  function layer(workflow: IWorkflowService) {
+  function layer(versionControl: IVersionControlService) {
     const validateWrite = makeAgentRolesYamlWriteValidator(KB, () =>
       fs.readFile(path.join(root, ROLES), 'utf-8').catch(() => null),
     );
     return new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite },
     );
   }
 
-  async function expectRefused(op: Promise<unknown>, workflow: IWorkflowService): Promise<void> {
-    await expect(op).rejects.toBeInstanceOf(RolesYamlNewRoleError);
-    expect(workflow.acquireLock).not.toHaveBeenCalled();
+  async function expectRefused(op: Promise<unknown>, versionControl: IVersionControlService): Promise<void> {
+    await expect(op).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-new-role' } });
+    expect(versionControl.acquireLock).not.toHaveBeenCalled();
     expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(CURRENT);
   }
 
   it('writeFile', async () => {
-    const workflow = makeWorkflow();
-    await expectRefused(layer(workflow).writeFile(ROLES, CURRENT + NEW_ROLE), workflow);
+    const versionControl = makeVersionControl();
+    await expectRefused(layer(versionControl).writeFile(ROLES, CURRENT + NEW_ROLE), versionControl);
   });
 
   it('writeFiles refuses the whole batch', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     await expectRefused(
-      layer(workflow).writeFiles([{ path: `${KB}/KnowledgeBase/ok.md`, content: 'fine' }, { path: ROLES, content: CURRENT + NEW_ROLE }], 'batch'),
-      workflow,
+      layer(versionControl).writeFiles([{ path: `${KB}/KnowledgeBase/ok.md`, content: 'fine' }, { path: ROLES, content: CURRENT + NEW_ROLE }], 'batch'),
+      versionControl,
     );
     await expect(fs.access(path.join(root, KB, 'KnowledgeBase/ok.md'))).rejects.toBeDefined();
   });
 
   it('appendFile, judged by the file it would leave', async () => {
-    const workflow = makeWorkflow();
-    await expectRefused(layer(workflow).appendFile(ROLES, NEW_ROLE), workflow);
+    const versionControl = makeVersionControl();
+    await expectRefused(layer(versionControl).appendFile(ROLES, NEW_ROLE), versionControl);
   });
 
   it('copyFile, judged by the source bytes', async () => {
-    const workflow = makeWorkflow();
-    await expectRefused(layer(workflow).copyFile(DRAFT, ROLES, { overwrite: true }), workflow);
+    const versionControl = makeVersionControl();
+    await expectRefused(layer(versionControl).copyFile(DRAFT, ROLES, { overwrite: true }), versionControl);
   });
 
   it('moveFile, leaving the source where it was', async () => {
-    const workflow = makeWorkflow();
-    await expectRefused(layer(workflow).moveFile(DRAFT, ROLES, { overwrite: true }), workflow);
+    const versionControl = makeVersionControl();
+    await expectRefused(layer(versionControl).moveFile(DRAFT, ROLES, { overwrite: true }), versionControl);
     expect(await fs.readFile(path.join(root, DRAFT), 'utf-8')).toBe(CURRENT + NEW_ROLE);
   });
 
   it('a members-only write and append land as before', async () => {
-    const workflow = makeWorkflow();
-    const fsLayer = layer(workflow);
+    const versionControl = makeVersionControl();
+    const fsLayer = layer(versionControl);
     await fsLayer.writeFile(ROLES, `${CURRENT}    - b@x.eu\n`);
     await fsLayer.appendFile(ROLES, '    - c@x.eu\n');
     expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(`${CURRENT}    - b@x.eu\n    - c@x.eu\n`);
-    expect(workflow.releaseLock).toHaveBeenCalledTimes(2);
+    expect(versionControl.releaseLock).toHaveBeenCalledTimes(2);
   });
 
   describe('judged again under the lock, against what a concurrent writer left there', () => {
     const WITH_PHOENIX = CURRENT + NEW_ROLE;
 
-    /** A workflow whose acquire lets `race` rewrite disk first — the lock holder that finished just before us. */
-    function racingWorkflow(race: () => Promise<void>): IWorkflowService {
-      const workflow = makeWorkflow();
-      const acquired = (workflow.acquireLock as ReturnType<typeof vi.fn>).getMockImplementation()!;
+    /** A version-control service whose acquire lets `race` rewrite disk first — the lock holder that finished just before us. */
+    function racingVersionControl(race: () => Promise<void>): IVersionControlService {
+      const versionControl = makeVersionControl();
+      const acquired = (versionControl.acquireLock as ReturnType<typeof vi.fn>).getMockImplementation()!;
       let raced = false;
-      (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
+      (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
         if (!raced) {
           raced = true;
           await race();
         }
         return acquired(...args);
       });
-      return workflow;
+      return versionControl;
     }
 
-    async function expectRefusedUnderLock(op: Promise<unknown>, workflow: IWorkflowService, locks: number): Promise<void> {
-      await expect(op).rejects.toBeInstanceOf(RolesYamlNewRoleError);
-      expect(workflow.releaseLockUntouched).toHaveBeenCalledTimes(locks);
-      expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-      expect(workflow.releaseLock).not.toHaveBeenCalled();
-      expect(workflow.commitChanges).not.toHaveBeenCalled();
+    async function expectRefusedUnderLock(op: Promise<unknown>, versionControl: IVersionControlService, locks: number): Promise<void> {
+      await expect(op).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-new-role' } });
+      expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(locks);
+      expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+      expect(versionControl.releaseLock).not.toHaveBeenCalled();
+      expect(versionControl.commitChanges).not.toHaveBeenCalled();
       expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(CURRENT);
     }
 
@@ -1306,15 +1265,15 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
     });
 
     it('writeFile cannot reinstate a role deleted while it waited for the lock', async () => {
-      const workflow = racingWorkflow(deletePhoenix);
-      await expectRefusedUnderLock(layer(workflow).writeFile(ROLES, `${WITH_PHOENIX}    - q@x.eu\n`), workflow, 1);
+      const versionControl = racingVersionControl(deletePhoenix);
+      await expectRefusedUnderLock(layer(versionControl).writeFile(ROLES, `${WITH_PHOENIX}    - q@x.eu\n`), versionControl, 1);
     });
 
     it('writeFiles re-judges the whole batch once every lock is held', async () => {
-      const workflow = racingWorkflow(deletePhoenix);
+      const versionControl = racingVersionControl(deletePhoenix);
       await expectRefusedUnderLock(
-        layer(workflow).writeFiles([{ path: `${KB}/KnowledgeBase/ok.md`, content: 'fine' }, { path: ROLES, content: WITH_PHOENIX }], 'batch'),
-        workflow,
+        layer(versionControl).writeFiles([{ path: `${KB}/KnowledgeBase/ok.md`, content: 'fine' }, { path: ROLES, content: WITH_PHOENIX }], 'batch'),
+        versionControl,
         2,
       );
       await expect(fs.access(path.join(root, KB, 'KnowledgeBase/ok.md'))).rejects.toBeDefined();
@@ -1324,31 +1283,31 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
       // Appending never adds a role the file had before, so what a race can
       // change is validity: the same line appended to the rewritten file breaks it.
       const rewritten = 'roles:\n  Admin:\n    - a@x.eu';
-      const workflow = racingWorkflow(() => fs.writeFile(path.join(root, ROLES), rewritten));
-      await expect(layer(workflow).appendFile(ROLES, '    - b@x.eu\n')).rejects.toBeInstanceOf(RolesYamlInvalidError);
-      expect(workflow.releaseLockUntouched).toHaveBeenCalledTimes(1);
-      expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+      const versionControl = racingVersionControl(() => fs.writeFile(path.join(root, ROLES), rewritten));
+      await expect(layer(versionControl).appendFile(ROLES, '    - b@x.eu\n')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
+      expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(1);
+      expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
       expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(rewritten);
     });
 
     it('copyFile judges — and writes — the source bytes read under the lock', async () => {
       await fs.writeFile(path.join(root, DRAFT), WITH_PHOENIX);
-      const workflow = racingWorkflow(deletePhoenix);
-      await expectRefusedUnderLock(layer(workflow).copyFile(DRAFT, ROLES, { overwrite: true }), workflow, 1);
+      const versionControl = racingVersionControl(deletePhoenix);
+      await expectRefusedUnderLock(layer(versionControl).copyFile(DRAFT, ROLES, { overwrite: true }), versionControl, 1);
     });
 
     it('moveFile re-judges with both locks held, and both release untouched', async () => {
       await fs.writeFile(path.join(root, DRAFT), WITH_PHOENIX);
-      const workflow = racingWorkflow(deletePhoenix);
-      await expectRefusedUnderLock(layer(workflow).moveFile(DRAFT, ROLES, { overwrite: true }), workflow, 2);
+      const versionControl = racingVersionControl(deletePhoenix);
+      await expectRefusedUnderLock(layer(versionControl).moveFile(DRAFT, ROLES, { overwrite: true }), versionControl, 2);
       expect(await fs.readFile(path.join(root, DRAFT), 'utf-8')).toBe(WITH_PHOENIX);
     });
 
     it('a members-only write whose roles all survive the wait still lands', async () => {
-      const workflow = racingWorkflow(() => fs.writeFile(path.join(root, ROLES), `${WITH_PHOENIX}    - q@x.eu\n`));
-      await layer(workflow).writeFile(ROLES, `${CURRENT}    - b@x.eu\n`);
+      const versionControl = racingVersionControl(() => fs.writeFile(path.join(root, ROLES), `${WITH_PHOENIX}    - q@x.eu\n`));
+      await layer(versionControl).writeFile(ROLES, `${CURRENT}    - b@x.eu\n`);
       expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(`${CURRENT}    - b@x.eu\n`);
-      expect(workflow.releaseLock).toHaveBeenCalledTimes(1);
+      expect(versionControl.releaseLock).toHaveBeenCalledTimes(1);
     });
 
     /** A validator that passes before the lock and refuses under it by throwing a bare string. */
@@ -1363,36 +1322,36 @@ describe('LockingFilesystem — the agent roles.yaml gate covers every op that l
     }
 
     it('a check that throws a non-Error still releases untouched, and the caller gets that value', async () => {
-      const workflow = makeWorkflow();
+      const versionControl = makeVersionControl();
       const fsLayer = new LockingFilesystem(
         { basePath: root, contained: true },
-        { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite: refusesUnderLockWith('refused') },
+        { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite: refusesUnderLockWith('refused') },
       );
       await expect(fsLayer.writeFile(ROLES, CURRENT)).rejects.toBe('refused');
-      expect(workflow.releaseLockUntouched).toHaveBeenCalledTimes(1);
-      expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+      expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(1);
+      expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
       expect(await fs.readFile(path.join(root, ROLES), 'utf-8')).toBe(WITH_PHOENIX);
     });
 
     it('a move whose check throws a non-Error releases BOTH locks untouched', async () => {
-      const workflow = makeWorkflow();
+      const versionControl = makeVersionControl();
       const fsLayer = new LockingFilesystem(
         { basePath: root, contained: true },
-        { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite: refusesUnderLockWith('refused') },
+        { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite: refusesUnderLockWith('refused') },
       );
       await expect(fsLayer.moveFile(DRAFT, ROLES, { overwrite: true })).rejects.toBe('refused');
-      expect(workflow.releaseLockUntouched).toHaveBeenCalledTimes(2);
-      expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
+      expect(versionControl.releaseLockUntouched).toHaveBeenCalledTimes(2);
+      expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
       expect(await fs.readFile(path.join(root, DRAFT), 'utf-8')).toBe(WITH_PHOENIX);
     });
   });
 
   it('a copy elsewhere never reads its source for a validator that does not claim the destination', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const validateWrite = Object.assign(vi.fn(), { appliesTo: vi.fn(() => false) });
     const fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB, validateWrite },
     );
     await fsLayer.copyFile(DRAFT, `${KB}/KnowledgeBase/copy.yaml`);
     expect(validateWrite.appliesTo).toHaveBeenCalledWith(`${KB}/KnowledgeBase/copy.yaml`);
@@ -1421,7 +1380,7 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
     await fs.writeFile(onDisk(SOURCE), 'source');
     fsLayer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow: makeWorkflow(), workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl: makeVersionControl(), workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
   });
 
@@ -1463,10 +1422,10 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
    * every lock it unwinds releases untouched.
    */
   it('releases UNTOUCHED when the destination is taken, so a lost race cannot eat the winner', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const layer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fs.writeFile(onDisk(TAKEN), 'the winner of the race');
 
@@ -1475,10 +1434,10 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
     // Both ends of the move: the destination is the one holding the winner's
     // bytes, and the source was not written either.
     for (const p of [SOURCE, TAKEN]) {
-      expect(workflow.releaseLockUntouched, p).toHaveBeenCalledWith('ws-feat', 'feat', p, USER);
+      expect(versionControl.releaseLockUntouched, p).toHaveBeenCalledWith('ws-feat', 'feat', p, USER);
     }
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
     expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
   });
 
@@ -1489,10 +1448,10 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
    * than discarding the winner's queued file.
    */
   it('an exclusive write onto a taken name is the same refusal, and releases UNTOUCHED', async () => {
-    const workflow = makeWorkflow();
+    const versionControl = makeVersionControl();
     const layer = new LockingFilesystem(
       { basePath: root, contained: true },
-      { workflow, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
+      { versionControl, workspaceId: 'ws-feat', branch: 'feat', user: USER, kbDirName: KB },
     );
     await fs.writeFile(onDisk(TAKEN), 'the winner of the race');
 
@@ -1501,9 +1460,9 @@ describe('LockingFilesystem — a destination that is taken is refused, never re
       message: 'A file named taken.md already exists in KnowledgeBase.',
     });
 
-    expect(workflow.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', TAKEN, USER);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(versionControl.releaseLockUntouched).toHaveBeenCalledWith('ws-feat', 'feat', TAKEN, USER);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
     expect(await fs.readFile(onDisk(TAKEN), 'utf-8')).toBe('the winner of the race');
   });