@bongos/core 1.19.574 → 1.19.576

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.574",
-  "core_contract": "1.19.574",
-  "source_commit": "cb6c20fba8bc93877d7917986195294b3d7d2d42",
+  "core_version": "1.19.576",
+  "core_contract": "1.19.576",
+  "source_commit": "a97463936d818b3a6be556837447748b3a2abaa1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T02:14:28.259Z",
+  "built_at": "2026-09-07T14:24:36.180Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 450,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2043,
+    "functional_verbatim": 2044,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2517,
-  "tree_sha256": "9160b243d293a7be2f13cb02991462b82a800e4e9948486d898f30a7598a0141",
+  "file_count": 2518,
+  "tree_sha256": "9b56f557f5e1d8d63c314cb2990df89c75d7230c3f16bdd41416396d95e2b6bd",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2692,7 +2692,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "34f3a97a9b2396e37b6b8739a008aa3c79fffa0f7e02df8b8586b755d6cd0206"
+      "sha256": "8f122cc3f3ca35dcc6569b98bad34967f2a4bbf9ebcbc0e645ca2b1016245fbc"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7552,12 +7552,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "267cb45a286e4a22e781d2c5ff28f5c609683bc79b5d8c327d2b3606aa0795a2"
+      "sha256": "8a58247d11bee28e30582d0860bd54cac15c8f3cb30753111063711a9369c390"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "aca40a127da79a5a8217c05ab5c074072dc0840d4b2baf89159d68412cfd6a08"
+      "sha256": "e2f634e2e1deae3517a6b545c91a2b4818c51b04cb56daa4f1528b822cc1d14e"
     },
     {
       "path": "public-docs/index.html",
@@ -9257,7 +9257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "8b068b3a2cefb919013cdcc7cf35ec4a84859fe16d6e5cf7723d3434370bfcd5"
+      "sha256": "fb020c72dfb07b789b7e281ba766fe8f0f9c4fe67c359c8b5c9928c8e86b85da"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11157,7 +11157,7 @@
     {
       "path": "tests/logger.mjs",
       "mode": "0000644",
-      "sha256": "edf87a88bd7130e85844db291d5f1d7b6de561434501bdb064dfadf0e23befe1"
+      "sha256": "7450580274562f784122e5e9eefe458669fb9083adddb7268364de7139f94cb5"
     },
     {
       "path": "tests/main_audit.mjs",
@@ -11269,6 +11269,11 @@
       "mode": "0000644",
       "sha256": "39812c560bcd88e3b3a7938ed2447fbd4ab24b0f925e9662b375910bcbe7f1da"
     },
+    {
+      "path": "tests/module_api_lazy.mjs",
+      "mode": "0000644",
+      "sha256": "40c396fda3a618bf9fa2d2ae3d8d30b50e62c4210199d70b5e29cb82a046d037"
+    },
     {
       "path": "tests/module_catalog.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1597,5 +1597,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.572 with no explicit bump. run 34072921884. (task 1002620)
   1.19.574 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.573 with no explicit bump. run 34075598213. (task 1002620)
+  1.19.575 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.574 with no explicit bump. run 34076465465. (task 1002620)
+  1.19.576 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.575 with no explicit bump. run 34132732488. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.574",
+  "version": "1.19.576",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.574",
+      "version": "1.19.576",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.574",
+  "version": "1.19.576",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -9,32 +9,38 @@
 // (task 1406); seams in src/module-seams.js (BV1.R39 / task 1408); the loader that
 // mounts modules behind kernel-composed auth is BV1.R41 / task 1410.
 
-const auth = require('./bongos/auth');
 const util = require('node:util');
-// task 1003208: api.logger() returns a real pino child from here (see below).
-const { logger: coreLogger } = require('./bongos/logger');
-const { pool, instanceDbName } = require('./bongos/pool');
 const branding = require('./branding');
-const projectDoor = require('./bongos/project-door');
+
+// LAZY BY CONSTRUCTION (task 1003677). Every kernel capability below that costs
+// something to load — auth, the Postgres pool, the route helpers, project
+// settings, the logger — is reached through a getter that `require()`s it on
+// first READ, never at module load. Node's module cache makes the repeat cost a
+// map lookup, and this file already used the idiom for db-kernel and the LLM
+// helpers; this extends it to the rest.
+//
+// Why it matters beyond tidiness: `require('src/module-api')` used to open a
+// Postgres pool and load the whole auth stack as a side effect of being
+// imported. Modules are required by the CLI too — `bongos claim` reads
+// modules/lifecycle/ship-card, `bongos start` reads task-classifier, and each
+// needs `branding` and nothing else — so importing one dragged 22 server files
+// into every CLI subcommand's require-closure. That is what made the CLI
+// impossible to ship as a public, client-only npx package (goal 1000054), and
+// with it what kept a builder holding no private-registry credential from
+// claiming any task at all.
+//
+// The contract is unchanged: ADR 0083's doorway is still the one file a module
+// may import, and every export still resolves to exactly what it did before —
+// it just resolves when read instead of when loaded. Adding an export stays a
+// MINOR bump; a getter is not a breaking change to a consumer that reads it.
+//
+// Keep it this way. A plain `name: require('./bongos/x').y` entry in the object
+// below is EAGER — it evaluates while the literal is built — so a new export
+// that costs anything belongs behind `get name() { return require(...); }`.
 const instanceConfig = require('./instance-config');
 const staleTimer = require('./stale-timer');
-// Destructured, not namespaced, deliberately — the same form src/bongos/routes/
-// builders.js uses for stale-timer.js. knip attributes a named export to a
-// destructured binding but not to a property read off a required namespace, so the
-// namespace form reports every export here as dead and regresses the ratchet.
-const {
-  resolveRotDays,
-  SETTING_KEYS: PROJECT_SETTING_KEYS,
-  getSetting: getProjectSetting,
-  setSetting: setProjectSetting,
-  describeRotTimer,
-  parseDays: parseRotDays,
-  MIN_ROT_DAYS,
-  MAX_ROT_DAYS,
-} = require('./bongos/project-settings');
 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).
@@ -49,7 +55,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.574'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.576'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');
@@ -74,7 +80,7 @@ const CORE_VERSION = '1.19.574'; // CI auto-patch carrier (ADR 0161); changelog:
 // A secret INTERPOLATED into a message string is still not redactable here; that
 // is the scrubber's and the prevent hook's job, as logger.js's own header says.
 function logger(moduleKey) {
-  const child = coreLogger.child({ module: moduleKey || 'module' });
+  const child = require('./bongos/logger').logger.child({ module: moduleKey || 'module' });
   const emit = (level) => (...args) => {
     if (args.length === 0) return child[level]('');
     const bindings = {};
@@ -98,21 +104,21 @@ module.exports = {
 
   // --- 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,
+  get requireBuilder() { return require('./bongos/auth').requireBuilder; },
+  get requireRank() { return require('./bongos/auth').requireRank; },
   // requirePermission(...atoms) — the AUTHORITY-ATOM gate (ADR 0151), mounted
   //     AFTER requireBuilder exactly like requireRank. Async, AND-semantics,
   //     fail-closed; denies with `permission_forbidden` rather than
   //     `rank_forbidden`. The rank-role compat seed makes it admit exactly who
   //     the equivalent requireRank admitted, so a migrated module route is
   //     behaviour-identical (BV1.R105).
-  requirePermission: auth.requirePermission,
-  rankMeetsThreshold: auth.rankMeetsThreshold,
-  requireBfgPrincipal: auth.requireBfgPrincipal,
+  get requirePermission() { return require('./bongos/auth').requirePermission; },
+  get rankMeetsThreshold() { return require('./bongos/auth').rankMeetsThreshold; },
+  get requireBfgPrincipal() { return require('./bongos/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,
+  get allowBoxScope() { return require('./bongos/auth').allowBoxScope; },
   // resolveSession(req) — resolve the request to a live session row (or null)
   //     WITHOUT the 401-or-pass behaviour of requireBuilder. A module route that
   //     must make its own auth decision — e.g. a browser page that REDIRECTS to
@@ -121,13 +127,13 @@ module.exports = {
   //     Returns the same shape lookupSession does (builder_id, github_id,
   //     github_login, display_name, avatar_url, rank, source, status); rank is
   //     still never an authority a module should trust for cross-instance identity.
-  resolveSession: (...a) => auth.resolveSession(...a),
+  resolveSession: (...a) => require('./bongos/auth').resolveSession(...a),
 
   // --- 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,
+  get pool() { return require('./bongos/pool').pool; },
+  getPool: () => require('./bongos/pool').pool,
+  get instanceDbName() { return require('./bongos/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;
@@ -157,7 +163,7 @@ module.exports = {
   //     enumerator alternates between them for double the rate (task 1003339,
   //     ADR 0209). Vendoring a second copy in a module is the failure this
   //     export exists to prevent.
-  accountExistenceReadRateLimit: require('./bongos/middleware/rate-limit').accountExistenceReadRateLimit,
+  get accountExistenceReadRateLimit() { return require('./bongos/middleware/rate-limit').accountExistenceReadRateLimit; },
   // publicProjectFeedRateLimit — the per-IP ceiling (120 reads/60s) on the PUBLIC
   //     projects feed (task 1002327, ADR 0252 §5.3). Same reasoning as its
   //     neighbour, and the same shape — ONE middleware instance, never a factory,
@@ -168,20 +174,20 @@ module.exports = {
   //     much as ours. ADR 0252 made this a condition of auto-appear, not a
   //     follow-up — the straight-through path and its abuse guard ship together
   //     (ADR 0047).
-  publicProjectFeedRateLimit: require('./bongos/middleware/rate-limit').publicProjectFeedRateLimit,
+  get publicProjectFeedRateLimit() { return require('./bongos/middleware/rate-limit').publicProjectFeedRateLimit; },
 
   // --- 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'),
+  get secretBox() { return 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'),
+  get routeRankCheck() { return require('./bongos/route-rank-check'); },
+  get permissionPathCheck() { return 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
@@ -189,13 +195,13 @@ module.exports = {
   //     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'),
+  get repoInfo() { return require('./bongos/repo-info'); },
+  get moduleScopeMap() { return 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'),
+  get pathMatch() { return 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)
@@ -204,7 +210,7 @@ module.exports = {
   // 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'),
+  get goalScopeCheck() { return 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
@@ -237,14 +243,14 @@ module.exports = {
   //     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'),
+  get llmCache() { return 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'),
+  get llmPricing() { return require('./bongos/llm-pricing'); },
 
   // --- host context — config / branding / identity (a module reads, never
   //     hardcodes, instance strings).
@@ -256,7 +262,7 @@ module.exports = {
   //     open-enrolment flag and the fail-closed default live in this one
   //     reader, and the sign-in flows and the public access-request route
   //     must answer with the same door (SR-19).
-  joinabilityMode: auth.joinabilityMode,
+  get joinabilityMode() { return require('./bongos/auth').joinabilityMode; },
   // projectJoinDoor() — the project's COMPOSED join/apply door: 'open' | 'apply' |
   //     'invite_only' | 'locked' (BV1.R12, task 1002331; ADR 0182 D6, ADR 0247).
   //     `joinabilityMode` above answers one knob; this answers the whole door,
@@ -266,7 +272,7 @@ module.exports = {
   //     surface calls THIS; a module that read a single knob would re-open a door
   //     the other two had closed. Optional `{ publishable }` for a caller that
   //     holds a publish verdict — see src/bongos/project-door.js.
-  projectJoinDoor: (opts) => projectDoor.effectiveJoinDoor(opts),
+  projectJoinDoor: (opts) => require('./bongos/project-door').effectiveJoinDoor(opts),
   // 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).
@@ -296,21 +302,21 @@ module.exports = {
   //     is about work nobody picked up, and it only ever ASKS a human. The rot read
   //     deliberately skips tasks at 'active' so the two never report the same rot
   //     with two different numbers. See src/bongos/project-settings.js.
-  resolveRotDays,
+  get resolveRotDays() { return require('./bongos/project-settings').resolveRotDays; },
   projectSettings: {
-    KEYS: PROJECT_SETTING_KEYS,
-    get: getProjectSetting,
-    set: setProjectSetting,
-    describeRotTimer,
+    get KEYS() { return require('./bongos/project-settings').SETTING_KEYS; },
+    get get() { return require('./bongos/project-settings').getSetting; },
+    get set() { return require('./bongos/project-settings').setSetting; },
+    get describeRotTimer() { return require('./bongos/project-settings').describeRotTimer; },
     // The RANGE CHECK, shared rather than re-typed. The settings page validates a
     // submitted timer with the very parser the resolver reads it back through, so the
     // form and the reader can never disagree about what 1..365 means (task 1003280).
-    parseDays: parseRotDays,
+    get parseDays() { return require('./bongos/project-settings').parseDays; },
     // The bounds themselves, so a surface that must SHOW them (the settings page's rot
     // row) reads the single source instead of re-typing 1/365 — the very drift the
     // page's own anti-drift rule forbids, caught one layer up on task 1003280's grade.
-    MIN_ROT_DAYS,
-    MAX_ROT_DAYS,
+    get MIN_ROT_DAYS() { return require('./bongos/project-settings').MIN_ROT_DAYS; },
+    get MAX_ROT_DAYS() { return require('./bongos/project-settings').MAX_ROT_DAYS; },
   },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,
@@ -351,18 +357,55 @@ module.exports = {
   //     own. asyncHandler + corsPublicGet added at BV1.R86 for the carved
   //     lifecycle routes (versions/done-when/analytics).
   buildInfo,
-  validateOrRespond,
-  LIMITS,
-  parseId,
-  asyncHandler,
-  corsPublicGet,
+  get validateOrRespond() { return require('./bongos/routes/_helpers').validateOrRespond; },
+  get LIMITS() { return require('./bongos/routes/_helpers').LIMITS; },
+  get parseId() { return require('./bongos/routes/_helpers').parseId; },
+  get asyncHandler() { return require('./bongos/routes/_helpers').asyncHandler; },
+  get corsPublicGet() { return require('./bongos/routes/_helpers').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,
+  get parsePagination() { return require('./bongos/routes/_helpers').parsePagination; },
+  get pageMeta() { return require('./bongos/routes/_helpers').pageMeta; },
+  get PAGINATION() { return require('./bongos/routes/_helpers').PAGINATION; },
 
   // --- logging
   logger,
 };
+
+// Keep every lazy export ASSIGNABLE (task 1003677). The getters above turned what
+// used to be plain data properties into accessors, and a getter-only property
+// THROWS on assignment — `TypeError: Cannot set property requireBuilder of #<Object>
+// which has only a getter`. Callers do assign: a test stubs `api.requireBuilder` to
+// bypass auth, and the module loader composes gates the same way. That is a real
+// part of this surface's contract, not an accident, so laziness must not cost it.
+//
+// Each accessor gains a setter that REPLACES itself with the assigned value — the
+// property becomes an ordinary writable data property from then on, exactly as it
+// was before, and the lazy require is simply never reached. Applied in a loop so a
+// future lazy export inherits it without anyone remembering to.
+function makeLazyPropsWritable(target) {
+  for (const key of Object.keys(target)) {
+    const d = Object.getOwnPropertyDescriptor(target, key);
+    if (!d) continue;
+    if (d.get && !d.set) {
+      Object.defineProperty(target, key, {
+        get: d.get,
+        set(value) {
+          Object.defineProperty(this, key, { value, writable: true, configurable: true, enumerable: d.enumerable });
+        },
+        configurable: true,
+        enumerable: d.enumerable,
+      });
+      continue;
+    }
+    // One level down, and ONLY through a data descriptor — reading `d.value` is
+    // free, whereas reading the property would fire a lazy getter and defeat the
+    // point. `projectSettings` is a nested namespace whose members are lazy too,
+    // and a settings test assigns `api.projectSettings.set`.
+    if (!d.get && d.value && typeof d.value === 'object' && Object.getPrototypeOf(d.value) === Object.prototype) {
+      makeLazyPropsWritable(d.value);
+    }
+  }
+}
+makeLazyPropsWritable(module.exports);

package/tests/logger.mjs

@@ -11,8 +11,20 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// pino resolves as a BARE specifier, never as ROOT/node_modules/pino (task 1003616).
+// An absolute path demands the directory exist at exactly that spot, so a fresh
+// per-claim worktree with no install of its own reported a phantom FAIL; the bare
+// form walks parent directories and finds the checkout the worktree lives under.
+// Where nothing is installed at all — a package-only consumer — say so and skip,
+// the same contract tests/hooks_drain.mjs uses for its own `pg` gate.
+try { require.resolve('pino'); } catch {
+  console.log('logger: SKIP — pino is not installed in or above this checkout (run npm install).');
+  process.exit(0);
+}
+
 const log = require(path.join(ROOT, 'src', 'bongos', 'logger.js'));
-const pino = require(path.join(ROOT, 'node_modules', 'pino'));
+const pino = require('pino');
 const { Writable } = require('node:stream');
 
 // pino writes through sonic-boom directly to the fd, so we can't intercept the

package/tests/module_api_lazy.mjs

@@ -0,0 +1,111 @@
+// tests/module_api_lazy.mjs — requiring the module doorway must not boot the
+// server (task 1003677).
+//
+// src/module-api.js is the ONE file a module may import (ADR 0083). It used to
+// require auth, the Postgres pool, the route helpers and project settings at
+// module scope — so merely IMPORTING it opened a pool and loaded the whole auth
+// stack as a side effect. Modules are imported by the CLI too (`bongos claim`
+// reads modules/lifecycle/ship-card, `bongos start` reads task-classifier, each
+// wanting `branding` and nothing else), so that side effect dragged 22 server
+// files into every CLI subcommand — which is what made the CLI impossible to
+// publish as a client-only npx package (goal 1000054) and left a builder with no
+// private-registry credential unable to claim anything.
+//
+// The invariant: a kernel capability loads when it is READ, not when the doorway
+// is imported. Measured against the real require.cache, because a static scan
+// cannot tell an eager `require()` from one inside a getter — the text is
+// identical, only the timing differs. Each case runs in its OWN child process:
+// require.cache is per-process, and one eager import anywhere would poison the
+// rest of the run.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HEAVY = /^src\/bongos\/(pool|auth|db|db-kernel|auth-[^/]*|routes\/)/;
+
+// Load `spec` in a fresh process and report which src/bongos files ended up in
+// the require cache. `read` optionally destructures a property first, proving the
+// getter resolves without dragging its neighbours in.
+function loadedAfter(spec, read = null) {
+  const script = `
+    const path = require('node:path');
+    const ROOT = ${JSON.stringify(ROOT)};
+    const m = require(path.join(ROOT, ${JSON.stringify(spec)}));
+    ${read ? `void m[${JSON.stringify(read)}];` : ''}
+    const files = Object.keys(require.cache)
+      .map((f) => path.relative(ROOT, f))
+      .filter((f) => f.startsWith('src/bongos/'));
+    process.stdout.write(JSON.stringify(files));
+  `;
+  // spawnSync, not execFileSync: several subcommands print usage and exit
+  // non-zero when required with no arguments. That is the script behaving
+  // correctly, and the measurement (already written to stdout) is still valid —
+  // only a MISSING/unparseable payload is a real failure.
+  const r = spawnSync(process.execPath, ['-e', script], { encoding: 'utf8' });
+  const out = (r.stdout || '').trim();
+  if (!out) throw new Error(`probe produced nothing for ${spec} (exit ${r.status}): ${(r.stderr || '').slice(0, 200)}`);
+  return JSON.parse(out);
+}
+
+test('importing the doorway loads no server: no pool, no auth, no routes', () => {
+  const files = loadedAfter('src/module-api.js');
+  const heavy = files.filter((f) => HEAVY.test(f));
+  assert.deepEqual(heavy, [],
+    `require('src/module-api') pulled in ${heavy.join(', ')}. A new export whose value is a bare `
+    + "`require('./bongos/x')` is EAGER — the object literal evaluates it at load. Put it behind "
+    + '`get name() { return require(...); }` instead.');
+});
+
+test('reading `branding` — what a CLI-imported module actually wants — stays cheap', () => {
+  const files = loadedAfter('src/module-api.js', 'branding');
+  assert.deepEqual(files.filter((f) => HEAVY.test(f)), [],
+    'reading one light export must not resolve the heavy ones');
+});
+
+test('reading `pool` DOES load it — laziness must not mean broken', () => {
+  const files = loadedAfter('src/module-api.js', 'pool');
+  assert.ok(files.some((f) => f === 'src/bongos/pool.js'),
+    'the pool getter must still resolve the real pool when read');
+});
+
+// The getters replaced plain data properties, and a getter-only property THROWS on
+// assignment. Callers do assign — a test stubs api.requireBuilder to bypass auth,
+// and two suites (catalog_only_client, government_abuse_matrix) failed exactly that
+// way on the first cut. Laziness must not cost assignability.
+test('a lazy export is still assignable, and the stub sticks', async () => {
+  const { createRequire } = await import('node:module');
+  const require_ = createRequire(import.meta.url);
+  const api = require_(path.join(ROOT, 'src/module-api.js'));
+  const before = api.requireBuilder;
+  assert.equal(typeof before, 'function', 'the getter resolves the real thing first');
+  const stub = function stubbed() {};
+  api.requireBuilder = stub;
+  assert.equal(api.requireBuilder, stub, 'assignment must replace the accessor, not throw or no-op');
+  api.requireBuilder = before;
+
+  // And one level down: projectSettings is a nested namespace whose members are
+  // lazy too, and tests/project_settings_page.mjs assigns `.set`. The first fix
+  // walked only the top level and that suite failed nine ways.
+  const prevSet = api.projectSettings.set;
+  const stubSet = function stubbedSet() {};
+  api.projectSettings.set = stubSet;
+  assert.equal(api.projectSettings.set, stubSet, 'a nested lazy export must be assignable too');
+  api.projectSettings.set = prevSet;
+});
+
+test('the two lifecycle modules the CLI imports boot no server', () => {
+  for (const spec of ['modules/lifecycle/ship-card.js', 'modules/lifecycle/task-classifier.js']) {
+    const heavy = loadedAfter(spec).filter((f) => HEAVY.test(f));
+    assert.deepEqual(heavy, [], `${spec} booted ${heavy.join(', ')} — the CLI imports this`);
+  }
+});
+
+test('every CLI subcommand loads without the server', () => {
+  for (const cmd of ['start', 'claim', 'ship', 'task', 'status', 'login', 'setup', 'release', 'cost', 'recall']) {
+    const heavy = loadedAfter(`scripts/gds/${cmd}.js`).filter((f) => HEAVY.test(f));
+    assert.deepEqual(heavy, [], `bongos ${cmd} booted ${heavy.join(', ')}`);
+  }
+});