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

package/src/modules/access/access-requests.routes.ts

@@ -1,5 +1,5 @@
 import express from 'express';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
@@ -48,15 +48,15 @@ export function createAccessRequestRoutes(deps: {
   accessControl: IAccessControl;
   workspaceService: WorkspaceService;
   authService: AuthService;
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   lifecycle: IAccessRequestLifecycle;
   kb: KbContext;
 }): express.Router {
-  const { accessControl, workspaceService, authService, workflow, lifecycle, kb } = deps;
+  const { accessControl, workspaceService, authService, versionControl, lifecycle, kb } = deps;
   const { kbDirName } = kb;
   const router = express.Router({ mergeParams: true });
   const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
-  const requests = new AccessRequestsService({ workflow, workspaceService, lifecycle, kb });
+  const requests = new AccessRequestsService({ versionControl, workspaceService, lifecycle, kb });
 
   async function requireUser(
     req: express.Request,
@@ -228,7 +228,7 @@ export function createAccessRequestRoutes(deps: {
         res.json({ requests: [] });
         return;
       }
-      const crs = await workflow.listChangeRequests();
+      const crs = await versionControl.listChangeRequests();
       const rows = await lifecycle.list(target.path, target, crs, user);
       // The note is the request's own column, read back per request.
       // Bounded by the open requests on ONE item — a handful at most — and a
@@ -236,7 +236,7 @@ export function createAccessRequestRoutes(deps: {
       // belongs to.
       const withNotes = await Promise.all(
         rows.map(async (row) => {
-          const detail = await workflow
+          const detail = await versionControl
             .getChangeRequestDetail(row.number, { patches: false })
             .catch(() => null);
           const note = detail?.accessRequest?.note;
@@ -265,7 +265,7 @@ export function createAccessRequestRoutes(deps: {
         res.status(400).json({ error: 'Invalid change request number' });
         return;
       }
-      const cr = await workflow.getChangeRequest(number);
+      const cr = await versionControl.getChangeRequest(number);
       if (!cr) {
         res.status(404).json({ error: 'Not found' });
         return;

package/src/modules/access/access-requests.service.ts

@@ -2,7 +2,7 @@ import path from 'node:path';
 import {
   joinBranchFor,
   type AuthUser,
-  type IWorkflowService,
+  type IVersionControlService,
 } from '@bevel-software/platform-shared';
 import {
   ChangeRequestConflictsError,
@@ -78,7 +78,7 @@ export function escapeMarkdown(text: string): string {
 export class AccessRequestsService {
   constructor(
     private readonly deps: {
-      workflow: IWorkflowService;
+      versionControl: IVersionControlService;
       workspaceService: WorkspaceService;
       lifecycle: IAccessRequestLifecycle;
       kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId' | 'kbDirName'>;
@@ -103,7 +103,7 @@ export class AccessRequestsService {
   }): Promise<{ number: number; level: RequestLevel }> {
     const { user, target, itemName, level } = input;
     const note = (input.note ?? '').trim();
-    const { workflow, workspaceService, kb } = this.deps;
+    const { versionControl, workspaceService, kb } = this.deps;
     const wsId = kb.defaultWorkspaceId();
     const branch = this.branchFor(user.email, target);
 
@@ -113,7 +113,7 @@ export class AccessRequestsService {
     // it is recut below. The branch name already carries the person, so
     // matching it is matching them.
     const openOnBranch = async () =>
-      (await workflow.listChangeRequests({ fresh: true })).find(
+      (await versionControl.listChangeRequests({ fresh: true })).find(
         (cr) => cr.state === 'open' && cr.branch === branch,
       );
     const existing = await openOnBranch();
@@ -124,7 +124,7 @@ export class AccessRequestsService {
     // got there first, and a message is not a contract. STRICT: the list
     // proves absence, and a listing that could not fetch proves nothing.
     const branchExists = async () =>
-      (await workflow.listBranches(wsId, { freshFetch: true, strictFetch: true })).some(
+      (await versionControl.listBranches(wsId, { freshFetch: true, strictFetch: true })).some(
         (b) => b.name === branch,
       );
     // A branch still standing here belonged to an ANSWERED request: it holds a
@@ -144,7 +144,7 @@ export class AccessRequestsService {
     let present = await branchExists();
     if (present) {
       try {
-        await workflow.deleteBranch(wsId, branch, user);
+        await versionControl.deleteBranch(wsId, branch, user);
         // A delete that RETURNED is proof enough; re-probing here would let a
         // ref list that has not caught up talk us out of cutting the branch we
         // just removed, and the proposal would have nowhere to go.
@@ -165,7 +165,7 @@ export class AccessRequestsService {
     }
     if (!present) {
       try {
-        await workflow.createBranch(wsId, branch, kb.defaultBranch);
+        await versionControl.createBranch(wsId, branch, kb.defaultBranch);
       } catch (err) {
         if (!(await branchExists())) throw err;
       }
@@ -195,7 +195,7 @@ export class AccessRequestsService {
       });
     if (onBranch !== spliced.text) {
       await workspaceService.writeFile(ws.id, wsRulesPath, spliced.text);
-      await workflow.commitChanges(
+      await versionControl.commitChanges(
         ws.id,
         user,
         `Request ${LEVEL_LABEL[level].toLowerCase()} access to ${itemName}`,
@@ -206,7 +206,7 @@ export class AccessRequestsService {
       // The level and the note are the request's own columns — what the
       // dialog and the editors' banner read back. The description is for the
       // people who read the request, and says the same things in prose.
-      const detail = await workflow.openChangeRequest(ws.id, user, {
+      const detail = await versionControl.openChangeRequest(ws.id, user, {
         sourceBranch: branch,
         targetBranch: kb.defaultBranch,
         title: `Access request: ${itemName}`,
@@ -260,10 +260,10 @@ export class AccessRequestsService {
    *                 claiming a refusal nobody made.
    */
   async status(user: AuthUser, target: AccessRequestTarget): Promise<AccessRequestStatus> {
-    const { workflow } = this.deps;
+    const { versionControl } = this.deps;
     const branch = this.branchFor(user.email, target);
 
-    const open = (await workflow.listChangeRequests({ fresh: true })).find(
+    const open = (await versionControl.listChangeRequests({ fresh: true })).find(
       (cr) => cr.state === 'open' && cr.branch === branch,
     );
     if (open) {
@@ -272,7 +272,7 @@ export class AccessRequestsService {
 
     const level = await this.levelAskedOn(branch, target, user.email);
     if (!level) return { state: 'none' };
-    const last = await workflow.latestClosedChangeRequest(user.email, branch);
+    const last = await versionControl.latestClosedChangeRequest(user.email, branch);
     return last ? { state: 'not-accepted', level, number: last.number } : { state: 'none' };
   }
 
@@ -288,7 +288,7 @@ export class AccessRequestsService {
    * for, and Can edit is the lesser claim.
    */
   private async levelOf(number: number): Promise<RequestLevel> {
-    const detail = await this.deps.workflow
+    const detail = await this.deps.versionControl
       .getChangeRequestDetail(number, { patches: false })
       .catch(() => null);
     return detail?.accessRequest?.level ?? 'write';

package/src/modules/access/access.routes.ts

@@ -22,8 +22,8 @@ import type { KbContext } from '../../shared/kb-context.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { AuthService, IAccountSwitchGuard } from '../auth/index.js';
-import type { WorkflowService, WorkflowEventBus } from '../workflow/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlService, VersionControlEventBus } from '../version-control/index.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { AccessDeniedError } from '../access-model/index.js';
 import {
   AccessMutationService,
@@ -90,8 +90,8 @@ export function createAccessRoutes(
   authService: AuthService,
   /** Auth's switch-off coordination, for the invite's promotion (`ifActive`). */
   switchGuard: IAccountSwitchGuard,
-  workflowService: WorkflowService,
-  eventBus: WorkflowEventBus,
+  versionControlService: VersionControlService,
+  eventBus: VersionControlEventBus,
   db: Database,
   kb: KbContext,
   /** The composition root's walk, for the roles admin's reference scan. */
@@ -104,7 +104,7 @@ export function createAccessRoutes(
   const mutation = new AccessMutationService(workspaceService, accessControl, kbDirName);
   const rolesAdmin = new RolesAdminService(
     workspaceService,
-    workflowService,
+    versionControlService,
     accessControl,
     disk,
     kbDirName,
@@ -414,9 +414,20 @@ export function createAccessRoutes(
    * nothing is moved.
    *
    * Gated like the sibling `overrides` route rather than the permissive
-   * `GET /access`: the caller must resolve read on the thing being moved. The
-   * lists name people, and someone who cannot see it has no business
-   * learning who can.
+   * `GET /access`: the caller must resolve read on the thing being moved AND
+   * on the destination folder. The lists name people, and someone who cannot
+   * see a thing has no business learning who can; the `after` lists and the
+   * `changes` are the destination folder's rules read back (whom it grants,
+   * whom it denies by name), so a folder the caller may not open tells them
+   * nothing either.
+   *
+   * `changes` is who loses and who gains `read` or `write` in the move, as the
+   * resolver judges each candidate on both sides
+   * (`prospectiveHolderChanges`) — the one answer the move dialog and the
+   * agent's `move_file` both show. The two lists are not that answer: they
+   * name grants, so a writer leaving a folder everyone reads shows as losing
+   * `read` it keeps, and a person the destination denies by name is on
+   * neither list.
    */
   router.get('/workspace/:id/access/prospective', async (req, res) => {
     const user = await requireUser(req, res);
@@ -445,13 +456,21 @@ export function createAccessRoutes(
         res.status(403).json({ error: 'You do not have access to this file.' });
         return;
       }
+      if (!(await accessControl.canRead(req.params.id, user.email, toDir))) {
+        res.status(403).json({ error: 'You do not have access to this folder.' });
+        return;
+      }
 
       const name = from.slice(from.lastIndexOf('/') + 1);
       const to = toDir ? `${toDir}/${name}` : name;
-      const { before, after } = await accessControl.prospectiveHolders(req.params.id, from, to);
+      const [{ before, after }, changes] = await Promise.all([
+        accessControl.prospectiveHolders(req.params.id, from, to),
+        accessControl.prospectiveHolderChanges(req.params.id, from, to),
+      ]);
       res.json({
         before: { read: holderPrincipals(before.read), write: holderPrincipals(before.write) },
         after: { read: holderPrincipals(after.read), write: holderPrincipals(after.write) },
+        changes,
       });
     } catch (err) {
       const { status, body } = toHttpError(err);
@@ -859,7 +878,7 @@ export function createAccessRoutes(
     user: AuthUser,
     op: () => Promise<void>,
   ): Promise<void> {
-    const existing = await workflowService.getLock(workspaceId, branch, wsEditPath);
+    const existing = await versionControlService.getLock(workspaceId, branch, wsEditPath);
     if (existing && existing.holderUserId === user.id) {
       // Caller already holds the lock (mid-edit) — write without touching it.
       await op();
@@ -875,7 +894,7 @@ export function createAccessRoutes(
       eventBus.emit({ kind: 'fs-tree-changed', workspaceId, branch });
       return;
     }
-    const acquired = await workflowService.acquireLock(workspaceId, branch, wsEditPath, user);
+    const acquired = await versionControlService.acquireLock(workspaceId, branch, wsEditPath, user);
     if (!acquired.acquired) {
       const holder = acquired.lock.holderName || 'another user';
       const err: Error & { status?: number } = new Error(
@@ -894,16 +913,16 @@ export function createAccessRoutes(
         // upload. Every other failure may have left partial bytes, so it keeps
         // the discarding release.
         if (isFolderGovernsRefusal(err)) {
-          await workflowService.releaseLockUntouched(workspaceId, branch, wsEditPath, user);
+          await versionControlService.releaseLockUntouched(workspaceId, branch, wsEditPath, user);
         } else {
-          await workflowService.releaseLockNoCommit(workspaceId, branch, wsEditPath, user);
+          await versionControlService.releaseLockNoCommit(workspaceId, branch, wsEditPath, user);
         }
       } catch {
         /* best-effort */
       }
       throw err;
     }
-    await workflowService.releaseLock(workspaceId, branch, wsEditPath, user);
+    await versionControlService.releaseLock(workspaceId, branch, wsEditPath, user);
     eventBus.emit({ kind: 'fs-tree-changed', workspaceId, branch });
   }
 
@@ -1219,7 +1238,7 @@ export function createAccessRoutes(
       if (err instanceof AccessDeniedError || err instanceof AccessMutationError) {
         logger('access.revoke.denied').warn(
           `ws=${workspaceId} byUserId=${user.id} -> ${
-            err instanceof WorkflowDomainError ? err.status : 500
+            err instanceof VersionControlDomainError ? err.status : 500
           }`,
         );
       }

package/src/modules/access/admin-locked-commit.ts

@@ -49,19 +49,19 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 import { type WriteValidator, LockingFilesystem } from '../kb-fs/index.js';
-import type { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
 
 export interface LockedCommitDeps {
   workspaceService: IWorkspaceService;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   kbDirName: string;
   /** Live-binding thunk — DEFAULT_BRANCH stays empty until setup. */
   defaultBranchOf: () => string;
   /** Domain-error constructor (RolesAdminError / GroupsAdminError). */
-  makeError: (message: string, status: number, payload?: Record<string, unknown>) => WorkflowDomainError;
+  makeError: (message: string, status: number, payload?: Record<string, unknown>) => VersionControlDomainError;
   /** Log prefix, e.g. 'roles-admin' / 'groups-admin'. */
   logTag: string;
   /** Contention wording: what is "being edited by <holder>". */
@@ -133,7 +133,7 @@ export class AdminLockedCommits {
     return new LockingFilesystem(
       { basePath, contained: true },
       {
-        workflow: this.deps.workflowService,
+        versionControl: this.deps.versionControlService,
         workspaceId,
         branch: this.defaultBranch,
         user: actor,
@@ -171,7 +171,7 @@ export class AdminLockedCommits {
    * module doc for the release semantics.
    *
    * `opts.coordinationFiles` names files locked ONLY to serialize with their
-   * writer — `fn` never writes them. They're acquired with the workflow
+   * writer — `fn` never writes them. They're acquired with the version-control
    * service's coordination flag (a pure mutex that skips the per-path write
    * gate — required for machine-owned files like `synced-groups.yaml`, which
    * a human actor may not, and need not, write) and always released with
@@ -197,7 +197,7 @@ export class AdminLockedCommits {
     let unrestored: Set<string> | null = null;
     try {
       for (const p of paths) {
-        const res = await this.deps.workflowService.acquireLock(
+        const res = await this.deps.versionControlService.acquireLock(
           workspaceId,
           this.defaultBranch,
           p,
@@ -248,13 +248,13 @@ export class AdminLockedCommits {
             // pointless commit whose enqueue failure strands a known-clean
             // lock until TTL. Or known-partial bytes (restore failed —
             // discarding to HEAD beats committing them).
-            await this.deps.workflowService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
+            await this.deps.versionControlService.releaseLockNoCommit(workspaceId, this.defaultBranch, h, actor);
           } else {
             // Push-retry (the enqueued commit retries the share), the
             // restored-failure path, and any held path the batch never
             // committed (commit-on-release: a prior holder's still-queued
             // work must be preserved, never discarded).
-            await this.deps.workflowService.releaseLock(workspaceId, this.defaultBranch, h, actor);
+            await this.deps.versionControlService.releaseLock(workspaceId, this.defaultBranch, h, actor);
           }
         } catch (releaseErr) {
           logger(this.deps.logTag).warn(
@@ -278,7 +278,7 @@ export class AdminLockedCommits {
     files: LockedWrite[],
     summary: string,
   ): Promise<void> {
-    const { workspaceService, workflowService, logTag } = this.deps;
+    const { workspaceService, versionControlService, logTag } = this.deps;
     try {
       for (const f of files) {
         if (f.content === null) {
@@ -293,7 +293,7 @@ export class AdminLockedCommits {
           await workspaceService.writeFile(workspaceId, this.wsRel(f.repoRel), f.content);
         }
       }
-      await workflowService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
+      await versionControlService.commitChanges(workspaceId, actor, summary, files.map((f) => this.wsRel(f.repoRel)));
       // Commit landed AND pushed — the tree at these paths is clean. Mark
       // them so withFileLocks releases them WITHOUT enqueueing a release
       // commit (see the module doc — an enqueue failure would strand the

package/src/modules/access/admin-route-helpers.ts

@@ -3,7 +3,7 @@
  * groups-admin.routes) — one error shape, one input-coercion rule, so the two
  * surfaces can't drift apart again.
  *
- * Error shape: a sub-500 `WorkflowDomainError` renders as its own status +
+ * Error shape: a sub-500 `VersionControlDomainError` renders as its own status +
  * message + payload; everything else — a raw error OR a 500-status domain
  * error (e.g. AccessMutationService wraps unexpected raw errors in a 500
  * AccessMutationError, message included) — is an INTERNAL error: logged
@@ -14,7 +14,7 @@
 
 import type express from 'express';
 import { logger } from '../../shared/logging.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 
 /** One error shape for every access-family route. */
@@ -22,11 +22,11 @@ export function toHttpError(
   err: unknown,
   logTag: string,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError && err.status < 500) {
+  if (err instanceof VersionControlDomainError && err.status < 500) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   logger(logTag).error('route failure:', { err });
-  const status = err instanceof WorkflowDomainError ? err.status : 500;
+  const status = err instanceof VersionControlDomainError ? err.status : 500;
   return { status, body: { error: 'Internal error.' } };
 }
 
@@ -49,7 +49,7 @@ export function requireNonEmptyString(
   opts?: { trim?: boolean },
 ): string {
   if (typeof value !== 'string' || value.trim() === '') {
-    throw new WorkflowDomainError(`${field} must be a non-empty string`, 400);
+    throw new VersionControlDomainError(`${field} must be a non-empty string`, 400);
   }
   return opts?.trim ? value.trim() : value;
 }

package/src/modules/access/change-read-gate.ts

@@ -1,6 +1,6 @@
 /**
  * Read-before-write: the gate every change passes on its way to the lock
- * (`WorkflowService.acquireLock`), on every branch. Contract and rationale in
+ * (`VersionControlService.acquireLock`), on every branch. Contract and rationale in
  * `access-model/change-gate.ts`; this is the service that answers.
  *
  * The verdict is taken against the WORKING TREE, not `HEAD` as the write gate

package/src/modules/access/groups-admin.service.ts

@@ -28,9 +28,9 @@
  */
 
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -63,7 +63,7 @@ const ROLES_YAML = 'roles.yaml';
 
 /** A group mutation that cannot proceed. `payload.kind` distinguishes the
  *  mode refusal (`'idp-mode'`) for the UI. */
-export class GroupsAdminError extends WorkflowDomainError {
+export class GroupsAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'GroupsAdminError';
@@ -118,18 +118,18 @@ export class GroupsAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
     private readonly kbDirName: string,
     /** Live-binding thunk — see RolesAdminService's identical note. */
     private readonly defaultBranchOf: () => string,
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new GroupsAdminError(message, status, payload),

package/src/modules/access/index.ts

@@ -5,7 +5,7 @@
  */
 export type { IAccessControl } from './access-control.interface.js';
 // Reached by other modules; exported here so they stop importing the files.
-export type { AccessDecisionSource, AccessTargetKind } from './access-control.interface.js';
+export type { AccessDecisionSource, AccessTargetKind, HolderChange, HolderChanges } from './access-control.interface.js';
 export { accessMdPathForFolder, fileCarriesAccessRules, governingFolderOf } from './access-mutation.service.js';
 export type { AccessMutationService, IAccessMutation, TargetKind } from './access-mutation.service.js';
 export { folderTarget, rulesFileFor } from './access-requests.contract.js';

package/src/modules/access/reference-scan.ts

@@ -507,7 +507,7 @@ export function readableReferences(
 const SCAN_TTL_MS = 30_000;
 
 /**
- * The slice of the workflow event bus the scanner taps for cache
+ * The slice of the version-control event bus the scanner taps for cache
  * invalidation. Structural (not the concrete class) so test doubles and the
  * services' optional bus stay compatible.
  */

package/src/modules/access/roles-admin.service.ts

@@ -36,9 +36,9 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('roles.recover');
-import type { WorkflowEventBus } from '../workflow/index.js';
-import type { AuthUser, IWorkspaceService, IWorkflowService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
+import type { AuthUser, IWorkspaceService, IVersionControlService } from '@bevel-software/platform-shared';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import type { ITreeWalker } from '../../shared/fs.contract.js';
 import type { IAccessControl } from './access-control.interface.js';
 import {
@@ -77,7 +77,7 @@ import { AdminLockedCommits } from './admin-locked-commit.js';
 import { KbReferenceScanner, readableReferences } from './reference-scan.js';
 
 /** A mutation that cannot proceed (invariant violation, contention, not found). */
-export class RolesAdminError extends WorkflowDomainError {
+export class RolesAdminError extends VersionControlDomainError {
   constructor(message: string, status = 422, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'RolesAdminError';
@@ -185,7 +185,7 @@ export class RolesAdminService {
 
   constructor(
     private readonly workspaceService: IWorkspaceService,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly accessControl: IAccessControl,
     /** The composition root's walk — the one the resolver finds access rules with. */
     disk: ITreeWalker,
@@ -205,7 +205,7 @@ export class RolesAdminService {
      * a roles.yaml / access.md change is an access change, and without this an
      * open tab keeps a now-stale read verdict until a manual reload.
      */
-    private readonly eventBus?: WorkflowEventBus,
+    private readonly eventBus?: VersionControlEventBus,
     /**
      * This deployment's configured admins (`ADMIN_EMAIL`) — the same list the
      * resolver treats as `deploymentOwners`, so it serves two purposes here:
@@ -218,7 +218,7 @@ export class RolesAdminService {
   ) {
     this.locked = new AdminLockedCommits({
       workspaceService,
-      workflowService,
+      versionControlService,
       kbDirName,
       defaultBranchOf,
       makeError: (message, status, payload) => new RolesAdminError(message, status, payload),
@@ -293,7 +293,7 @@ export class RolesAdminService {
    * error is status-less and would surface as 500).
    */
   private async assertRolesUnlocked(workspaceId: string, actor: AuthUser): Promise<void> {
-    const held = await this.workflowService.getLock(
+    const held = await this.versionControlService.getLock(
       workspaceId,
       this.defaultBranch,
       `${this.kbDirName}/${ROLES_YAML}`,
@@ -422,7 +422,7 @@ export class RolesAdminService {
     // the fix never reaches it). Best-effort: if origin is unreachable we fall
     // back to the local state and still attempt the local fix.
     try {
-      await this.workflowService.resetToRemote(workspaceId, this.defaultBranch);
+      await this.versionControlService.resetToRemote(workspaceId, this.defaultBranch);
       this.accessControl.invalidate(workspaceId);
     } catch (err) {
       log.warn('could not sync with origin before recovery; proceeding with local state:', { err });

package/src/modules/access/synced-groups-committer.ts

@@ -2,14 +2,14 @@ import path from 'node:path';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('directory-sync');
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { AccessControlService } from './access-control.service.js';
 import { SYNCED_GROUPS_YAML } from '../access-model/index.js';
-import type { WorkflowEventBus } from '../workflow/index.js';
+import type { VersionControlEventBus } from '../version-control/index.js';
 import { LockingFilesystem } from '../kb-fs/index.js';
-import { PushNeedsAgentResolutionError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError, VersionControlDomainError } from '../../shared/domain-errors.js';
 import { isAbsence } from '../../shared/fs.contract.js';
 import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
 
@@ -27,9 +27,9 @@ import type { SyncedGroupsWriterDeps } from './synced-groups-writer.js';
  */
 export function createSyncedGroupsCommitter(deps: {
   workspaceService: WorkspaceService;
-  workflowService: IWorkflowService;
+  versionControlService: IVersionControlService;
   accessControl: AccessControlService;
-  eventBus: WorkflowEventBus;
+  eventBus: VersionControlEventBus;
   kbDirName: string;
   bot: AuthUser;
   /** Thunk — DEFAULT_BRANCH is a live binding that stays empty until setup. */
@@ -37,7 +37,7 @@ export function createSyncedGroupsCommitter(deps: {
 }): Pick<SyncedGroupsWriterDeps, 'readCurrent' | 'persist' | 'onWritten'> {
   const {
     workspaceService,
-    workflowService,
+    versionControlService,
     accessControl,
     eventBus,
     kbDirName,
@@ -77,7 +77,7 @@ export function createSyncedGroupsCommitter(deps: {
       // roles admin's atomic writes use.
       const fsys = new LockingFilesystem(
         { basePath, contained: true },
-        { workflow: workflowService, workspaceId, branch, user: bot, kbDirName },
+        { versionControl: versionControlService, workspaceId, branch, user: bot, kbDirName },
       );
       try {
         await fsys.writeFiles(
@@ -115,19 +115,19 @@ export function createSyncedGroupsCommitter(deps: {
           // an operator (or any later write on the branch) pushes it.
           let armed = false;
           try {
-            await workflowService.releaseLock(workspaceId, branch, wsRelPath, bot);
+            await versionControlService.releaseLock(workspaceId, branch, wsRelPath, bot);
             armed = true;
           } catch (armErr) {
             const lockAlreadyReleased =
-              armErr instanceof WorkflowDomainError && armErr.payload?.kind === 'lock-not-held';
+              armErr instanceof VersionControlDomainError && armErr.payload?.kind === 'lock-not-held';
             if (lockAlreadyReleased) {
               try {
-                armed = await workflowService.hasQueuedCommit(workspaceId, branch, wsRelPath);
+                armed = await versionControlService.hasQueuedCommit(workspaceId, branch, wsRelPath);
                 if (!armed) {
                   // The row may already be gone because the worker WON the
                   // race: drained it and pushed. A branch with nothing left
                   // unpushed cannot be holding our landed commit hostage.
-                  armed = !(await workflowService.hasUnpushedCommits(workspaceId));
+                  armed = !(await versionControlService.hasUnpushedCommits(workspaceId));
                 }
               } catch (queueErr) {
                 log.warn('could not verify the pending-commit queue:', { err: queueErr });