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

package/dist/shared/fire-and-forget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fire-and-forget.js","sourceRoot":"","sources":["../../src/shared/fire-and-forget.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAI,QAAkC,EAAE,KAAQ,EAAE,GAAY,EAAE,MAAc;IAC7G,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,QAAQ,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,aAAa,CAAC,MAAM,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,GAAY,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAClG,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC7B,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAA8B,CAAC,IAAI,KAAK,UAAU,CAAC;AACnH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.36.1",
+  "version": "0.37.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, version control (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,8 +55,8 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.36.1",
-    "@bevel-software/platform-shared": "0.36.1"
+    "@bevel-software/platform-mcp-core": "0.37.0",
+    "@bevel-software/platform-shared": "0.37.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/capturing-logger.ts

@@ -0,0 +1,36 @@
+import type { ILogger, LogFields } from '../shared/logger.contract.js';
+
+/** One line a capturing logger kept: its level, message, and fields with the child bindings folded in. */
+export interface CapturedLine {
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  fields: LogFields;
+}
+
+/**
+ * A logger that keeps every line instead of printing it — the one capturing
+ * implementation a suite installs through `setLogger` (restoring the previous
+ * one in `finally`) or hands to code that takes an `ILogger`, when what is
+ * logged is the behaviour under test. Children fold their bindings into each
+ * line's fields, so `module: 'database'` is asserted like any other field.
+ */
+export function capturingLogger(): { logger: ILogger; lines: CapturedLine[] } {
+  const lines: CapturedLine[] = [];
+  const make = (bindings: LogFields): ILogger => {
+    const line = (level: CapturedLine['level']) => (message: string, fields: LogFields = {}) => {
+      // Like the production sink, the child's `module` is the logger's own and
+      // a call cannot rename it; every other field a call passes wins.
+      const folded: LogFields = { ...bindings, ...fields };
+      if (bindings.module !== undefined) folded.module = bindings.module;
+      lines.push({ level, message, fields: folded });
+    };
+    return {
+      debug: line('debug'),
+      info: line('info'),
+      warn: line('warn'),
+      error: line('error'),
+      child: (more) => make({ ...bindings, ...more }),
+    };
+  };
+  return { logger: make({}), lines };
+}

package/src/__tests__/real-access.ts

@@ -0,0 +1,16 @@
+import type { ITreeWalker } from '../shared/fs.contract.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import { AccessControlService } from '../modules/access/access-control.service.js';
+
+/**
+ * The access resolver over a real tree, wired the way the composition root
+ * wires it (`core/create-core-services.ts`). A module's suite whose
+ * assertions are what the real rules answer after its service ran — who may
+ * read, who may write — takes it from HERE rather than constructing another
+ * module's implementation itself: the service is on no module entry, by
+ * design (a module receives `IAccessControl` by injection), and this fixture
+ * stands in for the root, as `real-disk.ts` does for the disk.
+ */
+export function realAccessControl(workspace: WorkspaceService, kbDirName: string, disk: ITreeWalker): AccessControlService {
+  return new AccessControlService(workspace, kbDirName, disk);
+}

package/src/__tests__/real-auth.ts

@@ -0,0 +1,13 @@
+import { AuthService } from '../modules/auth/auth.service.js';
+
+/**
+ * The auth service, constructed the way the composition root constructs it
+ * (`core/create-core-services.ts`). A module's suite that drives routes which
+ * take the real service — the access routes, which it guards — takes it from
+ * HERE rather than constructing another module's implementation itself: the
+ * auth entry holds the service's contract and the class behind it is the
+ * root's to wire, as `real-disk.ts` stands in for the root for the disk.
+ */
+export function realAuthService(...args: ConstructorParameters<typeof AuthService>): AuthService {
+  return new AuthService(...args);
+}

package/src/__tests__/real-readers.ts

@@ -0,0 +1,27 @@
+import type { FileReaderRegistry } from '../modules/workspace/index.js';
+import { createFileReaderRegistry } from '../modules/workspace/file-readers/file-reader.registry.js';
+import type { DocExtractOutcome, DocExtractService } from '../modules/workspace/file-readers/doc-extract.service.js';
+
+/**
+ * The file readers, composed the way the composition root composes them
+ * (`core/create-core-services.ts`) over a document extractor. A module's suite
+ * that reads real files through them takes them from HERE rather than
+ * composing another module's internals itself: the registry factory is on no
+ * module entry, by design (a module receives the registry by injection), and
+ * this fixture stands in for the root, as `real-disk.ts` does for the disk.
+ */
+export function realFileReaders(docExtract: DocExtractService = noDocExtract()): FileReaderRegistry {
+  return createFileReaderRegistry(docExtract);
+}
+
+/**
+ * A document extractor that extracts nothing: a suite that reads no
+ * document-format file gets this typed refusal, not a silent empty text.
+ */
+export 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;
+}

package/src/__tests__/real-version-control.ts

@@ -0,0 +1,22 @@
+import type { KbContext } from '../shared/kb-context.js';
+import type { WorkspaceService } from '../modules/workspace/index.js';
+import { GitService } from '../modules/version-control/git/git.service.js';
+import { VersionControlHooks } from '../modules/version-control/version-control-hooks.js';
+
+/**
+ * The version-control collaborators, wired the way the composition root wires
+ * them (`core/create-core-services.ts`): the git service over a workspace and
+ * the lifecycle hooks it consults — where every commit it lands is reported
+ * (`onCommitLanded`). A module's suite that commits to a real repository
+ * takes them from HERE rather than constructing another module's
+ * implementation itself: none of them is on a module entry, by design — they
+ * arrive by injection — and this fixture stands in for the root, as
+ * `real-disk.ts` does for the disk.
+ */
+export function realVersionControlHooks(): VersionControlHooks {
+  return new VersionControlHooks();
+}
+
+export function realGitService(workspace: WorkspaceService, hooks: VersionControlHooks, kb: KbContext): GitService {
+  return new GitService(workspace, hooks, kb);
+}

package/src/core/__tests__/commit-announcements-wired-once.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * A landed commit is announced from ONE place. The git service reports every
+ * commit it lands through `VersionControlHooks.commitLanded`; the composition
+ * root hands that to the file-change notifier with one registration; nothing
+ * else emits on the notifier or calls the hook. A second announcer is how a
+ * batch gets announced twice, and a committer that announces on its own is how
+ * the next one forgets to — both were real findings on the release that made
+ * this rule, so the rule is pinned at the source level.
+ */
+const SRC = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const ROOT = path.join(SRC, 'core', 'create-core-services.ts');
+
+async function shippedSources(dir: string, out: string[] = []): Promise<string[]> {
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name !== '__tests__') await shippedSources(full, out);
+    } else if (/\.ts$/.test(entry.name) && !/\.test\.ts$/.test(entry.name)) out.push(full);
+  }
+  return out;
+}
+
+async function filesContaining(needle: RegExp): Promise<string[]> {
+  const hits: string[] = [];
+  for (const file of await shippedSources(SRC)) {
+    if (needle.test(await fs.readFile(file, 'utf8'))) hits.push(path.relative(SRC, file).replace(/\\/g, '/'));
+  }
+  return hits.sort();
+}
+
+describe('commit announcements are wired once', () => {
+  it('the composition root hands the git layer\'s landed commits to the notifier with one registration', async () => {
+    const source = await fs.readFile(ROOT, 'utf8');
+    const registrations = source.match(/versionControlHooks\.onCommitLanded\(/g) ?? [];
+    expect(registrations).toHaveLength(1);
+    expect(source).toContain('versionControlHooks.onCommitLanded((change) => fileChangeNotifier.emit(change));');
+  });
+
+  it('only the git service reports a landed commit, and only the root registers for it', async () => {
+    expect(await filesContaining(/\.commitLanded\(/)).toEqual(['modules/version-control/git/git.service.ts']);
+    expect(await filesContaining(/\.onCommitLanded\(/)).toEqual(['core/create-core-services.ts']);
+  });
+
+  it('nothing but the root emits on the notifier, and no committer announces on its own', async () => {
+    expect(await filesContaining(/fileChangeNotifier\.emit\(|fileChanges\??\.emit\(/)).toEqual(['core/create-core-services.ts']);
+    expect(await filesContaining(/announceCommitted|announceReleased/)).toEqual([]);
+  });
+});

package/src/core/create-core-services.ts

@@ -1024,6 +1024,10 @@ export async function createCoreServices(
   // id-repair keeps the id namespace collision-free. Subscribers are registered
   // below, once the reacting services exist.
   const fileChangeNotifier = new FileChangeNotifier();
+  // Every commit the git service lands — a save, an autosave checkpoint, a
+  // batch, a merge, a `commit_change` — reaches the notifier through this one
+  // registration, and nothing else emits on it (a test pins both).
+  versionControlHooks.onCommitLanded((change) => fileChangeNotifier.emit(change));
   // Who tells the reviewers of an opened change request: the composition root
   // of a distribution registers its listener here, after this returns (see
   // `ChangeRequestHooks`).
@@ -1040,7 +1044,6 @@ export async function createCoreServices(
     kb,
     changeGate,
     eventBus,
-    fileChangeNotifier,
     // Exposed as `versionControlService.hooks` — the SAME instance GitService and
     // the agent-access gate consult, so a deployment's registrations against
     // it reach every hook point.
@@ -1254,7 +1257,6 @@ export async function createCoreServices(
     pluginSource,
     pluginLocks: pluginProvisionService,
     events: eventBus,
-    fileChanges: fileChangeNotifier,
     // Its own lock: one starter-pack choice at a time, a concern no other
     // service's mutex serialises.
     choosing: new WorkspaceMutex(),

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

@@ -6,13 +6,13 @@ import { joinBranchFor, type IVersionControlService } from '@bevel-software/plat
 
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { testKbContext, TEST_BRANCH_MODEL } from '../../../__tests__/kb-context.js';
-import type { AuthService } from '../../auth/auth.service.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { AuthService } from '../../auth/index.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import type { IAccessControl } from '../access-control.interface.js';
 import type { IAccessRequestLifecycle } from '../access-requests.contract.js';
 import { createAccessRequestRoutes } from '../access-requests.routes.js';
 import { ChangeRequestConflictsError } from '../../../shared/domain-errors.js';
-import { pendingProposals } from '../../plugins/join-proposals.js';
+import { pendingProposals } from '../../plugins/index.js';
 
 /**
  * Asking for Can edit or Owner on an item, and what the editors then see.

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

@@ -1,11 +1,11 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { VersionControlService } from '../../version-control/version-control.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { VersionControlService } from '../../version-control/index.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';
@@ -110,8 +110,8 @@ describe('GroupsAdminService', () => {
     service = new GroupsAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -272,7 +272,7 @@ describe('GroupsAdminService', () => {
       '---\nread:\n  - deny everyone\n  - Sara <sara@x.io>\nwrite:\n  - Sara <sara@x.io>\n---\n',
     );
     await write(repo, 'Plugins/Sara/Notes.md', "---\nread: ['group/GTM Team']\n---\n# Notes\n");
-    const access = new AccessControlService(stubWorkspace(root) as never, KB, new NodeFs());
+    const access = new AccessControlService(stubWorkspace(root) as never, KB, realDisk());
     expect(await access.canRead(workspaceIdForBranch(DEFAULT_BRANCH), ADMIN.email, 'Plugins/Sara/Notes.md')).toBe(false);
 
     await service.renameGroup(ADMIN, 'gtm team', 'Go To Market');
@@ -289,7 +289,7 @@ describe('GroupsAdminService', () => {
     // `assertCanWriteAtRef`); this stub does the same through the live model.
     function gatedService(): { gated: GroupsAdminService; gatedCommits: { summary: string }[] } {
       const workspace = stubWorkspace(root);
-      const access = new AccessControlService(workspace as never, KB, new NodeFs());
+      const access = new AccessControlService(workspace as never, KB, realDisk());
       const versionControl = stubVersionControl();
       const svc = versionControl.svc as unknown as Record<string, unknown>;
       svc.commitChanges = async (ws: string, user: AuthUser, summary: string, onlyPaths: string[] = []) => {
@@ -300,7 +300,7 @@ describe('GroupsAdminService', () => {
         versionControl.commits.push({ summary });
         return {} as unknown;
       };
-      const gated = new GroupsAdminService(workspace, versionControl.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH);
+      const gated = new GroupsAdminService(workspace, versionControl.svc, access, realDisk(), KB, () => DEFAULT_BRANCH);
       return { gated, gatedCommits: versionControl.commits };
     }
 
@@ -395,8 +395,8 @@ describe('GroupsAdminService', () => {
     const svc = new GroupsAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -442,8 +442,8 @@ describe('GroupsAdminService', () => {
     const svc = new GroupsAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -482,8 +482,8 @@ describe('GroupsAdminService', () => {
     const svc = new GroupsAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -538,8 +538,8 @@ describe('groups roster referencedBy — the mirror of the roles roster attribut
       const svc = new GroupsAdminService(
         workspace,
         stubVersionControl().svc,
-        new AccessControlService(workspace as never, KB, new NodeFs()),
-        new NodeFs(),
+        new AccessControlService(workspace as never, KB, realDisk()),
+        realDisk(),
         KB,
         () => DEFAULT_BRANCH,
       );
@@ -581,8 +581,8 @@ describe('groups roster referencedBy — the mirror of the roles roster attribut
       await write(repo2, 'team/access.md', '---\nwrite:\n  - Reviewer\n---\n');
       await write(repo2, 'secret/Plan.md', '---\nread:\n  - deny everyone\n  - Reviewer\n---\n# Plan\n');
       const workspace = stubWorkspace(root2);
-      const access = new AccessControlService(workspace as never, KB, new NodeFs());
-      const svc = new GroupsAdminService(workspace, stubVersionControl().svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH);
+      const access = new AccessControlService(workspace as never, KB, realDisk());
+      const svc = new GroupsAdminService(workspace, stubVersionControl().svc, access, realDisk(), KB, () => DEFAULT_BRANCH);
       const rowsFor = async (email: string) =>
         (await svc.getRoster(email)).groups.find((g) => g.canonical === 'reviewer')!.bareNameResolvesToRole;
 
@@ -620,8 +620,8 @@ describe('groups roster referencedBy — the mirror of the roles roster attribut
       const svc = new GroupsAdminService(
         workspace,
         stubVersionControl().svc,
-        new AccessControlService(workspace as never, KB, new NodeFs()),
-        new NodeFs(),
+        new AccessControlService(workspace as never, KB, realDisk()),
+        realDisk(),
         KB,
         () => DEFAULT_BRANCH,
       );

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

@@ -1,12 +1,12 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { VersionControlService } from '../../version-control/version-control.service.js';
-import type { VersionControlEventBus } from '../../version-control/event-bus.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { VersionControlService } from '../../version-control/index.js';
+import type { VersionControlEventBus } from '../../version-control/index.js';
 import type { FileTreeEntry, VersionControlEventPayload } from '@bevel-software/platform-shared';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { AccessControlService } from '../access-control.service.js';
@@ -168,10 +168,10 @@ describe('RolesAdminService', () => {
     repo = path.join(workspaceDir, KB);
     await write(repo, 'roles.yaml', ROLES);
     ws = stubWorkspace(workspaceDir);
-    access = new AccessControlService(ws, KB, new NodeFs());
+    access = new AccessControlService(ws, KB, realDisk());
     versionControl = stubVersionControl();
     bus = stubEventBus();
-    svc = new RolesAdminService(ws, versionControl.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH, bus.bus, [
+    svc = new RolesAdminService(ws, versionControl.svc, access, realDisk(), KB, () => DEFAULT_BRANCH, bus.bus, [
       'recovery-admin@example.com',
     ]);
   });
@@ -193,7 +193,7 @@ describe('RolesAdminService', () => {
     // `DEFAULT_BRANCH` and froze it — every roles route then failed branch
     // validation with `Invalid branch name "": empty name` until a restart.
     let branch = '';
-    const late = new RolesAdminService(ws, versionControl.svc, access, new NodeFs(), KB, () => branch, bus.bus);
+    const late = new RolesAdminService(ws, versionControl.svc, access, realDisk(), KB, () => branch, bus.bus);
     branch = DEFAULT_BRANCH;
     const roster = await late.getRoster(ADMIN.email);
     expect(roster.map((r) => r.canonical)).toEqual(['admin', 'sales']);
@@ -257,7 +257,7 @@ describe('RolesAdminService', () => {
     const corrupt = 'roles:\n  Admin:\n    - a@x.eu\n  Admin:\n    - b@x.eu\n';
     await write(repo, 'roles.yaml', corrupt);
     access.invalidate(WS);
-    const adminless = new RolesAdminService(ws, versionControl.svc, access, new NodeFs(), KB, () => DEFAULT_BRANCH, bus.bus);
+    const adminless = new RolesAdminService(ws, versionControl.svc, access, realDisk(), KB, () => DEFAULT_BRANCH, bus.bus);
     // 409, not 500: the route helper hides >=500 bodies behind a generic
     // message, and this break-glass refusal must reach the operator verbatim.
     await expect(adminless.recover(ADMIN)).rejects.toMatchObject({
@@ -572,8 +572,8 @@ describe('roster referencedBy under group shadowing', () => {
     svc = new RolesAdminService(
       ws,
       stubVersionControl().svc,
-      new AccessControlService(ws, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(ws, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
       stubEventBus().bus,
@@ -630,8 +630,8 @@ describe('Admin fixed members — the deployment admin', () => {
     return new RolesAdminService(
       ws,
       versionControl.svc,
-      new AccessControlService(ws, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(ws, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
       stubEventBus().bus,

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

@@ -1,11 +1,11 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { VersionControlService } from '../../version-control/version-control.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { VersionControlService } from '../../version-control/index.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';
@@ -131,8 +131,8 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     service = new RolesAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -216,8 +216,8 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     const svc = new RolesAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -280,8 +280,8 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     const svc = new RolesAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );
@@ -305,8 +305,8 @@ describe('RolesAdminService — capabilities, group assignment, conversion', ()
     const svc = new RolesAdminService(
       workspace,
       versionControl.svc,
-      new AccessControlService(workspace as never, KB, new NodeFs()),
-      new NodeFs(),
+      new AccessControlService(workspace as never, KB, realDisk()),
+      realDisk(),
       KB,
       () => DEFAULT_BRANCH,
     );

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

@@ -7,13 +7,13 @@ import express from 'express';
 import { PgDialect } from 'drizzle-orm/pg-core';
 import type { SQL } from 'drizzle-orm';
 import { describe, it, expect, afterEach, vi } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.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 { VersionControlService } from '../../version-control/version-control.service.js';
-import type { VersionControlEventBus } from '../../version-control/event-bus.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import { realAuthService } from '../../../__tests__/real-auth.js';
+import type { VersionControlService } from '../../version-control/index.js';
+import type { VersionControlEventBus } from '../../version-control/index.js';
 import type { FileTreeEntry } from '@bevel-software/platform-shared';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
@@ -64,7 +64,7 @@ async function makeHarness(
   const realAccess = new AccessControlService(
     { getWorkspacePath: async () => workspaceDir, readFile: async () => ROLES } as unknown as WorkspaceService,
     KB,
-    new NodeFs(),
+    realDisk(),
   );
   const accessControl = {
     // Admin gate: the route's assertCanMutate calls canWrite('roles.yaml').
@@ -173,7 +173,7 @@ async function makeHarness(
 
   // The real auth service over the same double, so the promotion's switch
   // lock and read run as they do in production (`whileSwitchedOn`).
-  const authService = new AuthService(db, { jwtSecret: 'test', adminEmail: '', adminPassword: '', allowedEmailDomains: [] });
+  const authService = realAuthService(db, { jwtSecret: 'test', adminEmail: '', adminPassword: '', allowedEmailDomains: [] });
   vi.spyOn(authService, 'getUserById').mockImplementation(async () => ADMIN);
 
   const app = express();
@@ -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, versionControlService, eventBus, db, testKbContext({ kbDirName: KB }), new NodeFs()));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, authService, versionControlService, eventBus, db, testKbContext({ kbDirName: KB }), realDisk()));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

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

@@ -4,9 +4,9 @@ import path from 'node:path';
 import os from 'node:os';
 
 import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import type { AccessControlService } from '../access-control.service.js';
-import type { VersionControlEventBus } from '../../version-control/event-bus.js';
+import type { VersionControlEventBus } from '../../version-control/index.js';
 import { createSyncedGroupsCommitter } from '../synced-groups-committer.js';
 import { PushNeedsAgentResolutionError, VersionControlValidationError } from '../../../shared/domain-errors.js';
 

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

@@ -1,12 +1,12 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { VersionControlService } from '../../version-control/version-control.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { VersionControlService } from '../../version-control/index.js';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
@@ -167,8 +167,8 @@ describe('UserAccessRemovalService', () => {
 
   const read = (rel: string) => fs.readFile(path.join(repo, rel), 'utf-8');
 
-  function build(versionControl = stubVersionControl(), owners: string[] = ['owner@x.io'], disk: ITreeWalker = new NodeFs()) {
-    const access = new AccessControlService(workspace as never, KB, new NodeFs());
+  function build(versionControl = stubVersionControl(), owners: string[] = ['owner@x.io'], disk: ITreeWalker = realDisk()) {
+    const access = new AccessControlService(workspace as never, KB, realDisk());
     return {
       versionControl,
       service: new UserAccessRemovalService(workspace, versionControl.svc, access, disk, KB, () => DEFAULT_BRANCH, undefined, owners),
@@ -356,7 +356,7 @@ describe('UserAccessRemovalService', () => {
   });
 
   it('refuses to commit a partial cleanup when a folder cannot be listed', async () => {
-    const real = new NodeFs();
+    const real = realDisk();
     const holey = {
       walkKb: async (...args: Parameters<ITreeWalker['walkKb']>) => {
         const result = await real.walkKb(...args);

package/src/modules/database/__tests__/connection.pg.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { sql } from 'drizzle-orm';
+import { closeDb, createDb } from '../connection.js';
+import { setLogger } from '../../../shared/logging.js';
+import { capturingLogger } from '../../../__tests__/capturing-logger.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, withPgAdmin } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * The recovery the pool's error listener promises, on a real Postgres: a
+ * pooled client the server terminates while it idles — a restart, a forced
+ * database drop, an administrator's `pg_terminate_backend` — is logged and
+ * let go, and the next query opens a fresh connection and succeeds. The unit
+ * case in `connection.test.ts` pins the listener on a pool that never
+ * connected; this one pins what the listener is for.
+ *
+ * Runs where `TEST_DATABASE_URL` names a server; only connects to the
+ * database it names and terminates this test's own backend. Writes nothing.
+ */
+describe.skipIf(!PG_ADMIN_URL)('a pooled connection the server terminates', () => {
+  it(
+    'is logged with the error, and the next query succeeds on a new connection',
+    async () => {
+      const { logger: capturing, lines } = capturingLogger();
+      const previous = setLogger(capturing);
+      const db = createDb(PG_ADMIN_URL!);
+      try {
+        const backendPid = async () => Number((await db.execute(sql`select pg_backend_pid() as pid`)).rows[0]!.pid);
+        // The query's client now idles in the pool; the server ends it.
+        const first = await backendPid();
+        const noticed = new Promise<void>((resolve) => db.$client.once('error', () => resolve()));
+        // The signal is checked before the wait: a backend that was not
+        // terminated would otherwise surface as a timeout, not as the cause.
+        const { rows } = await withPgAdmin((admin) =>
+          admin.query<{ pg_terminate_backend: boolean }>('select pg_terminate_backend($1)', [first]),
+        );
+        expect(rows[0]?.pg_terminate_backend).toBe(true);
+        await noticed;
+
+        const second = await backendPid();
+        expect(second).not.toBe(first);
+        expect(lines).toEqual([
+          {
+            level: 'warn',
+            message: 'an idle database connection was closed by the server; the next query opens a new one:',
+            fields: { module: 'database', err: expect.objectContaining({ code: '57P01' }) },
+          },
+        ]);
+      } finally {
+        await closeDb(db);
+        setLogger(previous);
+      }
+    },
+    PG_TEST_TIMEOUT,
+  );
+});