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

package/dist/tenancy/tenant-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAClE,yCAAyC;IACzC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,mGAAmG;IACnG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IAetB,QAAQ,CAAC,UAAU,EAAE,gBAAgB;IAdvC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAAqE;IACpF,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyD;IAClF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGzB,UAAU,EAAE,gBAAgB,EACrC,IAAI,GAAE,iBAAsB;IAW9B,+FAA+F;IAC/F,KAAK,IAAI,IAAI;IAKb,0DAA0D;IAC1D,KAAK,IAAI,IAAI;IAKb,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,WAAW,CAKvB;IAED,6DAA6D;IAC7D,OAAO,IAAI,MAAM;IAIjB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAwBpC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBvB"}

package/dist/tenancy/tenant-runtime.js

@@ -0,0 +1,174 @@
+import { createCoreServices } from '../core/create-core-services.js';
+import { createCoreServer } from '../core/create-core-server.js';
+import { stopCore } from '../core/lifecycle.js';
+import { logger } from '../shared/logging.js';
+const log = logger('tenancy');
+const DEFAULT_RETRY_INITIAL_MS = 5_000;
+const DEFAULT_RETRY_MAX_MS = 60_000;
+/**
+ * How a tenant's graph is built with the composition root as a distribution
+ * calls it, plus the one thing a host must say: no mirroring onto the shared
+ * package's process-wide bindings, since this process has several graphs and
+ * no single value to put there.
+ */
+async function activateWithCore(descriptor) {
+    const core = await createCoreServices(descriptor.config, { ...descriptor.ports, mirrorSharedBindings: false });
+    try {
+        // No static dir: the host serves the SPA once, for every tenant.
+        const app = await createCoreServer(core, descriptor.extensions ?? {}, {});
+        return { core, app };
+    }
+    catch (err) {
+        // A graph whose boot failed still holds a pool and a lease.
+        await stopCore(core).catch(() => undefined);
+        throw err;
+    }
+}
+async function queuedCommits(graph) {
+    return (await graph.core.pendingCommitsService.oldestQueuedAt()) !== null;
+}
+/**
+ * One tenant's graph, brought up on first use and stopped when the host
+ * says so: `idle → activating → active → evicting → idle`.
+ *
+ * ACTIVATE ONCE. Requests arriving while the graph is being built all await
+ * the one activation in flight. A failed activation is remembered for a
+ * short, growing window and answered from memory inside it, so a tenant
+ * whose remote is down or whose token is wrong costs one clone attempt per
+ * window rather than one per request; past the window the next request
+ * tries again, since the remote may be back or the token fixed. An eviction
+ * that lands mid-activation waits for the activation and then stops what it
+ * produced, so a graph is never left running behind an evicted runtime.
+ *
+ * IN USE MEANS A RESPONSE IS OPEN. The host tells the runtime when it hands
+ * a request over and when that response closes, so idleness counts from the
+ * last response that ENDED, and a tenant with any response still open — an
+ * event stream a browser holds, a clone in flight — is busy and never
+ * evicted from under it.
+ */
+export class TenantRuntime {
+    descriptor;
+    graph = null;
+    activation = null;
+    eviction = null;
+    failure = null;
+    openResponses = 0;
+    lastUsedAt;
+    activate;
+    stopGraph;
+    isBusy;
+    now;
+    retryInitialMs;
+    retryMaxMs;
+    constructor(descriptor, deps = {}) {
+        this.descriptor = descriptor;
+        this.activate = deps.activate ?? activateWithCore;
+        this.stopGraph = deps.stop ?? ((graph) => stopCore(graph.core));
+        this.isBusy = deps.busy ?? queuedCommits;
+        this.now = deps.now ?? Date.now;
+        this.retryInitialMs = deps.retry?.initialMs ?? DEFAULT_RETRY_INITIAL_MS;
+        this.retryMaxMs = deps.retry?.maxMs ?? DEFAULT_RETRY_MAX_MS;
+        this.lastUsedAt = this.now();
+    }
+    /** A request was handed to this tenant; paired with {@link leave} when its response closes. */
+    enter() {
+        this.openResponses += 1;
+        this.lastUsedAt = this.now();
+    }
+    /** A response to this tenant closed, however it ended. */
+    leave() {
+        if (this.openResponses > 0)
+            this.openResponses -= 1;
+        this.lastUsedAt = this.now();
+    }
+    /** Responses handed over and not yet closed. */
+    get open() {
+        return this.openResponses;
+    }
+    get slug() {
+        return this.descriptor.slug;
+    }
+    get state() {
+        if (this.eviction)
+            return 'evicting';
+        if (this.graph)
+            return 'active';
+        if (this.activation)
+            return 'activating';
+        return 'idle';
+    }
+    /** Milliseconds since a request last touched this tenant. */
+    idleFor() {
+        return this.now() - this.lastUsedAt;
+    }
+    /**
+     * The graph, built if it is not running. Every caller of a concurrent
+     * first burst gets the same promise; a caller that arrives during an
+     * eviction waits for it, then starts the graph afresh.
+     */
+    async handle() {
+        this.lastUsedAt = this.now();
+        if (this.eviction)
+            await this.eviction;
+        if (this.graph)
+            return this.graph;
+        if (this.failure && this.now() < this.failure.until)
+            throw this.failure.error;
+        this.activation ??= this.activate(this.descriptor).then((graph) => {
+            this.graph = graph;
+            this.activation = null;
+            this.failure = null;
+            log.info(`tenant "${this.slug}" activated`);
+            return graph;
+        }, (err) => {
+            this.activation = null;
+            const backoffMs = Math.min(this.failure ? this.failure.backoffMs * 2 : this.retryInitialMs, this.retryMaxMs);
+            this.failure = { error: err, until: this.now() + backoffMs, backoffMs };
+            log.error(`tenant "${this.slug}" failed to activate; not asked again for ${backoffMs}ms:`, { err });
+            throw err;
+        });
+        return this.activation;
+    }
+    /**
+     * Whether an eviction would strand something: a response still open, or
+     * work the graph reports (queued commits). False when nothing runs.
+     */
+    async busy() {
+        if (this.openResponses > 0)
+            return true;
+        return this.graph ? this.isBusy(this.graph) : false;
+    }
+    /**
+     * Stop the graph, if one runs or is being built. Idempotent: a second call
+     * joins the eviction under way. Afterwards the runtime is idle and the
+     * next {@link handle} builds a fresh graph.
+     */
+    evict() {
+        if (this.eviction)
+            return this.eviction;
+        const eviction = (async () => {
+            if (this.activation) {
+                // Whatever the build produces is stopped; a build that fails has
+                // stopped its own graph already.
+                await this.activation.catch(() => undefined);
+            }
+            const graph = this.graph;
+            this.graph = null;
+            if (graph) {
+                await this.stopGraph(graph);
+                log.info(`tenant "${this.slug}" evicted`);
+            }
+        })();
+        // Assigned, then cleared by identity: an eviction with nothing to stop
+        // settles before this line runs, and a `finally` inside it would have
+        // cleared a field that was not yet set — leaving the settled promise
+        // in place as an eviction forever under way.
+        this.eviction = eviction;
+        void eviction.finally(() => {
+            if (this.eviction === eviction)
+                this.eviction = null;
+        });
+        return eviction;
+    }
+}
+//# sourceMappingURL=tenant-runtime.js.map

package/dist/tenancy/tenant-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.js","sourceRoot":"","sources":["../../src/tenancy/tenant-runtime.ts"],"names":[],"mappings":"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"}

package/dist/tenancy/tenant-secrets.d.ts

@@ -0,0 +1,24 @@
+/** The three secrets every graph needs, derived rather than stored. */
+export interface TenantSecrets {
+    /** Signs the tenant's login sessions and OAuth state. */
+    jwtSecret: string;
+    /** 32 bytes, base64: encrypts the tenant's vault values, MCP OAuth tokens and stored git credential. */
+    secretsEncKey: string;
+    /** HMAC key for the tenant's internal (loopback) tool tokens. */
+    internalTokenSecret: string;
+}
+/**
+ * A tenant's secrets from ONE master key and its slug, with HKDF-SHA256:
+ * the slug is the salt and each secret's name the info, so the three are
+ * independent of each other and of every other tenant's.
+ *
+ * Derived, not generated and stored, for the hand-over: a tenant that leaves
+ * for a dedicated deployment takes a `pg_dump` whose vault rows and stored
+ * git token are encrypted under its `secretsEncKey`. With derivation the key
+ * is reproducible from the master key and the slug on the day of the
+ * export, and nothing per tenant has to be kept safe in the meantime. The
+ * cloud app's registry calls this with the same inputs and gets the same
+ * answer.
+ */
+export declare function deriveTenantSecrets(masterKey: string, slug: string): TenantSecrets;
+//# sourceMappingURL=tenant-secrets.d.ts.map

package/dist/tenancy/tenant-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-secrets.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-secrets.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAYlF"}

package/dist/tenancy/tenant-secrets.js

@@ -0,0 +1,30 @@
+import { hkdfSync } from 'node:crypto';
+/** The least a master key may hold: 32 characters is 256 bits of a random string. */
+const MIN_MASTER_KEY_LENGTH = 32;
+/**
+ * A tenant's secrets from ONE master key and its slug, with HKDF-SHA256:
+ * the slug is the salt and each secret's name the info, so the three are
+ * independent of each other and of every other tenant's.
+ *
+ * Derived, not generated and stored, for the hand-over: a tenant that leaves
+ * for a dedicated deployment takes a `pg_dump` whose vault rows and stored
+ * git token are encrypted under its `secretsEncKey`. With derivation the key
+ * is reproducible from the master key and the slug on the day of the
+ * export, and nothing per tenant has to be kept safe in the meantime. The
+ * cloud app's registry calls this with the same inputs and gets the same
+ * answer.
+ */
+export function deriveTenantSecrets(masterKey, slug) {
+    if (masterKey.length < MIN_MASTER_KEY_LENGTH) {
+        throw new Error(`TENANT_MASTER_KEY must be at least ${MIN_MASTER_KEY_LENGTH} characters of random text`);
+    }
+    if (!slug)
+        throw new Error('A tenant slug is required to derive its secrets');
+    const derive = (info) => Buffer.from(hkdfSync('sha256', masterKey, `hexis-tenant:${slug}`, info, 32)).toString('base64');
+    return {
+        jwtSecret: derive('jwt-secret'),
+        secretsEncKey: derive('secrets-enc-key'),
+        internalTokenSecret: derive('internal-token-secret'),
+    };
+}
+//# sourceMappingURL=tenant-secrets.js.map

package/dist/tenancy/tenant-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-secrets.js","sourceRoot":"","sources":["../../src/tenancy/tenant-secrets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAYvC,qFAAqF;AACrF,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,IAAY;IACjE,IAAI,SAAS,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,sCAAsC,qBAAqB,4BAA4B,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CACtC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClG,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,YAAY,CAAC;QAC/B,aAAa,EAAE,MAAM,CAAC,iBAAiB,CAAC;QACxC,mBAAmB,EAAE,MAAM,CAAC,uBAAuB,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/tenancy/tenant-source.contract.d.ts

@@ -0,0 +1,45 @@
+import type { TenantConfig } from '../core-config.js';
+import type { CorePorts } from '../core/core-ports.js';
+import type { ServerExtensions } from '../core/create-core-server.js';
+/**
+ * A tenant, as the host needs to know it: which host names reach it, what
+ * its service graph is built from, and what a distribution adds to that
+ * graph. One of these is one `createCoreServices` + `createCoreServer`, run
+ * on demand and stopped again when idle — see `tenant-runtime.ts`.
+ *
+ * `ports` and `extensions` are per tenant on purpose: everything the
+ * enterprise overlay does per deployment (its SSO plugin, session sink,
+ * erasure participants, extra startup steps) it does per tenant here, through
+ * the same two seams, with nothing below the front door knowing the
+ * difference.
+ */
+export interface TenantDescriptor {
+    /** The tenant's stable name: lowercase, `[a-z][a-z0-9-]*`, at most 40 characters. */
+    readonly slug: string;
+    /** Host names (no port) whose requests belong to this tenant, lowercase. */
+    readonly hosts: readonly string[];
+    readonly config: TenantConfig;
+    readonly ports?: CorePorts;
+    readonly extensions?: ServerExtensions;
+}
+/**
+ * Where tenants come from. Core ships {@link StaticTenantSource}, which
+ * reads a file, for development and tests; the cloud app implements this
+ * over its own registry, where subdomains are provisioned and plans live.
+ * A source answers `null` for a host or slug it does not know, and the host
+ * turns that into a 404 without building anything.
+ */
+export interface TenantSource {
+    resolveByHost(host: string): Promise<TenantDescriptor | null>;
+    describe(slug: string): Promise<TenantDescriptor | null>;
+}
+/** What a slug may look like: it names a schema, a folder and a loopback path. */
+export declare const TENANT_SLUG_PATTERN: RegExp;
+export declare function assertTenantSlug(slug: string): string;
+/**
+ * A host name the way the host compares it: lowercase, without a port or a
+ * trailing dot. `Host` headers and `X-Forwarded-Host` values arrive in every
+ * spelling a client or proxy chooses.
+ */
+export declare function normalizeHost(host: string): string;
+//# sourceMappingURL=tenant-source.contract.d.ts.map

package/dist/tenancy/tenant-source.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-source.contract.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-source.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD"}

package/dist/tenancy/tenant-source.contract.js

@@ -0,0 +1,21 @@
+/** What a slug may look like: it names a schema, a folder and a loopback path. */
+export const TENANT_SLUG_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+export function assertTenantSlug(slug) {
+    if (!TENANT_SLUG_PATTERN.test(slug)) {
+        throw new Error(`Tenant slug must match ${TENANT_SLUG_PATTERN} (lowercase, digits, hyphens); got "${slug}"`);
+    }
+    return slug;
+}
+/**
+ * A host name the way the host compares it: lowercase, without a port or a
+ * trailing dot. `Host` headers and `X-Forwarded-Host` values arrive in every
+ * spelling a client or proxy chooses.
+ */
+export function normalizeHost(host) {
+    const trimmed = host.trim().toLowerCase().replace(/\.$/, '');
+    // `[::1]:3001` keeps its brackets; `example.test:3001` loses its port.
+    if (trimmed.startsWith('['))
+        return trimmed.replace(/\]:\d+$/, ']');
+    return trimmed.replace(/:\d+$/, '');
+}
+//# sourceMappingURL=tenant-source.contract.js.map

package/dist/tenancy/tenant-source.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-source.contract.js","sourceRoot":"","sources":["../../src/tenancy/tenant-source.contract.ts"],"names":[],"mappings":"AAsCA,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAE5D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,0BAA0B,mBAAmB,uCAAuC,IAAI,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7D,uEAAuE;IACvE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/migrations/0000_core_init.sql

@@ -173,51 +173,51 @@ CREATE TABLE IF NOT EXISTS "users" (
 --> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'api_tokens_user_id_users_id_fk' AND conrelid = 'public.api_tokens'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'api_tokens_user_id_users_id_fk' AND conrelid = to_regclass('api_tokens')
 	) THEN
-		ALTER TABLE "api_tokens" ADD CONSTRAINT "api_tokens_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "api_tokens" ADD CONSTRAINT "api_tokens_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'file_locks_holder_user_id_users_id_fk' AND conrelid = 'public.file_locks'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'file_locks_holder_user_id_users_id_fk' AND conrelid = to_regclass('file_locks')
 	) THEN
-		ALTER TABLE "file_locks" ADD CONSTRAINT "file_locks_holder_user_id_users_id_fk" FOREIGN KEY ("holder_user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "file_locks" ADD CONSTRAINT "file_locks_holder_user_id_users_id_fk" FOREIGN KEY ("holder_user_id") REFERENCES "users"("id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_auth_codes_client_id_oauth_clients_client_id_fk' AND conrelid = 'public.oauth_auth_codes'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_auth_codes_client_id_oauth_clients_client_id_fk' AND conrelid = to_regclass('oauth_auth_codes')
 	) THEN
-		ALTER TABLE "oauth_auth_codes" ADD CONSTRAINT "oauth_auth_codes_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "oauth_auth_codes" ADD CONSTRAINT "oauth_auth_codes_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_auth_codes_user_id_users_id_fk' AND conrelid = 'public.oauth_auth_codes'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_auth_codes_user_id_users_id_fk' AND conrelid = to_regclass('oauth_auth_codes')
 	) THEN
-		ALTER TABLE "oauth_auth_codes" ADD CONSTRAINT "oauth_auth_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "oauth_auth_codes" ADD CONSTRAINT "oauth_auth_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_tokens_client_id_oauth_clients_client_id_fk' AND conrelid = 'public.oauth_tokens'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_tokens_client_id_oauth_clients_client_id_fk' AND conrelid = to_regclass('oauth_tokens')
 	) THEN
-		ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_tokens_user_id_users_id_fk' AND conrelid = 'public.oauth_tokens'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'oauth_tokens_user_id_users_id_fk' AND conrelid = to_regclass('oauth_tokens')
 	) THEN
-		ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE no action ON UPDATE no action;
+		ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE no action ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 DO $$ BEGIN
 	IF NOT EXISTS (
-		SELECT 1 FROM pg_constraint WHERE conname = 'secrets_user_id_users_id_fk' AND conrelid = 'public.secrets'::regclass
+		SELECT 1 FROM pg_constraint WHERE conname = 'secrets_user_id_users_id_fk' AND conrelid = to_regclass('secrets')
 	) THEN
-		ALTER TABLE "secrets" ADD CONSTRAINT "secrets_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+		ALTER TABLE "secrets" ADD CONSTRAINT "secrets_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
 	END IF;
 END $$;--> statement-breakpoint
 CREATE UNIQUE INDEX IF NOT EXISTS "change_requests_number_unq" ON "change_requests" USING btree ("number");--> statement-breakpoint

package/migrations/0003_deployment_settings.sql

@@ -6,4 +6,4 @@ CREATE TABLE "deployment_settings" (
 	"updated_at" timestamp DEFAULT now() NOT NULL
 );
 --> statement-breakpoint
-ALTER TABLE "deployment_settings" ADD CONSTRAINT "deployment_settings_updated_by_users_id_fk" FOREIGN KEY ("updated_by") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;
+ALTER TABLE "deployment_settings" ADD CONSTRAINT "deployment_settings_updated_by_users_id_fk" FOREIGN KEY ("updated_by") REFERENCES "users"("id") ON DELETE set null ON UPDATE no action;

package/migrations/0005_github_facade.sql

@@ -22,4 +22,4 @@ CREATE TABLE "github_facade_identity" (
 );
 --> statement-breakpoint
 ALTER TABLE "api_tokens" ADD COLUMN "kind" text DEFAULT 'key' NOT NULL;--> statement-breakpoint
-ALTER TABLE "github_facade_codes" ADD CONSTRAINT "github_facade_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;
+ALTER TABLE "github_facade_codes" ADD CONSTRAINT "github_facade_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;

package/migrations/0012_agent_audit.sql

@@ -26,16 +26,16 @@ CREATE TABLE "agent_events" (
 );
 --> statement-breakpoint
 ALTER TABLE "oauth_tokens" ADD COLUMN "connection_id" uuid;--> statement-breakpoint
-ALTER TABLE "agent_connections" ADD CONSTRAINT "agent_connections_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_connections" ADD CONSTRAINT "agent_connections_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "public"."oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_key_id_api_tokens_id_fk" FOREIGN KEY ("key_id") REFERENCES "public"."api_tokens"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
-ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_connection_id_agent_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."agent_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_connections" ADD CONSTRAINT "agent_connections_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_connections" ADD CONSTRAINT "agent_connections_client_id_oauth_clients_client_id_fk" FOREIGN KEY ("client_id") REFERENCES "oauth_clients"("client_id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_key_id_api_tokens_id_fk" FOREIGN KEY ("key_id") REFERENCES "api_tokens"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "agent_events" ADD CONSTRAINT "agent_events_connection_id_agent_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "agent_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 CREATE INDEX "agent_connections_by_user" ON "agent_connections" USING btree ("user_id");--> statement-breakpoint
 CREATE UNIQUE INDEX "agent_connections_live_unq" ON "agent_connections" USING btree ("user_id","client_id") WHERE "agent_connections"."revoked_at" is null;--> statement-breakpoint
 CREATE INDEX "agent_events_by_key" ON "agent_events" USING btree ("key_id","at");--> statement-breakpoint
 CREATE INDEX "agent_events_by_connection" ON "agent_events" USING btree ("connection_id","at");--> statement-breakpoint
 CREATE INDEX "agent_events_by_at" ON "agent_events" USING btree ("at");--> statement-breakpoint
 CREATE INDEX "agent_events_by_user" ON "agent_events" USING btree ("user_id");--> statement-breakpoint
-ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_connection_id_agent_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "public"."agent_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "oauth_tokens" ADD CONSTRAINT "oauth_tokens_connection_id_agent_connections_id_fk" FOREIGN KEY ("connection_id") REFERENCES "agent_connections"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
 CREATE INDEX "oauth_tokens_by_connection" ON "oauth_tokens" USING btree ("connection_id");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.20.0",
+  "version": "0.21.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.20.0",
-    "@bevel-software/platform-shared": "0.20.0"
+    "@bevel-software/platform-mcp-core": "0.21.0",
+    "@bevel-software/platform-shared": "0.21.0"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",

package/src/__tests__/branch-model.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect, afterEach, beforeEach } from 'vitest';
 import {
   configureBranchModel,
+  currentBranchModel,
   isBranchModelConfigured,
   isProtectedBranch,
   protectedBranchDisplayName,
@@ -21,14 +22,14 @@ afterEach(() => configureBranchModel(PAIR));
 
 describe('configureBranchModel', () => {
   it('applies the model to every export', () => {
-    expect(isBranchModelConfigured()).toBe(true);
+    expect(isBranchModelConfigured(currentBranchModel())).toBe(true);
     expect(DEFAULT_BRANCH).toBe('target-company-state');
     expect([...PROTECTED_BRANCHES].sort()).toEqual([
       'current-company-state',
       'target-company-state',
     ]);
-    expect(isProtectedBranch('current-company-state')).toBe(true);
-    expect(isProtectedBranch('someone/draft')).toBe(false);
+    expect(isProtectedBranch(currentBranchModel(), 'current-company-state')).toBe(true);
+    expect(isProtectedBranch(currentBranchModel(), 'someone/draft')).toBe(false);
   });
 
   it('accepts the comma/space list the environment supplies', () => {
@@ -37,10 +38,10 @@ describe('configureBranchModel', () => {
   });
 
   it('derives display names from the slug', () => {
-    expect(protectedBranchDisplayName('target-company-state')).toBe('Target company state');
+    expect(protectedBranchDisplayName(currentBranchModel(), 'target-company-state')).toBe('Target company state');
     // Unknown names return null so the caller decides between the raw slug and
     // hiding the affordance — it must not invent a name for a feature branch.
-    expect(protectedBranchDisplayName('someone/draft')).toBeNull();
+    expect(protectedBranchDisplayName(currentBranchModel(), 'someone/draft')).toBeNull();
   });
 
   /**
@@ -74,6 +75,6 @@ describe('configureBranchModel', () => {
       configureBranchModel({ defaultBranch: 'nope', protectedBranches: ['other'] }),
     ).toThrow();
     expect(DEFAULT_BRANCH).toBe('target-company-state');
-    expect(isProtectedBranch('target-company-state')).toBe(true);
+    expect(isProtectedBranch(currentBranchModel(), 'target-company-state')).toBe(true);
   });
 });

package/src/__tests__/kb-context.ts

@@ -0,0 +1,30 @@
+import {
+  DEFAULT_KB_LAYOUT,
+  resolveBranchModel,
+  type BranchModel,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { KbContext } from '../shared/kb-context.js';
+
+/**
+ * The knowledge-base context suites hand to the services they construct: the
+ * historical two-branch pair `vitest.config.ts` pins (and `test-setup.ts`
+ * mirrors onto the shared bindings, for the fixtures that still spell a
+ * branch by its binding), the default layout, and `knowledge-base` as the
+ * checkout folder. Override any part for a suite that needs another.
+ */
+export const TEST_BRANCH_MODEL: BranchModel = {
+  defaultBranch: 'target-company-state',
+  protectedBranches: ['current-company-state', 'target-company-state'],
+};
+
+export function testKbContext(
+  overrides: { kbDirName?: string; branchModel?: BranchModel | null; layout?: KbLayout } = {},
+): KbContext {
+  const model = overrides.branchModel === undefined ? TEST_BRANCH_MODEL : overrides.branchModel;
+  return new KbContext(
+    overrides.kbDirName ?? 'knowledge-base',
+    model === null ? KbContext.branchModelOrUnconfigured({ defaultBranch: '', protectedBranches: [] }) : resolveBranchModel(model),
+    overrides.layout ?? DEFAULT_KB_LAYOUT,
+  );
+}