@bongos/core 1.21.150 → 1.21.152

package/modules/ui-design/module.json

@@ -4,6 +4,7 @@
   "description": "The platform capability that lets any builder on any instance create and design good-looking, functional UIs in line with that instance's world (scoped with the owner 2026-08-28; task 1003324, ADR 0197). It ships METHOD and never a world: the neutral design contract of ADR 0081 with its tool adapters (Claude Design, Figma), their sync CLIs and the validator; the /design playbook for ui-discipline work; the look-before-you-ship kit (kit/) and the style library (styles/). The thirteen design-style skills that lived in skills/ are the opt-in design-styles module since task 1004470; /design reaches them when that module is on. The instance's world — its branding pack, config/design-tokens.*, config/design-sources.json and its DESIGN.md — stays in config/ and at the repo root as the host boundary this module reads and never owns (ADR 0062 §7). Cloud Bongos's own front door is this module's first customer, not its owner. default-on because every instance has a face. No routes, no migrations, no port: declaration-only like character-anim, so disabling it withdraws only the skills it contributes and touches no served surface.",
   "version": "1.0.0",
   "coreVersion": "^1.19.0",
+  "category": { "parent": "pages" },
   "default": true,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "skills": ["design", "design-sync", "figma-design-sync"], "disciplines": ["ui"] },

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.150",
+  "version": "1.21.152",
   "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/release-notes.json

@@ -9914,5 +9914,17 @@
       "id": "1004760",
       "text": "When a project's GitHub App isn't installed, a refused ship now says so and links the one-click install, instead of a bare 'not proven'."
     }
+  ],
+  "1.21.151": [
+    {
+      "id": "1004739",
+      "text": "The module test runner can now test against the private core: the server sends its own copy of the core into the private test repo, once per version."
+    }
+  ],
+  "1.21.152": [
+    {
+      "id": "1003784",
+      "text": "Every module now says which of the eight categories it belongs to, and the module list in the terminal and the hall's Modules tab both show it and let you search by it."
+    }
   ]
 }

package/scripts/gds/credential-presence.js

@@ -121,6 +121,16 @@ const CREDENTIALS = [
     names: ['METRICS_TOKEN'],
     purpose: 'bearer token for a remote Prometheus scrape of /metrics (src/bongos/metrics.js)',
   },
+  {
+    id: 'module-test-runner', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REPO', 'MODULE_TEST_TOKEN'],
+    purpose: "runs store modules' own tests in a separate private GitHub repo (scripts/gds/module-test-runner.js, blocker 1000195); unset leaves Tests pending",
+  },
+  {
+    id: 'module-test-ref', file: 'web.env', need: 'optional',
+    names: ['MODULE_TEST_REF'], notSecret: true,
+    purpose: "the test repo branch holding the module-tests workflow (default main)",
+  },
   {
     id: 'hub-signing-key', file: 'web.env', need: 'optional',
     names: ['HUB_SIGNING_KEY'], prefixed: true,

package/scripts/gds/module-test-runner/README.md

@@ -22,9 +22,9 @@ stays `pending`.
    MODULE_TEST_REPO=<owner>/<repo>
    MODULE_TEST_TOKEN=<the token>
    ```
-   Optional: `MODULE_TEST_CORE_REPO=<owner>/<name>` if the server's git `origin` is not
-   the public core repo, and `MODULE_TEST_REF=<branch>` if the test repo's workflow
-   lives on a branch other than `main`.
+   Optional: `MODULE_TEST_REF=<branch>` if the test repo's workflow lives on a
+   branch other than `main`. Nothing names the core repo: the runner gets the
+   core from the test repo itself (see the header of `module-test-runner.js`).
 
 On the runner, a module's tests run as a separate user with no admin rights and
 no network access (only the machine's own loopback), after the core is installed.

package/scripts/gds/module-test-runner/module-tests.yml

@@ -6,7 +6,8 @@
 # nothing here ever holds a DB credential or a control-plane secret.
 #
 # Two jobs on purpose: `fetch` can read the repo (where the tarball waits on a
-# throwaway branch) but runs no module code; `test` runs the module's code with a
+# throwaway branch, and the core snapshot on core/<sha>) but runs no module code;
+# `test` runs the module's code with a
 # GITHUB_TOKEN that has NO permissions, so a module that scrapes its token still
 # cannot read another run's tarball. Inside `test`, the module's code runs as an
 # unprivileged user with its network cut (see "Cut the network for module code").
@@ -19,8 +20,7 @@ on:
       version_id: { description: store_module_versions.id, required: true, type: string }
       module_key: { description: the module's key, required: true, type: string }
       nonce: { description: this run's nonce (32 hex), required: true, type: string }
-      core_repo: { description: owner/name of the public core, required: true, type: string }
-      core_ref: { description: the core commit to test against, required: true, type: string }
+      core_ref: { description: the core commit to test against (40 hex; branch core/<sha> holds it), required: true, type: string }
 
 permissions: {}
 
@@ -31,14 +31,21 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Check the inputs
-        env: { NONCE: "${{ inputs.nonce }}", VERSION_ID: "${{ inputs.version_id }}" }
+        env: { NONCE: "${{ inputs.nonce }}", VERSION_ID: "${{ inputs.version_id }}", CORE_REF: "${{ inputs.core_ref }}" }
         run: |
           [[ "$NONCE" =~ ^[0-9a-f]{32}$ ]] || { echo "bad nonce"; exit 1; }
           [[ "$VERSION_ID" =~ ^[0-9]+$ ]] || { echo "bad version id"; exit 1; }
+          [[ "$CORE_REF" =~ ^[0-9a-f]{40}$ ]] || { echo "bad core ref"; exit 1; }
       - uses: actions/checkout@v4
         with: { ref: "module-test/${{ inputs.nonce }}", path: tarball, persist-credentials: false }
+      # The core repo is private, so the control plane pushes a snapshot of the
+      # core it runs to core/<sha> in THIS repo (once per commit; task 1004739).
+      - uses: actions/checkout@v4
+        with: { ref: "core/${{ inputs.core_ref }}", path: core-snapshot, persist-credentials: false }
       - uses: actions/upload-artifact@v4
         with: { name: "tarball-${{ inputs.nonce }}", path: tarball/module.tgz, retention-days: 1 }
+      - uses: actions/upload-artifact@v4
+        with: { name: "core-${{ inputs.nonce }}", path: core-snapshot/core.tgz, retention-days: 1, compression-level: 0 }
 
   test:
     needs: fetch
@@ -46,12 +53,17 @@ jobs:
     permissions: {}
     timeout-minutes: 30
     steps:
-      - uses: actions/checkout@v4
-        with: { repository: "${{ inputs.core_repo }}", ref: "${{ inputs.core_ref }}", path: core, persist-credentials: false }
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
       - uses: actions/download-artifact@v4
         with: { name: "tarball-${{ inputs.nonce }}", path: in }
+      - uses: actions/download-artifact@v4
+        with: { name: "core-${{ inputs.nonce }}", path: core-in }
+      - name: Unpack the core
+        run: |
+          mkdir core
+          tar -xzf core-in/core.tgz -C core
+          rm -rf core-in
       - name: Install the core
         working-directory: core
         run: npm ci --no-audit --no-fund

package/scripts/gds/module-test-runner.js

@@ -13,18 +13,31 @@
 // THE ROUND TRIP. Nothing on the runner ever holds a DB credential:
 //   1. dispatch — the control plane pushes the version's tarball to a throwaway
 //      orphan branch `module-test/<nonce>` in the test repo and dispatches the
-//      workflow with { version_id, module_key, nonce, core_repo, core_ref }. The
-//      nonce goes into the pending Tests row's detail.runner.
+//      workflow with { version_id, module_key, nonce, core_ref }. The nonce goes
+//      into the pending Tests row's detail.runner.
 //   2. the run — a `fetch` job (contents: read, no module code) copies the tarball
-//      into the run as an artifact; a separate `test` job (permissions: {}) checks
-//      out the core at core_ref, runs module-assess-tests.js --tarball with
-//      MODULE_TEST_SANDBOX=1, and uploads the signal JSON as artifact
+//      and the core snapshot into the run as artifacts; a separate `test` job
+//      (permissions: {}) unpacks the core, runs module-assess-tests.js --tarball
+//      with MODULE_TEST_SANDBOX=1, and uploads the signal JSON as artifact
 //      module-tests-<version_id>-<nonce>.
 //   3. collect — the control plane PULLS: it finds the run whose run-name carries
 //      the pending row's nonce, takes only that run's artifact of that exact name,
 //      checks the payload names the same version and nonce, inserts the signal row
 //      itself, recomposes the score, and deletes the branch.
 //
+// WHY THE CORE TRAVELS AS A SNAPSHOT (task 1004739). The core repo is private, so
+// a runner whose token has no permissions cannot check it out by name. Before the
+// first run against a core commit, dispatch pushes `git archive` of that commit
+// (tracked files only, so never node_modules; minus the design mocks in
+// .impeccable/, which nothing runs) to an orphan branch `core/<sha>` in the test
+// repo, with the same token. Once per commit: a later dispatch finds the ref and
+// reuses it. The `fetch` job reads it with its contents: read token like the
+// tarball, so the `test` job still needs no permission and no repo name at all.
+// GitHub refuses a blob over 100 MB and the archive goes up base64-encoded (a
+// third bigger), so a snapshot over MAX_CORE_BYTES fails the dispatch loudly: a
+// dispatch that cannot be sent is logged as an error, not a warning, because the
+// version's Tests part then stays pending until someone fixes the cause.
+//
 // WHY A PER-RUN BRANCH, NOT A DOWNLOAD TICKET. A ticket would mean a new
 // unauthenticated route on the control plane (and a change to the protected
 // route-rank-check), i.e. a fresh inbound path to the server holding the secrets.
@@ -37,53 +50,50 @@
 // tests pass, so the score is never trust-critical; what this protects is the
 // secrets and other authors' code.
 //
-// Configured by three control-plane env vars (all unset = off; Tests then stays
-// `pending`, exactly as before this task):
+// Configured by control-plane env vars (repo + token unset = off; Tests then
+// stays `pending`, exactly as before this task):
 //   MODULE_TEST_REPO       owner/name of the private test repo
 //   MODULE_TEST_TOKEN      a fine-grained token scoped to ONLY that repo, with
 //                          Actions: read & write and Contents: read & write
-//   MODULE_TEST_CORE_REPO  owner/name of the public core the runner checks out
-//                          (default: this checkout's `origin`)
 //   MODULE_TEST_REF        the test repo branch holding the workflow (default main)
 //
 //   node scripts/gds/module-test-runner.js dispatch <store_module_versions.id>
 //   node scripts/gds/module-test-runner.js collect
 
 const fs = require('node:fs');
+const path = require('node:path');
 const crypto = require('node:crypto');
 const zlib = require('node:zlib');
-const { execFileSync } = require('node:child_process');
+const { execFile } = require('node:child_process');
+const { promisify } = require('node:util');
+
+const execFileAsync = promisify(execFile);
 
 const WORKFLOW_FILE = 'module-tests.yml';
 const BRANCH_PREFIX = 'module-test/';
+const CORE_BRANCH_PREFIX = 'core/';
 const API = 'https://api.github.com';
 // A run that has not finished this long after dispatch is recorded not_scored.
 const MAX_RUN_AGE_MS = 6 * 60 * 60_000;
 const MAX_SIGNAL_BYTES = 256 * 1024;
+// GitHub's blob limit is 100 MB and the snapshot is sent base64 (4/3 the size).
+const MAX_CORE_BYTES = 72 * 1024 * 1024;
+const CORE_ROOT = path.join(__dirname, '..', '..');
 const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const NONCE_RE = /^[0-9a-f]{32}$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
 
 const runName = (versionId, nonce) => `module-tests ${versionId} ${nonce}`;
 const artifactName = (versionId, nonce) => `module-tests-${versionId}-${nonce}`;
 
-function originRepo() {
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: __dirname, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    const m = url.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/);
-    return m ? m[1] : null;
-  } catch { return null; }
-}
-
 // The runner config, or null when it is not set up (the default: Tests stays pending).
-function runnerConfig(env = process.env, { origin = originRepo } = {}) {
+function runnerConfig(env = process.env) {
   const repo = (env.MODULE_TEST_REPO || '').trim();
   const token = (env.MODULE_TEST_TOKEN || '').trim();
   if (!repo || !token) return null;
   if (!REPO_RE.test(repo)) throw new Error(`MODULE_TEST_REPO must be owner/name, got "${repo}"`);
-  const coreRepo = (env.MODULE_TEST_CORE_REPO || '').trim() || origin();
-  if (!coreRepo || !REPO_RE.test(coreRepo)) throw new Error('MODULE_TEST_CORE_REPO is unset and the core repo could not be read from git origin');
   const ref = (env.MODULE_TEST_REF || '').trim() || 'main';
-  return { repo, token, coreRepo, ref };
+  return { repo, token, ref };
 }
 
 // One GitHub REST call. Resolves the parsed body (or null for 204); throws with
@@ -104,7 +114,54 @@ async function gh(cfg, method, urlPath, body, { fetchImpl = fetch } = {}) {
 // The commit the control plane is running, so the runner tests against the same core.
 function currentCoreRef() {
   const { buildInfo } = require('../../src/build-info');
-  return buildInfo().commit || 'main';
+  return buildInfo().commit;
+}
+
+// The core at one commit, as the tar.gz the runner unpacks. Async, so the web
+// process keeps serving while git compresses. It needs the commit in a git
+// checkout here: a vendored core (node_modules/@bongos/core) has none, and gets
+// an error that says so rather than git's own.
+async function archiveCore(sha) {
+  try {
+    const { stdout } = await execFileAsync('git', ['archive', '--format=tar.gz', sha, '--', '.', ':(exclude).impeccable', ':(exclude)node_modules'],
+      { cwd: CORE_ROOT, encoding: 'buffer', maxBuffer: 4 * MAX_CORE_BYTES });
+    return stdout;
+  } catch (e) {
+    const why = String((e.stderr && e.stderr.toString()) || e.message).trim().split('\n')[0];
+    throw new Error(`could not snapshot core commit ${sha.slice(0, 8)}: the core must run from a git checkout that holds it (a vendored install has none) — git said: ${why}`);
+  }
+}
+
+// Push a one-file orphan commit to a new branch of the test repo.
+async function pushOrphanBranch(cfg, branch, file, bytes, message, { fetchImpl } = {}) {
+  const r = `/repos/${cfg.repo}`;
+  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: bytes.toString('base64'), encoding: 'base64' }, { fetchImpl });
+  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: file, mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
+  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message, tree: tree.sha, parents: [] }, { fetchImpl });
+  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+}
+
+// Make sure branch core/<sha> holds the core snapshot, pushing it only the first
+// time. Resolves { branch, pushed }. Two dispatches racing on a new commit both
+// push; the loser's ref create is refused (422) and it uses the winner's.
+async function ensureCoreSnapshot(cfg, sha, { fetchImpl, archive = archiveCore } = {}) {
+  if (!SHA_RE.test(sha || '')) throw new Error(`the running core commit is unknown ("${sha || ''}"), so there is no core to test against`);
+  const branch = `${CORE_BRANCH_PREFIX}${sha}`;
+  try {
+    await gh(cfg, 'GET', `/repos/${cfg.repo}/git/ref/heads/${branch}`, null, { fetchImpl });
+    return { branch, pushed: false };
+  } catch (e) { if (e.status !== 404) throw e; }
+  const tgz = await archive(sha);
+  if (tgz.length > MAX_CORE_BYTES) {
+    throw new Error(`the core snapshot for ${sha.slice(0, 8)} is ${(tgz.length / 1048576).toFixed(1)} MB, over the ${MAX_CORE_BYTES / 1048576} MB the test repo can take; trim what archiveCore sends in scripts/gds/module-test-runner.js`);
+  }
+  try {
+    await pushOrphanBranch(cfg, branch, 'core.tgz', tgz, `core snapshot ${sha}`, { fetchImpl });
+  } catch (e) {
+    if (e.status === 422) return { branch, pushed: false };
+    throw e;
+  }
+  return { branch, pushed: true };
 }
 
 function readVersionTarball(ver) {
@@ -112,27 +169,26 @@ function readVersionTarball(ver) {
   return fs.promises.readFile(versionArtifactFile(ver));
 }
 
-// Push the tarball to a throwaway orphan branch and dispatch the workflow.
-// Resolves the runner record kept in the pending row: { nonce, branch, dispatched_at }.
-async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, now = () => new Date() } = {}) {
+// Make sure the core snapshot is there, push the tarball to a throwaway orphan
+// branch, and dispatch the workflow. Resolves the runner record kept in the
+// pending row: { nonce, branch, core_ref, dispatched_at }.
+async function dispatchRun(ver, { cfg, fetchImpl, readTarball = readVersionTarball, coreRef = currentCoreRef, archive, now = () => new Date() } = {}) {
+  const sha = coreRef();
+  await ensureCoreSnapshot(cfg, sha, { fetchImpl, archive });
   const tgz = await readTarball(ver);
   const nonce = crypto.randomBytes(16).toString('hex');
   const branch = `${BRANCH_PREFIX}${nonce}`;
-  const r = `/repos/${cfg.repo}`;
-  const blob = await gh(cfg, 'POST', `${r}/git/blobs`, { content: tgz.toString('base64'), encoding: 'base64' }, { fetchImpl });
-  const tree = await gh(cfg, 'POST', `${r}/git/trees`, { tree: [{ path: 'module.tgz', mode: '100644', type: 'blob', sha: blob.sha }] }, { fetchImpl });
-  const commit = await gh(cfg, 'POST', `${r}/git/commits`, { message: `module tests: version ${ver.id}`, tree: tree.sha, parents: [] }, { fetchImpl });
-  await gh(cfg, 'POST', `${r}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.sha }, { fetchImpl });
+  await pushOrphanBranch(cfg, branch, 'module.tgz', tgz, `module tests: version ${ver.id}`, { fetchImpl });
   try {
-    await gh(cfg, 'POST', `${r}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
+    await gh(cfg, 'POST', `/repos/${cfg.repo}/actions/workflows/${WORKFLOW_FILE}/dispatches`, {
       ref: cfg.ref || 'main',
-      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_repo: cfg.coreRepo, core_ref: coreRef() },
+      inputs: { version_id: String(ver.id), module_key: ver.module_key, nonce, core_ref: sha },
     }, { fetchImpl });
   } catch (e) {
     await deleteBranch(cfg, branch, { fetchImpl });
     throw e;
   }
-  return { nonce, branch, dispatched_at: now().toISOString() };
+  return { nonce, branch, core_ref: sha, dispatched_at: now().toISOString() };
 }
 
 async function deleteBranch(cfg, branch, { fetchImpl } = {}) {
@@ -162,7 +218,7 @@ async function maybeDispatch(ver, { db, env = process.env, log = console, ...opt
   if (newest && !(newest.outcome === 'pending' && !(newest.detail && newest.detail.runner))) return null;
   let runner;
   try { runner = await dispatchRun(ver, { cfg, ...opts }); }
-  catch (e) { log.warn(`module test run for version ${ver.id} not dispatched: ${e.message}`); return null; }
+  catch (e) { log.error(`module test run for version ${ver.id} not dispatched: ${e.message}`); return null; }
   await db.query(
     `INSERT INTO module_assessment_signals (version_id, part, outcome, score, sample_size, reason, detail)
      VALUES ($1, 'tests', 'pending', NULL, NULL, $2, $3)`,
@@ -355,4 +411,4 @@ if (require.main === module) {
   main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (e) => { console.error(e.stack || e.message); process.exitCode = 1; });
 }
 
-module.exports = { runnerConfig, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };
+module.exports = { runnerConfig, archiveCore, maybeDispatch, collectResults, sweepTick, readZipEntry, validateSignal, runName, artifactName };

package/scripts/gds/module.js

@@ -452,14 +452,16 @@ function formatCatalog(rows, { catalogOnly = false, query = '', core = null, del
     return out.join('\n');
   }
 
-  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('AUTHOR', 20)}${pad('ORIGIN', 26)}${pad('LICENSE', 12)}UPKEEP`);
+  out.push(`  ${pad('', 5)}${pad('KEY', 20)}${pad('VERSION', 9)}${pad('SOURCE', 10)}${pad('CATEGORY', 28)}${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') + (delisted.has(r.key) ? ' · DELISTED' : '');
-    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${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}`);
+    // The parent key, plus the sub-category once one is approved (ADR 0342).
+    const cat = r.category ? r.category.parent + (r.category.sub ? `/${r.category.sub}` : '') : '—';
+    out.push(`  ${pad(mark, 5)}${pad(clip(r.key, 19), 20)}${pad(clip(r.version || '—', 8), 9)}${pad(r.source, 10)}${pad(clip(cat, 27), 28)}${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');

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.150'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.152'; // 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('discord'); log.info('mounted');

package/src/module-loader/catalog.js

@@ -30,6 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { deriveProvenance } = require('./provenance');
+const { CATEGORY_PARENTS } = require('./manifest-schema');
 
 // 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
@@ -99,6 +100,17 @@ function creditFor(manifest = {}, { source = 'instance', coreProjectName = CORE_
   };
 }
 
+// Where a module is browsed (ADR 0342): its parent key, that parent's label, and its
+// sub-category key — or null when the manifest declares none. The label is resolved
+// HERE so the hall and the CLI never keep their own copy of the parent list. A parent
+// outside the closed list cannot reach this (the validator refuses it), so an unknown
+// one is null rather than shown under a label nobody chose.
+function categoryFor(manifest = {}) {
+  const c = manifest.category;
+  if (!c || typeof c !== 'object' || !Object.hasOwn(CATEGORY_PARENTS, c.parent)) return null;
+  return { parent: c.parent, parentTitle: CATEGORY_PARENTS[c.parent], sub: c.sub || null };
+}
+
 // 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()).
@@ -138,6 +150,7 @@ function buildCatalog({
         license: manifest.license || null,
         maintainer: manifest.maintainer || null,
         maintenance: manifest.maintenance || null,
+        category: categoryFor(manifest),
       };
     })
     .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
@@ -160,7 +173,8 @@ function instanceRows(rows = []) {
 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]
+  return rows.filter((r) => [r.key, r.title, r.description, r.credit.author, r.credit.origin, r.license,
+    r.category && r.category.parentTitle, r.category && r.category.sub]
     .some((f) => f && String(f).toLowerCase().includes(q)));
 }
 

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

@@ -53,6 +53,10 @@
 //                                       //   actually declares in `contributes`, and every entry must be
 //                                       //   one it actually lists there — a typo'd exemption is an error,
 //                                       //   never a silent pass.
+//     "category": {                     // OPTIONAL. Where the module is browsed and ranked (ADR 0342).
+//       "parent": "money",              //   REQUIRED in-block: one of the eight CATEGORY_PARENTS keys.
+//       "sub":    "stripe-payments"     //   OPTIONAL. An approved sub-category key — the comparable set
+//     },                                //   the store's cap of ten counts within; absent while pending.
 //     "howto": {                        // OPTIONAL. Extras beside the module's HOWTO.md (ADR 0347 D3).
 //       "artifactUrl": "https://claude.ai/…" //   A Claude page with the same how-to, shown as an extra,
 //     },                                //   never graded and never required — the file is the how-to.
@@ -106,6 +110,24 @@ const SPEND_KEYS = ['requiresPayer'];
 // The `howto` block (ADR 0347 D3) — closed for the same reason; not exported either.
 const HOWTO_KEYS = ['artifactUrl'];
 
+// The eight fixed parent categories (ADR 0342 D1), key → the label a catalog shows.
+// A parent is for browsing only: the cap of ten counts within a SUB-category, never a
+// parent (D2). The list is closed so a typo'd "monye" fails loud rather than filing
+// the module under a ninth parent nobody browses; changing it needs a new ADR.
+// `sub` is shape-checked only — which sub-categories are approved is ledger state
+// (task 1004355), not something a pure validator can know.
+const CATEGORY_PARENTS = Object.freeze({
+  work: 'Work & planning',
+  people: 'Team & people',
+  quality: 'Quality & review',
+  money: 'Money',
+  communication: 'Communication',
+  pages: 'Pages & design',
+  hosting: 'Hosting & deploy',
+  knowledge: 'Knowledge',
+});
+const CATEGORY_KEYS = ['parent', 'sub'];
+
 // An https link on claude.ai (or a subdomain). Shape only: the store never fetches it.
 function isClaudeArtifactUrl(v) {
   if (!isStr(v)) return false;
@@ -320,6 +342,23 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional category (ADR 0342) ---
+  if ('category' in obj) {
+    const c = obj.category;
+    const parents = Object.keys(CATEGORY_PARENTS);
+    if (!isObj(c)) E('category: must be an object (e.g. { "parent": "money", "sub": "stripe-payments" })');
+    else {
+      for (const k of Object.keys(c)) {
+        if (!CATEGORY_KEYS.includes(k)) E(`category.${k}: unknown key (allowed: ${CATEGORY_KEYS.join(', ')}) — a module has exactly one sub-category (ADR 0342 D4)`);
+      }
+      if (!isStr(c.parent)) E(`category.parent: required — one of ${parents.join(', ')}`);
+      else if (!parents.includes(c.parent)) E(`category.parent: "${c.parent}" is not one of ${parents.join(', ')} (ADR 0342 D1)`);
+      if ('sub' in c && (!isStr(c.sub) || !KEY_RE.test(c.sub))) {
+        E('category.sub: must be a sub-category key (lowercase kebab-case) when present — leave it out while a new one is pending approval');
+      }
+    }
+  }
+
   // --- optional how-to extras (ADR 0347 D3) ---
   if ('howto' in obj) {
     const h = obj.howto;
@@ -370,5 +409,5 @@ function assertValidManifest(obj, label = 'module.json') {
 
 module.exports = {
   validateManifest, assertValidManifest, declaredEntries, entryLabel, KEY_RE, ALLOWED_CONTRIBUTES, ARRAY_OF_STRING_KEYS, ATTRIBUTION_KEYS,
-  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES,
+  MAINTENANCE_STATUSES, MAINTENANCE_KEYS, SUNSET_STATUSES, CATEGORY_PARENTS,
 };

package/tests/hall_catalog_world.mjs

@@ -58,7 +58,7 @@ test('modules: the row is the oversight row — title with the mono key, clamped
   assert.match(js, /<span class="ov-row__title">\$\{escapeHtml\(m\.title \|\| m\.key\)\}<span class="ov-mono">\$\{escapeHtml\(m\.key\)\}<\/span>/, 'the key rides inside the title in mono');
   assert.match(js, /class="ov-row__sub mod-row__desc"/, 'the description is the sub line');
   assert.match(js, /<details class="mod-more"/, 'a details disclosure opens the rest');
-  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
+  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{categoryFact\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, (task 1003784) the category, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
   assert.match(js, /<div class="ov-row__right mod-row__right">\$\{rightHtml\(m\)\}<\/div>/, 'the right column is one function');
   const css = read('modules.css');
   assert.match(css, /\.mod-row__desc \{[^}]*-webkit-line-clamp: 2/, 'the description clamps to two lines');
@@ -84,6 +84,9 @@ test('modules: upkeep colours the exception — undeclared is the warn pill, mai
   assert.match(js, /<span class="ov-fact">upkeep <b>\$\{escapeHtml\(status\)\}<\/b><\/span>/, 'a maintained module reads as a plain fact');
   assert.match(js, /fact-pill fact-pill--info">core-loaded</, 'core-loaded is the info pill');
   assert.match(js, /<span class="fact-chip">\$\{escapeHtml\(m\.license\)\}<\/span>/, 'the licence is a chip');
+  assert.match(js, /<span class="ov-fact">in <b>\$\{escapeHtml\(c\.parentTitle\)\}<\/b>\$\{sub\}<\/span>/,
+    'the category is a plain fact, labelled from the server row (task 1003784)');
+  assert.match(js, /cat\.parentTitle, cat\.sub\]/, 'the hall search covers the category, as searchCatalog does');
 });
 
 test('modules: the kit filter bar carries the search and a state lens, and the empty state is the kit\'s', () => {

package/tests/module_catalog.mjs

@@ -330,3 +330,37 @@ test('detectRoots: an explicit root bypasses the memo in both directions', () =>
   // …nor poison the memo for every later caller that asks about this process.
   assert.equal(catalog.detectRoots(), cached);
 });
+
+// ---------------------------------------------------------------------------
+// category — the ADR 0342 field, carried by the ONE model to both surfaces (task 1003784)
+// ---------------------------------------------------------------------------
+
+const categorized = () => catalog.buildCatalog({
+  loaded: [
+    loadedIn(CORE, 'economy', { category: { parent: 'money' } }),
+    loadedIn(CORE, 'discord', { category: { parent: 'communication', sub: 'team-chat' } }),
+    loadedIn(INST, 'game'),
+  ],
+  coreRoot: CORE, instanceRoot: INST,
+});
+
+test('buildCatalog: a row carries its category with the parent label; none declared is null', () => {
+  const byKey = Object.fromEntries(categorized().map((r) => [r.key, r]));
+  assert.deepEqual(byKey.economy.category, { parent: 'money', parentTitle: 'Money', sub: null });
+  assert.deepEqual(byKey.discord.category, { parent: 'communication', parentTitle: 'Communication', sub: 'team-chat' });
+  assert.equal(byKey.game.category, null);
+});
+
+test('searchCatalog: finds a module by its category label or sub-category', () => {
+  const rows = categorized();
+  assert.deepEqual(catalog.searchCatalog(rows, 'money').map((r) => r.key), ['economy']);
+  assert.deepEqual(catalog.searchCatalog(rows, 'team-chat').map((r) => r.key), ['discord']);
+});
+
+test('formatCatalog: the CATEGORY column shows parent/sub, and a dash when none is declared', () => {
+  const out = mod.formatCatalog(categorized());
+  assert.match(out, /CATEGORY/);
+  assert.match(out, /discord\s+\S+\s+core\s+communication\/team-chat/);
+  assert.match(out, /economy\s+\S+\s+core\s+money\s/);
+  assert.match(out, /game\s+\S+\s+instance\s+—\s/);
+});

package/tests/module_manifest.mjs

@@ -392,3 +392,39 @@ test('howto.artifactUrl: anything but an https claude.ai link is refused, as is
     .some((e) => e.startsWith('howto.artifactURL: unknown key')));
   assert.equal(validateManifest({ ...baseManifest(), howto: 'https://claude.ai/x' }).valid, false);
 });
+
+// --- category (ADR 0342, task 1003784) ---
+
+test('category: optional; a known parent, with or without a sub-category, is accepted', () => {
+  assert.equal(validateManifest(baseManifest()).valid, true, 'a manifest with no category still validates');
+  for (const category of [{ parent: 'money' }, { parent: 'communication', sub: 'team-chat' }]) {
+    const r = validateManifest({ ...baseManifest(), category });
+    assert.equal(r.valid, true, `${JSON.stringify(category)}: ${r.errors.join('; ')}`);
+  }
+});
+
+test('category: a parent outside the eight, a missing parent, a bad sub or an unknown key fails loud', () => {
+  const errs = (category) => validateManifest({ ...baseManifest(), category }).errors;
+  assert.ok(errs({ parent: 'monye' }).some((e) => e.startsWith('category.parent: "monye" is not one of')), 'a typo names the list');
+  assert.ok(errs({ sub: 'stripe-payments' }).some((e) => e.startsWith('category.parent: required')));
+  assert.ok(errs({ parent: 'money', sub: 'Stripe Payments' }).some((e) => e.startsWith('category.sub:')));
+  assert.ok(errs({ parent: 'money', sub: '' }).some((e) => e.startsWith('category.sub:')));
+  assert.ok(errs({ parent: 'money', subs: ['a', 'b'] }).some((e) => e.startsWith('category.subs: unknown key')),
+    'one sub-category per module (D4) — a second field is a typo, not a list');
+  assert.equal(validateManifest({ ...baseManifest(), category: 'money' }).valid, false);
+});
+
+test('category: the eight parents are exactly ADR 0342 D1', () => {
+  const { CATEGORY_PARENTS } = require(path.join(ROOT, 'src', 'module-loader', 'manifest-schema.js'));
+  assert.deepEqual(Object.keys(CATEGORY_PARENTS),
+    ['work', 'people', 'quality', 'money', 'communication', 'pages', 'hosting', 'knowledge']);
+});
+
+test('category: every bundled module declares one (core modules get categories too, ADR 0342)', async () => {
+  const fs = await import('node:fs');
+  const dir = path.join(ROOT, 'modules');
+  const missing = fs.readdirSync(dir)
+    .filter((k) => fs.existsSync(path.join(dir, k, 'module.json')))
+    .filter((k) => !JSON.parse(fs.readFileSync(path.join(dir, k, 'module.json'), 'utf8')).category);
+  assert.deepEqual(missing, [], `declare "category": { "parent": … } in: ${missing.join(', ')}`);
+});