@bongos/core 1.23.2 → 1.23.4

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "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.4",
+  "core_contract": "1.23.4",
+  "source_commit": "b78c52677b921b7b2a6f25834c77b7d516810aa9",
   "source_ref": "HEAD",
-  "built_at": "2026-10-26T20:56:59.821Z",
+  "built_at": "2026-10-26T21:43:52.539Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 616,
     "agent_docs_stubbed": 29,
-    "functional_verbatim": 3551,
+    "functional_verbatim": 3552,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 4197,
-  "tree_sha256": "b7044ab9489376d2235032b4c477d00a80eaff992b0e4b7ef85e006ac4ab4a44",
+  "file_count": 4198,
+  "tree_sha256": "e5ed2ca130fbbb98e21c941d9c51e72760f74f72e2d48d6d91a4e789bdd6ce10",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2937,12 +2937,12 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "dab88b77e92556a8ee38cf29f1c0651b03948fb64f84218de31deb29dd88a427"
+      "sha256": "3907ee1e7036c99afa1790df344933c6652b4d9ffe972715551ad9bdb2bb12d9"
     },
     {
       "path": "docs/modules-contract.md",
       "mode": "0000644",
-      "sha256": "c060a917d9a2e7ec3d0a982cdd4ea766fb169b60af48fe051b677de5e4c176ff"
+      "sha256": "ed7ab0d4799a935bb296457ebdba667c38dcfea5ebaec72e61968cd3ad91a6eb"
     },
     {
       "path": "docs/onboarding/diagrams/01-task-lifecycle.mmd",
@@ -10832,12 +10832,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "18afbb380a19b9cd590be01531be1be017361ae8e983737c21a4447fbdbf1fae"
+      "sha256": "793a3d85e023eafb3f0eb63e7a1c1b10f07a66e331adfb63d06a05921ad2f451"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ce17d8a6be52178ed3a90d897f8967eb1c7dd0f8a662cc9c15d0c32e20534e68"
+      "sha256": "db95c78d828b9fd2117b5a7b4e12d741fb21856022a6830b6cd286017a065f6f"
     },
     {
       "path": "public-docs/index.html",
@@ -10857,7 +10857,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "e3e8007ba8a4bb814329fc41bd3d9bb7a0d48821b8bc2bc4a83ae23ea213037f"
+      "sha256": "a491785c22b68e414bdf9668ca809f671a8927d06560aabfbc04ce3d56dfc131"
     },
     {
       "path": "scripts/bongos/CLAUDE.md",
@@ -11747,7 +11747,7 @@
     {
       "path": "scripts/bongos/module.js",
       "mode": "0000644",
-      "sha256": "0a0bbaea5b010533cfee379593768990a26717c4fcaf614896ec2b3b6b3061b6"
+      "sha256": "6fc19f18daa947837ee09d9d06010380144022ee6f637f3fd444f56cf558bfab"
     },
     {
       "path": "scripts/bongos/move-escalation.js",
@@ -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": "e9850d0157caab4215194a5e69e04420b0d9e3b97a8d1867f8f84e9087b88930"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -18484,6 +18484,11 @@
       "mode": "0000644",
       "sha256": "ba4233ed072c87df9dbc5c75af10655ad8eaaf9d8ccbe69df146052467a1279e"
     },
+    {
+      "path": "tests/module_store_cli.mjs",
+      "mode": "0000644",
+      "sha256": "cf4df707f62fa142f106822c44404603f8ec32213d61b6707818f5649c443275"
+    },
     {
       "path": "tests/module_store_delist.mjs",
       "mode": "0000644",
@@ -18502,7 +18507,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,9 @@ 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)
+  1.23.4 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.23.3 with no explicit bump. run 40406624494. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -176,6 +176,8 @@ closed on every unknown, including a ledger read it cannot complete.
 
 **Attribution (`author`/`origin`/`license`/`maintainer`) is portable metadata, not a cross-Bongos link** — each repo runs its own Bongos with its own builder identities ([ADR 0100](adr/0100-two-repo-instance-model.md) §3), so credit travels *with the module* rather than through a foreign key ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §2). `bongos module new` stamps all four as TODO placeholders (license defaults to `AGPL-3.0`) so a module carries its authorship from the day it's scaffolded, not bolted on later at upstream-submit time.
 
+**`bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]`** (task 1003811) is the **store** from the terminal: what the catalog lists, in its order — listed modules ranked, then New ones, unranked — with each module's score, price and place (parent, and sub-category once approved). It asks `GET /store/modules`, the same read the hall's "In the store" group makes, and filters, ranks and caps nothing itself: the quality floor, the ranking and the cap of ten per sub-category live only in `src/bongos/module-listing.js`, so the hall and the terminal cannot disagree about which modules are the best. `tests/module_store_cli.mjs` sends the same queries through the API and the CLI and requires the same modules in the same order.
+
 **`bongos module list [--catalog] [--search <text>] [--json]`** ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §2/§3, [ADR 0167](adr/0167-module-catalog-source-vs-provenance.md)) is the browsable catalog from the terminal: every module on disk with its enabled state, its author + origin credit, and its upkeep posture. `--catalog` narrows to the **core-shipped** modules — the shared catalog an instance opts into (§6, default-off). Two axes travel on each row and they are *not* the same question: **`source`** (which tree ships it — the core package or this instance's own repo, read structurally from the loader's discovery root, [ADR 0108](adr/0108-instance-composition-configurable-root.md) §1) and **`provenance`** (who built it, derived from the declared `origin`). A core module that declares no attribution is credited to the platform and the credit is **marked inferred** (`*`) rather than left blank or silently invented. The hall's Modules tab renders the same model (`src/module-loader/catalog.js`) via `GET /modules`, so the two surfaces cannot drift.
 
 **`bongos module check <key> [--sign-off "Name <email>"]`** ([ADR 0107](adr/0107-module-upstreaming-contribution-to-core-catalog.md) §4) is the submit-time pre-check a module must clear before it can be upstreamed. It reuses (never re-types) the public-mirror publish denylist (`scripts/bongos/publish-manifest.js`'s `matchesDeny`) to reject content that cannot ship under AGPL (game content, pixel art, copyrighted reference material) — deliberately the DENY half only, since a brand-new module is never on the publish ALLOWLIST until it's accepted into core (§6). It also requires `module.json`'s `license` to be AGPL-3.0 (inbound = outbound) and a declared `maintenance` posture — acceptance is a commitment to upkeep, so a module with no `maintenance.status`, or one already `deprecated`/`orphaned`, is refused ([ADR 0166](adr/0166-module-maintenance-and-deprecation-policy.md); see below). On a pass, `--sign-off` records a lightweight DCO-style affirmation (own work, licensed AGPL-3.0 — never a copyright-assignment CLA) to `modules/<key>/.upstream-signoff.json`.
@@ -398,7 +400,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.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.23.2",
+      "version": "1.23.4",
       "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.4",
   "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,17 @@
       "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."
+    }
+  ],
+  "1.23.4": [
+    {
+      "id": "1003811",
+      "text": "Builders can now browse the module store from the terminal with bongos module store, and it always shows the same modules in the same order as the hall."
+    }
   ]
 }

package/scripts/bongos/module.js

@@ -31,6 +31,14 @@
 //     model as the hall's Modules tab (src/module-loader/catalog.js), so the two
 //     surfaces cannot disagree about who built what.
 //
+//   bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]
+//     Task 1003811 (criterion wa5-curated-listing) — the STORE from the terminal:
+//     what the catalog lists, in its order. It asks GET /store/modules, the same
+//     read the hall's "In the store" group makes, and never filters, ranks or caps
+//     anything itself — the quality floor, the ranking and the cap of ten per
+//     sub-category live in one place (src/bongos/module-listing.js), so the hall
+//     and the terminal cannot disagree about which modules are the best.
+//
 //   bongos module check <key>
 //     ADR 0107 §4 — the submit-time pre-check a module must clear before it can
 //     be upstreamed into the shared core catalog. REUSES (never re-types) the
@@ -58,6 +66,7 @@
 //   bongos module new <key>            scaffold modules/<key>/
 //   bongos module new <key> --force    overwrite an existing modules/<key>/
 //   bongos module list [--catalog]     browse the module catalog (author + origin credit)
+//   bongos module store [--sort <part>] [--max-cents N] [--max-credits N]   what the store lists, best first
 //   bongos upgrade [--no-store]        pre-check enabled modules vs the core version + list store updates
 //   bongos module check <key> [--sign-off "Name <email>"]   AGPL/publish pre-check + DCO sign-off
 //   bongos module install <key> [--version X.Y.Z]   acquire from the store, verify, place (not enabled)
@@ -1060,6 +1069,84 @@ function storeError(res) {
   return (err && (err.message || err.code)) || `HTTP ${res.status}`;
 }
 
+// ---------------------------------------------------------------------------
+// bongos module store — what the store lists (task 1003811)
+// ---------------------------------------------------------------------------
+
+const STORE_USAGE = 'usage: bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]';
+
+// The query GET /store/modules takes, from argv. Returns { query } or { error }.
+// The server checks the values too; this only refuses what is not a value at all.
+function storeQuery(args) {
+  const params = [];
+  for (const [flag, param] of [['--sort', 'sort'], ['--max-cents', 'max_cents'], ['--max-credits', 'max_credits']]) {
+    const i = args.indexOf(flag);
+    if (i === -1) continue;
+    const v = args[i + 1];
+    if (!v || v.startsWith('--')) return { error: `${flag} needs a value` };
+    params.push(`${param}=${encodeURIComponent(v)}`);
+  }
+  return { query: params.length ? `?${params.join('&')}` : '' };
+}
+
+function formatPrice(price) {
+  if (!price || price.free) return 'free';
+  const parts = [];
+  if (price.cents != null) parts.push(`$${(price.cents / 100).toFixed(2)}`);
+  if (price.credits != null) parts.push(`${price.credits} credits`);
+  return parts.join(' or ') || 'free';
+}
+
+function formatPlace(category) {
+  if (!category) return '';
+  return category.label ? `${category.parent_title} › ${category.label}` : category.parent_title;
+}
+
+// Pure renderer over the GET /store/modules body. It keeps the server's order and
+// adds nothing to it: listed in rank, then New, never ranked.
+function formatStore(body) {
+  const out = [];
+  out.push('bongos module store — what the store lists, best first');
+  out.push(`  floor ${body.floor} out of 100 · at most ${body.cap} per sub-category`);
+  out.push(`  ${body.ranking}`);
+  if (body.sort) {
+    const part = (body.sort_parts || []).find((x) => x.part === body.sort);
+    out.push(`  sorted by ${part ? part.title : body.sort}`);
+  }
+  const max = body.max_price;
+  if (max) out.push(`  at most ${[max.cents != null ? `$${(max.cents / 100).toFixed(2)}` : null, max.credits != null ? `${max.credits} credits` : null].filter(Boolean).join(' or ')}`);
+  out.push('');
+  const listed = body.listed || [];
+  if (!listed.length) out.push('  Nothing is listed yet.');
+  listed.forEach((m, i) => {
+    out.push(`  ${String(i + 1).padStart(2)}. ${m.key}@${m.version}  ${m.overall}/100  ${formatPrice(m.price)}${m.category ? `  ${formatPlace(m.category)}` : ''}`);
+  });
+  const fresh = body.new || [];
+  if (fresh.length) {
+    out.push('');
+    out.push('  New — not ranked until projects have installed and used them:');
+    for (const m of fresh) out.push(`      ${m.key}@${m.version}  ${formatPrice(m.price)}${m.category ? `  ${formatPlace(m.category)}` : ''}`);
+  }
+  out.push('');
+  out.push('  Why a module is not here: GET /store/modules/<key>/listing');
+  return out.join('\n');
+}
+
+async function cmdStore(args, { log = console.log, errlog = console.error, request } = {}) {
+  const q = storeQuery(args);
+  if (q.error) { errlog(`bongos module store: ${q.error}`); errlog(STORE_USAGE); return 2; }
+  let call;
+  try { call = request || storeRequest(); }
+  catch (e) { errlog(`bongos module store: ${e.message}`); return 1; }
+  let res;
+  try { res = await call('GET', `/store/modules${q.query}`); }
+  catch (e) { errlog(`bongos module store: the store could not be reached — ${e.message}`); return 1; }
+  if (!res.ok) { errlog(`bongos module store: the store answered ${storeError(res)}`); return res.status === 400 ? 2 : 1; }
+  if (args.includes('--json')) { log(JSON.stringify(res.data, null, 2)); return 0; }
+  log(formatStore(res.data || {}));
+  return 0;
+}
+
 // Where install places a module: the INSTANCE's own modules/ root (ADR 0108 §1),
 // which the loader discovers. In a single checkout that is this repo's modules/.
 function instanceModulesDir() {
@@ -1319,6 +1406,8 @@ function printHelp(out = console.log) {
   out('  bongos module new <key>     Scaffold modules/<key>/ (manifest + skeleton + sample route + HOWTO.md + CLAUDE.md)');
   out('  bongos module list [--catalog] [--search <text>] [--json]');
   out('                              Browse the module catalog — what you can enable, with author + origin credit');
+  out('  bongos module store [--sort <part>] [--max-cents N] [--max-credits N] [--json]');
+  out('                              What the store lists, best first: above the quality floor, ranked, ten per sub-category');
   out('  bongos upgrade [--no-store] Pre-check enabled modules against the core version (fail-closed),');
   out('                              then list newer store versions of installed modules (never blocks)');
   out('  bongos module check <key> [--sign-off "Name <email>"]');
@@ -1338,6 +1427,7 @@ async function main(argv) {
   const sub = args[0];
   if (sub === 'new') return cmdNew(args.slice(1));
   if (sub === 'list' || sub === 'ls') return cmdList(args.slice(1));
+  if (sub === 'store') return cmdStore(args.slice(1));
   if (sub === 'upgrade') return cmdUpgrade(args.slice(1));
   if (sub === 'check') return cmdCheck(args.slice(1));
   if (sub === 'submit') return cmdSubmit(args.slice(1));
@@ -1354,7 +1444,7 @@ async function main(argv) {
 }
 
 module.exports = {
-  main, cmdNew, cmdList, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
+  main, cmdNew, cmdList, cmdStore, formatStore, cmdUpgrade, cmdCheck, cmdSubmit, cmdPublish, cmdInstall, cmdUpdate, printHelp,
   storeRequest,
   gatherCatalog, formatCatalog, ownProjectName,
   scaffoldModule, gatherUpgrade, evaluateUpgrade, gatherUpdates, evaluateUpdates, buildManifest,

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.4'; // 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_cli.mjs

@@ -0,0 +1,184 @@
+// tests/module_store_cli.mjs — `bongos module store` and the hall read ONE catalog
+// (task 1003811, criterion wa5-curated-listing). The terminal command asks the
+// real GET /store/modules handler here — off the real router, with pool.js replaced
+// in the require cache (the module_store_listing.mjs harness) — so the test pins
+// what the task asks: the same query through the API and through the CLI returns
+// the same modules in the same order, capped the same way. Two surfaces that drift
+// on which modules are "the best" is worse than either being wrong alone.
+//
+// Run:  node tests/module_store_cli.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// ---- the fake registry the route reads ----
+const state = { modules: {}, versions: [], scores: [], prices: [], categories: {} };
+const newestBy = (rows, keyOf, newer) => {
+  const out = new Map();
+  for (const r of rows) {
+    const k = keyOf(r);
+    if (!out.has(k) || newer(r, out.get(k))) out.set(k, r);
+  }
+  return [...out.values()];
+};
+const pool = {
+  async query(sql, params = []) {
+    if (/FROM store_module_categories c\b/.test(sql)) {
+      return { rows: params[0].filter((k) => state.categories[k]).map((k) => ({ module_key: k, ...state.categories[k] })) };
+    }
+    if (/FROM store_modules m JOIN store_module_versions v/.test(sql)) {
+      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 })),
+      };
+    }
+    if (/FROM store_module_prices/.test(sql)) {
+      return { rows: newestBy(state.prices.filter((p) => params[0].includes(p.module_key)), (p) => p.module_key, (a, b) => a.set_at > b.set_at) };
+    }
+    if (/FROM module_assessment_scores/.test(sql)) {
+      const ids = params[0].map(String);
+      return { rows: newestBy(state.scores.filter((s) => ids.includes(String(s.version_id))), (s) => s.version_id, (a, b) => a.computed_at > b.computed_at) };
+    }
+    return { rows: [] };
+  },
+};
+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 mod = require('../scripts/bongos/module.js');
+
+function storeHandler() {
+  const layer = buildModulesRouter().stack.find((l) => l.route && l.route.path === '/store/modules' && l.route.methods.get);
+  const stack = layer.route.stack;
+  return stack[stack.length - 1].handle;
+}
+
+// The API, as a browser or the hall reads it.
+async function apiGet(query) {
+  const res = {
+    statusCode: 200, body: undefined,
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set() { return this; },
+    fail(code, opts) { this.statusCode = opts.status; this.body = { error: { code, message: opts.message } }; return this; },
+  };
+  let nextErr = null;
+  await storeHandler()({ builder: { id: 0 }, query }, res, (err) => { nextErr = err; });
+  if (nextErr) throw nextErr;
+  return res;
+}
+
+// The CLI's request function, answered by the same handler: the URL the CLI
+// builds is parsed back into the query the route reads.
+const request = async (method, urlPath) => {
+  assert.equal(method, 'GET');
+  const url = new URL(urlPath, 'http://store.test');
+  assert.equal(url.pathname, '/store/modules');
+  const res = await apiGet(Object.fromEntries(url.searchParams));
+  return { ok: res.statusCode < 400, status: res.statusCode, data: res.body };
+};
+
+async function cliJson(args) {
+  const lines = [];
+  const errs = [];
+  const code = await mod.cmdStore([...args, '--json'], { log: (l) => lines.push(l), errlog: (l) => errs.push(l), request });
+  return { code, body: lines.length ? JSON.parse(lines.join('\n')) : null, errs };
+}
+
+const keys = (b) => b.listed.map((m) => m.key);
+
+// Fifteen Stripe modules above 94 (the owner's example), one module in a proposed
+// sub-category, one with no category, one New, and one under the floor.
+function seed() {
+  state.modules = {}; state.versions = []; state.scores = []; state.prices = []; state.categories = {};
+  const add = (key, s, cat) => {
+    const id = state.versions.length + 1;
+    state.modules[key] = { status: 'listed', title: key };
+    state.versions.push({ id, module_key: key, version: '1.0.0', published_at: 't' });
+    state.scores.push({ id, version_id: id, computed_at: 1, overall: 70, security_passed: true, is_new: false, ...s });
+    if (cat) state.categories[key] = cat;
+  };
+  const stripe = { parent: 'money', sub_key: 'stripe-payments', label: 'Stripe payments', status: 'approved' };
+  for (let i = 0; i < 15; i++) add(`stripe-${String(i).padStart(2, '0')}`, { overall: 99 - i }, stripe);
+  add('waiting', { overall: 60 }, { parent: 'money', sub_key: 'stripe-billing', label: 'Stripe billing', status: 'proposed' });
+  add('loose', { overall: 88 });
+  add('fresh', { is_new: true, overall: null });
+  add('weak', { overall: 20 });
+  state.prices = [
+    { module_key: 'stripe-01', price_cents: 900, price_credits: null, set_at: 1 },
+    { module_key: 'loose', price_cents: null, price_credits: 40, set_at: 1 },
+  ];
+}
+
+test('the terminal shows what the API lists, in its order, capped the same way', async () => {
+  seed();
+  const api = (await apiGet({})).body;
+  const cli = await cliJson([]);
+  assert.equal(cli.code, 0);
+  assert.deepEqual(cli.body, api, 'the CLI hands back the catalog exactly as the API answers it');
+  assert.equal(keys(api).filter((k) => k.startsWith('stripe-')).length, 10, 'the cap of ten holds');
+  assert.ok(!keys(api).includes('stripe-10') && !keys(api).includes('weak'), 'the eleventh and the one under the floor are not listed');
+  assert.ok(keys(api).includes('waiting') && keys(api).includes('loose'), 'a proposed sub-category and no category are not capped');
+  assert.deepEqual(api.new.map((m) => m.key), ['fresh']);
+});
+
+test('the same query through both: a sort and a maximum price give the same modules in the same order', async () => {
+  seed();
+  for (const [args, query] of [
+    [['--sort', 'tests'], { sort: 'tests' }],
+    [['--max-cents', '500'], { max_cents: '500' }],
+    [['--max-credits', '0'], { max_credits: '0' }],
+    [['--sort', 'docs', '--max-cents', '1000', '--max-credits', '100'], { sort: 'docs', max_cents: '1000', max_credits: '100' }],
+  ]) {
+    const api = (await apiGet(query)).body;
+    const cli = await cliJson(args);
+    assert.equal(cli.code, 0, args.join(' '));
+    assert.deepEqual(keys(cli.body), keys(api), args.join(' '));
+    assert.deepEqual(cli.body.new.map((m) => m.key), api.new.map((m) => m.key), args.join(' '));
+  }
+});
+
+test('the text view keeps the API order: listed ranked, then New, and says the floor and the cap', async () => {
+  seed();
+  const api = (await apiGet({})).body;
+  const lines = [];
+  assert.equal(await mod.cmdStore([], { log: (l) => lines.push(l), errlog: () => {}, request }), 0);
+  const text = lines.join('\n');
+  assert.match(text, /floor 50 out of 100 · at most 10 per sub-category/);
+  const at = (k) => text.indexOf(`${k}@`);
+  const order = [...keys(api), ...api.new.map((m) => m.key)].map(at);
+  assert.ok(order.every((i) => i !== -1), 'every listed and New module is shown');
+  assert.deepEqual(order, [...order].sort((a, b) => a - b), 'in the order the API gave');
+  assert.equal(at('stripe-10'), -1, 'the eleventh is not shown');
+  assert.match(text, /stripe-00@1\.0\.0 {2}99\/100 {2}free {2}Money › Stripe payments/);
+  assert.match(text, /stripe-01@1\.0\.0 {2}98\/100 {2}\$9\.00/);
+  assert.match(text, /loose@1\.0\.0 {2}88\/100 {2}40 credits$/m, 'no category, no place');
+  assert.match(text, /waiting@1\.0\.0 {2}60\/100 {2}free {2}Money$/m, 'a proposed sub-category shows its parent only');
+  assert.match(text, /New — not ranked[\s\S]*fresh@1\.0\.0/);
+});
+
+test('a value the server refuses, a flag with no value, and no session are reported, not swallowed', async () => {
+  seed();
+  const bad = await cliJson(['--sort', 'security']);
+  assert.equal(bad.code, 2);
+  assert.match(bad.errs.join('\n'), /the store answered/);
+  const missing = await cliJson(['--max-cents']);
+  assert.equal(missing.code, 2);
+  assert.match(missing.errs.join('\n'), /--max-cents needs a value/);
+  const errs = [];
+  const offline = await mod.cmdStore([], { log: () => {}, errlog: (l) => errs.push(l), request: async () => { throw new Error('ECONNREFUSED'); } });
+  assert.equal(offline, 1);
+  assert.match(errs.join('\n'), /could not be reached — ECONNREFUSED/);
+});
+
+test('`bongos module store` is dispatched and documented in the help', async () => {
+  const out = [];
+  mod.printHelp((l) => out.push(l));
+  assert.match(out.join('\n'), /bongos module store \[--sort <part>\]/);
+});

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 = [];
+});