@bongos/core 1.23.1 → 1.23.3

package/docs/architecture.md

@@ -262,6 +262,17 @@ passkey_challenges(challenge PK, purpose, builder_id NULL, created_at, expires_a
               -- single-use (DELETEd on consume), TTL swept; builder_id NULL for sign-in
 ```
 
+Store sub-categories (migration `core_280`, task 1004355, [ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md) D3 — an author proposes one at publish, a Metic+ person approves, renames or merges it; `src/bongos/module-subcategories.js`):
+
+```
+store_subcategories(id, parent one of 8, sub_key, label, status proposed|approved|merged,
+              proposed_by, decided_by, decided_at, merged_into FK self, created_at)
+              -- UNIQUE (parent, sub_key); merged ⇔ merged_into set; proposed ⇔ undecided.
+store_module_categories(module_key PK FK store_modules, parent, subcategory_id FK NULL, updated_at)
+              -- where a module sits now; a merge moves rows here. Only an approved
+              -- sub-category is live for the cap and ranking.
+```
+
 Module release channels (migration `core_276`, task 1003815, [ADR 0344](adr/0344-a-tester-is-a-project-that-opts-in-once.md) — which channel a published version is on; the data only, the tester-first publish, promotion gate and channel-aware install are their own tasks):
 
 ```

package/docs/module-api-changelog.md

@@ -3219,5 +3219,9 @@ 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)
+  1.23.3 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.2 with no explicit bump. run 40402796050. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -398,7 +398,9 @@ Run `bongos upgrade` to confirm coreVersion compatibility, then `node scripts/bo
 - **What a module is strong and weak at** (task 1003799, ADR 0343 D4). Each catalog entry also carries `parts` (the current result of Tests, Clean installs, Reliability, Tester feedback and How-to) and a reading of them: `strengths` (a part scored **80 or more**), `weaknesses` (a part scored **below the floor**) and `unmeasured` (a part with no score yet, which is never counted as weak). Each strength and weakness has a one-sentence `detail` saying what the number rests on. Security is not among them: every listed version has passed it. The reading is `readParts` in `src/bongos/module-listing.js`; the hall's Modules tab shows it in its "In the store" group, so two modules with the same overall score can be told apart.
 - **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`.
+- **The cap: at most ten per sub-category** (task 1003809, [ADR 0342](adr/0342-module-categories-are-eight-parents-with-approved-sub-categories.md) D2). Above the floor, at most **ten** modules are listed in each approved sub-category: the first ten in the ranking above, so a buyer's `sort` or maximum price reorders or narrows those ten but never lets the eleventh in. The cap is never applied to a parent. A module whose sub-category is only proposed is listed under its parent and counts toward no cap, and a New module is not ranked, so it neither takes a slot nor is held by one. The catalog returns the cap as `cap`. The rule is `applyCap` 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`, `over_cap`, `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. Past the cap it is `over_cap`, which names the score, the module's place in its sub-category and the cap, so an author can tell being eleventh apart from being below the floor. Both responses carry the module's `category` (`parent`, `parent_title`, and `sub` and `label` once its sub-category is approved). 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.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.23.1",
+      "version": "1.23.3",
       "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.3",
   "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,17 @@
       "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."
+    }
+  ],
+  "1.23.3": [
+    {
+      "id": "1003809",
+      "text": "The module store now shows at most ten modules in each sub-category, and a module that lands eleventh tells its author why."
+    }
   ]
 }

package/src/bongos/module-listing.js

@@ -17,6 +17,7 @@
 // A delisted module (ADR 0338 D2) is never in the catalog, whatever its score.
 
 const { parseVersion, cmp } = require('../module-loader/semver');
+const { readModuleCategories } = require('./module-subcategories');
 
 // The quality floor, 0-100. It lives here and nowhere else: it is part of Bongos
 // itself, not a live setting, so no author, builder or instance can move it.
@@ -106,9 +107,9 @@ function readParts(signals = [], { floor = QUALITY_FLOOR } = {}) {
 //   last, in key order: a missing part is never a zero, and never a first place.
 //
 // Only `listed` is sorted. A "New" version is never ranked (owner decision,
-// 2026-10-01), so `new` keeps key order whatever the buyer picks. Today this runs
-// over the whole store; once approved sub-categories exist (task 1004355) the same
-// rule orders each one (ADR 0342 D2).
+// 2026-10-01), so `new` keeps key order whatever the buyer picks. The cap of ten
+// per approved sub-category (applyCap) is drawn from the default ranking before any
+// sort, so a buyer's sort never changes who is listed.
 const SORT_PARTS = PARTS.map(({ part, title }) => ({ part, title }));
 
 // `entries` carry `parts` as readParts builds them. Returns a new array. Pure.
@@ -174,6 +175,44 @@ function rankListed(entries) {
   });
 }
 
+// ---------------------------------------------------------------------------
+// The cap: at most ten listed per sub-category (task 1003809, ADR 0342 D2)
+// ---------------------------------------------------------------------------
+//
+// The owner's rule: fifteen Stripe modules all scoring above 94% still show only the
+// top ten. The comparable set is an APPROVED sub-category, never a parent (D2): a
+// module whose sub-category is only proposed is listed under its parent and counts
+// toward no cap (D3). The ten are the first ten in the default ranking (RANKING), so
+// a buyer's sort or maximum price reorders or narrows the ten, never changes who they
+// are. A New version is not ranked, so it neither takes a slot nor is held by one.
+const CAP_PER_SUBCATEGORY = 10;
+
+// `ranked` in rankListed order; `cats` a Map of key -> readModuleCategories entry.
+// Returns { kept, held }: `kept` keeps the order, `held` maps each key past the cap
+// to { rank, cap, label } (its place in its sub-category). Pure.
+function applyCap(ranked, cats, cap = CAP_PER_SUBCATEGORY) {
+  const seen = new Map();
+  const kept = [];
+  const held = new Map();
+  for (const e of ranked) {
+    const c = cats.get(e.key);
+    if (!c || !c.live) { kept.push(e); continue; }
+    const set = `${c.parent}/${c.sub}`;
+    const rank = (seen.get(set) || 0) + 1;
+    seen.set(set, rank);
+    if (rank <= cap) kept.push(e);
+    else held.set(e.key, { rank, cap, label: c.label || c.sub });
+  }
+  return { kept, held };
+}
+
+// Where a module sits, as the catalog shows it: its parent, and its sub-category
+// only once approved. A proposed one is not shown: it is not live yet (D3).
+function categoryOf(c) {
+  if (!c) return null;
+  return { parent: c.parent, parent_title: c.parent_title, sub: c.live ? c.sub : null, label: c.live ? c.label : null };
+}
+
 // The newest version row per module key, in semver order (a version that does not
 // parse is skipped, as latestVersions does in module-store.js).
 function newestPerModule(rows) {
@@ -188,19 +227,28 @@ function newestPerModule(rows) {
   return [...out.values()];
 }
 
-// The catalog: { floor, ranking, sort, sort_parts, max_price, listed: [...], new: [...] },
-// each entry { key, title, version, published_at, price, overall, is_new, parts,
-// strengths, weaknesses, unmeasured } (the last four from readParts). Excluded
-// versions are left out entirely: a module below the bar is not listed at all, and
-// neither is one over the buyer's `maxPrice`. `listed` is in rankListed order unless
-// `sort` names a part, which orders it by sortByPart; `new` is never ranked and
-// stays in key order.
-async function listCatalog({ db, floor = QUALITY_FLOOR, sort = null, maxPrice = null } = {}) {
+// The catalog: { floor, cap, ranking, sort, sort_parts, max_price, listed: [...], new: [...] },
+// each entry { key, title, version, published_at, price, category, overall, is_new,
+// parts, strengths, weaknesses, unmeasured } (the last four from readParts). Excluded
+// versions are left out entirely: a module below the bar is not listed at all, nor
+// is one past the cap of its sub-category, nor one over the buyer's `maxPrice`.
+// `listed` is in rankListed order unless `sort` names a part, which orders it by
+// sortByPart; `new` is never ranked and stays in key order.
+async function listCatalog(opts = {}) {
+  return (await buildCatalog(opts)).catalog;
+}
+
+// listCatalog's work, plus `held`: the keys the cap left out, with their place
+// (applyCap). readListing reads `held` to tell an author they are eleventh, and
+// passes `keys` — one sub-category's modules — so one module's check reads only
+// the set it competes in, never the whole store. The cap counts within a
+// sub-category, so that subset ranks exactly as it does in the full catalog.
+async function buildCatalog({ db, floor = QUALITY_FLOOR, sort = null, maxPrice = null, keys = null } = {}) {
   const pool = db || require('./pool').pool;
   const { rows: versions } = await pool.query(
     `SELECT m.module_key, m.title, v.id AS version_id, v.version, v.published_at
        FROM store_modules m JOIN store_module_versions v ON v.module_key = m.module_key
-      WHERE m.status = 'listed'`);
+      WHERE m.status = 'listed'${keys ? ' AND m.module_key = ANY($1)' : ''}`, keys ? [keys] : []);
   const newest = newestPerModule(versions);
   const scores = new Map();
   if (newest.length) {
@@ -237,21 +285,26 @@ async function listCatalog({ db, floor = QUALITY_FLOOR, sort = null, maxPrice =
   }
   const max = maxPrice && (maxPrice.cents != null || maxPrice.credits != null)
     ? { cents: maxPrice.cents ?? null, credits: maxPrice.credits ?? null } : null;
-  const out = { floor, ranking: RANKING, sort: sort || null, sort_parts: SORT_PARTS, max_price: max, listed: [], new: [] };
+  const cats = await readModuleCategories(newest.map((r) => r.module_key), { db: pool });
+  const out = { floor, cap: CAP_PER_SUBCATEGORY, ranking: RANKING, sort: sort || null, sort_parts: SORT_PARTS, max_price: max, listed: [], new: [] };
   for (const r of newest.sort((a, b) => a.module_key.localeCompare(b.module_key))) {
     const score = scores.get(String(r.version_id)) || null;
     const { placement } = placeVersion(score, floor);
     if (placement === 'excluded') continue;
-    const price = priceOf(prices.get(r.module_key));
-    if (!withinMaxPrice(price, max)) continue;
     out[placement].push({
-      key: r.module_key, title: r.title, version: r.version, published_at: r.published_at, price,
+      key: r.module_key, title: r.title, version: r.version, published_at: r.published_at,
+      price: priceOf(prices.get(r.module_key)), category: categoryOf(cats.get(r.module_key)),
       overall: placement === 'new' ? null : score.overall, is_new: placement === 'new',
       ...readParts(signals.get(String(r.version_id)) || [], { floor }),
     });
   }
-  out.listed = sort ? sortByPart(out.listed, sort) : rankListed(out.listed);
-  return out;
+  // The cap first, over the default ranking; then the buyer's filter and order.
+  const { kept, held } = applyCap(rankListed(out.listed), cats);
+  const affordable = (e) => withinMaxPrice(e.price, max);
+  out.listed = kept.filter(affordable);
+  out.new = out.new.filter(affordable);
+  if (sort) out.listed = sortByPart(out.listed, sort);
+  return { catalog: out, held };
 }
 
 // ---------------------------------------------------------------------------
@@ -263,9 +316,10 @@ async function listCatalog({ db, floor = QUALITY_FLOOR, sort = null, maxPrice =
 // names the reason in a sentence, says what would change it, and carries the same
 // parts reading the catalog shows (the weakest parts first). The reasons are
 // placeVersion's, plus two the catalog drops before it gets that far: `delisted`
-// and `no_version`. Being past the cap of ten per category is a reason of its own
-// once the cap exists (task 1003809); it is not one yet.
-function explainPlacement({ placement, reason }, { overall = null, floor = QUALITY_FLOOR, security = null, weaknesses = [] } = {}) {
+// and `no_version`, and `over_cap`: above the floor but past the top ten of its
+// sub-category (task 1003809). From outside, being eleventh looks the same as being
+// below the floor, so the author is told which it is.
+function explainPlacement({ placement, reason }, { overall = null, floor = QUALITY_FLOOR, security = null, weaknesses = [], held = null } = {}) {
   const weakest = weaknesses.slice(0, 3).map((w) => `${w.title} (${w.score})`).join(', ');
   const say = (why, nextStep) => ({ listed: placement !== 'excluded', placement, reason, why, next_step: nextStep });
   switch (reason) {
@@ -291,6 +345,9 @@ function explainPlacement({ placement, reason }, { overall = null, floor = QUALI
     case 'below_floor':
       return say(`This version scored ${overall} out of 100. The store lists modules that score at least ${floor}.${weakest ? ` Its weakest parts: ${weakest}.` : ''}`,
         'Improve its weakest parts and publish a new version. The newest version is the one judged.');
+    case 'over_cap':
+      return say(`This version scored ${overall} out of 100, above the floor of ${floor}, but it ranks ${held.rank} in ${held.label}. The store lists the top ${held.cap} in each sub-category.`,
+        `Score higher than the module in place ${held.cap} and publish a new version. Between equal scores, the cheaper module ranks higher.`);
     case 'new':
       return say('This version is listed with a New label. It is not ranked until it has real install and reliability data.',
         'Nothing to do: it is ranked once projects have installed and used it.');
@@ -301,7 +358,7 @@ function explainPlacement({ placement, reason }, { overall = null, floor = QUALI
 }
 
 // Where one module stands in the catalog, and why: null for a key the store does not
-// know, else { module_key, title, status, version, version_id, floor, overall,
+// know, else { module_key, title, status, category, version, version_id, floor, overall,
 // listed, placement, reason, why, next_step, security, parts, strengths, weaknesses,
 // unmeasured }. Judges the same version the catalog does: the newest published one.
 // What the Security gate found is told only to the module's author (`viewerId`): to
@@ -312,7 +369,8 @@ async function readListing(key, { db, floor = QUALITY_FLOOR, viewerId = null } =
     'SELECT module_key, title, status, author_id FROM store_modules WHERE module_key = $1', [key]);
   const mod = mods[0];
   if (!mod) return null;
-  const head = { module_key: mod.module_key, title: mod.title, status: mod.status, floor };
+  const cat = (await readModuleCategories([key], { db: pool })).get(key);
+  const head = { module_key: mod.module_key, title: mod.title, status: mod.status, floor, category: categoryOf(cat) };
   const { rows: versions } = await pool.query(
     'SELECT module_key, id AS version_id, version, published_at FROM store_module_versions WHERE module_key = $1', [key]);
   const newest = newestPerModule(versions)[0];
@@ -337,16 +395,30 @@ async function readListing(key, { db, floor = QUALITY_FLOOR, viewerId = null } =
   const isAuthor = viewerId != null && String(mod.author_id) === String(viewerId);
   const security = sec ? { outcome: sec.outcome, reason: (isAuthor && sec.reason) || null } : null;
   const reading = readParts(signals, { floor });
-  const placed = placeVersion(score, floor);
+  let placed = placeVersion(score, floor);
+  // Above the floor in a live sub-category, the cap decides, over the same ranking
+  // the catalog uses, so the two never disagree. Only that sub-category is read:
+  // `self` is found by store_module_categories' primary key (module_key) and `peer`
+  // by idx_store_module_categories_sub (subcategory_id), both in core_280.
+  let held = null;
+  if (placed.placement === 'listed' && cat && cat.live) {
+    const { rows: peers } = await pool.query(
+      `SELECT peer.module_key
+         FROM store_module_categories self
+         JOIN store_module_categories peer ON peer.subcategory_id = self.subcategory_id
+        WHERE self.module_key = $1`, [key]);
+    held = (await buildCatalog({ db: pool, floor, keys: peers.map((p) => p.module_key) })).held.get(key) || null;
+    if (held) placed = { placement: 'excluded', reason: 'over_cap' };
+  }
   const overall = score && placed.placement !== 'new' ? score.overall : null;
   return {
     ...head, version: newest.version, version_id: newest.version_id, overall,
-    ...explainPlacement(placed, { overall, floor, security, weaknesses: reading.weaknesses }),
+    ...explainPlacement(placed, { overall, floor, security, weaknesses: reading.weaknesses, held }),
     security, ...reading,
   };
 }
 
 module.exports = {
-  QUALITY_FLOOR, STRONG_AT, SORT_PARTS, RANKING, placeVersion, readParts, sortByPart,
-  priceOf, withinMaxPrice, rankListed, listCatalog, explainPlacement, readListing,
+  QUALITY_FLOOR, STRONG_AT, SORT_PARTS, RANKING, CAP_PER_SUBCATEGORY, placeVersion, readParts,
+  sortByPart, priceOf, withinMaxPrice, rankListed, applyCap, listCatalog, explainPlacement, readListing,
 };

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.