@bongos/core 1.19.98 → 1.19.100

package/scripts/gds/module.js

@@ -22,6 +22,15 @@
 //     version of the loader's silent coreVersion SKIP (which would just drop the
 //     module at boot). Disabled mismatches are warnings, not blockers.
 //
+//   bongos module list [--catalog] [--search <q>] [--json]
+//     ADR 0107 §2/§3 (task 1001772) — the BROWSABLE CATALOG from the terminal:
+//     every module this instance can enable, each with its author + origin
+//     credit, its enabled state, and who maintains it. `--catalog` narrows to
+//     the CORE-shipped modules (the shared catalog an instance opts into, §6);
+//     without it you also see the instance's own modules. It renders the same
+//     model as the hall's Modules tab (src/module-loader/catalog.js), so the two
+//     surfaces cannot disagree about who built what.
+//
 //   bongos module check <key>
 //     ADR 0107 §4 — the submit-time pre-check a module must clear before it can
 //     be upstreamed into the shared core catalog. REUSES (never re-types) the
@@ -48,6 +57,7 @@
 // Usage:
 //   bongos module new <key>            scaffold modules/<key>/
 //   bongos module new <key> --force    overwrite an existing modules/<key>/
+//   bongos module list [--catalog]     browse the module catalog (author + origin credit)
 //   bongos upgrade                     pre-check enabled modules vs the core version
 //   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
 
@@ -60,6 +70,7 @@ const MODULES_DIR = path.join(REPO_ROOT, 'modules');
 const { validateManifest, assertValidManifest, KEY_RE, SUNSET_STATUSES } = require('../../src/module-loader/manifest-schema');
 const { parseVersion, cmp } = require('../../src/module-loader/semver');
 const loader = require('../../src/module-loader/loader');
+const catalog = require('../../src/module-loader/catalog');
 const { resolveModules, MODULE_REGISTRY, NEUTRAL_PATH, INSTANCE_PATH } = require('../../src/modules');
 // The public-mirror publish boundary (ADR 0098) — REUSED, never re-typed, for
 // the ADR 0107 §4 upstreaming pre-check. Only matchesDeny is used (not the full
@@ -327,6 +338,125 @@ function gatherUpgrade({ modulesDir = MODULES_DIR, core = coreVersion(), env = p
   return { rows, errors, core };
 }
 
+// ---------------------------------------------------------------------------
+// bongos module list — ADR 0107 §2/§3 the browsable catalog (task 1001772)
+// ---------------------------------------------------------------------------
+
+// The live catalog off disk + config. Unlike gatherUpgrade (which scans ONE
+// modulesDir because it is answering a question about this checkout's own
+// modules), this uses the loader's DEFAULT roots so a split instance sees both
+// trees — the core package's modules/ AND its own (ADR 0108 §1). That two-root
+// scan is what makes "core-shipped vs. built here" a structural fact here
+// rather than a guess.
+function gatherCatalog({ roots, core = coreVersion(), env = process.env, neutral, instance, prefix } = {}) {
+  neutral = neutral || readJson(NEUTRAL_PATH) || {};
+  instance = instance || readJson(INSTANCE_PATH) || {};
+  prefix = prefix || envPrefix();
+
+  const { loaded, skipped, errors } = loader.discoverModules(roots ? { roots, core } : { core });
+
+  // Same registry-spanning rule as gatherUpgrade: resolveModules throws on an
+  // unknown key, so every discovered key must be in the registry it is given.
+  const registry = { ...MODULE_REGISTRY };
+  for (const { key, manifest } of loaded) {
+    if (!(key in registry)) registry[key] = { default: manifest.default === true, contributes: manifest.contributes || {} };
+  }
+  for (const { key } of skipped) {
+    if (key && !(key in registry)) registry[key] = { default: false, contributes: {} };
+  }
+
+  let enabled = {};
+  try { enabled = resolveModules({ neutral, instance, env, envPrefix: prefix, registry }); }
+  catch { /* a malformed config must not blank the catalog — show it all as disabled */ }
+
+  const { coreRoot, instanceRoot, coreCheckout } = catalog.detectRoots();
+  const rows = catalog.buildCatalog({
+    loaded, enabled, coreRoot, instanceRoot, coreCheckout, ownProjectName: ownProjectName(),
+  });
+  return { rows, skipped, errors, core };
+}
+
+// The instance's own product name, for the credit axis (deriveProvenance).
+// Fail-soft: no brand pack resolvable → null, which makes provenance fall back
+// to "own-built" rather than guessing (provenance.js's documented behaviour).
+function ownProjectName() {
+  try { return require('../../src/branding').branding().identity.productName; } catch { return null; }
+}
+
+function pad(s, n) { return String(s == null ? '' : s).padEnd(n); }
+function clip(s, n) {
+  const v = String(s == null ? '' : s);
+  return v.length > n ? `${v.slice(0, n - 1)}…` : v;
+}
+
+// Pure renderer — every input arrives as a parameter (the tests pass catalog
+// rows straight in), so it touches no disk and no config.
+function formatCatalog(rows, { catalogOnly = false, query = '', core = null } = {}) {
+  const scoped = catalogOnly ? catalog.catalogRows(rows) : rows;
+  const shown = catalog.searchCatalog(scoped, query);
+  const counts = catalog.summarize(rows);
+  const out = [];
+
+  out.push(catalogOnly
+    ? 'bongos module list --catalog — core modules this instance can enable (ADR 0107 §6: opt-in, default-off)'
+    : 'bongos module list — every module on disk, with author + origin credit (ADR 0107 §2)');
+  if (core) out.push(`  core (src/module-api.js CORE_VERSION): ${core}`);
+  out.push(`  ${counts.catalog} in the core catalog (${counts.catalog_enabled} enabled) · ${counts.instance} built here · ${counts.total} total`);
+  if (query) out.push(`  filter "${query}" — ${shown.length} match(es)`);
+  out.push('');
+
+  if (!shown.length) {
+    out.push(query ? '  no module matches that filter.' : '  no modules discovered.');
+    return out.join('\n');
+  }
+
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  for (const r of shown) {
+    const mark = r.enabled ? '[x]' : '[ ]';
+    // An inferred credit is marked so it never reads as something the author
+    // typed — the catalog's whole job is honest attribution (ADR 0107 §2).
+    const suffix = r.credit.inferred ? '*' : '';
+    const upkeep = (r.maintenance && r.maintenance.status) || 'undeclared';
+    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(r.source, 10)}${pad(clip((r.credit.author || '—') + suffix, 19), 20)}${pad(clip((r.credit.origin || '—') + suffix, 25), 26)}${pad(clip(r.license || '—', 11), 12)}${upkeep}`);
+  }
+  out.push('');
+  out.push('  [x] enabled here · [ ] available, not enabled');
+  if (shown.some((r) => r.credit.inferred)) {
+    out.push(`  * credit not declared in module.json — shown as the platform (${catalog.CORE_PROJECT_NAME}), which ships it.`);
+  }
+  out.push('  enable one: add it to config/modules.json, or use the hall\'s Modules tab (Metic+).');
+  return out.join('\n');
+}
+
+function cmdList(args, { log = console.log, errlog = console.error, gather = gatherCatalog } = {}) {
+  const catalogOnly = args.includes('--catalog');
+  const json = args.includes('--json');
+  const sIdx = args.indexOf('--search');
+  const query = sIdx !== -1 ? (args[sIdx + 1] || '') : '';
+  if (sIdx !== -1 && (!args[sIdx + 1] || args[sIdx + 1].startsWith('--'))) {
+    errlog('usage: bongos module list [--catalog] [--search <text>] [--json]');
+    return 2;
+  }
+
+  let data;
+  try { data = gather(); }
+  catch (e) { errlog(`bongos module list: ${e.message}`); return 1; }
+
+  if (json) {
+    const scoped = catalogOnly ? catalog.catalogRows(data.rows) : data.rows;
+    const modules = catalog.searchCatalog(scoped, query);
+    log(JSON.stringify({ core: data.core, summary: catalog.summarize(data.rows), modules }, null, 2));
+    return 0;
+  }
+
+  log(formatCatalog(data.rows, { catalogOnly, query, core: data.core }));
+  for (const s of data.skipped) {
+    errlog(`  ! ${s.key}: not listed — ${s.reason}`);
+  }
+  for (const e of data.errors) errlog(`  ! ${e.dir}: ${(e.errors || []).join('; ')}`);
+  return 0;
+}
+
 // ---------------------------------------------------------------------------
 // bongos module check <key> — ADR 0107 §4 upstreaming pre-check + DCO sign-off
 // ---------------------------------------------------------------------------
@@ -649,6 +779,8 @@ function printHelp(out = console.log) {
   out('bongos module — scaffold + manage Cloud Bongos modules\n');
   out('Usage:');
   out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + CLAUDE.md)');
+  out('  bongos module list [--catalog] [--search <text>] [--json]');
+  out('                              Browse the module catalog — what you can enable, with author + origin credit');
   out('  bongos upgrade              Pre-check enabled modules against the core version (fail-closed)');
   out('  bongos module check <key> [--sign-off "Name <email>"]');
   out('                              AGPL/publish pre-check before upstreaming + record a DCO-style sign-off');
@@ -660,6 +792,7 @@ async function main(argv) {
   const args = argv.slice(2);
   const sub = args[0];
   if (sub === 'new') return cmdNew(args.slice(1));
+  if (sub === 'list' || sub === 'ls') return cmdList(args.slice(1));
   if (sub === 'upgrade') return cmdUpgrade(args.slice(1));
   if (sub === 'check') return cmdCheck(args.slice(1));
   if (sub === 'submit') return cmdSubmit(args.slice(1));
@@ -673,7 +806,8 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
+  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, printHelp,
+  gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, buildManifest,
   formatMaintenanceHint, isPastRemoveAfter,
   checkModulePublishability, recordSignOff, readSignOff, DCO_STATEMENT,

package/src/bongos/routes/modules.js

@@ -43,7 +43,7 @@ const path = require('node:path');
 const auth = require('../auth');
 const { asyncHandler, validateOrRespond, LIMITS } = require('./_helpers');
 const loader = require('../../module-loader/loader');
-const { deriveProvenance } = require('../../module-loader/provenance');
+const catalog = require('../../module-loader/catalog');
 const modulesLib = require('../../modules');
 // scripts/gds/ is a sibling CORE-package dir (both resolve under
 // resolveCoreRoot() — see scripts/gds/CLAUDE.md), so requiring its pure fs
@@ -80,31 +80,26 @@ function readInstanceConfig() {
   catch (e) { if (e.code === 'ENOENT') return { modules: {} }; throw e; }
 }
 
+// The catalog model (src/module-loader/catalog.js) is the SINGLE builder behind
+// both surfaces — this route and `bongos module list` — so the hall and the
+// terminal can never disagree about who built a module or which tree it ships
+// from (task 1001772). Every field the pre-catalog version returned is still
+// here, byte-for-byte; what's new is `source` (core-shipped vs. built here,
+// read structurally from the discovery root) and `credit` (the display
+// attribution, never blank for a core module, with `inferred` marking a value
+// the manifest didn't declare). `author`/`origin` stay the DECLARED manifest
+// values — `provenance` is derived from those, not from the display credit.
 function listModules() {
   const { loaded } = loader.discoverModules();
-  const enabledSet = modulesLib.modules();
-  const own = ownProjectName();
-  return loaded.map(({ key, manifest }) => {
-    const provenance = deriveProvenance(manifest.origin, own);
-    return {
-      key,
-      title: manifest.title,
-      description: manifest.description,
-      default: manifest.default === true,
-      enabled: enabledSet[key] === true,
-      coreVersion: manifest.coreVersion,
-      contributes: manifest.contributes || {},
-      provenance,
-      author: manifest.author || null,
-      origin: manifest.origin || null,
-      license: manifest.license || null,
-      maintainer: manifest.maintainer || null,
-      // Upkeep posture (ADR 0107 §7 / ADR 0166) — the catalog's job is to show
-      // who keeps a module true as the core advances, so a deprecated or
-      // unowned entry reads as such instead of looking like any other module.
-      maintenance: manifest.maintenance || null,
-    };
-  }).sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  const { coreRoot, instanceRoot, coreCheckout } = catalog.detectRoots();
+  return catalog.buildCatalog({
+    loaded,
+    enabled: modulesLib.modules(),
+    coreRoot,
+    instanceRoot,
+    coreCheckout,
+    ownProjectName: ownProjectName(),
+  });
 }
 
 module.exports = function buildModulesRouter() {
@@ -117,6 +112,10 @@ module.exports = function buildModulesRouter() {
       modules: all,
       own_built: all.filter((m) => m.provenance === 'own').length,
       core_loaded: all.filter((m) => m.provenance === 'core').length,
+      // The catalog roll-up (task 1001772): how many modules the core ships that
+      // this instance can opt into, and how many it has. Distinct from the
+      // own_built/core_loaded pair above, which counts the CREDIT axis.
+      catalog: catalog.summarize(all),
       submit_pipeline_live: true, // task 1770 shipped — POST /modules/:key/submit is real
     });
   }));

package/src/module-api.js

@@ -623,8 +623,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.96 with no explicit bump. run 31749223878. (task 1002620)
 //   1.19.98 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.97 with no explicit bump. run 31749841394. (task 1002620)
+//   1.19.99 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.98 with no explicit bump. run 31750941866. (task 1002620)
+//   1.19.100 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.99 with no explicit bump. run 31751275973. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.98'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.100'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/src/module-loader/catalog.js

@@ -0,0 +1,217 @@
+// src/module-loader/catalog.js — the browsable module catalog (ADR 0107 §2/§3,
+// task 1001772, the last task of goal 1000029). The "larger repository of
+// modules built by the sub-projects": every module an instance can enable, each
+// carrying its author + origin credit.
+//
+// Two surfaces read this ONE model so they cannot drift: the hall's Modules tab
+// (GET /api/bongos/modules) and `bongos module list --catalog`. Pure functions
+// only — the fs/config reads live in detectRoots() at the bottom, and every
+// builder below takes its inputs injected so the tests drive it hermetically.
+//
+// ---------------------------------------------------------------------------
+// The two axes, and why they are NOT the same question
+// ---------------------------------------------------------------------------
+//
+//   source     WHICH TREE does this module ship from — the core package, or
+//              this instance's own repo? Structural: it comes from the loader's
+//              discovery root (src/module-loader/loader.js scans both, ADR 0108
+//              §1). This is the CATALOG axis — "core" means an instance can
+//              enable it because the core shipped it.
+//
+//   provenance WHO BUILT it — read off the manifest's `origin` string
+//              (provenance.js, ADR 0107 §9). This is the CREDIT axis.
+//
+// They were conflated before this file existed: the Modules tab derived
+// "core-loaded" from `origin` alone, so in a split instance every core module
+// (economy, governance, hall-ui…) — none of which declares an `origin`, because
+// none was upstreamed from anywhere — read as "built here". A module's author
+// and the tree it ships from are independent facts; the catalog needs both.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { deriveProvenance } = require('./provenance');
+
+// The core's own published + source package names. A checkout whose package.json
+// says one of these IS the core, so its modules/ IS the catalog (see
+// coreCheckout below). Mirrors CORE_PKG in scripts/gds/{init,upgrade,update-channel}.js.
+const CORE_PACKAGE_NAMES = ['@bongos/core', 'cloud-bongos'];
+
+// The credit a core-shipped module carries when its manifest declares none.
+// Core's own modules predate the ADR 0107 §2 attribution fields and mostly leave
+// them unset; the honest answer is "the platform authored this", not a blank
+// cell. Callers may override (an instance rebrands nothing here — this names the
+// PLATFORM, not the host instance, and is the same string platform-identity's
+// manifest already carries).
+const CORE_PROJECT_NAME = 'Cloud Bongos';
+
+// Is `child` inside `parent`? Path-segment aware, so ".../modules-extra" never
+// counts as inside ".../modules".
+function isInside(child, parent) {
+  if (!child || !parent) return false;
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function samePath(a, b) {
+  if (!a || !b) return false;
+  return path.resolve(a) === path.resolve(b);
+}
+
+// Does this checkout's package.json name it as the core itself?
+function isCorePackageName(name) {
+  return CORE_PACKAGE_NAMES.includes(String(name || '').trim());
+}
+
+// WHICH TREE a discovered module ships from. `dir` is the module directory the
+// loader recorded (…/modules/<key>).
+//
+// The roots are DISTINCT in a split instance (core in node_modules/@bongos/core,
+// the instance at the repo root) — then this is a purely structural read and is
+// exactly right. They COINCIDE in a single checkout, where the same directory is
+// both roots and the structure can no longer answer it; there we fall back to
+// what the checkout says it is: the core repo's modules/ is the catalog, any
+// other checkout's is that instance's own.
+function deriveSource(dir, { coreRoot, instanceRoot, coreCheckout = false } = {}) {
+  if (coreRoot && instanceRoot && !samePath(coreRoot, instanceRoot)) {
+    if (isInside(dir, path.join(coreRoot, 'modules'))) return 'core';
+    return 'instance';
+  }
+  return coreCheckout ? 'core' : 'instance';
+}
+
+// Author + origin credit for one module (ADR 0107 §2 — a portable RECORD, never
+// a cross-GDS foreign key). This is the DISPLAY credit; the declared manifest
+// fields stay untouched beside it on every row, because "what the manifest says"
+// and "what the catalog shows" are different questions and callers need both
+// (tests/modules_route.mjs asserts provenance off the DECLARED origin).
+//
+// `inferred` is true when either value did not come from the manifest, so a
+// surface can mark it — an inferred credit must never read as a claim the author
+// typed, which is the whole point of an attribution record.
+function creditFor(manifest = {}, { source = 'instance', coreProjectName = CORE_PROJECT_NAME } = {}) {
+  const declaredAuthor = typeof manifest.author === 'string' && manifest.author.trim() ? manifest.author.trim() : null;
+  const declaredOrigin = typeof manifest.origin === 'string' && manifest.origin.trim() ? manifest.origin.trim() : null;
+  const fallback = source === 'core' ? coreProjectName : null;
+  return {
+    author: declaredAuthor || fallback,
+    origin: declaredOrigin || fallback,
+    inferred: !(declaredAuthor && declaredOrigin) && Boolean(fallback),
+  };
+}
+
+// One catalog row per discovered module. `loaded` is the loader's
+// discoverModules().loaded ([{ key, dir, manifest }]); `enabled` is the resolved
+// enablement map (src/modules.js modules()).
+function buildCatalog({
+  loaded = [],
+  enabled = {},
+  coreRoot,
+  instanceRoot,
+  coreCheckout = false,
+  coreProjectName = CORE_PROJECT_NAME,
+  ownProjectName = null,
+} = {}) {
+  return loaded
+    .map(({ key, dir, manifest = {} }) => {
+      const source = deriveSource(dir, { coreRoot, instanceRoot, coreCheckout });
+      const credit = creditFor(manifest, { source, coreProjectName });
+      return {
+        key,
+        title: manifest.title || key,
+        description: manifest.description || '',
+        source,
+        // The credit axis, unchanged from ADR 0107 §9 — kept alongside `source`
+        // so the hall's existing own/core-loaded split keeps working verbatim.
+        provenance: deriveProvenance(manifest.origin, ownProjectName),
+        enabled: enabled[key] === true,
+        default: manifest.default === true,
+        coreVersion: manifest.coreVersion || null,
+        contributes: manifest.contributes || {},
+        // DECLARED — exactly what module.json says (null when it says nothing).
+        author: manifest.author || null,
+        origin: manifest.origin || null,
+        // DISPLAY — never blank for a core-shipped module; `inferred` marks it.
+        credit,
+        license: manifest.license || null,
+        maintainer: manifest.maintainer || null,
+        maintenance: manifest.maintenance || null,
+      };
+    })
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}
+
+// The CATALOG proper — the core-shipped modules an instance can opt into
+// (ADR 0107 §6: accepted modules land default-off, every instance may enable).
+function catalogRows(rows = []) {
+  return rows.filter((r) => r.source === 'core');
+}
+
+// The instance's own modules — the other half of the Modules tab, and the pool
+// `bongos module submit` draws from.
+function instanceRows(rows = []) {
+  return rows.filter((r) => r.source === 'instance');
+}
+
+// Free-text browse over the fields a builder would actually search by. Empty
+// query returns everything (so a surface can pipe through it unconditionally).
+function searchCatalog(rows = [], query = '') {
+  const q = String(query || '').trim().toLowerCase();
+  if (!q) return rows;
+  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license]
+    .some((f) => f && String(f).toLowerCase().includes(q)));
+}
+
+function summarize(rows = []) {
+  const core = catalogRows(rows);
+  return {
+    total: rows.length,
+    catalog: core.length,
+    instance: rows.length - core.length,
+    enabled: rows.filter((r) => r.enabled).length,
+    catalog_enabled: core.filter((r) => r.enabled).length,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The one impure helper — resolve the roots + "is this the core checkout?"
+// ---------------------------------------------------------------------------
+
+// Fail-soft by construction: a missing/garbled package.json means "not the core
+// checkout", which degrades the catalog to "everything is this instance's own"
+// rather than crashing a page load or a CLI listing.
+function computeRoots({ coreRoot, instanceRoot } = {}) {
+  const cfg = require('../instance-config');
+  const core = coreRoot || cfg.resolveCoreRoot();
+  // NB resolveInstanceRoot() itself attempts a sync read of bongos.config.json —
+  // another reason this whole result is computed once, not per request.
+  const instance = instanceRoot || cfg.resolveInstanceRoot();
+  let name = null;
+  try { name = JSON.parse(fs.readFileSync(path.join(core, 'package.json'), 'utf8')).name; } catch { /* not the core, or unreadable */ }
+  return { coreRoot: core, instanceRoot: instance, coreCheckout: isCorePackageName(name), corePackageName: name || null };
+}
+
+// Cached singleton — the same lazy-memo + `_reset()` pattern loader.js uses for
+// `discovered()`, and for the same reason: this reads the filesystem, the answer
+// is invariant for the process lifetime (a running server's core root and
+// package identity cannot change under it), and `listModules()` is on the
+// request path for GET /modules. Recomputing two blocking readFileSync calls per
+// request to re-learn a constant is the kind of cost that only shows up under
+// load, so it is paid once at first use.
+//
+// An EXPLICIT root bypasses the cache entirely: a caller passing its own roots
+// is asking about a specific tree, not about this process, and must never get a
+// memoized answer for a different one (nor poison the cache for everyone else).
+let _rootsCache = null;
+function detectRoots({ coreRoot, instanceRoot } = {}) {
+  if (coreRoot || instanceRoot) return computeRoots({ coreRoot, instanceRoot });
+  return (_rootsCache ||= computeRoots());
+}
+
+// Drop the memo — for tests, and for any tool that relocates the roots mid-process.
+function _resetRoots() { _rootsCache = null; }
+
+module.exports = {
+  buildCatalog, catalogRows, instanceRows, searchCatalog, summarize,
+  deriveSource, creditFor, isCorePackageName, detectRoots, _resetRoots,
+  CORE_PACKAGE_NAMES, CORE_PROJECT_NAME,
+};

package/src/platform-server.js

@@ -60,12 +60,58 @@ const HOST = process.env.HOST || '127.0.0.1';
 // 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');
+// ── CONTENT-STAMPED STATIC ASSETS (task 1002766) ──
+// The landing HTML is `cf-cache-status: DYNAMIC` and never cached, but the
+// assets it references come back `Cache-Control: public, max-age=14400` — four
+// hours, Cloudflare's default Browser Cache TTL, not a header this app sets. So
+// after a deploy a RETURNING visitor gets brand-new markup styled by a
+// stylesheet up to four hours old: markup whose components that stylesheet has
+// never heard of. Measured live — a cached cosmos.css of 25,693 bytes with no
+// `.shell{` against 42,610 fresh — and again when the project card shipped and
+// rendered as an unstyled block at the foot of the page.
+//
+// A COLD visitor is unaffected, which is exactly what makes it easy to miss:
+// whoever deploys usually reloads in the browser holding the stale copy.
+//
+// Fixed by changing the URL rather than by fighting the header: a content hash
+// means a new core produces a new URL, so there is nothing to invalidate and no
+// Cloudflare purge token to hold (task 1002766 weighed both). Same `?v=<sha8>`
+// shape serve-internal.js already stamps onto the hall's own scripts.
+//
+// Stamped by RESOLUTION, not by a path allow-list: a URL is an asset if it
+// actually names a file under public-landing/. Routes (`/projects`, `/create`)
+// and API paths resolve to nothing and are left alone, so a new asset is
+// stamped the day it is added and nobody has to remember to list it.
+const _assetStamps = new Map();
+function assetStamp(url) {
+  if (!_assetStamps.has(url)) {
+    let v = '';
+    try {
+      const abs = path.resolve(LANDING_DIR, '.' + url);
+      // never let a template's own text walk out of the landing dir
+      if (abs.startsWith(LANDING_DIR + path.sep)) {
+        v = require('node:crypto').createHash('sha256')
+          .update(fs.readFileSync(abs)).digest('hex').slice(0, 8);
+      }
+    } catch { v = ''; }   // not a file → not an asset → no stamp
+    _assetStamps.set(url, v);
+  }
+  return _assetStamps.get(url);
+}
+const LOCAL_ASSET = /(href|src)="(\/[A-Za-z0-9._~/-]+\.[A-Za-z0-9]+)"/g;
+function stampAssets(html) {
+  return String(html).replace(LOCAL_ASSET, (m, attr, url) =>
+    assetStamp(url) ? `${attr}="${url}?v=${assetStamp(url)}"` : m);
+}
+
 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(stripApexOnly(fs.readFileSync(path.join(LANDING_DIR, file), 'utf8')));
+      // stamped LAST, so anything a later transform introduces is stamped too
+      html = stampAssets(injectBrandingGlobal(stripApexOnly(
+        fs.readFileSync(path.join(LANDING_DIR, file), 'utf8'))));
     } catch { /* absent → '' */ }
     _landingPages.set(file, html);
   }