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

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.22.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.22.0",
+    "@bevel-software/platform-shared": "0.22.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,
+  );
+}

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

@@ -20,6 +20,7 @@ import {
   validateKbLayout,
   validateKbRootName,
   normalizeSkillRoot,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
 
 /**
@@ -29,6 +30,10 @@ import {
  */
 afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
 
+/** The helpers under the browser's configured layout — the shape these cases were written against. */
+const validateGuideName = (name: string, roots: KbLayout = DEFAULT_KB_LAYOUT) => validateAgentsFileName(name, roots);
+const platformFile = (path: string) => isPlatformFile(path, currentKbLayout());
+
 describe('KB layout — validation', () => {
   test('accepts the defaults and any three distinct plain folder names', () => {
     expect(validateKbLayout({ ...DEFAULT_KB_LAYOUT })).toBeNull();
@@ -100,12 +105,12 @@ 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()).toEqual(['docs', 'Data']);
-    expect(reservedRootDirNames().has('plugins')).toBe(true);
-    expect(reservedRootDirNames().has('Plugins')).toBe(false);
-    // Path rules read the live name too.
-    expect(pluginOfPath('plugins/GTM/skills/x/SKILL.md')).toBe('GTM');
-    expect(pluginOfPath('Plugins/GTM/skills/x/SKILL.md')).toBeNull();
+    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.
+    expect(pluginOfPath('plugins/GTM/skills/x/SKILL.md', currentKbLayout())).toBe('GTM');
+    expect(pluginOfPath('Plugins/GTM/skills/x/SKILL.md', currentKbLayout())).toBeNull();
   });
 
   test('throws on an invalid layout and leaves the current one untouched', () => {
@@ -137,7 +142,7 @@ describe('KB layout — the agent guide\'s file name', () => {
   });
 
   test('accepts a plain markdown name and applies it to the live binding', () => {
-    expect(validateAgentsFileName('HEXIS.md')).toBeNull();
+    expect(validateGuideName('HEXIS.md')).toBeNull();
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     expect(AGENTS_FILE).toBe('HEXIS.md');
     expect(currentKbLayout().agentsFile).toBe('HEXIS.md');
@@ -145,30 +150,30 @@ describe('KB layout — the agent guide\'s file name', () => {
 
   test('refuses every shape that is not one markdown file name of its own', () => {
     // A folder path: the guide is read from the repository root and nowhere else.
-    expect(validateAgentsFileName('guides/HEXIS.md')).toMatch(/single file name/);
-    expect(validateAgentsFileName('guides\\HEXIS.md')).toMatch(/single file name/);
+    expect(validateGuideName('guides/HEXIS.md')).toMatch(/single file name/);
+    expect(validateGuideName('guides\\HEXIS.md')).toMatch(/single file name/);
     // Not markdown: the per-file access rules apply to `.md` alone.
-    expect(validateAgentsFileName('HEXIS.txt')).toMatch(/end in \.md/);
+    expect(validateGuideName('HEXIS.txt')).toMatch(/end in \.md/);
     // Nothing at all.
-    expect(validateAgentsFileName('')).toMatch(/required/);
-    expect(validateAgentsFileName('   ')).toMatch(/required/);
+    expect(validateGuideName('')).toMatch(/required/);
+    expect(validateGuideName('   ')).toMatch(/required/);
     // A dot-file every scanner skips — including the one that draws the tree.
-    expect(validateAgentsFileName('.hidden.md')).toMatch(/start with a dot/);
+    expect(validateGuideName('.hidden.md')).toMatch(/start with a dot/);
     // The guide's own pre-rename name stays legacy content.
-    expect(validateAgentsFileName('CLAUDE.md')).toMatch(/pre-rename name/);
-    expect(validateAgentsFileName('claude.md')).toMatch(/pre-rename name/);
+    expect(validateGuideName('CLAUDE.md')).toMatch(/pre-rename name/);
+    expect(validateGuideName('claude.md')).toMatch(/pre-rename name/);
     // The other platform files: two platform roles on one path.
-    expect(validateAgentsFileName('access.md')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('roles.yaml')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('.bevelignore')).toMatch(/platform file name/);
-    expect(validateAgentsFileName('mcp-description.md')).toMatch(/platform file name/);
+    expect(validateGuideName('access.md')).toMatch(/platform file name/);
+    expect(validateGuideName('roles.yaml')).toMatch(/platform file name/);
+    expect(validateGuideName('.bevelignore')).toMatch(/platform file name/);
+    expect(validateGuideName('mcp-description.md')).toMatch(/platform file name/);
     // The rule every path component passes.
-    expect(validateAgentsFileName('CON.md')).not.toBeNull();
-    expect(validateAgentsFileName('a:b.md')).not.toBeNull();
+    expect(validateGuideName('CON.md')).not.toBeNull();
+    expect(validateGuideName('a:b.md')).not.toBeNull();
   });
 
   test('refuses the name of a root folder, whichever of the two the save names', () => {
-    expect(validateAgentsFileName('Plugins.md', { ...DEFAULT_KB_LAYOUT, pluginsDir: 'Plugins.md' }))
+    expect(validateGuideName('Plugins.md', { ...DEFAULT_KB_LAYOUT, pluginsDir: 'Plugins.md' }))
       .toMatch(/already the plugins folder/);
     // Case-insensitively, like the folders are to each other: one entry on a
     // case-insensitive disk.
@@ -197,16 +202,16 @@ describe('KB layout — the agent guide\'s file name', () => {
       '.bevelignore',
       'AGENTS.md',
     ]);
-    expect(isPlatformFile('AGENTS.md')).toBe(true);
+    expect(platformFile('AGENTS.md')).toBe(true);
 
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(platformFileNames()).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
+    expect(platformFileNames(currentKbLayout())).toEqual(['access.md', 'roles.yaml', '.bevelignore', 'HEXIS.md']);
     // The guide the platform writes is immovable and undeletable…
-    expect(isPlatformFile('HEXIS.md')).toBe(true);
+    expect(platformFile('HEXIS.md')).toBe(true);
     // …and the customer's own AGENTS.md is a page like any other.
-    expect(isPlatformFile('AGENTS.md')).toBe(false);
+    expect(platformFile('AGENTS.md')).toBe(false);
     // Still root-only, as `roles.yaml` is: a nested copy is content.
-    expect(isPlatformFile('KnowledgeBase/HEXIS.md')).toBe(false);
+    expect(platformFile('KnowledgeBase/HEXIS.md')).toBe(false);
   });
 
   test('the pointer sentence is one sentence, naming the guide twice, from one place', () => {
@@ -215,7 +220,7 @@ describe('KB layout — the agent guide\'s file name', () => {
         "it is the platform's guide to its layout, files and rules.",
     );
     configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
-    expect(agentsFilePointerSentence()).toContain('HEXIS.md');
+    expect(agentsFilePointerSentence(currentKbLayout().agentsFile)).toContain('HEXIS.md');
   });
 
   /**
@@ -226,7 +231,7 @@ describe('KB layout — the agent guide\'s file name', () => {
    */
   test('the pointer sentence links correctly for a name full of markdown punctuation', () => {
     const name = 'Our [Agent] Guide (v2).md';
-    expect(validateAgentsFileName(name)).toBeNull();
+    expect(validateGuideName(name)).toBeNull();
     const sentence = agentsFilePointerSentence(name);
     // The label cannot end early: the brackets in it are escaped…
     expect(sentence).toContain('[Our \\[Agent\\] Guide (v2).md]');
@@ -240,7 +245,7 @@ describe('KB layout — the agent guide\'s file name', () => {
   test('the pointer sentence encodes a name that would otherwise open a URL fragment', () => {
     // `#` is legal in a filename and opens a fragment in a URL: `./#2 Guide.md`
     // links to the customer's OWN file with a fragment, not to the guide.
-    expect(validateAgentsFileName('#2 Guide.md')).toBeNull();
+    expect(validateGuideName('#2 Guide.md')).toBeNull();
     expect(agentsFilePointerSentence('#2 Guide.md')).toContain('(./%232%20Guide.md)');
     // `%` is legal too, and an unencoded one is a malformed escape.
     expect(agentsFilePointerSentence('100%.md')).toContain('(./100%25.md)');

package/src/core/__tests__/catalog-cache-invalidation.test.ts

@@ -4,6 +4,7 @@ import { FileChangeNotifier } from '../../modules/kb-fs/file-change-notifier.js'
 import { WorkflowEventBus } from '../../modules/workflow/event-bus.js';
 import { registerCatalogCacheInvalidation } from '../catalog-cache-invalidation.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
 
 const KB_DIR = 'knowledge-base';
 
@@ -25,7 +26,7 @@ function setup() {
   const off = registerCatalogCacheInvalidation({
     eventBus,
     fileChangeNotifier,
-    kbDirName: KB_DIR,
+    kb: testKbContext({ kbDirName: KB_DIR }),
     catalogs,
     accessControl,
   });

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

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
-import { createShutdown, holdCommitWorkerLease, withStartupTask, type LeasedWorker } from '../lifecycle.js';
+import { createShutdown, holdCommitWorkerLease, 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';
 
 /** A lease the suite scripts: what each `tryAcquire` answers, and a way to lose it. */
@@ -367,3 +368,79 @@ describe('createShutdown', () => {
     expect(d.order.filter((step) => step === 'db.end')).toHaveLength(1);
   });
 });
+
+describe('stopCore', () => {
+  function graph() {
+    const order: string[] = [];
+    return {
+      order,
+      core: {
+        commitWorker: {
+          async stop() {
+            order.push('commitWorker.stop');
+          },
+        },
+        backgroundJobs: {
+          stopSweeping() {
+            order.push('backgroundJobs.stopSweeping');
+          },
+          async drain() {
+            order.push('backgroundJobs.drain');
+          },
+        },
+        startupRetry: {
+          stop() {
+            order.push('startupRetry.stop');
+          },
+        },
+        db: {
+          $client: {
+            async end() {
+              order.push('db.end');
+            },
+          },
+        },
+        secretsScope: 'acme/t_acme',
+        log: () => undefined,
+      },
+    };
+  }
+
+  it('stops a graph without a server: sweeps and the retry first, the worker, then the pool', async () => {
+    const g = graph();
+    await stopCore(g.core as never);
+    expect(g.order).toEqual([
+      'backgroundJobs.stopSweeping',
+      'startupRetry.stop',
+      'backgroundJobs.drain',
+      'commitWorker.stop',
+      'db.end',
+    ]);
+  });
+
+  it('forgets the graph\'s secrets scope, so a descriptor that outlives it resolves nothing', async () => {
+    const g = graph();
+    registerBevelSecretsVariableLoader(
+      { resolve: async () => 'sk-live' } as never,
+      g.core.secretsScope,
+    );
+    const loader = new BevelSecretsVariableLoader('user-1', g.core.secretsScope);
+    expect(await loader.get('weather_KEY')).toBe('sk-live');
+    await stopCore(g.core as never);
+    expect(await loader.get('weather_KEY')).toBeNull();
+  });
+
+  it('stops a graph that never left a retry asking and never registered a scope', async () => {
+    const g = graph();
+    const core = { ...g.core, startupRetry: null, secretsScope: undefined };
+    await stopCore(core as never);
+    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'backgroundJobs.drain', 'commitWorker.stop', 'db.end']);
+  });
+
+  it('does not wait past the budget for a worker that never stops, and still ends the pool', async () => {
+    const g = graph();
+    const core = { ...g.core, commitWorker: { stop: () => new Promise<void>(() => undefined) } };
+    await stopCore(core as never, { deadlineMs: 50 });
+    expect(g.order).toEqual(['backgroundJobs.stopSweeping', 'startupRetry.stop', 'backgroundJobs.drain', 'db.end']);
+  });
+});

package/src/core/__tests__/public-config.test.ts

@@ -1,9 +1,13 @@
 import { describe, expect, it } from 'vitest';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
 import { publicConfig } from '../public-config.js';
+import { testKbContext } from '../../__tests__/kb-context.js';
 
 describe('GET /api/config payload', () => {
-  const body = publicConfig({ marketplaceGitUrl: 'https://kb.acme.com/git/marketplace.git', mcpUrl: 'https://kb.acme.com/api/mcp' });
+  const body = publicConfig(testKbContext(), {
+    marketplaceGitUrl: 'https://kb.acme.com/git/marketplace.git',
+    mcpUrl: 'https://kb.acme.com/api/mcp',
+  });
 
   it('advertises the agent-instructions capability, which the local bridge keys on', () => {
     expect(body.agentInstructions).toBe(true);

package/src/core/catalog-cache-invalidation.ts

@@ -1,7 +1,6 @@
-import { DEFAULT_BRANCH, PLUGINS_DIR, SKILLS_DIR } from '@bevel-software/platform-shared';
 import type { FileChangeNotifier } from '../modules/kb-fs/file-change-notifier.js';
 import type { WorkflowEventBus } from '../modules/workflow/event-bus.js';
-import { workspaceIdForBranch } from '../shared/workspace-id.js';
+import type { KbContext } from '../shared/kb-context.js';
 
 /**
  * A catalog that scans the DEFAULT branch's working tree and caches the result
@@ -26,8 +25,12 @@ export interface InvalidatableCatalog {
 export function registerCatalogCacheInvalidation(deps: {
   eventBus: WorkflowEventBus;
   fileChangeNotifier: FileChangeNotifier;
-  /** The KB folder inside the workspace — `paths` are workspace-relative. */
-  kbDirName: string;
+  /**
+   * The KB folder inside the workspace (`paths` are workspace-relative), the
+   * released branch, and the roots the catalogs read — read per event, never
+   * captured: a deployment may rename the roots from the setup screen.
+   */
+  kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId' | 'layout'>;
   catalogs: InvalidatableCatalog[];
   /**
    * The read gate every one of those catalogs is FILTERED through, dropped on
@@ -44,13 +47,13 @@ export function registerCatalogCacheInvalidation(deps: {
    */
   accessControl: { invalidate(workspaceId: string): void };
 }): () => void {
-  const { eventBus, fileChangeNotifier, kbDirName, catalogs, accessControl } = deps;
+  const { eventBus, fileChangeNotifier, kb, catalogs, accessControl } = deps;
   const invalidateAll = () => {
     for (const c of catalogs) c.invalidate();
     // Scoped to the branch the catalogs read, and no wider: a drop here costs
     // the next reader one model load, so it must not reach workspaces this
     // event says nothing about.
-    accessControl.invalidate(workspaceIdForBranch(DEFAULT_BRANCH));
+    accessControl.invalidate(kb.defaultWorkspaceId());
   };
 
   // Subscriber A — COMMIT-time freshness: a committed change drops the affected
@@ -61,17 +64,19 @@ export function registerCatalogCacheInvalidation(deps: {
   // service it belongs to — the caches are independent, so the split preserves
   // behavior.)
   const offFiles = fileChangeNotifier.onFilesChanged(({ branch, paths }) => {
-    if (branch !== DEFAULT_BRANCH) return;
+    if (branch !== kb.defaultBranch) return;
     // Skills, tools, the plugin index and the link index all read `Plugins/`
     // or `Skills/`, so one touch check drives every cache. An access grant
     // lands as a default-branch change to `Plugins/<plugin>/access.md` or a
     // skill folder's `access.md`, so this is also what makes a newly-granted
     // plugin or link unlock within one round-trip instead of one TTL. Both
-    // names are live bindings (a deployment may rename the roots), hence read
-    // per event rather than captured.
+    // names are read per event rather than captured: a deployment may rename
+    // the roots.
+    const { kbDirName, layout } = kb;
     if (
       paths.some(
-        (p) => p.startsWith(`${kbDirName}/${PLUGINS_DIR}/`) || p.startsWith(`${kbDirName}/${SKILLS_DIR}/`),
+        (p) =>
+          p.startsWith(`${kbDirName}/${layout.pluginsDir}/`) || p.startsWith(`${kbDirName}/${layout.skillsDir}/`),
       )
     ) {
       invalidateAll();
@@ -100,7 +105,7 @@ export function registerCatalogCacheInvalidation(deps: {
     if (event.kind !== 'fs-tree-changed' && event.kind !== 'git-sync-recovered') return;
     // Both events declare `branch`, so no `in` guard: the kind check above has
     // already narrowed the union to the two that carry one.
-    if (event.branch !== DEFAULT_BRANCH) return;
+    if (event.branch !== kb.defaultBranch) return;
     invalidateAll();
   });
 

package/src/core/core-ports.ts

@@ -6,6 +6,7 @@ import type {
 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 { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
 
 /**
@@ -98,6 +99,24 @@ export interface CorePorts {
    * contract each step signs up to). Core default: `[]`.
    */
   kbStartupSteps?: readonly OnServerStart[];
+  /**
+   * Mirror this composition's branch model and knowledge-base layout onto the
+   * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,
+   * `PLUGINS_DIR`, …), for an overlay that still reads them. Core itself
+   * reads only `CoreServices.kb`. Default true, so an overlay behaves as it
+   * did; a host that serves several knowledge bases in one process passes
+   * false, since there is no single value to put there.
+   */
+  mirrorSharedBindings?: boolean;
+  /**
+   * Whether a NEW account may be provisioned, asked before the row is
+   * inserted on every path that creates one (a first SSO sign-in, an admin
+   * creating an account, the owner's bootstrap sign-in, an embed identity).
+   * Core default: everyone is admitted. A host that sells seats answers
+   * from its plan; a refusal carries the port's own words to the person or
+   * admin who asked. See `modules/auth/account-admission.ts`.
+   */
+  accountAdmission?: IAccountAdmission;
 }
 
 /**