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

package/src/modules/kb-fs/__tests__/move-with-edits.test.ts

@@ -4,11 +4,11 @@ import { promisify } from 'node:util';
 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, FilesChange, IVersionControlService } from '@bevel-software/platform-shared';
+import type { VersionControlHooks } from '../../version-control/index.js';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { GitService } from '../../workflow/git/git.service.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { realGitService, realVersionControlHooks } from '../../../__tests__/real-version-control.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import { LockingFilesystem, MoveLockedError, MoveRacedError, MoveUndoError } from '../locking-filesystem.js';
 import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
 
@@ -34,7 +34,7 @@ async function git(cwd: string, args: string[]): Promise<string> {
 
 let root: string;
 let repo: string;
-let workflow: IWorkflowService;
+let versionControl: IVersionControlService;
 let lockedPaths: Set<string>;
 
 async function put(rel: string, content: string | Buffer): Promise<void> {
@@ -59,17 +59,18 @@ beforeEach(async () => {
   await git(repo, ['add', '-A']);
   await git(repo, ['commit', '-m', 'seed']);
 
-  const svc = new GitService(
+  landed = [];
+  hooks = realVersionControlHooks();
+  hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
+  // What the git layer reports landing — the one place every commit is announced from.
+  hooks.onCommitLanded((change) => landed.push(change));
+  const svc = realGitService(
     { getWorkspacePath: async () => root } as unknown as WorkspaceService,
-    (() => {
-      const hooks = new WorkflowHooks();
-      hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
-      return hooks;
-    })(),
+    hooks,
     testKbContext({ kbDirName: KB }),
   );
   lockedPaths = new Set();
-  workflow = {
+  versionControl = {
     acquireLock: vi.fn(async (_w: string, _b: string, p: string) =>
       lockedPaths.has(p)
         ? { acquired: false, lock: { holderName: 'Bob' } }
@@ -78,7 +79,7 @@ beforeEach(async () => {
     releaseLockNoCommit: vi.fn(async () => undefined),
     releaseLockUntouched: vi.fn(async () => undefined),
     commitChanges: vi.fn((w: string, u: AuthUser, s: string, paths?: string[]) => svc.commitChanges(w, u, s, paths)),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 });
 
 afterEach(async () => {
@@ -88,7 +89,7 @@ afterEach(async () => {
 const fsLayer = (validateWrite?: (p: string, content: unknown) => Promise<void>) =>
   new LockingFilesystem(
     { basePath: root, contained: true },
-    { workflow, workspaceId: WS, branch: 'feature-test', user: USER, kbDirName: KB, ...(validateWrite ? { validateWrite } : {}) },
+    { versionControl, workspaceId: WS, branch: 'feature-test', user: USER, kbDirName: KB, ...(validateWrite ? { validateWrite } : {}) },
   );
 
 /** The paths each release kind was called with. */
@@ -103,6 +104,11 @@ const edits = () => [
   { path: `${KB}/Index.md`, lockAt: `${KB}/Index.md`, content: '[one](Topics/Deep/A/One.md)\n' },
 ];
 
+/** Every commit the git layer landed, as the hook heard it (paths as git named them; the notifier is what sorts). */
+let landed: FilesChange[] = [];
+let hooks: VersionControlHooks;
+const heard = () => landed.map((c) => ({ ...c, paths: [...c.paths].sort() }));
+
 describe('LockingFilesystem.moveWithEdits', () => {
   it('lands the folder move and every edit as ONE commit that git reads as renames', async () => {
     const before = (await git(repo, ['rev-list', '--count', 'HEAD'])).trim();
@@ -123,6 +129,40 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
     // The binary moved byte for byte.
     expect([...(await fs.readFile(path.join(repo, 'Topics/Deep/A/pic.png')))]).toEqual([0x89, 0x50, 0x4e, 0x47, 0, 1, 2, 3]);
+    // The git layer reported the ONE commit, with every path it named at both
+    // ends — the one place any commit is announced from.
+    expect(heard()).toEqual([
+      {
+        workspaceId: WS,
+        branch: 'feature-test',
+        byUser: USER,
+        paths: [
+          `${KB}/Index.md`,
+          `${KB}/Projects/A/One.md`,
+          `${KB}/Projects/A/Two.md`,
+          `${KB}/Projects/A/pic.png`,
+          `${KB}/Topics/Deep/A/One.md`,
+          `${KB}/Topics/Deep/A/Two.md`,
+          `${KB}/Topics/Deep/A/pic.png`,
+        ],
+      },
+    ]);
+  });
+
+  it('a reactor that throws cannot unwind the landed move: the hook runs isolated, the commit, the files and the rename stay', async () => {
+    hooks.onCommitLanded(() => {
+      throw new Error('reactor exploded');
+    });
+    const before = (await git(repo, ['rev-list', '--count', 'HEAD'])).trim();
+    await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
+    expect(landed).toHaveLength(1);
+    expect((await git(repo, ['rev-list', '--count', 'HEAD'])).trim()).toBe(String(Number(before) + 1));
+    expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
+    expect(await read('Index.md')).toBe('[one](Topics/Deep/A/One.md)\n');
+    expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
+    await expect(fs.access(path.join(repo, 'Projects/A'))).rejects.toThrow();
+    // Every lock had already been given back untouched; nothing was discarded.
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
   });
 
   it('a single file moved with edits is one commit with a rename', async () => {
@@ -147,16 +187,17 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect((err as Error).message).toContain(`"${KB}/Projects/A/Two.md" is being edited by Bob`);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
     // Every lock taken was given back untouched.
-    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
+    expect(landed).toEqual([]);
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
   }, 20_000);
 
   it('a file saved into the folder while the locks were being taken refuses the move, nothing moved', async () => {
-    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    const acquire = versionControl.acquireLock as ReturnType<typeof vi.fn>;
     let arrived = false;
     acquire.mockImplementation(async () => {
       // The first lock is the moment somebody else's save lands in the folder.
@@ -171,15 +212,16 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(err).toBeInstanceOf(MoveRacedError);
     expect((err as Error).message).toContain(`"${KB}/Projects/A/Late.md" was added`);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
     expect(await read('Projects/A/Late.md')).toBe('late\n');
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(released(workflow.releaseLockUntouched).length).toBeGreaterThan(0);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched).length).toBeGreaterThan(0);
+    expect(landed).toEqual([]);
   });
 
   it('a move that fails and cannot be undone releases every lock with the discard, and says both', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async () => {
       // Something takes the old place while the move is in flight, so the
       // undo's rename finds its destination occupied.
       await put('Projects/A/Taken.md', 'x\n');
@@ -190,17 +232,19 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect((err as Error).message).toContain('commit exploded');
     expect((err as Error).message).toContain('could not be undone');
     // Nothing is handed back as untouched: every path goes with the discard.
-    expect(workflow.releaseLockUntouched).not.toHaveBeenCalled();
-    const discarded = released(workflow.releaseLockNoCommit);
+    expect(versionControl.releaseLockUntouched).not.toHaveBeenCalled();
+    const discarded = released(versionControl.releaseLockNoCommit);
     expect(discarded).toContain(`${KB}/Projects/A`);
     expect(discarded).toContain(`${KB}/Topics/Deep/A/One.md`);
     expect(discarded).toContain(`${KB}/Index.md`);
+    // A failed commit announces nothing.
+    expect(landed).toEqual([]);
   });
 
   it('a commit that landed but could not be pushed enqueues the committed paths only; the folder locks go back untouched', async () => {
     // The real commit lands; only its push is refused.
-    const commit = (workflow.commitChanges as ReturnType<typeof vi.fn>).getMockImplementation()!;
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
+    const commit = (versionControl.commitChanges as ReturnType<typeof vi.fn>).getMockImplementation()!;
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
       await commit(...args);
       throw new PushNeedsAgentResolutionError('feature-test', `${KB}/Index.md`, 'refused', '(not attempted)', 'refused');
     });
@@ -213,8 +257,8 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(Number(await git(repo, ['rev-list', '--count', 'HEAD']))).toBe(Number(commitsBefore) + 1);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
     expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
-    const enqueued = released(workflow.releaseLock);
-    const untouched = released(workflow.releaseLockUntouched);
+    const enqueued = released(versionControl.releaseLock);
+    const untouched = released(versionControl.releaseLockUntouched);
     // Every file the commit named is enqueued…
     for (const p of [`${KB}/Index.md`, `${KB}/Projects/A/One.md`, `${KB}/Topics/Deep/A/One.md`, `${KB}/Topics/Deep/A/pic.png`]) {
       expect(enqueued).toContain(p);
@@ -223,11 +267,30 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(enqueued).not.toContain(`${KB}/Projects/A`);
     expect(enqueued).not.toContain(`${KB}/Topics/Deep/A`);
     expect(untouched).toEqual([`${KB}/Projects/A`, `${KB}/Topics/Deep/A`]);
+    // The commit landed, so the git layer reported it — once, with the
+    // committed scope; the worker's later push makes no new commit and
+    // reports nothing more.
+    expect(heard()).toEqual([
+      {
+        workspaceId: WS,
+        branch: 'feature-test',
+        byUser: USER,
+        paths: [
+          `${KB}/Index.md`,
+          `${KB}/Projects/A/One.md`,
+          `${KB}/Projects/A/Two.md`,
+          `${KB}/Projects/A/pic.png`,
+          `${KB}/Topics/Deep/A/One.md`,
+          `${KB}/Topics/Deep/A/Two.md`,
+          `${KB}/Topics/Deep/A/pic.png`,
+        ],
+      },
+    ]);
   });
 
   it('locks every file of a moved folder at its old and its new path', async () => {
     await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
-    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string);
+    const locked = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string);
     for (const name of ['One.md', 'Two.md', 'pic.png']) {
       expect(locked).toContain(`${KB}/Projects/A/${name}`);
       expect(locked).toContain(`${KB}/Topics/Deep/A/${name}`);
@@ -236,19 +299,19 @@ describe('LockingFilesystem.moveWithEdits', () => {
   });
 
   it('a lock store that throws gives back the locks already held, and changes nothing', async () => {
-    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w: string, _b: string, p: string) => {
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w: string, _b: string, p: string) => {
       if (p === `${KB}/Projects/A/One.md`) throw new Error('lock store down');
       return { acquired: true, lock: { holderName: 'Alice' } };
     });
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('lock store down');
-    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`]);
+    expect(released(versionControl.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`]);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
   });
 
   it('every edit is judged again once the locks are held, and a refusal there changes nothing', async () => {
-    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    const acquire = versionControl.acquireLock as ReturnType<typeof vi.fn>;
     // A validator whose verdict depends on the state under the locks.
     const validateWrite = vi.fn(async (p: string) => {
       if (acquire.mock.calls.length > 0 && p.endsWith('Index.md')) throw new Error('refused under lock');
@@ -260,12 +323,12 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(validateWrite.mock.calls.filter((c) => c[0] === `${KB}/Index.md`)).toHaveLength(2);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Index.md`);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched)).toContain(`${KB}/Index.md`);
   });
 
   it('an edit whose bytes cannot be put back is released with the discard, not untouched', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementationOnce(async () => {
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementationOnce(async () => {
       // The restore of Index.md will fail: a folder now sits at its path.
       await fs.rm(path.join(repo, 'Index.md'));
       await fs.mkdir(path.join(repo, 'Index.md'));
@@ -274,11 +337,11 @@ describe('LockingFilesystem.moveWithEdits', () => {
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('commit exploded');
-    expect(released(workflow.releaseLockNoCommit)).toEqual([`${KB}/Index.md`]);
-    expect(released(workflow.releaseLockUntouched)).not.toContain(`${KB}/Index.md`);
+    expect(released(versionControl.releaseLockNoCommit)).toEqual([`${KB}/Index.md`]);
+    expect(released(versionControl.releaseLockUntouched)).not.toContain(`${KB}/Index.md`);
     // The moved file's edit was put back, and its lock released untouched.
     expect(await read('Projects/A/One.md')).toContain('../../NodeTypes/Task.md');
-    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Projects/A/One.md`);
+    expect(released(versionControl.releaseLockUntouched)).toContain(`${KB}/Projects/A/One.md`);
   });
 
   it('a check refusal under the locks changes nothing', async () => {
@@ -293,7 +356,7 @@ describe('LockingFilesystem.moveWithEdits', () => {
   });
 
   it('a failing commit puts every byte back and undoes the move', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('commit exploded'));
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('commit exploded'));
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('commit exploded');

package/src/modules/kb-fs/__tests__/repo-path.test.ts

@@ -9,7 +9,7 @@ import {
   normalizePathArgs,
   normalizeWorkspacePath,
 } from '../repo-path.js';
-import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../shared/domain-errors.js';
 
 const KB = 'knowledge-base';
 
@@ -80,8 +80,8 @@ describe('assertInsideRepo', () => {
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     expect(e.status).toBe(400);
     // The offending path, the rule, and the exact path to use instead: an
     // agent reading this error can retry without guessing.
@@ -144,8 +144,8 @@ describe('a line break in a path — one name to the gates, two object names to
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     expect(e.status).toBe(400);
     expect(e.message).toMatch(/control character/);
     // Never "use this instead": there is no corrected spelling of a name with
@@ -173,7 +173,7 @@ describe('a line break in a path — one name to the gates, two object names to
   it('refuses every control character, not only the line breaks', () => {
     for (const ch of ['\u0000', '\u0001', '\t', '\n', '\u000B', '\r', '\u001F', '\u007F']) {
       expect(() => normalizeWorkspacePath(`knowledge-base/Docs/a${ch}b.md`, KB), ch).toThrow(
-        WorkflowValidationError,
+        VersionControlValidationError,
       );
     }
   });
@@ -189,8 +189,8 @@ describe('a line break in a path — one name to the gates, two object names to
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     // Named as the CONFIGURATION error it is: an operator told their own path
     // was invalid would have nothing to fix.
     expect(e.message).toMatch(/checkout folder name/);

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

@@ -1,4 +1,4 @@
-import { BranchNameError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { BranchNameError, VersionControlValidationError } from '../../shared/domain-errors.js';
 
 // The protected-branch list is the knowledge base's (`KbContext.protectedBranches`):
 // services ask the context they were built with, so the backend guard and the
@@ -47,8 +47,8 @@ export function assertValidBranchName(name: string): void {
  * path we pass to `git` as a pathspec. Must stay within the repo; forward slashes only.
  */
 export function assertValidRelativePath(relativePath: string): void {
-  if (!relativePath) throw new WorkflowValidationError('path is required');
-  if (relativePath.length > 1024) throw new WorkflowValidationError('path too long');
+  if (!relativePath) throw new VersionControlValidationError('path is required');
+  if (relativePath.length > 1024) throw new VersionControlValidationError('path too long');
   // NUL, every other C0 control and DEL. A NUL is named on its own because it
   // terminates a C string and git's `-z` output; the rest are refused with it
   // because a LINE BREAK in a path is a separator in git's line-oriented stdin
@@ -59,22 +59,22 @@ export function assertValidRelativePath(relativePath: string): void {
   // check every path handed to git as a pathspec passes through.
   // eslint-disable-next-line no-control-regex
   if (/[\x00-\x1F\x7F]/.test(relativePath)) {
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       relativePath.includes('\0') ? 'path contains NUL' : 'path contains a control character',
     );
   }
   if (relativePath.includes('\\')) {
-    throw new WorkflowValidationError('path must use forward slashes only');
+    throw new VersionControlValidationError('path must use forward slashes only');
   }
   if (relativePath.startsWith('/') || /^[A-Za-z]:/.test(relativePath)) {
-    throw new WorkflowValidationError('path must be relative');
+    throw new VersionControlValidationError('path must be relative');
   }
   const parts = relativePath.split('/');
   if (parts.some((p) => p === '..' || p === '.')) {
-    throw new WorkflowValidationError('path must not contain "." or ".."');
+    throw new VersionControlValidationError('path must not contain "." or ".."');
   }
   if (relativePath.startsWith('-')) {
-    throw new WorkflowValidationError('path must not start with "-"');
+    throw new VersionControlValidationError('path must not start with "-"');
   }
   // Pathspec glob characters (`*`, `?`, `[`, `]`, `!`) and pathspec magic (`:(…)`)
   // would otherwise be interpreted by `git add -- <path>` / `git log -- <path>`

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

@@ -1,38 +1,63 @@
 /**
- * One in-process notification fired AFTER a set of file changes is committed +
- * pushed (post-lock-release), so backend services can react to KB writes without
- * the per-file TTL wait. Distinct from the SSE `WorkflowEventBus`, which fans
- * scoped events to browser sessions; this is an unscoped, server-side domain hook.
+ * One in-process notification per commit the git service lands — a single-file
+ * save, an autosave checkpoint, a batch (`LockingFilesystem.writeFiles`, a
+ * bulk upload, the admin roster commits, a plugin rename), a merge, a
+ * `commit_change` — fired when the commit lands: pushed, or awaiting its push
+ * (the later push makes no new commit and is not announced again). Backend
+ * services react to KB writes here without the per-file TTL wait. Distinct
+ * from the SSE `VersionControlEventBus`, which fans scoped events to browser
+ * sessions; this is an unscoped, server-side domain hook.
  *
- * BATCHED by design: a single-file save emits `paths: [p]`, a batch write
- * (`LockingFilesystem.writeFiles`, e.g. a bulk node upload) emits ONE event with
- * every path it committed. Subscribers that do expensive per-event work (the
- * id-repair rebuilds the id index) handle a whole batch off one rebuild instead
- * of N back-to-back ones.
+ * ONE SOURCE. The git service reports every commit it lands through
+ * `VersionControlHooks.onCommitLanded`, and the composition root hands that to
+ * this notifier once; nothing else emits here, and a test pins both. A commit
+ * made some other way (the startup runner's seed of a fresh knowledge base,
+ * before any catalog exists) is the one commit this does not see. A commit
+ * that ARRIVES by a pull was landed — and announced — by the process that made
+ * it; a pull of the default branch also announces the tree change on the SSE
+ * bus (`fs-tree-changed`), which the catalogs listen to, and a pull rebases
+ * this process's own commits without re-announcing them (their content is
+ * unchanged).
  *
- * Emitted from the two post-commit chokepoints (`WorkflowService.runPendingCommit`
- * for single-file writes, `LockingFilesystem.writeFiles` for batches).
+ * BATCHED by design: a single-file save emits `paths: [p]`, a batch emits ONE
+ * event with every path it committed, a merge every path it brought in — so a
+ * subscriber that does expensive per-event work (the id-repair rebuilds the id
+ * index) handles a whole batch off one rebuild instead of N back-to-back ones.
+ * Paths are workspace-relative, sorted and unique: `emit` shapes them.
  *
- * Every listener is invoked inside try/catch — a throwing subscriber must never
- * fail the commit that triggered it (mirrors the SSE bus's per-subscriber
- * isolation). Firing is fire-and-forget; a listener that needs to write files
- * (id-repair) does so on its own, after the locks have already been released.
+ * TIMING. The announcement is made when the commit lands, inside the git
+ * layer's reservation. A listener that only reads (the catalogs) is
+ * unaffected by locks. A listener that WRITES an announced path acquires its
+ * lock like any writer, and two cases differ: a batch's committer (the
+ * lock-aware filesystem, the admin commit driver) releases its locks once the
+ * commit's push has either gone through or been handed off to the recovery
+ * worker (the push is then still owed, and the lock no longer guards the
+ * path) — the lock-aware filesystem's acquire retries (three, two seconds
+ * apart) cover the usual push, and a push that outlasts them leaves the writer
+ * to skip; an editor's autosave checkpoint is announced while the editor's
+ * own lock is held, for as long as the person keeps editing, so a write to
+ * that path cannot be made then. In both cases the path's next announcement —
+ * the editor's release commit when it carries new bytes, the next change to
+ * the file — is when such a writer catches up; a writer that skips must
+ * therefore treat "could not lock" as "not now", as the id-repair already
+ * does. Before this release a batch was announced only where its filesystem
+ * had been handed the notifier, and a checkpoint not at all.
+ *
+ * Every listener is invoked isolated (`callFireAndForget`): one that throws, or
+ * whose promise rejects, is logged and never fails the commit that triggered
+ * it (mirrors the SSE bus's per-subscriber isolation). Firing is
+ * fire-and-forget; nothing awaits a listener.
  */
-import type { AuthUser } from '@bevel-software/platform-shared';
+import type { FilesChange } from '@bevel-software/platform-shared';
+import { callFireAndForget, type FireAndForgetListener } from '../../shared/fire-and-forget.js';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('file-change');
 
-export interface FilesChange {
-  workspaceId: string;
-  branch: string;
-  /** Workspace-relative paths committed in this change (≥1; sorted for batches). */
-  paths: string[];
-  /** Who the change was committed as — a reacting write (id-repair) acts as the same user. */
-  byUser: AuthUser;
-}
+export type { FilesChange };
 
-export type FilesChangedListener = (change: FilesChange) => void;
+/** Fire-and-forget: a listener may answer a promise, which nobody awaits; a rejection is logged like a throw. */
+export type FilesChangedListener = FireAndForgetListener<FilesChange>;
 
 export class FileChangeNotifier {
   private readonly listeners = new Set<FilesChangedListener>();
@@ -43,15 +68,13 @@ export class FileChangeNotifier {
     return () => this.listeners.delete(listener);
   }
 
-  /** Fan a change out to every listener; isolate + log each so one can't break the commit. */
+  /** Fan a change out to every listener — paths sorted and unique, nothing for an empty set; each isolated (a throw or a rejection is logged) so one can't break the commit. */
   emit(change: FilesChange): void {
-    if (change.paths.length === 0) return;
+    const paths = [...new Set(change.paths)].sort();
+    if (paths.length === 0) return;
+    const shaped: FilesChange = { ...change, paths };
     for (const listener of this.listeners) {
-      try {
-        listener(change);
-      } catch (err) {
-        log.error('listener threw:', { err });
-      }
+      callFireAndForget(listener, shaped, log, 'a file-change listener failed:');
     }
   }
 }