@bongos/core 1.23.1 → 1.23.2

package/docs/module-api-changelog.md

@@ -3219,5 +3219,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         so MINOR. The browser twin is window.OTB.sleep.
   1.23.1 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.23.0 with no explicit bump. run 40270556091. (task 1002620)
+  1.23.2 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.1 with no explicit bump. run 40399986777. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -399,6 +399,7 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/bo
 - **Sorting by a part** (task 1003800). `GET /store/modules?sort=<part>` orders the listed modules by one part a buyer cares about: `tests`, `install`, `reliability`, `tester_feedback` or `docs` (the response lists them as `sort_parts`, and says which one it applied as `sort`). Modules with a score for that part come first, highest first; a tie goes to the higher overall score, then the module key. A module with no score for that part goes last, so missing data never wins or loses a place on its own. New modules are not sorted: they are never ranked. Any other `sort` value is refused with a 400. Without `sort`, the listed modules are in the ranking below; New stays in key order. The rule is `sortByPart` in `src/bongos/module-listing.js`.
 - **The ranking, and a maximum price** (task 1003808, owner decision 2026-10-23). Without `sort`, listed modules are ranked **quality first**: highest overall score first; between equal scores, free modules first, then the lowest cash price, then the lowest credit price, then the module key. Price never buys a better place, it only orders modules the score could not tell apart (and it is never an input to the score, ADR 0343 D6). The response states the rule as `ranking`, and each entry carries its current `price` (`cents`, `credits`, `free`). A buyer may add `?max_cents=` and/or `?max_credits=` (whole numbers, 0 or more): modules that cost more are left out of both lists, free modules always stay, and a priced module stays when it is offered at or under a cap the buyer set. The applied caps come back as `max_price`. The rules are `rankListed` and `withinMaxPrice` in `src/bongos/module-listing.js`.
 - **Why a module is not listed** (task 1003810). `GET /store/modules/:key/listing` says where one module stands, judging the same newest version the catalog does: `listed` (true or false), a `reason` (`not_assessed`, `security_not_passed`, `no_score`, `below_floor`, `delisted`, `no_version`, `new` or `at_or_above_floor`), `why` in a sentence and `next_step` saying what would change it. A failed Security gate is told apart from one that has not finished, and names what it found to the module's author only (to anyone else it would point at a weakness not fixed yet); below the floor names the score, the floor and the weakest parts. It carries the same `parts`, `strengths`, `weaknesses` and `unmeasured` as the catalog, plus `security`. Any signed-in builder can read it. Being past the cap of ten per category will be a reason of its own once the cap exists (task 1003809). The rule is `explainPlacement` in `src/bongos/module-listing.js`.
+- **Sub-categories are approved before they count** (task 1004355, ADR 0342 D3). A module names `category: { parent, sub }` in `module.json`; `GET /store/subcategories` lists the approved ones under each of the eight parents. A `sub` the store has not seen under that parent is **proposed** at publish (labelled from its key) and the publish answer's `category` says so (`status: "proposed"`, `live: false`): until a Metic+ person decides, the module sits under its parent only and counts toward no cap. The review queue (`GET /store/subcategories/queue`, atom `module.subcategory.review`, metic + archon via `government_033`) shows each proposal with the modules that named it and its near-duplicate names; `POST /store/subcategories/:id/approve { label?, sub_key? }` makes it live, renamed first if asked (a rename onto an existing key is refused — merge instead), and `POST /store/subcategories/:id/merge { into }` folds it into an approved one and moves its modules there. A later publish naming a merged key lands on its target. Where a module sits is `store_module_categories` (core_278), apart from the manifest; `readModuleCategories` in `src/bongos/module-subcategories.js` is the read the cap uses.
 - **Testing new versions first** (task 1003802, [ADR 0344](adr/0344-a-tester-is-a-project-that-opts-in-once.md) D1). A project can choose to get each new version of its modules before everyone else. It is the project that opts in, never one builder for someone else's project, and never by default. `GET /modules/testing` returns `{ tester, general_only, updated_at, updated_by }` to anyone signed in. `POST /modules/testing { tester: true|false }` switches it, and `POST /modules/:key/general-only { general_only: true|false }` keeps one module on the versions everyone gets while the rest are tested. Both writes take the `module.enable` permission, the same one that turns modules on and off. Both are reversible: switching testing off puts the project back on general versions from its next update, and a module's "general only" mark is kept if testing is switched off and on again. The choice is stored in the project's own settings (`modules.tester`, `modules.general_only`); anything that cannot be read counts as not testing. `testsVersionsOf` in `src/bongos/module-testing.js` is the one answer to "does this project get the tester version of this module", which installs and updates use (task 1003805). The hall's Modules tab has the switch in its "Testing new versions" group, and the general-only control in each module's details.
 
 ### 7. Install from the store

package/migrations/core_280_store_subcategories.sql

@@ -0,0 +1,58 @@
+-- core_280_store_subcategories.sql — the store's sub-categories and the queue that
+-- approves them (task 1004355, ADR 0342 D3).
+--
+-- WHAT IT IS. A module sits under one of eight fixed parents (ADR 0342 D1) and, once
+-- approved, one narrow sub-category: the comparable set the cap of ten and the
+-- ranking count within (D2). An author proposes a sub-category when publishing; it
+-- is NOT live until a Metic+ person approves it (optionally renaming it) or merges
+-- it into an existing one. Until then the module is listed under its parent only.
+--
+--   store_subcategories       one row per (parent, sub_key). status proposed |
+--                             approved | merged. A merged row points at the
+--                             sub-category it was merged into, so a later publish
+--                             naming the old key lands on the right one.
+--   store_module_categories   where each store module sits now: its parent and the
+--                             sub-category it named (proposed or approved). A merge
+--                             moves every module of the merged row here. Kept apart
+--                             from the published manifest, which never changes.
+--
+-- The parent list matches CATEGORY_PARENTS in src/module-loader/manifest-schema.js;
+-- changing it needs a new ADR (D1).
+--
+-- Additive only (two new tables), so forward-safe. Idempotent: safe to re-run.
+-- Approved by the owner on 2026-10-15.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS store_subcategories (
+  id            bigserial PRIMARY KEY,
+  parent        text NOT NULL
+                  CHECK (parent IN ('work', 'people', 'quality', 'money', 'communication', 'pages', 'hosting', 'knowledge')),
+  sub_key       text NOT NULL
+                  CHECK (sub_key ~ '^[a-z][a-z0-9-]*$'),
+  label         text NOT NULL CHECK (length(label) BETWEEN 1 AND 80),
+  status        text NOT NULL DEFAULT 'proposed'
+                  CHECK (status IN ('proposed', 'approved', 'merged')),
+  proposed_by   bigint REFERENCES builders(id),
+  decided_by    bigint REFERENCES builders(id),
+  decided_at    timestamptz,
+  merged_into   bigint REFERENCES store_subcategories(id),
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (parent, sub_key),
+  CHECK ((status = 'merged') = (merged_into IS NOT NULL)),
+  CHECK ((status = 'proposed') = (decided_at IS NULL))
+);
+
+CREATE INDEX IF NOT EXISTS idx_store_subcategories_status ON store_subcategories (status);
+
+CREATE TABLE IF NOT EXISTS store_module_categories (
+  module_key      text PRIMARY KEY REFERENCES store_modules(module_key),
+  parent          text NOT NULL
+                    CHECK (parent IN ('work', 'people', 'quality', 'money', 'communication', 'pages', 'hosting', 'knowledge')),
+  subcategory_id  bigint REFERENCES store_subcategories(id),
+  updated_at      timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_store_module_categories_sub ON store_module_categories (subcategory_id);
+
+COMMIT;

package/modules/government/catalog.js

@@ -235,6 +235,9 @@ const PERMISSIONS = [
   // Re-run a store version's automatic assessment (task 1003796, ADR 0359). Never a
   // hand-set score: the owner ruled a person may ask for a re-check, not change the number.
   { key: 'module.assessment.rerun', system: false, floor: 'metic', guards: 'POST /store/modules/:key/versions/:version/reassess' },
+  // Review the store's proposed sub-categories (task 1004355, ADR 0342 D3): approve,
+  // rename then approve, or merge into an existing one (a merge moves its modules).
+  { key: 'module.subcategory.review', system: false, floor: 'metic', guards: 'GET /store/subcategories/queue, POST /store/subcategories/:id/approve, POST /store/subcategories/:id/merge' },
   // Take a module out of the store (task 1003797, ADR 0338 D2). Stops new installs,
   // versions and downloads; never reaches an instance that already holds it.
   { key: 'module.delist', system: false, floor: 'metic', guards: 'POST /store/modules/:key/delist, POST /store/modules/:key/versions/:version/release (a version the promotion gate held on tester — task 1003804)' },

package/modules/government/migrations/government_034_module_subcategory_review.sql

@@ -0,0 +1,35 @@
+-- government_034_module_subcategory_review.sql — grant the new
+-- `module.subcategory.review` atom to Metic and Archon (task 1004355, ADR 0342 D3).
+--
+-- WHAT IT IS. An author proposes a store sub-category when publishing; a Metic+
+-- person approves it (optionally renaming it) or merges it into an existing one.
+-- Merging moves every module that named it. Approving is what makes a set of
+-- modules "comparable" for the cap of ten, so it is Metic+, not every builder.
+--
+-- WHY THIS FILE EXISTS. RANK_SEED is derived from the catalog's floors, and the
+-- drift guard (tests/government_seed.mjs) compares it against the union of the
+-- run-once seed plus every later grant migration, per rank. A metic-floor key is
+-- held by metic AND archon, so both are granted here.
+--
+-- Additive only: one new permission key granted to two ranks; nothing is revoked.
+-- Approved by the owner on 2026-10-15 (with the sub-category table, core_280).
+-- Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- The `SELECT '<rank>', unnest(ARRAY[…])` shape is load-bearing: the drift guard
+-- scans for it literally.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'module.subcategory.review'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'module.subcategory.review'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.23.1",
+  "version": "1.23.2",
   "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

@@ -10389,5 +10389,11 @@
       "id": "1004893",
       "text": "The ~30 copy-pasted \"wait a moment\" helpers across the codebase now all use one shared helper (one for the browser, one for the server), and a fitness check stops new copies from creeping back in. Nothing users see changes."
     }
+  ],
+  "1.23.2": [
+    {
+      "id": "1004355",
+      "text": "Module authors can now propose a new store sub-category when they publish, and Metic+ reviewers approve, rename or merge it, with look-alike names shown side by side so duplicates don't split the rankings."
+    }
   ]
 }

package/src/bongos/module-store.js

@@ -25,6 +25,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { parseVersion, cmp } = require('../module-loader/semver');
 const { KEY_RE } = require('../module-loader/manifest-schema');
+const { recordPublishCategory } = require('./module-subcategories');
 
 // Where the store lives: <INSTANCE ROOT>/var/module-store (task 1004399).
 //
@@ -172,11 +173,11 @@ function relativeArtifactPath(file, { dir = storeDir() } = {}) {
 const PUBLISH_CHANNEL = 'tester';
 
 // One transaction. `db` is a pg Pool (anything with connect()). Returns
-// { ok: true, version: row, created: bool, channel } or { ok: false, code, message, status }.
+// { ok: true, version: row, created: bool, channel, category } or { ok: false, code, message, status }.
 async function publishVersion(input, { db, beforeCommit } = {}) {
   const {
     key, title, description, version, coreVersion, manifest,
-    treeSha256, tarballSha256, bytes, artifactPath: relPath, builderId,
+    treeSha256, tarballSha256, bytes, artifactPath: relPath, builderId, category,
   } = input;
   const pool = db || require('./pool').pool;
   const client = await pool.connect();
@@ -229,11 +230,15 @@ async function publishVersion(input, { db, beforeCommit } = {}) {
       `INSERT INTO store_module_version_channels (version_id, channel, reason, set_by)
        VALUES ($1, $2, $3, $4)`,
       [row.id, PUBLISH_CHANNEL, 'new_version', builderId]);
+    // Where the module sits, on the same transaction (task 1004355, ADR 0342 D3): a
+    // sub-category the store has not seen is proposed here and is not live until a
+    // Metic+ person approves it. A version naming no category leaves it where it was.
+    const placed = category ? await recordPublishCategory(client, { key, category, builderId }) : null;
     // Put the tarball in place while the row is still uncommitted: if this throws,
     // the catch below rolls the row back, so the two can never disagree.
     if (beforeCommit) await beforeCommit();
     await client.query('COMMIT');
-    return { ok: true, created, version: row, channel: PUBLISH_CHANNEL };
+    return { ok: true, created, version: row, channel: PUBLISH_CHANNEL, category: placed };
   } catch (e) {
     try { await client.query('ROLLBACK'); } catch { /* the connection may be gone */ }
     // Two publishes of the same version racing past the check: the UNIQUE wins.

package/src/bongos/module-subcategories.js

@@ -0,0 +1,316 @@
+'use strict';
+
+// src/bongos/module-subcategories.js — the store's sub-categories and the queue that
+// approves them (task 1004355, ADR 0342 D3; tables: core_280).
+//
+// A module sits under one of eight fixed parents and, once approved, one narrow
+// sub-category: the comparable set the cap of ten and the ranking count within (D2).
+// The author names a sub-category in module.json (`category: { parent, sub }`); a
+// key the store has never seen under that parent is PROPOSED at publish and is not
+// live until a Metic+ person approves it (optionally renaming it) or merges it into
+// an existing one (`module.subcategory.review`). Until then the module is listed
+// under its parent only and counts toward no cap.
+//
+// Where a module sits lives in store_module_categories, apart from the published
+// manifest (which never changes), so a merge can move modules without touching a
+// version. A merged row keeps a pointer to where it went, so a later publish naming
+// the old key lands on the right sub-category instead of proposing it again.
+
+const { CATEGORY_PARENTS } = require('../module-loader/manifest-schema');
+
+// How many pending proposals one queue read returns, oldest first. Each is compared
+// against every live sub-category for near-duplicates, so the read is bounded by
+// this times the live count; the rest wait for the next page of decisions.
+const QUEUE_LIMIT = 100;
+
+// The label a proposal starts with: its key in words ("stripe-payments" → "Stripe
+// payments"). The approver can rename it; the author never types a free-text label.
+function labelFromKey(subKey) {
+  const words = String(subKey || '').split('-').filter(Boolean).join(' ');
+  return words ? words[0].toUpperCase() + words.slice(1) : '';
+}
+
+// A label as a sub key: lowercase kebab-case, the shape manifest-schema checks.
+function subKeyFromLabel(label) {
+  return String(label || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').replace(/^[^a-z]+/, '');
+}
+
+// ---------------------------------------------------------------------------
+// Near-duplicates — the point of the queue (ADR 0342 D3)
+// ---------------------------------------------------------------------------
+//
+// "Stripe", "Stripe payments" and "Payments (Stripe)" must sit beside each other in
+// front of the approver. Two names are near when their significant words overlap by
+// at least half (Jaccard over word sets, a plural "s" dropped) or, as whole strings,
+// are within two edits of each other (a typo: "stirpe"). Filler words never count.
+const FILLER = new Set(['and', 'the', 'of', 'for', 'a', 'an', 'to', 'with', 'in', 'on']);
+
+function nameWords(name) {
+  return new Set(String(name || '').toLowerCase().split(/[^a-z0-9]+/)
+    .filter((w) => w && !FILLER.has(w))
+    .map((w) => (w.length > 3 && w.endsWith('s') ? w.slice(0, -1) : w)));
+}
+
+function editDistance(a, b) {
+  if (Math.abs(a.length - b.length) > 2) return 3;
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+}
+
+function isNear(a, b) {
+  return wordsNear(nameWords(a), nameWords(b));
+}
+
+// Two word sets are near when they share at least half their words (Jaccard), or,
+// joined, are within two edits of each other.
+function wordsNear(wa, wb) {
+  if (!wa.size || !wb.size) return false;
+  let shared = 0;
+  for (const w of wa) if (wb.has(w)) shared++;
+  if (shared / (wa.size + wb.size - shared) >= 0.5) return true;
+  const ja = [...wa].sort().join('');
+  const jb = [...wb].sort().join('');
+  return ja.length >= 4 && jb.length >= 4 && editDistance(ja, jb) <= 2;
+}
+
+// For each of `pending`, every other live (proposed or approved) sub-category whose
+// key or label is near its own, across all parents (an author may have picked the
+// wrong parent). Word sets are built once per row, not once per comparison. Pure.
+// Rows carry id, parent, sub_key, label, status.
+function nearDuplicatesFor(pending, rows) {
+  const live = (rows || []).filter((o) => o.status !== 'merged')
+    .map((o) => ({ o, names: [nameWords(o.sub_key), nameWords(o.label)] }));
+  const byId = new Map(live.map((x) => [String(x.o.id), x]));
+  return new Map(pending.map((row) => {
+    const mine = byId.get(String(row.id))?.names || [nameWords(row.sub_key), nameWords(row.label)];
+    const near = live
+      .filter((x) => String(x.o.id) !== String(row.id) && mine.some((m) => x.names.some((n) => wordsNear(m, n))))
+      .map(({ o }) => ({ id: o.id, parent: o.parent, sub_key: o.sub_key, label: o.label, status: o.status }));
+    return [String(row.id), near];
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Publish: record where the module sits, proposing a new sub-category
+// ---------------------------------------------------------------------------
+
+// Runs on the publish transaction's client (module-store.js publishVersion), so a
+// version never lands without its category or the other way round. `category` is
+// module.json's block, already shape-checked; absent → nothing changes (a version
+// that names no category leaves the module where it was). Returns what the author
+// is told, or null.
+async function recordPublishCategory(client, { key, category, builderId }) {
+  if (!category || !category.parent) return null;
+  const { parent, sub } = category;
+  if (!sub) {
+    await upsertModuleCategory(client, key, parent, null);
+    return { parent, sub: null, status: null, live: false };
+  }
+  await client.query(
+    `INSERT INTO store_subcategories (parent, sub_key, label, proposed_by)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT (parent, sub_key) DO NOTHING`,
+    [parent, sub, labelFromKey(sub), builderId]);
+  let row = await subcategoryByKey(client, parent, sub);
+  // One step is enough: a merge re-points every earlier merge at its new target
+  // (mergeSubcategory), so merged_into always names a live row.
+  if (row && row.status === 'merged') row = await subcategoryById(client, row.merged_into);
+  if (!row || row.status === 'merged') {
+    await upsertModuleCategory(client, key, parent, null);
+    return { parent, sub: null, status: null, live: false };
+  }
+  await upsertModuleCategory(client, key, row.parent, row.id);
+  return {
+    parent: row.parent, sub: row.sub_key, label: row.label, status: row.status,
+    live: row.status === 'approved', named: sub,
+  };
+}
+
+async function upsertModuleCategory(client, key, parent, subcategoryId) {
+  await client.query(
+    `INSERT INTO store_module_categories (module_key, parent, subcategory_id)
+     VALUES ($1, $2, $3)
+     ON CONFLICT (module_key) DO UPDATE
+       SET parent = EXCLUDED.parent, subcategory_id = EXCLUDED.subcategory_id, updated_at = now()`,
+    [key, parent, subcategoryId]);
+}
+
+const SUB_COLUMNS = 'id, parent, sub_key, label, status, proposed_by, decided_by, decided_at, merged_into, created_at';
+
+async function subcategoryByKey(exec, parent, subKey) {
+  const { rows: [row] } = await exec.query(
+    `SELECT ${SUB_COLUMNS} FROM store_subcategories WHERE parent = $1 AND sub_key = $2`, [parent, subKey]);
+  return row || null;
+}
+
+async function subcategoryById(exec, id, { lock = false } = {}) {
+  const { rows: [row] } = await exec.query(
+    `SELECT ${SUB_COLUMNS} FROM store_subcategories WHERE id = $1${lock ? ' FOR UPDATE' : ''}`, [id]);
+  return row || null;
+}
+
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+
+// The approved sub-categories, grouped under the eight parents: what an author picks
+// from. Any builder may read it.
+async function listSubcategories({ db } = {}) {
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    `SELECT id, parent, sub_key, label FROM store_subcategories
+      WHERE status = 'approved' ORDER BY parent, label`);
+  return {
+    parents: Object.entries(CATEGORY_PARENTS).map(([parent, title]) => ({
+      parent, title,
+      subcategories: rows.filter((r) => r.parent === parent).map((r) => ({ id: r.id, sub_key: r.sub_key, label: r.label })),
+    })),
+  };
+}
+
+// The Metic+ queue: every pending proposal, oldest first, with the modules that
+// named it and the near-duplicate names beside it.
+async function reviewQueue({ db } = {}) {
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    `SELECT ${SUB_COLUMNS} FROM store_subcategories WHERE status <> 'merged' ORDER BY created_at, id`);
+  const proposed = rows.filter((r) => r.status === 'proposed');
+  const pending = proposed.slice(0, QUEUE_LIMIT);
+  const modules = new Map();
+  if (pending.length) {
+    const { rows: mods } = await pool.query(
+      `SELECT module_key, subcategory_id FROM store_module_categories
+        WHERE subcategory_id = ANY($1) ORDER BY module_key`, [pending.map((r) => r.id)]);
+    for (const m of mods) {
+      const k = String(m.subcategory_id);
+      if (!modules.has(k)) modules.set(k, []);
+      modules.get(k).push(m.module_key);
+    }
+  }
+  const near = nearDuplicatesFor(pending, rows);
+  return {
+    total: proposed.length,
+    more: proposed.length > pending.length,
+    proposals: pending.map((r) => ({
+      id: r.id, parent: r.parent, parent_title: CATEGORY_PARENTS[r.parent] || r.parent,
+      sub_key: r.sub_key, label: r.label, proposed_by: r.proposed_by, proposed_at: r.created_at,
+      modules: modules.get(String(r.id)) || [],
+      near: near.get(String(r.id)) || [],
+    })),
+  };
+}
+
+// Where each of `keys` sits now: Map key → { parent, parent_title, sub, label,
+// status, live }. `live` is true only under an approved sub-category, the only kind
+// the cap and ranking count within (ADR 0342 D2, D3). A key with no row is absent.
+async function readModuleCategories(keys, { db } = {}) {
+  const out = new Map();
+  if (!keys || !keys.length) return out;
+  const pool = db || require('./pool').pool;
+  const { rows } = await pool.query(
+    `SELECT c.module_key, c.parent, s.sub_key, s.label, s.status
+       FROM store_module_categories c
+       LEFT JOIN store_subcategories s ON s.id = c.subcategory_id
+      WHERE c.module_key = ANY($1)`, [keys]);
+  for (const r of rows) {
+    out.set(r.module_key, {
+      parent: r.parent, parent_title: CATEGORY_PARENTS[r.parent] || r.parent,
+      sub: r.sub_key || null, label: r.label || null, status: r.status || null,
+      live: r.status === 'approved',
+    });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Decisions — approve (optionally renamed) and merge
+// ---------------------------------------------------------------------------
+
+async function inTx(db, fn) {
+  const pool = db || require('./pool').pool;
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const out = await fn(client);
+    await client.query(out && out.ok === false ? 'ROLLBACK' : 'COMMIT');
+    return out;
+  } catch (e) {
+    try { await client.query('ROLLBACK'); } catch { /* the connection may be gone */ }
+    throw e;
+  } finally {
+    client.release();
+  }
+}
+
+const refuse = (status, code, message) => ({ ok: false, status, code, message });
+
+// Approve a proposal, optionally under a new label and/or key. A rename onto a key
+// that already exists under the same parent is refused: that is a merge.
+async function approveSubcategory(id, { label = null, subKey = null, builderId }, { db } = {}) {
+  return inTx(db, async (client) => {
+    const row = await subcategoryById(client, id, { lock: true });
+    if (!row) return refuse(404, 'subcategory_not_found', `No sub-category ${id}.`);
+    if (row.status !== 'proposed') return refuse(409, 'subcategory_decided', `"${row.label}" is already ${row.status}.`);
+    const newLabel = label != null ? String(label).trim() : row.label;
+    if (!newLabel || newLabel.length > 80) return refuse(400, 'bad_label', 'A label is 1 to 80 characters.');
+    const newKey = subKey != null ? String(subKey) : (label != null ? subKeyFromLabel(newLabel) : row.sub_key);
+    if (!/^[a-z][a-z0-9-]*$/.test(newKey)) return refuse(400, 'bad_sub_key', 'A sub-category key is lowercase kebab-case.');
+    if (newKey !== row.sub_key) {
+      const clash = await subcategoryByKey(client, row.parent, newKey);
+      if (clash) return refuse(409, 'subcategory_exists', `"${newKey}" already exists under ${row.parent} — merge into it instead (POST /store/subcategories/${row.id}/merge { into: ${clash.id} }).`);
+    }
+    const renamed = newKey !== row.sub_key || newLabel !== row.label;
+    const { rows: [done] } = await client.query(
+      `UPDATE store_subcategories
+          SET status = 'approved', label = $2, sub_key = $3, decided_by = $4, decided_at = now()
+        WHERE id = $1 RETURNING ${SUB_COLUMNS}`,
+      [row.id, newLabel, newKey, builderId]);
+    return { ok: true, subcategory: done, renamed };
+  });
+}
+
+// Merge a sub-category (proposed, or an approved duplicate) into an approved one.
+// Every module that sat under it moves to the target, parent included, and any
+// earlier merge into it is re-pointed so a chain stays one step.
+async function mergeSubcategory(id, { into, builderId }, { db } = {}) {
+  return inTx(db, async (client) => {
+    if (String(id) === String(into)) return refuse(400, 'merge_into_self', 'A sub-category cannot be merged into itself.');
+    // Both rows locked in one statement, in id order, so two opposite merges at once
+    // wait on each other instead of deadlocking.
+    const { rows: locked } = await client.query(
+      `SELECT ${SUB_COLUMNS} FROM store_subcategories WHERE id = ANY($1) ORDER BY id FOR UPDATE`,
+      [[String(id), String(into)]]);
+    const row = locked.find((x) => String(x.id) === String(BigInt(id)));
+    const target = locked.find((x) => String(x.id) === String(BigInt(into)));
+    if (!row) return refuse(404, 'subcategory_not_found', `No sub-category ${id}.`);
+    if (row.status === 'merged') return refuse(409, 'subcategory_decided', `"${row.label}" is already merged.`);
+    if (!target) return refuse(404, 'subcategory_not_found', `No sub-category ${into} to merge into.`);
+    // Compared by the rows found, not the raw ids: "05" and "5" are the same row.
+    if (String(target.id) === String(row.id)) return refuse(400, 'merge_into_self', 'A sub-category cannot be merged into itself.');
+    if (target.status !== 'approved') return refuse(409, 'merge_target_not_approved', `Merge into an approved sub-category; "${target.label}" is ${target.status}.`);
+    await client.query(
+      `UPDATE store_subcategories
+          SET status = 'merged', merged_into = $2, decided_by = $3, decided_at = now()
+        WHERE id = $1`,
+      [row.id, target.id, builderId]);
+    await client.query('UPDATE store_subcategories SET merged_into = $2 WHERE merged_into = $1', [row.id, target.id]);
+    const { rows: moved } = await client.query(
+      `UPDATE store_module_categories SET subcategory_id = $2, parent = $3, updated_at = now()
+        WHERE subcategory_id = $1 RETURNING module_key`,
+      [row.id, target.id, target.parent]);
+    return { ok: true, merged: { id: row.id, sub_key: row.sub_key, label: row.label }, into: target, moved: moved.map((m) => m.module_key).sort() };
+  });
+}
+
+module.exports = {
+  isNear,
+  recordPublishCategory, listSubcategories, reviewQueue, readModuleCategories,
+  approveSubcategory, mergeSubcategory,
+};

package/src/bongos/route-rank-check.js

@@ -242,6 +242,11 @@ const EXPECTED_RANKS = {
   // Re-running a store version's assessment (task 1003796, ADR 0359) spends a Docs
   // grader call and re-opens the Security gate, so it is pinned to its own atom.
   'POST /store/modules/:key/versions/:version/reassess': 'perm:module.assessment.rerun',
+  // Approving, renaming or merging a store sub-category (task 1004355, ADR 0342 D3)
+  // decides which modules compete for the same ten slots, so it is pinned to its own atom.
+  'GET /store/subcategories/queue': 'perm:module.subcategory.review',
+  'POST /store/subcategories/:id/approve': 'perm:module.subcategory.review',
+  'POST /store/subcategories/:id/merge': 'perm:module.subcategory.review',
   // Delisting a store module (task 1003797, ADR 0338 D2) stops every new install of
   // it for every instance, so it is pinned to its own atom.
   'POST /store/modules/:key/delist': 'perm:module.delist',

package/src/bongos/routes/modules.js

@@ -111,6 +111,7 @@ const log = require('../logger').logger.child({ src: 'modules' });
 // as unused exports and tripped the dead-code ratchet that held this branch out of main.
 const { listOverrides, setOverride } = require('../module-overrides');
 const { listCatalog, readListing, SORT_PARTS } = require('../module-listing');
+const { listSubcategories, reviewQueue, approveSubcategory, mergeSubcategory } = require('../module-subcategories');
 const { readTesting, setTester, setGeneralOnly, testsVersionsOf } = require('../module-testing');
 const { readStanding, releaseHeld } = require('../module-promotion');
 
@@ -522,6 +523,7 @@ module.exports = function buildModulesRouter() {
           bytes: v.bytes,
           artifactPath: relativeArtifactPath(staged.final),
           builderId: req.builder.id,
+          category: v.moduleJson.category,
         }, { beforeCommit: () => commitArtifact(staged) });
       } finally {
         await removeArtifact(staged.tmp);
@@ -529,7 +531,7 @@ module.exports = function buildModulesRouter() {
       if (!result.ok) return res.fail(result.code, { status: result.status, message: result.message });
 
       console.log(`[gds] module "${key}" ${v.version} published to the store by builder ${req.builder.id}`);
-      res.status(201).json({ ok: true, created_module: result.created, version: result.version, channel: result.channel });
+      res.status(201).json({ ok: true, created_module: result.created, version: result.version, channel: result.channel, category: result.category || null });
       // A new version is a new thing to judge (task 1003794, ADR 0343): queue its
       // assessment after answering, since the Security gate asks npm about its
       // dependencies and can take a minute. The queue runs one at a time and is
@@ -891,6 +893,58 @@ module.exports = function buildModulesRouter() {
       res.json(listing);
     }));
 
+  // GET /api/bongos/store/subcategories — the approved sub-categories under each of
+  // the eight parents (task 1004355, ADR 0342 D3): what an author names in
+  // module.json's `category.sub`. A key not on this list is proposed at publish.
+  //
+  // rank: any-builder — public store metadata; nothing changed.
+  router.get('/store/subcategories', auth.requireBuilder,
+    asyncHandler('GET /store/subcategories', async (_req, res) => {
+      res.set('Cache-Control', 'private, max-age=60'); // changes only when a reviewer decides
+      res.json(await listSubcategories());
+    }));
+
+  // GET /api/bongos/store/subcategories/queue — the proposals waiting on a Metic+
+  // decision, oldest first, each with the modules that named it and the
+  // near-duplicate names beside it ("Stripe" next to "Stripe payments"), since
+  // stopping near-duplicates is the point of the queue (ADR 0342 D3).
+  router.get('/store/subcategories/queue', auth.requireBuilder, auth.requirePermission('module.subcategory.review'),
+    asyncHandler('GET /store/subcategories/queue', async (_req, res) => {
+      res.set('Cache-Control', 'no-store');
+      res.json(await reviewQueue());
+    }));
+
+  // POST /api/bongos/store/subcategories/:id/approve { label?, sub_key? } — make a
+  // proposal live, optionally renamed first. A rename onto a key that already
+  // exists under the parent is refused with the merge to run instead.
+  router.post('/store/subcategories/:id/approve', auth.requireBuilder, auth.requirePermission('module.subcategory.review'),
+    asyncHandler('POST /store/subcategories/:id/approve', async (req, res) => {
+      if (validateOrRespond(req, res, { label: { type: 'string', maxLength: 80 }, sub_key: { type: 'string', maxLength: 80 } })) return;
+      const id = String(req.params.id);
+      if (!/^\d{1,18}$/.test(id)) return res.fail('bad_request', { status: 400, message: 'A sub-category id is a whole number.' });
+      const r = await approveSubcategory(id, { label: req.body?.label ?? null, subKey: req.body?.sub_key ?? null, builderId: req.builder.id });
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      log.info({ id, builderId: req.builder.id }, `sub-category ${r.subcategory.parent}/${r.subcategory.sub_key} approved`);
+      res.json(r);
+    }));
+
+  // POST /api/bongos/store/subcategories/:id/merge { into } — fold a proposal (or an
+  // approved duplicate) into an approved sub-category. Every module under it moves
+  // to the target.
+  router.post('/store/subcategories/:id/merge', auth.requireBuilder, auth.requirePermission('module.subcategory.review'),
+    asyncHandler('POST /store/subcategories/:id/merge', async (req, res) => {
+      if (validateOrRespond(req, res, { into: {} })) return;  // bigint as number or string; validated below
+      const id = String(req.params.id);
+      const into = req.body?.into == null ? '' : String(req.body.into);
+      if (!/^\d{1,18}$/.test(id) || !/^\d{1,18}$/.test(into)) {
+        return res.fail('bad_request', { status: 400, message: 'Name the sub-category to merge into by id, in into.' });
+      }
+      const r = await mergeSubcategory(id, { into, builderId: req.builder.id });
+      if (!r.ok) return res.fail(r.code, { status: r.status, message: r.message });
+      log.info({ id, into, moved: r.moved.length, builderId: req.builder.id }, `sub-category ${r.merged.sub_key} merged into ${r.into.sub_key}`);
+      res.json(r);
+    }));
+
   router.post('/store/modules/:key/acquired', auth.requireBuilder,
     asyncHandler('POST /store/modules/:key/acquired', async (req, res) => {
       const { key } = req.params;

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.23.1'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.23.2'; // 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');