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

package/src/shared/domain-errors.ts

@@ -167,6 +167,64 @@ export class PullRebaseConflictError extends WorkflowDomainError {
   }
 }
 
+/**
+ * The one sentence a branch-less call is answered with. Names the input and
+ * what to pass, and carries NO stringified value of what was actually
+ * received: the whole point of this refusal is that the caller sent nothing,
+ * and echoing `undefined` back at them is how the branch "undefined" got
+ * invented in the first place.
+ */
+export const BRANCH_REQUIRED_MESSAGE =
+  '`branch` is required: pass the branch (draft) you are working on.';
+
+/**
+ * The caller named no branch — the input is missing, empty, not a string, or
+ * one of the stringified absent values (`"undefined"` / `"null"`) that a
+ * client produces by interpolating a variable it never set.
+ *
+ * Refused, never defaulted. A knowledge-base tool's workspace is NEVER implied
+ * by the credential (identity-only) — it always comes from this argument — so
+ * falling back to the deployment's default branch would make an omitted
+ * argument silently act on the protected branch. And it is refused HERE, at
+ * the boundary, because everything downstream treats the value as a real
+ * branch name: `workspaceIdForBranch` would turn it into a workspace directory
+ * literally named `undefined`, and the clone of that "branch" would fail with
+ * a story about a branch that never existed.
+ *
+ * 400 with kind `branch-required`, so a client tells it apart from the 404
+ * (no such branch) and the 410 (the branch was deleted) without reading prose.
+ */
+export class BranchRequiredError extends WorkflowDomainError {
+  readonly kind = 'branch-required' as const;
+  constructor() {
+    super(BRANCH_REQUIRED_MESSAGE, 400, { kind: 'branch-required' });
+    this.name = 'BranchRequiredError';
+  }
+}
+
+/**
+ * The stringified absent values. Both are syntactically valid git branch
+ * names, so the shape validator (`assertValidBranchName`) accepts them
+ * happily — accepting one is exactly the bug this guard exists for. They are
+ * refused BY NAME, which is why this check cannot be folded into the shape
+ * check however tempting that looks.
+ */
+const STRINGIFIED_ABSENT_VALUES = new Set(['undefined', 'null']);
+
+/**
+ * Refuse a call that names no branch, before anything downstream can turn the
+ * missing value into a directory name, a clone attempt or a log line.
+ *
+ * Deliberately NOT a shape check: a well-formed name this platform has never
+ * seen is a 404 the caller can act on, and a malformed one is a
+ * `BranchNameError` from the canonical validator. This answers only "you sent
+ * nothing", which is the one case where naming the branch back is impossible.
+ */
+export function assertBranchProvided(branch: unknown): asserts branch is string {
+  if (typeof branch !== 'string' || branch.length === 0) throw new BranchRequiredError();
+  if (STRINGIFIED_ABSENT_VALUES.has(branch)) throw new BranchRequiredError();
+}
+
 /**
  * The platform has never heard of this branch: nothing it has cloned, and
  * nothing any listing of origin's branches has mentioned. Distinct from

package/src/shared/git.contract.ts

@@ -39,21 +39,86 @@
  */
 
 /**
- * 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;
+  /**
+   * Make sure {@link token} answers with a credential that is still good,
+   * for one that is not fixed: a token a host issues for an hour has to be
+   * renewed by asking the host, which `token` cannot do, being read where
+   * nothing can wait. The runner awaits this before every call it makes. A
+   * failure here is not the call's failure: git runs with the token in
+   * hand, and the host says what it thinks of it. Absent for a credential
+   * that does not expire.
+   */
+  prepare?(): Promise<void>;
+}
+
+/** 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 +230,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