@bongos/core 1.23.2 → 1.23.3

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/bongos/package-core.js",
-  "core_version": "1.23.2",
-  "core_contract": "1.23.2",
-  "source_commit": "ceece568fbbcb8fc2b0ae26fb797c4e25cc561e8",
+  "core_version": "1.23.3",
+  "core_contract": "1.23.3",
+  "source_commit": "a0b45cd71b45f91da068da6eb3e6afef687897c6",
   "source_ref": "HEAD",
-  "built_at": "2026-10-26T20:56:59.821Z",
+  "built_at": "2026-10-26T21:16:36.258Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 616,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 4197,
-  "tree_sha256": "b7044ab9489376d2235032b4c477d00a80eaff992b0e4b7ef85e006ac4ab4a44",
+  "tree_sha256": "929094e8d49dd75a5e74b18f58a1b869fc50dbc5df600af9e861981227cdb40c",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2937,12 +2937,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "dab88b77e92556a8ee38cf29f1c0651b03948fb64f84218de31deb29dd88a427"
+      "sha256": "298fea75cd1590bf6dbb3ad5baedf0ec6c81d2eb811cf59a3d138bd15144c021"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "c060a917d9a2e7ec3d0a982cdd4ea766fb169b60af48fe051b677de5e4c176ff"
+      "sha256": "28cbf7f3d10bd67ef74880112746d182fac27a7659c52694c315b17efe5cb325"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -10832,12 +10832,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "18afbb380a19b9cd590be01531be1be017361ae8e983737c21a4447fbdbf1fae"
+      "sha256": "4a12dc099ad30270a9f2144f9f243b7183b968c6f9761736c2a10a4471ca08ee"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ce17d8a6be52178ed3a90d897f8967eb1c7dd0f8a662cc9c15d0c32e20534e68"
+      "sha256": "975226f43368c946a43c0ae434ba6132e404175ba6b4960c45fb72b6d109e715"
     },
     {
       "path": "public-docs/index.html",
@@ -10857,7 +10857,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "e3e8007ba8a4bb814329fc41bd3d9bb7a0d48821b8bc2bc4a83ae23ea213037f"
+      "sha256": "de9343583c3ac62144354a65b34a4a44bb4d9442c4abd1b77fafc16558c70f9c"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -14427,7 +14427,7 @@
     {
       "path": "src/bongos/module-listing.js",
       "mode": "0000644",
-      "sha256": "f0edc88d351578171d9b4e28fc4f54fb7a2fa3b3f75a2c4d9ca790d242fd902b"
+      "sha256": "3f7013b4e59f72fc89663461d6d5457e412624ae3d4c1df1d2a3b9a8d9168d02"
     },
     {
       "path": "src/bongos/module-overrides.js",
@@ -14712,7 +14712,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "63527f7ed1ef461762b9fb39edd735fc5361d94f5c3ecdc0c3a8bae4518418f3"
+      "sha256": "f87d7162b505fb241f2c33e6dfeaa86cb97d085c6f822384b2b7d923d4eadd1a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -18502,7 +18502,7 @@
     {
       "path": "tests/module_store_listing.mjs",
       "mode": "0000644",
-      "sha256": "5ff78feca75178ee59114da484a6746e4aa13aa0d1e080f838f18548e5c6b3e6"
+      "sha256": "5f0cb9cb6e3faf90d342e1d9e1767699b677b8630d874f1c2af9cb7f713ef530"
     },
     {
       "path": "tests/module_store_publish.mjs",

package/docs/module-api-changelog.md

@@ -3221,5 +3221,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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,8 @@ 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.
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.23.2",
+  "version": "1.23.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.23.2",
+      "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.2",
+  "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

@@ -10395,5 +10395,11 @@
       "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/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.2'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.23.3'; // 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/tests/module_store_listing.mjs

@@ -6,6 +6,8 @@
 //   - the route: the real GET /store/modules handler off the real router, with
 //     pool.js replaced in the require cache (the module_upgrade_updates.mjs harness).
 //
+// The cap of ten per approved sub-category (task 1003809) rides the same harness.
+//
 // Run:  node tests/module_store_listing.mjs
 
 import { strict as assert } from 'node:assert';
@@ -15,7 +17,7 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 
 // ---- the fake registry the route reads ----
-const state = { modules: {}, versions: [], scores: [], signals: [], prices: [] };
+const state = { modules: {}, versions: [], scores: [], signals: [], prices: [], categories: {}, versionReads: [] };
 const pool = {
   async query(sql, params = []) {
     if (/FROM store_module_prices/.test(sql)) {
@@ -27,10 +29,27 @@ const pool = {
       }
       return { rows: [...newest.values()] };
     }
+    if (/FROM store_module_categories self/.test(sql)) {
+      state.peerReads = (state.peerReads || 0) + 1;
+      const mine = state.categories[params[0]];
+      return {
+        rows: Object.keys(state.categories)
+          .filter((k) => mine && state.categories[k].sub_key === mine.sub_key && state.categories[k].parent === mine.parent)
+          .map((k) => ({ module_key: k })),
+      };
+    }
+    if (/FROM store_module_categories c\b/.test(sql)) {
+      return {
+        rows: params[0].filter((k) => state.categories[k])
+          .map((k) => ({ module_key: k, sub_key: null, label: null, status: null, ...state.categories[k] })),
+      };
+    }
     if (/FROM store_modules m JOIN store_module_versions v/.test(sql)) {
+      state.versionReads.push(params[0] ? [...params[0]] : null);
       return {
         rows: state.versions
           .filter((v) => state.modules[v.module_key] && state.modules[v.module_key].status === 'listed')
+          .filter((v) => !params[0] || params[0].includes(v.module_key))
           .map((v) => ({ ...v, version_id: v.id, title: state.modules[v.module_key].title })),
       };
     }
@@ -69,7 +88,7 @@ const poolPath = require.resolve('../src/bongos/pool.js');
 require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: { connect: async () => ({ ...pool, release() {} }), query: pool.query } } };
 
 const buildModulesRouter = require('../src/bongos/routes/modules.js');
-const { QUALITY_FLOOR, SORT_PARTS, RANKING, placeVersion, sortByPart, priceOf, withinMaxPrice, rankListed, explainPlacement } = require('../src/bongos/module-listing.js');
+const { QUALITY_FLOOR, SORT_PARTS, RANKING, CAP_PER_SUBCATEGORY, placeVersion, sortByPart, priceOf, withinMaxPrice, rankListed, applyCap, explainPlacement } = require('../src/bongos/module-listing.js');
 
 function handlerFor(router, method, p) {
   const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
@@ -179,7 +198,7 @@ test('GET /store/modules: an empty store answers empty lists and the floor', asy
   state.modules = {}; state.versions = []; state.scores = [];
   const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
   const res = await invoke(handle, {});
-  assert.deepEqual(res.body, { floor: 50, ranking: RANKING, sort: null, sort_parts: SORT_PARTS, max_price: null, listed: [], new: [] });
+  assert.deepEqual(res.body, { floor: 50, cap: 10, ranking: RANKING, sort: null, sort_parts: SORT_PARTS, max_price: null, listed: [], new: [] });
 });
 
 // ---------------------------------------------------------------------------
@@ -430,6 +449,7 @@ test('explainPlacement: every reason says why in a sentence and what would chang
     [{ placement: 'excluded', reason: 'delisted' }, {}],
     [{ placement: 'excluded', reason: 'no_version' }, {}],
     [{ placement: 'new', reason: 'new' }, {}],
+    [{ placement: 'excluded', reason: 'over_cap' }, { overall: 95, held: { rank: 11, cap: 10, label: 'Stripe payments' } }],
   ]) {
     const e = explainPlacement(placed, ctx);
     assert.equal(e.reason, placed.reason);
@@ -544,3 +564,112 @@ test('the listing read and the catalog agree on every module', async () => {
     assert.equal(r.body.listed, shown.has(key), key);
   }
 });
+
+// ---------------------------------------------------------------------------
+// the cap: at most ten per approved sub-category (task 1003809, ADR 0342 D2/D3)
+// ---------------------------------------------------------------------------
+
+const live = (parent, sub, label) => ({ parent, parent_title: parent, sub, label, status: 'approved', live: true });
+
+test('the cap is ten (owner decision, 2026-09-10)', () => {
+  assert.equal(CAP_PER_SUBCATEGORY, 10);
+});
+
+test('applyCap: ten per approved sub-category, counted in ranking order; a proposed one or none is never capped', () => {
+  const ranked = Array.from({ length: 12 }, (_, i) => ({ key: `s${String(i).padStart(2, '0')}` }))
+    .concat([{ key: 'other' }, { key: 'proposed' }, { key: 'loose' }]);
+  const cats = new Map(ranked.slice(0, 12).map((e) => [e.key, live('money', 'stripe', 'Stripe payments')]));
+  cats.set('other', live('money', 'invoices', 'Invoices'));
+  cats.set('proposed', { parent: 'money', sub: 'stripe', label: 'Stripe', status: 'proposed', live: false });
+  const { kept, held } = applyCap(ranked, cats);
+  assert.deepEqual(kept.map((e) => e.key), [...ranked.slice(0, 10).map((e) => e.key), 'other', 'proposed', 'loose']);
+  assert.deepEqual(held.get('s10'), { rank: 11, cap: 10, label: 'Stripe payments' });
+  assert.deepEqual(held.get('s11'), { rank: 12, cap: 10, label: 'Stripe payments' });
+  assert.equal(held.size, 2);
+});
+
+test('applyCap: the same sub key under two parents is two comparable sets', () => {
+  const ranked = Array.from({ length: 11 }, (_, i) => ({ key: `a${i}` })).concat(Array.from({ length: 2 }, (_, i) => ({ key: `b${i}` })));
+  const cats = new Map(ranked.map((e) => [e.key, e.key.startsWith('a') ? live('money', 'general', 'General') : live('work', 'general', 'General')]));
+  const { held } = applyCap(ranked, cats);
+  assert.deepEqual([...held.keys()], ['a10']);
+});
+
+// The owner's example, verbatim: fifteen Stripe modules all scoring above 94% still
+// show only the top ten.
+function fifteenStripeModules() {
+  state.versionReads = [];
+  state.modules = {}; state.versions = []; state.scores = []; state.signals = []; state.prices = []; state.categories = {};
+  for (let i = 0; i < 15; i++) {
+    const key = `stripe-${String(i).padStart(2, '0')}`;
+    state.modules[key] = { status: 'listed', title: key };
+    state.versions.push({ id: 100 + i, module_key: key, version: '1.0.0', published_at: 't' });
+    state.scores.push({ id: 100 + i, version_id: 100 + i, computed_at: 1, ...score({ overall: 99 - i }) });
+    state.categories[key] = { parent: 'money', sub_key: 'stripe-payments', label: 'Stripe payments', status: 'approved' };
+    // The lowest scorers are best on Tests, so a sort by Tests would put them first.
+    state.signals.push({ id: 100 + i, version_id: 100 + i, part: 'tests', outcome: 'scored', score: 50 + i, sample_size: 10, measured_at: 1 });
+  }
+  state.modules.waiting = { status: 'listed', title: 'Waiting' };
+  state.versions.push({ id: 200, module_key: 'waiting', version: '1.0.0', published_at: 't' });
+  state.scores.push({ id: 200, version_id: 200, computed_at: 1, ...score({ overall: 60 }) });
+  state.categories.waiting = { parent: 'money', sub_key: 'stripe-billing', label: 'Stripe billing', status: 'proposed' };
+}
+
+test('GET /store/modules: fifteen Stripe modules above 94 show only the top ten; a proposed sub-category is not capped', async () => {
+  fifteenStripeModules();
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
+  const res = await invoke(handle, { query: {} });
+  assert.equal(res.body.cap, 10);
+  const stripe = res.body.listed.filter((m) => m.category && m.category.sub === 'stripe-payments');
+  assert.deepEqual(stripe.map((m) => m.overall), [99, 98, 97, 96, 95, 94, 93, 92, 91, 90]);
+  assert.deepEqual(stripe[0].category, { parent: 'money', parent_title: 'Money', sub: 'stripe-payments', label: 'Stripe payments' });
+  const waiting = res.body.listed.find((m) => m.key === 'waiting');
+  assert.ok(waiting, 'a module in a proposed sub-category is listed under its parent');
+  assert.deepEqual(waiting.category, { parent: 'money', parent_title: 'Money', sub: null, label: null }, 'a proposed sub-category is not shown');
+});
+
+test('GET /store/modules: a sort or a maximum price reorders or narrows the ten, never lets the eleventh in', async () => {
+  fifteenStripeModules();
+  state.prices = [{ module_key: 'stripe-00', price_cents: 5000, price_credits: null, set_at: 1 }];
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules');
+  const sorted = await invoke(handle, { query: { sort: 'tests' } });
+  const keys = (b) => b.listed.filter((m) => m.key.startsWith('stripe-')).map((m) => m.key);
+  assert.deepEqual(new Set(keys(sorted.body)), new Set(Array.from({ length: 10 }, (_, i) => `stripe-0${i}`)));
+  assert.equal(keys(sorted.body)[0], 'stripe-09', 'the best on Tests among the ten leads');
+  const cheap = await invoke(handle, { query: { max_cents: '1000' } });
+  assert.equal(keys(cheap.body).length, 9, 'the priced one drops out and nobody takes its slot');
+  assert.ok(!keys(cheap.body).includes('stripe-10'));
+  state.prices = [];
+});
+
+test('GET /store/modules/:key/listing: the eleventh is told it is past the cap, not below the floor', async () => {
+  fifteenStripeModules();
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/listing');
+  const eleventh = await invoke(handle, { params: { key: 'stripe-10' } });
+  assert.equal(eleventh.body.listed, false);
+  assert.equal(eleventh.body.reason, 'over_cap');
+  assert.equal(eleventh.body.overall, 89);
+  assert.match(eleventh.body.why, /scored 89 out of 100, above the floor of 50, but it ranks 11 in Stripe payments/);
+  assert.match(eleventh.body.why, /top 10 in each sub-category/);
+  assert.ok(eleventh.body.next_step);
+  // One module's check reads only its own sub-category, never the whole store.
+  const scoped = state.versionReads.filter((r) => r);
+  assert.ok(scoped.length, 'the cap check reads a scoped set');
+  for (const r of scoped) assert.ok(!r.includes('waiting'), 'a module outside the sub-category is not read');
+  assert.equal(state.versionReads.filter((r) => r === null).length, 0, 'the whole store is never read for one module');
+  const tenth = await invoke(handle, { params: { key: 'stripe-09' } });
+  assert.equal(tenth.body.listed, true);
+  assert.equal(tenth.body.reason, 'at_or_above_floor');
+});
+
+test('the cap: the listing read and the catalog agree on every module', async () => {
+  fifteenStripeModules();
+  const catalog = (await invoke(handlerFor(buildModulesRouter(), 'get', '/store/modules').handle, { query: {} })).body;
+  const shown = new Set([...catalog.listed, ...catalog.new].map((m) => m.key));
+  const { handle } = handlerFor(buildModulesRouter(), 'get', '/store/modules/:key/listing');
+  for (const key of Object.keys(state.modules)) {
+    const r = await invoke(handle, { params: { key } });
+    assert.equal(r.body.listed, shown.has(key), key);
+  }
+  state.categories = {}; state.signals = [];
+});