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

package/src/shared/__tests__/kb-layout.plugin.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest';
-import { pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT, pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
+
+/** `pluginOfPath` under the default layout, which these cases are written against. */
+const plugin = (path: string) => pluginOfPath(path, DEFAULT_KB_LAYOUT);
 
 /**
  * `pluginOfPath` is the whole of the grouping contract — the sidebar, the
@@ -9,9 +12,9 @@ import { pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
  */
 describe('pluginOfPath', () => {
   it('reads the plugin from the Plugins root', () => {
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM/heyreach-campaign/SKILL.md`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM/heyreach.tool`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}/Engineering/review/architecture-review`)).toBe(
+    expect(plugin(`${PLUGINS_DIR}/GTM/heyreach-campaign/SKILL.md`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}/GTM/heyreach.tool`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}/Engineering/review/architecture-review`)).toBe(
       'Engineering',
     );
   });
@@ -19,27 +22,27 @@ describe('pluginOfPath', () => {
   it('returns null for content directly under the root — it has no plugin folder', () => {
     // The regression this guards: `Plugins/slack.tool` must NOT report a plugin
     // called "slack.tool", and `Plugins/GTM` must not report itself.
-    expect(pluginOfPath(`${PLUGINS_DIR}/slack.tool`)).toBeNull();
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM`)).toBeNull();
-    expect(pluginOfPath(PLUGINS_DIR)).toBeNull();
+    expect(plugin(`${PLUGINS_DIR}/slack.tool`)).toBeNull();
+    expect(plugin(`${PLUGINS_DIR}/GTM`)).toBeNull();
+    expect(plugin(PLUGINS_DIR)).toBeNull();
   });
 
   it('returns null outside the plugin root', () => {
-    expect(pluginOfPath('KnowledgeBase/Product/Knowledge/Foo.md')).toBeNull();
-    expect(pluginOfPath('Data/Engineering/Knowledge/Bar.md')).toBeNull();
+    expect(plugin('KnowledgeBase/Product/Knowledge/Foo.md')).toBeNull();
+    expect(plugin('Data/Engineering/Knowledge/Bar.md')).toBeNull();
     // The retired pre-merge roots are ordinary non-plugin folders now.
-    expect(pluginOfPath('Skills/GTM/heyreach-campaign')).toBeNull();
-    expect(pluginOfPath('Tools/NewsAgent/serper.tool')).toBeNull();
-    expect(pluginOfPath('access.md')).toBeNull();
-    expect(pluginOfPath('')).toBeNull();
+    expect(plugin('Skills/GTM/heyreach-campaign')).toBeNull();
+    expect(plugin('Tools/NewsAgent/serper.tool')).toBeNull();
+    expect(plugin('access.md')).toBeNull();
+    expect(plugin('')).toBeNull();
   });
 
   it('is not fooled by a prefix match on the root name', () => {
-    expect(pluginOfPath('PluginsOld/GTM/x')).toBeNull();
+    expect(plugin('PluginsOld/GTM/x')).toBeNull();
   });
 
   it('tolerates leading and doubled separators', () => {
-    expect(pluginOfPath(`/${PLUGINS_DIR}/GTM/x`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}//GTM//x`)).toBe('GTM');
+    expect(plugin(`/${PLUGINS_DIR}/GTM/x`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}//GTM//x`)).toBe('GTM');
   });
 });

package/src/shared/git-internals.ts

@@ -107,7 +107,13 @@ async function resolvedRealPath(absolutePath: string): Promise<string | null> {
  * Refuse a path under `rootDir` that names the git folder or resolves into it.
  *
  * `inputPath` is the caller's own spelling (checked lexically, encoded forms
- * included); `absolutePath` is where it lands on disk. Only the part below
+ * included, and probed on disk every way it could land — see
+ * {@link candidateTargets}); `absolutePath`, when a layer has already
+ * decided where the path goes, is that place, judged AS WELL. Both in one
+ * call, because the two answer different questions — a link reached by a
+ * reading this layer does not use is caught only by the spelling, a link the
+ * layer's own resolution follows only by the place — and one call walks the
+ * root once and probes a place that both name once. Only the part below
  * `rootDir` is judged, so a workspaces root that itself sits under some
  * `.git` directory does not refuse everything. A link that leaves the root
  * is judged on its target's path relative to the root, so a link into
@@ -116,9 +122,58 @@ async function resolvedRealPath(absolutePath: string): Promise<string | null> {
  */
 export async function assertNotGitInternals(rootDir: string, inputPath: string, absolutePath?: string): Promise<void> {
   assertNoGitInternalsSegment(inputPath);
-  const target = absolutePath ?? path.resolve(rootDir, inputPath.replace(/^[\\/]+/, ''));
-  if (hasGitInternalsSegment(path.relative(path.resolve(rootDir), target))) throw new GitInternalsError();
-  const [realTarget, realRoot] = await Promise.all([resolvedRealPath(target), resolvedRealPath(path.resolve(rootDir))]);
-  if (realTarget === null || realRoot === null) return;
-  if (hasGitInternalsSegment(path.relative(realRoot, realTarget))) throw new GitInternalsError();
+  const root = path.resolve(rootDir);
+  const realRoot = await resolvedRealPath(root);
+  // Each place once, remembering whether a layer resolved it (probed as
+  // given) or only a spelling named it (probed only inside the root).
+  const targets = new Map<string, boolean>();
+  for (const target of candidateTargets(root, inputPath)) targets.set(target, false);
+  if (absolutePath !== undefined) targets.set(absolutePath, true);
+  for (const [target, resolved] of targets) {
+    const relative = path.relative(root, target);
+    if (hasGitInternalsSegment(relative)) throw new GitInternalsError();
+    if (realRoot === null) continue;
+    // A raw spelling fans out into candidates, and one of them can name a
+    // place outside the workspace entirely — `/etc/…`, a deep climb. Such a
+    // candidate is judged by the lexical reading above (a link into another
+    // checkout's `.git` is named there) but NOT probed on disk: probing it
+    // would let an unreadable external directory answer with its own
+    // `EACCES` instead of the path rule's typed refusal for a spelling that
+    // was never a workspace path. A path a layer already resolved is the one
+    // place it is, so it is probed as given.
+    // `..` and `../…` are the climbs; `..link` is an ordinary name that merely
+    // starts with those characters, and a link by that name can point into the
+    // folder — so it is probed like any other entry under the root.
+    const climbsOut = relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+    if (!resolved && (relative === '' || climbsOut)) continue;
+    const realTarget = await resolvedRealPath(target);
+    if (realTarget !== null && hasGitInternalsSegment(path.relative(realRoot, realTarget))) throw new GitInternalsError();
+  }
+}
+
+/**
+ * Every place one raw spelling could LAND, because a spelling is not yet a
+ * path until something decides how to read it.
+ *
+ * A backslash separates segments on Windows and is an ordinary character in a
+ * filename here, so `kb\\Notes\\..\\link` is read BOTH ways; an absolute path
+ * is both the path it names and — as every workspace caller reads it — that
+ * path with its leading slashes dropped, under the workspace; and a leading
+ * climb (`../kb/link`) is both the climb it spells and the path left when the
+ * climb is dropped, which is how a lenient reader takes it. The spelling is
+ * refused when ANY reading lands in the git folder: which reading a later
+ * layer picks is not something this rule should have to predict.
+ *
+ * This is what a CALLER's own spelling needs. A path some layer has already
+ * resolved arrives as `absolutePath` and is judged as the one place it is.
+ */
+function candidateTargets(root: string, inputPath: string): string[] {
+  const targets = new Set<string>();
+  for (const spelling of new Set([inputPath, inputPath.replace(/\\/g, '/')])) {
+    const anchored = spelling.replace(/^[\\/]+/, '');
+    targets.add(path.resolve(root, anchored));
+    targets.add(path.resolve(root, anchored.replace(/^(\.\.?[\\/])+/, '')));
+    if (/^[\\/]/.test(spelling)) targets.add(path.resolve(spelling));
+  }
+  return [...targets];
 }

package/src/shared/git.contract.ts

@@ -39,21 +39,76 @@
  */
 
 /**
- * Strip the configured git token out of text on its way into an error, a log
- * line or a response.
+ * The credential git authenticates a knowledge base's remote with: the
+ * Basic-auth username the host expects and the token that is its password.
+ *
+ * A PROVIDER, read at every call, not a value captured at boot: the setup
+ * screen can supply a token after the graph is built, and a token rotated in
+ * the settings has to be the one the next push carries. The runner puts the
+ * token into the child's environment under {@link GIT_TOKEN_ENV}, which is
+ * the only place git reads it from (the inline credential helper spells
+ * `password=$GITHUB_TOKEN`), so the value never enters argv, a clone's
+ * config, or a message that quotes either. Nothing writes it into THIS
+ * process's environment: a server hosting several knowledge bases has one
+ * environment and several tokens.
+ */
+export interface GitCredentials {
+  /**
+   * The username sent in the Basic credential: GitHub `x-access-token`,
+   * GitLab `oauth2`, Bitbucket `x-token-auth`. Interpolated into the helper
+   * snippet, so callers validate it against `[A-Za-z0-9._-]+` before it
+   * gets here.
+   */
+  username(): string;
+  /** The token in effect, or null when the deployment has none configured. */
+  token(): string | null;
+}
+
+/** The username git is given when a deployment names none. */
+export const DEFAULT_GIT_USERNAME = 'x-access-token';
+
+/**
+ * The environment variable the child git process reads the token from. The
+ * name is historical (the first supported host), and it is the literal every
+ * app-stamped credential helper carries, which is what lets a re-stamp find
+ * its own helpers in a clone's config and leave an operator's alone.
+ */
+export const GIT_TOKEN_ENV = 'GITHUB_TOKEN';
+
+/** No token, the default username: an unauthenticated runner. */
+export const NO_GIT_CREDENTIALS: GitCredentials = Object.freeze({
+  username: () => DEFAULT_GIT_USERNAME,
+  token: () => null,
+});
+
+/** A provider from values or thunks, for a composition root or a test. */
+export function gitCredentials(
+  username: string | (() => string) = DEFAULT_GIT_USERNAME,
+  token: string | null | (() => string | null) = null,
+): GitCredentials {
+  const user = typeof username === 'function' ? username : () => username;
+  const secret = typeof token === 'function' ? token : () => token;
+  return {
+    username: () => user() || DEFAULT_GIT_USERNAME,
+    token: () => secret() || null,
+  };
+}
+
+/**
+ * Strip a git token out of text on its way into an error, a log line or a
+ * response.
  *
  * git puts the remote URL into a great many of its messages, and on a
  * token-authenticated remote that URL carries the credential. Without this, a
  * push failure writes the deployment's token into the container log, the API
  * response, and any change request the recovery agent opens about it.
  *
- * Read from the environment at call time rather than captured: the setup screen
- * can supply a token after boot, and `DeploymentSettingsService.syncGitTokenEnv`
- * puts it here — a value captured at module load would be the empty string for
- * exactly the deployments that configure their token that way.
+ * The token is the caller's to name (the runner names its own), never read
+ * from this process's environment: the environment holds no per-knowledge-
+ * base token any more, and a scrub that silently found none there would look
+ * like one that worked.
  */
-export function redactGitToken(text: string): string {
-  const token = process.env.GITHUB_TOKEN;
+export function redactGitToken(text: string, token: string | null | undefined): string {
   const scrubbed = token ? text.replaceAll(token, '***') : text;
   // URL userinfo as well: a remote spelled `https://user:pass@host` would
   // otherwise leak `pass` verbatim through every git failure that quotes the
@@ -165,6 +220,13 @@ export interface IGitRunner {
    * constant.
    */
   readonly defaultTimeoutMs: number;
+  /**
+   * The credential every call through this runner authenticates with — see
+   * {@link GitCredentials}. Exposed so the code that stamps a clone's helper
+   * or scrubs a message can ask the same runner it runs git through whether
+   * a token is in effect, rather than a second source that could disagree.
+   */
+  readonly credentials: GitCredentials;
   run(cwd: string, args: string[], opts: GitRunOptions & { encoding: 'buffer' }): Promise<GitRunResult<Buffer>>;
   run(cwd: string, args: string[], opts?: GitRunOptions & { encoding?: 'utf8' }): Promise<GitRunResult>;
 }

package/src/shared/kb-context.ts

@@ -0,0 +1,130 @@
+import {
+  UNCONFIGURED_BRANCH_MODEL,
+  isBranchModelConfigured,
+  isProtectedBranch,
+  resolveBranchModel,
+  resolveKbLayout,
+  validateBranchModel,
+  type BranchModel,
+  type BranchModelValue,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from './workspace-id.js';
+
+/**
+ * What ONE knowledge base is called, on disk and in git: the checkout folder
+ * inside each workspace, the branch model (default + protected branches) and
+ * the layout (the three renameable roots and the guide's file name).
+ *
+ * Every service that needs one of these is handed the knowledge base's
+ * context at construction and reads it there — never a process-wide value.
+ * The shared package's live bindings (`DEFAULT_BRANCH`, `PLUGINS_DIR`, …) are
+ * the BROWSER'S copy of the same facts and are forbidden in this package by
+ * an ESLint rule: a server hosting several knowledge bases in one process has
+ * no single value to put there, and a service that read one would be reading
+ * whichever knowledge base configured it last.
+ *
+ * LIVE, PER INSTANCE. The values are read through getters, not captured, for
+ * the same reason the live bindings were: a fresh deployment has no branch
+ * model until its setup screen is answered, and the save that completes setup
+ * applies one to the running graph — through {@link applyBranchModel} and
+ * {@link applyLayout} — so the knowledge-base startup phase that runs in that
+ * same request already sees it. Read `defaultBranch` inside a method body;
+ * a value copied into a field at construction would be the empty string on
+ * exactly those deployments.
+ */
+export class KbContext {
+  private model: BranchModelValue;
+  private layoutValue: Required<KbLayout>;
+  private readonly layoutListeners = new Set<() => void>();
+  private readonly branchModelListeners = new Set<() => void>();
+
+  constructor(
+    /** The checkout folder inside each workspace directory (`knowledge-base` by default). */
+    readonly kbDirName: string,
+    branchModel: BranchModelValue,
+    layout: KbLayout,
+  ) {
+    this.model = branchModel;
+    this.layoutValue = resolveKbLayout(layout);
+  }
+
+  /**
+   * The model as a deployment's settings describe it, or the unconfigured one
+   * when they describe none yet. UNCONFIGURED IS ALLOWED, and that is the
+   * point: a fresh deployment has no branch model, and refusing to build
+   * services would take away the setup screen where one gets entered. What
+   * reads the model before then is the setup path itself, which does not need
+   * it; the setup gate keeps the rest of the app shut until it is set.
+   */
+  static branchModelOrUnconfigured(model: BranchModel): BranchModelValue {
+    return validateBranchModel(model) ? UNCONFIGURED_BRANCH_MODEL : resolveBranchModel(model);
+  }
+
+  get branchModel(): BranchModelValue {
+    return this.model;
+  }
+
+  /** The branch users land on and the default propose target; `''` until configured. */
+  get defaultBranch(): string {
+    return this.model.defaultBranch;
+  }
+
+  get protectedBranches(): ReadonlySet<string> {
+    return this.model.protectedBranches;
+  }
+
+  isProtectedBranch(name: string | null | undefined): boolean {
+    return isProtectedBranch(this.model, name);
+  }
+
+  isBranchModelConfigured(): boolean {
+    return isBranchModelConfigured(this.model);
+  }
+
+  /** The workspace id of the default branch's clone — the released catalog's home. */
+  defaultWorkspaceId(): string {
+    return workspaceIdForBranch(this.model.defaultBranch);
+  }
+
+  /** The layout in effect: the three roots and the guide's file name, every name trimmed. */
+  get layout(): Required<KbLayout> {
+    return this.layoutValue;
+  }
+
+  /**
+   * Apply a branch model to the running graph — the setup-completing save.
+   * Validated like every model, so a bad pair is refused rather than applied
+   * half-way. Listeners run after the value is in place.
+   */
+  applyBranchModel(model: BranchModel): void {
+    this.model = resolveBranchModel(model);
+    for (const listener of this.branchModelListeners) listener();
+  }
+
+  /**
+   * Apply a layout to the running graph — the setup-completing save, so the
+   * knowledge-base phase that runs in the same request scaffolds the names the
+   * admin just chose. Throws on an invalid one. Listeners run after the value
+   * is in place, and only when the layout was accepted.
+   */
+  applyLayout(layout: KbLayout): void {
+    this.layoutValue = resolveKbLayout(layout);
+    for (const listener of this.layoutListeners) listener();
+  }
+
+  /**
+   * Be told when {@link applyLayout} runs — for the few things that cannot
+   * read the layout at the moment they are used: a value BUILT ONCE and handed
+   * to something that keeps it, such as the tool catalog's descriptions, which
+   * are validated into frozen defs at registration and then served from a map.
+   */
+  onLayoutApplied(listener: () => void): void {
+    this.layoutListeners.add(listener);
+  }
+
+  /** Be told when {@link applyBranchModel} runs. */
+  onBranchModelApplied(listener: () => void): void {
+    this.branchModelListeners.add(listener);
+  }
+}

package/src/shared/kb-layout.test.ts

@@ -1,32 +1,42 @@
 import { describe, it, expect } from 'vitest';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { ontologyOf } from './kb-layout.js';
 
+/** `ontologyOf` under the default layout, which is what these cases are written against. */
+const ont = (path: string, kbDirName?: string) => ontologyOf(path, DEFAULT_KB_LAYOUT, kbDirName);
+
 describe('ontologyOf', () => {
+  it('classifies under the knowledge-base root the layout names, not the default one', () => {
+    const layout = { ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'docs' };
+    expect(ontologyOf('docs/Product/Knowledge/Foo.md', layout)).toBe('docs/Product');
+    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md', layout)).toBeNull();
+  });
+
   it('resolves a named ontology under Knowledge', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
   });
 
   it('resolves a named ontology under NodeTypes', () => {
-    expect(ontologyOf('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
   });
 
   it('is space-safe in the ontology name', () => {
-    expect(ontologyOf('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
+    expect(ont('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
       'KnowledgeBase/IT Architecture',
     );
   });
 
   it('treats a nested ontology directory as the full prefix before the marker', () => {
-    expect(ontologyOf('KnowledgeBase/Plugin/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Plugin/Sub');
+    expect(ont('KnowledgeBase/Plugin/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Plugin/Sub');
   });
 
   it('returns null when the marker sits directly under KnowledgeBase/', () => {
-    expect(ontologyOf('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/NodeTypes/T.md')).toBeNull();
+    expect(ont('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
+    expect(ont('KnowledgeBase/NodeTypes/T.md')).toBeNull();
   });
 
   it('returns null for root-level Knowledge (not under KnowledgeBase/)', () => {
-    expect(ontologyOf('Knowledge/Foo.md')).toBeNull();
+    expect(ont('Knowledge/Foo.md')).toBeNull();
   });
 
   it('returns null for Data/ ontologies (deliberate session-ontology exemption)', () => {
@@ -35,54 +45,54 @@ describe('ontologyOf', () => {
     // Data paths as neutral — pipeline agents read knowledge and write data
     // in one session (owner decision 2026-07-27). See the `ontologyOf`
     // docstring; this is not drift.
-    expect(ontologyOf('Data/Ops/Knowledge/x.md')).toBeNull();
-    expect(ontologyOf('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
+    expect(ont('Data/Ops/Knowledge/x.md')).toBeNull();
+    expect(ont('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
     // KnowledgeBase paths still classify as before.
-    expect(ontologyOf('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
+    expect(ont('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
   });
 
   it('returns null for Plugins and root config (neutral)', () => {
-    expect(ontologyOf('Plugins/some-skill/SKILL.md')).toBeNull();
-    expect(ontologyOf('access.md')).toBeNull();
-    expect(ontologyOf('roles.yaml')).toBeNull();
+    expect(ont('Plugins/some-skill/SKILL.md')).toBeNull();
+    expect(ont('access.md')).toBeNull();
+    expect(ont('roles.yaml')).toBeNull();
   });
 
   it('returns null for an ontology path with no marker segment', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
+    expect(ont('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
   });
 
   it('does not match substring lookalikes (segment equality)', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
+    expect(ont('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
+    expect(ont('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
   });
 
   it('strips a kbDirName prefix (normalized and un-normalized)', () => {
-    expect(ontologyOf('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
+    expect(ont('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
       'KnowledgeBase/Product',
     );
-    expect(ontologyOf('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
+    expect(ont('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
       'KnowledgeBase/GTM',
     );
   });
 
   it('normalizes backslashes and leading/trailing slashes', () => {
-    expect(ontologyOf('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
   });
 
   it('canonicalizes inner . and .. segments to the same ontology', () => {
-    expect(ontologyOf('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
     // `..` also collapses inside the stripped kbDirName prefix.
-    expect(ontologyOf('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
+    expect(ont('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
       'KnowledgeBase/GTM',
     );
   });
 
   it('returns null for empty or root paths', () => {
-    expect(ontologyOf('')).toBeNull();
-    expect(ontologyOf('KnowledgeBase')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/Product')).toBeNull();
+    expect(ont('')).toBeNull();
+    expect(ont('KnowledgeBase')).toBeNull();
+    expect(ont('KnowledgeBase/Product')).toBeNull();
   });
 });

package/src/shared/kb-layout.ts

@@ -1,4 +1,4 @@
-import { KNOWLEDGE_BASE_DIR, ONTOLOGY_MARKERS, type Ontology } from '@bevel-software/platform-shared';
+import { ONTOLOGY_MARKERS, type KbLayout, type Ontology } from '@bevel-software/platform-shared';
 
 /**
  * Resolve which named ontology a KB path belongs to — the backend-side
@@ -81,13 +81,14 @@ function toSegments(path: string, kbDirName?: string): string[] {
  * `Knowledge-notes.md` are never treated as markers; space-safe; pure (no IO).
  *
  * @param path       repo-root-relative POSIX path (may carry a `kbDirName` prefix)
+ * @param layout     the knowledge base's layout — names its `KnowledgeBase/` root
  * @param kbDirName  optional on-disk clone folder prefix to strip first
  */
-export function ontologyOf(path: string, kbDirName?: string): Ontology {
+export function ontologyOf(path: string, layout: KbLayout, kbDirName?: string): Ontology {
   const segs = toSegments(path, kbDirName);
   // Must live under the dedicated KnowledgeBase/ container, with at least one
   // ontology-name segment and a marker after it (so length >= 3).
-  if (segs.length < 3 || segs[0] !== KNOWLEDGE_BASE_DIR) return null;
+  if (segs.length < 3 || segs[0] !== layout.knowledgeBaseDir) return null;
   // The ontology id is the prefix before the first marker segment. Require at
   // least one name segment between `KnowledgeBase/` and the marker, so a marker
   // sitting directly under `KnowledgeBase/` (`KnowledgeBase/Knowledge/...`) is

package/src/shared/pending-proposals.ts

@@ -1,6 +1,6 @@
-import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import type { ChangeRequest, IWorkflowService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../modules/workspace/workspace.service.js';
-import { workspaceIdForBranch } from './workspace-id.js';
+import type { KbContext } from './kb-context.js';
 import type { IAccessControl } from '../modules/access/access-control.interface.js';
 import { canonicalEmail, hashEmail } from './email-identity.js';
 import { printable } from './printable.js';
@@ -34,6 +34,8 @@ export interface ProposalSources {
   workspaceService: Pick<WorkspaceService, 'ensureRemotesFetched' | 'readFileAtRef'>;
   accessControl: Pick<IAccessControl, 'canWriteBatch'>;
   workflow: Pick<IWorkflowService, 'listChangeRequests'>;
+  /** Which branch is the released one, and its clone. */
+  kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>;
 }
 
 /** One file an open change request proposes, already read at that request's branch. */
@@ -78,8 +80,9 @@ export async function visibleProposedFiles(
     // access tree that decides who may review — so a request targeting some
     // other branch is not a proposal these surfaces can speak about: merging it
     // puts nothing in the catalog, and the card would never resolve.
+    const defaultBranch = sources.kb.defaultBranch;
     crs = (await sources.workflow.listChangeRequests()).filter(
-      (c) => c.state === 'open' && c.base === DEFAULT_BRANCH,
+      (c) => c.state === 'open' && c.base === defaultBranch,
     );
   } catch {
     return [];
@@ -91,7 +94,7 @@ export async function visibleProposedFiles(
   );
   if (candidates.length === 0) return [];
 
-  const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+  const wsId = sources.kb.defaultWorkspaceId();
   const authorHash = hashEmail(email);
 
   // One access load for every candidate, resolved on the DEFAULT branch — see

package/src/shared/redact-secret.ts

@@ -6,11 +6,11 @@
  * presigned remote keeps its credential.
  *
  * "The token in effect" is every place one can come from: each environment
- * spelling `CoreConfig` accepts (it normalises them onto `GITHUB_TOKEN` at
- * boot, but a later write to one of them is not normalised), plus whatever the
- * caller knows about — the settings-stored token, a token a request brought
- * along, or a remote's query values ({@link urlQuerySecrets}). Longest first,
- * so a secret that contains another is not half-scrubbed.
+ * spelling `CoreConfig` accepts (the operator's, process-wide), plus whatever
+ * the caller knows about — the knowledge base's own token as its git runner
+ * carries it, a token a request brought along, or a remote's query values
+ * ({@link urlQuerySecrets}). Longest first, so a secret that contains another
+ * is not half-scrubbed.
  *
  * Shared, not a module's own: the KB startup phase and the setup routes both
  * log git's words, and one scrub is the only way they cannot disagree about