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

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

@@ -28,7 +28,7 @@ function stripKbDir(path: string, kbDirName: string): string {
 const protectedInline = (kb: Pick<KbContext, 'protectedBranches'>) =>
   [...kb.protectedBranches].map((b) => `\`${b}\``).join(' / ');
 
-// Output sub-schemas for the git-aliased workflow payloads (Branch, Change,
+// Output sub-schemas for the git-aliased version-control payloads (Branch, Change,
 // ChangeRequest, …). Defined once and referenced by the individual tool
 // defs below so each tool still declares its own `outputs`.
 const branchSchema: JsonSchema = {
@@ -139,15 +139,15 @@ const changeRequestSummarySchema: JsonSchema = {
 };
 
 /**
- * Workflow domain tools, registered into the central catalog and hosted on the
+ * Version-control domain tools, registered into the central catalog and hosted on the
  * shared tools router — the ONE mechanism: build a self-describing UTCP def,
  * host the endpoint behind `toolAuth` + `toolHandler`, register the def. Each is
- * a thin facade over `IWorkflowService`; identity + workspace come from the
+ * a thin facade over `IVersionControlService`; identity + workspace come from the
  * resolved `ToolContext` (so a caller can never address another user/workspace).
  * All are `both` (external agents can drive repo ops directly); the write ones
  * carry the `write` tag so read-scoped callers are refused.
  */
-export function registerWorkflowTools(
+export function registerVersionControlTools(
   registry: IToolRegistry,
   router: Router,
   toolAuth: RequestHandler,
@@ -202,7 +202,7 @@ export function registerWorkflowTools(
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
-    // Every workflow tool that takes a branch REQUIRES it — the injected input
+    // Every version-control tool that takes a branch REQUIRES it — the injected input
     // and a hand-declared one (the fork base, the draft to switch to) alike.
     // A hand-declared one is required by its own schema, which `toolDef`
     // reads as `required` too; the tool handler refuses a call without it.
@@ -272,7 +272,7 @@ export function registerWorkflowTools(
     },
     write: false,
     handler: async (_args, ctx: ToolContext) => ({
-      branches: await ctx.workflowService.listBranches(await repoGlobalWorkspaceId(ctx)),
+      branches: await ctx.versionControlService.listBranches(await repoGlobalWorkspaceId(ctx)),
     }),
   });
 
@@ -299,7 +299,7 @@ export function registerWorkflowTools(
     },
     write: true,
     handler: async (args, ctx: ToolContext) => ({
-      change: await ctx.workflowService.commitChange(workspaceIdForBranch(args.branch as string), ctx.user, {
+      change: await ctx.versionControlService.commitChange(workspaceIdForBranch(args.branch as string), ctx.user, {
         summary: args.summary as string,
         description: typeof args.description === 'string' ? args.description : undefined,
       }),
@@ -346,11 +346,11 @@ export function registerWorkflowTools(
       }
       assertInsideRepo(path, kbDirName);
       const workspaceId = workspaceIdForBranch(branch);
-      const acquired = await ctx.workflowService.acquireLock(workspaceId, branch, path, ctx.user);
+      const acquired = await ctx.versionControlService.acquireLock(workspaceId, branch, path, ctx.user);
       if (!acquired.acquired) {
         return { saved: false, reason: `Locked by ${acquired.lock.holderName ?? 'another user'} — try again later.` };
       }
-      await ctx.workflowService.releaseLock(workspaceId, branch, path, ctx.user);
+      await ctx.versionControlService.releaseLock(workspaceId, branch, path, ctx.user);
       return { saved: true, queued: true };
     },
   });
@@ -369,7 +369,7 @@ export function registerWorkflowTools(
     },
     write: true,
     handler: async (args, ctx: ToolContext) => {
-      await ctx.workflowService.shareCurrentBranch(workspaceIdForBranch(args.branch as string), ctx.user);
+      await ctx.versionControlService.shareCurrentBranch(workspaceIdForBranch(args.branch as string), ctx.user);
       return { shared: true };
     },
   });
@@ -430,7 +430,7 @@ export function registerWorkflowTools(
         );
       }
       return {
-        branch: await ctx.workflowService.createBranch(workspaceIdForBranch(base), name),
+        branch: await ctx.versionControlService.createBranch(workspaceIdForBranch(base), name),
       };
     },
   });
@@ -478,7 +478,7 @@ export function registerWorkflowTools(
     // answer, so nothing below the tool changes.
     handler: async (args, ctx: ToolContext) =>
       summarizeChangeRequest(
-        await ctx.workflowService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
+        await ctx.versionControlService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
           sourceBranch: args.sourceBranch as string,
           targetBranch: args.targetBranch as string,
           title: args.title as string,
@@ -536,7 +536,7 @@ export function registerWorkflowTools(
       if (!(await maySeeChangeRequest(ctx, number))) {
         throw new ToolError(`Change request #${number} not found.`, 404);
       }
-      const updated = await ctx.workflowService.updateChangeRequest(number, ctx.user, {
+      const updated = await ctx.versionControlService.updateChangeRequest(number, ctx.user, {
         title,
         description,
         appendDescription,
@@ -614,7 +614,7 @@ export function registerWorkflowTools(
       if (typeof source !== 'string' || source.length === 0 || typeof target !== 'string' || target.length === 0) {
         throw new ToolError('`source` and `target` are required branch names.', 400);
       }
-      return { outcome: await ctx.workflowService.mergeBranch(ctx.user, source, target) };
+      return { outcome: await ctx.versionControlService.mergeBranch(ctx.user, source, target) };
     },
   });
 
@@ -685,7 +685,7 @@ export function registerWorkflowTools(
           kind: 'name-required',
         });
       }
-      return ctx.workflowService.deleteBranchChecked(ctx.user, name, {
+      return ctx.versionControlService.deleteBranchChecked(ctx.user, name, {
         dryRun: args.dryRun === true,
         discardUnmerged: args.discardUnmerged === true,
         maySee: (number) => maySeeChangeRequest(ctx, number),
@@ -734,7 +734,7 @@ export function registerWorkflowTools(
       // Validate the target exists by listing from any existing clone (every
       // clone tracks all remote refs) — there is no "current" workspace here,
       // and the default branch may not even be on the remote.
-      const branches = await ctx.workflowService.listBranches(await repoGlobalWorkspaceId(ctx));
+      const branches = await ctx.versionControlService.listBranches(await repoGlobalWorkspaceId(ctx));
       if (!branches.find((b) => b.name === target)) {
         const known = branches.map((b) => b.name).slice(0, 25).join(', ');
         throw new ToolError(`No draft named "${target}" on this workspace. Known: ${known || '(none)'}.`, 404);
@@ -757,7 +757,7 @@ export function registerWorkflowTools(
   //
   // What the app's History tab, compare view and "update from target" do,
   // as tools: the agent never runs git itself. Each reads through the
-  // workflow service's gated methods and takes the per-file read the file
+  // version-control service's gated methods and takes the per-file read the file
   // itself takes.
 
   /** The branch's workspace, made when it is not on disk yet, and its id. */
@@ -829,7 +829,7 @@ export function registerWorkflowTools(
       const workspaceId = await workspaceOf(ctx, branch);
       const rel = await requireRead(ctx, branch, workspaceId, path);
       const limit = typeof args.limit === 'number' ? args.limit : undefined;
-      const changes = await ctx.workflowService.listChangesForFile(workspaceId, path, limit);
+      const changes = await ctx.versionControlService.listChangesForFile(workspaceId, path, limit);
       return { path: rel, changes };
     },
   });
@@ -876,14 +876,14 @@ export function registerWorkflowTools(
       // read: the file is this workspace's file.
       const rel = await requireRead(ctx, branch, workspaceId, path);
       if (isCommitSha(at)) {
-        const { baseline, current } = await ctx.workflowService.fileAtChange(workspaceId, path, at);
+        const { baseline, current } = await ctx.versionControlService.fileAtChange(workspaceId, path, at);
         return { path: rel, at, kind: 'commit', sha: at, content: current, before: baseline };
       }
       // Read at the branch's published tip, authorized at that very commit
       // inside the read — before anything is said about the path there,
       // the folder refusal included: the ref is a name a fetch may move
       // between a verdict and a read; the commit is not.
-      const read = await ctx.workflowService.fileAtBranch(workspaceId, path, at, (commits) => requireReadAtCommits(ctx, workspaceId, rel, commits, at));
+      const read = await ctx.versionControlService.fileAtBranch(workspaceId, path, at, (commits) => requireReadAtCommits(ctx, workspaceId, rel, commits, at));
       return { path: rel, at, kind: 'branch', sha: read.sha, content: read.content };
     },
   });
@@ -926,14 +926,14 @@ export function registerWorkflowTools(
       const rel = await requireRead(ctx, branch, workspaceId, path);
       if (typeof args.at === 'string' && args.at.length > 0) {
         if (!isCommitSha(args.at)) throw new ToolError('`at` must be a full commit sha.', 400);
-        return { path: rel, diff: await ctx.workflowService.showFileAtChange(workspaceId, path, args.at) };
+        return { path: rel, diff: await ctx.versionControlService.showFileAtChange(workspaceId, path, args.at) };
       }
       const from = args.from;
       const to = args.to;
       if (typeof from !== 'string' || from.length === 0 || typeof to !== 'string' || to.length === 0) {
         throw new ToolError('Give `from` and `to` (two branches), or `at` (one commit).', 400);
       }
-      const compared = await ctx.workflowService.compareFile(workspaceId, path, from, to, async (sides) => {
+      const compared = await ctx.versionControlService.compareFile(workspaceId, path, from, to, async (sides) => {
         await requireReadAtCommits(ctx, workspaceId, rel, sides.from, from);
         await requireReadAtCommits(ctx, workspaceId, rel, sides.to, to);
       });
@@ -986,12 +986,12 @@ export function registerWorkflowTools(
       // The counts alone wait for the listing: its fetch refreshes the
       // remote-tracking refs they are measured against.
       const [status, [branches, counts], pending, forkBase] = await Promise.all([
-        ctx.workflowService.branchStatus(workspaceId),
-        ctx.workflowService
+        ctx.versionControlService.branchStatus(workspaceId),
+        ctx.versionControlService
           .listBranches(workspaceId)
-          .then(async (listed) => [listed, await ctx.workflowService.branchCounts(workspaceId)] as const),
-        ctx.workflowService.listPendingChangePaths(workspaceId),
-        ctx.workflowService.resolveForkBase(workspaceId, branch),
+          .then(async (listed) => [listed, await ctx.versionControlService.branchCounts(workspaceId)] as const),
+        ctx.versionControlService.listPendingChangePaths(workspaceId),
+        ctx.versionControlService.resolveForkBase(workspaceId, branch),
       ]);
       const info = branches.find((b) => b.name === branch);
       const base = typeof args.base === 'string' && args.base.length > 0 ? args.base : forkBase;
@@ -999,7 +999,7 @@ export function registerWorkflowTools(
       // change-request reads show them (readable at `origin/<base>`), the
       // uncommitted ones as the workspace's own listing would.
       const changedAll =
-        base && base !== branch ? await ctx.workflowService.changedPathsBetweenBranches(workspaceId, base, branch) : [];
+        base && base !== branch ? await ctx.versionControlService.changedPathsBetweenBranches(workspaceId, base, branch) : [];
       const readableChanged = base ? await readableAt(ctx, workspaceId, base, changedAll) : new Set<string>();
       const changedPaths = changedAll.filter((p) => readableChanged.has(p));
       const pendingRel = pending.map((p) => stripKbDir(p, kbDirName));
@@ -1177,12 +1177,12 @@ export function registerWorkflowTools(
       // group), handed to the service to ask before the merge.
       const outcome =
         resolutions !== undefined
-          ? await ctx.workflowService.updateBranch(workspaceId, ctx.user, {
+          ? await ctx.versionControlService.updateBranch(workspaceId, ctx.user, {
               ...(from !== undefined ? { from } : {}),
               resolutions,
               validateWrite: await ctx.getWriteValidator(branch),
             })
-          : await ctx.workflowService.updateBranch(workspaceId, ctx.user, from !== undefined ? { from } : {});
+          : await ctx.versionControlService.updateBranch(workspaceId, ctx.user, from !== undefined ? { from } : {});
       if (outcome.kind !== 'conflicts') return outcome;
       // A conflict answer carries the file on both branches, and a path's
       // name is information too: a file the caller may not read on both is

package/src/modules/{workflow → version-control}/change-request-hooks.ts

@@ -9,7 +9,7 @@ export type ChangeRequestPerson = Pick<AuthUser, 'id' | 'email' | 'name'>;
 
 /**
  * A change request was OPENED — by a person in the app or by an agent through
- * its tool, which take the one road (`WorkflowService.openChangeRequest`).
+ * its tool, which take the one road (`VersionControlService.openChangeRequest`).
  * Raised once per request, after its row exists and its source branch was
  * pushed, or the push was refused: the request exists either way, and the
  * branch's next push carries the commits. Never raised for a request that is

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/approval-states.test.ts

@@ -12,7 +12,7 @@ const mergeChangeRequestMock = vi.fn(async () => ({
   mergeCommit: 'merged-sha',
 }));
 
-import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
 import { changeRequests } from '../../../database/schema.js';
 import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
@@ -182,10 +182,10 @@ function makeService(rows: ApprovalRow[], byPath: EligibilityByPath) {
     getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
   } as unknown as WorkspaceService;
   const git = { mergeChangeRequest: mergeChangeRequestMock } as unknown as GitService;
-  return new ReviewWorkflowService(makeDb(rows), makeAccessControl(byPath), workspace, git);
+  return new ChangeRequestReviewService(makeDb(rows), makeAccessControl(byPath), workspace, git);
 }
 
-describe('ReviewWorkflowService.getApprovalStates', () => {
+describe('ChangeRequestReviewService.getApprovalStates', () => {
   const HEAD = 'head-sha-1';
   const BASE = 'current-company-state';
   const ALICE_EMAIL = 'alice@bevel.software';
@@ -751,7 +751,7 @@ describe('merge gate — every file type', () => {
  * load. The unreadable case propagates (the caller fails closed, 503); any
  * other lookup failure still degrades to empty eligibility as documented.
  */
-describe('ReviewWorkflowService.getApprovalStates — unreadable access tree', () => {
+describe('ChangeRequestReviewService.getApprovalStates — unreadable access tree', () => {
   const FILES = [file({ path: 'Knowledge/Foo.md' })];
   function serviceWith(overrides: Partial<IAccessControl>) {
     const workspace = {
@@ -759,7 +759,7 @@ describe('ReviewWorkflowService.getApprovalStates — unreadable access tree', (
       getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
     } as unknown as WorkspaceService;
     const git = { mergeChangeRequest: mergeChangeRequestMock } as unknown as GitService;
-    return new ReviewWorkflowService(makeDb([]), { ...makeAccessControl({}), ...overrides }, workspace, git);
+    return new ChangeRequestReviewService(makeDb([]), { ...makeAccessControl({}), ...overrides }, workspace, git);
   }
 
   it('propagates AccessUnreadableError from the eligibility lookup', async () => {

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/cancel-pr.test.ts

@@ -1,12 +1,12 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
 import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { GitService } from '../../git/git.service.js';
 import type { IAccessControl } from '../../../access/access-control.interface.js';
 import { hashEmail } from '../../../../shared/email-identity.js';
-import { WorkflowValidationError } from '../../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../../shared/domain-errors.js';
 
 // Cancel is now a DB state flip (no `gh`): `update(change_requests) … WHERE
 // number = ? AND state = 'open'`. This spy stands in for the update's
@@ -58,14 +58,14 @@ function makeAccessControl(adminEmails: string[] = []): IAccessControl {
   };
 }
 
-function makeService(accessControl: IAccessControl): ReviewWorkflowService {
+function makeService(accessControl: IAccessControl): ChangeRequestReviewService {
   // `ensureRemotesFetched` is best-effort (catches errors); the DB stub above
   // stands in for the state-flip update + the race re-read.
   const workspace = { ensureRemotesFetched: async () => undefined } as unknown as WorkspaceService;
-  return new ReviewWorkflowService(makeDb(), accessControl, workspace, {} as unknown as GitService);
+  return new ChangeRequestReviewService(makeDb(), accessControl, workspace, {} as unknown as GitService);
 }
 
-describe('ReviewWorkflowService.cancelPr', () => {
+describe('ChangeRequestReviewService.cancelPr', () => {
   beforeEach(() => {
     updateReturning.mockClear();
     updateReturning.mockResolvedValue([{ id: 'cr-1' }]);
@@ -145,7 +145,7 @@ describe('ReviewWorkflowService.cancelPr', () => {
     for (const bad of [0, -1, 1.5, Number.NaN]) {
       await expect(
         svc.cancelPr(bad, USER, 'open', null, 'current-company-state', 'ws-1'),
-      ).rejects.toBeInstanceOf(WorkflowValidationError);
+      ).rejects.toBeInstanceOf(VersionControlValidationError);
     }
   });
 
@@ -153,10 +153,10 @@ describe('ReviewWorkflowService.cancelPr', () => {
     const svc = makeService(makeAccessControl([USER.email]));
     await expect(
       svc.cancelPr(42, USER, 'open', null, '', 'ws-1'),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
     await expect(
       svc.cancelPr(42, USER, 'open', null, 'current-company-state', ''),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
   });
 
   it('skips the admin lookup when the author check matches', async () => {

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/carry-approvals-forward.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import type { PullRequestFile } from '@bevel-software/platform-shared';
-import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
 import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
 import type { GitService } from '../../git/git.service.js';
@@ -220,7 +220,7 @@ function makeService(
       return fn(tx);
     },
   } as unknown as Database;
-  const svc = new ReviewWorkflowService(
+  const svc = new ChangeRequestReviewService(
     db,
     {} as unknown as IAccessControl,
     {} as unknown as WorkspaceService,
@@ -229,7 +229,7 @@ function makeService(
   return { svc, db, stored, selected, inserted, order, locked, lockSql };
 }
 
-describe('ReviewWorkflowService.carryApprovalsForward', () => {
+describe('ChangeRequestReviewService.carryApprovalsForward', () => {
   it('re-pins only the approvals the merge did not touch, keeping who approved and when', async () => {
     const h = makeService([
       row('Sales/Deal.md'),
@@ -355,7 +355,7 @@ describe('ReviewWorkflowService.carryApprovalsForward', () => {
  * between the copy's select and its insert stayed pinned to the head the
  * update was replacing and vanished from the request it was made on.
  */
-describe('ReviewWorkflowService.approveFile: written under the same lock', () => {
+describe('ChangeRequestReviewService.approveFile: written under the same lock', () => {
   const USER = { id: 'u1', email: 'bob@bevel.software', name: 'Bob' };
   const FILES: PullRequestFile[] = [
     {
@@ -370,7 +370,7 @@ describe('ReviewWorkflowService.approveFile: written under the same lock', () =>
   ];
 
   const approver = (h: ReturnType<typeof makeService>) =>
-    new ReviewWorkflowService(
+    new ChangeRequestReviewService(
       h.db,
       {
         canWriteAtRef: async () => true,
@@ -493,7 +493,7 @@ describe('a carried approval still counts at the new head', () => {
     const h = makeService([row('Sales/Deal.md'), row('Sales/Terms.md')]);
     await h.svc.carryApprovalsForward(PR, OLD_HEAD, NEW_HEAD, ['Sales/Deal.md']);
 
-    const reader = new ReviewWorkflowService(
+    const reader = new ChangeRequestReviewService(
       {
         select: () => ({ from: () => ({ where: () => Promise.resolve(h.stored) }) }),
       } as unknown as Database,

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/erase-approver.test.ts

@@ -1,11 +1,11 @@
 import { describe, it, expect } from 'vitest';
 import type { SQL } from 'drizzle-orm';
 import { PgDialect } from 'drizzle-orm/pg-core';
-import { ReviewWorkflowService } from '../review-workflow.service.js';
-import type { ApprovalTx } from '../review-workflow.interface.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
+import type { ApprovalTx } from '../change-request-review.interface.js';
 
 /**
- * `eraseApprover` is the review workflow's half of account erasure: the rows
+ * `eraseApprover` is the change-request review's half of account erasure: the rows
  * are this module's, the writers that race the rewrite are this module's, so
  * the lock and the statement live here and erasure only hands over its
  * transaction. This pins what that half must do with it — take the
@@ -62,11 +62,11 @@ function harness() {
   };
   // `eraseApprover` touches nothing but the transaction it is given, so the
   // service's own collaborators are never reached.
-  const svc = new ReviewWorkflowService({} as never, {} as never, {} as never, {} as never);
+  const svc = new ChangeRequestReviewService({} as never, {} as never, {} as never, {} as never);
   return { svc, tx: tx as unknown as ApprovalTx, order, locked, lockSql, sets, wheres };
 }
 
-describe('ReviewWorkflowService.eraseApprover', () => {
+describe('ChangeRequestReviewService.eraseApprover', () => {
   it('takes the every-request lock exclusively, bounded, right before the rewrite', async () => {
     const h = harness();
     await h.svc.eraseApprover(h.tx, 'bob@bevel.software', {

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/merge-gate.test.ts

@@ -1,12 +1,12 @@
 import { describe, it, expect } from 'vitest';
 import type { FileApprovalEntry, FileApprovalState, PullRequestState } from '@bevel-software/platform-shared';
-import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
 
-function makeService(): ReviewWorkflowService {
+function makeService(): ChangeRequestReviewService {
   // evaluateMergeGate is pure — it never touches the DB, access service, or
   // workspace. Constructing with `undefined as any` for unused deps keeps the
   // test focused on the gate logic and avoids pulling in fixture scaffolding.
-  return new ReviewWorkflowService(undefined as any, undefined as any, undefined as any, undefined as any);
+  return new ChangeRequestReviewService(undefined as any, undefined as any, undefined as any, undefined as any);
 }
 
 const ADMIN_ELIGIBLE = {

package/src/modules/{workflow/review-workflow → version-control/change-request-review}/__tests__/merge-records-own-commit.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, vi } from 'vitest';
 
 import { PgDialect } from 'drizzle-orm/pg-core';
 import type { SQL } from 'drizzle-orm';
-import { ReviewWorkflowService } from '../review-workflow.service.js';
+import { ChangeRequestReviewService } from '../change-request-review.service.js';
 import { changeRequests, prMergeLog } from '../../../database/schema.js';
 import type { Database } from '../../../database/connection.js';
 import type { WorkspaceService } from '../../../workspace/workspace.service.js';
@@ -159,7 +159,7 @@ function makeService(mergeResult: AppliedMergeResult) {
     ensureRemotesFetched: vi.fn(async () => undefined),
     getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
   } as unknown as WorkspaceService;
-  const svc = new ReviewWorkflowService(
+  const svc = new ChangeRequestReviewService(
     makeDb(captured),
     {} as unknown as IAccessControl,
     workspace,
@@ -268,7 +268,7 @@ function makeStuckService(
   const workspace = {
     getOrCreateForBranch: vi.fn(async () => ({ id: 'ws-base' })),
   } as unknown as WorkspaceService;
-  const svc = new ReviewWorkflowService(
+  const svc = new ChangeRequestReviewService(
     makeDb(captured, { rows, casWon, begunLog }),
     {} as unknown as IAccessControl,
     workspace,

package/src/modules/{workflow/review-workflow/review-workflow.interface.ts → version-control/change-request-review/change-request-review.interface.ts}

@@ -45,7 +45,7 @@ export interface MergeGateResult {
  * merge; everything in this interface is in-app state
  * the team uses to decide whether the merge should fire.
  */
-export interface IReviewWorkflowService {
+export interface IChangeRequestReviewService {
   /**
    * Compose the per-file approval state for a PR detail response. Resolves
    * the eligible approver set against **the PR's base branch on origin**

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

@@ -20,16 +20,16 @@ import { mergeCommitSubject } from '../git/merge-commit.js';
 import { redactSecret } from '../../../shared/redact-secret.js';
 import {
   ChangeRequestConflictsError,
-  WorkflowDomainError,
-  WorkflowValidationError,
+  VersionControlDomainError,
+  VersionControlValidationError,
 } from '../../../shared/domain-errors.js';
 import type { WorkspaceService } from '../../workspace/index.js';
 import { canonicalEmail, hashEmail } from '../../../shared/email-identity.js';
 import type {
-  IReviewWorkflowService,
+  IChangeRequestReviewService,
   MergeGateInput,
   MergeGateResult,
-} from './review-workflow.interface.js';
+} from './change-request-review.interface.js';
 import {
   APPROVAL_LOCK_TIMEOUT_MS,
   isApprovalLockTimeout,
@@ -67,7 +67,7 @@ function redactTokens(msg: string, token: string | null | undefined): string {
  * let go. Retryable BY THE CALLER, and said in words a business user can act
  * on: nothing was written, and trying again is the whole fix.
  */
-class ApprovalBusyError extends WorkflowDomainError {
+class ApprovalBusyError extends VersionControlDomainError {
   constructor() {
     super(
       'This change request is being updated right now — try that again in a moment.',
@@ -78,7 +78,7 @@ class ApprovalBusyError extends WorkflowDomainError {
   }
 }
 
-class MergeBlockedError extends WorkflowDomainError {
+class MergeBlockedError extends VersionControlDomainError {
   constructor(reasons: string[]) {
     super(`Merge gate rejected: ${reasons.join('; ') || 'unknown'}`, 422, {
       mergeBlockedReasons: reasons,
@@ -87,14 +87,14 @@ class MergeBlockedError extends WorkflowDomainError {
   }
 }
 
-class MergeExecutionError extends WorkflowDomainError {
+class MergeExecutionError extends VersionControlDomainError {
   constructor(reason: string) {
     super(`Merge failed: ${reason}`, 502);
     this.name = 'MergeExecutionError';
   }
 }
 
-class ApprovalAuthError extends WorkflowDomainError {
+class ApprovalAuthError extends VersionControlDomainError {
   constructor(reason: 'not-eligible' | 'no-eligible-approvers' | 'path-not-in-pr') {
     const { status, msg } = {
       'not-eligible':          { status: 403, msg: "You don't have write access on this file's path" },
@@ -115,7 +115,7 @@ class ApprovalAuthError extends WorkflowDomainError {
  * Signing in again makes a fresh account at the same address, and approvals
  * made then are that new person's.
  */
-class ApprovalAccountGoneError extends WorkflowDomainError {
+class ApprovalAccountGoneError extends VersionControlDomainError {
   constructor() {
     super('This account no longer exists — sign in again to approve.', 401, {
       kind: 'approval-account-erased',
@@ -124,7 +124,7 @@ class ApprovalAccountGoneError extends WorkflowDomainError {
   }
 }
 
-class BypassAuthError extends WorkflowDomainError {
+class BypassAuthError extends VersionControlDomainError {
   constructor() {
     super(
       "Only admins can merge with bypass. You need write access to roles.yaml on the base branch to skip approval warnings.",
@@ -134,7 +134,7 @@ class BypassAuthError extends WorkflowDomainError {
   }
 }
 
-class CancelStateError extends WorkflowDomainError {
+class CancelStateError extends VersionControlDomainError {
   constructor(reason: 'already-applied' | 'already-cancelled') {
     const msg =
       reason === 'already-applied'
@@ -145,7 +145,7 @@ class CancelStateError extends WorkflowDomainError {
   }
 }
 
-class CancelAuthError extends WorkflowDomainError {
+class CancelAuthError extends VersionControlDomainError {
   constructor() {
     super(
       "You can't cancel this change request — that takes being its author, an admin, " +
@@ -158,7 +158,7 @@ class CancelAuthError extends WorkflowDomainError {
 
 function assertValidPrNumber(n: number): void {
   if (!Number.isInteger(n) || n <= 0) {
-    throw new WorkflowValidationError('PR number must be a positive integer');
+    throw new VersionControlValidationError('PR number must be a positive integer');
   }
 }
 
@@ -236,13 +236,13 @@ function evaluateGateParts(input: MergeGateInput): { hardReasons: string[]; warn
 
 function assertValidPath(p: unknown): asserts p is string | undefined {
   if (p === undefined || p === null) return;
-  if (typeof p !== 'string') throw new WorkflowValidationError('path must be a string');
-  if (!p) throw new WorkflowValidationError('path, if provided, must be non-empty');
-  if (p.length > 4096) throw new WorkflowValidationError('path exceeds 4096 character limit');
-  if (p.includes('\0')) throw new WorkflowValidationError('path contains NUL');
+  if (typeof p !== 'string') throw new VersionControlValidationError('path must be a string');
+  if (!p) throw new VersionControlValidationError('path, if provided, must be non-empty');
+  if (p.length > 4096) throw new VersionControlValidationError('path exceeds 4096 character limit');
+  if (p.includes('\0')) throw new VersionControlValidationError('path contains NUL');
 }
 
-export class ReviewWorkflowService implements IReviewWorkflowService {
+export class ChangeRequestReviewService implements IChangeRequestReviewService {
   constructor(
     private readonly db: Database,
     private readonly accessControl: IAccessControl,
@@ -394,8 +394,8 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
   ): Promise<FileApprovalState[]> {
     assertValidPrNumber(prNumber);
     assertValidPath(path);
-    if (!headSha) throw new WorkflowValidationError('head sha is required');
-    if (!baseBranch) throw new WorkflowValidationError('base branch is required');
+    if (!headSha) throw new VersionControlValidationError('head sha is required');
+    if (!baseBranch) throw new VersionControlValidationError('base branch is required');
 
     if (!files.some((f) => f.path === path)) {
       throw new ApprovalAuthError('path-not-in-pr');
@@ -513,9 +513,9 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     opts: { bypass?: boolean } = {},
   ): Promise<MergePrResult> {
     assertValidPrNumber(prNumber);
-    if (!headSha) throw new WorkflowValidationError('head sha is required');
-    if (!baseBranch) throw new WorkflowValidationError('base branch is required');
-    if (!workspaceId) throw new WorkflowValidationError('workspace id is required');
+    if (!headSha) throw new VersionControlValidationError('head sha is required');
+    if (!baseBranch) throw new VersionControlValidationError('base branch is required');
+    if (!workspaceId) throw new VersionControlValidationError('workspace id is required');
 
     // Server-side re-validation — never trust the frontend's cached gate.
     // Hard blocks always refuse. Missing approvals refuse unless the caller
@@ -562,7 +562,7 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
       .from(changeRequests)
       .where(eq(changeRequests.number, prNumber))
       .limit(1);
-    if (!cr) throw new WorkflowValidationError(`Change request #${prNumber} not found`);
+    if (!cr) throw new VersionControlValidationError(`Change request #${prNumber} not found`);
     // Re-validate lifecycle against the AUTHORITATIVE row, not the caller's
     // `state` (which only drove the gate). A stale or duplicate request must not
     // re-run the git merge on a CR that's already merged or closed.
@@ -837,8 +837,8 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
     workspaceId: string,
   ): Promise<CancelPrResult> {
     assertValidPrNumber(prNumber);
-    if (!baseBranch) throw new WorkflowValidationError('base branch is required');
-    if (!workspaceId) throw new WorkflowValidationError('workspace id is required');
+    if (!baseBranch) throw new VersionControlValidationError('base branch is required');
+    if (!workspaceId) throw new VersionControlValidationError('workspace id is required');
 
     // Refuse early on terminal states so the gh call only fires for genuinely
     // open PRs. Two distinct 422s — frontend distinguishes "already applied"
@@ -938,7 +938,7 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
   ): Promise<number> {
     assertValidPrNumber(prNumber);
     if (!fromHeadSha || !toHeadSha) {
-      throw new WorkflowValidationError('both head shas are required');
+      throw new VersionControlValidationError('both head shas are required');
     }
     if (fromHeadSha === toHeadSha) return 0;
 
@@ -1023,7 +1023,7 @@ export class ReviewWorkflowService implements IReviewWorkflowService {
   ): Promise<FileApprovalState[]> {
     assertValidPrNumber(prNumber);
     assertValidPath(path);
-    if (!headSha) throw new WorkflowValidationError('head sha is required');
+    if (!headSha) throw new VersionControlValidationError('head sha is required');
 
     const callerEmail = canonicalEmail(user.email);