@bevel-software/platform-core-backend 0.22.0 → 0.24.0

package/src/core/lifecycle.ts

@@ -1,7 +1,7 @@
 import type { Server } from 'node:http';
 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 { bootMaySurvive, 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';
@@ -164,7 +164,13 @@ export function holdCommitWorkerLease(
         running = false;
         wake?.();
         await loop;
+        // The worker is asked to stop whether or not this process is running
+        // it: a worker that can be held still (`holdable`) may be in the
+        // middle of a hold that uses the database, and its stop is what
+        // waits for that. Stopping a worker that is not running is nothing.
+        const idle = !workerRunning && !stopping;
         await stopWorker();
+        if (idle) await worker.stop().catch((err: unknown) => log(`commit worker stop failed: ${String(err)}`));
         await lease.release();
       })();
       return stopped;
@@ -202,6 +208,80 @@ export function withStartupTask(
   };
 }
 
+/** A worker the lease loop drives, which something else may hold still for a while. */
+export interface HoldableWorker extends LeasedWorker {
+  /**
+   * Run `work` with the worker stopped, and start it again afterwards if the
+   * lease loop still wants it running. A hold waits for the commit in flight
+   * to finish, as a stop does. Holds may overlap; the worker starts again
+   * when the last one ends, whether `work` resolved or threw.
+   */
+  whileHeld<T>(work: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * A worker that can be HELD STILL without the lease loop knowing.
+ *
+ * The lease loop decides whether this process is the one draining the commit
+ * queue; it starts the worker when the lease is taken and stops it when the
+ * lease is lost. Moving the deployment to another repository needs a second,
+ * independent reason for the worker not to run: while working copies are
+ * being set aside and cloned again, a queued commit must not be written into
+ * a directory that is being renamed away, nor into the fresh clone of a
+ * repository it was never meant for. Stopping the loop itself would release
+ * the lease, and another process would take the queue over mid-move.
+ *
+ * So the two reasons are kept apart. `wanted` is the lease loop's word,
+ * `holds` counts the moves in flight, and the worker runs exactly when it is
+ * wanted and nothing holds it.
+ *
+ * A stop waits for the holds in flight as well as for the worker. Shutdown
+ * awaits this stop (bounded by its own budget) before it ends the database
+ * pool, and a move still setting copies aside and cloning needs that pool:
+ * it is either finished, or known to have been cut.
+ */
+export function holdable(worker: LeasedWorker): HoldableWorker {
+  let wanted = false;
+  const inFlight = new Set<Promise<unknown>>();
+  /**
+   * ONE stop at a time, shared by everyone who asks. A worker's own stop is
+   * idempotent by answering 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.
+   */
+  let stopping: Promise<void> | null = null;
+  const stopWorker = (): Promise<void> => {
+    stopping ??= worker.stop().finally(() => {
+      stopping = null;
+    });
+    return stopping;
+  };
+  return {
+    start() {
+      wanted = true;
+      if (inFlight.size === 0) worker.start();
+    },
+    async stop() {
+      wanted = false;
+      await stopWorker();
+      await Promise.allSettled([...inFlight]);
+    },
+    whileHeld<T>(work: () => Promise<T>): Promise<T> {
+      const held = (async () => {
+        await stopWorker();
+        return work();
+      })();
+      inFlight.add(held);
+      const ended = (): void => {
+        inFlight.delete(held);
+        if (inFlight.size === 0 && wanted) worker.start();
+      };
+      held.then(ended, ended);
+      return held;
+    },
+  };
+}
+
 /**
  * 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
@@ -228,7 +308,8 @@ export interface BootableCore {
  * 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
+ * Throws to stop the boot on every failure but the ones the host answered
+ * about the repository or the credentials (see `bootMaySurvive`) — the
  * container's restart policy is the retry — see `kb-startup-runner.ts`.
  */
 export async function startCore<C extends BootableCore>(
@@ -267,18 +348,22 @@ export async function startCore<C extends BootableCore>(
   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
+    // The failures a boot survives: the host ANSWERED about the repository or
+    // the credentials, or could not be reached at all. None of them says
+    // anything about the knowledge base — what we would write is not known to
+    // be wrong — and every one of them is fixed somewhere else: the host comes
+    // back, the repository is created, the token is granted access, a rotated
+    // token is typed into the setup screen. Refusing to boot took away the
+    // login and setup screens the fix is entered on, and on 2026-09-28 a
+    // repository that had been replaced crash-looped a deployment for exactly
+    // that reason. The deployment comes up GATED instead: 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,
+    // 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. See `bootMaySurvive`.
+    if (!bootMaySurvive(err)) throw err;
+    startupLog.error('booting UNMAINTAINED and gated — the knowledge base could not be initialized:', {
+      detail: err instanceof Error ? err.message : String(err),
     });
     // Kept on the graph so that stopping the graph stops the asking: a
     // retry that outlived its graph would clone into a workspaces folder
@@ -343,6 +428,15 @@ export interface CoreStopDeps {
    * to it. Optional: a caller that has not built them yet passes nothing.
    */
   backgroundJobs?: { stopSweeping(): void; drain(): Promise<void> };
+  /**
+   * The agent upload store, whose own sweep deletes staged bytes nobody
+   * applied. Stopped with this graph because the next graph for the same
+   * tenant stages into the SAME directory with an empty record map: a sweep
+   * left running from a store that is gone would read the replacement's files
+   * as orphans and delete them under an apply that is about to read them.
+   * Optional: a caller that has not built one passes nothing.
+   */
+  agentUploadStore?: { stopSweeping(): void; drainSweep(): 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. */
@@ -426,6 +520,10 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   // 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();
+  // And the upload store's sweep, for the same reason and in the same breath:
+  // synchronous, and it only clears an interval and tells a sweep already
+  // running to stop deleting.
+  deps.agentUploadStore?.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.
@@ -439,6 +537,12 @@ async function releaseCore(deps: CoreStopDeps, remaining: () => number, log: (m:
   if (deps.backgroundJobs) {
     await bounded(deps.backgroundJobs.drain(), remaining(), 'finishing the background jobs', log);
   }
+  // The sweep in flight when the interval was cleared: awaited so the next
+  // graph for this tenant cannot start staging bytes while a store it has
+  // never heard of is still walking the same directory.
+  if (deps.agentUploadStore) {
+    await bounded(deps.agentUploadStore.drainSweep(), remaining(), 'finishing the upload sweep', 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);

package/src/core-config.ts

@@ -6,6 +6,8 @@ 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';
+import { hasControlCharacter } from './modules/kb-fs/repo-path.js';
+import { sanitizedPath } from './shared/printable.js';
 
 const log = logger('config');
 
@@ -86,6 +88,7 @@ export interface TenantConfig {
   readonly workspacesRoot: string;
   readonly backupsRoot: string;
   readonly spillRoot: string;
+  readonly agentUploadsRoot: string;
   readonly docExtractCacheRoot: string;
   readonly jwtSecret: string;
   readonly adminEmail: string;
@@ -100,7 +103,6 @@ export interface TenantConfig {
   readonly gitUsername: string;
   readonly gitToken: string;
   readonly kbTemplateDir: string;
-  readonly ontologySessionBlock: boolean;
   readonly updateCheckEnabled: boolean;
   readonly loginPasswordEnabled: boolean;
   readonly allowedEmailDomains: string[];
@@ -183,6 +185,21 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * never committed, best-effort GC'd on write.
    */
   readonly spillRoot: string;
+  /**
+   * Sibling-to-`workspacesRoot` location for the bytes an agent uploads with
+   * `request_file_upload`, held until `apply_file_upload` lands them (or their
+   * token expires, whichever comes first). BESIDE the workspaces, never inside
+   * one, and that placement is the point: an upload is content the server has
+   * accepted but not yet judged, so no file tool may name it — every workspace
+   * path resolves against a branch's checkout, and there is no spelling of one
+   * that reaches in here. Ephemeral and never committed.
+   *
+   * `AGENT_UPLOADS_ROOT` overrides it, and the placement is CHECKED at boot
+   * (`assertUploadsRootOutsideWorkspaces`): a value inside `workspacesRoot` —
+   * or one that resolves there through a link — refuses to start rather than
+   * quietly staging unjudged bytes where the file tools read.
+   */
+  readonly agentUploadsRoot: string;
   /**
    * Sibling-to-`workspacesRoot` location for the document-extraction cache —
    * text extracted from office documents/PDFs (`read_file`/`grep`), keyed by
@@ -259,17 +276,6 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
    * existing one. Override with `KB_TEMPLATE_DIR`.
    */
   readonly kbTemplateDir: string;
-  /**
-   * Ontology-session boundary kill-switch. When true (default), an agent run
-   * that has read across more than one ontology can no longer write. A no-op on
-   * a single-ontology KB. Set `ONTOLOGY_SESSION_BLOCK=false` to disable.
-   *
-   * Stays on CORE config (not `AppConfig`) even though the write BLOCK itself
-   * is an enterprise-registered hook: the flag also switches off the core-owned
-   * touch TRACKING (the gate skips entirely when false — see
-   * `session-ontology.gate.ts`), so it must exist wherever the tracking runs.
-   */
-  readonly ontologySessionBlock: boolean;
   /**
    * In-app update check. When true (default), `GET /api/update-check` lazily
    * asks api.github.com for the newest Hexis release — only when an admin's
@@ -390,6 +396,8 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     this.workspacesRoot = process.env.WORKSPACES_ROOT || path.resolve(process.cwd(), 'workspaces');
     this.backupsRoot = process.env.BACKUPS_ROOT || path.resolve(this.workspacesRoot, '..', 'backups');
     this.spillRoot = process.env.SPILL_ROOT || path.resolve(this.workspacesRoot, '..', 'tool-chain-spills');
+    this.agentUploadsRoot =
+      process.env.AGENT_UPLOADS_ROOT || path.resolve(this.workspacesRoot, '..', 'agent-uploads');
     this.docExtractCacheRoot =
       process.env.DOC_EXTRACT_CACHE_ROOT || path.resolve(this.workspacesRoot, '..', 'doc-extract-cache');
     // Required, and checked BEFORE the auth routes it signs for are ever
@@ -469,8 +477,6 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     // Default: the `kb-template/` folder shipped inside this package (works
     // both from src/ and compiled dist/ — see assets.ts).
     this.kbTemplateDir = process.env.KB_TEMPLATE_DIR || defaultKbTemplateDir();
-    this.ontologySessionBlock =
-      (process.env.ONTOLOGY_SESSION_BLOCK ?? 'true').trim().toLowerCase() !== 'false';
     this.updateCheckEnabled =
       (process.env.UPDATE_CHECK ?? 'true').trim().toLowerCase() !== 'false';
     this.allowedEmailDomains = (process.env.ALLOWED_EMAIL_DOMAINS || '')
@@ -621,5 +627,16 @@ export class CoreConfig implements TenantConfig, ProcessConfig {
     ) {
       throw new Error(`KB_DIR_NAME must be a single path segment: ${this.kbDirName}`);
     }
+    // A control character, a line break above all: this name is PREFIXED onto
+    // every workspace-relative path, and a line break in a path is a separator
+    // in git's line-oriented stdin protocols (`cat-file --batch` reads one
+    // `<ref>:<path>` per line). A name carrying one would make the normaliser
+    // emit the very path it refuses from a caller — so the deployment fails to
+    // boot rather than resolving paths nothing downstream can safely read.
+    if (hasControlCharacter(this.kbDirName)) {
+      throw new Error(
+        `KB_DIR_NAME must not contain a control character: "${sanitizedPath(this.kbDirName)}"`,
+      );
+    }
   }
 }

package/src/index.ts

@@ -52,18 +52,36 @@ export { coreMigrationsDir, defaultKbTemplateDir } from './assets.js';
 export {
   runCoreMigrations,
   runEnterpriseMigrations,
+  runPiiEncryptionBackfill,
 } from './modules/database/migrate.js';
 export {
   getDb,
   createDb,
   closeDb,
   dbSchemaOf,
+  piiKeysOf,
   assertSchemaName,
   DEFAULT_DB_SCHEMA,
   type Database,
   type DbOptions,
 } from './modules/database/connection.js';
 
+// PII column encryption (see shared/column-crypto.ts). The key belongs to the
+// database handle (`createDb(url, { piiKey })`), so an overlay seals its own
+// schema's columns by declaring them `encryptedText` / `blindIndexText` and
+// running on the handle the composition root built. `derivePiiKeys` and
+// `piiKeysOf` are for code that handles the stored form itself: SQL written
+// by hand, or a process that reads a knowledge base's tables without a handle
+// of this package's.
+export {
+  encryptedText,
+  blindIndexText,
+  derivePiiKeys,
+  isEncryptedBlob,
+  PII_CIPHERTEXT_PREFIX,
+  type PiiKeys,
+} from './shared/column-crypto.js';
+
 // Build identity surfaced by GET /api/health.
 export { GIT_SHA, resolveGitSha } from './version.js';
 
@@ -101,8 +119,18 @@ 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 {
+  alwaysWritable,
+  READ_ONLY_CODE,
+  type IWriteAccess,
+  type WriteAccessVerdict,
+} from './modules/write-access/write-access.js';
 export {
   AccountAdmissionRefusedError,
+  AccountDeactivatedError,
+  AccountChangeRefusedError,
+  AuthBackendError,
+  ACCOUNT_DEACTIVATED_MESSAGE,
   admitEveryone,
   type AccountAdmissionVerdict,
   type AccountProvisionReason,
@@ -112,6 +140,7 @@ export {
   WorkflowHooks,
   type CommitValidationHook,
   type CommitValidationContext,
+  type AgentOperationContext,
+  type AgentReadHook,
   type PreWriteHook,
-  type PreWriteContext,
 } from './modules/workflow/workflow-hooks.js';