@bongos/core 1.17.0

package/src/module-seams.js

@@ -0,0 +1,291 @@
+// src/module-seams.js — the kernel seam registry (the switchboard).
+//
+// The module system's one-way rule (ADR 0083 / design 04§1) forbids a module
+// importing another module. But modules still need to cooperate: the lifecycle
+// (which ships a task) needs a reward figure the economy module computes; the
+// lifecycle emits `task.shipped` and the discord module may want to react. The
+// resolution is a KERNEL-MEDIATED SEAM — the kernel is a switchboard so no
+// module ever holds a reference to another:
+//
+//   • PORTS (a required capability): a provider module registers a named
+//     provider; a consumer asks the kernel to resolve it and calls it. Exactly
+//     one provider per port (it is a required capability, not a broadcast).
+//     resolve() on an unregistered port THROWS (fail-clear) — a missing required
+//     capability is a configuration error, not a silent no-op.
+//
+//   • EVENTS (an optional reaction): a module emits a named event with a
+//     payload; zero-or-more modules that registered a listener react. emit()
+//     ISOLATES listener errors — one bad listener never breaks the emitter or
+//     the other listeners.
+//
+// This file is the minimal, correct implementation introduced with the doorway
+// (BV1.R37 / task 1406). The hardening pass (BV1.R39 / task 1408, M05) adds the
+// required-vs-optional port distinction wired to the loader, introspection, and
+// the full hermetic test matrix. It is re-exported through src/module-api.js so
+// a module reaches it only via the published doorway.
+
+// ---------------------------------------------------------------------------
+// Ports (required, single-provider capabilities)
+// ---------------------------------------------------------------------------
+
+const providers = new Map(); // portName -> provider value/function
+
+// Register a provider for a named port. Throws on a duplicate registration —
+// a port is a single, required capability; two providers is a wiring bug, not a
+// last-write-wins situation. (The loader catches this and fails the affected
+// module's mount, never the whole boot.)
+function registerProvider(portName, provider) {
+  if (typeof portName !== 'string' || !portName) {
+    throw new TypeError('registerProvider(portName, provider): portName must be a non-empty string');
+  }
+  if (provider == null) {
+    throw new TypeError(`registerProvider("${portName}"): provider must not be null/undefined`);
+  }
+  if (providers.has(portName)) {
+    throw new Error(`seam: port "${portName}" already has a provider (a port is single-provider)`);
+  }
+  providers.set(portName, provider);
+  return provider;
+}
+
+// True if a provider is registered for the port.
+function hasProvider(portName) {
+  return providers.has(portName);
+}
+
+// Resolve a port to its provider. Throws if none is registered — a required
+// capability that nobody provides is a fail-closed error, surfaced clearly.
+function resolve(portName) {
+  if (!providers.has(portName)) {
+    throw new Error(`seam: no provider registered for required port "${portName}"`);
+  }
+  return providers.get(portName);
+}
+
+// Optional resolution — returns the provider or `fallback` (default null) with
+// no throw. For consumers that can degrade when a capability is absent.
+function resolveOptional(portName, fallback = null) {
+  return providers.has(portName) ? providers.get(portName) : fallback;
+}
+
+// Names of all registered ports (introspection / drift scans).
+function listPorts() {
+  return Array.from(providers.keys()).sort();
+}
+
+// BOOT-TIME (manifest-level) verification, distinct from resolve()'s RUNTIME
+// throw: given the ENABLED modules' manifests, confirm every consumed port is
+// provided by some enabled module, and no port has two providers. The loader
+// (BV1.R41) runs this before mounting so a required capability with no provider
+// is caught at boot with a clear message — not as a surprise throw the first time
+// the seam is used. Pure (no registry mutation), so it is safe to run anytime.
+// manifests: [{ key, provides: [...], consumes: [...] }] → { ok, errors: [...] }.
+function verifyPortsSatisfied(manifests = []) {
+  const provided = new Map(); // port -> [providerKey,...]
+  for (const m of manifests) {
+    for (const p of m.provides || []) {
+      if (!provided.has(p)) provided.set(p, []);
+      provided.get(p).push(m.key);
+    }
+  }
+  const errors = [];
+  for (const m of manifests) {
+    for (const c of m.consumes || []) {
+      if (!provided.has(c)) {
+        errors.push(`module "${m.key}" consumes port "${c}" but no enabled module provides it`);
+      }
+    }
+  }
+  for (const [port, keys] of provided) {
+    if (keys.length > 1) errors.push(`port "${port}" is provided by more than one enabled module: ${keys.join(', ')} (a port is single-provider)`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Events (optional, many-listener reactions)
+// ---------------------------------------------------------------------------
+
+const listeners = new Map(); // eventName -> Set<fn>
+
+// Subscribe to an event. Returns an unsubscribe function.
+function on(eventName, handler) {
+  if (typeof eventName !== 'string' || !eventName) {
+    throw new TypeError('on(eventName, handler): eventName must be a non-empty string');
+  }
+  if (typeof handler !== 'function') {
+    throw new TypeError(`on("${eventName}"): handler must be a function`);
+  }
+  if (!listeners.has(eventName)) listeners.set(eventName, new Set());
+  listeners.get(eventName).add(handler);
+  return function off() {
+    const set = listeners.get(eventName);
+    if (set) set.delete(handler);
+  };
+}
+
+// Emit an event to all listeners. Listener errors are ISOLATED: a throwing
+// listener is logged and skipped; the emitter and the remaining listeners are
+// unaffected. Returns the number of listeners invoked.
+function emit(eventName, payload) {
+  const set = listeners.get(eventName);
+  if (!set || set.size === 0) return 0;
+  let invoked = 0;
+  for (const handler of set) {
+    invoked += 1; // count every listener invoked, throw or not
+    try {
+      handler(payload);
+    } catch (err) {
+      // Never let a reactor break the actor. Optional reactions are best-effort.
+      console.error(`[seam] listener for "${eventName}" threw:`, err && err.message ? err.message : err);
+    }
+  }
+  return invoked;
+}
+
+// Async emit — awaits async (or sync) listeners, isolating errors the same way
+// emit() does. For an emitter that wants to know all reactions have settled
+// (e.g. flush a notification before returning). Returns the count invoked.
+async function emitAsync(eventName, payload) {
+  const set = listeners.get(eventName);
+  if (!set || set.size === 0) return 0;
+  let invoked = 0;
+  for (const handler of set) {
+    invoked += 1;
+    try {
+      await handler(payload);
+    } catch (err) {
+      console.error(`[seam] async listener for "${eventName}" threw:`, err && err.message ? err.message : err);
+    }
+  }
+  return invoked;
+}
+
+// Names of all events with at least one listener (introspection).
+function listEvents() {
+  return Array.from(listeners.keys()).filter((k) => listeners.get(k).size > 0).sort();
+}
+
+// ---------------------------------------------------------------------------
+// Contributions (optional, many-contributor accumulating extension points)
+// ---------------------------------------------------------------------------
+//
+// The third seam primitive, distinct from both ports and events (BV1.R42 / task
+// 1411). A PORT is exactly one provider (a required capability); an EVENT is a
+// fire-and-forget reaction; a CONTRIBUTION accumulates — zero-or-more modules
+// each add a piece to a named extension point, and the kernel hands the whole
+// set back to a core consumer that renders them together. This is how a module
+// adds its own slice to a core surface without core hardcoding it: dev-box adds
+// box fields + a box settings panel, discord adds its link state, art adds its
+// key surface — each `contribute()`s; core merges. The strangler prerequisite
+// that lets those modules leave core (the surfaces in src/bongos/routes/me.js +
+// modules/hall-ui/public/settings.js stop being hardcoded). With no module enabled the
+// registry is empty and every consumer renders exactly what it does today.
+//
+// Canonical extension points (the names core consumes):
+//   • 'profile.fields'  — server-side: each contributor is `async (ctx) => ({…slice})`;
+//                         the slices merge into the GET /api/gds/me payload.
+//                         (The client settings-panel seam is its browser twin,
+//                          window.OTB.contributeSettingsPanel in dom-utils.js.)
+
+const contributors = new Map(); // point -> [contribution, ...] (registration order)
+
+// Register a contribution to a named extension point. Unlike a port, a point
+// accepts MANY contributions (no duplicate-registration throw). Returns the
+// contribution so a caller can keep a handle.
+function contribute(point, contribution) {
+  if (typeof point !== 'string' || !point) {
+    throw new TypeError('contribute(point, contribution): point must be a non-empty string');
+  }
+  if (contribution == null) {
+    throw new TypeError(`contribute("${point}"): contribution must not be null/undefined`);
+  }
+  if (!contributors.has(point)) contributors.set(point, []);
+  contributors.get(point).push(contribution);
+  return contribution;
+}
+
+// All contributions registered for a point, in registration order. Returns a
+// COPY (never the live array) and [] for an unknown point — a consumer can
+// always iterate without a guard.
+function contributions(point) {
+  return contributors.has(point) ? contributors.get(point).slice() : [];
+}
+
+// Collect every function-contribution to a point: invoke it with `ctx`, await
+// the result, and return the array of non-nullish results. For accumulating
+// server-side points like 'profile.fields' where each contributor is
+// `async (ctx) => ({…slice})`. Errors are ISOLATED the same way emit() isolates
+// a listener — one throwing contributor is logged and skipped, never breaking
+// the others or the caller. A non-function contribution is returned as-is.
+async function collectContributions(point, ctx) {
+  const out = [];
+  for (const c of contributions(point)) {
+    try {
+      const v = typeof c === 'function' ? await c(ctx) : c;
+      if (v != null) out.push(v);
+    } catch (err) {
+      console.error(`[seam] contribution to "${point}" threw:`, err && err.message ? err.message : err);
+    }
+  }
+  return out;
+}
+
+// Merge accumulating contribution slices into a base object, ADD-ONLY: a slice
+// may introduce new keys but never overwrite one already on `base` (core wins —
+// a module's contribution can't clobber a core field). Mutates + returns `base`,
+// and reports any collided keys so the caller can surface them — that signals a
+// move task took over a core key without first removing the core copy. Used by
+// GET /api/gds/me to fold 'profile.fields' slices into the profile payload.
+function mergeContributions(base, slices) {
+  const collisions = [];
+  for (const slice of slices || []) {
+    if (!slice || typeof slice !== 'object') continue;
+    for (const [k, v] of Object.entries(slice)) {
+      if (Object.prototype.hasOwnProperty.call(base, k)) { collisions.push(k); continue; }
+      base[k] = v;
+    }
+  }
+  return { base, collisions };
+}
+
+// Names of all extension points with at least one contribution (introspection).
+function listContributionPoints() {
+  return Array.from(contributors.keys()).filter((k) => contributors.get(k).length > 0).sort();
+}
+
+// A snapshot of the wired seams — for an observability tile / drift scan.
+function snapshot() {
+  return {
+    ports: listPorts(),
+    events: listEvents().map((e) => ({ event: e, listeners: listeners.get(e).size })),
+    contributions: listContributionPoints().map((p) => ({ point: p, contributors: contributors.get(p).length })),
+  };
+}
+
+// Test-only reset (kept tiny + explicit so hermetic tests start clean).
+function _reset() {
+  providers.clear();
+  listeners.clear();
+  contributors.clear();
+}
+
+module.exports = {
+  registerProvider,
+  hasProvider,
+  resolve,
+  resolveOptional,
+  listPorts,
+  verifyPortsSatisfied,
+  on,
+  emit,
+  emitAsync,
+  listEvents,
+  contribute,
+  contributions,
+  collectContributions,
+  mergeContributions,
+  listContributionPoints,
+  snapshot,
+  _reset,
+};

package/src/modules.js

@@ -0,0 +1,254 @@
+// src/modules.js — the feature-module selection layer (R54, task 1193, ADR 0062 §4).
+//
+// A config-flag layer that gates OPTIONAL features per instance. Branding
+// (src/branding.js) answers "what does this instance look like?"; this answers
+// "what does this instance DO?" — which optional features mount their routes,
+// hall/status UI sections, skills, disciplines, Colyseus rooms, and pollers.
+//
+// The cut: a small CORE is always on (the methodology — builders, tasks,
+// claims, credits, grading, memory, recall — everything a build platform needs
+// to build itself). Everything beyond that is a MODULE an instance turns on.
+//
+// Resolution precedence (highest wins), mirroring src/branding.js:
+//   env override  ->  instance config (config/modules.json)  ->  neutral
+//   starter (config/modules.neutral.json)
+// A fresh instance with NO config resolves to the VANILLA set: every feature
+// module OFF (fail-to-vanilla, never fail-to-OTB); disciplines are core only
+// (engineer + ideator — artist rides the art-pipeline module, R59).
+//
+// This is a config-flag exclusion mechanism, NOT a full plugin registry — the
+// cheaper near-term shape (ADR 0062 §4). R59 (task 1198) moves game + art-pipeline
+// in; R60 (task 1199) moves discord + dev-box in (UI sections / skills / pollers);
+// they consume the registry declared here.
+
+const fs = require('node:fs');
+const path = require('node:path');
+// The loader opens the closed registry: it discovers modules/*/module.json so the
+// resolver below spans built-in + discovered modules (ADR 0083 / BV1.R41). Empty
+// until a module is moved into modules/ — so this is a no-op on the current tree.
+const loader = require('./module-loader/loader');
+const { resolveCoreRoot, resolveInstanceRoot } = require('./instance-config');
+
+// ADR 0108 §1: the neutral starter ships WITH the core package; the instance
+// pack is host content. Both resolvers return the repo root today, so this is
+// byte-identical for the live instance.
+const NEUTRAL_PATH = path.join(resolveCoreRoot(), 'config', 'modules.neutral.json');
+const INSTANCE_PATH = path.join(resolveInstanceRoot(), 'config', 'modules.json');
+
+// The module registry — the single declarative source of what each optional
+// module contributes. The `contributes` map is documentation + the surface
+// R59/R60 consume to mount/teardown a module's parts. `default` is the
+// fail-safe value when neither config nor env names the module: always false,
+// so a brand-new instance is vanilla.
+//
+// CORE (always on, never a module): auth, builders, tasks, claims, versions,
+// done-when, credits/cost, inbox, blockers, leaderboard, analytics,
+// audit-log, security, access-requests, sessions, gate-approvals, healthz,
+// public. These mount unconditionally. The four optional feature modules AND the
+// first TWO carved CORE-domain modules have graduated to modules/<key>/ (dev-box
+// BV1.R43, discord BV1.R47, art-pipeline BV1.R48, game BV1.R49, memory BV1.R72 —
+// memory/recall/search/learnings, ADR 0091 §2 — and grading BV1.R73 — the
+// adversarial grade panel + rubric, behind the `grade` kernel port, ADR 0091 §4).
+// A core-domain module like memory or grading is `default: true` (it ships to
+// every instance — the build system's memory + quality gate are not optional),
+// unlike the default-off feature modules.
+// The built-in registry is now empty; every module is discovered + mounted by
+// moduleLoader from modules/*/module.json.
+const MODULE_REGISTRY = {};
+
+// Disciplines the CORE always provides. Modules add to this (e.g. art-pipeline
+// adds 'artist'). Ideation is methodology core — the idea_inbox, capture.js and
+// /idea-triage ship to every instance regardless of feature modules — so a
+// vanilla instance offers engineer + ideator. Only 'artist' is module-gated: it
+// exists to produce the game's pixel art, so it rides the art-pipeline module
+// (R59 / task 1198). A vanilla instance therefore offers ['engineer','ideator'].
+const CORE_DISCIPLINES = ['engineer', 'ideator'];
+
+const KNOWN_MODULES = Object.keys(MODULE_REGISTRY);
+
+// The EFFECTIVE registry spans the built-in MODULE_REGISTRY + every module
+// discovered under modules/ (ADR 0083 / BV1.R41). As a built-in is moved out
+// into modules/<key>/ (BV1.R43+), it leaves MODULE_REGISTRY and reappears here
+// as a discovered manifest, so membership is unchanged across the move. With no
+// modules/ dir (the current tree) discoveredRegistry() is {} → effectiveRegistry
+// === MODULE_REGISTRY and knownModules() === KNOWN_MODULES (byte-identical).
+function effectiveRegistry() {
+  return { ...MODULE_REGISTRY, ...loader.discoveredRegistry() };
+}
+function knownModules() {
+  return Object.keys(effectiveRegistry());
+}
+
+const TRUTHY = new Set(['1', 'true', 'on', 'yes', 'enabled']);
+const FALSY = new Set(['0', 'false', 'off', 'no', 'disabled']);
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+
+function coerceBool(v) {
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'string') {
+    const s = v.trim().toLowerCase();
+    if (TRUTHY.has(s)) return true;
+    if (FALSY.has(s)) return false;
+  }
+  return undefined;
+}
+
+// Pure resolver — all inputs injected, so tests drive it with zero I/O.
+// Returns a frozen { <moduleKey>: boolean } covering EVERY registry key, plus a
+// non-enumerable resolution that throws on an unknown module key (typo guard).
+function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = 'CLOUDBONGOS', registry = MODULE_REGISTRY } = {}) {
+  // The known-key set + defaults come from the passed registry: callers inject
+  // the built-in MODULE_REGISTRY (the default, what the pure unit tests use) or
+  // the effective built-in+discovered registry (what loadModules passes). This
+  // keeps resolveModules pure while letting the disk loader span discovered
+  // modules. (ADR 0083 / BV1.R41.)
+  const known = Object.keys(registry);
+  const fromConfig = (cfg, source) => {
+    const m = isObj(cfg) ? cfg.modules : undefined;
+    if (m === undefined) return {};
+    if (!isObj(m)) throw new Error(`modules: \`modules\` in ${source} config must be an object`);
+    const out = {};
+    for (const [k, v] of Object.entries(m)) {
+      if (known.includes(k)) { out[k] = v; continue; }
+      // Unknown key. A config may name a module this build hasn't installed: a stripped
+      // CORE has no game/art-pipeline/discord/dev-box, yet config/modules.neutral.json
+      // (which ships WITH the core) names them so the SAME file is valid in the full repo
+      // too. Tolerate an unknown module ONLY when it is DISABLED — a disabled-and-absent
+      // module is a no-op. ENABLING an absent module is a real error (the feature you asked
+      // for isn't here) and still throws, which also keeps the typo guard for the dangerous
+      // direction. (task 1824: this is what lets the vanilla core boot instead of crashing
+      // on `unknown module "game"`.)
+      if (coerceBool(v) === true) {
+        throw new Error(`modules: cannot enable unknown module "${k}" in ${source} config — it is not installed (known: ${known.join(', ') || '(none)'}).`);
+      }
+      // disabled-and-absent → silently drop (a typo on a disable is harmless; the module's
+      // default is already off, so the resolved set is identical either way).
+    }
+    return out;
+  };
+
+  const merged = { ...fromConfig(neutral, 'neutral'), ...fromConfig(instance, 'instance') };
+
+  // Env overrides: <PREFIX>_MODULE_<KEY> where KEY is upper-snake of the module
+  // name (dev-box -> DEV_BOX). Highest precedence.
+  for (const key of known) {
+    const envName = `${envPrefix}_MODULE_${key.toUpperCase().replace(/-/g, '_')}`;
+    const raw = env[envName];
+    if (raw !== undefined && raw !== '') {
+      const b = coerceBool(raw);
+      if (b === undefined) throw new Error(`modules: ${envName}="${raw}" is not a boolean (use 1/0, on/off, true/false)`);
+      merged[key] = b;
+    }
+  }
+
+  const resolved = {};
+  for (const key of known) {
+    const v = key in merged ? coerceBool(merged[key]) : undefined;
+    resolved[key] = v === undefined ? registry[key].default : v;
+  }
+  return Object.freeze(resolved);
+}
+
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
+// Disk loader with the documented precedence. Both files are OPTIONAL: with
+// neither, every module resolves to its `default` (vanilla = all off).
+//
+// Instance-pack FILE selection mirrors src/branding.js's GDS_BRANDING_FILE knob,
+// so ONE deployed checkout can run two instances side by side (OTB on the
+// committed config/modules.json; a vanilla Cloud Bongos process on the neutral
+// set) differentiated only by env, with no divergent clone. Highest wins:
+//   explicit instancePath arg
+//   -> GDS_MODULES_FILE env (a path to a modules pack)
+//   -> if GDS_BRANDING_FILE is set (this process opted into a NON-default BRAND)
+//      but names no modules file: the NEUTRAL starter — a branded sibling must
+//      NOT silently inherit the default instance's config/modules.json. That was
+//      the bug that made cloudbongos.com advertise all four modules ON though it
+//      runs the vanilla brand (CB-V1 task 1, the C8 self-build proof). Per-module
+//      env overrides (<PREFIX>_MODULE_<KEY>) still apply on top, so a branded
+//      sibling can still opt a single module on.
+//   -> config/modules.json (the default OTB instance pack)
+// Like branding's selector, these are FIXED env names (read before the resolved
+// envPrefix is known), not <PREFIX>_ ones. A relative path resolves against the
+// repo root.
+function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.env } = {}) {
+  const neutral = readJson(neutralPath) || {};
+  let ip = instancePath;
+  if (ip === undefined) {
+    const override = env.GDS_MODULES_FILE;
+    if (override) ip = path.resolve(resolveInstanceRoot(), override);
+    else if (env.GDS_BRANDING_FILE) ip = NEUTRAL_PATH;
+    else ip = INSTANCE_PATH;
+  }
+  const instance = readJson(ip) || {};
+  // Reuse the branding env prefix so an instance has ONE prefix, not two.
+  let envPrefix = 'CLOUDBONGOS';
+  try { envPrefix = require('./branding').branding().envPrefix || envPrefix; } catch { /* fail-to-default */ }
+  // Resolve against the EFFECTIVE registry (built-in + discovered) so a config
+  // flag for a discovered module is honored. No-op until a module exists.
+  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry() });
+}
+
+// Resolved singleton for app code; lazy so require-time never crashes tooling.
+let _cached = null;
+const modules = () => (_cached ||= loadModules());
+// Public invalidation — call after something changes what loadModules() would
+// read (a config-file write from the hall's Modules-tab toggle, ADR 0107 §9;
+// also used by tests). Cheap: the next modules() call just re-reads disk.
+const reload = () => { _cached = null; return modules(); };
+const _resetForTests = () => { _cached = null; };
+
+function isModuleEnabled(name, set = modules()) {
+  const known = knownModules();
+  if (!known.includes(name)) {
+    throw new Error(`modules: isModuleEnabled("${name}") — unknown module (known: ${known.join(', ')})`);
+  }
+  return set[name] === true;
+}
+
+const enabledModules = (set = modules()) => knownModules().filter((k) => set[k] === true);
+
+// Disciplines this instance offers = core + every enabled module's declared
+// disciplines, deduped, stable order. Vanilla = ['engineer','ideator'].
+function enabledDisciplines(set = modules()) {
+  const reg = effectiveRegistry();
+  const out = [...CORE_DISCIPLINES];
+  for (const key of enabledModules(set)) {
+    for (const d of (reg[key] && reg[key].contributes.disciplines) || []) {
+      if (!out.includes(d)) out.push(d);
+    }
+  }
+  return out;
+}
+
+// CLIENT-SAFE projection — module flags are just booleans, all safe to expose.
+// The hall/status front-ends read this to hide UI sections for off modules.
+function clientModules(set = modules()) {
+  return {
+    enabled: knownModules().reduce((o, k) => { o[k] = set[k] === true; return o; }, {}),
+    disciplines: enabledDisciplines(set),
+  };
+}
+
+module.exports = {
+  MODULE_REGISTRY,
+  KNOWN_MODULES,
+  effectiveRegistry,
+  knownModules,
+  CORE_DISCIPLINES,
+  resolveModules,
+  loadModules,
+  modules,
+  reload,
+  isModuleEnabled,
+  enabledModules,
+  enabledDisciplines,
+  clientModules,
+  NEUTRAL_PATH,
+  INSTANCE_PATH,
+  _resetForTests,
+};

package/src/platform-server.js

@@ -0,0 +1,135 @@
+// src/platform-server.js — the GDS-ONLY entrypoint (ADR 0062 R51, task 1190).
+//
+// The inverse of src/preview-server.js: where the preview server boots ONLY the
+// game, this boots ONLY the build platform (Cloud Bongos) — the GDS API + the
+// builders' hall + the status dashboard — with NO game in the process.
+//
+// WHAT IT SERVES — the entire internal surface, via the shared mount that
+// server.js also uses (so the two entrypoints never drift, ADR 0052):
+//   * /healthz + /version
+//   * /api/gds/*                 — the full GDS API (buildGdsRouter)
+//   * the status dashboard host  — modules/status-ui/public/ (the status-ui module's
+//                                  web surface, BV1.R84 — served by the loader seam)
+//   * the builders' hall host    — modules/hall-ui/public/ (the hall-ui module's
+//                                  web surface, BV1.R85 — served by its dedicated
+//                                  block in serve-internal)
+//   * /downloads/devbox/*        — the Dev Box installer redirects
+//
+// WHAT IT DELIBERATELY DOES NOT CONSTRUCT — the host game runtime:
+//   * NO Colyseus server, NO WebSocketTransport
+//   * NO game rooms (WorldRoom / QueueRoom). The builders' hall is still live
+//     here: its updates ride the SSE endpoint in the GDS router
+//     (src/bongos/routes/live.js, R55/ADR 0069), which needs no Colyseus — that is
+//     exactly why the room was retired.
+//   * NO Phaser/Colyseus vendored client libs (/vendor/*)
+//   * NO tile assets (/assets/tiles/*) and NO game static (public/)
+// Because this process never requires src/rooms/, src/world/, or colyseus, a
+// game-less Cloud Bongos instance — one whose repo carries zero game code — can
+// run it unchanged. The "no game route/asset is reachable" guarantee is enforced
+// by ABSENCE (the game middleware is simply never mounted), not by a runtime
+// check, exactly as preview-server.js enforces "no internal API" by absence.
+//
+// Background services (uptime poller, publish reconciler, Discord bot) are NOT
+// started here. They are not game code, but which of them a given instance runs
+// is an instance-policy decision that R54's feature-module system (task 1193)
+// will own; R51 keeps this entrypoint to the minimal "serve the surfaces" core.
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const express = require('express');
+const { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGlobal } = require('./bongos/serve-internal');
+const { isApiShapedPath, apiNotFoundBody } = require('./bongos/api-path-404');
+
+const PORT = Number(process.env.PORT) || 3000;
+const HOST = process.env.HOST || '127.0.0.1';
+
+// The apex landing page — a game-less instance's home (replaces the bare 404 the
+// apex host used to serve). A deliberately MINIMAL placeholder: the mascot + a
+// way into the Builders' Hall; the full landing is its own task. Served only on
+// the apex host (status./builders. are handled by mountInternalSurfaces). The
+// branding pack is injected once at boot (theme + window.__BRANDING__), exactly
+// as the hall pages are, so the look + identity come from config, not hardcode.
+const LANDING_DIR = path.join(__dirname, '..', 'public-landing');
+const _landingPages = new Map(); // memoized per file; '' if absent (instance ships no landing)
+function landingPage(file) {
+  if (!_landingPages.has(file)) {
+    let html = '';
+    try {
+      html = injectBrandingGlobal(fs.readFileSync(path.join(LANDING_DIR, file), 'utf8'));
+    } catch { /* absent → '' */ }
+    _landingPages.set(file, html);
+  }
+  return _landingPages.get(file);
+}
+function landingHtml() { return landingPage('index.html'); }
+function isApexHost(req) {
+  return !isStatusHost(req) && !isBuildersHost(req);
+}
+
+// Build the configured Express app WITHOUT binding a port — so the boot smoke
+// test (tests/platform-boot.mjs) can drive it over an ephemeral listener and
+// importing this module never starts a server.
+function buildPlatformApp() {
+  const app = express();
+  app.disable('x-powered-by');
+  // A Cloud Bongos instance also sits behind a reverse proxy (Caddy/Cloudflare);
+  // trust the immediate proxy so req.secure / x-forwarded-proto are honest for
+  // the OAuth callbacks the GDS auth router performs.
+  app.set('trust proxy', 1);
+
+  // The whole internal surface — shared verbatim with server.js (ADR 0062 R51).
+  mountInternalSurfaces(app);
+
+  // Apex landing. On the apex host (not status./builders.), GET / serves the
+  // branding-injected landing page, and other paths can resolve a landing asset
+  // (e.g. the mascot image) from public-landing/. Both fall through to the 404
+  // tail when there is no landing file or no matching asset.
+  app.get('/', (req, res, next) => {
+    if (!isApexHost(req)) return next();
+    const html = landingHtml();
+    if (!html) return next();
+    res.type('html').send(html);
+  });
+  // The branded project-creation experience (goal 35, task 2081) — a sibling
+  // landing page at a clean /create URL, branding-injected like the landing.
+  app.get('/create', (req, res, next) => {
+    if (!isApexHost(req)) return next();
+    const html = landingPage('create.html');
+    if (!html) return next();
+    res.type('html').send(html);
+  });
+  const landingAssets = express.static(LANDING_DIR, { index: false, fallthrough: true });
+  app.use((req, res, next) => {
+    if (!isApexHost(req)) return next();
+    return landingAssets(req, res, next);
+  });
+
+  // Non-game tail. Anything that did not resolve to /api/gds, the status host,
+  // or the builders' hall lands here. There is NO game to fall through to, so:
+  //   * an API-shaped path gets a self-describing JSON 404 (never HTML), the
+  //     same contract server.js gives so a mis-prefixed CLI call is legible;
+  //   * everything else gets a plain-text 404 — a game-less instance ships no
+  //     themed island page (public/404.html lives in the game module).
+  app.use((req, res) => {
+    res.status(404);
+    if (isApiShapedPath(req.path)) {
+      return res.json(apiNotFoundBody(req.path));
+    }
+    return res.type('text/plain').send('404 — not found');
+  });
+
+  return app;
+}
+
+// Start only when run as the entry (`node src/platform-server.js`). Importing the
+// module (the smoke test) must NOT bind a port.
+if (require.main === module) {
+  const app = buildPlatformApp();
+  const httpServer = http.createServer(app);
+  httpServer.listen(PORT, HOST, () => {
+    console.log(`Cloud Bongos platform (GDS-only, no game; ADR 0062 R51) listening on ${HOST}:${PORT}`);
+  });
+}
+
+module.exports = { buildPlatformApp };