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

package/src/modules/{workflow → version-control}/git/__tests__/git.service.syncFromRemote.test.ts

@@ -5,7 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { GitService } from '../git.service.js';
 import { RemoteBranchGoneError } from '../../../../shared/domain-errors.js';
-import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+import { runGit, gitOut, stubVersionControlHooks, stubWorkspaceService } from './git-test-helpers.js';
 
 /**
  * `syncFromRemote` against real repositories: what it reports about the clone
@@ -82,7 +82,7 @@ describe('GitService.syncFromRemote', () => {
       await fs.writeFile(path.join(dir, 'b.md'), 'b\n');
       await fs.rename(path.join(dir, 'old name.md'), path.join(dir, 'new name.md'));
     });
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
 
     const r = await git.syncFromRemote('ws');
     expect(r.before).toBe(before);
@@ -106,7 +106,7 @@ describe('GitService.syncFromRemote', () => {
     await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
     await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
     await runGit(repo, ['checkout', '-b', BRANCH]).catch(() => undefined);
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
 
     // Still empty on both sides: nothing to sync, and NOT 'remote gone' — a
     // fresh deployment nobody has pushed to must never have its clone retired.
@@ -135,7 +135,7 @@ describe('GitService.syncFromRemote', () => {
     await runGit(upstream, ['branch', 'ali/x', BRANCH]);
     const { workspaceDir } = await cloneWorkspace(root, upstream, 'ali%2Fx', 'ali/x');
     await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
-    const git = new GitService(stubWorkspaceService({ 'ali%2Fx': workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ 'ali%2Fx': workspaceDir }), stubVersionControlHooks(), testKbContext());
     await expect(git.syncFromRemote('ali%2Fx')).rejects.toBeInstanceOf(RemoteBranchGoneError);
   });
 });
@@ -164,7 +164,7 @@ describe('GitService.syncFromRemote — the cases git exits 0 on but should not
     await pushFromElsewhere(root, upstream, async (dir) => {
       await fs.writeFile(path.join(dir, 'a.md'), 'edited on the host\n');
     });
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
 
     await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
       name: 'PullRebaseConflictError',
@@ -187,7 +187,7 @@ describe('GitService.syncFromRemote — the cases git exits 0 on but should not
     await runGit(repo, ['rm', '-rf', '--cached', '.']).catch(() => undefined);
     await fs.rm(path.join(repo, 'a.md'), { force: true });
     await fs.rm(path.join(repo, 'old name.md'), { force: true });
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
     await expect(git.syncFromRemote('ws')).rejects.toBeInstanceOf(RemoteBranchGoneError);
   });
 
@@ -195,7 +195,7 @@ describe('GitService.syncFromRemote — the cases git exits 0 on but should not
     const upstream = await bareUpstream(root, true);
     await runGit(upstream, ['branch', 'ali/x', BRANCH]);
     const { workspaceDir } = await cloneWorkspace(root, upstream, 'ws');
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
     expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(true);
     await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
     expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(false);
@@ -242,7 +242,7 @@ describe('GitService.syncFromRemote — an unborn clone that already holds stage
     await runGit(seed, ['add', '.']);
     await runGit(seed, ['commit', '-m', 'first']);
     await runGit(seed, ['push', upstream, BRANCH]);
-    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), testKbContext());
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubVersionControlHooks(), testKbContext());
 
     await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
       name: 'PullRebaseConflictError',

package/src/modules/{workflow → version-control}/git/__tests__/git.service.worktrees.test.ts

@@ -10,7 +10,7 @@ import { NodeFs } from '../../../kb-fs/node-fs.js';
 import { WorkspaceMutex } from '../../../kb-fs/mutex.js';
 import { WorkspaceService } from '../../../workspace/workspace.service.js';
 import { KbRepository, repositoryDirFor } from '../../../workspace/kb-repository.js';
-import { WorkflowHooks } from '../../workflow-hooks.js';
+import { VersionControlHooks } from '../../version-control-hooks.js';
 import { GitService } from '../git.service.js';
 import { NodeGitRunner } from '../node-git-runner.js';
 import { workspaceIdForBranch } from '../../../../shared/workspace-id.js';
@@ -74,7 +74,7 @@ beforeEach(async () => {
   workspaces = newWorkspaceService(
     workspacesRoot, upstream, testKbContext(), new NodeFs(), runner, undefined, undefined, repository,
   );
-  gitService = new GitService(workspaces, new WorkflowHooks(), testKbContext(), mutex, null, runner);
+  gitService = new GitService(workspaces, new VersionControlHooks(), testKbContext(), mutex, null, runner);
 });
 
 afterEach(async () => {
@@ -117,7 +117,7 @@ describe('GitService over worktrees', () => {
     await fs.mkdir(path.dirname(clone), { recursive: true });
     await git(root, ['clone', '-q', '-b', TARGET, upstream, clone]);
     const clones = newWorkspaceService(cloneRoot, upstream, testKbContext(), new NodeFs());
-    const onClones = await new GitService(clones, new WorkflowHooks(), testKbContext()).changedFilesForPr(
+    const onClones = await new GitService(clones, new VersionControlHooks(), testKbContext()).changedFilesForPr(
       id(TARGET), TARGET, 'alice/a',
     );
     expect(onWorktrees).toEqual(onClones);
@@ -227,7 +227,7 @@ describe('GitService and the repository administrator', () => {
         return runner.run(cwd, args, opts);
       }) as NodeGitRunner['run'],
     };
-    const service = new GitService(recorded, new WorkflowHooks(), testKbContext(), mutex, null, recordingRunner);
+    const service = new GitService(recorded, new VersionControlHooks(), testKbContext(), mutex, null, recordingRunner);
     await recorded.getOrCreateForBranch(TARGET);
     await recorded.getOrCreateForBranch('alice/a');
 

package/src/modules/{workflow → version-control}/git/__tests__/pull-request.service.list-fetch.test.ts

@@ -5,7 +5,7 @@ import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { GitService } from '../git.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
-import { WorkflowValidationError } from '../../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../../shared/domain-errors.js';
 
 /**
  * What a change-request LIST is allowed to cost.
@@ -178,7 +178,7 @@ describe('the list of applied requests reads each merge commit once', () => {
 
   it('asks again for a merge commit the clone did not hold the first time', async () => {
     const { svc, ofAppliedChange } = appliedHarness([applied(1)]);
-    ofAppliedChange.mockRejectedValueOnce(new WorkflowValidationError('commit is not in this clone'));
+    ofAppliedChange.mockRejectedValueOnce(new VersionControlValidationError('commit is not in this clone'));
 
     const before = await svc.listPrsByState(['merged']);
     const after = await svc.listPrsByState(['merged']);

package/src/modules/{workflow → version-control}/git/__tests__/pull-request.service.test.ts

@@ -6,7 +6,7 @@ import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
 import { hashEmail as hash } from '../../../../shared/email-identity.js';
-import { AppliedChangeMismatchError, WorkflowValidationError } from '../../../../shared/domain-errors.js';
+import { AppliedChangeMismatchError, VersionControlValidationError } from '../../../../shared/domain-errors.js';
 
 function pr(overrides: Partial<PullRequestSummary>): PullRequestSummary {
   return {
@@ -392,7 +392,7 @@ describe('PullRequestService.listPrsByState', () => {
 
     it('asks again for a commit the clone did not hold — that one the next fetch may bring', async () => {
       const { svc, atCommit } = svcOver([row({ number: 9, state: 'merged' })], ['A.md']);
-      atCommit.mockRejectedValueOnce(new WorkflowValidationError('commit is not in this clone'));
+      atCommit.mockRejectedValueOnce(new VersionControlValidationError('commit is not in this clone'));
       expect((await svc.listPrsByState(['closed', 'merged']))[0]?.touchedNodePaths).toEqual([]);
       expect((await svc.listPrsByState(['closed', 'merged']))[0]?.touchedNodePaths).toEqual(['A.md']);
       expect(atCommit).toHaveBeenCalledTimes(2);
@@ -432,7 +432,7 @@ describe('PullRequestService.listPrsByState', () => {
     } as unknown as WorkspaceService;
     const git = {
       changedPathsAndPairsOfAppliedChange: vi.fn(async () => {
-        throw new WorkflowValidationError(
+        throw new VersionControlValidationError(
           `commit ${MERGE_SHA} is not a merge commit in this clone, so it cannot be change request #1's`,
         );
       }),
@@ -487,7 +487,7 @@ describe('PullRequestService.getPrDetail with a retired branch and no merge comm
     } as unknown as WorkspaceService;
     const git = {
       resolvePrShas: async () => {
-        throw new WorkflowValidationError('unknown branch: feature/x');
+        throw new VersionControlValidationError('unknown branch: feature/x');
       },
     } as unknown as GitService;
     return new PullRequestService(db, workspace, makeAccessControl({}), git);
@@ -561,7 +561,7 @@ describe('PullRequestService.getPrDetail of an applied request', () => {
       findAnyWorkspaceId: async () => 'ws',
     } as unknown as WorkspaceService;
     const resolvePrShas = vi.fn(async () => {
-      throw new WorkflowValidationError('unknown branch: feature/x');
+      throw new VersionControlValidationError('unknown branch: feature/x');
     });
     const appliedChangeShas = vi.fn(async () => ({ baseSha: BASE_SHA, headSha: HEAD_SHA }));
     const changedFilesOfAppliedChange = vi.fn(async () => [
@@ -637,7 +637,7 @@ describe('PullRequestService.getPrDetail of an applied request', () => {
     const { svc } = svcFor();
     const git = (svc as unknown as { gitService: Record<string, unknown> }).gitService;
     git.appliedChangeShas = async () => {
-      throw new WorkflowValidationError(`no first parent for commit ${MERGE_SHA}`);
+      throw new VersionControlValidationError(`no first parent for commit ${MERGE_SHA}`);
     };
     // Fail-closed, as before the decision: no files, so author-only — never
     // somebody else's file list.

package/src/modules/{workflow → version-control}/git/git.service.ts

@@ -23,7 +23,7 @@ import type {
 import { isFolderPlaceholder } from '@bevel-software/platform-shared';
 import { mergeCommitMessageNames } from './merge-commit.js';
 import type { WorkspaceService } from '../../workspace/index.js';
-import type { WorkflowHooks, CommitValidationContext } from '../workflow-hooks.js';
+import type { VersionControlHooks, CommitValidationContext } from '../version-control-hooks.js';
 import type { IAccessControl } from '../../access/index.js';
 import { AccessDeniedError } from '../../access-model/index.js';
 import { WorkspaceIdMutex, type WorkspaceMutex, assertInsideRepo, cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS, readRefSha } from '../../kb-fs/index.js';
@@ -42,8 +42,8 @@ import {
   AppliedChangeMismatchError,
   BranchAuthorshipError,
   BranchDeleteRefusedError,
-  WorkflowDomainError,
-  WorkflowValidationError,
+  VersionControlDomainError,
+  VersionControlValidationError,
   ProtectedBranchError,
   PullRebaseConflictError,
   RemoteBranchGoneError,
@@ -69,7 +69,7 @@ const crLog = logger('cr');
 
 
 /**
- * Fallback committer identity. Every workflow commit overrides the author via
+ * Fallback committer identity. Every version-control commit overrides the author via
  * `--author=…` so the real human shows up in `git log`; this is just the
  * committer git records need. Mirrors the value `WorkspaceService` stamps on
  * each clone — set again where an operation must not depend on that ambient
@@ -149,13 +149,13 @@ function buildDefaultCommitSummary(repoRelativePath: string): string {
 
 function assertValidAuthor(user: AuthUser): void {
   if (!user.name || !user.email) {
-    throw new WorkflowValidationError('commit author name and email are required');
+    throw new VersionControlValidationError('commit author name and email are required');
   }
   if (/[\r\n<>]/.test(user.name)) {
-    throw new WorkflowValidationError('commit author name contains invalid characters');
+    throw new VersionControlValidationError('commit author name contains invalid characters');
   }
   if (/[\r\n<>\s]/.test(user.email) || !/^[^@\s]+@[^@\s]+$/.test(user.email)) {
-    throw new WorkflowValidationError('commit author email is not a valid address');
+    throw new VersionControlValidationError('commit author email is not a valid address');
   }
 }
 
@@ -317,13 +317,13 @@ export class GitService implements IGitService {
   constructor(
     private readonly workspaceService: WorkspaceService,
     /**
-     * Workflow lifecycle hooks. This service only consults the ADVISORY
+     * Version-control lifecycle hooks. This service only consults the ADVISORY
      * `commitValidation` hooks (registered by the enterprise kb module in the
      * composition root — the constructor-injected `IKbValidator` this
      * replaced). No hooks registered = no commit-time validation, which is
      * safe because validation is advisory and never blocks a commit.
      */
-    private readonly hooks: WorkflowHooks,
+    private readonly hooks: VersionControlHooks,
     private readonly kb: KbContext,
     // Keyed by the CANONICAL workspace id: a route's Express-decoded `:id`
     // (`alice/feature`) and a tool's `alice%2Ffeature` name one clone, and
@@ -808,7 +808,7 @@ export class GitService implements IGitService {
       const cwd = await this.repoDir(workspaceId);
       const current = await this.currentBranch(cwd);
       if (current === name) {
-        throw new WorkflowValidationError(
+        throw new VersionControlValidationError(
           `Cannot delete "${name}" while it's the checked-out branch.`,
         );
       }
@@ -824,7 +824,7 @@ export class GitService implements IGitService {
         // not just their own — but keep the "refuse if origin still has the
         // ref" safety: a present remote means the branch is still live.
         if (await this.refExists(cwd, `refs/remotes/origin/${name}`)) {
-          throw new WorkflowValidationError(
+          throw new VersionControlValidationError(
             `Branch "${name}" still exists on origin — refusing to auto-prune.`,
           );
         }
@@ -1008,12 +1008,12 @@ export class GitService implements IGitService {
     req: ShareChangesRequest,
   ): Promise<CommitAttribution> {
     const subject = req.summary?.trim();
-    if (!subject) throw new WorkflowValidationError('commit summary is required');
+    if (!subject) throw new VersionControlValidationError('commit summary is required');
     if (subject.length > 200) {
-      throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
+      throw new VersionControlValidationError('commit summary must be ≤ 200 characters');
     }
     if (subject.includes('\n')) {
-      throw new WorkflowValidationError('commit summary must be a single line');
+      throw new VersionControlValidationError('commit summary must be a single line');
     }
     assertValidAuthor(user);
 
@@ -1033,12 +1033,12 @@ export class GitService implements IGitService {
       ]);
       const touched = parsePorcelainZ(porcelain);
       if (touched.length === 0) {
-        throw new WorkflowValidationError('No pending changes to commit', {
+        throw new VersionControlValidationError('No pending changes to commit', {
           kind: 'no-pending-changes',
         });
       }
       if (touched.length > 1) {
-        throw new WorkflowValidationError(
+        throw new VersionControlValidationError(
           `Each change must affect exactly one file. ${touched.length} files are currently pending: ${touched.join(', ')}. Commit them one at a time.`,
           { kind: 'too-many-files-dirty', paths: touched },
         );
@@ -1206,7 +1206,7 @@ export class GitService implements IGitService {
       // **No access check at commit time.** Per the "disk is the source of
       // truth" rule, by the time content is on disk it must not be rejected.
       // The permission check that used to live here now runs at lock
-      // acquisition (see `WorkflowService.acquireLock`'s
+      // acquisition (see `VersionControlService.acquireLock`'s
       // `assertCanWriteAtPath`), so a user can't even start editing a file
       // they lack write permission on — they never reach this commit. The
       // legacy gate could destroy a user's edits when access changed
@@ -1235,10 +1235,10 @@ export class GitService implements IGitService {
 
       const subject = summary?.trim() || buildDefaultCommitSummary(repoRelativePath);
       if (subject.length > 200) {
-        throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
+        throw new VersionControlValidationError('commit summary must be ≤ 200 characters');
       }
       if (subject.includes('\n')) {
-        throw new WorkflowValidationError('commit summary must be a single line');
+        throw new VersionControlValidationError('commit summary must be a single line');
       }
 
       await this.git(cwd, [
@@ -1292,9 +1292,9 @@ export class GitService implements IGitService {
   ): Promise<CommitAttribution | null> {
     assertValidAuthor(user);
     const subject = summary?.trim();
-    if (!subject) throw new WorkflowValidationError('commit summary is required');
-    if (subject.length > 200) throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
-    if (subject.includes('\n')) throw new WorkflowValidationError('commit summary must be a single line');
+    if (!subject) throw new VersionControlValidationError('commit summary is required');
+    if (subject.length > 200) throw new VersionControlValidationError('commit summary must be ≤ 200 characters');
+    if (subject.includes('\n')) throw new VersionControlValidationError('commit summary must be a single line');
 
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
@@ -1480,7 +1480,7 @@ export class GitService implements IGitService {
     }
   }
 
-  // `forcePush` method removed. The workflow layer no longer auto-force-pushes
+  // `forcePush` method removed. The version-control layer no longer auto-force-pushes
   // as a recovery — when the cooperative `pull --rebase` + retry can't
   // reconcile, we throw `PushNeedsAgentResolutionError` and hand off to the
   // agent. The agent has git + gh CLI access and can choose to run a raw
@@ -1493,7 +1493,7 @@ export class GitService implements IGitService {
 
   /**
    * Attempt a local merge of `origin/<targetBranch>` into the currently-
-   * checked-out branch. Used by the workflow module to auto-merge target →
+   * checked-out branch. Used by the version-control module to auto-merge target →
    * source when a change request is opened or refreshed (PLAN §1).
    *
    * Two outcomes:
@@ -1564,7 +1564,7 @@ export class GitService implements IGitService {
     assertValidBranchName(fromBranch);
     assertValidAuthor(user);
     if (/\n\s*\n/.test(opts.subject)) {
-      throw new WorkflowValidationError('merge commit subject must be a single paragraph');
+      throw new VersionControlValidationError('merge commit subject must be a single paragraph');
     }
     // Every resolution names a repository path; which of them are conflicted
     // is only known inside the merge, where they are matched exactly.
@@ -1579,12 +1579,12 @@ export class GitService implements IGitService {
       const p = this.stripRepoPrefix(r.path);
       const ways = [r.content !== undefined, r.choose !== undefined].filter(Boolean).length;
       if (ways !== 1) {
-        throw new WorkflowValidationError(`resolution for "${p}": give either \`content\` or \`choose\`, not ${ways === 0 ? 'neither' : 'both'}`);
+        throw new VersionControlValidationError(`resolution for "${p}": give either \`content\` or \`choose\`, not ${ways === 0 ? 'neither' : 'both'}`);
       }
       if (r.choose !== undefined && !['ours', 'theirs', 'delete'].includes(r.choose)) {
-        throw new WorkflowValidationError(`resolution for "${p}": \`choose\` is \`ours\`, \`theirs\` or \`delete\``);
+        throw new VersionControlValidationError(`resolution for "${p}": \`choose\` is \`ours\`, \`theirs\` or \`delete\``);
       }
-      if (resolutions.has(p)) throw new WorkflowValidationError(`"${p}" is resolved twice`);
+      if (resolutions.has(p)) throw new VersionControlValidationError(`"${p}" is resolved twice`);
       resolutions.set(p, { ...r, path: p });
     }
     return this.mutex.run(workspaceId, async () =>
@@ -1616,7 +1616,7 @@ export class GitService implements IGitService {
    *
    * `publish` runs over the merge commit inside this same reservation, so no
    * save or sync can land between the commit and its push; it is the
-   * caller's push policy (the workflow's `pushWithRecovery`: one replay onto
+   * caller's push policy (the version-control service's `pushWithRecovery`: one replay onto
    * the moved branch with the merge kept, `--rebase-merges`, then the typed
    * hand-off) over this checkout's own unlocked moves.
    */
@@ -1653,14 +1653,14 @@ export class GitService implements IGitService {
     if (opts.guardCheckout) {
       const checkedOut = await this.currentBranch(cwd);
       if (checkedOut !== branch) {
-        throw new WorkflowValidationError(`the workspace is on "${checkedOut}", not on "${branch}"`);
+        throw new VersionControlValidationError(`the workspace is on "${checkedOut}", not on "${branch}"`);
       }
       // A merge rewrites tracked files. Edits still on their way to a commit
       // (a save the worker has not landed) would be swept into the merge
       // commit under this user's name, or lost under the merge's version.
       const { stdout: dirty } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
       if (parsePorcelainZ(dirty).length > 0) {
-        throw new WorkflowDomainError(
+        throw new VersionControlDomainError(
           `"${branch}" has edits that are not committed yet. Try again once they are saved.`,
           409,
           { kind: 'branch-busy', branch },
@@ -1687,8 +1687,8 @@ export class GitService implements IGitService {
     // A merge with nothing to settle leaves no resolution a place to go: one
     // supplied anyway names a path that is not conflicted, and is refused as
     // such rather than dropped on the floor behind a published merge.
-    const noConflictsFor = (): WorkflowValidationError =>
-      new WorkflowValidationError(
+    const noConflictsFor = (): VersionControlValidationError =>
+      new VersionControlValidationError(
         `nothing conflicted, so nothing is resolved here: ${[...opts.resolutions.keys()].join(', ')}.`,
         { kind: 'not-conflicted', paths: [...opts.resolutions.keys()] },
       );
@@ -1723,7 +1723,7 @@ export class GitService implements IGitService {
           // locks. Refused whole, before any resolution is applied — naming
           // the caller's own paths only, never the conflicted set (which the
           // caller is told of, cut to what they may read, by the answer).
-          throw new WorkflowValidationError(
+          throw new VersionControlValidationError(
             `not conflicted, so not resolved here: ${stray.join(', ')}.`,
             { kind: 'not-conflicted', paths: stray },
           );
@@ -1901,7 +1901,7 @@ export class GitService implements IGitService {
     // the way that is a link is refused, and a path that is itself a link is
     // replaced as a path (the link removed first), never written through.
     if ((await linkedAncestor(cwd, path.dirname(file))) !== null) {
-      throw new WorkflowValidationError(`"${r.path}" is reached through a link, so it is not resolved here`);
+      throw new VersionControlValidationError(`"${r.path}" is reached through a link, so it is not resolved here`);
     }
     if (r.content !== undefined) {
       if ((await lstatOrNull(file))?.isSymbolicLink()) await fs.unlink(file);
@@ -2029,7 +2029,7 @@ export class GitService implements IGitService {
     // `mergeCommitSubject` already flattens the title it builds from; this is the
     // guard that keeps any other caller from reintroducing the break.
     if (/\n\s*\n/.test(commit.subject)) {
-      throw new WorkflowValidationError('merge commit subject must be a single paragraph');
+      throw new VersionControlValidationError('merge commit subject must be a single paragraph');
     }
     const MAX_ATTEMPTS = 3;
     return this.mutex.run(baseWorkspaceId, async () => {
@@ -2044,7 +2044,7 @@ export class GitService implements IGitService {
         const { stdout: dirty } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
         const unpushed = await this.hasUnpushedCommitsAt(cwd);
         if (parsePorcelainZ(dirty).length > 0 || unpushed) {
-          throw new WorkflowDomainError(
+          throw new VersionControlDomainError(
             `"${targetBranch}" has edits that are not shared yet. Try the merge again once they are saved.`,
             409,
             { kind: 'merge-target-busy', targetBranch },
@@ -2453,7 +2453,7 @@ export class GitService implements IGitService {
 
   /**
    * Rebase the checked-out branch onto `remoteRef`, turning a content
-   * conflict into the typed error the workflow layer queues recovery for.
+   * conflict into the typed error the version-control layer queues recovery for.
    * Shared by `pull` and `syncFromRemote` so the two cannot drift.
    */
   private async rebaseOntoRemote(
@@ -2535,7 +2535,7 @@ export class GitService implements IGitService {
         abortSucceeded = false;
       });
       if (abortSucceeded && conflictedPaths.length > 0) {
-        // Typed so the workflow layer can queue background recovery — this
+        // Typed so the version-control layer can queue background recovery — this
         // divergence never resolves on its own (every retry pull hits the
         // same conflict) and the unpushed local commits are someone's saved
         // content stuck violating save=share.
@@ -3029,7 +3029,7 @@ export class GitService implements IGitService {
           // Only the genuinely empty separator lines are skipped.
           const touched = nameLine.endsWith('\r') ? nameLine.slice(0, -1) : nameLine;
           if (touched && touched !== repoRelativePath) {
-            throw new WorkflowValidationError(
+            throw new VersionControlValidationError(
               `"${relativePath}" is a directory at that point in history — history is served per file`,
             );
           }
@@ -3064,7 +3064,7 @@ export class GitService implements IGitService {
   ): Promise<string> {
     assertValidRelativePath(relativePath);
     if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
-      throw new WorkflowValidationError('invalid commit sha');
+      throw new VersionControlValidationError('invalid commit sha');
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
@@ -3119,7 +3119,7 @@ export class GitService implements IGitService {
   ): Promise<{ baseline: string | null; current: string | null }> {
     assertValidRelativePath(relativePath);
     if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
-      throw new WorkflowValidationError('invalid commit sha');
+      throw new VersionControlValidationError('invalid commit sha');
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
@@ -3160,7 +3160,7 @@ export class GitService implements IGitService {
     assertValidBranchName(fromBranch);
     assertValidBranchName(toBranch);
     if (fromBranch === toBranch) {
-      throw new WorkflowValidationError('from and to branches must differ');
+      throw new VersionControlValidationError('from and to branches must differ');
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
@@ -3291,7 +3291,7 @@ export class GitService implements IGitService {
     if (opts.at) {
       for (const sha of [opts.at.baseSha, opts.at.headSha]) {
         if (!/^[0-9a-f]{40,64}$/.test(sha)) {
-          throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+          throw new VersionControlValidationError(`invalid commit sha: ${sha}`);
         }
       }
     }
@@ -3411,7 +3411,7 @@ export class GitService implements IGitService {
    * side for a merge commit, and for a squashed or fast-forwarded commit it is
    * simply the commit before — the same answer either way.
    *
-   * Throws `WorkflowValidationError` whenever the recorded commit cannot be
+   * Throws `VersionControlValidationError` whenever the recorded commit cannot be
    * PROVEN to be this request's own merge commit — see
    * {@link appliedChangeShas}. Every caller reads that as "the file set could
    * not be resolved" and falls back to its own fail-closed answer, which is what
@@ -3424,7 +3424,7 @@ export class GitService implements IGitService {
   ): Promise<{ baseSha: string; headSha: string }> {
     const { mergeSha, number } = applied;
     if (!/^[0-9a-f]{40,64}$/.test(mergeSha)) {
-      throw new WorkflowValidationError(`invalid commit sha: ${mergeSha}`);
+      throw new VersionControlValidationError(`invalid commit sha: ${mergeSha}`);
     }
     const revParse = async (rev: string): Promise<string | null> => {
       try {
@@ -3447,7 +3447,7 @@ export class GitService implements IGitService {
     // or a message that does not name the request) never becomes it, and is
     // reported as a mismatch the caller may remember.
     if (!(await revParse(`${mergeSha}^{commit}`))) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `commit ${mergeSha} is not in this clone, so change request #${number} cannot be read from it yet`,
       );
     }
@@ -3612,7 +3612,7 @@ export class GitService implements IGitService {
     // concurrent `fetch --prune origin` (`ensureRemotesFetched` and
     // `fetchPrRefs` both run outside this mutex, deliberately) can drop a
     // remote-tracking ref between the two, and re-resolving inside the mutex
-    // would then throw `WorkflowValidationError` — which `touchedPathsFor`
+    // would then throw `VersionControlValidationError` — which `touchedPathsFor`
     // swallows into an empty touched-path set, i.e. exactly the change
     // request missing from its own author's tree that the skip is guarded
     // against. The commits stay readable whatever happens to the ref names.
@@ -3792,7 +3792,7 @@ export class GitService implements IGitService {
   ): Promise<{ mergeBaseSha: string | null; behind: boolean }> {
     for (const sha of [at.baseSha, at.headSha]) {
       if (!/^[0-9a-f]{40,64}$/.test(sha)) {
-        throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+        throw new VersionControlValidationError(`invalid commit sha: ${sha}`);
       }
     }
     const cwd = await this.repoDir(workspaceId);
@@ -3835,7 +3835,7 @@ export class GitService implements IGitService {
   ): Promise<string[]> {
     for (const sha of [fromSha, toSha]) {
       if (!/^[0-9a-f]{40,64}$/.test(sha)) {
-        throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+        throw new VersionControlValidationError(`invalid commit sha: ${sha}`);
       }
     }
     const cwd = await this.repoDir(workspaceId);
@@ -3866,7 +3866,7 @@ export class GitService implements IGitService {
     assertValidBranchName(baseBranch);
     assertValidRelativePath(relativePath);
     if (!/^[0-9a-f]{40,64}$/.test(sha)) {
-      throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+      throw new VersionControlValidationError(`invalid commit sha: ${sha}`);
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
@@ -3876,7 +3876,7 @@ export class GitService implements IGitService {
         await this.git(cwd, ['merge-base', '--is-ancestor', sha, baseRef]);
       } catch (err) {
         if ((err as { exitCode?: number }).exitCode === 1) {
-          throw new WorkflowDomainError(
+          throw new VersionControlDomainError(
             `That commit is not part of "${baseBranch}" — it is not this request's fork point.`,
             404,
           );
@@ -4086,7 +4086,7 @@ export class GitService implements IGitService {
     try {
       return await this.publishedPrEnds(cwd, baseBranch, headBranch);
     } catch (err) {
-      if (err instanceof WorkflowValidationError) return null;
+      if (err instanceof VersionControlValidationError) return null;
       throw err;
     }
   }
@@ -4143,7 +4143,7 @@ export class GitService implements IGitService {
         if (!(err instanceof GitRunError) || err.timedOut || err.exitCode !== 1) throw err;
       }
     }
-    throw new WorkflowValidationError(`unknown branch: ${branch}`);
+    throw new VersionControlValidationError(`unknown branch: ${branch}`);
   }
 
   /**
@@ -4182,7 +4182,7 @@ export class GitService implements IGitService {
         // Try the next candidate.
       }
     }
-    throw new WorkflowValidationError(`unknown branch: ${branch}`);
+    throw new VersionControlValidationError(`unknown branch: ${branch}`);
   }
 
   // ── internals ──────────────────────────────────────────────────────────
@@ -4341,7 +4341,7 @@ export class GitService implements IGitService {
       throw err;
     }
     if (kind === 'tree') {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `"${displayPath}" is a directory at that point in history — history is served per file`,
       );
     }
@@ -4497,7 +4497,7 @@ export class GitService implements IGitService {
   ): Promise<{ bytes: Buffer; blobId: string } | null> {
     assertValidRelativePath(relativePath);
     if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
-      throw new WorkflowValidationError('invalid commit sha');
+      throw new VersionControlValidationError('invalid commit sha');
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {

package/src/modules/{workflow → version-control}/git/node-git-runner.ts

@@ -65,7 +65,7 @@ const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
  * The environment every invocation runs under, laid OVER whatever the caller
  * supplied so that none of it can be unset per call. Only what is safe for
  * EVERY caller belongs here. `GIT_LITERAL_PATHSPECS` does not: it is the
- * workflow service's answer to raw user paths, and the startup runner spells
+ * version-control service's answer to raw user paths, and the startup runner spells
  * its literal paths with `:(literal)` magic, which that setting would disable
  * — so each of them sets its own, per call.
  *