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

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

@@ -1,20 +1,15 @@
 /**
- * Workflow facade — the only thing app callers (routes, agent tools, tests)
+ * Version-control facade — the only thing app callers (routes, agent tools, tests)
  * should reach for. Today it delegates to the existing git / PR /
- * review-workflow services; over PLAN steps 2–5 the implementations migrate
+ * change-request-review services; over PLAN steps 2–5 the implementations migrate
  * here directly and the underlying services either disappear or move
  * underneath this module.
  *
  * The facade does no caching, no validation, no policy of its own — it
  * exists to:
- *   1. Lock in the workflow vocabulary on the consumer side.
- *   2. Concentrate every call into git/PR/review-workflow into one place
+ *   1. Lock in the version-control vocabulary on the consumer side.
+ *   2. Concentrate every call into git/PR/change-request-review into one place
  *      so the agent prompt can stop knowing about `git` / `gh`.
- *
- * Methods backed by services that don't exist yet (locks, openChangeRequest,
- * updateFromTarget) throw `NotImplementedWorkflowError`. The interface
- * defines them so frontend / agent code can wire to the final surface while
- * those backings land.
  */
 
 import path from 'node:path';
@@ -55,7 +50,7 @@ import type {
   FileLock,
   FolderChangeRequest,
   FolderChangeRequestRemoval,
-  IWorkflowService,
+  IVersionControlService,
   MergeBranchOutcome,
   MergeChangeRequestOutcome,
   MergeResolution,
@@ -79,17 +74,16 @@ import { changeRequests, pgErrorCode } from '../database/index.js';
 import type { GitService } from './git/git.service.js';
 import { redactSecret } from '../../shared/redact-secret.js';
 import type { PullRequestService } from './git/pull-request.service.js';
-import type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
+import type { IChangeRequestReviewService } from './change-request-review/change-request-review.interface.js';
 import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { IAccessControl } from '../access/index.js';
 import type { FileLockService } from './file-lock.service.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import type { PendingCommitsService } from './pending-commits.service.js';
-import type { WorkflowEventBus } from './event-bus.js';
+import type { VersionControlEventBus } from './event-bus.js';
 import { describeSyncFailure, sanitizeError } from './sanitize-error.js';
-import type { FileChangeNotifier } from '../kb-fs/index.js';
-import { WorkflowHooks } from './workflow-hooks.js';
+import { VersionControlHooks } from './version-control-hooks.js';
 import {
   ChangeRequestHooks,
   type ChangeRequestPerson,
@@ -109,8 +103,8 @@ import {
   PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   RemoteBranchGoneError,
-  WorkflowDomainError,
-  WorkflowValidationError,
+  VersionControlDomainError,
+  VersionControlValidationError,
 } from '../../shared/domain-errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError, EVERYONE_CANONICAL, type IChangeReadGate } from '../access-model/index.js';
@@ -196,7 +190,7 @@ function redactTokens(msg: string, token: string | null | undefined): string {
  */
 function assertDescriptionFits(description: string | undefined): void {
   if (description !== undefined && description.length > CHANGE_REQUEST_DESCRIPTION_MAX) {
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `A change request's description is at most ${CHANGE_REQUEST_DESCRIPTION_MAX} characters; this one would have ${description.length}.`,
     );
   }
@@ -204,13 +198,13 @@ function assertDescriptionFits(description: string | undefined): void {
 
 function assertEditable(state: string): void {
   if (state === 'merged') {
-    throw new WorkflowDomainError(
+    throw new VersionControlDomainError(
       'This change request has already been applied; its title and description can no longer be changed.',
       409,
     );
   }
   if (state !== 'open') {
-    throw new WorkflowDomainError(
+    throw new VersionControlDomainError(
       'This change request is closed; its title and description can no longer be changed.',
       409,
     );
@@ -223,7 +217,7 @@ type EligibleWritersAtRef = Awaited<ReturnType<IAccessControl['eligibleWritersFo
 /**
  * The one question the open asks of accounts: which of these addresses have
  * a live account. `AuthService.findActiveAccountsByEmail` answers it in a
- * single indexed read; the shape is spelled here so the workflow module
+ * single indexed read; the shape is spelled here so the version-control module
  * imports nothing of auth's. Keyed by the canonical address asked for.
  */
 export interface ApproverAccounts {
@@ -254,13 +248,13 @@ function folderPrefix(folder: string): string {
   return `${folder.replace(/\/+$/, '')}/`;
 }
 
-export class WorkflowService implements IWorkflowService {
+export class VersionControlService implements IVersionControlService {
   /**
    * Concrete `PullRequestService` (not the interface) so the facade can call
    * `invalidateDetailCache` after a mutation lands — the legacy routes do
-   * this inline, and the workflow facade absorbs that responsibility so its
+   * this inline, and the version-control facade absorbs that responsibility so its
    * own routes stay free of cache plumbing. Replaceable later when the PR
-   * detail cache moves into the workflow module proper (PLAN step 5).
+   * detail cache moves into the version-control module proper (PLAN step 5).
    *
    * `db` + `workspaceService` + `kbDirName` back `openChangeRequest`, which
    * inserts a change_requests row and runs the local auto-merge — no provider
@@ -268,10 +262,10 @@ export class WorkflowService implements IWorkflowService {
    */
   /**
    * Concrete `GitService` (not the interface) so the facade can reach
-   * `mergeFromOrigin` — the local auto-merge primitive the workflow needs
+   * `mergeFromOrigin` — the local auto-merge primitive the version-control service needs
    * for `openChangeRequest` + `updateFromTarget` (PLAN §1). The interface
    * intentionally doesn't surface that method because it's an internal
-   * implementation detail of the workflow auto-merge story; nothing outside
+   * implementation detail of the version-control auto-merge story; nothing outside
    * the facade should call it directly.
    */
   private get kbDirName(): string {
@@ -282,7 +276,7 @@ export class WorkflowService implements IWorkflowService {
     private readonly db: Database,
     private readonly git: GitService,
     private readonly prs: PullRequestService,
-    private readonly reviewWorkflow: IReviewWorkflowService,
+    private readonly changeRequestReview: IChangeRequestReviewService,
     private readonly workspaceService: WorkspaceService,
     private readonly accessControl: IAccessControl,
     private readonly fileLocks: FileLockService,
@@ -308,24 +302,17 @@ export class WorkflowService implements IWorkflowService {
      * become no-ops in that case (we null-guard each call). In a real
      * boot the composition root always wires one.
      */
-    private readonly events?: WorkflowEventBus,
-    /**
-     * In-process post-commit hook (distinct from the SSE `events` bus): fires
-     * after a file's change is committed + pushed so backend services (catalog
-     * invalidation, id-repair) react without the per-file TTL wait. Optional,
-     * like `events`.
-     */
-    private readonly fileChanges?: FileChangeNotifier,
+    private readonly events?: VersionControlEventBus,
     /**
-     * Workflow lifecycle-hook registry (see `workflow-hooks.ts`). PUBLIC so
+     * Version-control lifecycle-hook registry (see `version-control-hooks.ts`). PUBLIC so
      * the composition root registers module-owned behavior against it
-     * (`core.workflowService.hooks.onCommitValidation(…)` /
+     * (`core.versionControlService.hooks.onCommitValidation(…)` /
      * `.onPreWrite(…)`) after `createCoreServices` returns. The composition
      * root passes the SAME instance `GitService` and the agent-access gate
      * consult; the default keeps test constructions (which don't exercise
      * hooks) unchanged.
      */
-    public readonly hooks: WorkflowHooks = new WorkflowHooks(),
+    public readonly hooks: VersionControlHooks = new VersionControlHooks(),
     /**
      * The seam a deployment's notification extends when a request is opened
      * (see `change-request-hooks.ts`). The composition root passes the SAME
@@ -343,7 +330,7 @@ export class WorkflowService implements IWorkflowService {
     // The type already requires it; this holds for a caller the compiler did
     // not see (plain JavaScript, a positional slip in a harness).
     if (!changeGate || typeof changeGate.assertMayChange !== 'function') {
-      throw new Error('WorkflowService requires a read-before-write gate (IChangeReadGate)');
+      throw new Error('VersionControlService requires a read-before-write gate (IChangeReadGate)');
     }
   }
 
@@ -518,7 +505,7 @@ export class WorkflowService implements IWorkflowService {
           // this branch is the deleter's own to withdraw; a request INTO it
           // belongs to someone else, and telling the branch owner to
           // "withdraw" it points them at a verb they cannot use.
-          throw new WorkflowValidationError(
+          throw new VersionControlValidationError(
             open.end === 'source'
               ? `Branch "${name}" has an open change request (#${open.number}). ` +
                 `Withdraw or decline it before deleting the branch.`
@@ -926,7 +913,7 @@ export class WorkflowService implements IWorkflowService {
   // operation, which was the only place the legacy DirtyWorkingTreeError
   // could surface as a user-facing 409.
 
-  // `forkCurrentToDraft` removed (see IWorkflowService): per-branch workspaces
+  // `forkCurrentToDraft` removed (see IVersionControlService): per-branch workspaces
   // make the dirty-tree-carry-along escape hatch impossible by construction.
 
   branchStatus(workspaceId: string): Promise<BranchWorkspaceStatus> {
@@ -1140,7 +1127,7 @@ export class WorkflowService implements IWorkflowService {
       // this sync's — never a save that landed alongside. Capped: a bulk
       // import would otherwise fan hundreds of events out to say what one
       // refresh says.
-      if (announce.changedPaths.length <= WorkflowService.SYNC_FILE_EVENT_CAP) {
+      if (announce.changedPaths.length <= VersionControlService.SYNC_FILE_EVENT_CAP) {
         for (const p of announce.changedPaths) {
           this.events?.emit({
             kind: 'file-changed',
@@ -1549,7 +1536,7 @@ export class WorkflowService implements IWorkflowService {
     const targetPath = canonicalFileIdentity(rawPath);
     const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
     if (!lock || lock.holderUserId !== user.id) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Cannot commit "${targetPath}": you don't hold the lock.`,
         { kind: 'lock-not-held', branch, path: targetPath },
       );
@@ -1560,7 +1547,7 @@ export class WorkflowService implements IWorkflowService {
     // holder checkpoint bytes onto a path — machine-owned files included —
     // whose write rule they never passed.
     if (lock.mode === 'coordination') {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Cannot commit "${targetPath}": the lock is a coordination hold, which grants no write authority.`,
         { kind: 'coordination-hold', branch, path: targetPath },
       );
@@ -1683,7 +1670,7 @@ export class WorkflowService implements IWorkflowService {
       lockLog.warn(
         `RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${lock ? `held by ${lock.holderUserId}` : 'no lock row'}`,
       );
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Cannot release lock on "${targetPath}": not held by you (or no longer exists).`,
         { kind: 'lock-not-held', branch, path: targetPath },
       );
@@ -1701,7 +1688,7 @@ export class WorkflowService implements IWorkflowService {
       lockLog.warn(
         `RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → coordination hold (no commit may be enqueued)`,
       );
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Cannot release lock on "${targetPath}" with a commit: it is a coordination hold. Use releaseLockNoCommit.`,
         { kind: 'coordination-hold', branch, path: targetPath },
       );
@@ -1782,11 +1769,14 @@ export class WorkflowService implements IWorkflowService {
       // which is exactly how a diverged workspace ends up stuck forever.
       // So: if the branch is ahead of its remote-tracking ref, push (with
       // the same cooperative recovery, so a conflicting divergence throws
-      // and the worker's ladder takes over). Nothing to emit either way —
+      // and the worker's ladder takes over). No `file-changed` either way —
       // there's no new sha.
       if (await this.git.hasUnpushedCommits(workspaceId)) {
         await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
       }
+      // Nothing landed here, so nothing is announced: the git layer reports
+      // each commit as it lands (an autosave checkpoint, a batch whose push
+      // retry this row is), and this row made none.
       return;
     }
     await this.pushWithRecovery(workspaceId, branch, targetPath, user, opts);
@@ -1799,9 +1789,6 @@ export class WorkflowService implements IWorkflowService {
       byUserId: user.id,
       byUserName: user.name,
     });
-    // Post-commit, post-lock-release: the one chokepoint every single-file write
-    // converges on. Backend reactors (catalog invalidation, id-repair) hook here.
-    this.fileChanges?.emit({ workspaceId, branch, paths: [targetPath], byUser: user });
   }
 
   /**
@@ -1896,7 +1883,7 @@ export class WorkflowService implements IWorkflowService {
    * still fails." The full rationale lives at the call site in
    * `releaseLock`; this method is the de-duplicated body.
    *
-   * EVERY workflow push goes through here — saves, sharing a branch, opening
+   * EVERY version-control push goes through here — saves, sharing a branch, opening
    * a request, update-from-target, the decline revert, the roles.yaml
    * restore — so a push the host refuses answers one way everywhere: the
    * commit stays local, the sync banner goes up, and the caller gets the
@@ -2061,7 +2048,7 @@ export class WorkflowService implements IWorkflowService {
     //
     // One refinement for COORDINATION holds: the holder never legitimately
     // wrote the path (the write paths refuse coordination possession), so
-    // anything dirty there is either bytes smuggled in around the workflow —
+    // anything dirty there is either bytes smuggled in around version control —
     // which the discard rightly wipes — or a PRIOR save's work whose commit
     // is still queued. Only the queue can tell those apart: when a live
     // pending-commit row exists for the path, the dirty bytes are that
@@ -2279,15 +2266,15 @@ export class WorkflowService implements IWorkflowService {
     user: AuthUser,
     input: OpenChangeRequestInput,
   ): Promise<ChangeRequestDetail & { notified: string[] }> {
-    if (!input.sourceBranch) throw new WorkflowValidationError('sourceBranch is required');
-    if (!input.targetBranch) throw new WorkflowValidationError('targetBranch is required');
+    if (!input.sourceBranch) throw new VersionControlValidationError('sourceBranch is required');
+    if (!input.targetBranch) throw new VersionControlValidationError('targetBranch is required');
     if (input.sourceBranch === input.targetBranch) {
-      throw new WorkflowValidationError('source and target branches must differ');
+      throw new VersionControlValidationError('source and target branches must differ');
     }
-    if (!input.title?.trim()) throw new WorkflowValidationError('title is required');
+    if (!input.title?.trim()) throw new VersionControlValidationError('title is required');
     assertDescriptionFits(input.description?.trim());
     if (this.kb.isProtectedBranch(input.sourceBranch)) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`,
         { kind: 'source-is-protected', sourceBranch: input.sourceBranch },
       );
@@ -2334,7 +2321,7 @@ export class WorkflowService implements IWorkflowService {
 
     // Auto-merge target → source. `mergeFromOrigin` enforces "current
     // branch == source" and "clean working tree" before attempting; both
-    // failures surface as structured workflow errors that pass straight
+    // failures surface as structured version-control errors that pass straight
     // through to the caller.
     const mergeOutcome = await this.git.mergeFromOrigin(
       workspaceId,
@@ -2428,7 +2415,7 @@ export class WorkflowService implements IWorkflowService {
         // rival was merged/closed in the microsecond between the conflict and
         // this re-query), don't fabricate a #0 — report it as a transient race.
         if (!existing) {
-          throw new WorkflowValidationError(
+          throw new VersionControlValidationError(
             `Change request for "${input.sourceBranch}" → "${input.targetBranch}" ` +
               'raced with a concurrent open/close; retry.',
             { kind: 'open-change-request-failed' },
@@ -2446,7 +2433,7 @@ export class WorkflowService implements IWorkflowService {
       // openChangeRequest finds no duplicate, re-runs the (idempotent, already
       // up-to-date) auto-merge, and inserts the row.
       const rawMsg = err instanceof Error ? err.message : String(err);
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Failed to open change request: ${redactTokens(rawMsg, this.git.credentials?.token())}`,
         { kind: 'open-change-request-failed' },
       );
@@ -2492,7 +2479,7 @@ export class WorkflowService implements IWorkflowService {
       detail: null,
       pushRefused: null,
       detailError:
-        detailError ?? new WorkflowValidationError(`Created change request #${prNumber} but could not fetch its detail`),
+        detailError ?? new VersionControlValidationError(`Created change request #${prNumber} but could not fetch its detail`),
     };
     });
 
@@ -2622,19 +2609,19 @@ export class WorkflowService implements IWorkflowService {
       patches: false,
     });
     if (!detail) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Change request #${number} not found.`,
         { kind: 'change-request-not-found', number },
       );
     }
     if (detail.state !== 'open') {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Change request #${number} is ${detail.state} — only open requests can refresh from target.`,
         { kind: 'change-request-not-open', state: detail.state },
       );
     }
     if (!detail.viewerCanUpdate) {
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         'Only the author of this change request, or someone who may apply it, can update it.',
         403,
       );
@@ -2780,7 +2767,7 @@ export class WorkflowService implements IWorkflowService {
           headBeforeMerge,
           headAfterMerge,
         );
-        await this.reviewWorkflow.carryApprovalsForward(
+        await this.changeRequestReview.carryApprovalsForward(
           number,
           headBeforeMerge,
           headAfterMerge,
@@ -2806,7 +2793,7 @@ export class WorkflowService implements IWorkflowService {
       viewerEmail: user.email,
     });
     if (!refreshed) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `Refreshed change request #${number} but could not re-fetch its detail.`,
       );
     }
@@ -2825,7 +2812,7 @@ export class WorkflowService implements IWorkflowService {
   ): Promise<FileApproval[]> {
     // Taken BEFORE the approval lands (see `clearApplyFailure`).
     const approvedAfter = new Date();
-    const approvals = await this.reviewWorkflow.approveFile(
+    const approvals = await this.changeRequestReview.approveFile(
       number,
       path,
       user,
@@ -2865,7 +2852,7 @@ export class WorkflowService implements IWorkflowService {
     authorIdHash: string | null,
     workspaceId: string,
   ): Promise<FileApproval[]> {
-    const approvals = await this.reviewWorkflow.unapproveFile(
+    const approvals = await this.changeRequestReview.unapproveFile(
       number,
       path,
       user,
@@ -2933,9 +2920,9 @@ export class WorkflowService implements IWorkflowService {
     repoRelPath: string,
   ): Promise<{ closed: boolean; remainingPaths: string[] }> {
     const summary = await this.prs.getPr(number);
-    if (!summary) throw new WorkflowDomainError('change request not found', 404);
+    if (!summary) throw new VersionControlDomainError('change request not found', 404);
     if (summary.state !== 'open') {
-      throw new WorkflowDomainError('This change request is no longer open.', 422);
+      throw new VersionControlDomainError('This change request is no longer open.', 422);
     }
     const baseBranch = summary.base;
     const headBranch = summary.branch;
@@ -2954,7 +2941,7 @@ export class WorkflowService implements IWorkflowService {
     // The verb acts on the request as it is NOW — never a cached file list.
     const paths = await this.git.changedPathsForPr(ws.id, baseBranch, headBranch);
     if (!paths.includes(repoRelPath)) {
-      throw new WorkflowDomainError('That file is not part of this change request.', 422);
+      throw new VersionControlDomainError('That file is not part of this change request.', 422);
     }
 
     const canApprove = await this.accessControl.canWriteAtRef(
@@ -2964,7 +2951,7 @@ export class WorkflowService implements IWorkflowService {
       repoRelPath,
     );
     if (canApprove !== true) {
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         'Only an eligible approver of this file can revert it — declining takes the same permission as accepting.',
         403,
       );
@@ -2972,7 +2959,7 @@ export class WorkflowService implements IWorkflowService {
 
     const mergeBase = await this.git.mergeBaseForPr(ws.id, baseBranch, headBranch);
     if (!mergeBase) {
-      throw new WorkflowDomainError('These branches share no history to revert to.', 422);
+      throw new VersionControlDomainError('These branches share no history to revert to.', 422);
     }
 
     const placeholder = await this.placeholderRevertedWith(ws.id, mergeBase, repoRelPath, paths);
@@ -2991,7 +2978,7 @@ export class WorkflowService implements IWorkflowService {
         const lockPath = `${this.kbDirName}/${p}`;
         const lock = await this.fileLocks.acquire(ws.id, headBranch, lockPath, user);
         if (!lock.acquired) {
-          throw new WorkflowDomainError(
+          throw new VersionControlDomainError(
             p === repoRelPath
               ? `${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`
               : `The folder of ${repoRelPath} is being changed by ${lock.lock.holderName} — try again once the edit settles.`,
@@ -3079,7 +3066,7 @@ export class WorkflowService implements IWorkflowService {
           log.warn(
             `changedPathsForPr failed for #${cr.number} under folder ${printable(folder)}: ${printable(sanitizeError(err))}`,
           );
-          throw new WorkflowDomainError(
+          throw new VersionControlDomainError(
             `Couldn't read what change request #${cr.number} proposes — try again in a moment.`,
             500,
           );
@@ -3159,7 +3146,7 @@ export class WorkflowService implements IWorkflowService {
     const requests = await this.changeRequestsUnderFolder(folder, user);
     const refused = requests.filter((r) => !r.mayRemove);
     if (refused.length > 0) {
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `You can't remove proposed changes from ${refused.map((r) => `#${r.number}`).join(', ')} — only the author, an admin or someone who can write every file it proposes here can.`,
         403,
       );
@@ -3185,7 +3172,7 @@ export class WorkflowService implements IWorkflowService {
         log.warn(
           `pull failed for #${summary.number} before removing folder ${printable(folder)}: ${printable(sanitizeError(err))}`,
         );
-        throw new WorkflowDomainError(
+        throw new VersionControlDomainError(
           `#${summary.number} could not be brought up to date, so nothing was removed — try again in a moment.`,
           409,
         );
@@ -3198,7 +3185,7 @@ export class WorkflowService implements IWorkflowService {
       // file need not be one of it — so the request has to be asked about again.
       const unjudged = paths.filter((p) => !request.paths.includes(p));
       if (unjudged.length > 0) {
-        throw new WorkflowDomainError(
+        throw new VersionControlDomainError(
           `#${summary.number} changed while the folder was being deleted (${unjudged.length === 1 ? unjudged[0] :`${unjudged.length} new files`}), so no proposed changes were removed — try again.`,
           409,
         );
@@ -3207,7 +3194,7 @@ export class WorkflowService implements IWorkflowService {
       if (paths.length > 0) {
         mergeBase = await this.git.mergeBaseForPr(ws.id, summary.base, summary.branch);
         if (!mergeBase) {
-          throw new WorkflowDomainError(`#${summary.number} shares no history with its target to revert to.`, 422);
+          throw new VersionControlDomainError(`#${summary.number} shares no history with its target to revert to.`, 422);
         }
       }
       plans.push({ number: summary.number, branch: summary.branch, wsId: ws.id, paths, mergeBase });
@@ -3237,7 +3224,7 @@ export class WorkflowService implements IWorkflowService {
           group.paths.push({ path: repoRelPath, mergeBase: plan.mergeBase! });
         } else if (seen.mergeBase !== plan.mergeBase) {
           const sharing = group.plans.map((other) => `#${other.number}`).join(', ');
-          throw new WorkflowDomainError(
+          throw new VersionControlDomainError(
             `${sharing} propose ${repoRelPath} from the same branch against different targets, so it can't be taken out of both at once. Decline it in each request instead.`,
             422,
           );
@@ -3267,7 +3254,7 @@ export class WorkflowService implements IWorkflowService {
           const lockPath = `${this.kbDirName}/${repoRelPath}`;
           const lock = await this.fileLocks.acquire(group.wsId, group.branch, lockPath, user);
           if (!lock.acquired) {
-            throw new WorkflowDomainError(
+            throw new VersionControlDomainError(
               `${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`,
               409,
             );
@@ -3350,7 +3337,7 @@ export class WorkflowService implements IWorkflowService {
       log.warn(
         `push failed for ${failed} removing folder ${printable(folder)}: ${printable(sanitizeError(pushFailure.err))}`,
       );
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `The folder's files were removed from ${finished.map((plan) => `#${plan.number}`).join(', ')}, but ${failed} could not be updated and it and any later requests were left as they were. Run the delete again to finish.`,
         500,
       );
@@ -3374,9 +3361,9 @@ export class WorkflowService implements IWorkflowService {
    */
   async deleteChangeRequest(number: number, user: AuthUser): Promise<void> {
     const summary = await this.prs.getPr(number);
-    if (!summary) throw new WorkflowDomainError('change request not found', 404);
+    if (!summary) throw new VersionControlDomainError('change request not found', 404);
     if (summary.state === 'merged') {
-      throw new WorkflowDomainError('This change request has already been applied.', 422);
+      throw new VersionControlDomainError('This change request has already been applied.', 422);
     }
 
     // Which `roles.yaml` authorizes this? The base branch's, exactly as every
@@ -3401,7 +3388,7 @@ export class WorkflowService implements IWorkflowService {
       try {
         await this.workspaceService.ensureRemotesFetched(ws.id, { strict: true });
       } catch {
-        throw new WorkflowDomainError(
+        throw new VersionControlDomainError(
           `Could not verify the base branch "${summary.base}" — origin was unreachable. Retry in a moment.`,
           409,
         );
@@ -3424,7 +3411,7 @@ export class WorkflowService implements IWorkflowService {
     // attempt the sweep has either closed the row or shown the base alive.
     if (isAdmin === null) {
       this.kickDeletedBranchSweep();
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `The base branch "${summary.base}" could not be resolved — it may have been deleted, or origin was unreachable. A background check is running; retry in a moment.`,
         409,
       );
@@ -3439,7 +3426,7 @@ export class WorkflowService implements IWorkflowService {
     // stay honest.
     const callerIsAuthor = !!(summary.authorId && summary.authorId === hashEmail(user.email));
     if (!callerIsAuthor && isAdmin !== true) {
-      throw new WorkflowDomainError("Only the request's author or an admin can delete it.", 403);
+      throw new VersionControlDomainError("Only the request's author or an admin can delete it.", 403);
     }
 
     // Close first (idempotent: an already-closed request just skips to the
@@ -3456,7 +3443,7 @@ export class WorkflowService implements IWorkflowService {
     } else {
       const fresh = await this.prs.getPr(number);
       if (fresh?.state === 'merged') {
-        throw new WorkflowDomainError('This change request has already been applied.', 422);
+        throw new VersionControlDomainError('This change request has already been applied.', 422);
       }
     }
     await this.retireMergedSourceBranch(number, summary.base, user);
@@ -3495,7 +3482,7 @@ export class WorkflowService implements IWorkflowService {
       await this.workspaceService.ensureRemotesFetched(workspaceId, { strict: true, force: true });
     } catch {
       this.kickDeletedBranchSweep();
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `Could not verify the base branch "${baseBranch}" — origin was unreachable. Retry in a moment.`,
         409,
       );
@@ -3512,7 +3499,7 @@ export class WorkflowService implements IWorkflowService {
     // read and a batch lookup done for nothing.
     if (isAdmin === null) {
       this.kickDeletedBranchSweep();
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `The base branch "${baseBranch}" could not be resolved — it may have been deleted, or origin was unreachable. A background check is running; retry in a moment.`,
         409,
       );
@@ -3561,16 +3548,16 @@ export class WorkflowService implements IWorkflowService {
     const description = input.description === undefined ? undefined : input.description.trim();
     const appended = input.appendDescription === undefined ? undefined : input.appendDescription.trim();
     if (title === undefined && description === undefined && appended === undefined) {
-      throw new WorkflowValidationError('Give a new title, a new description, or both.');
+      throw new VersionControlValidationError('Give a new title, a new description, or both.');
     }
     if (description !== undefined && appended !== undefined) {
-      throw new WorkflowValidationError('Give either a new description or text to append to it, not both.');
+      throw new VersionControlValidationError('Give either a new description or text to append to it, not both.');
     }
     if (title !== undefined && title.length === 0) {
-      throw new WorkflowValidationError('A change request needs a title; it cannot be empty.');
+      throw new VersionControlValidationError('A change request needs a title; it cannot be empty.');
     }
     if (title !== undefined && title.length > CHANGE_REQUEST_TITLE_MAX) {
-      throw new WorkflowValidationError(
+      throw new VersionControlValidationError(
         `A change request's title is at most ${CHANGE_REQUEST_TITLE_MAX} characters; this one has ${title.length}.`,
       );
     }
@@ -3579,7 +3566,7 @@ export class WorkflowService implements IWorkflowService {
     // stored.
     assertDescriptionFits(description);
     const summary = await this.prs.getPr(number);
-    if (!summary) throw new WorkflowDomainError('change request not found', 404);
+    if (!summary) throw new VersionControlDomainError('change request not found', 404);
     assertEditable(summary.state);
 
     // The grants beyond authorship are read in the base branch's own workspace,
@@ -3601,7 +3588,7 @@ export class WorkflowService implements IWorkflowService {
       },
     );
     if (grant === null) {
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         "Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.",
         403,
       );
@@ -3649,14 +3636,14 @@ export class WorkflowService implements IWorkflowService {
     this.prs.invalidateDetailCache(number);
     if (!updated) {
       const fresh = await this.prs.getPr(number);
-      if (!fresh) throw new WorkflowDomainError('change request not found', 404);
+      if (!fresh) throw new VersionControlDomainError('change request not found', 404);
       assertEditable(fresh.state);
-      throw new WorkflowDomainError('This change request changed while it was being edited. Retry in a moment.', 409);
+      throw new VersionControlDomainError('This change request changed while it was being edited. Retry in a moment.', 409);
     }
     crLog.info(`#${number} title/description edited`);
     this.events?.emit({ kind: 'change-request-edited', number });
     const fresh = await this.prs.getPr(number);
-    if (!fresh) throw new WorkflowDomainError('change request not found', 404);
+    if (!fresh) throw new VersionControlDomainError('change request not found', 404);
     return fresh;
   }
 
@@ -3734,7 +3721,7 @@ export class WorkflowService implements IWorkflowService {
    * branch is gone. Closing takes it out of every open list (which is the
    * whole visible problem) while a `state = 'closed'` row can still be read,
    * counted, and reopened by hand. Deleting would make this sweep the one
-   * operation in the workflow that destroys history without a human asking.
+   * operation in version control that destroys history without a human asking.
    *
    * ONE fetch, then a set lookup. The freshness matters more than the cost:
    * `changedPathsForPr` fails when a branch is missing from THAT
@@ -4202,7 +4189,7 @@ export class WorkflowService implements IWorkflowService {
       }
     }
 
-    const result = await this.reviewWorkflow.cancelPr(
+    const result = await this.changeRequestReview.cancelPr(
       number,
       user,
       state,
@@ -4280,7 +4267,7 @@ export class WorkflowService implements IWorkflowService {
 
     let result;
     try {
-      result = await this.reviewWorkflow.mergePr(
+      result = await this.changeRequestReview.mergePr(
         number,
         user,
         mergeHeadSha,
@@ -4430,7 +4417,7 @@ export class WorkflowService implements IWorkflowService {
 
   async mergeBranch(user: AuthUser, sourceBranch: string, targetBranch: string): Promise<MergeBranchOutcome> {
     if (sourceBranch === targetBranch) {
-      throw new WorkflowValidationError(`\`source\` and \`target\` are both "${sourceBranch}" — name two different branches.`);
+      throw new VersionControlValidationError(`\`source\` and \`target\` are both "${sourceBranch}" — name two different branches.`);
     }
 
     // Asked once BEFORE waiting, so a merge the open request forbids is refused
@@ -4481,7 +4468,7 @@ export class WorkflowService implements IWorkflowService {
       // The merge runs in the target's own workspace, like a change request's.
       const targetWorkspaceId = (await this.workspaceService.getOrCreateForBranch(targetBranch)).id;
       if (!(await this.git.remoteBranchExists(targetWorkspaceId, sourceBranch))) {
-        throw new WorkflowValidationError(`No branch named "${sourceBranch}" on the shared remote.`);
+        throw new VersionControlValidationError(`No branch named "${sourceBranch}" on the shared remote.`);
       }
 
       const result = await this.git.mergeChangeRequest(
@@ -4525,7 +4512,7 @@ export class WorkflowService implements IWorkflowService {
                 // roles.yaml would bypass both, on the one file the access
                 // model cannot survive being wrong.
                 if (changedPaths.includes('roles.yaml')) {
-                  throw new WorkflowDomainError(
+                  throw new VersionControlDomainError(
                     `"${targetBranch}" is protected and this merge would change its roles.yaml. ` +
                       `Roles never change through a merge: restore roles.yaml on "${sourceBranch}" to the version on ` +
                       `"${targetBranch}" and merge again, and ask the user to change roles in the app.`,
@@ -4541,7 +4528,7 @@ export class WorkflowService implements IWorkflowService {
                 );
                 const denied = allowed ? changedPaths.filter((p) => !allowed.get(p)) : [];
                 if (denied.length === 0) return;
-                throw new WorkflowDomainError(
+                throw new VersionControlDomainError(
                   `"${targetBranch}" is protected and you cannot commit directly to it: ` +
                     `${denied.length} changed file(s) are outside your write access (${denied.join(', ')}). ` +
                     `Open a change request from "${sourceBranch}" into "${targetBranch}" and ask the user to review it in the app.`,
@@ -4657,7 +4644,7 @@ export class WorkflowService implements IWorkflowService {
    */
   private gateWouldPass(number: number, approvals: FileApproval[]): boolean {
     try {
-      const gate = this.reviewWorkflow.evaluateMergeGate({ prNumber: number, state: 'open', approvals });
+      const gate = this.changeRequestReview.evaluateMergeGate({ prNumber: number, state: 'open', approvals });
       return gate?.mergeable === true && gate.warnings.length === 0;
     } catch (err) {
       crLog.warn(`could not re-evaluate the merge gate of change request #${number}; keeping its refusal:`, { err });
@@ -4978,7 +4965,7 @@ export class WorkflowService implements IWorkflowService {
       throw new Error('updateBranch: resolutions need a `validateWrite` to be asked before the merge');
     }
     if (this.kb.isProtectedBranch(branch)) {
-      throw new WorkflowDomainError(
+      throw new VersionControlDomainError(
         `"${branch}" is protected: it is changed through change requests, never merged into directly.`,
         403,
         { kind: 'protected-update-target', branch },
@@ -5026,7 +5013,7 @@ export class WorkflowService implements IWorkflowService {
         if (open !== null) throw new OpenChangeRequestBlocksMergeError(from, branch, open);
       }
       if (!(await this.git.remoteBranchExists(workspaceId, from))) {
-        throw new WorkflowValidationError(`No branch named "${from}" on the shared repository.`);
+        throw new VersionControlValidationError(`No branch named "${from}" on the shared repository.`);
       }
       const resolutions = opts.resolutions ?? [];
       const subject = from === branch ? `Merge the shared ${branch} into the local one` : `Merge ${from} into ${branch}`;
@@ -5038,7 +5025,7 @@ export class WorkflowService implements IWorkflowService {
           ? ` Conflicts resolved by ${user.name} <${user.email}> in: ${resolutions.map((r) => r.path).join(', ')}.`
           : '');
       // Published inside the merge's own reservation: nothing lands between
-      // the merge commit and its push, and the push is EVERY workflow push's
+      // the merge commit and its push, and the push is EVERY version-control push's
       // `pushWithRecovery`, run over the merge's own unlocked moves — a
       // rejection replays the merge (kept as a merge) onto the moved branch
       // and pushes again; a replay that conflicts or a host that refuses