@bongos/core 1.24.5 → 1.24.7

package/tests/account_linking.mjs

@@ -0,0 +1,289 @@
+// tests/account_linking.mjs — GitHub and Google as two ways into ONE account,
+// linked and unlinked by the person (task 1004995, ADR 0393/0396).
+//
+// WHY. The owner's rules: a signed-in person can link the other provider and
+// both open the same account; never remove the last way in; when emails match,
+// suggest — never join; and an account that already exists separately is said
+// plainly and never merged. And the ADR 0393 carry-over: once linking exists,
+// every GitHub sign-in must find the person first, or a GitHub account linked to
+// someone who joined with Google signs in as a second person.
+// No database, no network: a recording fake pool, a stubbed fetch for GitHub,
+// and the db-kernel functions stubbed before the files that destructure them load.
+//
+// Run:  node --test tests/account_linking.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+process.env.BONGOS_GITHUB_CLIENT_ID = process.env.BONGOS_GITHUB_CLIENT_ID || 'gh-test-client';
+process.env.BONGOS_GITHUB_CLIENT_SECRET = process.env.BONGOS_GITHUB_CLIENT_SECRET || 'gh-test-secret';
+process.env.BONGOS_OPEN_XENOS_ENROLLMENT = '1';
+
+function fakePool(script) {
+  const p = { log: [], script };
+  const run = async (sql, params = []) => {
+    p.log.push({ sql, params });
+    for (const [re, answer] of p.script) {
+      if (re.test(sql)) return typeof answer === 'function' ? answer(sql, params, p.log) : answer;
+    }
+    return { rows: [], rowCount: 0 };
+  };
+  p.query = run;
+  p.connect = async () => ({ query: run, release() {} });
+  return p;
+}
+
+// ── stubs, installed before anything destructures them ──
+const kernel = require('../src/bongos/db-kernel.js');
+const upserts = [];
+kernel.getBuilderByGithubId = async () => null;
+kernel.upsertBuilder = async (b) => { upserts.push(b); return { id: 9, github_id: String(b.githubId), github_login: b.githubLogin, status: 'active', rank: 'xenos' }; };
+kernel.createSession = async () => ({ id: 1 });
+const dbMod = require('../src/bongos/db.js');
+dbMod.createSession = kernel.createSession;
+const admission = require('../src/bongos/auth-admission.js');
+admission.safeSyncRankRole = async () => {};
+let ME = '-7';
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+const routePool = fakePool([]);
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool: routePool,
+  requireBuilder: (req, _res, next) => { req.builder = { id: 1, github_id: ME, github_login: '~ana' }; next(); },
+};
+const seams = require('../src/module-seams.js');
+const hub = { personKeyForGithub: async () => null, recordHubSignin: async () => {} };
+if (!seams.hasProvider('platform-identity.hub')) seams.registerProvider('platform-identity.hub', hub);
+const registered = seams.resolveOptional('platform-identity.hub');
+
+const logins = require('../modules/platform-identity/account-logins.js');
+const profileRoutes = require('../modules/platform-identity/routes/profile.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const { completeWebFlow } = require('../src/bongos/auth-github.js');
+const { linkLanding } = require('../src/bongos/routes/auth-link.js');
+const { renderExistingAccountHint } = require('../src/bongos/sign-in-pages.js');
+
+const dupe = () => { const e = new Error('duplicate key'); e.code = '23505'; throw e; };
+
+// ── 1. who a GitHub sign-in reaches ──────────────────────────────────────────
+
+test('a GitHub id linked to someone who joined with Google reaches THEIR key; an unknown one reaches no one', async () => {
+  const pool = fakePool([[/FROM platform_identity_account_logins l/, (_s, params) => (params[1] === '555' ? { rows: [{ account_id: 3, person_key: '-7' }] } : { rows: [] })]]);
+  assert.equal(await logins.personKeyForGithub('555', { pool }), '-7');
+  assert.equal(await logins.personKeyForGithub('556', { pool }), null);
+  assert.equal(await logins.personKeyForGithub('-7', { pool }), null, 'a minted key is never a GitHub id');
+});
+
+test('the hub’s GitHub web sign-in signs a linked GitHub account in as the person, not a second account', async () => {
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = async (url) => ({
+    ok: true,
+    json: async () => (String(url).includes('access_token') ? { access_token: 't', scope: '' } : { id: 555, login: 'ana-gh', name: 'Ana', avatar_url: null, email: 'ana@example.com' }),
+  });
+  const asked = [];
+  const signins = [];
+  registered.personKeyForGithub = async (id) => { asked.push(id); return id === '555' ? '-7' : null; };
+  registered.recordHubSignin = async (r) => { signins.push(r); };
+  upserts.length = 0;
+  try {
+    await completeWebFlow({ code: 'c', redirectUri: 'https://hub.example/cb' });
+  } finally { globalThis.fetch = realFetch; }
+  assert.deepEqual(asked, ['555'], 'the hub is asked who the GitHub id reaches, first');
+  assert.equal(upserts[0].githubId, '-7', 'the builder row is the person’s, keyed on their minted key');
+  assert.equal(upserts[0].githubLogin, 'ana-gh', 'with the real GitHub login, now that GitHub is linked');
+  assert.equal(signins[0].githubId, '-7', 'the hub account touched is the person’s');
+  assert.equal(signins[0].githubUserId, '555', 'and the GitHub way in itself is stamped as used');
+});
+
+test('with no hub (any other instance) the GitHub id is the key, exactly as before', async () => {
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = async (url) => ({ ok: true, json: async () => (String(url).includes('access_token') ? { access_token: 't' } : { id: 42, login: 'octo' }) });
+  const saved = registered.personKeyForGithub;
+  delete registered.personKeyForGithub;
+  upserts.length = 0;
+  try { await completeWebFlow({ code: 'c', redirectUri: 'https://x.example/cb' }); } finally { globalThis.fetch = realFetch; registered.personKeyForGithub = saved; }
+  assert.equal(upserts[0].githubId, '42');
+});
+
+// ── 2. linking — never a merge ───────────────────────────────────────────────
+
+const ownedBy = (key) => [/FROM platform_identity_account_logins l\s+JOIN/, key ? { rows: [{ account_id: 1, person_key: key }] } : { rows: [] }];
+
+test('a way in that already reaches ANOTHER person is refused as taken, and nothing is written', async () => {
+  const pool = fakePool([ownedBy('99')]);
+  assert.deepEqual(await logins.linkLogin({ personKey: '-7', provider: 'github', subject: '555', githubLogin: 'x' }, { pool }), { refused: 'taken' });
+  assert.equal(pool.log.filter((q) => /INSERT|UPDATE|DELETE/.test(q.sql)).length, 0);
+});
+
+test('linking what is already yours is a no-op success', async () => {
+  const pool = fakePool([ownedBy('-7')]);
+  assert.deepEqual(await logins.linkLogin({ personKey: '-7', provider: 'google', subject: 'g-1' }, { pool }), { linked: true, already: true });
+});
+
+test('linking GitHub adds the way in and writes the real login on the account', async () => {
+  const pool = fakePool([ownedBy(null), [/SELECT id FROM platform_identity_accounts WHERE github_id/, { rows: [{ id: 4 }] }]]);
+  assert.deepEqual(await logins.linkLogin({ personKey: '-7', provider: 'github', subject: '555', email: 'ana@example.com', githubLogin: 'ana-gh' }, { pool }), { linked: true, already: false });
+  const ins = pool.log.find((q) => /INSERT INTO platform_identity_account_logins/.test(q.sql));
+  assert.deepEqual(ins.params, [4, 'github', '555', 'ana@example.com']);
+  const upd = pool.log.find((q) => /UPDATE platform_identity_accounts SET github_login/.test(q.sql));
+  assert.deepEqual(upd.params, [4, 'ana-gh']);
+});
+
+test('linking Google writes no GitHub login', async () => {
+  const pool = fakePool([ownedBy(null), [/SELECT id FROM platform_identity_accounts WHERE github_id/, { rows: [{ id: 4 }] }]]);
+  await logins.linkLogin({ personKey: '42', provider: 'google', subject: 'g-1' }, { pool });
+  assert.equal(pool.log.filter((q) => /github_login/.test(q.sql) && /UPDATE/.test(q.sql)).length, 0);
+});
+
+test('a race: someone else took it a moment ago → taken; you already hold that provider → already_linked', async () => {
+  let n = 0;
+  const raced = fakePool([
+    [/FROM platform_identity_account_logins l\s+JOIN/, () => (n++ === 0 ? { rows: [] } : { rows: [{ account_id: 2, person_key: '99' }] })],
+    [/SELECT id FROM platform_identity_accounts WHERE github_id/, { rows: [{ id: 4 }] }],
+    [/INSERT INTO platform_identity_account_logins/, dupe],
+  ]);
+  assert.deepEqual(await logins.linkLogin({ personKey: '-7', provider: 'google', subject: 'g-1' }, { pool: raced }), { refused: 'taken' });
+  const held = fakePool([ownedBy(null), [/SELECT id FROM platform_identity_accounts WHERE github_id/, { rows: [{ id: 4 }] }], [/INSERT INTO platform_identity_account_logins/, dupe]]);
+  assert.deepEqual(await logins.linkLogin({ personKey: '-7', provider: 'google', subject: 'g-2' }, { pool: held }), { refused: 'already_linked' });
+});
+
+// ── 3. unlinking — never the last way in ─────────────────────────────────────
+
+test('the refusal rule: never the last way in; never GitHub from an account born with it', () => {
+  assert.equal(logins.unlinkRefusal({ personKey: '-7', provider: 'google', count: 1 }), 'last_way_in');
+  assert.equal(logins.unlinkRefusal({ personKey: '-7', provider: 'github', count: 2 }), null, 'a Google-born person may drop GitHub');
+  assert.equal(logins.unlinkRefusal({ personKey: '-7', provider: 'google', count: 2 }), null);
+  assert.equal(logins.unlinkRefusal({ personKey: '42', provider: 'github', count: 2 }), 'born_with', 'its key IS its GitHub id');
+  assert.equal(logins.unlinkRefusal({ personKey: '42', provider: 'google', count: 2 }), null);
+});
+
+const held = (...providers) => [/FOR UPDATE OF l/, { rows: providers.map((provider, i) => ({ id: 10 + i, provider, account_id: 4 })) }];
+
+test('unlink counts and deletes under one lock, and clears the GitHub login with GitHub', async () => {
+  const pool = fakePool([held('github', 'google')]);
+  assert.deepEqual(await logins.unlinkLogin({ personKey: '-7', provider: 'github' }, { pool }), { unlinked: true });
+  assert.ok(pool.log.some((q) => /BEGIN/i.test(q.sql)), 'inside a transaction');
+  assert.deepEqual(pool.log.find((q) => /DELETE FROM platform_identity_account_logins/.test(q.sql)).params, [10]);
+  assert.deepEqual(pool.log.find((q) => /SET github_login = NULL/.test(q.sql)).params, [4]);
+});
+
+test('unlink refuses the last way in, a GitHub-born account’s GitHub, and one not linked — deleting nothing', async () => {
+  for (const [key, provider, rows, want] of [
+    ['-7', 'google', ['google'], 'last_way_in'],
+    ['42', 'github', ['github', 'google'], 'born_with'],
+    ['-7', 'github', ['google'], 'not_linked'],
+  ]) {
+    const pool = fakePool([held(...rows)]);
+    assert.deepEqual(await logins.unlinkLogin({ personKey: key, provider }, { pool }), { refused: want }, `${key} ${provider}`);
+    assert.equal(pool.log.filter((q) => /^\s*(DELETE|UPDATE)/.test(q.sql)).length, 0);
+  }
+});
+
+// ── 4. a matching email suggests, never joins ────────────────────────────────
+
+test('the first-sign-in hint names providers only, and only while the identity reaches no one', async () => {
+  const pool = fakePool([ownedBy(null), [/SELECT DISTINCT provider/, { rows: [{ provider: 'github' }] }]]);
+  assert.deepEqual(await logins.existingAccountHint({ provider: 'google', subject: 'g-1', email: 'Ana@Example.com' }, { pool }), ['github']);
+  const q = pool.log.find((x) => /SELECT DISTINCT provider/.test(x.sql));
+  assert.match(q.sql, /provider <> \$1 AND lower\(email\) = lower\(\$2\)/);
+  assert.doesNotMatch(q.sql, /github_id|handle|account_id|SELECT[^F]*email/, 'it reads back no key, handle or address');
+  const known = fakePool([ownedBy('-7')]);
+  assert.deepEqual(await logins.existingAccountHint({ provider: 'google', subject: 'g-1', email: 'a@b.c' }, { pool: known }), [], 'a returning person is never stopped');
+  assert.deepEqual(await logins.existingAccountHint({ provider: 'google', subject: 'g-1', email: null }, { pool }), []);
+});
+
+test('the hint page offers the existing account or a new one, joins nothing and names no one', () => {
+  const html = renderExistingAccountHint({ githubHref: '/api/bongos/auth/web/start?via=github&return=%2Faccount%23aWaysIn', newAccountHref: '/api/bongos/auth/google/start?fresh=1' });
+  assert.match(html, /Sign in with GitHub/);
+  assert.match(html, /Make a new account with Google/);
+  assert.match(html, /href="\/api\/bongos\/auth\/google\/start\?fresh=1"/);
+  assert.match(html, /We never join accounts on our own, even when the emails match\./);
+});
+
+test('every link answer lands on the account page’s ways section', () => {
+  assert.equal(linkLanding('github', { linked: true }), '/account?linked=github#aWaysIn');
+  assert.equal(linkLanding('google', { refused: 'taken' }), '/account?link_refused=taken&provider=google#aWaysIn');
+  assert.equal(linkLanding('google', null), '/account?link_refused=failed&provider=google#aWaysIn');
+});
+
+// ── 5. the own-scoped routes ─────────────────────────────────────────────────
+
+let server; let port;
+before(async () => {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use('/api/bongos', profileRoutes());
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(() => server.close());
+const call = (method, path) => new Promise((resolve, reject) => {
+  const r = http.request({ host: '127.0.0.1', port, path, method }, (resp) => {
+    let data = ''; resp.on('data', (c) => { data += c; }); resp.on('end', () => resolve({ status: resp.statusCode, body: data ? JSON.parse(data) : null }));
+  });
+  r.on('error', reject); r.end();
+});
+
+test('GET /me/sign-in-methods says, per way in, why it cannot be removed', async () => {
+  ME = '-7';
+  routePool.script = [[/FROM platform_identity_account_logins l\s+JOIN platform_identity_accounts a ON a.id = l.account_id\s+WHERE a.github_id/, { rows: [{ provider: 'google', email: 'ana@example.com' }] }]];
+  const res = await call('GET', '/api/bongos/me/sign-in-methods');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body.methods, [{ provider: 'google', email: 'ana@example.com', unlink_refused: 'last_way_in' }]);
+});
+
+test('DELETE /me/sign-in-methods/:provider removes one, keyed on the session, and refuses in plain words', async () => {
+  ME = '-7';
+  routePool.script = [held('github', 'google')];
+  routePool.log.length = 0;
+  assert.equal((await call('DELETE', '/api/bongos/me/sign-in-methods/google')).status, 200);
+  assert.deepEqual(routePool.log.find((q) => /FOR UPDATE/.test(q.sql)).params, ['-7'], 'the person is the session’s, never a parameter');
+  routePool.script = [held('google')];
+  const last = await call('DELETE', '/api/bongos/me/sign-in-methods/google');
+  assert.equal(last.status, 409);
+  assert.equal(last.body.error.code, 'last_way_in');
+  assert.equal((await call('DELETE', '/api/bongos/me/sign-in-methods/discord')).status, 404, 'only the known providers');
+});
+
+// ── 6. Link GitHub, end to end through its callback ──────────────────────────
+
+test('Link GitHub: a GitHub account that already has its own account here is refused, never merged', async () => {
+  const auth = require('../src/bongos/auth.js');
+  const buildAuthLinkRouter = require('../src/bongos/routes/auth-link.js');
+  const linked = [];
+  registered.linkLogin = async (r) => { linked.push(r); return { linked: true, already: false }; };
+  const realSession = auth.resolveSession;
+  auth.resolveSession = async () => ({ github_id: '-7', display_name: 'Ana', status: 'active' });
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = async (url) => ({ ok: true, json: async () => (String(url).includes('access_token') ? { access_token: 't' } : { id: 555, login: 'ana-gh' }) });
+  const realGet = dbMod.getBuilderByGithubId;
+  const app = express();
+  app.use(buildAuthLinkRouter());
+  const srv = http.createServer(app);
+  await new Promise((r) => srv.listen(0, '127.0.0.1', r));
+  const hit = () => new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port: srv.address().port, path: '/auth/web/callback/link?state=s1&code=c', headers: { cookie: 'bongos_link_state=s1' } },
+      (resp) => { resp.resume(); resolve(resp.headers.location); }).on('error', reject);
+  });
+  try {
+    dbMod.getBuilderByGithubId = async (id) => (id === '555' ? { id: 3 } : null);
+    assert.equal(await hit(), '/account?link_refused=taken&provider=github#aWaysIn');
+    assert.equal(linked.length, 0, 'the hub was never asked to link it');
+    dbMod.getBuilderByGithubId = async () => null;
+    upserts.length = 0;
+    assert.equal(await hit(), '/account?linked=github#aWaysIn');
+    assert.deepEqual(linked[0], { personKey: '-7', provider: 'github', subject: '555', email: null, githubLogin: 'ana-gh' });
+    assert.equal(upserts[0].githubId, '-7');
+    assert.equal(upserts[0].githubLogin, 'ana-gh', 'the hall shows the real login from now on');
+  } finally {
+    auth.resolveSession = realSession; globalThis.fetch = realFetch; dbMod.getBuilderByGithubId = realGet; srv.close();
+  }
+});

package/tests/account_logins_db.mjs

@@ -154,6 +154,62 @@ try {
   const after = await accountRow(first.personKey);
   same([after.github_login, after.profile_state], [null, 'active'], 'the hub sign-in activates the person and writes no login');
 
+  // 9 — linking and removing ways in (task 1004995), against the real constraints
+  // and real row locks, which a fake pool cannot execute.
+  await q(migrationSql('platform_identity_035_account_login_email_idx.sql'));
+  await q(migrationSql('platform_identity_035_account_login_email_idx.sql'));
+  ok((await q(`SELECT 1 FROM pg_indexes WHERE indexname = 'platform_identity_account_logins_lower_email_idx'`)).rows.length === 1,
+    'the address index exists, and its migration re-runs safely');
+
+  const GH_LINK = '90499203'; // a GitHub id nobody holds yet
+  const ana = await logins.signInWithLogin({ provider: 'google', subject: SUB('ana'), email: 'ana@example.com', displayName: 'Ana' }, { pool });
+  const bo = await logins.signInWithLogin({ provider: 'google', subject: SUB('bo'), email: 'bo@example.com', displayName: 'Bo' }, { pool });
+
+  // Two people link the same GitHub account at once: the UNIQUE (provider, subject)
+  // decides, so exactly one gets it and the other is told it is taken.
+  const racedLinks = await Promise.all([
+    logins.linkLogin({ personKey: ana.personKey, provider: 'github', subject: GH_LINK, githubLogin: 'ana-gh' }, { pool }),
+    logins.linkLogin({ personKey: bo.personKey, provider: 'github', subject: GH_LINK, githubLogin: 'ana-gh' }, { pool }),
+  ]);
+  same(racedLinks.map((r) => (r.linked ? 'linked' : r.refused)).sort(), ['linked', 'taken'], 'two people racing for one GitHub account: one links, one is refused, nothing merges');
+  const winner = racedLinks[0].linked ? ana : bo;
+  const loser = racedLinks[0].linked ? bo : ana;
+  same((await accountRow(winner.personKey)).github_login, 'ana-gh', 'the winner’s account now shows the real GitHub login');
+  same((await accountRow(loser.personKey)).github_login, null, 'the other account is untouched');
+  same(await logins.personKeyForGithub(GH_LINK, { pool }), winner.personKey, 'a GitHub sign-in with that id now reaches the winner');
+  same(await logins.linkLogin({ personKey: loser.personKey, provider: 'github', subject: GH_LINK, githubLogin: 'x' }, { pool }), { refused: 'taken' },
+    'linking it again later is still refused');
+  same(await logins.linkLogin({ personKey: winner.personKey, provider: 'github', subject: '90499204', githubLogin: 'y' }, { pool }), { refused: 'already_linked' },
+    'a person holds one GitHub way in; a second is refused by the database');
+
+  // Two removals at once on a person with two ways in: the row lock serialises
+  // them, so exactly one goes and the other finds it would be the last.
+  const removed = await Promise.all([
+    logins.unlinkLogin({ personKey: winner.personKey, provider: 'google' }, { pool }),
+    logins.unlinkLogin({ personKey: winner.personKey, provider: 'github' }, { pool }),
+  ]);
+  same(removed.filter((r) => r.unlinked).length, 1, 'two racing removals: exactly one goes through');
+  same(removed.filter((r) => r.refused === 'last_way_in').length, 1, 'the other is refused as the last way in');
+  same((await logins.listLoginsForPerson(winner.personKey, { pool })).length, 1, 'the person keeps one way in');
+
+  // GitHub never comes off an account born with it (its key IS its GitHub id).
+  same(await logins.unlinkLogin({ personKey: String(GH), provider: 'github' }, { pool }), { refused: 'born_with' }, 'a GitHub-born account keeps GitHub');
+  same((await logins.listLoginsForPerson(String(GH), { pool })).map((m) => m.provider), ['github', 'google'], 'and nothing was deleted');
+
+  // A GitHub way in removed from a person who joined with Google clears the login.
+  const cy = await logins.signInWithLogin({ provider: 'google', subject: SUB('cy'), email: 'cy@example.com', displayName: 'Cy' }, { pool });
+  await logins.linkLogin({ personKey: cy.personKey, provider: 'github', subject: '90499205', githubLogin: 'cy-gh' }, { pool });
+  same(await logins.unlinkLogin({ personKey: cy.personKey, provider: 'github' }, { pool }), { unlinked: true }, 'a linked GitHub comes off a Google-born person');
+  same([(await accountRow(cy.personKey)).github_login, await logins.personKeyForGithub('90499205', { pool })], [null, null],
+    'their login is cleared and that GitHub id reaches no one again');
+
+  // The first-sign-in hint: the address another way in shows, provider names only.
+  await logins.touchGithubLogin({ githubId: String(GH), email: 'Octo-GH@Example.com' }, { pool });
+  same(await logins.existingAccountHint({ provider: 'google', subject: SUB('newcomer'), email: 'octo-gh@example.com' }, { pool }), ['github'],
+    'a new Google identity with a GitHub way in’s address (any case) is offered GitHub');
+  same(await logins.existingAccountHint({ provider: 'google', subject: SUB('octo'), email: 'octo-gh@example.com' }, { pool }), [],
+    'a Google identity that already reaches someone is never stopped');
+
   console.log(`\naccount_logins_db.mjs: ${pass} passed`);
 } finally {
   await cleanup();

package/tests/autopickup_cap.mjs

@@ -2,7 +2,8 @@
 // (task 1004677 / BV2.TW19a, ADR 0371 D3, D5, D6).
 //
 // Pinned here (DB-free; the race lives in tests/autopickup_cap_db.mjs):
-//   1. the two parsers and the resolver: off by default, cap 20 by default, an
+//   1. the parsers and the resolver: off by default, cap 200 by default (task
+//      1005003; it was 20), per-rank caps read from one JSON row, an
 //      unusable stored value reported and never thrown, a dead DB answers defaults;
 //   2. the refusal ladder: not a tweak, switch off, round limit, monthly cap, and the
 //      lock is taken BEFORE either count;
@@ -35,7 +36,12 @@ async function withPool(query, fn) {
   pool.query = query;
   try { return await fn(); } finally { pool.query = saved; }
 }
-const settingsRows = (map) => async (_sql, [key]) => ({ rows: key in map ? [{ key, value: map[key] }] : [] });
+// Answers both the single-key read (getSetting) and the one-query batch read
+// (key = ANY($1)) that resolveTweakAutopickup makes.
+const settingsRows = (map) => async (_sql, [key]) => {
+  const keys = Array.isArray(key) ? key : [key];
+  return { rows: keys.filter((k) => k in map).map((k) => ({ key: k, value: map[k] })) };
+};
 
 // ---- 1. the setting ---------------------------------------------------------
 
@@ -50,11 +56,11 @@ test('the parsers accept exactly off|on and a whole positive cap', () => {
   assert.match(parseAutopickupCap('100000').reason, /out of range/);
 });
 
-test('an untouched project is off with a cap of 20', async () => {
+test('an untouched project is off with a cap of 200 and no rank caps', async () => {
   assert.equal(DEFAULT_AUTOPICKUP, 'off');
-  assert.equal(DEFAULT_AUTOPICKUP_CAP, 20);
+  assert.equal(DEFAULT_AUTOPICKUP_CAP, 200);
   const r = await withPool(settingsRows({}), () => resolveTweakAutopickup());
-  assert.deepEqual(r, { mode: 'off', cap: 20, source: { mode: 'default', cap: 'default' }, invalid: [] });
+  assert.deepEqual(r, { mode: 'off', cap: 200, rank_caps: {}, source: { mode: 'default', cap: 'default' }, invalid: [] });
   assert.match(describeTweakAutopickup(r), /waits until a person/);
 });
 
@@ -63,7 +69,7 @@ test('stored values are read; an unusable one is reported and falls back', async
     () => resolveTweakAutopickup());
   assert.equal(r.mode, 'on');
   assert.equal(r.source.mode, 'project_settings');
-  assert.equal(r.cap, 20);
+  assert.equal(r.cap, 200);
   assert.equal(r.invalid.length, 1);
   assert.equal(r.invalid[0].raw, 'lots');
   assert.match(describeTweakAutopickup({ mode: 'on', cap: 7 }), /up to 7 a month/);
@@ -72,7 +78,7 @@ test('stored values are read; an unusable one is reported and falls back', async
 test('a database that cannot be read answers the defaults', async () => {
   const r = await withPool(async () => { throw new Error('db down'); }, () => resolveTweakAutopickup());
   assert.equal(r.mode, 'off');
-  assert.equal(r.cap, 20);
+  assert.equal(r.cap, 200);
 });
 
 // ---- 2. the refusal ladder --------------------------------------------------
@@ -128,7 +134,7 @@ test('the monthly cap refuses at the cap and admits below it', async () => {
 test('claimTask runs the gate before the insert, and names the column only on a marked claim', () => {
   const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'db-claims.js'), 'utf8');
   const body = src.slice(src.indexOf('async function claimTask('), src.indexOf('async function claimTasksBatch'));
-  const gate = body.indexOf('autoPickupRefusal(client, task, autoPickupSettings)');
+  const gate = body.indexOf('autoPickupRefusal(client, task, autoPickupSettings, builderRank)');
   const insert = body.indexOf('INSERT INTO claims');
   assert.ok(gate > 0 && insert > gate, 'the gate runs inside the transaction, before the insert');
   assert.match(body.slice(gate, insert), /if \(refusal\) throw refusal;/, 'a refusal stops the claim');
@@ -155,15 +161,19 @@ const fakeRes = () => ({
   json(p) { this.payload = p; return this; },
 });
 
-function buildRouter({ used = 4 } = {}) {
+function buildRouter({ used = 4, rankCaps = {} } = {}) {
   const ps = api.projectSettings;
   const saved = { resolve: ps.resolveTweakAutopickup, set: ps.set };
   const writes = [];
-  const state = { mode: 'off', cap: 20 };
+  const state = { mode: 'off', cap: 20, rank_caps: { ...rankCaps } };
   ps.resolveTweakAutopickup = async () => ({ ...state, source: { mode: 'default', cap: 'default' }, invalid: [] });
   ps.set = async (key, value, by) => {
     writes.push({ key, value, by });
-    if (key === 'tweak.autopickup') state.mode = value; else state.cap = value;
+    if (key === 'tweak.autopickup') state.mode = value;
+    else if (key.startsWith('tweak.autopickup_rank_cap.')) {
+      const rank = key.slice('tweak.autopickup_rank_cap.'.length);
+      if (value === '') delete state.rank_caps[rank]; else state.rank_caps[rank] = value;
+    } else state.cap = value;
   };
   const autopickup = require('../modules/lifecycle/autopickup.js');
   const savedCount = autopickup.countThisMonth;
@@ -234,3 +244,185 @@ test('core_275 is additive: one nullable column, recorded in schema_migrations',
   assert.doesNotMatch(sql, /NOT NULL|DROP /);
   assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('core_275_claims_auto_pickup'\)/);
 });
+
+// ---- 5. the cap per project and per builder rank (task 1005003) ------------
+
+const { rankCapKey } = require('../src/bongos/project-settings.js');
+const { effectiveCap } = require('../modules/lifecycle/autopickup.js');
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+
+test('a project override and a rank override are both read, in ONE query', async () => {
+  assert.equal(rankCapKey('xenos'), 'tweak.autopickup_rank_cap.xenos');
+  let queries = 0;
+  const rows = settingsRows({
+    [SETTING_KEYS.TWEAK_AUTOPICKUP]: 'on',
+    [SETTING_KEYS.TWEAK_AUTOPICKUP_CAP]: '40',
+    'tweak.autopickup_rank_cap.xenos': '5',
+    'tweak.autopickup_rank_cap.archon': '80',
+    'tweak.autopickup_rank_cap.metic': '', // cleared: follows the project cap
+    'tweak.autopickup_rank_cap.olympian': '9', // off the live ladder: never read
+  });
+  const r = await withPool(async (sql, params) => { queries += 1; return rows(sql, params); }, () => resolveTweakAutopickup());
+  assert.equal(queries, 1, 'mode, cap and every rank cap come back in one round trip');
+  assert.equal(r.cap, 40);
+  assert.deepEqual(r.rank_caps, { xenos: 5, archon: 80 });
+  assert.deepEqual(r.invalid, []);
+  assert.equal(describeTweakAutopickup(r),
+    'On: a running Autobongos runner applies submitted pages on its own, up to 40 a month. Some builder ranks have their own limit: xenos 5, archon 80. The artist still approves every one.');
+
+  const bad = await withPool(settingsRows({ 'tweak.autopickup_rank_cap.xenos': '-1' }), () => resolveTweakAutopickup());
+  assert.deepEqual(bad.rank_caps, {}, 'an unusable rank row falls back to the project cap');
+  assert.equal(bad.invalid.length, 1);
+  assert.equal(bad.invalid[0].where, "project_settings['tweak.autopickup_rank_cap.xenos']");
+});
+
+test('the effective cap is the rank\'s own cap, else the project cap', () => {
+  const s = { mode: 'on', cap: 200, rank_caps: { xenos: 5 } };
+  assert.deepEqual(effectiveCap(s, 'xenos'), { cap: 5, from: 'rank' });
+  assert.deepEqual(effectiveCap(s, 'metic'), { cap: 200, from: 'project' });
+  assert.deepEqual(effectiveCap(s, null), { cap: 200, from: 'project' });
+  assert.deepEqual(effectiveCap({ cap: 200 }, 'xenos'), { cap: 200, from: 'project' }, 'no rank caps at all');
+});
+
+test('the default cap of 200 admits round 199 and refuses at 200', async () => {
+  const s = { mode: 'on', cap: DEFAULT_AUTOPICKUP_CAP, rank_caps: {} };
+  assert.equal(await autoPickupRefusal(fakeClient({ month: 199 }), tweak, s, 'metic'), null);
+  const r = await autoPickupRefusal(fakeClient({ month: 200 }), tweak, s, 'metic');
+  assert.equal(r.code, 'AUTO_PICKUP_CAP_REACHED');
+  assert.equal(r.cap, 200);
+  assert.equal(r.cap_from, 'project');
+  assert.equal(r.message, 'Auto-pickup has used this month\'s 200 rounds, so submitted pages wait for a person until next month.');
+});
+
+test('a rank override replaces the project cap for that rank only, both ways', async () => {
+  const s = { mode: 'on', cap: 50, rank_caps: { xenos: 10, archon: 80 } };
+  // lower than the project cap: refuses a xenos runner where a metic one is admitted
+  const lower = await autoPickupRefusal(fakeClient({ month: 10 }), tweak, s, 'xenos');
+  assert.equal(lower.code, 'AUTO_PICKUP_CAP_REACHED');
+  assert.equal(lower.cap, 10);
+  assert.equal(lower.cap_from, 'rank');
+  assert.match(lower.message, /reached 10, the limit this project sets for a xenos builder's runner, so submitted pages wait for a person/);
+  assert.equal(await autoPickupRefusal(fakeClient({ month: 10 }), tweak, s, 'metic'), null);
+  // higher than the project cap: admits an archon runner past the project's number
+  assert.equal(await autoPickupRefusal(fakeClient({ month: 60 }), tweak, s, 'archon'), null);
+  assert.equal((await autoPickupRefusal(fakeClient({ month: 60 }), tweak, s, 'metic')).code, 'AUTO_PICKUP_CAP_REACHED');
+});
+
+test('claimTask passes the claimer\'s rank, read inside the transaction, to the gate', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'db-claims.js'), 'utf8');
+  const body = src.slice(src.indexOf('async function claimTask('), src.indexOf('async function claimTasksBatch'));
+  const rankRead = body.indexOf('const builderRank = builderRows[0] ? builderRows[0].rank : null;');
+  const gate = body.indexOf('autoPickupRefusal(client, task, autoPickupSettings, builderRank)');
+  assert.ok(rankRead > 0 && gate > rankRead);
+});
+
+test('the read reports the caller\'s own cap and what is left of it', async () => {
+  const { route, restore } = buildRouter({ used: 4, rankCaps: { xenos: 6 } });
+  try {
+    const get = handler(route('get', '/project-settings/tweak-autopickup'));
+    const x = fakeRes();
+    await get({ builder: { id: 1, rank: 'xenos' } }, x);
+    assert.deepEqual([x.payload.my_cap, x.payload.my_cap_from, x.payload.remaining_this_month], [6, 'rank', 2]);
+    assert.deepEqual(x.payload.rank_caps, { xenos: 6 });
+    const m = fakeRes();
+    await get({ builder: { id: 2, rank: 'metic' } }, m);
+    assert.deepEqual([m.payload.my_cap, m.payload.my_cap_from, m.payload.remaining_this_month], [20, 'project', 16]);
+  } finally { restore(); }
+});
+
+test('rank_caps is a partial update: a number sets, null clears, an unnamed rank is kept', async () => {
+  const { route, writes, restore } = buildRouter({ rankCaps: { xenos: 5, thetes: 9 } });
+  try {
+    const patch = handler(route('patch', '/project-settings/tweak-autopickup'));
+    const res = fakeRes();
+    await patch({ body: { rank_caps: { metic: 30, xenos: null } }, builder: { id: 7, rank: 'metic' } }, res);
+    assert.equal(res.code, null);
+    // One single-row upsert per named rank — never a read-modify-write of a shared
+    // object, so it cannot overwrite a rank someone else is editing at the same time.
+    assert.deepEqual(writes, [
+      { key: 'tweak.autopickup_rank_cap.metic', value: 30, by: 7 },
+      { key: 'tweak.autopickup_rank_cap.xenos', value: '', by: 7 },
+    ]);
+    assert.deepEqual(res.payload.rank_caps, { thetes: 9, metic: 30 });
+    assert.equal(res.payload.my_cap, 30);
+  } finally { restore(); }
+});
+
+test('two people saving two different ranks at once both keep their edit', async () => {
+  const { route, restore } = buildRouter();
+  try {
+    const patch = handler(route('patch', '/project-settings/tweak-autopickup'));
+    const a = fakeRes();
+    const b = fakeRes();
+    await Promise.all([
+      patch({ body: { rank_caps: { xenos: 5 } }, builder: { id: 7 } }, a),
+      patch({ body: { rank_caps: { archon: 80 } }, builder: { id: 8 } }, b),
+    ]);
+    const after = fakeRes();
+    await handler(route('get', '/project-settings/tweak-autopickup'))({ builder: { id: 9, rank: 'metic' } }, after);
+    assert.deepEqual(after.payload.rank_caps, { xenos: 5, archon: 80 });
+  } finally { restore(); }
+});
+
+test('an unknown rank or a bad rank number writes nothing, the project cap included', async () => {
+  const { route, writes, restore } = buildRouter();
+  try {
+    const patch = handler(route('patch', '/project-settings/tweak-autopickup'));
+    const unknown = fakeRes();
+    await patch({ body: { cap: 100, rank_caps: { olympian: 5 } }, builder: { id: 7 } }, unknown);
+    assert.equal(unknown.code, 'bad_tweak_autopickup');
+    assert.match(unknown.payload.message, /unknown rank 'olympian'/);
+    const zero = fakeRes();
+    await patch({ body: { cap: 100, rank_caps: { xenos: 0 } }, builder: { id: 7 } }, zero);
+    assert.match(zero.payload.message, /rank_caps\.xenos: must be positive/);
+    assert.equal(writes.length, 0);
+  } finally { restore(); }
+});
+
+// The server's permission check on the write, run for real: the route's own
+// requirePermission layer, against a stub government port (the
+// tests/government_require_permission.mjs double). Whoever holds
+// project.settings.manage — the project owner, or anyone granted it — passes; a
+// builder without it is refused with 403 before the handler runs.
+async function runWriteGate(heldKeys) {
+  const { route, restore } = buildRouter();
+  try {
+    const stack = route('patch', '/project-settings/tweak-autopickup').stack;
+    const gate = stack[1].handle;
+    assert.equal(gate.name, 'permissionGate', 'the second layer is the kernel permission gate');
+    seams._reset();
+    seams.registerProvider('government', { resolveBuilderPermissions: async () => heldKeys });
+    const res = { _status: null, _json: null, status(c) { this._status = c; return this; }, json(b) { this._json = b; return this; } };
+    attachFail({}, res, () => {});
+    let passed = false;
+    await gate({ builder: { id: 7, rank: 'metic' }, body: { rank_caps: { xenos: 5 } } }, res, () => { passed = true; });
+    return { passed, res };
+  } finally { seams._reset(); restore(); }
+}
+
+test('a builder holding project.settings.manage may set the caps', async () => {
+  const { passed, res } = await runWriteGate(['project.settings.manage']);
+  assert.equal(passed, true);
+  assert.equal(res._status, null);
+});
+
+test('a builder without project.settings.manage is refused', async () => {
+  const { passed, res } = await runWriteGate(['idea.triage']);
+  assert.equal(passed, false);
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+  assert.deepEqual(res._json.error.details.required, ['project.settings.manage']);
+});
+
+test('the settings page row offers the project cap and one box per live rank', () => {
+  const { tweakCapRow } = require('../modules/lifecycle/routes/project-settings.js');
+  const row = tweakCapRow({ mode: 'off', cap: 200, rank_caps: { xenos: 5 }, source: { cap: 'default' }, invalid: [] });
+  assert.equal(row.key, 'tweak_round_cap');
+  assert.equal(row.editable, true);
+  assert.equal(row.value.cap, 200);
+  assert.deepEqual(row.value.ranks, api.LIVE_RANK_LADDER.map((rank) => ({ rank, cap: rank === 'xenos' ? 5 : null })));
+  const page = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'project-settings.js'), 'utf8');
+  assert.match(page, /row\.key === 'tweak_round_cap'/);
+  assert.match(page, /sendJson\('PATCH', '\/project-settings\/tweak-autopickup', \{ cap: Number\(\$\('ps-tweak-cap'\)\.value\), rank_caps: rankCaps \}\)/);
+});