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

package/src/core/lifecycle.ts

@@ -1,8 +1,17 @@
 import type { Server } from 'node:http';
-import type { Database } from '../modules/database/connection.js';
+import { closeDb, type Database } from '../modules/database/connection.js';
 import type { AdvisoryLease } from '../modules/database/advisory-lock.js';
+import { KbRemoteUnreachableError, type KbStartupRunner } from '../modules/workspace/startup/kb-startup-runner.js';
+import { noteBesideCheckout } from '../modules/workspace/startup/beside-checkout.js';
+import { unregisterBevelSecretsVariableLoader } from '../modules/secrets-vault/secrets-variable-loader.js';
+import type { WorkflowService } from '../modules/workflow/workflow.service.js';
+import type { PluginJoinRequestJobs } from '../modules/plugins/join-request-jobs.service.js';
+import { printable } from '../shared/printable.js';
 import { logger } from '../shared/logging.js';
 
+const startupLog = logger('kb-startup');
+const crLog = logger('cr');
+
 /**
  * The process lifecycle: who may drain the commit queue, and how the process
  * stops.
@@ -193,25 +202,166 @@ export function withStartupTask(
   };
 }
 
-export interface ShutdownDeps {
-  /** The listening server — stops accepting, then drops what is connected. */
-  server: Pick<Server, 'close' | 'closeAllConnections'>;
+/**
+ * What one knowledge base's graph needs of itself to be STARTED: the boot
+ * side effects that used to run inside `createCoreServer`, named so a host
+ * can run them for a graph it builds on demand, and stop them again.
+ */
+export interface BootableCore {
+  config: { workspacesRoot: string };
+  kbDirName: string;
+  kbStartupRunner: Pick<KbStartupRunner, 'runAll' | 'retryUntilMaintained'>;
+  workflowService: Pick<WorkflowService, 'closeChangeRequestsWithDeletedBranches'>;
+  pluginJoinRequestJobs: Pick<PluginJoinRequestJobs, 'startSweeping'>;
+  /**
+   * The startup phase's retry, when the boot survived an unreachable remote
+   * and is asking again on a timer; null otherwise. Set by {@link startCore},
+   * stopped by {@link stopCore}.
+   */
+  startupRetry: { stop(): void } | null;
+}
+
+/**
+ * Bring a built graph up: the distribution's boot hook, the note about what
+ * sits beside a checkout, the knowledge-base startup phase with its
+ * unreachable-remote fallback, the deleted-branch sweep and the join-request
+ * jobs. `createCoreServer` runs this for a single-tenant deployment; a host
+ * serving several knowledge bases runs it when a tenant is activated.
+ *
+ * Throws to stop the boot on every failure but an unreachable remote — the
+ * container's restart policy is the retry — see `kb-startup-runner.ts`.
+ */
+export async function startCore<C extends BootableCore>(
+  core: C,
+  ext: { onBoot?(core: C): Promise<void> | void } = {},
+): Promise<void> {
+  // Overlay boot-time side effects (startup reconciles, periodic sweeps).
+  await ext.onBoot?.(core);
+
+  // What is already sitting beside a checkout, named once per boot and touched
+  // by nothing. Outside the KB startup phase below on purpose: that phase is
+  // gated on the branch model and the repository URL, and a deployment whose
+  // setup never finished — or whose remote is down — is exactly one whose
+  // strays would otherwise go unmentioned. A diagnostic never stops a boot, so
+  // an unreadable workspaces root is logged and the boot carries on.
+  try {
+    await noteBesideCheckout(core.config.workspacesRoot, core.kbDirName);
+  } catch (err) {
+    // `printable`, because the message quotes a path off the disk (an ENOENT
+    // or EACCES names the file it failed on) and a name carrying a control
+    // character would forge a second line of the operator's log.
+    startupLog.warn('could not look for content beside the checkouts:', {
+      detail: printable(err instanceof Error ? err.message : String(err)),
+    });
+  }
+
+  // The KB startup phase — AFTER the distribution's onBoot, because a FATAL
+  // template finding raised there must stop the boot before anything seeds
+  // from that template; the runner then brings every branch up to this build
+  // before any route can serve KB content. Throws to stop the boot (the
+  // container's restart policy is the retry) — see kb-startup-runner.ts.
+  //
+  // Runs in the booting process whether or not it holds the commit-worker
+  // lease, so on a redeploy it overlaps the outgoing holder's commits for the
+  // seconds it takes — the documented window at `holdCommitWorkerLease`.
+  try {
+    await core.kbStartupRunner.runAll();
+  } catch (err) {
+    // The one failure a boot survives: the remote cannot be reached. That
+    // says nothing about the knowledge base — what we would write is not
+    // known to be wrong, we cannot get there — so refusing to boot only took
+    // away the login and setup screens an operator needs to fix it (a
+    // rotated token, say). The deployment comes up GATED: the setup routes
+    // read the runner's standing failure and keep the app shut, the setup
+    // screen shows why, saving it retries, and the runner keeps trying on
+    // its own. Every other failure still stops the boot, because it means
+    // the template or a step would write something wrong.
+    if (!(err instanceof KbRemoteUnreachableError)) throw err;
+    startupLog.error('booting UNMAINTAINED and gated — the knowledge-base remote could not be reached:', {
+      detail: err.message,
+    });
+    // Kept on the graph so that stopping the graph stops the asking: a
+    // retry that outlived its graph would clone into a workspaces folder
+    // nobody serves any more.
+    core.startupRetry = core.kbStartupRunner.retryUntilMaintained();
+  }
+
+  // Close change requests whose source branch has been deleted. SEQUENCED
+  // AFTER the startup phase above, for two reasons: the sweep's fresh fetch
+  // lazily bootstraps and fetches the same default-branch clone the runner
+  // maintains (kicking it off earlier races the runner's clone/fetch of that
+  // very directory), and on a brand-new deployment it would run before the
+  // empty remote is seeded, fail its clone, swallow the error, and leave
+  // deleted-branch CRs open for the whole process. Still not awaited from
+  // here on: a slow or unreachable remote must not hold up the server —
+  // nothing downstream depends on the result, and the requests it closes
+  // have been unusable since the branch went away, so landing a few seconds
+  // into uptime is soon enough. Errors are swallowed inside the sweep, which
+  // fails safe by closing nothing.
+  void core.workflowService
+    .closeChangeRequestsWithDeletedBranches()
+    .then((n) => {
+      if (n > 0) {
+        crLog.info(`closed ${n} change request${n === 1 ? '' : 's'} with a deleted branch`);
+      }
+    })
+    .catch((err) => crLog.warn('deleted-branch sweep failed:', { err }));
+
+  // Recorded join requests that are still owed, resumed — now, and then on a
+  // timer. SEQUENCED AFTER the startup phase for the same reason as the sweep
+  // above: the work needs the default-branch clone the runner maintains and
+  // the plugin catalog read from it, and a sweep that ran first would refuse
+  // every row for a knowledge base that simply was not ready — telling people
+  // their request could not be sent when nothing had gone wrong with it.
+  //
+  // ON A TIMER rather than at boot alone, because boot cannot cover the
+  // redeploy: this process sweeps while the outgoing one still holds a
+  // record, skips it (correctly — two servers must not do git on one branch),
+  // and the outgoing process then exits mid-work. Nothing else would look at
+  // that row again. The requester cannot prompt it either: a pending record
+  // shows them the "Requested" card, not a button.
+  //
+  // Not awaited, and nothing to report here but the failure to read the table
+  // at all: a first request from a person is a full clone, nothing else at
+  // boot depends on it, and each row records its own outcome.
+  core.pluginJoinRequestJobs.startSweeping();
+}
+
+/**
+ * What one knowledge base's graph holds that must be let go of when it
+ * stops: the pieces {@link stopCore} winds down, in the order it winds
+ * them down. `createShutdown` takes the same, plus the listening server.
+ */
+export interface CoreStopDeps {
   /** The lease loop from {@link holdCommitWorkerLease}: its stop finishes the in-flight commit and releases the lease. */
   commitWorker: Pick<LeaseLoopHandle, 'stop'>;
   /**
    * Background work to wind down before the pool goes — the join-request
-   * sweep and its jobs, today. The timer is stopped after the server so
-   * nothing new is scheduled, then the jobs already running are awaited
-   * (within the budget) so the pool is not ended under a clone or a push
-   * that is still writing to it. Optional: a caller that has not built them
-   * yet passes nothing.
+   * sweep and its jobs, today. The timer is stopped first so nothing new is
+   * scheduled, then the jobs already running are awaited (within the budget)
+   * so the pool is not ended under a clone or a push that is still writing
+   * to it. Optional: a caller that has not built them yet passes nothing.
    */
   backgroundJobs?: { stopSweeping(): void; drain(): Promise<void> };
+  /** The startup phase's retry, if the boot left one asking — see {@link BootableCore.startupRetry}. */
+  startupRetry?: { stop(): void } | null;
   /** The database — its pool is ended last, once nothing above can still need it. */
   db: Pick<Database, '$client'>;
+  /**
+   * The scope this graph's secrets vault was registered under with the UTCP
+   * variable loader (see `secrets-variable-loader.ts`); forgotten on stop so
+   * a descriptor that outlives the graph resolves nothing. Optional: a
+   * single-tenant process exits right after, and has nothing to forget.
+   */
+  secretsScope?: string;
   log?: (message: string) => void;
 }
 
+export interface ShutdownDeps extends CoreStopDeps {
+  /** The listening server — stops accepting, then drops what is connected. */
+  server: Pick<Server, 'close' | 'closeAllConnections'>;
+}
+
 export interface ShutdownOptions {
   /**
    * Total time the sequence may take. Default 8s: Docker's `stop_grace_period`
@@ -261,6 +411,60 @@ async function bounded(promise: Promise<unknown>, ms: number, label: string, log
  *      died mid-commit, now the exception rather than the rule.
  *   3. End the pool.
  */
+/**
+ * Let go of everything a graph holds, in order, within `remaining()`.
+ * The order is the point — see {@link createShutdown} for why each step
+ * sits where it does.
+ */
+async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m: string) => void): Promise<void> {
+  // First, and BEFORE the commit worker is stopped. Stopping that worker
+  // awaits an in-flight commit and can spend most of the remaining budget
+  // doing it; a sweep tick firing inside that window reads the still-open
+  // pool and starts fresh clone/commit/push work that the end of the
+  // sequence then kills mid-git. Nothing new can be recorded once the
+  // server is closed (or the tenant is no longer routed to), so this is the
+  // earliest point the interval is dead weight. Synchronous and unfailing
+  // — it just clears an interval — so it needs no budget of its own.
+  deps.backgroundJobs?.stopSweeping();
+  // A startup phase still asking for an unreachable remote stops asking:
+  // synchronous, and nothing after it must be able to clone into a
+  // workspaces folder that is about to belong to nobody.
+  deps.startupRetry?.stop();
+  // Clearing the interval stops future ticks; it does nothing to a job a
+  // tick already started, which holds a claim it heartbeats through the
+  // pool and is mid-clone or mid-push. Awaited here, in the budget: a job
+  // that finishes releases or marks its row; one that cannot in time is
+  // killed with the process and its claim goes stale for the next sweep
+  // — which is the recovery every crash already gets.
+  if (deps.backgroundJobs) {
+    await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
+  }
+  await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
+  if (deps.secretsScope !== undefined) unregisterBevelSecretsVariableLoader(deps.secretsScope);
+  await bounded(closeDb(deps.db), remaining(), 'ending the database pool', log);
+}
+
+export interface StopCoreOptions {
+  /** Total time the stop may take. Default: the shutdown's 8s. */
+  deadlineMs?: number;
+}
+
+/**
+ * Stop one knowledge base's graph without stopping the process: the
+ * shutdown sequence minus closing the server. What a host runs when it
+ * evicts a tenant, and what {@link createShutdown} runs after the server
+ * has closed. Bounded like the shutdown, so a step that hangs cannot hold
+ * the host's event loop hostage.
+ */
+export async function stopCore(core: CoreStopDeps, opts: StopCoreOptions = {}): Promise<void> {
+  const log = core.log ?? ((message: string) => logger('lifecycle').info(message));
+  const deadlineMs = opts.deadlineMs ?? DEFAULT_SHUTDOWN_DEADLINE_MS;
+  const startedAt = Date.now();
+  const remaining = () => Math.max(0, deadlineMs - (Date.now() - startedAt));
+  await releaseCore(core, remaining, log);
+  log(`graph stopped in ${Date.now() - startedAt}ms`);
+}
+
 export function createShutdown(
   deps: ShutdownDeps,
   opts: ShutdownOptions = {},
@@ -284,26 +488,7 @@ export function createShutdown(
         'closing the server',
         log,
       );
-      // Immediately after the server, and BEFORE the commit worker is stopped.
-      // Stopping that worker awaits an in-flight commit and can spend most of
-      // the remaining budget doing it; a sweep tick firing inside that window
-      // reads the still-open pool and starts fresh clone/commit/push work that
-      // the `process.exit()` at the end of the sequence then kills mid-git.
-      // Nothing new can be recorded once the server is closed, so this is the
-      // earliest point the interval is dead weight. Synchronous and unfailing
-      // — it just clears an interval — so it needs no budget of its own.
-      deps.backgroundJobs?.stopSweeping();
-      // Clearing the interval stops future ticks; it does nothing to a job a
-      // tick already started, which holds a claim it heartbeats through the
-      // pool and is mid-clone or mid-push. Awaited here, in the budget: a job
-      // that finishes releases or marks its row; one that cannot in time is
-      // killed with the process and its claim goes stale for the next sweep
-      // — which is the recovery every crash already gets.
-      if (deps.backgroundJobs) {
-        await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
-      }
-      await bounded(deps.commitWorker.stop(), remaining(), 'stopping the commit worker', log);
-      await bounded(deps.db.$client.end(), remaining(), 'ending the database pool', log);
+      await releaseCore(deps, remaining, log);
 
       log(`shutdown complete in ${Date.now() - startedAt}ms`);
     })();

package/src/core/public-config.ts

@@ -1,4 +1,4 @@
-import { DEFAULT_BRANCH, PROTECTED_BRANCHES, currentKbLayout } from '@bevel-software/platform-shared';
+import type { KbContext } from '../shared/kb-context.js';
 
 /** The two addresses the server derives once and hands to {@link publicConfig}. */
 export interface PublicConfigAddresses {
@@ -24,19 +24,22 @@ export interface PublicConfigAddresses {
  * means a rebuild.
  *
  * A pure function of its inputs, so the payload is testable without a server.
+ * `kb` is read at call time, not captured: the branch model arrives from the
+ * setup screen on a fresh deployment, and the next `/api/config` after that
+ * save has to carry it.
  */
-export function publicConfig({ marketplaceGitUrl, mcpUrl }: PublicConfigAddresses) {
+export function publicConfig(kb: KbContext, { marketplaceGitUrl, mcpUrl }: PublicConfigAddresses) {
   return {
     branchModel: {
-      defaultBranch: DEFAULT_BRANCH,
-      protectedBranches: [...PROTECTED_BRANCHES],
+      defaultBranch: kb.defaultBranch,
+      protectedBranches: [...kb.protectedBranches],
     },
     /**
      * The three renameable KB roots, for the same reason as the branch
      * model: the file tree, the library router and every path rule read
      * them, and they used to be compile-time constants.
      */
-    kbLayout: currentKbLayout(),
+    kbLayout: kb.layout,
     /**
      * The per-user marketplace git remote (see modules/marketplace). Same
      * derivation as `mcpUrl`: our address, userinfo stripped; the caller

package/src/core-config.ts

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { defaultKbTemplateDir } from './assets.js';
 import { assertKeyDecodesTo32Bytes } from './shared/token-crypto.js';
 import { DEFAULT_GIT_TIMEOUT_MS } from './modules/workflow/git/node-git-runner.js';
+import { DEFAULT_DB_SCHEMA, assertSchemaName } from './modules/database/connection.js';
 import { logger } from './shared/logging.js';
 
 const log = logger('config');
@@ -57,6 +58,88 @@ export function withoutUserinfo(url: string): string {
   return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, '$1');
 }
 
+/**
+ * Everything ONE knowledge base's service graph is built from — the values
+ * that differ between two knowledge bases a process might host. A
+ * single-tenant deployment reads them from the environment ({@link CoreConfig});
+ * a host serving several builds one of these per tenant from its registry.
+ * `createCoreServices` takes this shape, so the two are the same code path.
+ *
+ * `port`, `nodeEnv` and `trustProxy` are process facts a graph still needs
+ * (the loopback address the MCP proxy dials, cookie flags, the proxy hop
+ * count its Express app trusts), so they appear here as well as on
+ * {@link ProcessConfig}: a tenant's config carries the values of the process
+ * it runs in.
+ */
+export interface TenantConfig {
+  readonly port: number;
+  readonly databaseUrl: string;
+  /** The Postgres schema this knowledge base's tables live in. `public` for a single-tenant deployment. */
+  readonly dbSchema: string;
+  readonly nodeEnv: string;
+  readonly tenantId: string;
+  /** The credential prefixes derived from `tenantId` — see the getters on {@link CoreConfig}. */
+  readonly externalApiKeyPrefix: string;
+  readonly internalTokenPrefix: string;
+  readonly uploadTokenPrefix: string;
+  readonly mcpOAuthTokenPrefix: string;
+  readonly workspacesRoot: string;
+  readonly backupsRoot: string;
+  readonly spillRoot: string;
+  readonly docExtractCacheRoot: string;
+  readonly jwtSecret: string;
+  readonly adminEmail: string;
+  readonly adminPassword: string;
+  readonly oidcIssuerUrl: string;
+  readonly oidcClientId: string;
+  readonly oidcClientSecret: string;
+  readonly oidcScopes: string;
+  readonly oidcProviderLabel: string;
+  readonly kbRepoUrl: string;
+  readonly kbDirName: string;
+  readonly gitUsername: string;
+  readonly gitToken: string;
+  readonly kbTemplateDir: string;
+  readonly ontologySessionBlock: boolean;
+  readonly updateCheckEnabled: boolean;
+  readonly loginPasswordEnabled: boolean;
+  readonly allowedEmailDomains: string[];
+  readonly secretsEncKey: string;
+  readonly internalTokenSecret: string;
+  readonly trustProxy: string;
+  readonly gitTimeoutMs: number;
+  readonly publicBackendUrl: string;
+  readonly publicFrontendUrl: string;
+  readonly configuredPublicFrontendUrl: string | null;
+  /**
+   * Where this graph's own REST surface is reached from inside the process
+   * (the MCP proxy dials it, and seeds it into the UTCP manuals it builds).
+   * Unset, `http://127.0.0.1:<port>`; a tenant host names its tenant on the
+   * path — see `tenancy/tenant-host.ts`.
+   */
+  readonly loopbackBaseUrl?: string;
+  /**
+   * The environment the deployment settings (repository, git credential,
+   * branch model, SSO, sync secret, …) resolve against before the stored
+   * layer. Unset, the process's own. A tenant host builds one per tenant
+   * from its record, so a variable set on the host process never reaches
+   * every tenant and a record's values behave as environment-pinned ones.
+   */
+  readonly settingsEnv?: NodeJS.ProcessEnv;
+}
+
+/**
+ * What the PROCESS is configured with, independent of how many knowledge
+ * bases it serves: where it listens, which proxy hops it trusts, and the
+ * environment name. A single-tenant deployment's {@link CoreConfig} is both
+ * this and its one tenant's {@link TenantConfig}.
+ */
+export interface ProcessConfig {
+  readonly port: number;
+  readonly nodeEnv: string;
+  readonly trustProxy: string;
+}
+
 /**
  * Configuration for the CORE platform: the git-backed workspace/workflow,
  * skills, tools, secrets vault, access control, and the MCP surface. Contains
@@ -64,9 +147,16 @@ export function withoutUserinfo(url: string): string {
  * `AppConfig` (config.ts), which extends this class. A core-only deployment
  * boots from exactly these env vars.
  */
-export class CoreConfig {
+export class CoreConfig implements TenantConfig, ProcessConfig {
   readonly port: number;
   readonly databaseUrl: string;
+  /**
+   * The Postgres schema this deployment's tables live in (`DB_SCHEMA`,
+   * default `public`). Set it to host this knowledge base beside others in
+   * one database, each on a schema of its own; see
+   * `modules/database/connection.ts` for what that changes.
+   */
+  readonly dbSchema: string;
   readonly nodeEnv: string;
   /**
    * Tenant slug injected into every credential prefix so a deploy can brand its
@@ -155,6 +245,13 @@ export class CoreConfig {
    * credential-helper shell snippet.
    */
   readonly gitUsername: string;
+  /**
+   * The git token the environment supplied (`GIT_TOKEN`, or the legacy
+   * `GITHUB_TOKEN` / `GH_TOKEN`), or `''`. The setup screen's stored token is
+   * read through the settings service instead; the composition root folds
+   * the two into the runner's credentials, environment first.
+   */
+  readonly gitToken: string;
   /**
    * Filesystem path to the KB seed template (the `kb-template/` folder shipped
    * inside this package — see `defaultKbTemplateDir()`). The seeder reads this
@@ -282,6 +379,7 @@ export class CoreConfig {
   constructor() {
     this.port = parseInt(process.env.PORT || '3001', 10);
     this.databaseUrl = resolveDatabaseUrl();
+    this.dbSchema = assertSchemaName((process.env.DB_SCHEMA || DEFAULT_DB_SCHEMA).trim());
     this.nodeEnv = process.env.NODE_ENV || 'development';
     this.tenantId = (process.env.TENANT_ID || 'bevel').trim().toLowerCase();
     if (!/^[a-z0-9]+$/.test(this.tenantId)) {
@@ -352,13 +450,14 @@ export class CoreConfig {
     this.kbRepoUrl = (process.env.KB_REPO_URL || '').trim();
     this.kbDirName = (process.env.KB_DIR_NAME || '').trim();
     // Provider-neutral git token: operators can set GIT_TOKEN (or the legacy
-    // GITHUB_TOKEN / GH_TOKEN). Normalize onto GITHUB_TOKEN — the name the
-    // credential helper and every `$GITHUB_TOKEN` read + redaction use — so all
-    // three work unchanged. GIT_TOKEN takes PRECEDENCE: it's the provider-neutral
-    // name, so setting it must override a stale legacy GITHUB_TOKEN (e.g. when
-    // switching the KB from GitHub to GitLab), not be shadowed by it.
-    const gitToken = process.env.GIT_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
-    if (gitToken) process.env.GITHUB_TOKEN = gitToken;
+    // GITHUB_TOKEN / GH_TOKEN). Read here, never written back: the git runner
+    // hands the token in effect to each child it spawns, so the process
+    // environment does not need to carry it, and a server hosting several
+    // knowledge bases could not carry all of theirs. GIT_TOKEN takes
+    // PRECEDENCE: it's the provider-neutral name, so setting it must override
+    // a stale legacy GITHUB_TOKEN (e.g. when switching the KB from GitHub to
+    // GitLab), not be shadowed by it.
+    this.gitToken = (process.env.GIT_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '').trim();
     this.gitUsername = (process.env.GIT_USERNAME || 'x-access-token').trim();
     // Interpolated into the credential-helper shell snippet, so reject anything
     // that isn't a plain token — no quotes, spaces, or shell metacharacters.

package/src/index.ts

@@ -17,7 +17,9 @@
  * Finer-grained internals are available via the `./modules/*` subpath exports.
  */
 
-export { CoreConfig } from './core-config.js';
+export { CoreConfig, resolveDatabaseUrl, type TenantConfig, type ProcessConfig } from './core-config.js';
+// Serving several knowledge bases from one process — see docs/multi-tenant.md.
+export * from './tenancy/index.js';
 export { createCoreServices, type CoreServices } from './core/create-core-services.js';
 export {
   createCoreServer,
@@ -33,9 +35,14 @@ export type { ILogger, LogFields } from './shared/logger.contract.js';
 // handle type `CoreServices.commitWorker` carries.
 export {
   createShutdown,
+  startCore,
+  stopCore,
   withStartupTask,
+  type BootableCore,
+  type CoreStopDeps,
   type ShutdownDeps,
   type ShutdownOptions,
+  type StopCoreOptions,
   type LeaseLoopHandle,
   type LeasedWorker,
 } from './core/lifecycle.js';
@@ -46,7 +53,16 @@ export {
   runCoreMigrations,
   runEnterpriseMigrations,
 } from './modules/database/migrate.js';
-export { getDb, type Database } from './modules/database/connection.js';
+export {
+  getDb,
+  createDb,
+  closeDb,
+  dbSchemaOf,
+  assertSchemaName,
+  DEFAULT_DB_SCHEMA,
+  type Database,
+  type DbOptions,
+} from './modules/database/connection.js';
 
 // Build identity surfaced by GET /api/health.
 export { GIT_SHA, resolveGitSha } from './version.js';
@@ -85,6 +101,13 @@ export type {
 export type { ILlmUsageMeter } from './modules/tool-auth/llm-usage-meter.js';
 export type { AuthProviderPlugin } from './modules/auth/auth.routes.js';
 export type { IErasureParticipant } from './modules/auth/account-erasure.service.js';
+export {
+  AccountAdmissionRefusedError,
+  admitEveryone,
+  type AccountAdmissionVerdict,
+  type AccountProvisionReason,
+  type IAccountAdmission,
+} from './modules/auth/account-admission.js';
 export {
   WorkflowHooks,
   type CommitValidationHook,

package/src/modules/access/__tests__/access-control.admin-root-floor.test.ts

@@ -21,6 +21,7 @@ import {
 import { createAccessRoutes } from '../access.routes.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * The Admin write floor at the repository root, and the eligible lists that
@@ -287,7 +288,7 @@ describe('Admin write floor at the repository root', () => {
           } as unknown as WorkflowService,
           { emit: () => {} } as unknown as WorkflowEventBus,
           usersDbDouble(),
-          KB,
+          testKbContext({ kbDirName: KB }),
         ),
       );
       server = await new Promise<Server>((resolve) => {

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

@@ -10,6 +10,7 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP contract for `POST /access/batch` — the verb dispatch. Existing callers
@@ -59,7 +60,7 @@ async function makeHarness(): Promise<Harness> {
       {} as unknown as WorkflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       usersDbDouble(),
-      KB,
+      testKbContext({ kbDirName: KB }),
     ),
   );
 

package/src/modules/access/__tests__/access.routes.folder-governs.test.ts

@@ -15,6 +15,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
 import { AccessMutationError, AccessMutationService } from '../access-mutation.service.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * A file that cannot carry frontmatter is never written by an access mutation.
@@ -158,7 +159,7 @@ describe('access mutations on a file that cannot carry frontmatter', () => {
         workflowService,
         { emit: vi.fn() } as unknown as WorkflowEventBus,
         usersDbDouble(),
-        KB,
+        testKbContext({ kbDirName: KB }),
       ),
     );
     server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.group-grant.test.ts

@@ -10,6 +10,7 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP-level contract tests for GROUP and ROLE principals on the share
@@ -87,7 +88,7 @@ async function makeHarness(opts: {
     (req as unknown as { userId: string }).userId = USER.id;
     next();
   });
-  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB));
+  app.use('/api', createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })));
 
   const server = await new Promise<Server>((resolve) => {
     const s = app.listen(0, () => resolve(s));

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

@@ -11,6 +11,7 @@ import type { WorkflowService } from '../../workflow/workflow.service.js';
 import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { usersDbDouble } from './users-db-double.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP contract for `GET /access/overrides`. The scan itself is covered in
@@ -97,7 +98,7 @@ async function makeHarness(opts: {
   });
   app.use(
     '/api',
-    createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, KB),
+    createAccessRoutes(accessControl, workspaceService, authService, workflowService, eventBus, db, testKbContext({ kbDirName: KB })),
   );
 
   const server = await new Promise<Server>((resolve) => {

package/src/modules/access/__tests__/access.routes.proposal-branch.test.ts

@@ -16,6 +16,7 @@ import { usersDbDouble } from './users-db-double.js';
 import { AccessControlService } from '../access-control.service.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { branchForWorkspaceId, workspaceIdForBranch } from '../../../shared/workspace-id.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * Manage access on a file that exists ONLY on a change request's branch.
@@ -136,7 +137,7 @@ describe('access routes on a proposal branch (real git)', () => {
         workflowService,
         { emit: () => {} } as unknown as WorkflowEventBus,
         usersDbDouble(),
-        KB,
+        testKbContext({ kbDirName: KB }),
       ),
     );
     server = await new Promise<Server>((resolve) => {

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

@@ -11,6 +11,7 @@ import type { WorkflowEventBus } from '../../workflow/event-bus.js';
 import type { Database } from '../../database/connection.js';
 import { createAccessRoutes } from '../access.routes.js';
 import { WorkflowDomainError } from '../../../shared/domain-errors.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 /**
  * HTTP contract for `GET /access/prospective` — what the move confirmation
@@ -67,7 +68,7 @@ async function makeHarness(opts: { canRead?: boolean } = {}): Promise<Harness> {
       {} as unknown as WorkflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       {} as unknown as Database,
-      KB,
+      testKbContext({ kbDirName: KB }),
     ),
   );