@bongos/core 1.17.0

package/src/instance-config.js

@@ -0,0 +1,200 @@
+// src/instance-config.js — the instance config namespace (R61 / task 1200, ADR 0062).
+//
+// Two instance-identity leaks lived hard-coded across the codebase: the CLI
+// config root (~/.config/otb/) and the OTB_*/PMS_*/GDS_* env-var prefixes. This
+// module makes BOTH resolve from the branding contract (src/branding.js) so a
+// fresh Cloud Bongos instance uses a neutral namespace, while keeping read-side
+// back-compat so existing OTB installs and old local sessions never break.
+//
+//   config dir  : ~/.config/<branding.configDir>   (OTB → "otb", vanilla → "cloudbongos")
+//   env prefix  : <branding.envPrefix>_<SUFFIX>     (OTB → "OTB_", vanilla → "CLOUDBONGOS_")
+//
+// The cut is deliberately ZERO-RISK for the live instance: OTB's branding pack
+// pins configDir="otb" + envPrefix="OTB", so every path + env read resolves to
+// EXACTLY what it does today. Only a fresh/neutral instance gets the neutral
+// namespace. On READ we additionally fall back to the historical hard-coded dir
+// and to the legacy env prefixes, so a value set the old way still resolves.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// Last-resort default if branding can't be read at all (vanilla, never OTB).
+const FALLBACK_DIR = 'cloudbongos';
+const FALLBACK_ENV_PREFIX = 'CLOUDBONGOS';
+
+// Historical hard-coded config dir — always also checked on READ so a session /
+// ledger / key written before R61 (or by an instance that later changed its
+// configDir) still resolves. Write always targets the configured dir.
+const LEGACY_DIRS = ['otb'];
+
+// Legacy env prefixes tried (in order) AFTER the configured one. These cover the
+// three prefixes that coexisted pre-R61 (OTB_ operational, GDS_ API/auth, PMS_
+// the original name). Keeping them means prod's existing env is honored verbatim.
+const LEGACY_ENV_PREFIXES = ['OTB', 'GDS', 'PMS'];
+
+// Lazy require (ADR 0108 §1 made this a two-way edge: branding.js now requires
+// resolveCoreRoot()/resolveInstanceRoot() from this module, so a top-level
+// require('./branding') here would form an eval-time cycle — branding.js would
+// receive this module's still-empty exports and crash on the undefined resolver).
+// By call time both modules have finished loading.
+function safeBrand() {
+  try { return require('./branding').branding(); } catch { return {}; }
+}
+
+function configDirName(b = safeBrand()) {
+  return b.configDir || FALLBACK_DIR;
+}
+
+function envPrefix(b = safeBrand()) {
+  return b.envPrefix || FALLBACK_ENV_PREFIX;
+}
+
+// Absolute path to the instance config dir — the WRITE target and first read.
+function configHome(b = safeBrand()) {
+  return path.join(os.homedir(), '.config', configDirName(b));
+}
+
+// All config dirs to try on READ, configured first then legacy, de-duped.
+function configReadDirs(b = safeBrand()) {
+  const home = os.homedir();
+  const dirs = [configHome(b)];
+  for (const d of LEGACY_DIRS) {
+    const p = path.join(home, '.config', d);
+    if (!dirs.includes(p)) dirs.push(p);
+  }
+  return dirs;
+}
+
+// Path to a named file inside the configured (write) config dir.
+function configPath(name, b = safeBrand()) {
+  return path.join(configHome(b), name);
+}
+
+// Every candidate path for a named config file, configured dir first then legacy
+// dirs — for read-with-fallback (the gds-session.json / cost_ledger pattern).
+function configReadPaths(name, b = safeBrand()) {
+  return configReadDirs(b).map((d) => path.join(d, name));
+}
+
+// Read the first existing copy of a config file across the read dirs (configured
+// dir first, then legacy ~/.config/otb). Returns the file contents, or null if
+// none exists. Non-ENOENT errors (e.g. permissions) propagate. This is the
+// read-side back-compat shim every local-dev config file (discord-bot.json,
+// gds-github.json, the secret key, …) routes through.
+function readConfigFileSync(name, { encoding = 'utf8', b = safeBrand() } = {}) {
+  for (const p of configReadPaths(name, b)) {
+    try { return fs.readFileSync(p, encoding); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+  }
+  return null;
+}
+
+// Resolve an env var by SUFFIX across the configured prefix + legacy prefixes.
+// resolveEnv('API_BASE') tries <PREFIX>_API_BASE (CLOUDBONGOS_ on vanilla, OTB_
+// on the OTB instance), then OTB_/GDS_/PMS_API_BASE. Returns undefined if none
+// is set to a non-empty value. `extraLegacy` prepends suffix-specific aliases
+// (rare — e.g. a var that had an idiosyncratic legacy name).
+function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy = LEGACY_ENV_PREFIXES } = {}) {
+  const seen = new Set();
+  for (const pfx of [prefix, ...legacy]) {
+    if (!pfx || seen.has(pfx)) continue;
+    seen.add(pfx);
+    const v = env[`${pfx}_${suffix}`];
+    if (v !== undefined && v !== '') return v;
+  }
+  return undefined;
+}
+
+// resolveCoreRoot() / resolveInstanceRoot() — the ADR 0108 §1 configurable-root
+// resolvers, extending this module's established zero-risk pattern from
+// ~/.config to the in-repo roots. Two OPPOSITE directions, both load-bearing:
+//
+//   resolveCoreRoot()     -> where the core PACKAGE's own files live (core
+//                            modules/, core migrations/, infra/ installers,
+//                            *.neutral.json defaults). Today: the repo root
+//                            (this file lives at <root>/src/instance-config.js).
+//                            Packaged later: the node_modules package dir —
+//                            that flip needs no further per-site edits.
+//
+//   resolveInstanceRoot() -> where HOST content lives (config/, instance
+//                            modules/, migrations/instance/, identity).
+//                            Precedence: <PREFIX>_INSTANCE_ROOT env -> a
+//                            bongos.config.json pointer -> process.cwd().
+//
+// Today process.cwd() === resolveCoreRoot() === the single repo root (the
+// live instance runs from its own checkout), so routing a reader through
+// either resolver is BYTE-IDENTICAL for prod. The split only diverges once a
+// consumer repo installs the core as a dependency.
+function resolveCoreRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+// Reads an optional bongos.config.json at `cwd` for an `instanceRoot` pointer
+// (a relative or absolute path). Returns undefined when absent/invalid so the
+// caller falls through to process.cwd() — a missing/malformed pointer must
+// never crash boot (same fail-to-default posture as branding/modules).
+function readInstanceRootPointer(cwd = process.cwd()) {
+  try {
+    const raw = fs.readFileSync(path.join(cwd, 'bongos.config.json'), 'utf8');
+    const j = JSON.parse(raw);
+    if (j && typeof j.instanceRoot === 'string' && j.instanceRoot.trim()) {
+      return path.resolve(cwd, j.instanceRoot);
+    }
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  return undefined;
+}
+
+// The instance root ONLY when it is EXPLICITLY pointed at (env var or a
+// bongos.config.json pointer) — never the cwd fallback. `null` when neither is
+// set. Callers that must write to a DETERMINISTIC location (a generated-doc
+// write) use this so the output never lands "wherever the process happens to be".
+function resolveInstanceRootExplicit({ env = process.env } = {}) {
+  // prefix is pinned to FALLBACK_ENV_PREFIX rather than envPrefix()'s default —
+  // envPrefix() reads the brand pack, and the brand pack's own path is resolved
+  // FROM this function (branding.js's INSTANCE_PATH calls resolveInstanceRoot()).
+  // Calling back into safeBrand() here would be a genuine self-reference, not
+  // just a require-order artifact. LEGACY_ENV_PREFIXES already covers OTB's
+  // configured prefix, so this is byte-identical for the live instance (mirrors
+  // GDS_BRANDING_FILE's own "read before the resolved envPrefix is known" rule).
+  const fromEnv = resolveEnv('INSTANCE_ROOT', { env, prefix: FALLBACK_ENV_PREFIX });
+  if (fromEnv) return path.resolve(fromEnv);
+  const fromConfig = readInstanceRootPointer();
+  if (fromConfig) return fromConfig;
+  return null;
+}
+
+function resolveInstanceRoot({ env = process.env } = {}) {
+  return resolveInstanceRootExplicit({ env }) || process.cwd();
+}
+
+// Where a PER-INSTANCE generated artifact (the OpenAPI spec + the typed client)
+// is written/read. A consumer that installs the core as an npm dep points at its
+// own repo (via <PREFIX>_INSTANCE_ROOT / bongos.config.json — e.g. `bongos
+// upgrade` sets it), so the docs+client regenerate INTO the instance, not into
+// node_modules/@cloudbongos/core. In a single checkout no pointer is set, so this
+// is resolveCoreRoot() — BYTE-IDENTICAL to today (ADR 0108). Deliberately NOT the
+// cwd fallback: a generated-doc write must be deterministic.
+function resolveDocsRoot(opts = {}) {
+  return resolveInstanceRootExplicit(opts) || resolveCoreRoot();
+}
+
+module.exports = {
+  FALLBACK_DIR,
+  FALLBACK_ENV_PREFIX,
+  LEGACY_DIRS,
+  LEGACY_ENV_PREFIXES,
+  configDirName,
+  envPrefix,
+  configHome,
+  configReadDirs,
+  configPath,
+  configReadPaths,
+  readConfigFileSync,
+  resolveEnv,
+  resolveCoreRoot,
+  resolveInstanceRoot,
+  resolveInstanceRootExplicit,
+  resolveDocsRoot,
+  readInstanceRootPointer,
+};

package/src/module-api.js

@@ -0,0 +1,366 @@
+// src/module-api.js — THE PUBLISHED, SEMVER'D DOORWAY (ADR 0083 / design 01§3).
+//
+// This is the ONLY core file a module may `require`. It re-exports the kernel
+// capabilities a module legitimately needs; everything else in the core is
+// off-limits to modules. The one-way rule (enforced by the fitness checks in
+// BV1.R40 once modules exist):
+//
+//     module  ──require──▶  src/module-api.js  ──▶  kernel
+//     core    ──✗──────────────────────────────▶  module   (forbidden)
+//     module  ──✗──────────────────────────────▶  module   (forbidden; use a seam)
+//
+// Adding to this surface is a MINOR semver bump (safe — existing modules keep
+// working). Changing or removing an export is a MAJOR bump (breaking). Each
+// module declares the `coreVersion` it supports; `bongos upgrade` (BV1.R50)
+// pre-checks every enabled module against CORE_VERSION below.
+//
+// Introduced by the doorway task (BV1.R37 / task 1406). The seam registry is in
+// src/module-seams.js (hardened in BV1.R39 / task 1408); the loader that mounts
+// modules behind kernel-composed auth is BV1.R41 / task 1410.
+
+const auth = require('./bongos/auth');
+const { pool, instanceDbName } = require('./bongos/pool');
+const branding = require('./branding');
+const instanceConfig = require('./instance-config');
+const seams = require('./module-seams');
+const { buildInfo } = require('./build-info');
+const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePagination, pageMeta, PAGINATION } = require('./bongos/routes/_helpers');
+
+// ---------------------------------------------------------------------------
+// CORE_VERSION — the version of THIS published surface (semver).
+// Bump MINOR when adding an export; MAJOR when changing/removing one.
+// 1.0.0 — initial doorway: auth gates, pool accessor, config/branding, seams.
+// 1.1.0 — contribution seam: contribute/contributions/collectContributions/
+//         listContributionPoints (BV1.R42 / task 1411) — additive, so MINOR.
+// 1.2.0 — capabilities the first extracted module (dev-box, BV1.R43 / task 1412)
+//         needs from the kernel: auth.allowBoxScope, db.getBuilderById /
+//         setBuilderBoxBlocked, buildInfo, route _helpers (validateOrRespond /
+//         LIMITS) — all additive, so MINOR.
+// 1.3.0 — capabilities the art-pipeline module (BV1.R48 / task 1417) needs:
+//         db.getBuilderGeminiKeyRow / setBuilderGeminiKey / clearBuilderGeminiKey
+//         — all additive, so MINOR.
+// 1.4.0 — generic kernel capabilities the discord module (BV1.R47 / task 1416)
+//         needs: db.insertAuditLog / createTask, inbox.captureIdea, the
+//         LIVE_RANK_LADDER rank ladder, and task-classifier VOTABLE_TASK_STATUSES.
+//         All generic (no module is named) + additive, so MINOR. The discord-
+//         SPECIFIC helpers (bot-token loader, snowflake validator, webhook poster)
+//         are deliberately NOT here — a module vendors its own domain code; the
+//         kernel doorway stays module-agnostic (the "core carries no module code"
+//         fitness check forbids naming a module key in this file).
+// 1.5.0 — BV1.R68 / ADR 0091 (kernel-bounding): adds `withTx` — the BEGIN/COMMIT
+//         transaction primitive a carved CORE domain needs for a multi-statement
+//         write (memory, R72, runs transactional stores). Additive → MINOR. The
+//         same change RELOCATES the dev-box domain query `setBuilderBoxBlocked`
+//         out to modules/dev-box/db.js and drops its doorway re-export. A strict
+//         reading calls removing an export MAJOR, but the sole consumer (the
+//         dev-box module) moves in lockstep and no enabled module at its pinned
+//         coreVersion loses a capability it uses — so the strangler treats an
+//         in-repo lockstep relocation as MINOR (a real MAJOR bump would
+//         gratuitously break every `^1.x` module at the loader's coreVersion gate).
+//         ADR 0091 §3 classifies the rest of this surface (kernel vs leak) below.
+// 1.6.0 — BV1.R73 / ADR 0091 §1+§4 (grading carve): adds the two KERNEL trust
+//         classifiers `routeRankCheck` + `permissionPathCheck` (the deterministic
+//         route→rank + protected-path matchers — KERNEL_FILES per R70) so the
+//         grading module's deterministic pre-passes reach them through the doorway
+//         instead of a deep core require; and `llmCache` (the shared LLM-cost
+//         cache — a DOMAIN leak, not kernel; see the leak bucket below). All
+//         additive → MINOR. The grade capability itself is NOT a doorway export —
+//         it is a kernel PORT the grading module registers (`grade`) and the
+//         lifecycle resolves (ADR 0091 §4).
+// 1.7.0 — BV1.R77 / ADR 0093 (economy carve): adds `llmPricing` (the shared
+//         token->USD pricing lib — a DOMAIN leak like `llmCache`, consumed by BOTH
+//         the carved economy module's reward/cost paths AND core cost scripts
+//         ship.js/session-cost.js, so it can't be economy-owned). Additive ->
+//         MINOR. The reward capability is a kernel PORT the economy module
+//         registers (`reward`), not a doorway export.
+// 1.8.0 — BV1.R78 / ADR 0093 §5 (ideas carve): adds `parseId` — the route-param
+//         validator from routes/_helpers.js, alongside `validateOrRespond`/`LIMITS`
+//         (KERNEL shared route helpers, ADR 0091 §1) so the carved ideas module's
+//         routes don't vendor their own. Additive. The same change RETIRES the
+//         `captureIdea` doorway leak: it relocates to the ideas module behind the
+//         `ideas.capture` kernel PORT (the home ADR 0091 §3 promised), with the
+//         sole consumer (discord #ideas inbound) moving to resolve the port in
+//         lockstep — so, like `setBuilderBoxBlocked` at 1.5.0, the export removal
+//         is treated as MINOR (no enabled module at its pinned coreVersion loses a
+//         capability it uses; a real MAJOR bump would gratuitously break every
+//         `^1.x` module at the loader's coreVersion gate).
+// 1.9.0 — BV1.R81 / ADR 0093 §1 (onboarding carve): adds `enabledDisciplines` —
+//         the instance's offered-disciplines resolver (src/modules.js: core
+//         engineer/ideator + each enabled module's disciplines). The carved
+//         onboarding module's newcomer-restock backstop intersects the chore
+//         disciplines with what THIS instance offers, so it needs the registry's
+//         answer without reaching into src/modules.js directly. Generic (names no
+//         module) + additive, so MINOR. The onboarding capability itself is NOT a
+//         doorway export — it is a kernel PORT the onboarding module registers
+//         (`onboarding`) and the lifecycle/profile readers resolve (ADR 0093 §1).
+// 1.10.0 — BV1.R82 / ADR 0093 §1 (sessions/BFG carve): adds `builderRollingAvgGrade`
+//         — the per-builder rolling grade-pass read the BFG's cross-builder
+//         `gatherInteractionSignals` needs to score interaction quality. It is a
+//         grade-TREND read (not kernel; consumed by the carved sessions module's
+//         BFG AND still by core routes/me.js's profile reader — the discord-twin
+//         pattern), so it sits in the DOMAIN-leak bucket like `llmPricing`/
+//         `getBuilderGeminiKeyRow`, relocating behind a port if/when the grade-
+//         trend reads are carved. Generic (names no module) + additive, so MINOR.
+//         The sessions capability itself is NOT a doorway export and NOT a port —
+//         sessions registers no provider (like memory); core never calls back in.
+// 1.11.0 — BV1.R83 / ADR 0093 §1 (autonomy/MAS carve): adds `tallyPeerVotes` —
+//         the peer-vote→karma weekly fold-in transaction the carved autonomy
+//         module's in-process routine timer (modules/autonomy/pollers/routine-
+//         timers.js) fires. It's the SAME transaction the lifecycle route
+//         POST /tasks/peer-votes/tally runs (the route + timer must share ONE
+//         path, never diverge), so it can't be autonomy-owned — it writes
+//         karma_log/peer_votes/tasks, all lifecycle/core-owned. A LIFECYCLE leak
+//         like `createTask`/`VOTABLE_TASK_STATUSES`: no clean home until the
+//         lifecycle domain is carved (R86), when it resolves behind a `lifecycle.*`
+//         kernel port. Until then the doorway re-export IS the (explicit, marked)
+//         seam. Generic (names no module) + additive, so MINOR. The autonomy
+//         capability itself is NOT a doorway export — the timer is a poller the
+//         loader starts, the precheck a module route, and the gate a CLI.
+// 1.12.0 — BV1.R86 / ADR 0093 §1,§3 (lifecycle carve — the LAST core-domain
+//         carve): the build state machine (tasks·claims·versions·done-when·ship
+//         orchestration) became modules/lifecycle/, so two net changes to this
+//         surface:
+//         (a) ADDS the KERNEL helpers the moved lifecycle libs need through the
+//             doorway instead of a deep core require: `repoInfo` (src/bongos/repo-
+//             info.js — the git-remote/slug resolver github-push.js + conflict-
+//             resolve.js read), `moduleScopeMap` (src/bongos/module-scope-map.js —
+//             the goal scope-wall roster routes/tasks.js + routes/goals.js read for
+//             module-key validation), `userAgent` (src/branding.js — the
+//             branding-derived HTTP UA github-push.js stamps GitHub requests with),
+//             `pathMatch` (src/bongos/path-match.js — the pure touches[]-overlap
+//             matcher claim/optimizer use; already grandfathered kernel-adjacent
+//             infra), and two more shared route helpers off _helpers.js
+//             (`asyncHandler` + `corsPublicGet`, alongside the existing
+//             validateOrRespond/LIMITS/parseId) the carved lifecycle routes
+//             (versions/done-when/analytics) reuse. All KERNEL config/identity/
+//             infra/route-helpers (ADR 0091 §1); additive → MINOR.
+//         (b) RETIRES the three LIFECYCLE doorway leaks `createTask`,
+//             `VOTABLE_TASK_STATUSES`, and `tallyPeerVotes` — they now resolve
+//             behind the `lifecycle` kernel PORT the module registers (ADR 0093 §3,
+//             "each carve deletes its leak"). The sole consumers (modules/ideas →
+//             via onboarding/discord, modules/discord, modules/autonomy, and core
+//             cascade-dispatch.js) resolve that port in lockstep, so — like
+//             `setBuilderBoxBlocked` at 1.5.0 / `captureIdea` at 1.8.0 — the export
+//             removal is treated as MINOR (no enabled module at its pinned
+//             coreVersion loses a capability it uses; a real MAJOR bump would
+//             gratuitously break every `^1.x` module at the loader's coreVersion
+//             gate). The lifecycle capability itself is NOT a doorway export — it is
+//             a kernel PORT (`lifecycle`) the module registers and core + the other
+//             modules resolve.
+// 1.13.0 — BV1.R60 / ADR 0086 §3 (goal-scoped bounded task authoring): adds
+//         `goalScopeCheck` (src/bongos/goal-scope-check.js) — the PURE scope wall the
+//         carved lifecycle module's POST /goals/:id/tasks create gate calls to
+//         decide "may this member author this task here?". It is KERNEL (the trust
+//         boundary for the create-time gate; it only COMPOSES the existing kernel
+//         matchers moduleScopeMap + pathMatch + permissionPathCheck, holding no
+//         domain logic), exposed so the module reaches it through the doorway
+//         instead of a deep core require. Generic (names no module) + additive, so
+//         MINOR. PERMANENT — same family as routeRankCheck/permissionPathCheck.
+// 1.15.0 — task 1971 (single-host hall): the published ./serve-internal surface's
+//         host router (isBuildersHost) now also treats the configured
+//         branding().domains.buildersOrigin host as the hall host, so an instance with
+//         no dedicated builders.<apex> subdomain serves its hall on its own host.
+//         Backward-compatible new capability of an exported surface → MINOR. Also
+//         carries task 1970 (the firstAdmin web-flow admission fix, src/bongos/auth.js).
+//         First stock version to supersede the emersonian-circles 1.14.1 fork (the
+//         task 1973 de-fork).
+// 1.16.0 — task 1690 / ADR 0100 §2 + ADR 0103 §4: the first core release consumed via the REAL
+//         `bongos upgrade` channel (previously the module-compat pre-check stub). Turns it into a
+//         real bump-pin → npm install → migrate → materialize .claude → restart → verify path, plus
+//         the per-instance core_upgrades ledger (core_189). Builds on the 1.15.0 line above; no
+//         doorway export removed or changed → MINOR.
+// 1.17.0 — R14 (#2001 / ADR 0119, criterion api-pagination): adds the shared
+//         pagination helpers `parsePagination` / `pageMeta` / `PAGINATION` off
+//         _helpers.js so a MODULE list route adopts the one paging contract
+//         (limit/offset clamp + the page-meta block) instead of hand-rolling it —
+//         the same reason validateOrRespond/LIMITS are on the doorway. Additive
+//         (new exports, no export removed or changed) → MINOR; every `^1.x`
+//         module keeps working, and a module using them is satisfied by 1.17.0.
+// ---------------------------------------------------------------------------
+const CORE_VERSION = '1.17.0'; // see the changelog above — R14 adds the shared pagination helpers to the doorway (#2001)
+
+// A namespaced logger so a module's log lines are attributable + consistent.
+// Usage: const log = api.logger('dev-box'); log.info('mounted');
+function logger(moduleKey) {
+  const tag = `[${moduleKey || 'module'}]`;
+  return {
+    info: (...a) => console.log(tag, ...a),
+    warn: (...a) => console.warn(tag, ...a),
+    error: (...a) => console.error(tag, ...a),
+  };
+}
+
+module.exports = {
+  CORE_VERSION,
+
+  // --- auth & rank (ADR 0016) — the gates the loader composes around a module's
+  //     routes; a module declares the rank it needs and never wires auth itself.
+  requireBuilder: auth.requireBuilder,
+  requireRank: auth.requireRank,
+  rankMeetsThreshold: auth.rankMeetsThreshold,
+  requireBfgPrincipal: auth.requireBfgPrincipal,
+  // allowBoxScope — opt a route in to box-scoped (dev-box bootstrap) session
+  //     tokens. A module's own bootstrap routes flag themselves; everything else
+  //     stays closed to box tokens (the ADR 0016 trust boundary).
+  allowBoxScope: auth.allowBoxScope,
+
+  // --- data — the shared Postgres pool. A module owns its namespaced tables
+  //     (<key>_*) via its own migrations (BV1.R46); it reaches them through this.
+  pool,
+  getPool: () => pool,
+  instanceDbName,
+  // withTx(fn, {pool}) — run fn(client) inside BEGIN/COMMIT (ROLLBACK + rethrow
+  //     on error, always release). The KERNEL transaction primitive a carved
+  //     core domain needs for a multi-statement write (BV1.R68 / ADR 0091 §3;
+  //     the memory carve, R72, runs transactional stores). Resolves from the
+  //     bounded src/bongos/db-kernel.js slice (carved in R69), not the monolith.
+  withTx: (...a) => require('./bongos/db-kernel').withTx(...a),
+
+  // === KERNEL db helpers — PERMANENT doorway surface (ADR 0091 §1/§3) ========
+  //     Genuinely-kernel reads/writes: builder IDENTITY (getBuilderById), the
+  //     AUDIT log (insertAuditLog), and the RANK ladder (LIVE_RANK_LADDER).
+  //     These belong on the doorway and stay. R69 carved them out of the 6k-LOC
+  //     db.js into the bounded src/bongos/db-kernel.js, which this surface resolves
+  //     through — so loading a kernel accessor no longer drags in the monolith.
+  getBuilderById: (...a) => require('./bongos/db-kernel').getBuilderById(...a),
+  insertAuditLog: (...a) => require('./bongos/db-kernel').insertAuditLog(...a),
+  get LIVE_RANK_LADDER() { return require('./bongos/db-kernel').LIVE_RANK_LADDER; },
+  // --- per-builder secrets at rest (AES-256-GCM box) — a kernel trust
+  //     primitive; the full secretBox object is exposed so a module can call
+  //     isConfigured/encrypt/decrypt/provisionMasterKey without reaching core.
+  secretBox: require('./bongos/secret-box'),
+
+  // --- KERNEL trust classifiers (ADR 0091 §1, KERNEL_FILES) — the deterministic
+  //     route→rank + protected-path matchers. They are KERNEL (the trust
+  //     boundary, never "called" by a domain), exposed so a module that runs the
+  //     same deterministic pre-passes (the grading panel, BV1.R73) reaches them
+  //     through the doorway instead of a deep core require. PERMANENT.
+  routeRankCheck: require('./bongos/route-rank-check'),
+  permissionPathCheck: require('./bongos/permission-path-check'),
+  // --- KERNEL repo + scope-map helpers (ADR 0091 §1, KERNEL_FILES) — exposed for
+  //     the carved lifecycle module (BV1.R86): repoInfo (the git-remote/slug
+  //     resolver github-push.js + conflict-resolve.js read) and moduleScopeMap
+  //     (the goal scope-wall roster routes/tasks.js + routes/goals.js read for
+  //     module-key validation). Both are KERNEL files (the scope-map IS the trust
+  //     wall, repo-info is the publish-target identity); a module reaches them
+  //     through the doorway instead of a deep core require. PERMANENT.
+  repoInfo: require('./bongos/repo-info'),
+  moduleScopeMap: require('./bongos/module-scope-map'),
+  // pathMatch — the pure touches[]-overlap matcher (src/bongos/path-match.js; no
+  // domain logic — already a grandfathered kernel-adjacent infra util). The
+  // carved lifecycle module's claim/optimizer overlap checks reach it here
+  // instead of requiring the core file (BV1.R86).
+  pathMatch: require('./bongos/path-match'),
+  // goalScopeCheck — the pure scope wall for goal-authored tasks (src/bongos/goal-
+  // scope-check.js, BV1.R59 / ADR 0086 §3). The lifecycle module's POST /goals/:id/
+  // tasks create gate (BV1.R60) calls check(goalScopeModules, touches, builderRank)
+  // to decide, ordered + fail-closed, whether a goal member may author a task here.
+  // KERNEL (the trust boundary for the create-time gate): it only COMPOSES the
+  // moduleScopeMap + pathMatch + permissionPathCheck matchers above — never a
+  // second protected list — so a module reaches it via the doorway, not a deep
+  // core require (which the module-boundary fitness check would red). PERMANENT.
+  goalScopeCheck: require('./bongos/goal-scope-check'),
+
+  // === DOMAIN capabilities still on the doorway — SCHEDULED TO RELOCATE ======
+  //     NOT kernel: these leak a domain's queries through the doorway (ADR 0091
+  //     §3, the "domain-leak-pending-carve" bucket). Each is kept ONLY until the
+  //     owning domain is carved — deleting one early would break its in-repo
+  //     consumer. A NEW module must NOT depend on these.
+  //   • Gemini-key storage → RELOCATED to modules/art-pipeline/db.js (ADR 0102):
+  //     the art module owns the credential store + registers the
+  //     'art.getBuilderGeminiKeyRow' port; the doorway no longer imports the core db.
+  //   • builderRollingAvgGrade → RELOCATED to modules/grading/db.js (ADR 0102): a
+  //     grade-TREND read behind the 'grade.builderRollingAvgGrade' port; core me.js
+  //     + the sessions BFG resolve it, so the doorway no longer imports the core db.
+  //   • createTask, VOTABLE_TASK_STATUSES, tallyPeerVotes — RETIRED at BV1.R86
+  //     (ADR 0093 §3). The lifecycle domain is now a module (modules/lifecycle/),
+  //     so all three live behind the `lifecycle` kernel PORT it registers, not on
+  //     the doorway. The sole consumers resolve that port: createTask via the
+  //     onboarding/discord module db slices (newcomer-restock + discord-bugs),
+  //     VOTABLE_TASK_STATUSES via discord-reaction, tallyPeerVotes via the autonomy
+  //     routine-timers poller, and classifyTaskKind via core cascade-dispatch.js.
+  //     This is the last leak deletion ADR 0091 §3 promised — the doorway no longer
+  //     re-exports any lifecycle domain query.
+  //   • captureIdea — RETIRED at BV1.R78 (ADR 0093 §5). The ideas domain is now a
+  //     module (modules/ideas/), so captureIdea lives behind the `ideas.capture`
+  //     kernel PORT it registers, not on the doorway. The sole consumer (discord
+  //     #ideas inbound) resolves that port. This is the leak deletion §3 promised.
+  //   • llmCache (BV1.R73) → the shared LLM-cost cache (cache key/TTL/savings
+  //     ledger over its own table). NOT kernel (not in the ADR 0091 §1 roster);
+  //     consumed by BOTH the carved grading module (grader.runSubagent wraps its
+  //     spawns in withCache) AND core (routes/llm-cache.js, the cost scripts), so
+  //     it can't be grading-owned. A tracked domain leak (the R70 ratchet flags
+  //     module-api → llm-cache as WARN); it relocates behind a port if/when an
+  //     llm-infra domain is carved (tranche 2).
+  llmCache: require('./bongos/llm-cache'),
+  //   • llmPricing (BV1.R77) → the shared token->USD pricing lib (the locked
+  //     PRICES table + priceModelUsage/componentsFromModelUsage). NOT kernel;
+  //     consumed by BOTH the carved economy module (reward/cost paths) AND core
+  //     cost scripts (ship.js, session-cost.js), so it can't be economy-owned —
+  //     a DOMAIN leak like llmCache. Relocates behind a port if/when an llm-infra
+  //     domain is carved (tranche 2).
+  llmPricing: require('./bongos/llm-pricing'),
+
+  // --- host context — config / branding / identity (a module reads, never
+  //     hardcodes, instance strings).
+  branding: branding.branding,
+  clientBranding: branding.clientBranding,
+  // userAgent — the instance's HTTP User-Agent string (branding-derived). The
+  // carved lifecycle module's github-push.js stamps every GitHub API request with
+  // it instead of reaching into src/branding.js directly (BV1.R86).
+  userAgent: branding.userAgent,
+  resolveEnv: instanceConfig.resolveEnv,
+  readConfigFileSync: instanceConfig.readConfigFileSync,
+  configHome: instanceConfig.configHome,
+  configPath: instanceConfig.configPath,
+  // --- module-selection facade (src/modules.js) — the instance's offered
+  //     disciplines (core engineer/ideator + each enabled module's). A module
+  //     that gates work by what THIS instance actually offers (onboarding's
+  //     newcomer-chore backstop) reads it here instead of requiring src/modules.js
+  //     directly. Resolved lazily so requiring the doorway never forces a config
+  //     read at module-load (BV1.R81 / ADR 0093 §1).
+  enabledDisciplines: (...a) => require('./modules').enabledDisciplines(...a),
+
+  // --- the seam registry — how modules cooperate without importing each other.
+  //     Three primitives: PORTS (one required provider), EVENTS (many optional
+  //     reactions), CONTRIBUTIONS (many accumulating extension points — how a
+  //     module adds its slice to a core surface, e.g. 'profile.fields'). See
+  //     src/module-seams.js.
+  registerProvider: seams.registerProvider,
+  hasProvider: seams.hasProvider,
+  resolve: seams.resolve,
+  resolveOptional: seams.resolveOptional,
+  listPorts: seams.listPorts,
+  verifyPortsSatisfied: seams.verifyPortsSatisfied,
+  on: seams.on,
+  emit: seams.emit,
+  emitAsync: seams.emitAsync,
+  listEvents: seams.listEvents,
+  contribute: seams.contribute,
+  contributions: seams.contributions,
+  collectContributions: seams.collectContributions,
+  listContributionPoints: seams.listContributionPoints,
+  seamSnapshot: seams.snapshot,
+
+  // --- build metadata + shared route-validation helpers — a module's routes
+  //     reuse the kernel's request validators (validateOrRespond/LIMITS/parseId),
+  //     the async-route error wrapper (asyncHandler), the public-GET CORS+cache
+  //     wrapper (corsPublicGet), and the build stamp instead of vendoring their
+  //     own. asyncHandler + corsPublicGet added at BV1.R86 for the carved
+  //     lifecycle routes (versions/done-when/analytics).
+  buildInfo,
+  validateOrRespond,
+  LIMITS,
+  parseId,
+  asyncHandler,
+  corsPublicGet,
+  // R14 (#2001 / ADR 0119): the shared pagination contract, so a MODULE list
+  // route pages identically to core (parsePagination clamps ?limit=&offset=;
+  // pageMeta builds the { limit, offset, total? } block).
+  parsePagination,
+  pageMeta,
+  PAGINATION,
+
+  // --- logging
+  logger,
+};