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

package/src/modules/access/__tests__/roles-capabilities.test.ts

@@ -5,7 +5,7 @@ import path from 'node:path';
 import os from 'node:os';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { WorkflowService } from '../../workflow/workflow.service.js';
+import type { VersionControlService } from '../../version-control/version-control.service.js';
 import type { AuthUser, FileTreeEntry } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { AccessControlService } from '../access-control.service.js';
@@ -65,7 +65,7 @@ function stubWorkspace(workspaceDir: string): WorkspaceService {
   } as unknown as WorkspaceService;
 }
 
-function stubWorkflow() {
+function stubVersionControl() {
   const commits: { summary: string }[] = [];
   // Strict per-path locks — a live row is contended even for the same user,
   // exactly like FileLockService (nesting bugs must fail here too).
@@ -107,7 +107,7 @@ function stubWorkflow() {
       commits.push({ summary });
       return {} as unknown;
     },
-  } as unknown as WorkflowService;
+  } as unknown as VersionControlService;
   return { svc, commits, acquireCalls };
 }
 
@@ -126,11 +126,11 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     await write(repo, 'groups.yaml', 'groups:\n  GTM Team:\n    - sara@x.io\n');
     await write(repo, 'access.md', '---\nwrite:\n  - Admin\nread:\n  - Product\n---\n');
     const workspace = stubWorkspace(root);
-    const workflow = stubWorkflow();
-    commits = workflow.commits;
+    const versionControl = stubVersionControl();
+    commits = versionControl.commits;
     service = new RolesAdminService(
       workspace,
-      workflow.svc,
+      versionControl.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
       new NodeFs(),
       KB,
@@ -212,10 +212,10 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     // that claims no write authority. A write-intent acquire here would fail
     // EVERY manual-mode conversion at lock acquisition.
     const workspace = stubWorkspace(root);
-    const workflow = stubWorkflow();
+    const versionControl = stubVersionControl();
     const svc = new RolesAdminService(
       workspace,
-      workflow.svc,
+      versionControl.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
       new NodeFs(),
       KB,
@@ -226,12 +226,12 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     expect(await groupsYaml()).toContain('Product:');
     // The synced file WAS locked (the serialization is real), via coordination;
     // the written files keep their write-gated acquires.
-    expect(workflow.acquireCalls).toContainEqual({
+    expect(versionControl.acquireCalls).toContainEqual({
       path: `${KB}/synced-groups.yaml`,
       coordination: true,
     });
-    expect(workflow.acquireCalls).toContainEqual({ path: `${KB}/roles.yaml`, coordination: false });
-    expect(workflow.acquireCalls).toContainEqual({ path: `${KB}/groups.yaml`, coordination: false });
+    expect(versionControl.acquireCalls).toContainEqual({ path: `${KB}/roles.yaml`, coordination: false });
+    expect(versionControl.acquireCalls).toContainEqual({ path: `${KB}/groups.yaml`, coordination: false });
   });
 
   it('conversion refusals: capability role, group-assigned role, IdP mode', async () => {
@@ -259,8 +259,8 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     // write nothing (committing a groups.yaml group in IdP mode writes a
     // retired file).
     const workspace = stubWorkspace(root);
-    const workflow = stubWorkflow();
-    const wf = workflow.svc as unknown as {
+    const versionControl = stubVersionControl();
+    const wf = versionControl.svc as unknown as {
       acquireLock: (
         w: string,
         b: string,
@@ -269,7 +269,7 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
         opts?: { coordination?: boolean },
       ) => Promise<unknown>;
     };
-    const origAcquire = wf.acquireLock.bind(workflow.svc);
+    const origAcquire = wf.acquireLock.bind(versionControl.svc);
     wf.acquireLock = async (w, b, p, u, opts) => {
       if (p === `${KB}/synced-groups.yaml`) {
         // The sync's provisioning push won the race for this lock and landed.
@@ -279,7 +279,7 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     };
     const svc = new RolesAdminService(
       workspace,
-      workflow.svc,
+      versionControl.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
       new NodeFs(),
       KB,
@@ -292,19 +292,19 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     // Nothing moved.
     expect(await rolesYaml()).toBe(ROLES);
     expect(await groupsYaml()).not.toContain('Product');
-    expect(workflow.commits).toHaveLength(0);
+    expect(versionControl.commits).toHaveLength(0);
   });
 
   it('a failed conversion with NO pre-existing groups.yaml leaves no groups.yaml behind', async () => {
     await fs.rm(path.join(repo, 'groups.yaml'));
     const workspace = stubWorkspace(root);
-    const workflow = stubWorkflow();
-    (workflow.svc as unknown as { commitChanges: unknown }).commitChanges = async () => {
+    const versionControl = stubVersionControl();
+    (versionControl.svc as unknown as { commitChanges: unknown }).commitChanges = async () => {
       throw new Error('commit exploded');
     };
     const svc = new RolesAdminService(
       workspace,
-      workflow.svc,
+      versionControl.svc,
       new AccessControlService(workspace as never, KB, new NodeFs()),
       new NodeFs(),
       KB,

package/src/modules/access/__tests__/roles.routes.test.ts

@@ -12,8 +12,8 @@ import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IAccessControl } from '../access-control.interface.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { AuthService } from '../../auth/auth.service.js';
-import type { WorkflowService } from '../../workflow/workflow.service.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlService } from '../../version-control/version-control.service.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import type { FileTreeEntry } from '@bevel-software/platform-shared';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
@@ -113,7 +113,7 @@ async function makeHarness(
   // exactly like FileLockService (nesting bugs must fail here too).
   const locks = new Map<string, { id: string; name: string }>();
   const lockRow = (h: { id: string; name: string }) => ({ holderUserId: h.id, holderName: h.name });
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn(async (_w: string, _b: string, p: string) => {
       const h = locks.get(p);
       return h ? lockRow(h) : null;
@@ -131,9 +131,9 @@ async function makeHarness(
     // Write-free: the lock-aware filesystem writes to disk; this just commits the
     // dirty tree. Not exercised by these route tests (no rename), but kept honest.
     commitChanges: vi.fn(async () => ({})),
-  } as unknown as WorkflowService;
+  } as unknown as VersionControlService;
 
-  const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+  const eventBus = { emit: vi.fn() } as unknown as VersionControlEventBus;
   const accounts = [
     { email: 'off@example.com', deactivatedAt: new Date('2026-09-01T00:00:00Z') },
     'on@example.com',
@@ -182,7 +182,7 @@ async function makeHarness(
     (req as unknown as { userId: string }).userId = ADMIN.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, versionControlService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

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

@@ -3,12 +3,12 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import type { AccessControlService } from '../access-control.service.js';
-import type { WorkflowEventBus } from '../../workflow/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/event-bus.js';
 import { createSyncedGroupsCommitter } from '../synced-groups-committer.js';
-import { PushNeedsAgentResolutionError, WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { PushNeedsAgentResolutionError, VersionControlValidationError } from '../../../shared/domain-errors.js';
 
 const KB = 'knowledge-base';
 const BOT: AuthUser = { id: 'bot-1', email: 'directory-sync@bevel.local', name: 'Directory Sync Bot' };
@@ -26,7 +26,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
   });
 
   function makeDeps(
-    workflowOverrides: Partial<
+    versionControlOverrides: Partial<
       Record<'commitChanges' | 'releaseLock' | 'hasQueuedCommit' | 'hasUnpushedCommits', unknown>
     > = {},
   ) {
@@ -44,7 +44,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
     // Default: the branch still carries the landed-but-unpushed commit — the
     // truthful answer everywhere except the worker-won-the-race scenario.
     const hasUnpushedCommits = vi.fn(async () => true);
-    const workflowService = {
+    const versionControlService = {
       acquireLock: vi.fn(async () => ({ acquired: true, lock: {} })),
       releaseLock,
       releaseLockNoCommit,
@@ -52,13 +52,13 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
       hasQueuedCommit,
       hasUnpushedCommits,
       commitChanges: vi.fn(async () => ({})),
-      ...workflowOverrides,
-    } as unknown as IWorkflowService;
+      ...versionControlOverrides,
+    } as unknown as IVersionControlService;
     const accessControl = { invalidate: vi.fn() } as unknown as AccessControlService;
-    const eventBus = { emit: vi.fn() } as unknown as WorkflowEventBus;
+    const eventBus = { emit: vi.fn() } as unknown as VersionControlEventBus;
     const committer = createSyncedGroupsCommitter({
       workspaceService,
-      workflowService,
+      versionControlService,
       accessControl,
       eventBus,
       kbDirName: KB,
@@ -99,7 +99,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
       .mockResolvedValueOnce(undefined)
       // The committer's arm probe: nothing left to release.
       .mockRejectedValue(
-        new WorkflowValidationError('Cannot release lock: not held by you.', {
+        new VersionControlValidationError('Cannot release lock: not held by you.', {
           kind: 'lock-not-held',
         }),
       );
@@ -125,7 +125,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
     // unpublished forever. With the queue consulted directly, an empty queue
     // must surface the original push failure.
     const releaseLock = vi.fn().mockRejectedValue(
-      new WorkflowValidationError('Cannot release lock: not held by you.', {
+      new VersionControlValidationError('Cannot release lock: not held by you.', {
         kind: 'lock-not-held',
       }),
     );
@@ -154,7 +154,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
       .fn()
       .mockResolvedValueOnce(undefined) // writeFiles' release: enqueued + dropped
       .mockRejectedValue(
-        new WorkflowValidationError('Cannot release lock: not held by you.', {
+        new VersionControlValidationError('Cannot release lock: not held by you.', {
           kind: 'lock-not-held',
         }),
       );
@@ -171,7 +171,7 @@ describe('createSyncedGroupsCommitter.persist — post-commit push failures', ()
 
   it('REJECTS when the queue itself cannot be read (armed must be PROVEN, never assumed)', async () => {
     const releaseLock = vi.fn().mockRejectedValue(
-      new WorkflowValidationError('Cannot release lock: not held by you.', {
+      new VersionControlValidationError('Cannot release lock: not held by you.', {
         kind: 'lock-not-held',
       }),
     );

package/src/modules/access/__tests__/user-access-removal.service.test.ts

@@ -6,7 +6,7 @@ import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { WorkflowService } from '../../workflow/workflow.service.js';
+import type { VersionControlService } from '../../version-control/version-control.service.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
@@ -62,7 +62,7 @@ function stubWorkspace(workspaceDir: string): WorkspaceService {
   } as unknown as WorkspaceService;
 }
 
-function stubWorkflow(opts: { failCommit?: boolean; pushNeedsResolution?: boolean } = {}) {
+function stubVersionControl(opts: { failCommit?: boolean; pushNeedsResolution?: boolean } = {}) {
   const commits: { summary: string; paths: string[]; author: string }[] = [];
   const locks = new Map<string, AuthUser>();
   const lockRow = (h: AuthUser) => ({ holderUserId: h.id, holderName: h.name });
@@ -89,7 +89,7 @@ function stubWorkflow(opts: { failCommit?: boolean; pushNeedsResolution?: boolea
       if (opts.pushNeedsResolution) throw new PushNeedsAgentResolutionError(DEFAULT_BRANCH, paths[0], 'diverged', 'rebase failed');
       return {} as unknown;
     },
-  } as unknown as WorkflowService;
+  } as unknown as VersionControlService;
   return { svc, commits, locks };
 }
 
@@ -167,11 +167,11 @@ describe('UserAccessRemovalService', () => {
 
   const read = (rel: string) => fs.readFile(path.join(repo, rel), 'utf-8');
 
-  function build(workflow = stubWorkflow(), owners: string[] = ['owner@x.io'], disk: ITreeWalker = new NodeFs()) {
+  function build(versionControl = stubVersionControl(), owners: string[] = ['owner@x.io'], disk: ITreeWalker = new NodeFs()) {
     const access = new AccessControlService(workspace as never, KB, new NodeFs());
     return {
-      workflow,
-      service: new UserAccessRemovalService(workspace, workflow.svc, access, disk, KB, () => DEFAULT_BRANCH, undefined, owners),
+      versionControl,
+      service: new UserAccessRemovalService(workspace, versionControl.svc, access, disk, KB, () => DEFAULT_BRANCH, undefined, owners),
     };
   }
 
@@ -236,12 +236,12 @@ describe('UserAccessRemovalService', () => {
   });
 
   it('removes the address from all four kinds of file in ONE commit named by the anonymised id', async () => {
-    const { service, workflow } = build();
+    const { service, versionControl } = build();
     const before = await read('access.md');
     const result = await service.remove(ADMIN, LEE, 'deleted-1234');
 
-    expect(workflow.commits).toHaveLength(1);
-    const [commit] = workflow.commits;
+    expect(versionControl.commits).toHaveLength(1);
+    const [commit] = versionControl.commits;
     expect(commit.summary).toBe('Remove erased account deleted-1234 from roles, groups and access rules');
     expect(commit.summary).not.toContain('lee');
     expect(commit.author).toBe('admin@x.io');
@@ -258,15 +258,15 @@ describe('UserAccessRemovalService', () => {
     expect(await read('Sales/access.md')).not.toContain('lee@x.io');
     expect((await service.report(LEE)).total).toBe(0);
     // No locks left behind.
-    expect(workflow.locks.size).toBe(0);
+    expect(versionControl.locks.size).toBe(0);
   });
 
   it('counts synced groups but never writes them, reporting the file as still naming the user', async () => {
     await write(repo, 'synced-groups.yaml', 'groups:\n  Engineering:\n    - lee@x.io\n');
-    const { service, workflow } = build();
+    const { service, versionControl } = build();
     expect((await service.report(LEE)).groups).toBe(2);
     const result = await service.remove(ADMIN, LEE, 'deleted-1');
-    expect(workflow.commits[0].paths).not.toContain(`${KB}/synced-groups.yaml`);
+    expect(versionControl.commits[0].paths).not.toContain(`${KB}/synced-groups.yaml`);
     expect(result.stillNamedIn).toEqual(['synced-groups.yaml']);
   });
 
@@ -278,11 +278,11 @@ describe('UserAccessRemovalService', () => {
       .spyOn(AccessControlService.prototype, 'canWriteBatchAtRef')
       .mockImplementation(async (_ws, _ref, _email, paths) => new Map(paths.map((p) => [p, p !== 'Sales/Plan.md'])));
     try {
-      const { service, workflow } = build();
+      const { service, versionControl } = build();
       const result = await service.remove(ADMIN, LEE, 'deleted-1');
 
-      expect(workflow.commits).toHaveLength(1);
-      expect(workflow.commits[0].paths.sort()).toEqual(
+      expect(versionControl.commits).toHaveLength(1);
+      expect(versionControl.commits[0].paths.sort()).toEqual(
         ['Sales/access.md', 'groups.yaml', 'roles.yaml'].map((p) => `${KB}/${p}`).sort(),
       );
       expect(result.removedFrom.sort()).toEqual(['Sales/access.md', 'groups.yaml', 'roles.yaml']);
@@ -291,7 +291,7 @@ describe('UserAccessRemovalService', () => {
       expect(await read('Sales/Plan.md')).toBe(NODE);
       expect(await read('roles.yaml')).not.toContain('lee@x.io');
       expect(await read('Sales/access.md')).not.toContain('lee@x.io');
-      expect(workflow.locks.size).toBe(0);
+      expect(versionControl.locks.size).toBe(0);
     } finally {
       canWrite.mockRestore();
     }
@@ -308,9 +308,9 @@ describe('UserAccessRemovalService', () => {
 
       // The pre-check only ever narrows the set; with nothing known, attempt
       // them all — the lock gate remains the authority.
-      const { service, workflow } = build();
+      const { service, versionControl } = build();
       const result = await service.remove(ADMIN, LEE, 'deleted-1');
-      expect(workflow.commits).toHaveLength(1);
+      expect(versionControl.commits).toHaveLength(1);
       expect(result.removedFrom.sort()).toEqual(['Sales/Plan.md', 'Sales/access.md', 'groups.yaml', 'roles.yaml']);
       expect(result.stillNamedIn).toEqual([]);
     } finally {
@@ -330,25 +330,25 @@ describe('UserAccessRemovalService', () => {
   });
 
   it('refuses the owner and the last Admin, writing nothing', async () => {
-    const { service, workflow } = build(stubWorkflow(), ['Lee@x.io']);
+    const { service, versionControl } = build(stubVersionControl(), ['Lee@x.io']);
     const report = await service.report(LEE);
     expect(report.removable).toBe(false);
     expect(report.blockedReason).toBe('The owner stays in roles and access rules.');
     await expect(service.remove(ADMIN, LEE, 'deleted-1')).rejects.toMatchObject({ status: 409 });
 
-    const other = build(stubWorkflow(), []);
+    const other = build(stubVersionControl(), []);
     expect((await other.service.report('admin@x.io')).removable).toBe(true);
     await write(repo, 'roles.yaml', 'roles:\n  Admin:\n    - lee@x.io\n');
     expect((await other.service.report(LEE)).blockedReason).toMatch(/last Admin/);
     await expect(other.service.remove(ADMIN, LEE, 'deleted-1')).rejects.toMatchObject({ status: 409 });
 
-    expect(workflow.commits).toHaveLength(0);
-    expect(other.workflow.commits).toHaveLength(0);
+    expect(versionControl.commits).toHaveLength(0);
+    expect(other.versionControl.commits).toHaveLength(0);
     expect(await read('groups.yaml')).toBe(GROUPS);
   });
 
   it('a failed commit restores every file and leaves them naming the user', async () => {
-    const { service } = build(stubWorkflow({ failCommit: true }));
+    const { service } = build(stubVersionControl({ failCommit: true }));
     await expect(service.remove(ADMIN, LEE, 'deleted-1')).rejects.toThrow(/push rejected/);
     expect(await read('roles.yaml')).toBe(ROLES);
     expect(await read('Sales/access.md')).toBe(SALES_ACCESS);
@@ -363,12 +363,12 @@ describe('UserAccessRemovalService', () => {
         return { ...result, holes: [...result.holes, 'Secret'] };
       },
     } as unknown as ITreeWalker;
-    const { service, workflow } = build(stubWorkflow(), ['owner@x.io'], holey);
+    const { service, versionControl } = build(stubVersionControl(), ['owner@x.io'], holey);
     await expect(service.remove(ADMIN, LEE, 'deleted-1')).rejects.toMatchObject({
       status: 422,
       message: expect.stringMatching(/could not be read \(Secret\)/),
     });
-    expect(workflow.commits).toHaveLength(0);
+    expect(versionControl.commits).toHaveLength(0);
     expect(await read('roles.yaml')).toBe(ROLES);
   });
 
@@ -377,9 +377,9 @@ describe('UserAccessRemovalService', () => {
       throw new Error('cache gone');
     });
     try {
-      const { service, workflow } = build();
+      const { service, versionControl } = build();
       const result = await service.remove(ADMIN, LEE, 'deleted-1');
-      expect(workflow.commits).toHaveLength(1);
+      expect(versionControl.commits).toHaveLength(1);
       expect(result.removedFrom.sort()).toEqual(['Sales/Plan.md', 'Sales/access.md', 'groups.yaml', 'roles.yaml']);
       expect(result.stillNamedIn).toEqual([]);
       // The refresh really ran after the commit and really threw.
@@ -391,9 +391,9 @@ describe('UserAccessRemovalService', () => {
   });
 
   it('a commit whose push needs resolution is reported as removed, publishing pending', async () => {
-    const { service, workflow } = build(stubWorkflow({ pushNeedsResolution: true }));
+    const { service, versionControl } = build(stubVersionControl({ pushNeedsResolution: true }));
     const result = await service.remove(ADMIN, LEE, 'deleted-1');
-    expect(workflow.commits).toHaveLength(1);
+    expect(versionControl.commits).toHaveLength(1);
     expect(result.publishPending).toBe(true);
     expect(result.removedFrom.sort()).toEqual(['Sales/Plan.md', 'Sales/access.md', 'groups.yaml', 'roles.yaml']);
     expect(result.stillNamedIn).toEqual([]);

package/src/modules/access/access-control.interface.ts

@@ -92,6 +92,17 @@ export type PathHolders = { read: HolderList; write: HolderList };
  */
 export type ProspectiveHolders = { before: PathHolders; after: PathHolders };
 
+/** One principal that loses or gains one verb in a move. A person is named by their address when they have no display name. */
+export type HolderChange = {
+  kind: 'group' | 'role' | 'plugin' | 'person';
+  name: string;
+  email?: string;
+  verb: 'read' | 'write';
+};
+
+/** Who loses and who gains opening or editing a file or folder in a move — see {@link IAccessControl.prospectiveHolderChanges}. */
+export type HolderChanges = { lose: HolderChange[]; gain: HolderChange[] };
+
 /** One caller's own verdict per access verb on one path. */
 export type PathVerbs = { read: boolean; write: boolean; download: boolean; owner: boolean };
 
@@ -420,6 +431,21 @@ export interface IAccessControl {
     toPath: string,
   ): Promise<ProspectiveHolders>;
 
+  /**
+   * Who loses and who gains `read` or `write` on one file or folder if a move
+   * puts it at `toPath`, over the same relocation as
+   * {@link IAccessControl.prospectiveHolders}. A holder on one side loses (or
+   * gains) the verb only when it does not hold it on the other side: the
+   * lists name grants, so a group no rule names at the destination may still
+   * read there through `everyone`, and one a rule denies there may not.
+   * Writes nothing and moves nothing.
+   */
+  prospectiveHolderChanges(
+    workspaceId: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<HolderChanges>;
+
   /**
    * The CALLER'S OWN `{ read, write, download, owner }` at `toPath` as they
    * will be once `fromPath` has been moved (`sourceRemains: false`, the

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

@@ -8,7 +8,7 @@ const log = logger('access');
 import { isAbsence, type ITreeWalker, type WalkListener } from '../../shared/fs.contract.js';
 import { assertOneSpecPerLine, isCommitSha, isGitTimeout, type IGitRunner } from '../../shared/git.contract.js';
 import { hashEmail } from '../../shared/email-identity.js';
-import { NodeGitRunner } from '../workflow/index.js';
+import { NodeGitRunner } from '../version-control/index.js';
 import { readRevSha } from '../kb-fs/index.js';
 import type { WorkspaceService } from '../workspace/index.js';
 import type {
@@ -22,6 +22,8 @@ import type {
   GrantSources,
   PathHolders,
   PathVerbs,
+  HolderChange,
+  HolderChanges,
   ProspectiveHolders,
   ResolvedPrincipal,
 } from './access-control.interface.js';
@@ -1354,6 +1356,70 @@ function eligibleHoldersResolved(
   return { principals, roles, users };
 }
 
+/** One side of a move: the access model, the path, and the rules the file carries there. */
+type MoveSide = { model: AccessModel; path: string; own: OwnEntries | null };
+
+/** The key set behind one entry of an eligible-holders list, read back from its name and kind. */
+function keysOfHolder(model: AccessModel, holder: ResolvedPrincipal): ReadonlySet<string> {
+  for (const [canonical, record] of model.roles.byCanonical) {
+    if (record.kind === holder.kind && record.displayName === holder.name) return principalKeysOfToken(model, canonical);
+  }
+  return principalKeysOfToken(model, canonicalRoleName(holder.name));
+}
+
+/**
+ * Who loses and who gains `verb` between the two sides of a move. The
+ * candidates are every principal and person a rule on either side names for
+ * the verb, as a grant or as a denial, and every holder either side lists;
+ * each is put to both sides' resolvers as the gates would put it. The holder
+ * lists alone are not enough: they name grants, so they miss a group still
+ * covered by `everyone`, and they cannot show someone whose only access was
+ * `everyone` and whom a rule on the far side denies by name.
+ */
+function holderChangesFor(verb: 'read' | 'write', here: MoveSide, there: MoveSide): HolderChanges {
+  const collectives = new Map<string, { holder: ResolvedPrincipal; keys: ReadonlySet<string> }>();
+  const people = new Set<string>();
+  const addCollective = (holder: ResolvedPrincipal, keys: ReadonlySet<string>) => {
+    const id = `${holder.kind}\0${holder.name.toLowerCase()}`;
+    if (!collectives.has(id)) collectives.set(id, { holder, keys });
+  };
+  for (const side of [here, there]) {
+    const held = eligibleHoldersResolved(side.model, verb, side.path, side.own);
+    for (const holder of held.principals) addCollective(holder, keysOfHolder(side.model, holder));
+    for (const user of held.users) people.add(user.email);
+    const { byRole, byEmail } = resolveAtPath(side.model, verb, side.path, side.own);
+    for (const token of byRole.keys()) {
+      const record = side.model.roles.byCanonical.get(token);
+      addCollective(
+        { name: record ? record.displayName : token, kind: record?.kind ?? 'role' },
+        principalKeysOfToken(side.model, token),
+      );
+    }
+    for (const email of byEmail.keys()) people.add(email);
+  }
+  const lose: HolderChange[] = [];
+  const gain: HolderChange[] = [];
+  const record = (had: boolean, has: boolean, change: HolderChange) => {
+    if (had && !has) lose.push(change);
+    if (!had && has) gain.push(change);
+  };
+  for (const { holder, keys } of collectives.values()) {
+    record(
+      hasPermissionForKeys(here.model, verb, keys, here.path, here.own),
+      hasPermissionForKeys(there.model, verb, keys, there.path, there.own),
+      { kind: holder.kind, name: holder.name, verb },
+    );
+  }
+  for (const email of [...people].sort()) {
+    record(
+      hasPermissionResolved(here.model, verb, email, here.path, here.own),
+      hasPermissionResolved(there.model, verb, email, there.path, there.own),
+      { kind: 'person', name: email, email, verb },
+    );
+  }
+  return { lose, gain };
+}
+
 /**
  * Every individual the model names: `roles.yaml` members, emails named inline
  * at this path's scope, and the deployment owner (bound by every rule that
@@ -1928,6 +1994,32 @@ export class AccessControlService implements IAccessControl {
     };
   }
 
+  /** Who loses and who gains `read` or `write` in a move (see the interface). */
+  async prospectiveHolderChanges(
+    workspaceId: string,
+    fromPath: string,
+    toPath: string,
+  ): Promise<HolderChanges> {
+    const model = await this.loadModel(workspaceId);
+    const repoDir = await this.repoDir(workspaceId);
+    const { isFolder, ownHere, ownThere, landing } =
+      await this.relocationSubject(repoDir, fromPath, toPath);
+    const here: MoveSide = { model, path: fromPath, own: ownHere };
+    const there: MoveSide = {
+      model: withRelocatedAccessFiles(model, fromPath, toPath, { sourceRemains: false, sourceIsFolder: isFolder, landing }),
+      path: toPath,
+      own: ownThere,
+    };
+    const lose: HolderChange[] = [];
+    const gain: HolderChange[] = [];
+    for (const verb of ['read', 'write'] as const) {
+      const changes = holderChangesFor(verb, here, there);
+      lose.push(...changes.lose);
+      gain.push(...changes.gain);
+    }
+    return { lose, gain };
+  }
+
   /**
    * The caller's own verbs at `toPath` as they will be once `fromPath` has
    * been moved or copied there (see the interface).

package/src/modules/access/access-declarations.ts

@@ -1,5 +1,5 @@
 import type { FileTreeEntry, IWorkspaceService } from '@bevel-software/platform-shared';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import { accessMdPathForFolder } from './access-mutation.service.js';
 import {
   EVERYONE_CANONICAL,
@@ -75,7 +75,7 @@ export interface AccessDeclaration {
 export const DECLARATION_SCAN_FILE_CAP = 400;
 
 /** 400 for a target that is not a folder. */
-export class AccessDeclarationsError extends WorkflowDomainError {
+export class AccessDeclarationsError extends VersionControlDomainError {
   constructor(message: string, status = 400) {
     super(message, status);
     this.name = 'AccessDeclarationsError';

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

@@ -53,7 +53,7 @@ import {
   AccessSpliceError,
 } from '../access-model/index.js';
 import type { Verb, Principal, TokenMatch } from '../access-model/index.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError } from '../../shared/domain-errors.js';
 import {
   canCarryFrontmatter,
   FOLDER_GOVERNS_ACCESS_KIND,
@@ -64,7 +64,7 @@ import {
 export type TargetKind = 'folder' | 'file';
 
 /** Bad-request-class mutation failure (invalid principal, unknown role/group, lockout). */
-export class AccessMutationError extends WorkflowDomainError {
+export class AccessMutationError extends VersionControlDomainError {
   constructor(message: string, status = 400, payload?: Record<string, unknown>) {
     super(message, status, payload);
     this.name = 'AccessMutationError';