@bongos/core 1.23.1 → 1.23.3

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

package/tests/module_store_subcategories.mjs

@@ -0,0 +1,364 @@
+// tests/module_store_subcategories.mjs — the sub-category approval queue (task
+// 1004355, ADR 0342 D3): a publish proposes a sub-category the store has not seen,
+// a Metic+ person approves (optionally renamed) or merges it, a merge moves its
+// modules, and near-duplicate names sit beside each proposal. DB-free: an in-memory
+// fake of the two core_278 tables, matched by SQL shape.
+//
+// Run:  node tests/module_store_subcategories.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+
+// The routes reach the database through pool.js; point it at whichever fake the
+// route test below installs (the module_store_reassess.mjs harness).
+let routeDb = null;
+const poolPath = require.resolve('../src/bongos/pool.js');
+const poolProxy = { query: (...a) => routeDb.query(...a), connect: (...a) => routeDb.connect(...a) };
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: poolProxy } };
+const {
+  isNear, recordPublishCategory, listSubcategories, reviewQueue, readModuleCategories,
+  approveSubcategory, mergeSubcategory,
+} = require('../src/bongos/module-subcategories.js');
+const subs = { isNear, recordPublishCategory, listSubcategories, reviewQueue, readModuleCategories, approveSubcategory, mergeSubcategory };
+const { checkRouteRanks } = require('../src/bongos/route-rank-check.js');
+const catalog = require('../modules/government/catalog.js');
+
+// ---- an in-memory store_subcategories + store_module_categories ----------------
+
+function fakeDb() {
+  const state = { subs: [], cats: new Map(), nextId: 1, log: [] };
+  const query = async (sql, p = []) => {
+    const q = sql.replace(/\s+/g, ' ').trim();
+    state.log.push(q);
+    if (/^(BEGIN|COMMIT|ROLLBACK)$/.test(q)) return { rows: [] };
+    if (q.startsWith('INSERT INTO store_subcategories')) {
+      if (!state.subs.some((s) => s.parent === p[0] && s.sub_key === p[1])) {
+        state.subs.push({ id: String(state.nextId++), parent: p[0], sub_key: p[1], label: p[2], status: 'proposed', proposed_by: p[3], decided_by: null, decided_at: null, merged_into: null, created_at: new Date(state.nextId) });
+      }
+      return { rows: [] };
+    }
+    if (/FROM store_subcategories WHERE parent = \$1 AND sub_key = \$2/.test(q)) {
+      return { rows: state.subs.filter((s) => s.parent === p[0] && s.sub_key === p[1]).map((s) => ({ ...s })) };
+    }
+    if (/FROM store_subcategories WHERE id = ANY\(\$1\) ORDER BY id FOR UPDATE/.test(q)) {
+      const ids = p[0].map((x) => String(BigInt(x)));
+      return { rows: state.subs.filter((s) => ids.includes(s.id)).map((s) => ({ ...s })) };
+    }
+    if (/FROM store_subcategories WHERE id = \$1/.test(q)) return { rows: state.subs.filter((s) => s.id === String(p[0])).map((s) => ({ ...s })) };
+    if (/FROM store_subcategories WHERE status = 'approved'/.test(q)) return { rows: state.subs.filter((s) => s.status === 'approved') };
+    if (/FROM store_subcategories WHERE status <> 'merged'/.test(q)) return { rows: state.subs.filter((s) => s.status !== 'merged') };
+    if (q.startsWith('INSERT INTO store_module_categories')) {
+      state.cats.set(p[0], { module_key: p[0], parent: p[1], subcategory_id: p[2] == null ? null : String(p[2]) });
+      return { rows: [] };
+    }
+    if (/FROM store_module_categories WHERE subcategory_id = ANY/.test(q)) {
+      const ids = p[0].map(String);
+      return { rows: [...state.cats.values()].filter((c) => ids.includes(c.subcategory_id)) };
+    }
+    if (/FROM store_module_categories c LEFT JOIN/.test(q)) {
+      return { rows: [...state.cats.values()].filter((c) => p[0].includes(c.module_key)).map((c) => {
+        const s = state.subs.find((x) => x.id === c.subcategory_id);
+        return { module_key: c.module_key, parent: c.parent, sub_key: s ? s.sub_key : null, label: s ? s.label : null, status: s ? s.status : null };
+      }) };
+    }
+    if (q.startsWith("UPDATE store_subcategories SET status = 'approved'")) {
+      const s = state.subs.find((x) => x.id === String(p[0]));
+      Object.assign(s, { status: 'approved', label: p[1], sub_key: p[2], decided_by: p[3], decided_at: new Date() });
+      return { rows: [s] };
+    }
+    if (q.startsWith("UPDATE store_subcategories SET status = 'merged'")) {
+      const s = state.subs.find((x) => x.id === String(p[0]));
+      Object.assign(s, { status: 'merged', merged_into: String(p[1]), decided_by: p[2], decided_at: new Date() });
+      return { rows: [] };
+    }
+    if (q.startsWith('UPDATE store_subcategories SET merged_into')) {
+      for (const s of state.subs) if (s.merged_into === String(p[0])) s.merged_into = String(p[1]);
+      return { rows: [] };
+    }
+    if (q.startsWith('UPDATE store_module_categories')) {
+      const moved = [];
+      for (const c of state.cats.values()) {
+        if (c.subcategory_id === String(p[0])) { c.subcategory_id = String(p[1]); c.parent = p[2]; moved.push({ module_key: c.module_key }); }
+      }
+      return { rows: moved };
+    }
+    throw new Error(`fake db: unexpected SQL: ${q}`);
+  };
+  const client = { query, release() {} };
+  return { state, query, connect: async () => client, client };
+}
+
+const publish = (db, key, category, builderId = '7') => subs.recordPublishCategory(db.client, { key, category, builderId });
+
+// ---- publish proposes ------------------------------------------------------------
+
+test('publish: an unseen sub-category is proposed, not live, labelled from its key', async () => {
+  const db = fakeDb();
+  const out = await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  assert.equal(out.status, 'proposed');
+  assert.equal(out.live, false);
+  assert.equal(out.label, 'Stripe payments');
+  assert.equal(db.state.subs.length, 1);
+  assert.equal(db.state.cats.get('pay-a').subcategory_id, db.state.subs[0].id);
+});
+
+test('publish: a second module naming the same key joins the one proposal', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' }, '8');
+  assert.equal(db.state.subs.length, 1);
+  const { proposals } = await subs.reviewQueue({ db });
+  assert.deepEqual(proposals[0].modules, ['pay-a', 'pay-b']);
+});
+
+test('publish: a parent with no sub sits under the parent only; no category leaves nothing written', async () => {
+  const db = fakeDb();
+  const out = await publish(db, 'chat', { parent: 'communication' });
+  assert.deepEqual(out, { parent: 'communication', sub: null, status: null, live: false });
+  assert.equal(db.state.cats.get('chat').subcategory_id, null);
+  assert.equal(await publish(db, 'other', undefined), null);
+  assert.equal(db.state.cats.has('other'), false);
+});
+
+test('publish: naming an approved sub-category is live at once', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await subs.approveSubcategory(db.state.subs[0].id, { builderId: '1' }, { db });
+  const out = await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  assert.equal(out.live, true);
+  assert.equal(out.status, 'approved');
+});
+
+// ---- approve / rename ------------------------------------------------------------
+
+test('approve: makes a proposal live and records who decided', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  const r = await subs.approveSubcategory(db.state.subs[0].id, { builderId: '1' }, { db });
+  assert.equal(r.ok, true);
+  assert.equal(r.renamed, false);
+  assert.equal(r.subcategory.status, 'approved');
+  assert.equal(r.subcategory.decided_by, '1');
+  const cats = await subs.readModuleCategories(['pay-a'], { db });
+  assert.equal(cats.get('pay-a').live, true);
+  const listed = await subs.listSubcategories({ db });
+  assert.equal(listed.parents.length, 8);
+  assert.deepEqual(listed.parents.find((x) => x.parent === 'money').subcategories.map((s) => s.sub_key), ['stripe']);
+});
+
+test('approve: a rename takes a new label and derives its key; the module stays put', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'payments-stripe' });
+  const r = await subs.approveSubcategory(db.state.subs[0].id, { label: 'Stripe payments', builderId: '1' }, { db });
+  assert.equal(r.renamed, true);
+  assert.equal(r.subcategory.sub_key, 'stripe-payments');
+  assert.equal((await subs.readModuleCategories(['pay-a'], { db })).get('pay-a').sub, 'stripe-payments');
+});
+
+test('approve: refuses a rename onto an existing key (that is a merge), and a decided row', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe-pay' });
+  const [a, b] = db.state.subs;
+  await subs.approveSubcategory(a.id, { builderId: '1' }, { db });
+  const clash = await subs.approveSubcategory(b.id, { subKey: 'stripe', builderId: '1' }, { db });
+  assert.equal(clash.code, 'subcategory_exists');
+  assert.match(clash.message, /merge/);
+  assert.equal((await subs.approveSubcategory(a.id, { builderId: '1' }, { db })).code, 'subcategory_decided');
+  assert.equal((await subs.approveSubcategory('99', { builderId: '1' }, { db })).code, 'subcategory_not_found');
+  assert.equal((await subs.approveSubcategory(b.id, { subKey: 'Bad Key', builderId: '1' }, { db })).code, 'bad_sub_key');
+});
+
+// ---- merge -----------------------------------------------------------------------
+
+test('merge: moves every module of the merged name to the target, parent included', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'pay-c', { parent: 'work', sub: 'stripe' });
+  const [target, money, work] = db.state.subs;
+  await subs.approveSubcategory(target.id, { builderId: '1' }, { db });
+  const r1 = await subs.mergeSubcategory(money.id, { into: target.id, builderId: '1' }, { db });
+  assert.deepEqual(r1.moved, ['pay-b']);
+  const r2 = await subs.mergeSubcategory(work.id, { into: target.id, builderId: '1' }, { db });
+  assert.deepEqual(r2.moved, ['pay-c']);
+  const cats = await subs.readModuleCategories(['pay-b', 'pay-c'], { db });
+  assert.equal(cats.get('pay-b').sub, 'stripe-payments');
+  assert.equal(cats.get('pay-c').parent, 'money');
+  assert.equal(cats.get('pay-c').live, true);
+});
+
+test('merge: a later publish naming the merged key lands on the target, not a new proposal', async () => {
+  const db = fakeDb();
+  await publish(db, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'pay-b', { parent: 'money', sub: 'stripe' });
+  const [target, dup] = db.state.subs;
+  await subs.approveSubcategory(target.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(dup.id, { into: target.id, builderId: '1' }, { db });
+  const out = await publish(db, 'pay-d', { parent: 'money', sub: 'stripe' });
+  assert.equal(out.sub, 'stripe-payments');
+  assert.equal(out.live, true);
+  assert.equal(out.named, 'stripe');
+  assert.equal(db.state.subs.length, 2);
+});
+
+test('merge: an approved duplicate can be folded too, and earlier merges into it are re-pointed', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'stripe-pay' });
+  await publish(db, 'c', { parent: 'money', sub: 'stripe-payments' });
+  const [s1, s2, s3] = db.state.subs;
+  await subs.approveSubcategory(s1.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(s2.id, { into: s1.id, builderId: '1' }, { db });
+  await subs.approveSubcategory(s3.id, { builderId: '1' }, { db });
+  const r = await subs.mergeSubcategory(s1.id, { into: s3.id, builderId: '1' }, { db });
+  assert.deepEqual(r.moved, ['a', 'b']);
+  assert.equal(db.state.subs.find((s) => s.id === s2.id).merged_into, s3.id);
+});
+
+test('merge: refuses self, an unapproved target, a missing row and an already-merged one', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'paypal' });
+  const [s1, s2] = db.state.subs;
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s1.id, builderId: '1' }, { db })).code, 'merge_into_self');
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db })).code, 'merge_target_not_approved');
+  assert.equal((await subs.mergeSubcategory('99', { into: s2.id, builderId: '1' }, { db })).code, 'subcategory_not_found');
+  await subs.approveSubcategory(s2.id, { builderId: '1' }, { db });
+  await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db });
+  assert.equal((await subs.mergeSubcategory(s1.id, { into: s2.id, builderId: '1' }, { db })).code, 'subcategory_decided');
+  assert.ok(db.state.log.includes('ROLLBACK'));
+});
+
+// ---- near-duplicates ---------------------------------------------------------------
+
+test('near: "Stripe", "Stripe payments" and "Payments (Stripe)" sit beside each other; unrelated names do not', () => {
+  assert.ok(subs.isNear('Stripe', 'Stripe payments'));
+  assert.ok(subs.isNear('Stripe payments', 'Payments (Stripe)'));
+  assert.ok(subs.isNear('stripe-payment', 'Stripe payments'));
+  assert.ok(subs.isNear('stirpe', 'stripe'));
+  assert.ok(!subs.isNear('Stripe', 'Discord bots'));
+  assert.ok(!subs.isNear('Weather', 'Whether forecasts'));
+});
+
+test('queue: each proposal carries its near-duplicates across parents, never itself or a merged row', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'stripe-payments' });
+  await publish(db, 'c', { parent: 'work', sub: 'payments-stripe' });
+  await publish(db, 'd', { parent: 'communication', sub: 'discord-bots' });
+  const { proposals } = await subs.reviewQueue({ db });
+  const byKey = Object.fromEntries(proposals.map((p) => [`${p.parent}/${p.sub_key}`, p]));
+  assert.deepEqual(byKey['money/stripe'].near.map((n) => n.sub_key).sort(), ['payments-stripe', 'stripe-payments']);
+  assert.deepEqual(byKey['communication/discord-bots'].near, []);
+  assert.equal(byKey['money/stripe'].parent_title, 'Money');
+});
+
+// ---- authority ---------------------------------------------------------------------
+
+test('authority: the review routes are pinned to their own Metic+ atom, granted to metic and archon', () => {
+  const entry = catalog.byKey('module.subcategory.review');
+  assert.ok(entry, 'catalog defines module.subcategory.review');
+  assert.equal(entry.floor, 'metic');
+  assert.equal(entry.system, false);
+  const sql = fs.readFileSync(new URL('../modules/government/migrations/government_034_module_subcategory_review.sql', import.meta.url), 'utf8');
+  for (const rank of ['metic', 'archon']) assert.match(sql, new RegExp(`SELECT '${rank}', unnest\\(ARRAY\\[\\s*'module\\.subcategory\\.review'`));
+  const res = checkRouteRanks();
+  assert.equal(res.ok, true);
+  assert.deepEqual((res.findings || []).filter((f) => /subcategor/.test(JSON.stringify(f))), []);
+});
+
+test('merge: both rows are locked in one statement, in id order (no deadlock between opposite merges)', async () => {
+  const db = fakeDb();
+  await publish(db, 'a', { parent: 'money', sub: 'stripe' });
+  await publish(db, 'b', { parent: 'money', sub: 'paypal' });
+  const [s1, s2] = db.state.subs;
+  await subs.approveSubcategory(s1.id, { builderId: '1' }, { db });
+  db.state.log.length = 0;
+  await subs.mergeSubcategory(s2.id, { into: s1.id, builderId: '1' }, { db });
+  const locks = db.state.log.filter((q) => /FOR UPDATE/.test(q));
+  assert.equal(locks.length, 1);
+  assert.match(locks[0], /WHERE id = ANY\(\$1\) ORDER BY id FOR UPDATE/);
+});
+
+test('queue: bounded to the oldest hundred proposals, and says how many wait', async () => {
+  const db = fakeDb();
+  for (let i = 0; i < 105; i++) await publish(db, `m${i}`, { parent: 'work', sub: `kind-${i}` });
+  const q = await subs.reviewQueue({ db });
+  assert.equal(q.proposals.length, 100);
+  assert.equal(q.total, 105);
+  assert.equal(q.more, true);
+  assert.equal(q.proposals[0].sub_key, 'kind-0');
+});
+
+// ---- the HTTP routes, through the real router ------------------------------------
+
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+const router = buildModulesRouter();
+function route(method, p) {
+  const layer = router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${p} on the router`);
+  return layer.route.stack;
+}
+async function call(method, p, { params = {}, body = {} } = {}) {
+  const stack = route(method, p);
+  const res = {
+    statusCode: 200, body: undefined, headers: {},
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    set(k, v) { this.headers[k] = v; return this; },
+    fail(code, opts, details) { const o = typeof opts === 'number' ? { status: opts, details } : (opts || {}); this.statusCode = o.status; this.body = { error: code, ...o }; return this; },
+  };
+  let err = null;
+  await stack[stack.length - 1].handle({ params, body, query: {}, builder: { id: 3 } }, res, (e) => { err = e; });
+  if (err) throw err;
+  return res;
+}
+
+test('routes: the three review routes sit behind requireBuilder + the module.subcategory.review atom; the list behind requireBuilder only', () => {
+  const src = fs.readFileSync(new URL('../src/bongos/routes/modules.js', import.meta.url), 'utf8');
+  for (const decl of [
+    "router.get('/store/subcategories/queue'",
+    "router.post('/store/subcategories/:id/approve'",
+    "router.post('/store/subcategories/:id/merge'",
+  ]) {
+    assert.ok(src.includes(`${decl}, auth.requireBuilder, auth.requirePermission('module.subcategory.review')`), decl);
+  }
+  assert.equal(route('get', '/store/subcategories/queue').length, 3);
+  assert.equal(route('get', '/store/subcategories').length, 2);
+});
+
+test('routes: list, queue, approve and merge end to end, refusals mapped to their status', async () => {
+  routeDb = fakeDb();
+  await publish(routeDb, 'pay-a', { parent: 'money', sub: 'stripe-payments' });
+  await publish(routeDb, 'pay-b', { parent: 'money', sub: 'stripe' });
+  const [target, dup] = routeDb.state.subs;
+
+  const queue = await call('get', '/store/subcategories/queue');
+  assert.equal(queue.statusCode, 200);
+  assert.equal(queue.body.proposals.length, 2);
+  assert.equal(queue.body.proposals[0].near[0].sub_key, 'stripe');
+
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: 'x1' } })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: target.id }, body: { label: 5 } })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: '999' } })).statusCode, 404);
+  const ok = await call('post', '/store/subcategories/:id/approve', { params: { id: target.id }, body: { label: 'Stripe payments' } });
+  assert.equal(ok.statusCode, 200);
+  assert.equal(ok.body.subcategory.status, 'approved');
+  assert.equal((await call('post', '/store/subcategories/:id/approve', { params: { id: target.id } })).statusCode, 409);
+
+  const listed = await call('get', '/store/subcategories');
+  assert.equal(listed.statusCode, 200);
+  assert.deepEqual(listed.body.parents.find((x) => x.parent === 'money').subcategories.map((x) => x.sub_key), ['stripe-payments']);
+
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: {} })).statusCode, 400);
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: '0' + dup.id } })).statusCode, 400);
+  const merged = await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: Number(target.id) } });
+  assert.equal(merged.statusCode, 200);
+  assert.deepEqual(merged.body.moved, ['pay-b']);
+  assert.equal((await call('post', '/store/subcategories/:id/merge', { params: { id: dup.id }, body: { into: target.id } })).statusCode, 409);
+});