@bevel-software/platform-core-backend 0.34.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,16 +272,17 @@ 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)),
     }),
   });
 
   mount({
     name: 'commit_change',
     description:
-      'Save the currently-pending file edits as a new change on the current branch. Each change ' +
-      'must affect exactly one file — if multiple files are dirty, returns a structured error ' +
-      'listing them; commit them one at a time. Refused on protected branches without write permission.',
+      'Commit, as you, the one file left uncommitted on `branch`, without sharing it. Writes commit and share ' +
+      'on their own moments later (`branch_status` lists those still landing); `unzip` leaves its files uncommitted. ' +
+      'If several files are uncommitted, returns a structured error listing them; commit them one at a time. ' +
+      'Refused on protected branches without write permission.',
     inputs: {
       type: 'object',
       properties: {
@@ -298,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,
       }),
@@ -309,7 +310,7 @@ export function registerWorkflowTools(
     name: 'save_file',
     description:
       'Schedule the file at <path> for commit + push using whatever bytes are on disk (no content ' +
-      'rewrite) — for binary uploads or files left uncommitted. On lock contention returns ' +
+      'rewrite) — for files left uncommitted, such as those `unzip` extracts. On lock contention returns ' +
       '`{ saved: false, reason }` rather than throwing. The commit lands asynchronously.',
     inputs: {
       type: 'object',
@@ -345,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 };
     },
   });
@@ -357,8 +358,9 @@ export function registerWorkflowTools(
   mount({
     name: 'share_current_branch',
     description:
-      'Publish the current branch to the shared remote so teammates and any change request pick up ' +
-      'your commits. No arguments. Refused on protected branches without write permission.',
+      'Publish `branch` to the shared remote so teammates and any change request pick up its commits. ' +
+      'Writes already share on their own: this is for sharing again after a refused push (`branch_status` shows ' +
+      'the branch ahead). Refused on protected branches without write permission.',
     inputs: { type: 'object', properties: {}, additionalProperties: false },
     outputs: {
       type: 'object',
@@ -367,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 };
     },
   });
@@ -377,10 +379,11 @@ export function registerWorkflowTools(
     description:
       'Create a new unprotected draft named `name`, forked from the existing branch `branch`. The ' +
       `backend rejects protected names (${protectedInline(kb)}) and filesystem-invalid names — surface ` +
-      'those errors verbatim. Convention: `<email-localpart>/<kebab-slug>`. Does NOT switch the ' +
-      'agent onto the new draft.',
+      'those errors verbatim. Name it `<you>/<kebab-slug>`: `<you>` is the person\'s email before the @, in lower case, ' +
+      'with each run of characters other than letters and digits as one `-` (`paul.brandt@` gives `paul-brandt/`). ' +
+      'Only that prefix makes the draft theirs, to delete later. Does NOT switch the agent onto the new draft.',
     // `branch` here is the fork BASE — its own meaning — so skip the generic
-    // workspace-`branch` injection ("the branch you are currently working on"),
+    // workspace-`branch` injection ("the branch to work on: ... or your draft"),
     // whose wording invites filling in the draft being created instead.
     skipBranch: true,
     // The handler refuses a missing `name` with a message that says what the
@@ -389,7 +392,7 @@ export function registerWorkflowTools(
     inputs: {
       type: 'object',
       properties: {
-        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<email-localpart>/<kebab-slug>` for user drafts). Must not exist yet.' },
+        name: { type: 'string', minLength: 1, description: 'Name of the draft to create (`<you>/<kebab-slug>` for user drafts, as the description says). Must not exist yet.' },
         branch: { type: 'string', minLength: 1, description: 'Existing branch to fork the new draft from — usually the branch you are currently on.' },
       },
       required: ['name', 'branch'],
@@ -427,7 +430,7 @@ export function registerWorkflowTools(
         );
       }
       return {
-        branch: await ctx.workflowService.createBranch(workspaceIdForBranch(base), name),
+        branch: await ctx.versionControlService.createBranch(workspaceIdForBranch(base), name),
       };
     },
   });
@@ -437,7 +440,7 @@ export function registerWorkflowTools(
     description:
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
-      '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      '`change-request-conflicts` error with affected paths. ' +
       'Answers a SUMMARY, not the request\'s content: `url` first (hand it to the user), then `number`, ' +
       '`title`, `state`, `sourceBranch`, `targetBranch`, `approvals` (who must approve each file), ' +
       '`mergeBlockedReasons` (what blocks the merge), and `files` — the changed paths with their kind of ' +
@@ -475,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,
@@ -533,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,
@@ -549,12 +552,13 @@ export function registerWorkflowTools(
     name: 'merge_branch',
     description:
       'Merge branch `source` into branch `target` as you, and publish `target`. An agent proposes and syncs; ' +
-      'a person merges: this tool never lands a change request. It refuses while a change request from `source` ' +
+      'a person merges: this never lands a change request. It refuses while a change request from `source` ' +
       'into `target` is open (naming it): ask the user to review it in the app. It refuses ' +
-      'when `target` is a protected branch unless you could commit every changed file directly to it. ' +
+      'when `target` is a protected branch unless you could commit every changed file directly to it (never ' +
+      'for a change to `roles.yaml`). ' +
       'SYNC: merging the target into your draft (`source` = the change request\'s target, `target` = your draft) ' +
       'is always allowed, even with the draft\'s request open. ' +
-      'Writes are committed asynchronously; the merge first waits up to 20s for those on `source`. ' +
+      'Writes are committed asynchronously; it waits up to 20s for those on `source`. ' +
       'Returns `merged` with the merge commit; `nothing-to-merge` with `target`\'s tip when it already holds ' +
       'all of `source`; `pending-commits` (nothing merged) when writes are still committing — retry shortly — ' +
       'or one failed (`needsAttention`: tell the user); or `conflicts-need-resolution` with the conflicting ' +
@@ -610,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) };
     },
   });
 
@@ -618,7 +622,7 @@ export function registerWorkflowTools(
     name: 'delete_branch',
     description:
       'Delete branch `name` from the shared repository and the server. Allowed for the ' +
-      'branch\'s author (`<email-localpart>/…`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
+      'branch\'s author (`<you>/…` per `create_branch`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
       'protected branch, a name that is not a branch, a branch with saves still landing or a file held ' +
       '(retry once they land). An open change request from or into it that proposes nothing is closed and the ' +
       'delete goes ahead; one that still proposes something refuses it, naming and linking it: its author ' +
@@ -681,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),
@@ -730,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);
@@ -753,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. */
@@ -825,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 };
     },
   });
@@ -836,13 +840,13 @@ export function registerWorkflowTools(
       'One file as it was at a point in history: `at` is a commit (from `list_file_changes`, on `branch`\'s ' +
       'own history) or the name of another branch (its published tip). Answers `content` (null when the ' +
       'file was not there) and `sha`, the commit it was read at; for a commit, also `before`, the file ' +
-      'just before that commit. To put an earlier version back, write it with `write_file`. Takes the read ' +
-      'the file takes at that point.',
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes your ' +
+      'read of the file on `branch` now and, for a branch, also at its tip.',
     inputs: {
       type: 'object',
       properties: {
         path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
-        at: { type: 'string', minLength: 1, description: 'A commit sha, or a branch name.' },
+        at: { type: 'string', minLength: 1, description: 'A full commit sha (40 or 64 hex characters), or a branch name.' },
         sessionId: SESSION_ID_INPUT,
       },
       required: ['path', 'at'],
@@ -872,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 };
     },
   });
@@ -922,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);
       });
@@ -982,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;
@@ -995,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));
@@ -1173,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**