@bongos/core 1.20.83 → 1.21.2

package/tests/craft_achievements.mjs

@@ -0,0 +1,349 @@
+// tests/craft_achievements.mjs — achievements for artist and ideator moments
+// (task 1004438 / WA6.RP08, goal 1000095, criterion wa6-roles-read-true-in-public).
+//
+// The done-when: "fixtures earn each new achievement exactly once, and existing
+// artists and ideators get theirs on backfill". Run for real:
+//
+//   1. THE CATALOG. migrations/core_270 seeds seven craft achievements, renames the
+//      misleading art-pipeline-shipper, and its LIKE literals are economy's own
+//      reason prefixes (a drift there awards nothing and errors nowhere).
+//   2. THE RECONCILE. The REAL reconcileBuilderAchievements over a stateful fake
+//      ledger: an ideator and an artist earn each badge at its threshold, and a
+//      second and third reconcile unlock nothing more.
+//   3. THE WRITERS. The REAL awardIdeaFullPassCredit and awardArtistPageCredit pay
+//      the payee AND put the moment on their shelf — the payment happens inside
+//      someone else's ship, so the shipper's reconcile would never reach them —
+//      and a reconcile that throws never fails the payment.
+//   4. THE BACKFILL. The migration's backfill statements key on the same facts and
+//      stamp the FIRST qualifying credit, idempotently.
+//   5. THE PICTURES. The roster's and the status page's emoji maps carry every id
+//      with the migration's own icon.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const ROOT = fileURLToPath(new URL('..', import.meta.url));
+const { test, summary } = makeRunner();
+const read = (f) => fs.readFileSync(path.join(ROOT, f), 'utf8').replace(/\r\n/g, '\n');
+const MIGRATION = read('migrations/core_270_craft_achievements.sql');
+const seams = require('../src/module-seams.js');
+const achievements = require('../modules/economy/achievements.js');
+const credits = require('../modules/economy/credits.js');
+
+const CRAFT = ['first-thought-ignited', 'first-full-idea', 'first-board-ratification', 'thought-built-ten',
+  'first-page-approved', 'ten-pages-approved', 'whole-surface-tweaked'];
+
+// the catalog rows, read out of the migration's VALUES list
+function catalog() {
+  const out = new Map();
+  for (const m of MIGRATION.matchAll(/\('([a-z0-9-]+)', '([^']+)',\s*'([^']*)',\s*'([^']+)', (\d+), (\d+)\)/g)) {
+    out.set(m[1], { id: m[1], name: m[2], description: m[3], icon: m[4], credit_bonus: Number(m[5]), sort_order: Number(m[6]) });
+  }
+  return out;
+}
+const CATALOG = catalog();
+
+// ---- a stateful fake ledger ---------------------------------------------------------
+// Understands exactly the statements the reconcile and the two writers send; every
+// other read answers "nothing" (the engineer evaluators find no claims, no streak).
+const likeRe = (pat) => new RegExp('^' + pat.replace(/[.*+?^${}()|[\]]/g, (c) => `\\${c}`).replace(/\\\\_/g, '_').replace(/%/g, '.*') + '$');
+function fakeLedger({ failReconcile = false } = {}) {
+  const ledger = [];
+  const unlocked = [];
+  const sql = [];
+  let nextId = 1;
+  const rowsFor = (builderId, pat) => ledger.filter((r) => String(r.builder_id) === String(builderId) && likeRe(pat).test(r.reason) && r.delta > 0);
+  const client = {
+    ledger, unlocked, sql,
+    async query(text, params = []) {
+      const q = text.replace(/\s+/g, ' ').trim();
+      sql.push(q);
+      if (/^(SAVEPOINT|RELEASE SAVEPOINT|ROLLBACK TO SAVEPOINT)/.test(q)) return { rows: [], rowCount: 0 };
+      if (q.startsWith('SELECT 1 FROM builder_achievements WHERE builder_id=$1 AND achievement_id=$2')) {
+        if (failReconcile) throw new Error('reconcile blew up');
+        const hit = unlocked.some((u) => String(u.builder_id) === String(params[0]) && u.achievement_id === params[1]);
+        return { rows: hit ? [{}] : [], rowCount: hit ? 1 : 0 };
+      }
+      if (q.startsWith('SELECT id, name, credit_bonus FROM achievements WHERE id=$1')) {
+        const a = CATALOG.get(params[0]) || (params[0] === 'first-ship' ? null : null);
+        return a ? { rows: [a], rowCount: 1 } : { rows: [], rowCount: 0 };
+      }
+      if (q.startsWith('INSERT INTO builder_achievements')) {
+        if (!unlocked.some((u) => String(u.builder_id) === String(params[0]) && u.achievement_id === params[1])) {
+          unlocked.push({ builder_id: String(params[0]), achievement_id: params[1], task: params[2] });
+        }
+        return { rows: [], rowCount: 1 };
+      }
+      if (q.startsWith('INSERT INTO credit_log')) {
+        // the writers' INSERT ... SELECT ... WHERE NOT EXISTS (per builder+reason, or task+reason)
+        const [builderId, taskId, delta, reason, description] = params;
+        const exists = q.includes('WHERE task_id = $2 AND reason = $4')
+          ? ledger.some((r) => String(r.task_id) === String(taskId) && r.reason === reason)
+          : ledger.some((r) => String(r.builder_id) === String(builderId) && r.reason === reason);
+        if (exists) return { rows: [], rowCount: 0 };
+        ledger.push({ id: nextId++, builder_id: String(builderId), task_id: taskId, delta, reason, description: description || '' });
+        return { rows: [], rowCount: 1 };
+      }
+      if (q.startsWith('SELECT achievement_id FROM builder_achievements WHERE builder_id = $1 AND achievement_id = ANY($2::text[])')) {
+        if (failReconcile) throw new Error('reconcile blew up');
+        return { rows: unlocked.filter((u) => u.builder_id === String(params[0]) && params[1].includes(u.achievement_id)).map((u) => ({ achievement_id: u.achievement_id })) };
+      }
+      if (q.startsWith('SELECT bool_or(reason LIKE $2) AS ignited')) {
+        // the craft facts, computed the way the statement says: one row of aggregates
+        const [b, ship, full, board, page] = params;
+        const byIdea = new Map();
+        for (const r of rowsFor(b, ship)) {
+          const [, idea, task] = r.reason.split(':');
+          if (!byIdea.has(idea)) byIdea.set(idea, new Set());
+          byIdea.get(idea).add(task);
+        }
+        return {
+          rows: [{
+            ignited: rowsFor(b, ship).length > 0 ? true : null,
+            full_idea: rowsFor(b, full).length > 0 ? true : null,
+            ratified: rowsFor(b, board).length > 0 ? true : null,
+            pages: rowsFor(b, page).length,
+            best_thought_tasks: Math.max(0, ...[...byIdea.values()].map((s) => s.size)),
+          }],
+          rowCount: 1,
+        };
+      }
+      if (q.startsWith('SELECT DISTINCT builder_id FROM credit_log')) {
+        const pats = params.slice(0, 4).map(likeRe);
+        const ids = [...new Set(ledger.filter((r) => r.delta > 0 && pats.some((re) => re.test(r.reason))).map((r) => r.builder_id))].sort();
+        return { rows: ids.map((builder_id) => ({ builder_id })) };
+      }
+      if (q.startsWith('SELECT COUNT(*)::int AS n FROM credit_log')) return { rows: [{ n: 0 }], rowCount: 1 };
+      if (q.startsWith('SELECT total_credits FROM builders')) return { rows: [{ total_credits: 0 }], rowCount: 1 };
+      // a page-tweak task read by awardArtistPageCredit
+      if (q.includes('FROM tasks t') && q.includes('artist_id')) {
+        return { rows: [{ source: 'page-tweak', status: 'shipped', credits_reward: 30, kind: 'feature', artist_id: '2001' }], rowCount: 1 };
+      }
+      return { rows: [], rowCount: 0 };
+    },
+  };
+  return client;
+}
+const pay = (client, builderId, reason, delta = 5, task = null) => client.ledger.push({ id: client.ledger.length + 1000, builder_id: String(builderId), task_id: task, delta, reason, description: '' });
+const shelf = (client, builderId) => client.unlocked.filter((u) => u.builder_id === String(builderId)).map((u) => u.achievement_id).sort();
+const craftShelf = (client, builderId) => shelf(client, builderId).filter((id) => CRAFT.includes(id));
+
+// ---- 1. the catalog -------------------------------------------------------------------
+
+await test('the migration seeds seven craft achievements, paying no bonus, and renames the art-pipeline badge', () => {
+  assert.deepEqual([...CATALOG.keys()].sort(), [...CRAFT].sort());
+  for (const a of CATALOG.values()) assert.equal(a.credit_bonus, 0, `${a.id}: recognition only, no minted credits on backfill`);
+  assert.match(MIGRATION, /UPDATE achievements\s+SET name = 'Art Pipeline Engineer'[\s\S]*icon = '🛠️'\s+WHERE id = 'art-pipeline-shipper'/);
+  assert.equal(CATALOG.get('first-page-approved').icon, '🎨', 'the palette is the artist\'s now');
+  const ids = achievements.STATE_EVALUATORS ? achievements.STATE_EVALUATORS.map((e) => e.id) : null;
+  if (ids) for (const id of CRAFT) assert.ok(ids.includes(id), `${id} has an evaluator`);
+});
+
+await test('the migration\'s LIKE literals are economy\'s own reason prefixes, escaped', () => {
+  const lit = (p) => p.replace(/_/g, '\\_') + '%';
+  for (const p of [credits.IDEA_STREAM_REASON_PREFIXES.task_ship, credits.IDEA_STREAM_REASON_PREFIXES.full_pass,
+    credits.IDEA_STREAM_REASON_PREFIXES.governance_pass, credits.ARTIST_PAGE_REASON_PREFIX]) {
+    assert.ok(MIGRATION.includes(`LIKE '${lit(p)}'`), `the backfill spells ${p}`);
+    assert.ok(read('modules/economy/achievements.js').includes(lit(p).replace(/\\/g, '\\\\')), `the evaluator spells ${p}`);
+  }
+});
+
+// ---- 2. the reconcile -----------------------------------------------------------------
+
+await test('an ideator earns each idea badge at its threshold, exactly once', async () => {
+  seams._reset();
+  const c = fakeLedger();
+  const IDE = '2002';
+  await achievements.reconcileBuilderAchievements(c, IDE);
+  assert.deepEqual(craftShelf(c, IDE), [], 'nothing for a builder the ledger has paid nothing');
+  pay(c, IDE, 'idea.credit.task_ship:7:101');
+  pay(c, IDE, 'idea.credit.full_pass:7');
+  pay(c, IDE, 'idea.credit.governance_pass:7');
+  for (let t = 1; t <= 9; t++) pay(c, IDE, `idea.credit.task_ship:8:${200 + t}`);
+  await achievements.reconcileBuilderAchievements(c, IDE);
+  assert.deepEqual(craftShelf(c, IDE), ['first-board-ratification', 'first-full-idea', 'first-thought-ignited'],
+    'nine tasks under one thought (plus one under another) is not ten from one');
+  pay(c, IDE, 'idea.credit.task_ship:8:210');
+  pay(c, IDE, 'idea.credit.task_ship:8:210', 3); // a second payee row for the same task is not a second task
+  await achievements.reconcileBuilderAchievements(c, IDE);
+  await achievements.reconcileBuilderAchievements(c, IDE);
+  assert.deepEqual(craftShelf(c, IDE), ['first-board-ratification', 'first-full-idea', 'first-thought-ignited', 'thought-built-ten']);
+  assert.equal(c.unlocked.length, new Set(c.unlocked.map((u) => u.achievement_id)).size, 'each exactly once');
+});
+
+await test('an artist earns First Page, Ten Pages and A Whole Surface, exactly once', async () => {
+  seams._reset();
+  let surfaces = [{ key: 'landing', tweaked: 5, total: 6 }];
+  seams.registerProvider('copy-desk.artistStats', async () => ({ surfaces }));
+  const c = fakeLedger();
+  const ART = '2001';
+  pay(c, ART, 'tweak.page_approved:301', 30, 301);
+  await achievements.reconcileBuilderAchievements(c, ART);
+  assert.deepEqual(craftShelf(c, ART), ['first-page-approved']);
+  for (let t = 2; t <= 9; t++) pay(c, ART, `tweak.page_approved:${300 + t}`, 30, 300 + t);
+  await achievements.reconcileBuilderAchievements(c, ART);
+  assert.deepEqual(craftShelf(c, ART), ['first-page-approved'], 'nine pages is not ten');
+  pay(c, ART, 'tweak.page_approved:310', 30, 310);
+  surfaces = [{ key: 'landing', tweaked: 6, total: 6 }];
+  await achievements.reconcileBuilderAchievements(c, ART);
+  await achievements.reconcileBuilderAchievements(c, ART);
+  assert.deepEqual(craftShelf(c, ART), ['first-page-approved', 'ten-pages-approved', 'whole-surface-tweaked']);
+  assert.equal(c.unlocked.length, 3, 'each exactly once');
+  seams._reset();
+});
+
+await test('A Whole Surface without the studio\'s port is "could not tell", never a badge', async () => {
+  seams._reset();
+  const c = fakeLedger();
+  pay(c, '2001', 'tweak.page_approved:301', 30, 301);
+  await achievements.reconcileBuilderAchievements(c, '2001');
+  assert.ok(!shelf(c, '2001').includes('whole-surface-tweaked'));
+});
+
+// ---- 3. the writers -------------------------------------------------------------------
+
+await test('a Full Idea payment puts First Full Idea on the ideator\'s shelf, in the same call', async () => {
+  seams._reset();
+  const c = fakeLedger();
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 7, authorId: '2002', completenessScore: 90, config: { ideatorCredit: true } });
+  assert.ok(r.credited > 0, 'paid');
+  assert.deepEqual(craftShelf(c, '2002'), ['first-full-idea']);
+  assert.ok(c.sql.includes('SAVEPOINT ach_craft_credit'), 'under a savepoint, so a gamification error cannot fail the payment');
+  const again = await credits.awardIdeaFullPassCredit(c, { ideaId: 7, authorId: '2002', completenessScore: 90, config: { ideatorCredit: true } });
+  assert.equal(again.credited, 0, 'the second call pays nothing');
+  assert.equal(c.unlocked.length, 1, 'and unlocks nothing more');
+});
+
+await test('an approved page puts First Page Approved on the artist\'s shelf', async () => {
+  seams._reset();
+  const c = fakeLedger();
+  const r = await credits.awardArtistPageCredit(c, 301);
+  assert.equal(r.reason, 'paid');
+  assert.deepEqual(craftShelf(c, '2001'), ['first-page-approved']);
+});
+
+await test('a reconcile that throws never fails the payment', async () => {
+  seams._reset();
+  const c = fakeLedger({ failReconcile: true });
+  const r = await credits.awardIdeaFullPassCredit(c, { ideaId: 9, authorId: '2002', completenessScore: 90, config: { ideatorCredit: true } });
+  assert.ok(r.credited > 0, 'still paid');
+  assert.equal(c.ledger.length, 1);
+  assert.ok(c.sql.includes('ROLLBACK TO SAVEPOINT ach_craft_credit'), 'rolled back to its own savepoint only');
+  // on a POOL (no transaction) SAVEPOINT itself fails; the reconcile still runs
+  const pool = fakeLedger();
+  const q = pool.query.bind(pool);
+  pool.query = (text, params) => (/^SAVEPOINT/.test(text) ? Promise.reject(new Error('SAVEPOINT can only be used in transaction blocks')) : q(text, params));
+  await achievements.reconcileAfterCraftCredit(pool, '2002');
+  pay(pool, '2002', 'idea.credit.full_pass:11');
+  const got = await achievements.reconcileAfterCraftCredit(pool, '2002');
+  assert.deepEqual(got.map((a) => a.id), ['first-full-idea'], 'a pool payer still reaches the shelf');
+});
+
+await test('a payment runs only the craft rules, in two reads, and asks the studio only about an artist', async () => {
+  seams._reset();
+  let portCalls = 0;
+  seams.registerProvider('copy-desk.artistStats', async () => { portCalls++; return { surfaces: [] }; });
+  const c = fakeLedger();
+  await credits.awardIdeaFullPassCredit(c, { ideaId: 7, authorId: '2002', completenessScore: 90, config: { ideatorCredit: true } });
+  const after = c.sql.slice(c.sql.findIndex((q) => q.startsWith('SAVEPOINT ach_craft_credit')));
+  assert.ok(!after.some((q) => /FROM claims|session_records|total_credits FROM builders|ship\.net_negative/.test(q)),
+    'no claim, streak, diff or credit-total check on an idea payment');
+  assert.equal(after.filter((q) => q.startsWith('SELECT achievement_id FROM builder_achievements')).length, 1, 'one read of what is held');
+  assert.equal(after.filter((q) => q.startsWith('SELECT bool_or(reason LIKE $2) AS ignited')).length, 1, 'one read of the craft facts');
+  assert.equal(portCalls, 0, 'an ideator with no approved page is never asked about surfaces');
+  await credits.awardArtistPageCredit(c, 301);
+  assert.equal(portCalls, 1, 'an artist with an approved page is');
+  seams._reset();
+});
+
+await test('a builder holding every craft badge costs one read and nothing more', async () => {
+  seams._reset();
+  const c = fakeLedger();
+  for (const id of CRAFT) c.unlocked.push({ builder_id: '2002', achievement_id: id });
+  const before = c.sql.length;
+  await achievements.reconcileAfterCraftCredit(c, '2002');
+  const sent = c.sql.slice(before).filter((q) => !/SAVEPOINT/.test(q));
+  assert.deepEqual(sent.map((q) => q.slice(0, 40)), ['SELECT achievement_id FROM builder_achie']);
+});
+
+// ---- 4. the backfill ------------------------------------------------------------------
+
+await test('A Whole Surface is backfilled by the once-per-start sweep, for the artists the ledger has paid', async () => {
+  seams._reset();
+  let asked = [];
+  seams.registerProvider('copy-desk.artistStats', async (id) => { asked.push(String(id)); return { surfaces: [{ tweaked: 4, total: 4 }] }; });
+  const c = fakeLedger();
+  pay(c, '2001', 'tweak.page_approved:301', 30, 301);
+  pay(c, '2002', 'idea.credit.task_ship:7:101');
+  pay(c, '95', 'session.token_reward', 40); // an engineer the craft ledger never paid
+  const out = await achievements.backfillCraftAchievements({ client: c });
+  assert.equal(out.checked, 2, 'the artist and the ideator, not the engineer');
+  assert.ok(shelf(c, '2001').includes('whole-surface-tweaked'));
+  assert.ok(!shelf(c, '95').length, 'the engineer is untouched');
+  assert.deepEqual(asked, ['2001'], 'the studio is asked about the artist only');
+  const again = await achievements.backfillCraftAchievements({ client: c });
+  assert.equal(again.unlocked, 0, 'a second run unlocks nothing');
+
+  const reconciler = require('../modules/lifecycle/publish-reconciler.js');
+  const calls = [];
+  const reward = { backfillCraftAchievements: async () => { calls.push(1); return { checked: 1, unlocked: 1 }; } };
+  const quiet = { logFn: () => {}, errFn: () => {} };
+  await reconciler.runCraftAchievementBackfill({ reward, ...quiet, forceCraftBackfill: true });
+  await reconciler.runCraftAchievementBackfill({ reward, ...quiet });
+  assert.equal(calls.length, 1, 'once per process start, not on every tick');
+  const failing = await reconciler.runCraftAchievementBackfill({ reward: { backfillCraftAchievements: async () => { throw new Error('db down'); } }, ...quiet, forceCraftBackfill: true });
+  assert.equal(failing.skipped, 'error', 'a failure is logged and swallowed');
+  assert.match(read('modules/lifecycle/publish-reconciler.js'), /runCraftAchievementBackfill\(deps\)\.catch\(crashHandler\('craft achievement backfill'\)\)/, 'the tick runs it');
+  seams._reset();
+});
+
+await test('the backfill keys each badge on the same ledger fact and stamps the first qualifying credit, idempotently', () => {
+  const blocks = MIGRATION.split('INSERT INTO builder_achievements').slice(1);
+  const ids = blocks.map((b) => (b.match(/'([a-z0-9-]+)'/) || [])[1]);
+  assert.deepEqual(ids.sort(), CRAFT.filter((id) => id !== 'whole-surface-tweaked').sort(),
+    'six backfilled from the ledger; A Whole Surface needs the page inventory (a file), so the reconcile awards it');
+  for (const b of blocks) {
+    assert.match(b, /ON CONFLICT DO NOTHING/, 'a re-run converges');
+    assert.match(b, /delta > 0/, 'a zero or negative row is no moment');
+  }
+  assert.match(blocks.find((b) => b.includes("'ten-pages-approved'")), /WHERE nth = 10/, 'stamped at the tenth page');
+  assert.match(blocks.find((b) => b.includes("'thought-built-ten'")), /PARTITION BY builder_id, split_part\(reason, ':', 2\)/, 'counted per thought');
+  assert.match(MIGRATION, /diagnose-achievements\.js --apply/, 'the migration names how A Whole Surface is backfilled');
+});
+
+// ---- 5. the pictures ------------------------------------------------------------------
+
+await test('the roster and the status page draw every craft badge with the migration\'s icon', () => {
+  const roster = read('modules/hall-ui/public/roster.js');
+  const status = read('modules/status-ui/public/status.js');
+  const unescape = (s) => s.replace(/\\u\{([0-9A-F]+)\}/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)));
+  for (const a of CATALOG.values()) {
+    const r = roster.match(new RegExp(`'${a.id}': '([^']+)'`));
+    const s = status.match(new RegExp(`'${a.id}': '([^']+)'`));
+    assert.ok(r && unescape(r[1]) === a.icon, `roster draws ${a.id} as ${a.icon}`);
+    assert.ok(s && s[1] === a.icon, `status draws ${a.id} as ${a.icon}`);
+  }
+  assert.ok(unescape(roster.match(/'art-pipeline-shipper': '([^']+)'/)[1]) === '🛠️');
+  assert.equal(status.match(/'art-pipeline-shipper': '([^']+)'/)[1], '🛠️');
+});
+
+await test('a badge is named in words for a hover and a screen reader, never its id slug', () => {
+  const roster = read('modules/hall-ui/public/roster.js');
+  const fn = roster.slice(roster.indexOf('function achWords'), roster.indexOf('function achRowHtml'));
+  const achWords = new Function(`${fn}; return achWords;`)();
+  assert.equal(achWords('first-page-approved'), 'First page approved');
+  assert.equal(achWords('thought-built-ten'), 'Thought built ten');
+  assert.match(roster, /title="' \+ esc\(words\) \+ '" aria-label="' \+ esc\(words\) \+ '"/);
+  assert.doesNotMatch(roster, /title="' \+ esc\(id\)/);
+  const status = read('modules/status-ui/public/status.js');
+  assert.doesNotMatch(status, /span\.title = id;/);
+  assert.match(status, /span\.setAttribute\('aria-label', span\.title\)/);
+});
+
+summary();

package/tests/founding_birth.mjs

@@ -0,0 +1,200 @@
+// tests/founding_birth.mjs — A NEW PROJECT IS BORN INTO GENESIS, and a demo's genesis is
+// expedited (task 1004506 / BV2.PS18, goal 1000121; spec step 5, D4, D8, D9).
+//
+// Done-when: a new real project and a new demo each open their hall already in genesis;
+// the demo's decide stage needs no choices and its stages fit its time box; a
+// pre-existing hall is unchanged. These tests RUN the instance half
+// (modules/onboarding/founding-birth.js) over an in-memory project_settings store and
+// fake lifecycle port: the birth hook runs once, is idempotent, never runs without the
+// marker, and never after the project came alive. The hub half (the marker on the row
+// and in web.env) is pinned in tests/provisioning_settings_env.mjs and
+// tests/wizard_demo.mjs.
+//
+// Run:  node --test tests/founding_birth.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const birth = require('../modules/onboarding/founding-birth.js');
+const gh = require('../modules/onboarding/genesis-home.js');
+const fm = require('../modules/onboarding/founding-mode.js');
+
+const BORN = { born: true, demo: null };
+const BORN_DEMO = { born: true, demo: { people: 3, hours_each: 4 } };
+
+function world({ marker = BORN, settings = {}, withLifecycle = true } = {}) {
+  const store = new Map(Object.entries(settings));
+  const writes = [];
+  let seeds = 0;
+  const lifecycle = withLifecycle ? {
+    seedGenesis: async () => { seeds += 1; return { seeded: 5 }; },
+    genesisTasks: async () => ({}),
+  } : null;
+  const deps = () => ({
+    marker,
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { writes.push(k); store.set(k, String(v)); return { key: k, value: String(v) }; },
+    lifecycle, government: null, now: new Date('2026-10-01T09:00:00Z'),
+  });
+  return { store, writes, deps, seeds: () => seeds };
+}
+
+// ── the marker ───────────────────────────────────────────────────────────────
+
+test('the marker: born only with a readable birth stamp; a demo box only inside its limits', () => {
+  assert.deepEqual(birth.birthMarker(undefined), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({}), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: 'whenever' }), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z' }), { born: true, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z', demoPeople: '3', demoHours: '4' }),
+    { born: true, demo: { people: 3, hours_each: 4 } });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z', demoPeople: '99', demoHours: '4' }),
+    { born: true, demo: null }, 'a malformed box still founds, with the ordinary plan');
+  assert.deepEqual(birth.birthMarker({ demoPeople: '3', demoHours: '4' }), { born: false, demo: null },
+    'a demo box without a birth is not a birth');
+});
+
+// ── the birth hook ───────────────────────────────────────────────────────────
+
+test('no marker: nothing runs, and the database is never read (a pre-existing hall is unchanged)', async () => {
+  const r = await birth.bornFounding({
+    marker: { born: false, demo: null },
+    getSetting: async () => { throw new Error('read without a marker'); },
+    setSetting: async () => { throw new Error('write without a marker'); },
+  });
+  assert.deepEqual(r, { ran: false, reason: 'no_marker' });
+});
+
+test('a new real project is born deciding: founding on, stage decide, no plan, nothing filed', async () => {
+  const w = world();
+  const r = await birth.bornFounding(w.deps());
+  assert.deepEqual(r, { ran: true, started: true, plan: false, demo: false });
+  const mode = await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null });
+  assert.equal(mode.active, true);
+  assert.equal(mode.stage, 'decide');
+  assert.equal(w.store.get(gh.PLAN_KEY), undefined, 'a real founder settles their own plan');
+  assert.equal(w.seeds(), 0);
+});
+
+test('idempotent: a second run (a restart, a settings push) changes nothing', async () => {
+  const w = world();
+  await birth.bornFounding(w.deps());
+  const before = new Map(w.store);
+  w.writes.length = 0;
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, [], 'no write at all');
+  assert.deepEqual([...w.store], [...before]);
+});
+
+test('never after the project came alive: genesis happens once', async () => {
+  const w = world({ settings: {
+    [fm.KEYS.ACTIVE]: 'false', [fm.KEYS.STARTED_AT]: '2026-09-01T00:00:00.000Z', [fm.KEYS.ENDED_AT]: '2026-09-10T00:00:00.000Z',
+  } });
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_alive' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null }), null, 'the hall stays alive');
+});
+
+test('a founding already under way (started by hand, mid-stage) is left exactly where it is', async () => {
+  const w = world({ marker: BORN_DEMO, settings: {
+    [fm.KEYS.ACTIVE]: 'true', [fm.KEYS.STAGE]: 'strategize', [fm.KEYS.STARTED_AT]: '2026-09-28T00:00:00.000Z',
+  } });
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(w.seeds(), 0);
+});
+
+test('a new demo is born past decide: the plan is settled from the demo, and its stages are filed', async () => {
+  const w = world({ marker: BORN_DEMO });
+  const r = await birth.bornFounding(w.deps());
+  assert.deepEqual(r, { ran: true, started: true, plan: true, demo: true });
+  assert.equal(w.seeds(), 1, 'the five stages filed as tasks, once');
+  const plan = JSON.parse(w.store.get(gh.PLAN_KEY));
+  assert.equal(plan.government, 'monarchy', 'Monarchy / BDFL: the founder\'s one yes closes each stage (D4)');
+  assert.equal(plan.passes, 1);
+  assert.equal(plan.advisors, 'none');
+  assert.equal(plan.expected_builders, 3, 'the demo\'s people');
+  assert.deepEqual(plan.demo, { people: 3, hours_each: 4 });
+  const mode = await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null });
+  assert.equal(mode.stage, 'scope', 'the decide stage needs no choices: it is already behind');
+  // Again: nothing more.
+  w.writes.length = 0;
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(w.seeds(), 1, 'never filed twice');
+});
+
+test('a demo whose plan could not be saved yet (no board) asks for a retry, and the retry settles it', async () => {
+  birth.resetBirthForTests();
+  const store = new Map();
+  let seeds = 0;
+  const base = {
+    marker: BORN_DEMO,
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { store.set(k, String(v)); },
+    government: null,
+  };
+  const first = await birth.ensureBirth({ ...base, lifecycle: null });
+  assert.equal(first.retry, true);
+  assert.equal(first.reason, 'no_board');
+  assert.equal(store.get(fm.KEYS.STAGE) || 'decide', 'decide');
+  const second = await birth.ensureBirth({ ...base, lifecycle: { seedGenesis: async () => { seeds += 1; return { seeded: 5 }; } } });
+  assert.deepEqual(second, { ran: true, started: false, plan: true, demo: true }, 'the retry saves the plan without restarting founding');
+  assert.equal(seeds, 1);
+  assert.equal(store.get(fm.KEYS.STAGE), 'scope');
+  birth.resetBirthForTests();
+});
+
+test('once per process: concurrent first reads share ONE run', async () => {
+  birth.resetBirthForTests();
+  const w = world({ marker: BORN_DEMO });
+  const results = await Promise.all([birth.ensureBirth(w.deps()), birth.ensureBirth(w.deps()), birth.ensureBirth(w.deps())]);
+  assert.equal(results[0], results[1]);
+  assert.equal(results[1], results[2]);
+  assert.equal(w.seeds(), 1);
+  assert.equal(w.writes.filter((k) => k === fm.KEYS.STARTED_AT).length, 1, 'started once');
+  assert.equal(w.writes.filter((k) => k === gh.PLAN_KEY).length, 1, 'planned once');
+  // A later read reuses the settled run; it does not touch the store again.
+  w.writes.length = 0;
+  await birth.ensureBirth(w.deps());
+  assert.deepEqual(w.writes, []);
+  birth.resetBirthForTests();
+});
+
+test('a run that throws is forgotten, so a later read tries again; the read itself never fails', async () => {
+  birth.resetBirthForTests();
+  let fail = true;
+  const store = new Map();
+  const deps = {
+    marker: BORN,
+    getSetting: async (k) => { if (fail) throw new Error('db down'); return store.has(k) ? { value: store.get(k) } : null; },
+    setSetting: async (k, v) => { store.set(k, String(v)); },
+  };
+  assert.deepEqual(await birth.ensureBirth(deps), { ran: false, reason: 'error' });
+  fail = false;
+  assert.equal((await birth.ensureBirth(deps)).ran, true);
+  assert.equal(store.get(fm.KEYS.ACTIVE), 'true');
+  birth.resetBirthForTests();
+});
+
+// ── the wiring ───────────────────────────────────────────────────────────────
+
+test('the /me read (the port, no arguments) runs the birth first; a caller with its own deps does not', async () => {
+  const port = require('../modules/onboarding/port.js');
+  const orig = { ensure: birth.ensureBirth, read: fm.foundingModeFor };
+  const calls = [];
+  birth.ensureBirth = async () => { calls.push('birth'); };
+  fm.foundingModeFor = async (d) => { calls.push(d ? 'read:deps' : 'read'); return null; };
+  try {
+    await port.foundingModeFor();
+    assert.deepEqual(calls, ['birth', 'read'], 'the birth lands before the read, so the first hall paint is already founding');
+    calls.length = 0;
+    await port.foundingModeFor({ getSetting: async () => null });
+    assert.deepEqual(calls, ['read:deps']);
+  } finally {
+    birth.ensureBirth = orig.ensure;
+    fm.foundingModeFor = orig.read;
+  }
+});

package/tests/founding_builders.mjs

@@ -192,7 +192,8 @@ async function rosterRows(marks) {
       makeLedger: (cfg) => { rowFn = cfg.rowHtml; return { render() {} }; },
     },
   });
-  sandbox.document = { getElementById: () => ({ innerHTML: '', className: '', textContent: '', hidden: false }) };
+  // addEventListener/querySelectorAll: the role toggle wires its chips (task 1004437).
+  sandbox.document = { getElementById: () => ({ innerHTML: '', className: '', textContent: '', hidden: false, addEventListener() {}, querySelectorAll: () => [] }) };
   if (!marks) delete sandbox.window.OTBFounding; // a page without the script at all
   vm.runInContext(read('roster.js'), sandbox, { filename: 'roster.js' });
   await new Promise((r) => setImmediate(r));

package/tests/founding_mode.mjs

@@ -278,7 +278,9 @@ test('/me carries founding_mode from the onboarding port, fail-open to null', ()
   assert.match(ME, /onboarding\.foundingModeFor\(\)/);
   const at = ME.indexOf('onboarding.foundingModeFor()');
   assert.match(ME.slice(at, at + 200), /catch \(_\) \{ return null; \}/);
-  assert.match(PORT, /foundingModeFor: \(\.\.\.a\) => foundingMode\.foundingModeFor\(\.\.\.a\)/);
+  // The port delegates at call time; a no-argument read (me.js) first runs the guarded
+  // birth (task 1004506, tests/founding_birth.mjs).
+  assert.match(PORT, /foundingModeFor: async \(\.\.\.a\) => \{\s*if \(!a\.length\) await foundingBirth\.ensureBirth\(\);\s*return foundingMode\.foundingModeFor\(\.\.\.a\);/);
 });
 
 test('BOTH applyAccess callers pass it, or the index would never show the band', () => {