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

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

@@ -1,12 +1,12 @@
 /**
- * A `LocalFilesystem` that wraps every mutating operation in a workflow
+ * A `LocalFilesystem` that wraps every mutating operation in a version-control
  * lock acquire → super-call → release-with-auto-commit-and-push cycle.
  * This is the agent's file edit surface — Mastra hands the agent the
  * workspace's filesystem tools (write_file / edit_file / etc.), and those
  * call directly into this class, so the agent's edits go through the same
  * lock + commit + push pipeline as the human editor's saves.
  *
- * Per the workflow spec (PLAN.md §2):
+ * Per the version-control spec (PLAN.md §2):
  *   - Each tool call is one acquire/release cycle. The agent never holds a
  *     lock while it's "thinking" between tool calls — a fast human editor
  *     can always grab a file the agent isn't actively writing.
@@ -14,11 +14,11 @@
  *     2-second intervals (~6s ceiling) then surface a structured error
  *     so the agent can skip the file and continue with the rest of its
  *     turn rather than aborting the whole call.
- *   - Lock-release inside `WorkflowService.releaseLock` is the thing that
+ *   - Lock-release inside `VersionControlService.releaseLock` is the thing that
  *     actually commits + pushes the file — see that method for the
  *     `commitFile → release → push` sequence. We don't repeat the commit
  *     step here; releasing IS committing.
- *   - `rmdir` is refused. The workflow invariant is "each change touches
+ *   - `rmdir` is refused. The version-control invariant is "each change touches
  *     exactly one file" and a recursive directory delete violates that.
  *     The agent must delete entries individually via `deleteFile`.
  *   - `mkdir` followed by a `.gitkeep` write is the canonical way to land
@@ -47,9 +47,8 @@ import {
   type RemoveOptions,
   type WriteOptions,
 } from '@mastra/core/workspace';
-import type { AuthUser, Change, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, Change, IVersionControlService } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
-import type { FileChangeNotifier } from './file-change-notifier.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import { DestinationTakenError, lstatOrNull, renameNoReplace, takenError } from '../../shared/rename-no-replace.js';
 import { linkedAncestor } from '../../shared/no-link-below.js';
@@ -134,13 +133,13 @@ export type WriteValidator = ((path: string, content: FileContent) => void | Pro
 };
 
 /**
- * Dependencies the wrapper needs to talk to the workflow lock service.
+ * Dependencies the wrapper needs to talk to the version-control lock service.
  * Captured at construction time so every per-method call resolves to the
  * same `(workspace, branch, user)` triple — the agent can't accidentally
  * target a different workspace through this filesystem.
  */
 export interface LockingFilesystemContext {
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   workspaceId: string;
   branch: string;
   user: AuthUser;
@@ -167,12 +166,6 @@ export interface LockingFilesystemContext {
    * when the destination is a path the validator's `appliesTo` claims.
    */
   validateWrite?: WriteValidator;
-  /**
-   * Post-commit hook for the BATCH `writeFiles` path (which commits via
-   * `commitChanges` and so skips `runPendingCommit`'s emit). Single-file ops
-   * emit through the queue instead, so they don't need this. Optional.
-   */
-  fileChanges?: FileChangeNotifier;
   /**
    * Optional creator read-grant planner (see `modules/access/creator-access`).
    * When present, a write/mkdir that starts a NEW FOLDER directly under one
@@ -475,7 +468,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     summary: string,
     check?: () => Promise<void>,
   ): Promise<Change | null> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
     await this.assertNotGitInternals(src);
     await this.assertNotGitInternals(dest);
     this.assertInsideRepo(dest);
@@ -512,10 +505,10 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const release = async (mode: 'untouched' | 'enqueue'): Promise<void> => {
       for (const p of acquired) {
         try {
-          if (mode === 'enqueue' && scope.includes(p)) await workflow.releaseLock(workspaceId, branch, p, user);
-          else if (mode === 'enqueue') await workflow.releaseLockUntouched(workspaceId, branch, p, user);
-          else if (dirtyLeft.has(p)) await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
-          else await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+          if (mode === 'enqueue' && scope.includes(p)) await versionControl.releaseLock(workspaceId, branch, p, user);
+          else if (mode === 'enqueue') await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
+          else if (dirtyLeft.has(p)) await versionControl.releaseLockNoCommit(workspaceId, branch, p, user);
+          else await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
         } catch (releaseErr) {
           log.warn(`lock release failed for "${p}" during moveWithEdits:`, { err: releaseErr });
         }
@@ -526,7 +519,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       let ok = false;
       try {
         for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-          const result = await workflow.acquireLock(workspaceId, branch, p, user);
+          const result = await versionControl.acquireLock(workspaceId, branch, p, user);
           if (result.acquired) {
             ok = true;
             break;
@@ -599,9 +592,8 @@ export class LockingFilesystem extends GitGuardedFilesystem {
           ...edits.map((e) => e.path),
         ]),
       ].sort();
-      const change = await workflow.commitChanges(workspaceId, user, summary, scope);
+      const change = await versionControl.commitChanges(workspaceId, user, summary, scope);
       await release('untouched');
-      if (change) this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: scope, byUser: user });
       return change;
     } catch (err) {
       if (err instanceof PushNeedsAgentResolutionError) {
@@ -681,7 +673,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
    * `writeFile` takes one lock cycle per file and lets the deferred queue commit
    * it, this wraps the WHOLE batch in one cycle: acquire every path's lock up
    * front, write every file to disk, then commit the whole set synchronously as
-   * one change via the workflow service's `commitChanges` (one `git add` + one
+   * one change via the version-control service's `commitChanges` (one `git add` + one
    * `git commit`, then push), and release WITHOUT a per-file commit. Fail-closed:
    * if any lock can't be acquired, or a write/commit throws, nothing is committed
    * (the failure-path `releaseLockNoCommit` discards the uncommitted bytes).
@@ -713,7 +705,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       writes: readonly { path: string; content: FileContent }[],
     ) => Promise<{ path: string; content: FileContent }[]>,
   ): Promise<Change | null> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
     // Fail the whole batch before any plan, validator or lock: one stray path
     // must not let its siblings land while it silently misses git.
     for (const w of writes) await this.assertNotGitInternals(w.path);
@@ -760,7 +752,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // with the discard so the corrupt bytes can't outlive the batch.
     const failedSeedDiscards = new Set<string>();
     // Release every acquired lock, each with the semantics its outcome
-    // earned. Three shapes (mirroring the three WorkflowService releases):
+    // earned. Three shapes (mirroring the three VersionControlService releases):
     //
     //   'discard'   → releaseLockNoCommit: resets the path's working tree to
     //     HEAD. Only for bytes this batch itself owns — its committed paths
@@ -783,11 +775,11 @@ export class LockingFilesystem extends GitGuardedFilesystem {
         try {
           const mode = modeOf(p);
           if (mode === 'discard') {
-            await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
+            await versionControl.releaseLockNoCommit(workspaceId, branch, p, user);
           } else if (mode === 'enqueue') {
-            await workflow.releaseLock(workspaceId, branch, p, user);
+            await versionControl.releaseLock(workspaceId, branch, p, user);
           } else {
-            await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+            await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
           }
         } catch (releaseErr) {
           log.warn(`lock release failed for "${p}" during writeFiles:`, { err: releaseErr });
@@ -800,7 +792,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       let holderName: string | null = null;
       let ok = false;
       for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-        const result = await workflow.acquireLock(workspaceId, branch, p, user);
+        const result = await versionControl.acquireLock(workspaceId, branch, p, user);
         if (result.acquired) {
           ok = true;
           break;
@@ -864,7 +856,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // without it would leave that folder invisible to them.
     for (const p of [...seeds.keys()].sort()) {
       if (paths.includes(p)) continue; // already locked as a caller path
-      const result = await workflow.acquireLock(workspaceId, branch, p, user);
+      const result = await versionControl.acquireLock(workspaceId, branch, p, user);
       if (result.acquired) {
         acquired.push(p);
       } else {
@@ -967,7 +959,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       // seeds): on the shared per-branch workspace another save's bytes may be
       // dirty with their commit still queued, and an unscoped commit would
       // sweep them in under this batch's author/summary.
-      change = await workflow.commitChanges(workspaceId, user, summary, touched);
+      change = await versionControl.commitChanges(workspaceId, user, summary, touched);
       if (seeds.size > 0) this.lockContext.creatorAccess?.noteAccessFileWritten(workspaceId);
     } catch (err) {
       if (err instanceof PushNeedsAgentResolutionError) {
@@ -1027,16 +1019,10 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     await releaseAll((p) =>
       committed.has(p) || failedSeedDiscards.has(p) ? 'discard' : 'untouched',
     );
-    // This batch path commits via `commitChanges`, NOT the per-file queue, so it
-    // skips `runPendingCommit`'s emit — fire the post-commit hook here with the
-    // WHOLE batch as one event, so an expensive subscriber (id-repair rebuilds the
-    // id index) reacts once per batch, not once per file. A no-op commit (clean
-    // tree) changed nothing, so it emits nothing.
-    if (change) {
-      // `touched` = caller paths + any creator-grant seeds that landed in the
-      // same commit — the exact set this batch may have touched.
-      this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: touched, byUser: user });
-    }
+    // The commit, if one landed, was reported by the git layer as it landed
+    // (`VersionControlHooks.onCommitLanded`) with the paths it committed —
+    // `touched` plus any creator-grant seed in the same commit. Nothing to
+    // announce here.
     return change;
   }
 
@@ -1052,7 +1038,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const plan = await this.planCreate(inputPath, 'dir');
     // mkdir itself is not a lockable op (it touches no file content), so we
     // do the bare super-call without acquiring. The lock + commit happens on
-    // the `.gitkeep` write below — that's the file the workflow change
+    // the `.gitkeep` write below — that's the file the version-control change
     // attaches to. If the dir already has content (rare; e.g. recursive
     // create where a sibling already exists), we skip the .gitkeep — empty-
     // folder placeholders are only useful for actually-empty folders.
@@ -1180,7 +1166,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
 
   /**
    * Acquire the lock, run `op`, release. The release does the commit +
-   * push via `WorkflowService.releaseLock`. On contention we retry a few
+   * push via `VersionControlService.releaseLock`. On contention we retry a few
    * times before surfacing a structured failure — long enough to ride
    * out a human typing a quick edit, short enough that the agent doesn't
    * stall a whole turn waiting for someone to step away from a file.
@@ -1214,12 +1200,12 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     op: () => Promise<T>,
     check?: () => Promise<void>,
   ): Promise<T> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
 
     let lastHolderName: string | null = null;
     let acquired = false;
     for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-      const result = await workflow.acquireLock(workspaceId, branch, inputPath, user);
+      const result = await versionControl.acquireLock(workspaceId, branch, inputPath, user);
       if (result.acquired) {
         acquired = true;
         break;
@@ -1263,9 +1249,9 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       // caller actually cares about.
       try {
         if (err instanceof CheckRefusal || err instanceof DestinationTakenError) {
-          await workflow.releaseLockUntouched(workspaceId, branch, inputPath, user);
+          await versionControl.releaseLockUntouched(workspaceId, branch, inputPath, user);
         } else {
-          await workflow.releaseLockNoCommit(workspaceId, branch, inputPath, user);
+          await versionControl.releaseLockNoCommit(workspaceId, branch, inputPath, user);
         }
       } catch (releaseErr) {
         log.warn(`lock release failed for "${inputPath}" after op error:`, { err: releaseErr });
@@ -1278,7 +1264,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // actual `commitFile + push` out of band. The agent's tool call
     // returns once disk + lock + enqueue are done — the commit lands
     // moments later (typically <1s) without blocking the agent's turn.
-    await workflow.releaseLock(workspaceId, branch, inputPath, user);
+    await versionControl.releaseLock(workspaceId, branch, inputPath, user);
     return result;
   }
 }

package/src/modules/kb-fs/repo-path.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 import { assertTmpRefsTaken, isTmpRef } from './tmp-ref.js';
 
@@ -112,7 +112,7 @@ export function assertInsideRepo(wsPath: string, kbDirName: string): void {
     // forge a second line of the answer, in the message and in the `path` a
     // JSON consumer reads.
     const shown = sanitizedPath(wsPath);
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `"${shown}" contains a control character: a line break, a NUL or another invisible byte is not part of any ` +
         'file name, and git reads a line break in a path as the end of one object name and the start of another. ' +
         'Remove it and send the name as it is written.',
@@ -127,7 +127,7 @@ export function assertInsideRepo(wsPath: string, kbDirName: string): void {
     .replace(/^(\.\.(\/|$))+/, '')
     .replace(/^\.$/, '');
   const corrected = isInsideRepo(normalized, kbDirName) ? normalized : `${kbDirName}/${normalized}`;
-  throw new WorkflowValidationError(
+  throw new VersionControlValidationError(
     `"${wsPath}" is outside the knowledge base repository: paths are workspace-relative, must start with "${kbDirName}/" and may not contain "." or ".." segments or backslashes. ` +
       `Use "${corrected}" instead. A file written without that prefix lands beside the repository, where it is never committed or pushed.`,
     { kind: 'path-outside-repo', path: wsPath, kbDirName, corrected },
@@ -183,7 +183,7 @@ export function normalizeWorkspacePath(wsPath: string, kbDirName: string): strin
   // `core-config` and the `kbDirName` setting validator both refuse this at
   // the point it is SET, so reaching here means the two drifted.
   if (CONTROL_CHARACTERS.test(kbDirName)) {
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `the configured checkout folder name (kbDirName / KB_DIR_NAME) contains a control character: "${sanitizedPath(kbDirName)}". ` +
         'Every workspace path is prefixed with it, so no path can be resolved until the setting is corrected.',
       { kind: 'kb-dir-name-control-character', kbDirName: sanitizedPath(kbDirName) },
@@ -237,7 +237,7 @@ export function assertRepoRootNameFree(wsPath: string, kbDirName: string): void
   const segments = String(wsPath).replace(/\/+$/, '').split('/');
   const reserved = kbDirName.toLowerCase();
   if (segments[0] !== kbDirName || segments[1]?.toLowerCase() !== reserved) return;
-  throw new WorkflowValidationError(
+  throw new VersionControlValidationError(
     `"${segments[1]}" is reserved: it is the checkout folder's name. A folder of that name at the repository root ` +
       `could never be reached — every workspace path starting with "${kbDirName}/" names the checkout itself — so it cannot be created, moved to or renamed to.` +
       // Said only when the caller spelled it differently, so the ordinary

package/src/modules/kb-fs/tmp-ref.ts

@@ -1,4 +1,4 @@
-import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 
 /**
@@ -33,9 +33,9 @@ export function isTmpRef(value: unknown): boolean {
  * copying it into the repository. A 400 with a `kind` to branch on, before
  * any gate, lock or write.
  */
-export function tmpRefReadOnlyRefusal(ref: string, tool: string): WorkflowValidationError {
+export function tmpRefReadOnlyRefusal(ref: string, tool: string): VersionControlValidationError {
   const shown = sanitizedPath(ref);
-  return new WorkflowValidationError(
+  return new VersionControlValidationError(
     `"${shown}" is a tmp ref, and ${tool} does not take one there: the workspace's tmp folder is read-only through ` +
       'the ref. read_file, file_stat and grep read the one file it names; to keep the file, copy_file it to a ' +
       'repository path (the ref as `src`, the repository path as `dest`).',

package/src/modules/kb-sync/__tests__/kb-sync.service.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
 import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { KbSyncService } from '../kb-sync.service.js';
-import type { SyncWorkflowPort, SyncWorkspacePort } from '../kb-sync.interface.js';
+import type { SyncVersionControlPort, SyncWorkspacePort } from '../kb-sync.interface.js';
 
 function deferred<T>() {
   let resolve!: (v: T) => void;
@@ -24,7 +24,7 @@ function updated(branch: string): BranchSyncOutcome {
 describe('KbSyncService', () => {
   it('answers the sync without waiting for the tidy-up after it', async () => {
     let finish = (): void => undefined;
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       // A tidy-up that never ends unless told to — and one that fails.
@@ -36,36 +36,36 @@ describe('KbSyncService', () => {
         .mockRejectedValueOnce(new Error('boom')),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const svc = new KbSyncService(versionControl, workspaces(['main']));
     await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
-    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
+    expect(versionControl.tidyAfterSweep).toHaveBeenCalledTimes(1);
     await expect(svc.sync({ branches: 'all' })).resolves.toMatchObject({ status: 'synced' });
     finish();
   });
 
   it('syncs every known clone for an "all" request and reports unknown branches as not cloned', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 1),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
 
     const all = await svc.sync({ branches: 'all' });
     expect(all.status).toBe('synced');
     expect(all.results.map((r) => r.branch)).toEqual(['main', 'ali/x']);
     expect(all.changeRequests.closedDeletedBranch).toBe(1);
     // Every sweep for deleted branches is followed by the leftover cleanup.
-    expect(workflow.tidyAfterSweep).toHaveBeenCalledTimes(1);
-    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
+    expect(versionControl.tidyAfterSweep).toHaveBeenCalledTimes(1);
+    expect(versionControl.syncWorkspaceFromRemote).toHaveBeenCalledWith('ali%2Fx');
 
     const some = await svc.sync({ branches: ['ali/x', 'juan/other'] });
     expect(some.results).toEqual([updated('ali/x'), { branch: 'juan/other', outcome: 'not-cloned' }]);
   });
 
   it('a conflict or an error makes the result partial; the other branches still sync', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
         id === 'main'
           ? { branch: 'main', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' }
@@ -75,14 +75,14 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('partial');
     expect(r.results[1]).toEqual(updated('ali/x'));
   });
 
   it('a failing sweep does not fail the sync', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async () => updated('main')),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => {
         throw new Error('origin down');
@@ -90,7 +90,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main']));
+    const svc = new KbSyncService(versionControl, workspaces(['main']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('synced');
     expect(r.changeRequests.closedDeletedBranch).toBe(0);
@@ -103,7 +103,7 @@ describe('KbSyncService', () => {
     // landing after the gate opened.
     const calls: string[][] = [['']];
     let gateOpened = false;
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         const branch = decodeURIComponent(id);
         if (!gateOpened && branch === 'main') {
@@ -120,7 +120,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
 
     const first = svc.sync({ branches: ['main'] });
     // Three requests land while the first is parked on `gate`.
@@ -137,12 +137,12 @@ describe('KbSyncService', () => {
     expect(r2.results.map((r) => r.branch)).toEqual(['ali/x']);
     expect(r3.results.map((r) => r.branch)).toEqual(['juan/y']);
     expect(r4.results.map((r) => r.branch)).toEqual(['ali/x']);
-    expect(workflow.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
+    expect(versionControl.closeChangeRequestsWithDeletedBranches).toHaveBeenCalledTimes(2);
   });
 
   it('an "all" arriving mid-run absorbs the queued branches', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -151,7 +151,7 @@ describe('KbSyncService', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const second = svc.sync({ branches: ['ali/x'] });
     const third = svc.sync({ branches: 'all' });
@@ -166,14 +166,14 @@ describe('KbSyncService', () => {
 
 describe('KbSyncService.lastSync', () => {
   it('is null before the first sync, then records when, who and what', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
     let clock = 1_000;
-    const svc = new KbSyncService(workflow, workspaces(['main']), () => clock);
+    const svc = new KbSyncService(versionControl, workspaces(['main']), () => clock);
     expect(svc.lastSync()).toBeNull();
 
     await svc.sync({ branches: 'all', by: 'bearer' });
@@ -191,7 +191,7 @@ describe('KbSyncService.lastSync', () => {
 
   it('a coalesced follow-up names everyone who asked for it', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -200,7 +200,7 @@ describe('KbSyncService.lastSync', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const first = svc.sync({ branches: ['main'], by: 'bearer' });
     const second = svc.sync({ branches: ['ali/x'], by: 'github-signature' });
     const third = svc.sync({ branches: ['ali/x'], by: 'admin@example.com' });
@@ -212,7 +212,7 @@ describe('KbSyncService.lastSync', () => {
 
 describe('KbSyncService — a throwing branch step', () => {
   it('becomes an error outcome; the other branches, the sweep and the record all still happen', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') throw new Error('fatal: unable to access https://x:ghp_secret@host/r');
         return updated(decodeURIComponent(id));
@@ -221,7 +221,7 @@ describe('KbSyncService — a throwing branch step', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x']));
     const r = await svc.sync({ branches: 'all', by: 'bearer' });
     expect(r.status).toBe('partial');
     expect(r.results[0]).toMatchObject({ branch: 'main', outcome: 'error' });
@@ -233,8 +233,8 @@ describe('KbSyncService — a throwing branch step', () => {
 });
 
 describe('KbSyncService — clones the host no longer has, and clones that cannot be read', () => {
-  it('a remote-gone branch is retired through the workflow, counts as clean, and does not stop the others', async () => {
-    const workflow: SyncWorkflowPort = {
+  it('a remote-gone branch is retired through version control, counts as clean, and does not stop the others', async () => {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> =>
         id === 'ali%2Fx' ? { branch: 'ali/x', outcome: 'remote-gone' } : updated(decodeURIComponent(id)),
       ),
@@ -242,16 +242,16 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['ali/x', 'main']));
+    const svc = new KbSyncService(versionControl, workspaces(['ali/x', 'main']));
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('synced');
     expect(r.results).toEqual([{ branch: 'ali/x', outcome: 'remote-gone' }, updated('main')]);
-    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
-    expect(workflow.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
+    expect(versionControl.retireRemoteGoneClone).toHaveBeenCalledTimes(1);
+    expect(versionControl.retireRemoteGoneClone).toHaveBeenCalledWith('ali%2Fx');
   });
 
   it('a clone that could not be read is that branch’s error, not everyone’s', async () => {
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => updated(decodeURIComponent(id))),
       closeChangeRequestsWithDeletedBranches: vi.fn(async () => 0),
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
@@ -263,21 +263,21 @@ describe('KbSyncService — clones the host no longer has, and clones that canno
         { id: 'juan%2Fy', branch: 'juan/y', unreadable: "Could not read this branch's clone: EPERM" },
       ],
     };
-    const svc = new KbSyncService(workflow, port);
+    const svc = new KbSyncService(versionControl, port);
     const r = await svc.sync({ branches: 'all' });
     expect(r.status).toBe('partial');
     expect(r.results).toEqual([
       updated('main'),
       { branch: 'juan/y', outcome: 'error', error: "Could not read this branch's clone: EPERM" },
     ]);
-    expect(workflow.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
+    expect(versionControl.syncWorkspaceFromRemote).toHaveBeenCalledTimes(1);
   });
 });
 
 describe('KbSyncService — a coalesced caller is judged by its own branches', () => {
   it("branch A's hook is not failed by branch B's conflict in the same follow-up", async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string): Promise<BranchSyncOutcome> => {
         if (id === 'main') await gate.promise;
         if (id === 'juan%2Fy') return { branch: 'juan/y', outcome: 'conflict', conflictedPaths: ['a.md'], error: 'msg' };
@@ -287,7 +287,7 @@ describe('KbSyncService — a coalesced caller is judged by its own branches', (
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const hookA = svc.sync({ branches: ['ali/x'] });
     const hookB = svc.sync({ branches: ['juan/y'] });
@@ -306,7 +306,7 @@ describe('KbSyncService — a coalesced caller is judged by its own branches', (
 describe('KbSyncService — a waiter keeps the branches it asked for', () => {
   it('a caller that edits its array after queueing changes nothing about its sync or its answer', async () => {
     const gate = deferred<void>();
-    const workflow: SyncWorkflowPort = {
+    const versionControl: SyncVersionControlPort = {
       syncWorkspaceFromRemote: vi.fn(async (id: string) => {
         if (id === 'main') await gate.promise;
         return updated(decodeURIComponent(id));
@@ -315,7 +315,7 @@ describe('KbSyncService — a waiter keeps the branches it asked for', () => {
       tidyAfterSweep: vi.fn(async () => ({ closedEmpty: 0, removedLeftovers: 0 })),
       retireRemoteGoneClone: vi.fn(async () => true),
     };
-    const svc = new KbSyncService(workflow, workspaces(['main', 'ali/x', 'juan/y']));
+    const svc = new KbSyncService(versionControl, workspaces(['main', 'ali/x', 'juan/y']));
     const first = svc.sync({ branches: ['main'] });
     const asked = ['ali/x'];
     const waiting = svc.sync({ branches: asked });
@@ -325,6 +325,6 @@ describe('KbSyncService — a waiter keeps the branches it asked for', () => {
     await first;
     const r = await waiting;
     expect(r.results.map((x) => x.branch)).toEqual(['ali/x']);
-    expect(workflow.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
+    expect(versionControl.syncWorkspaceFromRemote).not.toHaveBeenCalledWith('juan%2Fy');
   });
 });

package/src/modules/kb-sync/index.ts

@@ -3,7 +3,7 @@ export type {
   LastSync,
   SyncRequest,
   SyncResult,
-  SyncWorkflowPort,
+  SyncVersionControlPort,
   SyncWorkspacePort,
 } from './kb-sync.interface.js';
 export { KbSyncService } from './kb-sync.service.js';

package/src/modules/kb-sync/kb-sync.interface.ts

@@ -5,7 +5,7 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
  * Hexis "the repository changed" and Hexis brings the clones it holds up to
  * date. The module owns the HTTP surface, the credential check, the payload
  * parsing and the coalescing; every git operation happens behind the
- * workflow port below, never here.
+ * version-control port below, never here.
  */
 
 /** Which branches a caller asked to sync. `'all'` = every clone Hexis holds. */
@@ -51,8 +51,8 @@ export interface IKbSyncService {
   lastSync(): LastSync | null;
 }
 
-/** The slice of the workflow module a sync drives. */
-export interface SyncWorkflowPort {
+/** The slice of the version-control module a sync drives. */
+export interface SyncVersionControlPort {
   syncWorkspaceFromRemote(workspaceId: string): Promise<BranchSyncOutcome>;
   /**
    * Retire the clone of a branch the host deleted, under the branch-lifecycle