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

package/dist/modules/{workflow/workflow.service.js → version-control/version-control.service.js}

@@ -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';
 import { execFile } from 'node:child_process';
@@ -38,11 +33,11 @@ import { redactSecret } from '../../shared/redact-secret.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 import { describeSyncFailure, sanitizeError } from './sanitize-error.js';
-import { WorkflowHooks } from './workflow-hooks.js';
+import { VersionControlHooks } from './version-control-hooks.js';
 import { ChangeRequestHooks, } from './change-request-hooks.js';
 import { WorkspaceMutex, assertValidBranchName } from '../kb-fs/index.js';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
-import { BranchAuthorshipError, BranchDeleteBlockedError, BranchNotFoundError, ChangeRequestConflictsError, DuplicateChangeRequestError, OpenChangeRequestBlocksMergeError, ProtectedBranchError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, RemoteBranchGoneError, WorkflowDomainError, WorkflowValidationError, } from '../../shared/domain-errors.js';
+import { BranchAuthorshipError, BranchDeleteBlockedError, BranchNotFoundError, ChangeRequestConflictsError, DuplicateChangeRequestError, OpenChangeRequestBlocksMergeError, ProtectedBranchError, RolesYamlPreservationError, PullRebaseConflictError, PushNeedsAgentResolutionError, RemoteBranchGoneError, VersionControlDomainError, VersionControlValidationError, } from '../../shared/domain-errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
 import { AccessDeniedError, EVERYONE_CANONICAL } from '../access-model/index.js';
 import { printable } from '../../shared/printable.js';
@@ -117,15 +112,15 @@ function redactTokens(msg, token) {
  */
 function assertDescriptionFits(description) {
     if (description !== undefined && description.length > CHANGE_REQUEST_DESCRIPTION_MAX) {
-        throw new WorkflowValidationError(`A change request's description is at most ${CHANGE_REQUEST_DESCRIPTION_MAX} characters; this one would have ${description.length}.`);
+        throw new VersionControlValidationError(`A change request's description is at most ${CHANGE_REQUEST_DESCRIPTION_MAX} characters; this one would have ${description.length}.`);
     }
 }
 function assertEditable(state) {
     if (state === 'merged') {
-        throw new WorkflowDomainError('This change request has already been applied; its title and description can no longer be changed.', 409);
+        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('This change request is closed; its title and description can no longer be changed.', 409);
+        throw new VersionControlDomainError('This change request is closed; its title and description can no longer be changed.', 409);
     }
 }
 /** Git commit subjects are capped at 200 characters (`GitService.commitFile`). */
@@ -148,11 +143,11 @@ const basenameOf = (repoRelPath) => repoRelPath.split('/').pop() ?? repoRelPath;
 function folderPrefix(folder) {
     return `${folder.replace(/\/+$/, '')}/`;
 }
-export class WorkflowService {
+export class VersionControlService {
     db;
     git;
     prs;
-    reviewWorkflow;
+    changeRequestReview;
     workspaceService;
     accessControl;
     fileLocks;
@@ -160,16 +155,15 @@ export class WorkflowService {
     kb;
     changeGate;
     events;
-    fileChanges;
     hooks;
     changeRequestHooks;
     accounts;
     /**
      * 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
@@ -177,16 +171,16 @@ export class WorkflowService {
      */
     /**
      * 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.
      */
     get kbDirName() {
         return this.kb.kbDirName;
     }
-    constructor(db, git, prs, reviewWorkflow, workspaceService, accessControl, fileLocks, 
+    constructor(db, git, prs, changeRequestReview, workspaceService, accessControl, fileLocks, 
     /**
      * Background commit queue. `releaseLock` enqueues a row instead of
      * committing inline; the `PendingCommitsWorker` drains the queue and
@@ -210,22 +204,15 @@ export class WorkflowService {
      */
     events, 
     /**
-     * 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`.
-     */
-    fileChanges, 
-    /**
-     * 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.
      */
-    hooks = new WorkflowHooks(), 
+    hooks = 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
@@ -242,7 +229,7 @@ export class WorkflowService {
         this.db = db;
         this.git = git;
         this.prs = prs;
-        this.reviewWorkflow = reviewWorkflow;
+        this.changeRequestReview = changeRequestReview;
         this.workspaceService = workspaceService;
         this.accessControl = accessControl;
         this.fileLocks = fileLocks;
@@ -250,14 +237,13 @@ export class WorkflowService {
         this.kb = kb;
         this.changeGate = changeGate;
         this.events = events;
-        this.fileChanges = fileChanges;
         this.hooks = hooks;
         this.changeRequestHooks = changeRequestHooks;
         this.accounts = accounts;
         // 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)');
         }
     }
     // ── Branches ──────────────────────────────────────────────────────────────
@@ -401,7 +387,7 @@ export class WorkflowService {
                     // 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(open.end === 'source'
+                    throw new VersionControlValidationError(open.end === 'source'
                         ? `Branch "${name}" has an open change request (#${open.number}). ` +
                             `Withdraw or decline it before deleting the branch.`
                         : `Open change request #${open.number} proposes changes into "${name}". ` +
@@ -747,7 +733,7 @@ export class WorkflowService {
     // longer exposes a "checkout this branch on the source workspace's clone"
     // 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) {
         return this.git.status(workspaceId);
@@ -950,7 +936,7 @@ export class WorkflowService {
             // 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',
@@ -1261,7 +1247,7 @@ export class WorkflowService {
         const targetPath = canonicalFileIdentity(rawPath);
         const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
         if (!lock || lock.holderUserId !== user.id) {
-            throw new WorkflowValidationError(`Cannot commit "${targetPath}": you don't hold the lock.`, { kind: 'lock-not-held', branch, path: targetPath });
+            throw new VersionControlValidationError(`Cannot commit "${targetPath}": you don't hold the lock.`, { kind: 'lock-not-held', branch, path: targetPath });
         }
         // A coordination hold is NOT write possession (see `acquireLock`): it was
         // acquired past the write-authorization gate on the promise that nothing
@@ -1269,7 +1255,7 @@ export class WorkflowService {
         // holder checkpoint bytes onto a path — machine-owned files included —
         // whose write rule they never passed.
         if (lock.mode === 'coordination') {
-            throw new WorkflowValidationError(`Cannot commit "${targetPath}": the lock is a coordination hold, which grants no write authority.`, { kind: 'coordination-hold', branch, path: targetPath });
+            throw new VersionControlValidationError(`Cannot commit "${targetPath}": the lock is a coordination hold, which grants no write authority.`, { kind: 'coordination-hold', branch, path: targetPath });
         }
         const change = await this.git.commitFile(workspaceId, user, targetPath, summary);
         // Push the autosave commit so other users on the branch see it
@@ -1380,7 +1366,7 @@ export class WorkflowService {
         const lock = await this.fileLocks.get(workspaceId, branch, targetPath);
         if (!lock || lock.holderUserId !== user.id) {
             lockLog.warn(`RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → ${lock ? `held by ${lock.holderUserId}` : 'no lock row'}`);
-            throw new WorkflowValidationError(`Cannot release lock on "${targetPath}": not held by you (or no longer exists).`, { kind: 'lock-not-held', branch, path: targetPath });
+            throw new VersionControlValidationError(`Cannot release lock on "${targetPath}": not held by you (or no longer exists).`, { kind: 'lock-not-held', branch, path: targetPath });
         }
         // Releasing a coordination hold must NEVER enqueue a commit: the hold was
         // granted past the write-authorization gate (see `acquireLock`) on the
@@ -1393,7 +1379,7 @@ export class WorkflowService {
         // row until its TTL.
         if (lock.mode === 'coordination') {
             lockLog.warn(`RELEASE refused ws=${workspaceId} branch=${branch} path=${targetPath} user=${user.id} → coordination hold (no commit may be enqueued)`);
-            throw new WorkflowValidationError(`Cannot release lock on "${targetPath}" with a commit: it is a coordination hold. Use releaseLockNoCommit.`, { kind: 'coordination-hold', branch, path: targetPath });
+            throw new VersionControlValidationError(`Cannot release lock on "${targetPath}" with a commit: it is a coordination hold. Use releaseLockNoCommit.`, { kind: 'coordination-hold', branch, path: targetPath });
         }
         // Order matters here:
         //   1. Drop the lock row. Other sessions can re-acquire immediately.
@@ -1457,11 +1443,14 @@ export class WorkflowService {
             // 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);
@@ -1474,9 +1463,6 @@ export class WorkflowService {
             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 });
     }
     /**
      * Workspaces whose last push failed. Purely so the recovery event fires on
@@ -1563,7 +1549,7 @@ export class WorkflowService {
      * 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
@@ -1683,7 +1669,7 @@ export class WorkflowService {
         //
         // 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
@@ -1850,17 +1836,17 @@ export class WorkflowService {
      */
     async openChangeRequest(workspaceId, user, input) {
         if (!input.sourceBranch)
-            throw new WorkflowValidationError('sourceBranch is required');
+            throw new VersionControlValidationError('sourceBranch is required');
         if (!input.targetBranch)
-            throw new WorkflowValidationError('targetBranch is required');
+            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');
+            throw new VersionControlValidationError('title is required');
         assertDescriptionFits(input.description?.trim());
         if (this.kb.isProtectedBranch(input.sourceBranch)) {
-            throw new WorkflowValidationError(`Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`, { kind: 'source-is-protected', sourceBranch: input.sourceBranch });
+            throw new VersionControlValidationError(`Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`, { kind: 'source-is-protected', sourceBranch: input.sourceBranch });
         }
         // The whole open sequence — uniqueness check through row insert — runs
         // under the lifecycle lock of BOTH branches. `retireMergedSourceBranch`
@@ -1890,7 +1876,7 @@ export class WorkflowService {
             }
             // 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, input.sourceBranch, input.targetBranch, user);
             if (mergeOutcome.kind === 'conflicts') {
@@ -1959,7 +1945,7 @@ export class WorkflowService {
                     // 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(`Change request for "${input.sourceBranch}" → "${input.targetBranch}" ` +
+                        throw new VersionControlValidationError(`Change request for "${input.sourceBranch}" → "${input.targetBranch}" ` +
                             'raced with a concurrent open/close; retry.', { kind: 'open-change-request-failed' });
                     }
                     throw new DuplicateChangeRequestError(input.sourceBranch, input.targetBranch, existing.number);
@@ -1970,7 +1956,7 @@ export class WorkflowService {
                 // 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(`Failed to open change request: ${redactTokens(rawMsg, this.git.credentials?.token())}`, { kind: 'open-change-request-failed' });
+                throw new VersionControlValidationError(`Failed to open change request: ${redactTokens(rawMsg, this.git.credentials?.token())}`, { kind: 'open-change-request-failed' });
             }
             this.prs.invalidateDetailCache(prNumber);
             const opened = {
@@ -2013,7 +1999,7 @@ export class WorkflowService {
                 eligible,
                 detail: null,
                 pushRefused: null,
-                detailError: detailError ?? new WorkflowValidationError(`Created change request #${prNumber} but could not fetch its detail`),
+                detailError: detailError ?? new VersionControlValidationError(`Created change request #${prNumber} but could not fetch its detail`),
             };
         });
         // The request exists in every branch of the outcome — the listeners are
@@ -2134,13 +2120,13 @@ export class WorkflowService {
             patches: false,
         });
         if (!detail) {
-            throw new WorkflowValidationError(`Change request #${number} not found.`, { kind: 'change-request-not-found', number });
+            throw new VersionControlValidationError(`Change request #${number} not found.`, { kind: 'change-request-not-found', number });
         }
         if (detail.state !== 'open') {
-            throw new WorkflowValidationError(`Change request #${number} is ${detail.state} — only open requests can refresh from target.`, { kind: 'change-request-not-open', state: detail.state });
+            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('Only the author of this change request, or someone who may apply it, can update it.', 403);
+            throw new VersionControlDomainError('Only the author of this change request, or someone who may apply it, can update it.', 403);
         }
         // Taken BEFORE the head moves (the pull below can move it too): only a
         // refusal recorded earlier describes the revision this replaces (see
@@ -2263,7 +2249,7 @@ export class WorkflowService {
         if (headMoved) {
             try {
                 updatedPaths = await this.git.pathsChangedBetween(workspaceId, headBeforeMerge, headAfterMerge);
-                await this.reviewWorkflow.carryApprovalsForward(number, headBeforeMerge, headAfterMerge, updatedPaths);
+                await this.changeRequestReview.carryApprovalsForward(number, headBeforeMerge, headAfterMerge, updatedPaths);
             }
             catch (err) {
                 log.warn(`could not carry approvals forward on change request #${number} after updating from target`, { err });
@@ -2282,14 +2268,14 @@ export class WorkflowService {
             viewerEmail: user.email,
         });
         if (!refreshed) {
-            throw new WorkflowValidationError(`Refreshed change request #${number} but could not re-fetch its detail.`);
+            throw new VersionControlValidationError(`Refreshed change request #${number} but could not re-fetch its detail.`);
         }
         return { ...refreshed, updatedPaths };
     }
     async approveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId) {
         // Taken BEFORE the approval lands (see `clearApplyFailure`).
         const approvedAfter = new Date();
-        const approvals = await this.reviewWorkflow.approveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId);
+        const approvals = await this.changeRequestReview.approveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId);
         // A recorded approval can answer a GATE refusal only — a conflict or a git
         // error still describes the request — and only once the gate that refused
         // would now pass: approving one file of several leaves the rest waiting,
@@ -2310,7 +2296,7 @@ export class WorkflowService {
         return approvals;
     }
     async unapproveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId) {
-        const approvals = await this.reviewWorkflow.unapproveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId);
+        const approvals = await this.changeRequestReview.unapproveFile(number, path, user, files, headSha, baseBranch, authorIdHash, workspaceId);
         this.prs.invalidateDetailCache(number);
         this.events?.emit({
             kind: 'approval-changed',
@@ -2362,9 +2348,9 @@ export class WorkflowService {
     async revertChangeRequestFile(number, user, repoRelPath) {
         const summary = await this.prs.getPr(number);
         if (!summary)
-            throw new WorkflowDomainError('change request not found', 404);
+            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;
@@ -2381,15 +2367,15 @@ export class WorkflowService {
         // 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(ws.id, `origin/${baseBranch}`, user.email, repoRelPath);
         if (canApprove !== true) {
-            throw new WorkflowDomainError('Only an eligible approver of this file can revert it — declining takes the same permission as accepting.', 403);
+            throw new VersionControlDomainError('Only an eligible approver of this file can revert it — declining takes the same permission as accepting.', 403);
         }
         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);
         const reverted = placeholder ? [repoRelPath, placeholder] : [repoRelPath];
@@ -2406,7 +2392,7 @@ export class WorkflowService {
                 const lockPath = `${this.kbDirName}/${p}`;
                 const lock = await this.fileLocks.acquire(ws.id, headBranch, lockPath, user);
                 if (!lock.acquired) {
-                    throw new WorkflowDomainError(p === repoRelPath
+                    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.`, 409);
                 }
@@ -2486,7 +2472,7 @@ export class WorkflowService {
             }
             catch (err) {
                 log.warn(`changedPathsForPr failed for #${cr.number} under folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
-                throw new WorkflowDomainError(`Couldn't read what change request #${cr.number} proposes — try again in a moment.`, 500);
+                throw new VersionControlDomainError(`Couldn't read what change request #${cr.number} proposes — try again in a moment.`, 500);
             }
         }));
         const touching = resolved
@@ -2549,7 +2535,7 @@ export class WorkflowService {
         const requests = await this.changeRequestsUnderFolder(folder, user);
         const refused = requests.filter((r) => !r.mayRemove);
         if (refused.length > 0) {
-            throw new WorkflowDomainError(`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);
+            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);
         }
         const prefix = folderPrefix(folder);
         // Everything that can refuse happens before the first commit, so a
@@ -2571,7 +2557,7 @@ export class WorkflowService {
             }
             catch (err) {
                 log.warn(`pull failed for #${summary.number} before removing folder ${printable(folder)}: ${printable(sanitizeError(err))}`);
-                throw new WorkflowDomainError(`#${summary.number} could not be brought up to date, so nothing was removed — try again in a moment.`, 409);
+                throw new VersionControlDomainError(`#${summary.number} could not be brought up to date, so nothing was removed — try again in a moment.`, 409);
             }
             const paths = (await this.git.changedPathsForPr(ws.id, summary.base, summary.branch)).filter((p) => p.startsWith(prefix));
             // The permission above was judged on the paths the request proposed
@@ -2579,13 +2565,13 @@ export class WorkflowService {
             // 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(`#${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);
+                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);
             }
             let mergeBase = null;
             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 });
@@ -2612,7 +2598,7 @@ export class WorkflowService {
                 }
                 else if (seen.mergeBase !== plan.mergeBase) {
                     const sharing = group.plans.map((other) => `#${other.number}`).join(', ');
-                    throw new WorkflowDomainError(`${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);
+                    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);
                 }
             }
         }
@@ -2639,7 +2625,7 @@ export class WorkflowService {
                     const lockPath = `${this.kbDirName}/${repoRelPath}`;
                     const lock = await this.fileLocks.acquire(group.wsId, group.branch, lockPath, user);
                     if (!lock.acquired) {
-                        throw new WorkflowDomainError(`${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`, 409);
+                        throw new VersionControlDomainError(`${repoRelPath} is being edited by ${lock.lock.holderName} — try again once the edit settles.`, 409);
                     }
                     held.push({ wsId: group.wsId, branch: group.branch, lockPath });
                 }
@@ -2710,7 +2696,7 @@ export class WorkflowService {
         if (pushFailure) {
             const failed = pushFailure.group.plans.map((plan) => `#${plan.number}`).join(', ');
             log.warn(`push failed for ${failed} removing folder ${printable(folder)}: ${printable(sanitizeError(pushFailure.err))}`);
-            throw new WorkflowDomainError(`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);
+            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);
         }
         return results;
     }
@@ -2731,9 +2717,9 @@ export class WorkflowService {
     async deleteChangeRequest(number, user) {
         const summary = await this.prs.getPr(number);
         if (!summary)
-            throw new WorkflowDomainError('change request not found', 404);
+            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
         // other admin check here. When the base branch itself is gone, this
@@ -2758,7 +2744,7 @@ export class WorkflowService {
                 await this.workspaceService.ensureRemotesFetched(ws.id, { strict: true });
             }
             catch {
-                throw new WorkflowDomainError(`Could not verify the base branch "${summary.base}" — origin was unreachable. Retry in a moment.`, 409);
+                throw new VersionControlDomainError(`Could not verify the base branch "${summary.base}" — origin was unreachable. Retry in a moment.`, 409);
             }
             isAdmin = await this.accessControl.canWriteAtRef(ws.id, `origin/${summary.base}`, user.email, 'roles.yaml');
         }
@@ -2774,7 +2760,7 @@ export class WorkflowService {
         // attempt the sweep has either closed the row or shown the base alive.
         if (isAdmin === null) {
             this.kickDeletedBranchSweep();
-            throw new WorkflowDomainError(`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);
+            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);
         }
         // Authorship is decided from the STORED author hash, never from anything
         // the caller sends. Note what is deliberately NOT short-circuited for an
@@ -2786,7 +2772,7 @@ export class WorkflowService {
         // 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
         // branch retirement). Guarded on `open` so a concurrent merge wins.
@@ -2803,7 +2789,7 @@ export class WorkflowService {
         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);
@@ -2837,7 +2823,7 @@ export class WorkflowService {
         }
         catch {
             this.kickDeletedBranchSweep();
-            throw new WorkflowDomainError(`Could not verify the base branch "${baseBranch}" — origin was unreachable. Retry in a moment.`, 409);
+            throw new VersionControlDomainError(`Could not verify the base branch "${baseBranch}" — origin was unreachable. Retry in a moment.`, 409);
         }
         const isAdmin = await this.accessControl.canWriteAtRef(workspaceId, `origin/${baseBranch}`, user.email, 'roles.yaml');
         if (isAdmin === true)
@@ -2847,7 +2833,7 @@ export class WorkflowService {
         // read and a batch lookup done for nothing.
         if (isAdmin === null) {
             this.kickDeletedBranchSweep();
-            throw new WorkflowDomainError(`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);
+            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);
         }
         let detail;
         try {
@@ -2885,16 +2871,16 @@ export class WorkflowService {
         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(`A change request's title is at most ${CHANGE_REQUEST_TITLE_MAX} characters; this one has ${title.length}.`);
+            throw new VersionControlValidationError(`A change request's title is at most ${CHANGE_REQUEST_TITLE_MAX} characters; this one has ${title.length}.`);
         }
         // A replacement is measured here; an append is measured on what it
         // leaves, inside the transaction, since that depends on the body as
@@ -2902,7 +2888,7 @@ export class WorkflowService {
         assertDescriptionFits(description);
         const summary = await this.prs.getPr(number);
         if (!summary)
-            throw new WorkflowDomainError('change request not found', 404);
+            throw new VersionControlDomainError('change request not found', 404);
         assertEditable(summary.state);
         // The grants beyond authorship are read in the base branch's own workspace,
         // resolved only once authorship has not already decided: an author's edit
@@ -2918,7 +2904,7 @@ export class WorkflowService {
             }
         });
         if (grant === null) {
-            throw new WorkflowDomainError("Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.", 403);
+            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);
         }
         // The body is rewritten from the row as stored, not from the summary read
         // above, inside one transaction holding the row's lock (`FOR UPDATE`) from
@@ -2963,15 +2949,15 @@ export class WorkflowService {
         if (!updated) {
             const fresh = await this.prs.getPr(number);
             if (!fresh)
-                throw new WorkflowDomainError('change request not found', 404);
+                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);
+            throw new VersionControlDomainError('change request not found', 404);
         return fresh;
     }
     /**
@@ -3043,7 +3029,7 @@ export class WorkflowService {
      * 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
@@ -3506,7 +3492,7 @@ export class WorkflowService {
                 effectiveAuthorIdHash = hashEmail(user.email);
             }
         }
-        const result = await this.reviewWorkflow.cancelPr(number, user, state, effectiveAuthorIdHash, baseBranch, workspaceId);
+        const result = await this.changeRequestReview.cancelPr(number, user, state, effectiveAuthorIdHash, baseBranch, workspaceId);
         this.prs.invalidateDetailCache(number);
         this.events?.emit({ kind: 'change-request-rejected', number });
         return result;
@@ -3561,7 +3547,7 @@ export class WorkflowService {
         }
         let result;
         try {
-            result = await this.reviewWorkflow.mergePr(number, user, mergeHeadSha, mergeApprovals, state, title, baseBranch, workspaceId, opts);
+            result = await this.changeRequestReview.mergePr(number, user, mergeHeadSha, mergeApprovals, state, title, baseBranch, workspaceId, opts);
         }
         catch (err) {
             // The local merge hit conflicts — hand the caller (agent/UI) the actual
@@ -3693,7 +3679,7 @@ export class WorkflowService {
     }
     async mergeBranch(user, sourceBranch, targetBranch) {
         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
         // at once rather than after the source's commits have landed. Not the
@@ -3742,7 +3728,7 @@ export class WorkflowService {
             // 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(targetWorkspaceId, sourceBranch, targetBranch, {
                 subject: `Merge ${sourceBranch} into ${targetBranch}`,
@@ -3780,7 +3766,7 @@ export class WorkflowService {
                         // roles.yaml would bypass both, on the one file the access
                         // model cannot survive being wrong.
                         if (changedPaths.includes('roles.yaml')) {
-                            throw new WorkflowDomainError(`"${targetBranch}" is protected and this merge would change its roles.yaml. ` +
+                            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.`, 403, { kind: 'protected-merge-changes-roles', targetBranch, sourceBranch });
                         }
@@ -3788,7 +3774,7 @@ export class WorkflowService {
                         const denied = allowed ? changedPaths.filter((p) => !allowed.get(p)) : [];
                         if (denied.length === 0)
                             return;
-                        throw new WorkflowDomainError(`"${targetBranch}" is protected and you cannot commit directly to it: ` +
+                        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.`, 403, { kind: 'protected-merge-target', targetBranch, deniedPaths: denied });
                     }
@@ -3888,7 +3874,7 @@ export class WorkflowService {
      */
     gateWouldPass(number, approvals) {
         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) {
@@ -4159,7 +4145,7 @@ export class WorkflowService {
             throw new Error('updateBranch: resolutions need a `validateWrite` to be asked before the merge');
         }
         if (this.kb.isProtectedBranch(branch)) {
-            throw new WorkflowDomainError(`"${branch}" is protected: it is changed through change requests, never merged into directly.`, 403, { kind: 'protected-update-target', branch });
+            throw new VersionControlDomainError(`"${branch}" is protected: it is changed through change requests, never merged into directly.`, 403, { kind: 'protected-update-target', branch });
         }
         // The one merge a person makes: a change request's. An update that would
         // land an OPEN request from `from` into this draft is that merge by
@@ -4205,7 +4191,7 @@ export class WorkflowService {
                     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}`;
@@ -4216,7 +4202,7 @@ export class WorkflowService {
                     ? ` 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
@@ -4268,4 +4254,4 @@ export class WorkflowService {
         return this.git.changedPathsForPr(workspaceId, base, branch);
     }
 }
-//# sourceMappingURL=workflow.service.js.map
+//# sourceMappingURL=version-control.service.js.map