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

package/src/modules/embed/__tests__/embed.service.test.ts

@@ -1,10 +1,9 @@
 import jwt from 'jsonwebtoken';
 import { createHmac } from 'node:crypto';
 import { describe, expect, it, vi } from 'vitest';
-import { createFileReaderRegistry } from '../../workspace/file-readers/file-reader.registry.js';
-import type { DocExtractOutcome, DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
-import { makeRolesYamlWriteValidator, RolesYamlInvalidError } from '../../access-model/roles-yaml-guard.js';
-import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/account-admission.js';
+import { realFileReaders } from '../../../__tests__/real-readers.js';
+import { makeRolesYamlWriteValidator } from '../../access-model/index.js';
+import { ACCOUNT_DEACTIVATED_MESSAGE } from '../../auth/index.js';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
 import { EmbedService, type EmbedConfig } from '../embed.service.js';
 import {
@@ -54,19 +53,6 @@ interface Opts {
   resolveNodeId?: ((id: string) => Promise<string | null>) | null;
 }
 
-/**
- * The extraction service the reader registry takes, typed against its
- * contract: no test here reads a document-format file, and one that did
- * would get this typed refusal, not a silent empty text.
- */
-function noDocExtract(): DocExtractService {
-  const extract = async (): Promise<DocExtractOutcome> => ({
-    ok: false,
-    message: 'this suite reads no document-format file',
-  });
-  return { extract } satisfies Pick<DocExtractService, 'extract'> as DocExtractService;
-}
-
 function build(opts: Opts = {}) {
   const files: Record<string, string | Buffer> = opts.files ?? { [WS]: PAGE };
   const workspaceService = {
@@ -102,11 +88,11 @@ function build(opts: Opts = {}) {
     isEmailDomainAllowed: vi.fn(() => opts.emailDomainAllowed ?? true),
     isActive: vi.fn(async () => opts.active ?? true),
   };
-  const workflowService = {
+  const versionControlService = {
     // No live lock: a save takes it. The contention rules themselves are
     // exercised against the real lock in embed.service.lock.test.ts.
     getLock: vi.fn(async () => null),
-    // The suggestions branch is created here, under the workflow's own
+    // The suggestions branch is created here, under the version-control service's own
     // branch-lifecycle lock, never straight through git.
     createBranch: opts.createBranch ?? vi.fn(async () => ({})),
     acquireLock: vi.fn(async () => ({
@@ -135,16 +121,16 @@ function build(opts: Opts = {}) {
     workspaceService as never,
     accessControl as never,
     authService as never,
-    workflowService as never,
+    versionControlService as never,
     gitService as never,
     accountLinks as never,
-    createFileReaderRegistry(noDocExtract()),
+    realFileReaders(),
     // The real gate: the property under test is that an embed write cannot
     // put on disk what the app's editor would refuse.
     makeRolesYamlWriteValidator(KB),
     opts.resolveNodeId ?? null,
   );
-  return { service, workspaceService, accessControl, authService, workflowService, gitService, accountLinks };
+  return { service, workspaceService, accessControl, authService, versionControlService, gitService, accountLinks };
 }
 
 /** The token a mint produced, decoded — so a test can assert on the claims. */
@@ -494,18 +480,18 @@ describe('EmbedService: bytes', () => {
 
 describe('EmbedService: saving as a writer', () => {
   it('writes to the default branch and releases the lock, which commits', async () => {
-    const { service, workspaceService, workflowService } = build();
+    const { service, workspaceService, versionControlService } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await service.acquireLock(token);
     await service.save(token, 'new text');
-    expect(workflowService.acquireLock).toHaveBeenCalledWith(
+    expect(versionControlService.acquireLock).toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       BRANCH,
       WS,
       expect.objectContaining({ id: USER.id }),
     );
     expect(workspaceService.writeFile).toHaveBeenCalledWith(encodeURIComponent(BRANCH), WS, 'new text');
-    expect(workflowService.releaseLock).toHaveBeenCalledWith(
+    expect(versionControlService.releaseLock).toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       BRANCH,
       WS,
@@ -526,12 +512,12 @@ describe('EmbedService: saving as a writer', () => {
    * commit to publish.
    */
   it('writes nothing when the viewer no longer holds the lock', async () => {
-    const { service, workspaceService, workflowService } = build({ acquired: false, holderName: 'Bob' });
+    const { service, workspaceService, versionControlService } = build({ acquired: false, holderName: 'Bob' });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.save(token, 'x')).rejects.toThrow(EmbedLockedError);
     await expect(service.save(token, 'x')).rejects.toThrow('Bob');
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   /**
@@ -541,27 +527,27 @@ describe('EmbedService: saving as a writer', () => {
    * have access.
    */
   it('refuses to keep a lock alive for a viewer who lost write access, and releases it', async () => {
-    const { service, accessControl, workflowService } = build();
+    const { service, accessControl, versionControlService } = build();
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     accessControl.canWrite.mockResolvedValue(false);
     await expect(service.heartbeat(token)).rejects.toThrow(EmbedAccessError);
-    expect(workflowService.heartbeatLock).not.toHaveBeenCalled();
-    expect(workflowService.releaseLockNoCommit).toHaveBeenCalledWith(
+    expect(versionControlService.heartbeatLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLockNoCommit).toHaveBeenCalledWith(
       expect.any(String),
       BRANCH,
       `${KB}/${REPO}`,
       expect.objectContaining({ id: USER.id }),
     );
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('releases the lock WITHOUT committing when the write fails, and rethrows', async () => {
-    const { service, workspaceService, workflowService } = build();
+    const { service, workspaceService, versionControlService } = build();
     workspaceService.writeFile.mockRejectedValueOnce(new Error('disk full'));
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.save(token, 'x')).rejects.toThrow('disk full');
-    expect(workflowService.releaseLockNoCommit).toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLockNoCommit).toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('refuses Edit and Save to a viewer without write access', async () => {
@@ -594,12 +580,12 @@ describe('EmbedService: saving as a writer', () => {
 
 describe('EmbedService: proposing as a non-writer', () => {
   it('commits to the viewer OWN suggestions branch and opens a change request', async () => {
-    const { service, workspaceService, workflowService } = build({ canWrite: false });
+    const { service, workspaceService, versionControlService } = build({ canWrite: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     const result = await service.propose(token, 'proposed text');
 
     const branch = 'suggestions/alice-u-1/knowledge';
-    expect(workflowService.createBranch).toHaveBeenCalledWith(encodeURIComponent(BRANCH), branch, BRANCH);
+    expect(versionControlService.createBranch).toHaveBeenCalledWith(encodeURIComponent(BRANCH), branch, BRANCH);
     expect(workspaceService.writeFile).toHaveBeenCalledWith(encodeURIComponent(branch), WS, 'proposed text');
     // The write and its commit run inside the workspace service's own
     // per-path turn — the queue every other write surface takes — so two
@@ -607,7 +593,7 @@ describe('EmbedService: proposing as a non-writer', () => {
     expect(workspaceService.withPathTurn).toHaveBeenCalledWith(encodeURIComponent(branch), WS, expect.any(Function));
     const turn = workspaceService.withPathTurn.mock.invocationCallOrder[0]!;
     expect(workspaceService.writeFile.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
-    expect(workflowService.commitChanges.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
+    expect(versionControlService.commitChanges.mock.invocationCallOrder[0]).toBeGreaterThan(turn);
     /**
      * COMMITTED, and committed BEFORE the request is opened.
      *
@@ -617,7 +603,7 @@ describe('EmbedService: proposing as a non-writer', () => {
      * request has no file changes to approve" about a proposal sitting
      * uncommitted on disk. Found on a real boot, not by a stub.
      */
-    expect(workflowService.commitChanges).toHaveBeenCalledWith(
+    expect(versionControlService.commitChanges).toHaveBeenCalledWith(
       encodeURIComponent(branch),
       expect.objectContaining({ id: USER.id }),
       expect.stringContaining(REPO),
@@ -626,10 +612,10 @@ describe('EmbedService: proposing as a non-writer', () => {
       // in-flight write of theirs in under this message.
       [WS],
     );
-    expect(workflowService.commitChanges.mock.invocationCallOrder[0]).toBeLessThan(
-      workflowService.openChangeRequest.mock.invocationCallOrder[0],
+    expect(versionControlService.commitChanges.mock.invocationCallOrder[0]).toBeLessThan(
+      versionControlService.openChangeRequest.mock.invocationCallOrder[0],
     );
-    expect(workflowService.openChangeRequest).toHaveBeenCalledWith(
+    expect(versionControlService.openChangeRequest).toHaveBeenCalledWith(
       encodeURIComponent(branch),
       expect.objectContaining({ id: USER.id }),
       { sourceBranch: branch, targetBranch: BRANCH, title: 'Changes from Alice. Knowledge' },
@@ -638,10 +624,10 @@ describe('EmbedService: proposing as a non-writer', () => {
   });
 
   it('touches NOTHING on the default branch — no lock, no write there', async () => {
-    const { service, workspaceService, workflowService } = build({ canWrite: false });
+    const { service, workspaceService, versionControlService } = build({ canWrite: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await service.propose(token, 'proposed text');
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalledWith(
       encodeURIComponent(BRANCH),
       expect.anything(),
@@ -653,10 +639,10 @@ describe('EmbedService: proposing as a non-writer', () => {
     const createBranch = vi.fn(async () => {
       throw new Error('a branch named "suggestions/alice-u-1/knowledge" already exists');
     });
-    const { service, workflowService } = build({ canWrite: false, createBranch });
+    const { service, versionControlService } = build({ canWrite: false, createBranch });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, 'x')).resolves.toMatchObject({ number: 42 });
-    expect(workflowService.openChangeRequest).toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).toHaveBeenCalled();
   });
 
   it('a second proposal finds the branch on origin and does not try to create it again', async () => {
@@ -666,11 +652,11 @@ describe('EmbedService: proposing as a non-writer', () => {
     const createBranch = vi.fn(async () => {
       throw new Error('git push failed: ! [rejected] suggestions/alice-u-1/knowledge (non-fast-forward)');
     });
-    const { service, workflowService } = build({ canWrite: false, createBranch, remoteBranchExists: true });
+    const { service, versionControlService } = build({ canWrite: false, createBranch, remoteBranchExists: true });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, 'again')).resolves.toMatchObject({ number: 42 });
     expect(createBranch).not.toHaveBeenCalled();
-    expect(workflowService.openChangeRequest).toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).toHaveBeenCalled();
   });
 
   /**
@@ -706,16 +692,16 @@ describe('EmbedService: proposing as a non-writer', () => {
     // The same PNG-under-a-markdown-name the save test uses: a proposal is a
     // commit of text, and must not commit text over bytes a Save refuses.
     const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]);
-    const { service, workspaceService, workflowService } = build({
+    const { service, workspaceService, versionControlService } = build({
       canWrite: false,
       files: { [WS]: png },
     });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     await expect(service.propose(token, '# replaced')).rejects.toThrow(EmbedAccessError);
-    expect(workflowService.createBranch).not.toHaveBeenCalled();
+    expect(versionControlService.createBranch).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
-    expect(workflowService.openChangeRequest).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.openChangeRequest).not.toHaveBeenCalled();
   });
 });
 
@@ -728,7 +714,7 @@ describe('EmbedService: proposing as a non-writer', () => {
  */
 describe('EmbedService: a switched-off account', () => {
   it('reads, saves and proposes nothing on a token minted for it, and is told why', async () => {
-    const { service, workspaceService, workflowService } = build({ active: false });
+    const { service, workspaceService, versionControlService } = build({ active: false });
     const { token } = await service.mintForUser({ userId: USER.id, reference: REPO });
     for (const call of [
       () => service.loadFile(token),
@@ -744,8 +730,8 @@ describe('EmbedService: a switched-off account', () => {
     }
     expect(workspaceService.readFileBinary).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
   });
 });
 
@@ -789,24 +775,24 @@ describe('EmbedService: the roles.yaml write gate', () => {
   const VALID = 'roles:\n  Admin:\n    - a@x.eu\n';
 
   it('refuses to save a roles.yaml that would not parse, writing nothing and taking no lock', async () => {
-    const { service, workspaceService, workflowService } = build({ files: { [ROLES]: VALID } });
+    const { service, workspaceService, versionControlService } = build({ files: { [ROLES]: VALID } });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
-    await expect(service.save(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
+    await expect(service.save(token, 'roles: [oops')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.acquireLock).not.toHaveBeenCalled();
-    expect(workflowService.releaseLock).not.toHaveBeenCalled();
+    expect(versionControlService.acquireLock).not.toHaveBeenCalled();
+    expect(versionControlService.releaseLock).not.toHaveBeenCalled();
   });
 
   it('refuses to propose a roles.yaml that would not parse, before any branch is made', async () => {
-    const { service, workspaceService, workflowService } = build({
+    const { service, workspaceService, versionControlService } = build({
       canWrite: false,
       files: { [ROLES]: VALID },
     });
     const { token } = await service.mintForUser({ userId: USER.id, reference: 'roles.yaml' });
-    await expect(service.propose(token, 'roles: [oops')).rejects.toThrow(RolesYamlInvalidError);
-    expect(workflowService.createBranch).not.toHaveBeenCalled();
+    await expect(service.propose(token, 'roles: [oops')).rejects.toMatchObject({ status: 422, payload: { kind: 'roles-yaml-invalid' } });
+    expect(versionControlService.createBranch).not.toHaveBeenCalled();
     expect(workspaceService.writeFile).not.toHaveBeenCalled();
-    expect(workflowService.commitChanges).not.toHaveBeenCalled();
+    expect(versionControlService.commitChanges).not.toHaveBeenCalled();
   });
 
   it('saves a roles.yaml that parses, and any other file untouched by the gate', async () => {

package/src/modules/embed/__tests__/embed.tools.test.ts

@@ -57,7 +57,7 @@ async function serve(opts: Opts = {}) {
       ...(caller.tokenId ? { tokenId: caller.tokenId } : {}),
       abortSignal: new AbortController().signal,
       workspaceService: {} as never,
-      workflowService: {} as never,
+      versionControlService: {} as never,
       events: {} as never,
       getFilesystem: async () => {
         throw new Error('open_page reads through readForTool, not the filesystem');

package/src/modules/embed/embed.routes.ts

@@ -332,7 +332,7 @@ function statusFor(err: unknown): number {
   if (err instanceof EmbedNodeNotFoundError) return 404;
   if (err instanceof EmbedLockedError) return 409;
   if (err instanceof EmbedRefParseError) return 400;
-  // A domain error from the workflow layer (a protected-branch refusal, a
+  // A domain error from the version-control layer (a protected-branch refusal, a
   // duplicate request) already carries the status it deserves.
   const status = (err as { status?: unknown })?.status;
   if (typeof status === 'number' && status >= 400 && status < 600) return status;

package/src/modules/embed/embed.service.ts

@@ -1,13 +1,13 @@
 import { createHmac } from 'node:crypto';
 import { ACCOUNT_DEACTIVATED_MESSAGE, timingSafeStringEqual } from '../auth/index.js';
 import jwt from 'jsonwebtoken';
-import type { AuthUser, IGitService, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IGitService, IVersionControlService } from '@bevel-software/platform-shared';
 import { suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import type { KbContext } from '../../shared/kb-context.js';
 import type { IAccessControl } from '../access/index.js';
-import { changeRequestLink, changeRequestLinkBase } from '../workflow/index.js';
+import { changeRequestLink, changeRequestLinkBase } from '../version-control/index.js';
 import type { FileReaderRegistry } from '../workspace/index.js';
 import type { WriteValidator } from '../kb-fs/index.js';
 import type {
@@ -105,7 +105,7 @@ export class EmbedService implements IEmbedService {
     private readonly workspaceService: EmbedWorkspacePort,
     private readonly accessControl: IAccessControl,
     private readonly authService: EmbedAuthPort,
-    private readonly workflowService: IWorkflowService,
+    private readonly versionControlService: IVersionControlService,
     private readonly gitService: IGitService,
     private readonly accountLinks: IAccountLinkService,
     private readonly readers: FileReaderRegistry,
@@ -320,7 +320,7 @@ export class EmbedService implements IEmbedService {
 
   async acquireLock(token: string): Promise<EmbedLockResult> {
     const { user, wsPath } = await this.requireEditor(token);
-    const result = await this.workflowService.acquireLock(
+    const result = await this.versionControlService.acquireLock(
       this.defaultWorkspaceId(),
       this.kb.defaultBranch,
       wsPath,
@@ -343,19 +343,19 @@ export class EmbedService implements IEmbedService {
     // goes HERE, not only when the view hears the refusal: a frame that is
     // gone, or a host that never delivers the 403, would otherwise leave the
     // file shut to the writers who still have access until the TTL. Letting
-    // go takes no access — the workflow releases only a lock this user holds.
+    // go takes no access — the version-control service releases only a lock this user holds.
     if (!canWrite) {
-      await this.workflowService.releaseLockNoCommit(workspaceId, this.kb.defaultBranch, wsPath, user);
+      await this.versionControlService.releaseLockNoCommit(workspaceId, this.kb.defaultBranch, wsPath, user);
       throw new EmbedAccessError();
     }
-    await this.workflowService.heartbeatLock(workspaceId, this.kb.defaultBranch, wsPath, user);
+    await this.versionControlService.heartbeatLock(workspaceId, this.kb.defaultBranch, wsPath, user);
   }
 
   async cancel(token: string): Promise<void> {
     const claims = this.verifyToken(token);
     const { user } = await this.resolveIdentity(claims);
     if (!user) return;
-    await this.workflowService.releaseLockNoCommit(
+    await this.versionControlService.releaseLockNoCommit(
       this.defaultWorkspaceId(),
       this.kb.defaultBranch,
       this.wsPathFor(claims.repoRelative),
@@ -384,9 +384,9 @@ export class EmbedService implements IEmbedService {
       await this.workspaceService.writeFile(workspaceId, wsPath, content);
       // Release commits + pushes the on-disk bytes through the background
       // queue — the same path the app's file page takes out of edit mode.
-      await this.workflowService.releaseLock(workspaceId, this.kb.defaultBranch, wsPath, user);
+      await this.versionControlService.releaseLock(workspaceId, this.kb.defaultBranch, wsPath, user);
     } catch (err) {
-      await this.workflowService
+      await this.versionControlService
         .releaseLockNoCommit(workspaceId, this.kb.defaultBranch, wsPath, user)
         .catch((cleanupErr) => {
           // Best-effort cleanup failed — say so, so a stuck lock is
@@ -446,11 +446,11 @@ export class EmbedService implements IEmbedService {
     // ORIGIN first: a second proposal finds the branch already pushed, and
     // creating it again would fail as a non-fast-forward push, not as
     // "already exists" — the race between the two is still caught below.
-    // Created through the workflow service, under its branch-lifecycle lock,
+    // Created through the version-control service, under its branch-lifecycle lock,
     // as every branch the app creates is: creating one is the one operation
     // that can bring a "gone" branch back under a retirement's feet.
     if (!(await this.gitService.remoteBranchExists(this.defaultWorkspaceId(), branch))) {
-      await this.workflowService
+      await this.versionControlService
         .createBranch(this.defaultWorkspaceId(), branch, this.kb.defaultBranch)
         .catch((err: unknown) => {
           if (err instanceof Error && /already exists|non-fast-forward|fetch first/i.test(err.message)) return;
@@ -469,7 +469,7 @@ export class EmbedService implements IEmbedService {
       // Scoped to the one path this proposal is about: the suggestions branch
       // is shared by everything this person has proposed, and a bare commit
       // would sweep in another in-flight write of theirs under this message.
-      await this.workflowService.commitChanges(
+      await this.versionControlService.commitChanges(
         workspace.id,
         user,
         `Propose changes to ${claims.repoRelative}`,
@@ -477,7 +477,7 @@ export class EmbedService implements IEmbedService {
       );
     });
     try {
-      const created = await this.workflowService.openChangeRequest(workspace.id, user, {
+      const created = await this.versionControlService.openChangeRequest(workspace.id, user, {
         sourceBranch: branch,
         targetBranch: this.kb.defaultBranch,
         title: `Changes from ${user.name}. Knowledge`,
@@ -531,14 +531,14 @@ export class EmbedService implements IEmbedService {
    */
   private async ensureHoldsLock(workspaceId: string, wsPath: string, user: AuthUser): Promise<void> {
     const branch = this.kb.defaultBranch;
-    const current = await this.workflowService.getLock(workspaceId, branch, wsPath);
+    const current = await this.versionControlService.getLock(workspaceId, branch, wsPath);
     if (current) {
       // A coordination hold grants no write authority, so it is not "ours"
       // for a save even when the id matches.
       if (current.holderUserId === user.id && current.mode !== 'coordination') return;
       throw new EmbedLockedError(current.holderName);
     }
-    const taken = await this.workflowService.acquireLock(workspaceId, branch, wsPath, user);
+    const taken = await this.versionControlService.acquireLock(workspaceId, branch, wsPath, user);
     if (!taken.acquired) throw new EmbedLockedError(taken.lock.holderName);
   }
 
@@ -551,7 +551,7 @@ export class EmbedService implements IEmbedService {
   }
 
   /**
-   * A change request's address, through the same builder the workflow tools
+   * A change request's address, through the same builder the version-control tools
    * use — so a proposal made from a chat and one made by an agent point at
    * the same place, path prefix of a proxied deployment included.
    */

package/src/modules/kb-fs/__tests__/branch-name.test.ts

@@ -4,7 +4,7 @@ import {
   assertValidBranchName,
   assertValidRelativePath,
 } from '../branch-name.js';
-import { BranchNameError, WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { BranchNameError, VersionControlValidationError } from '../../../shared/domain-errors.js';
 
 describe('assertValidBranchName', () => {
   it.each([
@@ -79,7 +79,7 @@ describe('assertValidRelativePath', () => {
     ['delete', 'Docs/a\u007Fb.md'],
     ['leading dash', '-afile'],
   ])('rejects %s (%s)', (_label, p) => {
-    expect(() => assertValidRelativePath(p)).toThrow(WorkflowValidationError);
+    expect(() => assertValidRelativePath(p)).toThrow(VersionControlValidationError);
   });
 });
 

package/src/modules/kb-fs/__tests__/file-change-notifier.test.ts

@@ -18,12 +18,13 @@ describe('FileChangeNotifier', () => {
     const b = vi.fn();
     notifier.onFilesChanged(a);
     notifier.onFilesChanged(b);
-    const c = change(['x/Tools/a.tool', 'x/Knowledge/B.md']);
-    notifier.emit(c);
+    notifier.emit(change(['x/Tools/a.tool', 'x/Knowledge/B.md']));
+    // Both hear the one change, shaped: paths sorted.
+    const shaped = change(['x/Knowledge/B.md', 'x/Tools/a.tool']);
     expect(a).toHaveBeenCalledTimes(1);
-    expect(a).toHaveBeenCalledWith(c);
+    expect(a).toHaveBeenCalledWith(shaped);
     expect(b).toHaveBeenCalledTimes(1);
-    expect(b).toHaveBeenCalledWith(c);
+    expect(b).toHaveBeenCalledWith(shaped);
   });
 
   it('a throwing listener never blocks the others (commit isolation)', () => {
@@ -38,6 +39,16 @@ describe('FileChangeNotifier', () => {
     expect(after).toHaveBeenCalledOnce();
   });
 
+  it('a listener whose promise rejects is isolated too — the rejection is caught, the others heard', async () => {
+    const notifier = new FileChangeNotifier();
+    const after = vi.fn();
+    notifier.onFilesChanged(async () => Promise.reject(new Error('boom, later')));
+    notifier.onFilesChanged(after);
+    expect(() => notifier.emit(change(['x/A.md']))).not.toThrow();
+    await new Promise<void>((resolve) => setImmediate(resolve));
+    expect(after).toHaveBeenCalledOnce();
+  });
+
   it('an empty path list emits nothing; unsubscribe stops delivery', () => {
     const notifier = new FileChangeNotifier();
     const listener = vi.fn();
@@ -48,4 +59,12 @@ describe('FileChangeNotifier', () => {
     notifier.emit(change(['x/A.md']));
     expect(listener).not.toHaveBeenCalled();
   });
+
+  it('hands every listener the paths sorted and unique: the shape of the contract is made here, once', () => {
+    const notifier = new FileChangeNotifier();
+    const heard: FilesChange[] = [];
+    notifier.onFilesChanged((c) => heard.push(c));
+    notifier.emit(change(['x/B.md', 'x/A.md', 'x/B.md']));
+    expect(heard).toEqual([change(['x/A.md', 'x/B.md'])]);
+  });
 });