@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/migrations/meta/_journal.json

@@ -99,6 +99,20 @@
       "when": 1790243482866,
       "tag": "0013_agent_identity_and_key_soft_delete",
       "breakpoints": true
+    },
+    {
+      "idx": 14,
+      "version": "7",
+      "when": 1790667040382,
+      "tag": "0014_change_request_closed_reason",
+      "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "7",
+      "when": 1790892582327,
+      "tag": "0015_account_deactivation",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,8 +52,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.21.0",
-    "@bevel-software/platform-shared": "0.21.0"
+    "@bevel-software/platform-shared": "0.23.0",
+    "@bevel-software/platform-mcp-core": "0.23.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/kb-layout-config.test.ts

@@ -10,7 +10,6 @@ import {
   currentKbLayout,
   isPlatformFile,
   mentionsAgentsFile,
-  ontologyRoots,
   platformFileNames,
   pluginOfPath,
   renderKbLayoutPlaceholders,
@@ -105,7 +104,6 @@ describe('KB layout — configuration', () => {
 
   test('the derived sets follow the configured names rather than snapshotting the defaults', () => {
     configureKbLayout({ knowledgeBaseDir: 'docs', skillsDir: 'skills', pluginsDir: 'plugins' });
-    expect(ontologyRoots(currentKbLayout())).toEqual(['docs', 'Data']);
     expect(reservedRootDirNames(currentKbLayout()).has('plugins')).toBe(true);
     expect(reservedRootDirNames(currentKbLayout()).has('Plugins')).toBe(false);
     // Path rules read the configured name too.

package/src/__tests__/retired-settings.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CoreConfig } from '../core-config.js';
+import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../modules/agent-instructions/compose.js';
+
+/**
+ * What a deployment is left holding after the per-conversation boundary moved
+ * out of these packages: a variable nobody reads, a table nobody touches, and
+ * no wording that names what Hexis no longer knows about.
+ */
+
+const REQUIRED = {
+  KB_REPO_URL: 'https://example.com/org/kb.git',
+  ADMIN_EMAIL: 'root@example.com',
+  ADMIN_PASSWORD: 'sup3r-secret',
+  JWT_SECRET: 'test-jwt-secret',
+  SECRETS_ENC_KEY: 'kToAi8FXWDpDn3A6yQ/60O39bv05N7XzVOIu/0CJrFc=',
+};
+
+let saved: NodeJS.ProcessEnv;
+
+beforeEach(() => {
+  saved = { ...process.env };
+  delete process.env.ONTOLOGY_SESSION_BLOCK;
+  Object.assign(process.env, REQUIRED);
+});
+
+afterEach(() => {
+  process.env = saved;
+});
+
+describe('ONTOLOGY_SESSION_BLOCK is retired', () => {
+  it('is ignored: the config builds either way, with no such setting on it', () => {
+    for (const value of ['false', 'true', 'nonsense']) {
+      process.env.ONTOLOGY_SESSION_BLOCK = value;
+      const config = new CoreConfig();
+      expect(config.kbRepoUrl).toBe(REQUIRED.KB_REPO_URL);
+      expect(config).not.toHaveProperty('ontologySessionBlock');
+    }
+  });
+
+  it('a config built with it set is the same as one built without it', () => {
+    const without = JSON.stringify(new CoreConfig());
+    process.env.ONTOLOGY_SESSION_BLOCK = 'false';
+    expect(JSON.stringify(new CoreConfig())).toBe(without);
+  });
+
+  // BOTH reference docs, so neither can be left promising what the other
+  // retired: `.env.example` is the one a deployment COPIES, so an entry
+  // surviving there is an inert kill-switch somebody sets and believes in.
+  it.each(['docs/configuration.md', '.env.example'])('%s documents no variable named for it', async (doc) => {
+    const here = fileURLToPath(new URL('.', import.meta.url));
+    const text = await readFile(join(here, '../../../../', doc), 'utf8');
+    expect(text).not.toContain('ONTOLOGY_SESSION_BLOCK');
+    expect(text.toLowerCase()).not.toContain('ontolog');
+  });
+});
+
+describe('what an agent or a person reads names no ontology', () => {
+  it('the server instructions do not', () => {
+    expect(PLATFORM_HEADER.toLowerCase()).not.toContain('ontolog');
+    expect(TOOL_PREFIX_LINE.toLowerCase()).not.toContain('ontolog');
+  });
+});
+
+/**
+ * The table stays in this release so that no deployment runs a version in
+ * which neither side has it — but nothing in this package may read or write it
+ * any more. The schema file that declares it is the one and only mention.
+ */
+describe('session_ontology_touches is unused', () => {
+  it('is named by the schema that declares it and by nothing else', async () => {
+    const src = fileURLToPath(new URL('..', import.meta.url));
+    const self = fileURLToPath(import.meta.url);
+    const found: string[] = [];
+    const walk = async (dir: string): Promise<void> => {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await walk(path);
+          continue;
+        }
+        // This file names the table to look for it; it is not a use of it.
+        if (!entry.name.endsWith('.ts') || path === self) continue;
+        const text = await readFile(path, 'utf8');
+        if (text.includes('sessionOntologyTouches') || text.includes('session_ontology_touches')) {
+          found.push(path.slice(src.length));
+        }
+      }
+    };
+    await walk(src);
+    expect(found).toEqual(['modules/database/core-schema.ts']);
+  });
+});

package/src/core/__tests__/gated-boot.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import fsp from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { startCore, type BootableCore } from '../lifecycle.js';
+import { ClassifiedFailure, gitFailure } from '../../shared/git-failure.js';
+import {
+  KbRemoteUnreachableError,
+  bootMaySurvive,
+} from '../../modules/workspace/startup/kb-startup-runner.js';
+
+/**
+ * A boot over a knowledge-base repository the host will not serve.
+ *
+ * On 2026-09-28 a deployment's repository was deleted and replaced. The new
+ * address saved and its connection test passed, but a working copy still
+ * fetching through the OLD address answered "repository not found" inside a
+ * startup step — which was not the one failure a boot survived, so the
+ * container stopped, restarted, and stopped again, taking the setup screen
+ * that would have fixed it with it.
+ *
+ * The rule now: whatever the host ANSWERED about the repository or the
+ * credentials lets the boot come up GATED. Only a failure that says the
+ * knowledge base itself would be written wrong still stops it.
+ */
+
+/** An empty workspaces root, so the beside-the-checkout note finds nothing to say. */
+let workspacesRoot: string;
+
+beforeEach(async () => {
+  workspacesRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'gated-boot-'));
+});
+
+afterEach(async () => {
+  await fsp.rm(workspacesRoot, { recursive: true, force: true });
+});
+
+/** A core whose startup phase fails in a way the test picks. */
+function bootable(runAll: () => Promise<void>) {
+  const retries = { started: 0 };
+  const core: BootableCore = {
+    config: { workspacesRoot },
+    kbDirName: 'knowledge-base',
+    kbStartupRunner: {
+      runAll,
+      retryUntilMaintained: () => {
+        retries.started += 1;
+        return { stop() {} };
+      },
+    } as BootableCore['kbStartupRunner'],
+    workflowService: {
+      closeChangeRequestsWithDeletedBranches: async () => 0,
+    } as BootableCore['workflowService'],
+    pluginJoinRequestJobs: { startSweeping() {} } as BootableCore['pluginJoinRequestJobs'],
+    startupRetry: null,
+  };
+  return { core, retries };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('startCore over a repository the host will not serve', () => {
+  it('comes up gated on "repository not found" raised inside the phase — no restart loop', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const { core, retries } = bootable(async () => {
+      throw new ClassifiedFailure(
+        'KB startup step "groups-to-plugins" failed: git fetch failed: repository not found',
+        gitFailure('not-found'),
+      );
+    });
+
+    // Resolves: the server boots. The setup routes keep it gated on the
+    // runner's standing failure, and the admin can sign in and fix it.
+    await expect(startCore(core)).resolves.toBeUndefined();
+    // And it keeps asking on its own: a repository that is created, or a token
+    // that is granted access to it, needs no settings change on this side.
+    expect(retries.started).toBe(1);
+    expect(core.startupRetry).not.toBeNull();
+  });
+
+  it('comes up gated when the host rejected the credentials', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const { core } = bootable(async () => {
+      throw new ClassifiedFailure('git push failed: Authentication failed', gitFailure('credentials-rejected'));
+    });
+    await expect(startCore(core)).resolves.toBeUndefined();
+    // The same gated contract as the sibling above: the boot hands the retry
+    // handle to the runner rather than leaving the deployment to a restart.
+    // (Handle CREATION is what this pins — the stub counts
+    // `retryUntilMaintained` calls, which cannot tell a handle being made from
+    // a retry loop actually running; that semantics is
+    // `kb-startup-runner.degraded.test.ts`'s.)
+    expect(core.startupRetry).not.toBeNull();
+  });
+
+  it('still STOPS the boot when the failure is about what a step would write', async () => {
+    const { core, retries } = bootable(async () => {
+      throw new ClassifiedFailure(
+        'KB startup step "template-files" failed: the template is missing roles.yaml',
+        { kind: 'step-failed', cause: 'The startup step "template-files" failed.' },
+      );
+    });
+
+    // Booting over this would scaffold something wrong into every branch.
+    await expect(startCore(core)).rejects.toThrow(/template-files/);
+    expect(retries.started).toBe(0);
+  });
+});
+
+describe('bootMaySurvive', () => {
+  it('says yes to the remote being out of reach, whatever raised it', () => {
+    expect(bootMaySurvive(new KbRemoteUnreachableError('could not be reached'))).toBe(true);
+    expect(bootMaySurvive(new ClassifiedFailure('x', gitFailure('unreachable')))).toBe(true);
+  });
+
+  it('says yes to what the host answered about the repository or the credentials', () => {
+    for (const kind of ['not-found', 'credentials-rejected', 'write-refused'] as const) {
+      expect({ kind, survives: bootMaySurvive(new ClassifiedFailure('x', gitFailure(kind))) }).toEqual({
+        kind,
+        survives: true,
+      });
+    }
+  });
+
+  it('says no to everything else — those say the knowledge base would be written wrong', () => {
+    expect(bootMaySurvive(new ClassifiedFailure('x', gitFailure('push-refused-by-policy')))).toBe(false);
+    expect(bootMaySurvive(new ClassifiedFailure('x', gitFailure('unknown')))).toBe(false);
+    expect(bootMaySurvive(new Error('a step threw'))).toBe(false);
+  });
+});

package/src/core/__tests__/lifecycle.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { createShutdown, holdCommitWorkerLease, stopCore, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { createShutdown, holdCommitWorkerLease, holdable, stopCore, withStartupTask, type LeasedWorker } from '../lifecycle.js';
 import { BevelSecretsVariableLoader, registerBevelSecretsVariableLoader } from '../../modules/secrets-vault/secrets-variable-loader.js';
 import type { AdvisoryLease } from '../../modules/database/advisory-lock.js';
 
@@ -158,6 +158,31 @@ describe('holdCommitWorkerLease', () => {
     await handle.stop();
     expect(record.released).toBe(1);
   });
+
+  /**
+   * A process that never held the lease never ran the worker, and can still
+   * be in the middle of a hold on it: a repository move, using the database.
+   * Shutdown ends the pool after this stop, so this stop is what waits.
+   */
+  it('stop() waits for a hold in flight on a worker this process never ran', async () => {
+    const { lease, record } = fakeLease([false]);
+    const worker = holdable({ start: () => undefined, stop: async () => undefined });
+    const clock = manualSleep();
+    const handle = holdCommitWorkerLease(lease, worker, { sleep: clock.sleep, log: () => undefined });
+    await settle();
+
+    let finishMove: () => void = () => undefined;
+    const move = worker.whileHeld(() => new Promise<void>((resolve) => (finishMove = resolve)));
+    await settle();
+    const stopping = handle.stop();
+    await settle();
+    expect(record.released).toBe(0);
+
+    finishMove();
+    await move;
+    await stopping;
+    expect(record.released).toBe(1);
+  });
 });
 
 describe('withStartupTask', () => {
@@ -444,3 +469,147 @@ describe('stopCore', () => {
     expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'startupRetry.stop', 'backgroundJobs.drain', 'db.end']);
   });
 });
+
+/**
+ * Two independent reasons for the commit worker not to run: the lease loop
+ * does not want it (another process holds the queue), or something holds it
+ * still (the deployment is being moved to another repository). It runs
+ * exactly when it is wanted and nothing holds it.
+ */
+describe('holdable', () => {
+  function recorded() {
+    const events: string[] = [];
+    const worker: LeasedWorker = {
+      start: () => void events.push('start'),
+      stop: async () => void events.push('stop'),
+    };
+    return { events, worker: holdable(worker) };
+  }
+
+  it('stops a running worker for the work, and starts it again afterwards', async () => {
+    const { events, worker } = recorded();
+    worker.start();
+    const answer = await worker.whileHeld(async () => {
+      events.push('work');
+      return 42;
+    });
+    expect(answer).toBe(42);
+    expect(events).toEqual(['start', 'stop', 'work', 'start']);
+  });
+
+  it('starts it again when the work fails, and hands the failure on', async () => {
+    const { events, worker } = recorded();
+    worker.start();
+    await expect(
+      worker.whileHeld(async () => {
+        throw new Error('the move failed');
+      }),
+    ).rejects.toThrow('the move failed');
+    expect(events).toEqual(['start', 'stop', 'start']);
+  });
+
+  it('does not start a worker the lease loop never wanted', async () => {
+    const { events, worker } = recorded();
+    await worker.whileHeld(async () => undefined);
+    expect(events).not.toContain('start');
+  });
+
+  it('holds back a start the lease loop asks for during the work, and makes it afterwards', async () => {
+    const { events, worker } = recorded();
+    await worker.whileHeld(async () => {
+      // The lease is taken while the move runs.
+      worker.start();
+      events.push('work');
+    });
+    expect(events).toEqual(['stop', 'work', 'start']);
+  });
+
+  it('leaves it stopped when the lease loop stopped it during the work', async () => {
+    const { events, worker } = recorded();
+    worker.start();
+    // The loop's stop waits for the hold, so it is not awaited from inside it.
+    let stopping: Promise<void> = Promise.resolve();
+    await worker.whileHeld(async () => {
+      stopping = worker.stop();
+      await settle();
+    });
+    await stopping;
+    expect(events.at(-1)).toBe('stop');
+    expect(events.filter((e) => e === 'start')).toHaveLength(1);
+  });
+
+  /**
+   * Shutdown awaits this stop before it ends the database pool. A move still
+   * setting copies aside needs that pool, so the stop does not come back
+   * while a hold is in flight.
+   */
+  it('does not finish stopping while a hold is still in flight', async () => {
+    const { worker } = recorded();
+    worker.start();
+    let finishMove: () => void = () => undefined;
+    const move = worker.whileHeld(() => new Promise<void>((resolve) => (finishMove = resolve)));
+    await settle();
+    let stopped = false;
+    const stopping = worker.stop().then(() => (stopped = true));
+    await settle();
+    expect(stopped).toBe(false);
+    finishMove();
+    await move;
+    await stopping;
+    expect(stopped).toBe(true);
+  });
+
+  it('finishes stopping when the hold in flight fails', async () => {
+    const { worker } = recorded();
+    let failMove: (err: Error) => void = () => undefined;
+    const move = worker.whileHeld(() => new Promise<void>((_, reject) => (failMove = reject)));
+    move.catch(() => undefined);
+    await settle();
+    const stopping = worker.stop();
+    failMove(new Error('the move failed'));
+    await expect(stopping).resolves.toBeUndefined();
+  });
+
+  /**
+   * A worker's stop answers a second caller at once while the first is
+   * still waiting for the commit in flight. A second hold given that answer
+   * would set a working copy aside under that commit.
+   */
+  it('makes a second hold wait for the stop the first one is still waiting on', async () => {
+    const events: string[] = [];
+    let stopped = false;
+    let finishStop: () => void = () => undefined;
+    const worker = holdable({
+      start: () => void events.push('start'),
+      // As the commit worker's: the first call waits, a later one returns.
+      stop: () => {
+        if (stopped) return Promise.resolve();
+        stopped = true;
+        return new Promise<void>((resolve) => (finishStop = resolve));
+      },
+    });
+    worker.start();
+    const first = worker.whileHeld(async () => void events.push('first work'));
+    const second = worker.whileHeld(async () => void events.push('second work'));
+    await settle();
+    // The commit in flight has not finished: neither hold has begun.
+    expect(events).toEqual(['start']);
+    finishStop();
+    await Promise.all([first, second]);
+    expect(events.slice(0, 3).sort()).toEqual(['first work', 'second work', 'start']);
+  });
+
+  it('waits for the last of two overlapping holds before it starts again', async () => {
+    const { events, worker } = recorded();
+    worker.start();
+    let finishFirst: () => void = () => undefined;
+    const first = worker.whileHeld(() => new Promise<void>((resolve) => (finishFirst = resolve)));
+    await settle();
+    await worker.whileHeld(async () => undefined);
+    // The second hold ended and the first is still running: not started yet.
+    expect(events.filter((e) => e === 'start')).toHaveLength(1);
+    finishFirst();
+    await first;
+    expect(events.filter((e) => e === 'start')).toHaveLength(2);
+  });
+});

package/src/core/__tests__/set-aside-root-is-one-place.test.ts

@@ -0,0 +1,63 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setAsideRootFor } from '../../modules/workspace/set-aside-clone.js';
+
+/**
+ * A working copy of a repository that is no longer the configured one is SET
+ * ASIDE rather than deleted, and two places do it: the KB startup phase,
+ * sweeping the whole workspaces root, and the workspace service, refusing to
+ * adopt one on a branch open. They must set aside into ONE directory.
+ *
+ * They did not. The composition root gave the phase a root under the backups
+ * volume and the workspace service nothing at all, so that one fell back to a
+ * sibling of the workspaces root — which in the shipped compose file is the
+ * container's own filesystem, not a volume. A copy the workspace service kept
+ * was therefore gone at the next ordinary recreate, after the setup screen had
+ * told the admin it was being kept and where to find it.
+ *
+ * Read off the source, like `migrations-unqualified.test.ts` reads the
+ * migrations: the wiring is a single call graph that cannot be built in a unit
+ * test (it wants a database, a git host and a disk), and the invariant is
+ * about the TEXT — that the folder is named once and that one name reaches
+ * both. A second literal is exactly how the two came apart.
+ */
+
+const compositionRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../create-core-services.ts',
+);
+
+describe('the set-aside root the composition root wires', () => {
+  it('is named once, and handed to both the startup phase and the workspace service', async () => {
+    const source = await fs.readFile(compositionRoot, 'utf8');
+
+    // Named once. Two occurrences means two expressions, which is how a
+    // change to one of them silently stops applying to the other.
+    const literals = source.match(/'replaced-working-copies'/g) ?? [];
+    expect(literals).toHaveLength(1);
+
+    // And that one name is rooted at the backups volume, which the deployment
+    // mounts — not at the workspaces root's parent, which it does not.
+    expect(source).toMatch(
+      /const replacedWorkingCopiesRoot = path\.join\(config\.backupsRoot, 'replaced-working-copies'\)/,
+    );
+
+    // Both consumers read the one variable.
+    expect(source).toMatch(/new WorkspaceService\([\s\S]*?replacedWorkingCopiesRoot,[\s\S]*?\);/);
+    expect(source).toMatch(/setAsideRoot: replacedWorkingCopiesRoot,/);
+  });
+});
+
+describe('setAsideRootFor', () => {
+  it('uses the root it is given, whatever the workspaces root is', () => {
+    expect(setAsideRootFor('/app/apps/server/workspaces', '/app/apps/server/backups/replaced-working-copies')).toBe(
+      '/app/apps/server/backups/replaced-working-copies',
+    );
+  });
+
+  it('falls back beside the workspaces root — a place a container deployment must not rely on', () => {
+    expect(setAsideRootFor('/app/apps/server/workspaces')).toBe('/app/apps/server/replaced-working-copies');
+  });
+});

package/src/core/core-ports.ts

@@ -7,6 +7,7 @@ import type { ILlmUsageMeter } from '../modules/tool-auth/llm-usage-meter.js';
 import type { AuthProviderPlugin } from '../modules/auth/auth.routes.js';
 import type { IErasureParticipant } from '../modules/auth/account-erasure.service.js';
 import type { IAccountAdmission } from '../modules/auth/account-admission.js';
+import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 
 /**
@@ -34,7 +35,7 @@ import type { OnServerStart } from '../modules/workspace/startup/on-server-start
  *   enterprise root overwrites the `CoreServices` fields (or pushes into the
  *   `authProviders` array) after construction, before the server is built.
  *
- * (Commit-time KB validation and the ontology write block are NOT ports:
+ * (Commit-time KB validation and the agent read/write hooks are NOT ports:
  * they are workflow lifecycle HOOKS the enterprise root registers on
  * `workflowService.hooks` after construction — see
  * `modules/workflow/workflow-hooks.ts`.)
@@ -117,6 +118,15 @@ export interface CorePorts {
    * admin who asked. See `modules/auth/account-admission.ts`.
    */
   accountAdmission?: IAccountAdmission;
+  /**
+   * Whether the deployment may be changed right now. Asked before every
+   * mutating route (bar the ones that sign people in, manage accounts or
+   * configure the deployment) and every write tool. Core default: always.
+   * A host that sells seats answers no while more accounts are on than its
+   * plan allows, so the workspace is read-only until an admin fixes it. See
+   * `modules/write-access/write-access.ts`.
+   */
+  writeAccess?: IWriteAccess;
 }
 
 /**