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

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

@@ -10,6 +10,8 @@ import {
   getDb,
   type Database,
 } from '../connection.js';
+import { setLogger } from '../../../shared/logging.js';
+import { capturingLogger } from '../../../__tests__/capturing-logger.js';
 
 /**
  * Pools here are never connected: `pg.Pool` opens nothing until a query is
@@ -27,6 +29,34 @@ afterEach(async () => {
   await Promise.all(opened.splice(0).map((db) => closeDb(db)));
 });
 
+describe('an idle connection the server closes', () => {
+  it('is logged, with the error, and let go — the pool has a listener, so the event cannot end the process', () => {
+    // A capturing logger stands in for the process's: the warning is the
+    // behaviour under test, not a side effect to tolerate.
+    const { logger: capturing, lines } = capturingLogger();
+    const previous = setLogger(capturing);
+    try {
+      const db = createDb(URL);
+      opened.push(db);
+      // `pg.Pool` emits an idle client's failure on itself; without a listener
+      // Node throws the event. The terminated-backend error is what a server
+      // restart or a forced drop sends to every idle client.
+      const terminated = Object.assign(new Error('terminating connection due to administrator command'), { code: '57P01' });
+      expect(db.$client.listenerCount('error')).toBe(1);
+      expect(() => db.$client.emit('error', terminated)).not.toThrow();
+      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: terminated },
+        },
+      ]);
+    } finally {
+      setLogger(previous);
+    }
+  });
+});
+
 describe('schema per knowledge base', () => {
   it('searches the schema it was built for, and leaves the default schema to the server', () => {
     const acme = createDb(URL, { schema: 'acme' });

package/src/modules/database/__tests__/migrations-unqualified.test.ts

@@ -1,32 +1,32 @@
-import { describe, it, expect } from 'vitest';
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { coreMigrationsDir } from '../../../assets.js';
-
-/**
- * A knowledge base hosted beside others lives in a schema of its own, found
- * through `search_path`. A migration that spells `public.` runs against the
- * wrong schema there — creating the table in `public`, or guarding on a
- * constraint that lives elsewhere — and the tenant that runs it is the first
- * to find out. So no migration may name a schema: this reads every file the
- * runner would, so the rule cannot be forgotten by the next one.
- */
-describe('core migrations', () => {
-  it('never qualify a table with a schema', async () => {
-    const dir = coreMigrationsDir();
-    const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.sql')).sort();
-    expect(files.length).toBeGreaterThan(0);
-    const offenders: string[] = [];
-    for (const name of files) {
-      const text = await fs.readFile(path.join(dir, name), 'utf8');
-      text.split('\n').forEach((line, i) => {
-        // Bare (`public.users`) and quoted (`"public"."users"`) alike: the
-        // quoted spelling is what drizzle generates, and it is what a live
-        // two-tenant run found still pointing every tenant's foreign keys at
-        // a `public.users` that does not exist there.
-        if (/\bpublic"?\./.test(line)) offenders.push(`${name}:${i + 1}: ${line.trim()}`);
-      });
-    }
-    expect(offenders).toEqual([]);
-  });
-});
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { coreMigrationsDir } from '../../../assets.js';
+
+/**
+ * A knowledge base hosted beside others lives in a schema of its own, found
+ * through `search_path`. A migration that spells `public.` runs against the
+ * wrong schema there — creating the table in `public`, or guarding on a
+ * constraint that lives elsewhere — and the tenant that runs it is the first
+ * to find out. So no migration may name a schema: this reads every file the
+ * runner would, so the rule cannot be forgotten by the next one.
+ */
+describe('core migrations', () => {
+  it('never qualify a table with a schema', async () => {
+    const dir = coreMigrationsDir();
+    const files = (await fs.readdir(dir)).filter((name) => name.endsWith('.sql')).sort();
+    expect(files.length).toBeGreaterThan(0);
+    const offenders: string[] = [];
+    for (const name of files) {
+      const text = await fs.readFile(path.join(dir, name), 'utf8');
+      text.split('\n').forEach((line, i) => {
+        // Bare (`public.users`) and quoted (`"public"."users"`) alike: the
+        // quoted spelling is what drizzle generates, and it is what a live
+        // two-tenant run found still pointing every tenant's foreign keys at
+        // a `public.users` that does not exist there.
+        if (/\bpublic"?\./.test(line)) offenders.push(`${name}:${i + 1}: ${line.trim()}`);
+      });
+    }
+    expect(offenders).toEqual([]);
+  });
+});

package/src/modules/database/connection.ts

@@ -2,6 +2,9 @@ import { sql } from 'drizzle-orm';
 import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './schema.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('database');
 import { PII_CIPHERTEXT_PREFIX, PiiParam, derivePiiKeys, type PiiKeys } from '../../shared/column-crypto.js';
 
 /**
@@ -189,6 +192,15 @@ export function createDb(databaseUrl: string, opts: DbOptions = {}) {
     // operator's own `search_path` stays in force there.
     ...(dbSchema === DEFAULT_DB_SCHEMA ? {} : { options: `-c search_path=${dbSchema}` }),
   });
+  // An IDLE client's failure — its backend terminated by the server (a
+  // restart, a `drop database … with (force)`, an administrator's
+  // `pg_terminate_backend`), a dropped network — is emitted on the pool, and
+  // an 'error' event nobody listens to ends the process. Logged and let go:
+  // the pool has already discarded that client, and the next query opens a
+  // fresh one. A query in flight is not this path; it fails to its caller.
+  pool.on('error', (err) => {
+    log.warn('an idle database connection was closed by the server; the next query opens a new one:', { err });
+  });
   const db = drizzle(pool, { schema });
   schemas.set(db, dbSchema);
   if (keys) piiKeys.set(db, { keys, of: opts.piiKey! });

package/src/modules/database/core-schema.ts

@@ -1,5 +1,5 @@
 /**
- * CORE platform tables — the git-backed workspace/workflow, auth, access,
+ * CORE platform tables — the git-backed workspace and version control, auth, access,
  * change requests, locks, the pending-commits queue, connection keys, MCP
  * OAuth, the Secrets Vault, and the embed's Atlassian account links. A
  * core-only deployment migrates and runs on exactly these tables.
@@ -323,7 +323,7 @@ export const fileLocks = pgTable('file_locks', {
   holderName: encryptedText('holder_name').notNull(),
   // How the lock was acquired. 'edit' (the default) is a normal write hold —
   // the holder is editing and the release publishes their bytes.
-  // 'coordination' is a pure-mutex hold (see IWorkflowService.acquireLock)
+  // 'coordination' is a pure-mutex hold (see IVersionControlService.acquireLock)
   // that grants NO write authority. Persisted on the row — not inferred at
   // release time — so the write/checkpoint/commit-enqueue paths can refuse
   // to treat a coordination hold as write possession for as long as the row

package/src/modules/diff/__tests__/diff.routes.read-gate.test.ts

@@ -2,7 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
-import type { IWorkflowService } from '@bevel-software/platform-shared';
+import type { IVersionControlService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
 import type { AuthService } from '../../auth/auth.service.js';
 import type { IDiffService } from '../diff.interface.js';
@@ -46,7 +46,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createDiffRoutes(diffService, authService, {} as unknown as IWorkflowService, accessControl, KB));
+  app.use('/api', createDiffRoutes(diffService, authService, {} as unknown as IVersionControlService, accessControl, KB));
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));
   });

package/src/modules/diff/__tests__/diff.routes.rejectPathsLocked.test.ts

@@ -2,10 +2,10 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 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 { IDiffService } from '../diff.interface.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../shared/domain-errors.js';
 import { rejectPathsLocked } from '../diff.routes.js';
 
 /**
@@ -21,7 +21,7 @@ const BRANCH = 'alice/revert-test';
 const WORKSPACE_ID = workspaceIdForBranch(BRANCH);
 
 interface Harness {
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   diff: IDiffService;
   calls: string[];
   workspaceDir: string;
@@ -56,7 +56,7 @@ async function makeHarness(overrides: {
     overrides.commit?.();
     return { sha: 'abc', summary } as never;
   });
-  const workflow = { acquireLock, releaseLockNoCommit, commitChanges } as unknown as IWorkflowService;
+  const versionControl = { acquireLock, releaseLockNoCommit, commitChanges } as unknown as IVersionControlService;
 
   const revertPlan = vi.fn(async (_ws: string, paths: string[]) => ({
     workspaceDir,
@@ -66,7 +66,7 @@ async function makeHarness(overrides: {
     deletes: paths.filter((p) => p.endsWith('added.md')),
   }));
   const diff = { revertPlan } as unknown as IDiffService;
-  return { workflow, diff, calls, workspaceDir };
+  return { versionControl, diff, calls, workspaceDir };
 }
 
 describe('rejectPathsLocked', () => {
@@ -82,7 +82,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
 
-    await rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+    await rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
       'knowledge-base/a.md',
       'knowledge-base/added.md',
     ]);
@@ -104,7 +104,7 @@ describe('rejectPathsLocked', () => {
     const h = await makeHarness();
     workspaceDir = h.workspaceDir;
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', []),
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', []),
     ).resolves.toBeUndefined();
     expect(h.calls).toEqual([]);
   });
@@ -119,11 +119,11 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
         'knowledge-base/added.md',
       ]),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
 
     // No commit landed and the disk is untouched — the batch is atomic.
     expect(h.calls.some((c) => c.startsWith('commit:'))).toBe(false);
@@ -131,7 +131,7 @@ describe('rejectPathsLocked', () => {
     await expect(fs.access(path.join(h.workspaceDir, 'knowledge-base/added.md'))).resolves.toBeUndefined();
   }, 15_000);
 
-  it('surfaces a commit failure as a WorkflowValidationError and releases without committing', async () => {
+  it('surfaces a commit failure as a VersionControlValidationError and releases without committing', async () => {
     const h = await makeHarness({
       commit: () => {
         throw new Error('push rejected');
@@ -140,10 +140,10 @@ describe('rejectPathsLocked', () => {
     workspaceDir = h.workspaceDir;
 
     await expect(
-      rejectPathsLocked(h.workflow, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
+      rejectPathsLocked(h.versionControl, h.diff, WORKSPACE_ID, USER, 'knowledge-base', [
         'knowledge-base/a.md',
       ]),
-    ).rejects.toBeInstanceOf(WorkflowValidationError);
+    ).rejects.toBeInstanceOf(VersionControlValidationError);
     // Locks were dropped via the no-commit path after the failure.
     expect(h.calls.filter((c) => c.startsWith('releaseNoCommit:'))).toHaveLength(1);
   });

package/src/modules/diff/diff.routes.ts

@@ -1,10 +1,10 @@
 import express from 'express';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import type { IDiffService } from './diff.interface.js';
 import type { AuthService } from '../auth/index.js';
 import type { IAccessControl } from '../access/index.js';
 import { canReadWorkspacePath, toKbRelative, resolveReadableMap } from '../access-model/index.js';
-import { WorkflowDomainError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlDomainError, VersionControlValidationError } from '../../shared/domain-errors.js';
 import { domainErrorBody } from '../../shared/http-errors.js';
 import { LockingFilesystem } from '../kb-fs/index.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
@@ -13,7 +13,7 @@ import '../auth/index.js';
 function toHttpError(
   err: unknown,
 ): { status: number; body: Record<string, unknown> } {
-  if (err instanceof WorkflowDomainError) {
+  if (err instanceof VersionControlDomainError) {
     return { status: err.status, body: domainErrorBody(err) };
   }
   const message = err instanceof Error ? err.message : 'Unknown error';
@@ -39,7 +39,7 @@ function toHttpError(
  * the first disk mutation, so a restore can never race a concurrent editor.
  */
 export async function rejectPathsLocked(
-  workflowService: IWorkflowService,
+  versionControlService: IVersionControlService,
   diffService: IDiffService,
   workspaceId: string,
   user: AuthUser,
@@ -53,7 +53,7 @@ export async function rejectPathsLocked(
   if (total === 0) return;
   const lockingFs = new LockingFilesystem(
     { basePath: plan.workspaceDir, contained: true },
-    { workflow: workflowService, workspaceId, branch, user, kbDirName },
+    { versionControl: versionControlService, workspaceId, branch, user, kbDirName },
   );
   try {
     await lockingFs.writeFiles(
@@ -71,7 +71,7 @@ export async function rejectPathsLocked(
     const reason = contended
       ? `"${contended[1]}" is being edited by ${contended[2]}`
       : raw.replace(/\.\s*$/, '');
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `Couldn't revert: ${reason}. No changes were committed — try again when the files are free.`,
     );
   }
@@ -88,7 +88,7 @@ export async function rejectPathsLocked(
 export function createDiffRoutes(
   diffService: IDiffService,
   authService: AuthService,
-  workflowService: IWorkflowService,
+  versionControlService: IVersionControlService,
   accessControl: IAccessControl,
   kbDirName: string,
 ): express.Router {
@@ -268,7 +268,7 @@ export function createDiffRoutes(
           current?.changes.map((c) => c.path) ?? [],
         );
       }
-      await rejectPathsLocked(workflowService, diffService, req.params.id, user, kbDirName, paths);
+      await rejectPathsLocked(versionControlService, diffService, req.params.id, user, kbDirName, paths);
       res.json({ session: await diffService.currentSession(req.params.id) });
     } catch (err) {
       const { status, body } = toHttpError(err);

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

@@ -1,7 +1,7 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { AuthUser } from '@bevel-software/platform-shared';
-import { FileLockService } from '../../workflow/file-lock.service.js';
-import { makeFakeLockDb, type FakeLockDb } from '../../workflow/__tests__/fake-file-lock-db.js';
+import { FileLockService } from '../../version-control/file-lock.service.js';
+import { makeFakeLockDb, type FakeLockDb } from '../../version-control/__tests__/fake-file-lock-db.js';
 import { createFileReaderRegistry } from '../../workspace/file-readers/file-reader.registry.js';
 import type { DocExtractOutcome, DocExtractService } from '../../workspace/file-readers/doc-extract.service.js';
 import { makeRolesYamlWriteValidator } from '../../access-model/roles-yaml-guard.js';
@@ -19,8 +19,8 @@ import { EmbedLockedError } from '../embed.errors.js';
  * shares the human's user id, and must not steal their edit). On a real boot
  * every Save from the embed answered 409 against the writer's own Edit lock.
  *
- * So the lock half of the workflow service here is the real `FileLockService`
- * over the in-memory `file_locks` table the workflow suites use — the
+ * So the lock half of the version-control service here is the real `FileLockService`
+ * over the in-memory `file_locks` table the version-control suites use — the
  * contention rules come from the code that enforces them.
  */
 
@@ -55,7 +55,7 @@ function build() {
   };
   // The lock verbs go straight to the real service; release drops the row as
   // the real `releaseLock` does once it has enqueued the commit.
-  const workflowService = {
+  const versionControlService = {
     getLock: vi.fn((id: string, branch: string, path: string) => locks.get(id, branch, path)),
     acquireLock: vi.fn((id: string, branch: string, path: string, user: AuthUser) =>
       locks.acquire(id, branch, path, user),
@@ -80,13 +80,13 @@ function build() {
       isEmailDomainAllowed: () => true,
       isActive: async () => true,
     } as never,
-    workflowService as never,
+    versionControlService as never,
     { remoteBranchExists: async () => false } as never,
     { getUserId: async () => null } as never,
     createFileReaderRegistry(noDocExtract()),
     makeRolesYamlWriteValidator(KB),
   );
-  return { service, workspaceService, workflowService };
+  return { service, workspaceService, versionControlService };
 }
 
 beforeEach(() => {