@bongos/core 1.20.52 → 1.20.54

package/modules/lifecycle/page-tweak-artist.js

@@ -0,0 +1,86 @@
+// modules/lifecycle/page-tweak-artist.js — WHO a page-tweak round belongs to,
+// written once (task 1004432 / WA6.RP02, ADR 0341 D10).
+//
+// A round has two people. The ARTIST wrote the words in the studio and holds the
+// round's WEB claim (no worktree, no creating session: the claim the submit
+// released). The APPLIER is the session that put the words into the page, on an
+// ordinary CLI claim in a worktree. The artist is the author of record: they are
+// the one paid (economy's awardArtistPageCredit), the one the changelog names
+// (page-tweak-reads.js), and, since this task, the one `tasks.shipped_by` names
+// once the round ships. The applier is a helper.
+//
+// Pure: SQL fragments and nothing else, so every reader takes the rule from here
+// instead of re-typing it. Economy cannot require this file (a module reaches
+// another only through a port), so credits.js keeps its own copy of the
+// predicate and tests/page_tweak_artist.mjs holds the two strings together.
+
+'use strict';
+
+const PAGE_TWEAK_SOURCE = 'page-tweak';
+
+// A WEB claim: the artist's. Neither a worktree (a CLI applier) nor a creating
+// session (an agent-made claim) is on it.
+function webClaimPredicate(alias = 'c') {
+  return `${alias}.worktree_name IS NULL AND ${alias}.creator_session_id IS NULL`;
+}
+
+// The newest claim first; the id breaks a same-instant tie the same way in
+// every reader.
+function latestFirst(alias = 'c') {
+  return `${alias}.claimed_at DESC, ${alias}.id DESC`;
+}
+
+// The round's artist: the builder of its latest web claim, as a scalar
+// subquery over `taskIdExpr` (a column or a bind parameter). NULL when the
+// round never had a web claim, which a caller treats as "no artist".
+function artistIdSql(taskIdExpr) {
+  return `(SELECT c.builder_id FROM claims c
+            WHERE c.task_id = ${taskIdExpr} AND ${webClaimPredicate('c')}
+            ORDER BY ${latestFirst('c')}
+            LIMIT 1)`;
+}
+
+// THE AUTHOR OF RECORD, as shipTask writes it (db-ship.js). Everywhere shipped
+// work is counted or listed reads tasks.shipped_by: the profile, the shipped
+// count, the activity log, the status page's recent list, streaks,
+// achievements, the hub rollup. For an ordinary task that is the claim holder,
+// set at confirm, and this keeps it (COALESCE with `fallbackParam`, the caller's
+// builder). For a page tweak it is the ARTIST, written at the SHIPPED flip and
+// nowhere earlier: until a round ships, shipped_by still names the applier,
+// because the rebase gate (needsRebaseTasksForBuilder, status='confirmed') must
+// refuse the session that can actually rebase, never an artist with no
+// worktree. A round with no web claim keeps its applier. Used inside
+// `UPDATE tasks`, so the row is `tasks`.
+function shippedBySql(fallbackParam) {
+  return `CASE WHEN source = '${PAGE_TWEAK_SOURCE}'
+                 THEN COALESCE(${artistIdSql('tasks.id')}, shipped_by, ${fallbackParam})
+                 ELSE COALESCE(shipped_by, ${fallbackParam}) END`;
+}
+
+// The helper beside a shipped row, for a list that shows people. The helper is
+// the round's APPLIER, the builder of its latest WORKTREE claim: display only
+// ("with help from"), never attribution or pay. A LEFT JOIN
+// LATERAL yielding helper_login and helper_display_name on a page tweak whose
+// applier is someone other than the author of record, and nothing otherwise
+// (an ordinary task, a self-applied round, a round with no worktree claim).
+// `alias` is the tasks alias of the surrounding query.
+//
+// THE COST, since it runs once per row of a feed. The source test sits inside
+// the claims scan and names only the outer row, so Postgres plans it as a
+// one-time filter: an ordinary task reads no claim at all. A page tweak's lookup
+// is idx_claims_task_all (core_263, claims (task_id)) plus a sort of that one
+// task's few claims, and the feeds are LIMITed.
+function helperJoinSql(alias = 't') {
+  return `LEFT JOIN LATERAL (
+             SELECT hb.github_login AS helper_login, hb.display_name AS helper_display_name
+               FROM (SELECT c.builder_id FROM claims c
+                      WHERE ${alias}.source = '${PAGE_TWEAK_SOURCE}'
+                        AND c.task_id = ${alias}.id AND c.worktree_name IS NOT NULL
+                      ORDER BY ${latestFirst('c')}
+                      LIMIT 1) ap
+               JOIN builders hb ON hb.id = ap.builder_id
+              WHERE ap.builder_id IS DISTINCT FROM ${alias}.shipped_by
+           ) helper ON true`;
+}
+
+module.exports = { PAGE_TWEAK_SOURCE, webClaimPredicate, latestFirst, artistIdSql, shippedBySql, helperJoinSql };

package/modules/lifecycle/page-tweak-reads.js

@@ -13,6 +13,7 @@
 
 const api = require('../../src/module-api');
 const hold = require('./page-tweak-hold');
+const artistRule = require('./page-tweak-artist');
 
 // Every page-tweak task, oldest first, with what the round state (D7) and the
 // changelog (D8) need beside the task itself:
@@ -35,9 +36,10 @@ const hold = require('./page-tweak-hold');
 //   * the active claim is a plain join: uniq_active_claim_per_task allows at
 //     most one row per task, and its partial index serves it.
 //   * the latest web claim is ONE pass over claims (the `web` CTE, DISTINCT ON
-//     per task), joined once, rather than a correlated subquery per task:
-//     claims has no full index on task_id, so a per-row LATERAL would scan it
-//     once per round.
+//     per task), joined once, rather than a correlated subquery per task.
+//     (When this was written claims had no full index on task_id; core_263 has
+//     since added idx_claims_task_all, so a per-task lookup is an index probe.
+//     The single pass stays: it is still the cheaper plan for every round at once.)
 //
 // `pageId` narrows it to ONE page's rounds (task 1004319 / TW08): the draft
 // autosave runs this on every debounced save, and a page's rounds are a handful
@@ -52,8 +54,8 @@ async function listPageTweakTasks({ pageId = null } = {}) {
      ), web AS (
        SELECT DISTINCT ON (c.task_id) c.task_id, c.builder_id
          FROM claims c JOIN pt ON pt.id = c.task_id
-        WHERE c.worktree_name IS NULL AND c.creator_session_id IS NULL
-        ORDER BY c.task_id, c.claimed_at DESC, c.id DESC
+        WHERE ${artistRule.webClaimPredicate('c')}
+        ORDER BY c.task_id, ${artistRule.latestFirst('c')}
      )
      SELECT t.id, t.status, t.title, t.description, t.source_ref, t.touches,
             t.shipped_at, t.created_at, t.updated_at,

package/modules/lifecycle/routes/tasks.js

@@ -33,6 +33,7 @@ const { depRefusalRow } = require('../dead-deps.js');
 // quality verdict rather than an outage or an errored worker (task 1002652).
 // The acclaim feed reads it so a grader outage never reaches a voter as 0.0.
 const { gradeQualityWhere } = require('../db-shared');
+const { helperJoinSql } = require('../page-tweak-artist'); // task 1004432: a page tweak's applier as a helper
 const auth = api;
 const db = require('../db');
 const pageTweakReads = require('../page-tweak-reads'); const { HELD_NOT_ARMED } = require('../page-tweak-hold'); // ADR 0341 D7 (tests stub the read)
@@ -783,6 +784,7 @@ module.exports = function buildTasksRouter() {
         `SELECT t.id, t.title, t.value_summary, t.version_id, t.status,
                 t.shipped_at, t.shipped_by,
                 b.github_login, b.display_name,
+                helper.helper_login, helper.helper_display_name,
                 COALESCE(pv.net, 0)::int AS net_votes,
                 mine.vote                AS my_vote,
                 -- task 1002835: a karma vote is uninformed without the two facts
@@ -801,6 +803,7 @@ module.exports = function buildTasksRouter() {
                 cost.total_usd          AS cost_usd
            FROM tasks t
            LEFT JOIN builders b ON b.id = t.shipped_by
+           ${helperJoinSql('t')}
            LEFT JOIN task_grades g ON g.task_id = t.id
            LEFT JOIN LATERAL (
              SELECT SUM(amount_usd) AS total_usd

package/modules/sessions/db.js

@@ -741,6 +741,10 @@ async function sessionUploadCoverage({ days, windowHours } = {}) {
         AND t.shipped_by IS NOT NULL
         AND t.shipped_at IS NOT NULL
         AND t.shipped_at >= now() - ($1 * interval '1 day')
+        -- task 1004432: a shipped page tweak names its ARTIST, who writes in the
+        -- studio and runs no session, so it can never be "covered"; the session
+        -- that applied it is the applier's, on an ordinary task of its own kind.
+        AND t.source IS DISTINCT FROM 'page-tweak'
       GROUP BY t.shipped_by, b.github_login
       ORDER BY 4 DESC`,
     [d, w]
@@ -765,6 +769,10 @@ async function shipsMissingSessionRecord({ days, windowHours, limit, builderId }
         AND t.shipped_by IS NOT NULL
         AND t.shipped_at IS NOT NULL
         AND t.shipped_at >= now() - ($1 * interval '1 day')
+        -- task 1004432: a shipped page tweak names its ARTIST, who writes in the
+        -- studio and runs no session, so it can never be "covered"; the session
+        -- that applied it is the applier's, on an ordinary task of its own kind.
+        AND t.source IS DISTINCT FROM 'page-tweak'
         AND ($3::bigint IS NULL OR t.shipped_by = $3)
         AND NOT EXISTS (
           SELECT 1

package/modules/status-ui/public/status.js

@@ -984,7 +984,9 @@ function renderShippedPage() {
     const meta = document.createElement('p');
     meta.className = 'shipped__meta';
     const by = t.display_name || t.github_login;
-    meta.textContent = `${by ? `inscribed by ${by} · ` : ''}${fmtRelativeTime(t.shipped_at)}`;
+    // task 1004432: an approved page is the artist's; the session that applied it is a helper.
+    const helper = t.helper_display_name || t.helper_login;
+    meta.textContent = `${by ? `inscribed by ${by} · ` : ''}${helper ? `with help from ${helper} · ` : ''}${fmtRelativeTime(t.shipped_at)}`;
     li.appendChild(title);
     if (thumb) li.appendChild(thumb);
     li.appendChild(meta);

package/package-lock.json

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

package/package.json

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

@@ -8429,5 +8429,17 @@
       "id": "1004475",
       "text": "Equity or shares is now also greyed out for a single-owner company and for a research entity, each with its own short reason. Only a regular for-profit company or a division of a corporation is offered equity. As before, it's"
     }
+  ],
+  "1.20.53": [
+    {
+      "id": "1004432",
+      "text": "An approved page now counts as the artist's own work everywhere the project shows who did what: their profile, their shipped count, their activity, the status page and the leaderboard. Before, the page was credited to the sess"
+    }
+  ],
+  "1.20.54": [
+    {
+      "id": "1004400",
+      "text": "The Government page now recommends a starting government and a starting set of ranks for your kind of project (game, research, business, non-profit) and its size. It only ever recommends a form you can adopt today. A team of a"
+    }
   ]
 }

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

@@ -253,6 +253,7 @@ const GOVERNMENT_PINS = {
   'PUT /government/ranks/:rankKey/permissions/:permissionKey': 'perm:government.manage',
   'DELETE /government/ranks/:rankKey/permissions/:permissionKey': 'perm:government.manage',
   'POST /government/ranks/:rankKey/reset': 'perm:government.manage',
+  'POST /government/rank-sets/apply': 'perm:government.manage',
   'POST /government/assignments': 'perm:government.manage',
   'DELETE /government/assignments/:builderId/:rankKey': 'perm:government.manage',
   // The Board Room's first route (R08 of goal 1000069 — the R04-carried pin).

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.52'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.54'; // 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/government_charter_library.mjs

@@ -24,11 +24,16 @@ test('the ladder bands track exactly the thresholds the synthesis names', () =>
   assert.equal(recommendedCharter(2).key, 'monarchy', 'this project today: two builders → the founding monarchy');
   assert.equal(recommendedCharter(3).key, 'direct-democracy', 'the circle rung starts at 3');
   assert.equal(recommendedCharter(8).key, 'direct-democracy');
-  assert.equal(recommendedCharter(9).key, 'presidential', '~9: name an executive');
-  assert.equal(recommendedCharter(49).key, 'presidential');
+  // ~9 and ~150 are where the ladder's own shapes (Presidential, Federation)
+  // cannot be adopted yet, so the recommendation names the nearest form that
+  // can — and says what is coming in `later` (task 1004400).
+  assert.equal(recommendedCharter(9).key, 'timocratic-republic', '~9: the circle gets too big');
+  assert.equal(recommendedCharter(9).later.key, 'presidential');
+  assert.equal(recommendedCharter(49).key, 'timocratic-republic');
   assert.equal(recommendedCharter(50).key, 'foundation', '~50: written charter + council');
   assert.equal(recommendedCharter(149).key, 'foundation');
-  assert.equal(recommendedCharter(150).key, 'federation', '~150: adjudication separates — federate');
+  assert.equal(recommendedCharter(150).key, 'foundation', '~150: a council carries it until federation exists');
+  assert.equal(recommendedCharter(150).later.key, 'federation');
   assert.equal(recommendedCharter(0).key, 'monarchy', 'a zero/unknown headcount fails to the founding shape');
   assert.equal(recommendedCharter('nonsense').key, 'monarchy');
 });
@@ -74,7 +79,7 @@ test('the library presents all seven structures with honest selectable marks (cl
     const entry = b.split('{ key:')[0];
     assert.ok(entry.includes('how:'), 'a selectable structure names its configuration');
   }
-  assert.match(client, /recommended at your headcount/, 'the one live datum is rendered');
+  assert.match(client, /recommended for this type and size/, 'the one live datum is rendered');
   assert.match(client, /c\.key === recommendedKey/, "the pill is driven by the SERVER's recommendation, never re-derived client-side");
   for (const t of ['Locked', 'Laddered', 'Scheduled']) {
     assert.ok(client.includes(`name: '${t}'`), `trajectory ${t} present`);
@@ -171,7 +176,8 @@ test('the recommendation names a charter the config can actually express', () =>
     const rec = recommendedCharter(n);
     const charter = by[rec.key];
     assert.ok(charter, `headcount ${n} recommends "${rec.key}", which is not in the library`);
-    if (charter.selectable) {
+    assert.ok(charter.selectable, `headcount ${n} recommends "${rec.key}", which cannot be adopted (task 1004400)`);
+    {
       assert.ok(charter.predicate !== undefined,
         `headcount ${n} recommends selectable "${rec.key}" — it must carry a checkable predicate`);
     }

package/tests/government_constitution_view.mjs

@@ -82,7 +82,10 @@ test('the read rides the vote atom, and the client renders the SERVER value (sou
   assert.equal(rrc.MODULE_EXPECTED_RANKS.government['GET /government/constitution'],
     `${rrc.PERM_PIN_PREFIX}board.vote.cast`);
   const client = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'government.js'), 'utf8');
-  assert.match(client, /fetchJson\('\/government\/constitution'\)/, 'the panel loads the resolved value');
+  // Since task 1004400 the path may carry ?type= / &headcount= (advice-only
+  // inputs for the recommendation), so constitutionPath() builds it.
+  assert.match(client, /fetchJson\(constitutionPath\(\)\)/, 'the panel loads the resolved value');
+  assert.match(client, /`\/government\/constitution\$\{qs/, 'from the constitution read, nowhere else');
   assert.ok(!/'first_ratifier'[^]*hardcod/i.test(client), 'sanity');
   assert.match(client, /loadConstitution\(\)/, 'the panel loads for everyone the page admits');
 });

package/tests/government_recommendations.mjs

@@ -0,0 +1,119 @@
+// tests/government_recommendations.mjs — recommended governments and base-rank
+// sets by project TYPE and SIZE (task 1004400, criterion wa7-government).
+//
+// The rules held here, each because the live site once broke it:
+//   • a recommendation only ever names a charter that can be ADOPTED — the
+//     ladder used to recommend Presidential (~9) and Federation (150+), and the
+//     live project, at 10 builders, was told to adopt one nobody can;
+//   • the type really changes the answer, not just the wording;
+//   • every grant a recommended rank carries is one a custom rank can hold;
+//   • a Foundation is always recommended together with the council rank it is
+//     governed through, and that rank makes a valid charter proposal.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const reco = require(path.join(ROOT, 'modules', 'government', 'recommendations.js'));
+const charter = require(path.join(ROOT, 'modules', 'government', 'charter.js'));
+const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
+const provisioning = require(path.join(ROOT, 'modules', 'provisioning', 'provisioning.js'));
+
+const TYPES = reco.PROJECT_TYPES.map((t) => t.key);
+// Every band edge, plus nonsense — the edges are where a ladder goes wrong.
+const HEADCOUNTS = [0, 1, 2, 3, 8, 9, 10, 49, 50, 149, 150, 151, 1000, -4, 'nonsense', null];
+const CUSTOM_RANK = { is_system: false, seeded_rank: null };
+
+// The hall's charter library says which charters are selectable; read it from
+// the client source, since browser code cannot be required.
+function hallSelectableKeys() {
+  const client = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'government.js'), 'utf8');
+  const lib = client.slice(client.indexOf('const CHARTERS'), client.indexOf('const TRAJECTORIES'));
+  return [...lib.matchAll(/key: '([a-z-]+)', name: '[^']+', selectable: true/g)].map((m) => m[1]);
+}
+
+test('the project types are exactly the ones a project declares at creation', () => {
+  assert.deepEqual(TYPES, provisioning.PROJECT_TYPES);
+});
+
+test('every type and size recommends a charter that can be adopted today', () => {
+  const available = charter.FORMS.filter((f) => f.available).map((f) => f.key);
+  const selectable = hallSelectableKeys();
+  assert.ok(selectable.length >= 4, 'the hall library parse found its selectable charters');
+  for (const type of [...TYPES, undefined, 'spaceship']) {
+    for (const n of HEADCOUNTS) {
+      const c = reco.recommendedCharter(n, type);
+      assert.ok(available.includes(c.key), `${type}@${n} recommends "${c.key}", which charter.js cannot adopt`);
+      assert.ok(selectable.includes(c.key), `${type}@${n} recommends "${c.key}", which the hall marks not selectable`);
+      if (c.later) assert.ok(!available.includes(c.later.key), 'a `later` shape is one that cannot be adopted yet');
+    }
+  }
+});
+
+test('the live case: a project of 10 is no longer told to adopt Presidential', () => {
+  const c = reco.recommendedCharter(10, 'not-sure');
+  assert.equal(c.key, 'timocratic-republic');
+  assert.equal(c.later.key, 'presidential', 'what the ladder would name is still said, as coming later');
+});
+
+test('the project type changes the answer, not just the words', () => {
+  assert.equal(reco.recommendedCharter(20, 'game').key, 'timocratic-republic');
+  assert.equal(reco.recommendedCharter(20, 'non-profit').key, 'foundation', 'a non-profit is governed by trustees early');
+  assert.equal(reco.recommendedRankSet('game', 5).ranks[0].rank_key, 'playtester');
+  assert.equal(reco.recommendedRankSet('research', 5).ranks[0].rank_key, 'peer-reviewer');
+  assert.equal(reco.recommendedCharter(20, 'spaceship').type, 'not-sure', 'an unknown type reads as not sure');
+});
+
+test('the rank set grows with size', () => {
+  const sizes = [1, 5, 20, 80, 200].map((n) => reco.recommendedRankSet('business', n).ranks.length);
+  assert.deepEqual(sizes, [0, 1, 2, 3, 3]);
+});
+
+test('every recommended rank is creatable and every grant is one a custom rank can hold', () => {
+  for (const type of TYPES) {
+    for (const n of HEADCOUNTS) {
+      for (const r of reco.recommendedRankSet(type, n).ranks) {
+        assert.match(r.rank_key, /^[a-z][a-z0-9-]*$/, `${r.rank_key} must be a slug the rank API accepts`);
+        assert.ok(r.rank_key.length >= 2 && r.rank_key.length <= 64);
+        assert.ok(!catalog.RANK_ORDER.includes(r.rank_key), `${r.rank_key} must not collide with a standard rank`);
+        assert.ok(r.label && r.description);
+        assert.ok(r.permissions.length > 0);
+        for (const key of r.permissions) {
+          assert.ok(catalog.byKey(key), `${r.rank_key}: ${key} is not in the catalog`);
+          assert.ok(catalog.isGrantableTo(key, CUSTOM_RANK), `${r.rank_key}: ${key} cannot be granted to a custom rank`);
+        }
+      }
+    }
+  }
+});
+
+test('a recommended Foundation always comes with its council rank, and that rank makes a valid charter', () => {
+  const live = { membership: 'rank:archon', pass_rule: 'first_ratifier', window_minutes: null, close_early_on_full_turnout: true };
+  let foundations = 0;
+  for (const type of TYPES) {
+    for (const n of HEADCOUNTS) {
+      const c = reco.recommendedCharter(n, type);
+      if (c.key !== 'foundation') { assert.equal(c.council_rank, null); continue; }
+      foundations += 1;
+      const set = reco.recommendedRankSet(type, n).ranks.map((r) => r.rank_key);
+      assert.ok(set.includes(c.council_rank), `${type}@${n}: the rank set must carry ${c.council_rank}`);
+      const built = charter.buildCharterProposal(live, { form: 'foundation', councilRank: c.council_rank });
+      assert.ok(built.ok, `${type}@${n}: ${c.council_rank} must make a valid Foundation (${built.reason})`);
+    }
+  }
+  assert.ok(foundations > 0, 'the walk reached a Foundation');
+});
+
+test('recommendationsFor carries both answers and the vocabulary to ask about another', () => {
+  const r = reco.recommendationsFor({ type: 'research', headcount: 60 });
+  assert.equal(r.type, 'research');
+  assert.equal(r.size, 'organisation');
+  assert.equal(r.charter.key, 'foundation');
+  assert.equal(r.rank_set.ranks.length, 3);
+  assert.equal(r.project_types.length, TYPES.length);
+  for (const b of r.size_bands) assert.equal(reco.sizeBandFor(b.example).key, b.key, 'each size option lands in its own band');
+});

package/tests/government_routes.mjs

@@ -60,6 +60,7 @@ test('the routes file declares the full R110 surface', () => {
     'POST /government/ranks/:rankKey/reset',
     'POST /government/assignments',
     'DELETE /government/assignments/:builderId/:rankKey',
+    'POST /government/rank-sets/apply',
   ];
   for (const key of wanted) assert.ok(declared.has(key), `missing route ${key}`);
 });
@@ -203,6 +204,7 @@ test('without government.manage EVERY route 403s (reads included)', async () =>
     ['DELETE', '/government/ranks/r/permissions/task.create'],
     ['POST', '/government/assignments'],
     ['DELETE', '/government/assignments/7/r'],
+    ['POST', '/government/rank-sets/apply'],
   ]) {
     const r = await call(method, p, method === 'GET' ? undefined : {});
     assert.equal(r.status, 403, `${method} ${p} must deny`);
@@ -243,6 +245,39 @@ test('GET /government/assignments returns builder↔role rows', async () => {
   assert.equal(r.json.assignments[0].rank_key, 'metic');
 });
 
+// --- recommended rank sets (task 1004400) -------------------------------------
+
+test('POST /government/rank-sets/apply creates the missing ranks with their grants and leaves existing ones alone', async () => {
+  const realGet = stub.getRankByKey;
+  // 'design-lead' already exists: it must be skipped, never re-granted.
+  stub.getRankByKey = async (k) => (k === 'design-lead' ? { rank_key: k, label: 'Mine', is_system: false, seeded_rank: null } : null);
+  try {
+    const r = await call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 20 });
+    assert.equal(r.status, 200);
+    assert.deepEqual(r.json.skipped, ['design-lead']);
+    assert.deepEqual(r.json.created.map((c) => c.rank_key), ['playtester']);
+    const creates = calls.filter(([k]) => k === 'createRank');
+    assert.equal(creates.length, 1);
+    assert.equal(creates[0][1].createdBy, 42, 'created_by is the session builder');
+    const grants = calls.filter(([k]) => k === 'grantRankPermission').map(([, a]) => a);
+    assert.ok(grants.length > 0 && grants.every((g) => g.rankKey === 'playtester'), 'an existing rank is never re-granted');
+    assert.ok(grants.every((g) => catalog.isGrantableTo(g.permissionKey, { is_system: false, seeded_rank: null })));
+  } finally { stub.getRankByKey = realGet; }
+});
+
+test('POST /government/rank-sets/apply needs a headcount and does nothing at founding size', async () => {
+  const bad = await call('POST', '/government/rank-sets/apply', { type: 'game' });
+  assert.equal(bad.status, 400);
+  const realGet = stub.getRankByKey;
+  stub.getRankByKey = async () => null;
+  try {
+    const solo = await call('POST', '/government/rank-sets/apply', { type: 'game', headcount: 1 });
+    assert.equal(solo.status, 200);
+    assert.deepEqual(solo.json.created, []);
+    assert.equal(calls.filter(([k]) => k === 'createRank').length, 0);
+  } finally { stub.getRankByKey = realGet; }
+});
+
 // --- create role -------------------------------------------------------------
 
 test('POST /government/ranks creates a custom role, created_by = the session builder', async () => {