@bongos/core 1.17.0

package/src/module-loader/loader.js

@@ -0,0 +1,268 @@
+// src/module-loader/loader.js — the module loader (BV1.R41 / task 1410, ADR 0083).
+//
+// Replaces the CLOSED KNOWN_MODULES registry (src/modules.js) with DISCOVERY:
+// it scans modules/*/module.json, validates each manifest (manifest-schema),
+// checks its coreVersion against the doorway's CORE_VERSION, and exposes the
+// discovered set so src/modules.js's resolver spans built-in + discovered, and
+// routes.js mounts discovered module routers behind the kernel's auth/audit.
+//
+// SAFE-BY-CONSTRUCTION during the strangler migration: with no modules/ dir
+// (the state until BV1.R43 moves dev-box), discovery returns EMPTY and every
+// function below is a no-op — OTB behaves byte-identically. As built-ins move
+// out, they become discovered manifests and the closed registry shrinks.
+//
+// require-time is intentionally light (manifest-schema + semver only). The
+// doorway CORE_VERSION is read LAZILY inside coreVersion() so requiring this from
+// src/modules.js can never form an eval-time cycle through module-api → auth.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { validateManifest } = require('./manifest-schema');
+const { satisfies } = require('./semver');
+const { resolveCoreRoot } = require('../instance-config');
+
+// ADR 0108 §1: modules/ ships WITH the core package. resolveCoreRoot() returns
+// the repo root today, so this is byte-identical for the live instance.
+const DEFAULT_ROOTS = [path.join(resolveCoreRoot(), 'modules')];
+
+// Lazy — avoids an eval-time require cycle (modules.js → loader → module-api →
+// auth → …). By call time the graph is loaded; falls back to the known initial
+// version if module-api is somehow unavailable (tooling contexts).
+function coreVersion() {
+  try { return require('../module-api').CORE_VERSION; } catch { return '1.0.0'; }
+}
+
+// Discover + validate + coreVersion-check every modules/*/module.json. Pure-ish
+// (reads disk; no mutation of app state). Returns:
+//   { loaded: [{key,dir,manifest}], skipped: [{key,dir,reason}], errors: [{dir,errors}] }
+function discoverModules({ roots = DEFAULT_ROOTS, core = coreVersion() } = {}) {
+  const loaded = [];
+  const skipped = [];
+  const errors = [];
+  const seen = new Set();
+
+  for (const root of roots) {
+    let entries;
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); }
+    catch (e) { if (e.code === 'ENOENT') continue; throw e; }
+
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const dir = path.join(root, ent.name);
+      const manifestPath = path.join(dir, 'module.json');
+      let raw;
+      try { raw = fs.readFileSync(manifestPath, 'utf8'); }
+      catch (e) { if (e.code === 'ENOENT') continue; errors.push({ dir, errors: [`unreadable module.json: ${e.message}`] }); continue; }
+
+      let parsed;
+      try { parsed = JSON.parse(raw); }
+      catch (e) { errors.push({ dir, errors: [`module.json is not valid JSON: ${e.message}`] }); continue; }
+
+      const { valid, errors: errs } = validateManifest(parsed);
+      if (!valid) { errors.push({ dir, errors: errs }); continue; }
+      if (parsed.key !== ent.name) { errors.push({ dir, errors: [`manifest key "${parsed.key}" must match directory name "${ent.name}"`] }); continue; }
+      if (seen.has(parsed.key)) { errors.push({ dir, errors: [`duplicate module key "${parsed.key}"`] }); continue; }
+      seen.add(parsed.key);
+
+      if (!satisfies(core, parsed.coreVersion)) {
+        skipped.push({ key: parsed.key, dir, reason: `coreVersion "${parsed.coreVersion}" not satisfied by core ${core}` });
+        continue;
+      }
+      loaded.push({ key: parsed.key, dir, manifest: parsed });
+    }
+  }
+  return { loaded, skipped, errors };
+}
+
+// Cached singleton for app code (lazy, like src/modules.js's modules()).
+let _cache = null;
+function discovered(opts) { return (_cache ||= discoverModules(opts)); }
+function _reset() { _cache = null; _startedPollers = []; }
+
+// The discovered manifests as MODULE_REGISTRY-shaped entries, so src/modules.js
+// can merge them with its built-in registry. Empty until a module exists.
+function discoveredRegistry(opts) {
+  const out = {};
+  for (const { key, manifest, dir } of discovered(opts).loaded) {
+    out[key] = {
+      title: manifest.title,
+      description: manifest.description,
+      default: manifest.default === true,
+      contributes: manifest.contributes || {},
+      _discovered: true,
+      _dir: dir,
+      _provides: manifest.provides || [],
+      _consumes: manifest.consumes || [],
+    };
+  }
+  return out;
+}
+
+// Mount each discovered + ENABLED module's route factories onto `router`. A
+// module declares contributes.routes:["box"] → factory at modules/<key>/routes/box.js
+// exporting a function returning an express Router. Auth model: audit is composed
+// at the kernel level in routes.js before this is called; each route self-gates at
+// its required rank via api.requireBuilder / api.requireRank (public read routes
+// need no gate). The BV1.R44 fitness check enforces that every write route is
+// rank-gated. Returns the count mounted. No-op when nothing is discovered/enabled.
+function mountModuleRoutes(router, { isEnabled } = {}, opts) {
+  let mounted = 0;
+  for (const { key, dir, manifest } of discovered(opts).loaded) {
+    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+    const routeKeys = (manifest.contributes && manifest.contributes.routes) || [];
+    for (const rk of routeKeys) {
+      const factory = require(path.join(dir, 'routes', `${rk}.js`));
+      const sub = typeof factory === 'function' ? factory() : factory;
+      router.use(sub);
+      mounted += 1;
+    }
+  }
+  return mounted;
+}
+
+// Hall-widget client scripts contributed by enabled modules (BV1.R75, ADR 0062 §4).
+// A module that owns a builders'-hall UI section declares contributes.uiSections in
+// its manifest AND ships a browser script at modules/<key>/public/hall-widget.js that
+// calls window.OTB.contributeHallWidget({...}). This returns, for each discovered +
+// ENABLED module that declares uiSections and actually ships that file, the SERVED URL
+// the hall HTML should <script>-load — i.e. /modules/<key>/public/hall-widget.js (the
+// static mount serve-internal.js adds under /modules/). The hall twin of
+// mountModuleRoutes: an enabled module's widget appears, a disabled one vanishes (it's
+// never injected), and contributeHallWidget itself no-ops a stale widget whose module
+// is off. No-op (empty list) until a module ships a hall widget — same SAFE-BY-
+// CONSTRUCTION posture as every other seam here. Returns [{ key, src }].
+function hallWidgetScripts({ isEnabled } = {}, opts) {
+  const out = [];
+  for (const { key, dir, manifest } of discovered(opts).loaded) {
+    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+    const sections = (manifest.contributes && manifest.contributes.uiSections) || [];
+    if (sections.length === 0) continue;
+    const scriptPath = path.join(dir, 'public', 'hall-widget.js');
+    if (!fs.existsSync(scriptPath)) continue; // declarative-only uiSections (e.g. status-page section)
+    out.push({ key, src: `/modules/${key}/public/hall-widget.js` });
+  }
+  return out;
+}
+
+// Host-routed static web surfaces contributed by enabled modules (BV1.R84, ADR 0093
+// §1 / 02-module-map §6 — a web surface is first-class). A module that owns a web
+// surface (e.g. the status dashboard at status.<apex>) declares
+// contributes.webSurfaces:[{ host:"status.", dir:"public" }] in its manifest AND
+// ships that static dir at modules/<key>/<dir>/. This returns, for each discovered +
+// ENABLED module that declares webSurfaces and actually ships the directory, the
+// SERVING descriptor serve-internal.js iterates to route by Host header:
+//   { key, host, dir } — host is the lowercase Host-header prefix; dir is the
+//   ABSOLUTE on-disk path of the static directory.
+// The Host-routed twin of mountModuleRoutes / hallWidgetScripts: an enabled module's
+// surface answers on its host, a disabled one vanishes (it's never returned, so
+// serve-internal never routes its host). No-op (empty list) until a module ships a
+// web surface — same SAFE-BY-CONSTRUCTION posture as every other seam here. Pure
+// (reads disk only). Exported + module-agnostic so serve-internal hardcodes no key.
+function moduleWebSurfaces({ isEnabled } = {}, opts) {
+  const out = [];
+  for (const { key, dir, manifest } of discovered(opts).loaded) {
+    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+    const surfaces = (manifest.contributes && manifest.contributes.webSurfaces) || [];
+    for (const s of surfaces) {
+      if (!s || typeof s.host !== 'string' || typeof s.dir !== 'string') continue;
+      const abs = path.join(dir, s.dir);
+      let isDir = false;
+      try { isDir = fs.statSync(abs).isDirectory(); } catch { isDir = false; }
+      if (!isDir) continue; // declared but not shipped → skip (no host routed)
+      out.push({ key, host: s.host.toLowerCase(), dir: abs });
+    }
+  }
+  return out;
+}
+
+// Started poller handles (key, name, module), so stopModulePollers stops exactly
+// what startModulePollers started — and a test can introspect them.
+let _startedPollers = [];
+
+// Start each discovered + ENABLED module's background pollers. A module declares
+// contributes.pollers:["discord-bot"] → a start/stop module at
+// modules/<key>/pollers/discord-bot.js. NON-BLOCKING + failure-isolated: start()
+// may return a promise (e.g. the Discord gateway connect); we fire it and attach
+// a .catch so a poller problem can never take the boot — the API/game stay up.
+// This is the module-agnostic successor to the hardcoded `discordBot.start()`
+// block server.js used to carry (BV1.R47 / task 1416). `deps` is forwarded to
+// each poller's start(); `{ isEnabled }` gates by the instance's module config.
+// No-op when nothing is discovered/enabled. Returns the started-handle list.
+function startModulePollers(deps = {}, { isEnabled } = {}, opts) {
+  const started = [];
+  for (const { key, dir, manifest } of discovered(opts).loaded) {
+    if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
+    const pollerKeys = (manifest.contributes && manifest.contributes.pollers) || [];
+    for (const pk of pollerKeys) {
+      const pollerPath = path.join(dir, 'pollers', `${pk}.js`);
+      let poller;
+      try {
+        poller = require(pollerPath);
+      } catch (e) {
+        // No modules/<key>/pollers/<pk>.js → a DECLARATIVE-ONLY / non-web poller
+        // (e.g. dev-box's box-lifecycle sweep runs on the control plane, not in
+        // this process). Skip silently — only a web-process poller ships a file
+        // here. A file that EXISTS but throws is a real error (the catch below).
+        if (e && e.code === 'MODULE_NOT_FOUND' && String(e.message).includes(pollerPath)) continue;
+        console.error(`[module-loader] poller ${key}/${pk} failed to load: ${e && e.message ? e.message : e}`);
+        continue;
+      }
+      try {
+        if (poller && typeof poller.start === 'function') {
+          const r = poller.start(deps);
+          if (r && typeof r.then === 'function') {
+            r.catch((e) => console.error(`[module-loader] poller ${key}/${pk} start error: ${e && e.message ? e.message : e}`));
+          }
+          started.push({ key, poller: pk, handle: poller });
+        }
+      } catch (e) {
+        console.error(`[module-loader] poller ${key}/${pk} start threw: ${e && e.message ? e.message : e}`);
+      }
+    }
+  }
+  _startedPollers = started;
+  return started;
+}
+
+// Stop every poller startModulePollers started, in reverse order. Awaits each
+// stop() (the Discord gateway close is async) so a caller can sequence a clean
+// shutdown: `loader.stopModulePollers().finally(() => process.exit(0))`. Errors
+// are isolated — one poller's failed stop never blocks the others. Returns the
+// count stopped.
+async function stopModulePollers() {
+  const handles = _startedPollers.slice().reverse();
+  _startedPollers = [];
+  for (const { key, poller, handle } of handles) {
+    try {
+      if (handle && typeof handle.stop === 'function') await handle.stop();
+    } catch (e) {
+      console.error(`[module-loader] poller ${key}/${poller} failed to stop: ${e && e.message ? e.message : e}`);
+    }
+  }
+  return handles.length;
+}
+
+// A snapshot for observability / a /watch tile.
+function loaderSnapshot(opts) {
+  const d = discovered(opts);
+  return {
+    loaded: d.loaded.map((m) => m.key),
+    skipped: d.skipped,
+    errors: d.errors,
+  };
+}
+
+module.exports = {
+  discoverModules,
+  discovered,
+  discoveredRegistry,
+  mountModuleRoutes,
+  hallWidgetScripts,
+  moduleWebSurfaces,
+  startModulePollers,
+  stopModulePollers,
+  loaderSnapshot,
+  coreVersion,
+  DEFAULT_ROOTS,
+  _reset,
+};

package/src/module-loader/manifest-schema.js

@@ -0,0 +1,140 @@
+// src/module-loader/manifest-schema.js — the module.json manifest schema +
+// validator (BV1.R38 / task 1407, ADR 0083 / design 04§4).
+//
+// A module.json is the single declared contract for what a module contributes.
+// It is the per-module externalization of the closed MODULE_REGISTRY entries in
+// src/modules.js (which the loader, BV1.R41, replaces with manifest discovery).
+// The loader and the fitness gate both act on it, so "maintaining a module"
+// largely means "keeping its manifest true."
+//
+// THE SCHEMA (module.json):
+//   {
+//     "key":          "dev-box",        // REQUIRED. ^[a-z][a-z0-9-]*$ ; must match the module's dir name.
+//     "title":        "Dev boxes",      // REQUIRED. Human label.
+//     "description":  "…",              // REQUIRED. One sentence.
+//     "coreVersion":  "^1.0.0",         // REQUIRED. semver range of src/module-api.js CORE_VERSION it supports.
+//     "default":      false,            // OPTIONAL (default false). Enablement fail-safe when no config names it.
+//     "author":       "…",              // OPTIONAL. Attribution (ADR 0107 §2) — portable, not a cross-GDS FK.
+//     "origin":       "…",              // OPTIONAL. Origin instance/project this module was built in.
+//     "license":      "…",              // OPTIONAL. e.g. "AGPL-3.0" — the license this module is offered under.
+//     "maintainer":   "…",              // OPTIONAL. Who to credit/contact if this module is upstreamed.
+//     "contributes": {                  // REQUIRED object (may be empty). What the module mounts:
+//       "routes":      ["box"],         //   route-factory keys (mounted behind kernel-composed auth)
+//       "rooms":       ["WorldRoom"],   //   Colyseus room classes (realtime seam)
+//       "pollers":     ["box-lifecycle"],// background pollers to start/stop
+//       "disciplines": ["artist"],      //   disciplines this module adds
+//       "skills":      ["otb-…"],       //   slash-command skills it ships
+//       "uiSections":  ["boxes"],       //   hall/status UI sections it owns
+//       "webSurfaces": [{ "host": "status.", "dir": "public" }], // host-routed static web surfaces (BV1.R84)
+//       "migrations":  true             //   true => modules/<key>/migrations/ exists (or an array of names)
+//     },
+//     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
+//     "consumes":      ["grade"],       // OPTIONAL. seam ports this module resolves (required capabilities).
+//     "prerequisites": { "modules": ["economy"] }  // OPTIONAL. other modules that must be enabled.
+//   }
+//
+// validateManifest(obj) -> { valid, errors[], manifest } — pure, no I/O.
+// assertValidManifest(obj) throws on the first failure (loader convenience).
+
+const { isValidRange } = require('./semver');
+
+const KEY_RE = /^[a-z][a-z0-9-]*$/;
+
+// contributes sub-keys that must be arrays of non-empty strings when present.
+const ARRAY_OF_STRING_KEYS = ['routes', 'rooms', 'pollers', 'disciplines', 'skills', 'uiSections'];
+// Every key contributes is ALLOWED to declare (anything else is a typo → error).
+// webSurfaces (BV1.R84) is the host-routed static-surface seam — an array of
+// objects, not strings, so it is validated separately below.
+const ALLOWED_CONTRIBUTES = [...ARRAY_OF_STRING_KEYS, 'webSurfaces', 'migrations'];
+
+// Top-level attribution fields (ADR 0107 §2) — optional, portable strings.
+const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
+
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+const isStrArray = (v) => Array.isArray(v) && v.every(isStr);
+
+// A webSurface entry: { host: "<subdomain-prefix>.", dir: "<static-dir-rel-to-module>" }.
+// `host` is the lowercase Host-header prefix the surface answers on (e.g. "status."
+// → status.<apex>); `dir` is the module-relative directory of static files to serve
+// (e.g. "public"). Both required, non-empty strings; `dir` must stay inside the
+// module (no absolute / "..").
+const isWebSurface = (v) =>
+  isObj(v) && isStr(v.host) && isStr(v.dir) && !v.dir.startsWith('/') && !v.dir.split(/[\\/]/).includes('..');
+const isWebSurfaceArray = (v) => Array.isArray(v) && v.every(isWebSurface);
+
+function validateManifest(obj) {
+  const errors = [];
+  const E = (msg) => errors.push(msg);
+
+  if (!isObj(obj)) {
+    return { valid: false, errors: ['manifest must be a JSON object'], manifest: null };
+  }
+
+  // --- required scalar fields ---
+  if (!isStr(obj.key)) E('key: required non-empty string');
+  else if (!KEY_RE.test(obj.key)) E(`key: "${obj.key}" must match ${KEY_RE} (lowercase, kebab-case)`);
+
+  if (!isStr(obj.title)) E('title: required non-empty string');
+  if (!isStr(obj.description)) E('description: required non-empty string');
+
+  if (!isStr(obj.coreVersion)) E('coreVersion: required non-empty semver range string (e.g. "^1.0.0")');
+  else if (!isValidRange(obj.coreVersion)) E(`coreVersion: "${obj.coreVersion}" is not a valid semver range`);
+
+  // --- optional default ---
+  if ('default' in obj && typeof obj.default !== 'boolean') E('default: must be a boolean when present');
+
+  // --- optional attribution (ADR 0107 §2 — portable credit, not a cross-GDS FK) ---
+  for (const k of ATTRIBUTION_KEYS) {
+    if (k in obj && !isStr(obj[k])) E(`${k}: must be a non-empty string when present`);
+  }
+
+  // --- contributes (required object) ---
+  if (!isObj(obj.contributes)) {
+    E('contributes: required object (use {} if the module contributes nothing)');
+  } else {
+    for (const k of Object.keys(obj.contributes)) {
+      if (!ALLOWED_CONTRIBUTES.includes(k)) {
+        E(`contributes.${k}: unknown key (allowed: ${ALLOWED_CONTRIBUTES.join(', ')})`);
+      }
+    }
+    for (const k of ARRAY_OF_STRING_KEYS) {
+      if (k in obj.contributes && !isStrArray(obj.contributes[k])) {
+        E(`contributes.${k}: must be an array of non-empty strings`);
+      }
+    }
+    if ('webSurfaces' in obj.contributes && !isWebSurfaceArray(obj.contributes.webSurfaces)) {
+      E('contributes.webSurfaces: must be an array of { host: "<prefix>.", dir: "<module-relative dir>" } objects (dir inside the module, no absolute path or "..")');
+    }
+    if ('migrations' in obj.contributes) {
+      const m = obj.contributes.migrations;
+      if (typeof m !== 'boolean' && !isStrArray(m)) {
+        E('contributes.migrations: must be true/false or an array of migration names');
+      }
+    }
+  }
+
+  // --- optional seam declarations ---
+  if ('provides' in obj && !isStrArray(obj.provides)) E('provides: must be an array of non-empty strings (port names)');
+  if ('consumes' in obj && !isStrArray(obj.consumes)) E('consumes: must be an array of non-empty strings (port names)');
+
+  // --- optional prerequisites ---
+  if ('prerequisites' in obj) {
+    if (!isObj(obj.prerequisites)) E('prerequisites: must be an object');
+    else if ('modules' in obj.prerequisites && !isStrArray(obj.prerequisites.modules)) {
+      E('prerequisites.modules: must be an array of module-key strings');
+    }
+  }
+
+  return { valid: errors.length === 0, errors, manifest: errors.length === 0 ? obj : null };
+}
+
+function assertValidManifest(obj, label = 'module.json') {
+  const { valid, errors } = validateManifest(obj);
+  if (!valid) {
+    throw new Error(`${label} invalid:\n  - ${errors.join('\n  - ')}`);
+  }
+  return obj;
+}
+
+module.exports = { validateManifest, assertValidManifest, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS };

package/src/module-loader/provenance.js

@@ -0,0 +1,28 @@
+// src/module-loader/provenance.js — pure "who built this module" classifier
+// (ADR 0107 §9). A module is OWN-BUILT if its manifest names no `origin`, or
+// names this instance itself; it is CORE-LOADED if `origin` names a
+// different project — i.e. it flowed in from the shared Cloud Bongos catalog
+// (ADR 0107 §1's upstream/downstream arrows meet here).
+//
+// No module in this tree names a FOREIGN origin today — every module here was
+// built in this repo. Some name THIS instance as their origin (e.g. the
+// provisioning module's "Off the Boats (the first Cloud Bongos instance…)"),
+// which is still own-built. The split (core-loaded) side lights up only once a
+// module is actually pulled back in from the shared catalog under a different
+// project's name (ADR 0107 §8 pipeline, tasks 1770/1772).
+
+function deriveProvenance(origin, ownProjectName) {
+  const o = origin && String(origin).trim();
+  if (!o) return 'own';
+  const own = ownProjectName && String(ownProjectName).trim().toLowerCase();
+  // "names this instance itself" (ADR 0107 §9) — an origin that IS, or leads
+  // with, the own project name is own-built (a self-referential origin like
+  // "Off the Boats (the first Cloud Bongos instance)" counts). Only an origin
+  // naming a DIFFERENT project is core-loaded from the shared catalog. (An
+  // exact `===` was too brittle: it was written when no module set `origin`,
+  // so it never met a real, descriptive value — task 1776 re-land.)
+  if (!own || o.toLowerCase().startsWith(own)) return 'own';
+  return 'core';
+}
+
+module.exports = { deriveProvenance };

package/src/module-loader/semver.js

@@ -0,0 +1,100 @@
+// src/module-loader/semver.js — a tiny, dependency-free semver checker for the
+// module system (BV1.R38 / task 1407, ADR 0083).
+//
+// We deliberately do NOT pull in the `semver` npm package: the project is a
+// no-bundler, dependency-minimal monolith, and the module-system only needs a
+// small, well-understood subset — exact, caret (^), tilde (~), comparator
+// ranges (>=, >, <=, <, =), and "*"/"" (any). A module declares the
+// `coreVersion` range it supports; the loader (BV1.R41) checks it against
+// CORE_VERSION from src/module-api.js; `bongos upgrade` (BV1.R50) reuses this.
+
+const SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+
+// Parse "1.2.3" -> [1,2,3], or null if not a clean release version (we don't
+// support pre-release/build metadata — the core version is always plain X.Y.Z).
+function parseVersion(v) {
+  if (typeof v !== 'string') return null;
+  const m = SEMVER_RE.exec(v.trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+function cmp(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+// A single comparator (one space-separated token) against a parsed version.
+function satisfiesComparator(version, token) {
+  const t = token.trim();
+  if (t === '' || t === '*' || t === 'x' || t === 'X') return true;
+
+  // caret: ^1.2.3 -> >=1.2.3 <2.0.0 ; ^0.2.3 -> >=0.2.3 <0.3.0 ; ^0.0.3 -> >=0.0.3 <0.0.4
+  if (t.startsWith('^')) {
+    const base = parseVersion(t.slice(1));
+    if (!base) return false;
+    if (cmp(version, base) < 0) return false;
+    let upper;
+    if (base[0] > 0) upper = [base[0] + 1, 0, 0];
+    else if (base[1] > 0) upper = [0, base[1] + 1, 0];
+    else upper = [0, 0, base[2] + 1];
+    return cmp(version, upper) < 0;
+  }
+
+  // tilde: ~1.2.3 -> >=1.2.3 <1.3.0
+  if (t.startsWith('~')) {
+    const base = parseVersion(t.slice(1));
+    if (!base) return false;
+    if (cmp(version, base) < 0) return false;
+    return cmp(version, [base[0], base[1] + 1, 0]) < 0;
+  }
+
+  // comparator ranges
+  const m = /^(>=|<=|>|<|=)?\s*(\d+\.\d+\.\d+)$/.exec(t);
+  if (!m) return false;
+  const op = m[1] || '=';
+  const base = parseVersion(m[2]);
+  if (!base) return false;
+  const c = cmp(version, base);
+  switch (op) {
+    case '>=': return c >= 0;
+    case '<=': return c <= 0;
+    case '>': return c > 0;
+    case '<': return c < 0;
+    case '=': return c === 0;
+    default: return false;
+  }
+}
+
+// Does `version` (an exact X.Y.Z) satisfy `range`? A range is space-separated
+// comparators ALL of which must hold (AND); "||" separates alternative ranges
+// (OR). Returns false on an unparseable version.
+function satisfies(version, range) {
+  const v = parseVersion(version);
+  if (!v) return false;
+  if (range == null || range === '') return true;
+  const alternatives = String(range).split('||');
+  return alternatives.some((alt) =>
+    alt.trim().split(/\s+/).filter(Boolean).every((tok) => satisfiesComparator(v, tok)));
+}
+
+// Is `range` a syntactically valid range string we can evaluate? Used by the
+// manifest validator so a typo'd coreVersion is caught at validate-time, not at
+// mount-time.
+function isValidRange(range) {
+  if (range == null) return false;
+  const s = String(range).trim();
+  if (s === '' || s === '*') return true;
+  return s.split('||').every((alt) => {
+    const tokens = alt.trim().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) return false;
+    return tokens.every((t) => {
+      if (t === '*' || t === 'x' || t === 'X') return true;
+      if (t.startsWith('^') || t.startsWith('~')) return parseVersion(t.slice(1)) != null;
+      return /^(>=|<=|>|<|=)?\s*\d+\.\d+\.\d+$/.test(t);
+    });
+  });
+}
+
+module.exports = { parseVersion, satisfies, isValidRange, cmp };