@bongos/core 1.21.105 → 1.21.107

package/tests/autopickup_cap.mjs

@@ -0,0 +1,236 @@
+// tests/autopickup_cap.mjs — tweak auto-pickup's setting, monthly cap and claim mark
+// (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
+//      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;
+//   3. claimTask: a marked claim runs the gate before the insert and names the
+//      column; an unmarked claim's insert is unchanged;
+//   4. the routes: any builder reads (with this month's count), only
+//      project.settings.manage writes, and a half-valid body writes nothing.
+//
+// Run:  node --test tests/autopickup_cap.mjs
+import { strict as assert } from 'node:assert';
+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 poolMod = require(path.join(ROOT, 'src', 'bongos', 'pool.js'));
+const {
+  DEFAULT_AUTOPICKUP, DEFAULT_AUTOPICKUP_CAP, parseAutopickup, parseAutopickupCap,
+  resolveTweakAutopickup, describeTweakAutopickup, SETTING_KEYS, AUTOPICKUP_MODES, MAX_AUTOPICKUP_CAP,
+} = require('../src/bongos/project-settings.js');
+const { autoPickupRefusal, LOCK_KEY, MAX_AUTO_APPLIES_PER_ROUND } = require('../modules/lifecycle/autopickup.js');
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+
+async function withPool(query, fn) {
+  const pool = poolMod.pool;
+  const saved = pool.query;
+  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] }] : [] });
+
+// ---- 1. the setting ---------------------------------------------------------
+
+test('the parsers accept exactly off|on and a whole positive cap', () => {
+  assert.deepEqual([...AUTOPICKUP_MODES], ['off', 'on']);
+  assert.equal(api.projectSettings.MAX_AUTOPICKUP_CAP, MAX_AUTOPICKUP_CAP, 'the doorway hands out the same bound');
+  assert.deepEqual(parseAutopickup(' On '), { mode: 'on' });
+  assert.match(parseAutopickup('maybe').reason, /off \| on/);
+  assert.deepEqual(parseAutopickupCap('5'), { cap: 5 });
+  assert.match(parseAutopickupCap('0').reason, /positive/);
+  assert.match(parseAutopickupCap('2.5').reason, /whole/);
+  assert.match(parseAutopickupCap('100000').reason, /out of range/);
+});
+
+test('an untouched project is off with a cap of 20', async () => {
+  assert.equal(DEFAULT_AUTOPICKUP, 'off');
+  assert.equal(DEFAULT_AUTOPICKUP_CAP, 20);
+  const r = await withPool(settingsRows({}), () => resolveTweakAutopickup());
+  assert.deepEqual(r, { mode: 'off', cap: 20, source: { mode: 'default', cap: 'default' }, invalid: [] });
+  assert.match(describeTweakAutopickup(r), /waits until a person/);
+});
+
+test('stored values are read; an unusable one is reported and falls back', async () => {
+  const r = await withPool(settingsRows({ [SETTING_KEYS.TWEAK_AUTOPICKUP]: 'on', [SETTING_KEYS.TWEAK_AUTOPICKUP_CAP]: 'lots' }),
+    () => resolveTweakAutopickup());
+  assert.equal(r.mode, 'on');
+  assert.equal(r.source.mode, 'project_settings');
+  assert.equal(r.cap, 20);
+  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/);
+});
+
+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);
+});
+
+// ---- 2. the refusal ladder --------------------------------------------------
+
+function fakeClient({ round = 0, month = 0 } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push(sql.includes('pg_advisory_xact_lock') ? `lock:${params[0]}` : sql.includes('date_trunc') ? 'month' : 'round');
+      if (sql.includes('pg_advisory_xact_lock')) return { rows: [] };
+      return { rows: [{ n: sql.includes('date_trunc') ? month : round }] };
+    },
+  };
+}
+const tweak = { id: 9, source: 'page-tweak' };
+const on = { mode: 'on', cap: 3 };
+
+test('a marked claim on anything but a page tweak is refused, before any lock', async () => {
+  const c = fakeClient();
+  assert.equal((await autoPickupRefusal(c, { id: 9, source: 'manual' }, on)).code, 'AUTO_PICKUP_NOT_A_TWEAK');
+  assert.deepEqual(c.calls, []);
+});
+
+test('the switch off refuses a marked claim', async () => {
+  assert.equal((await autoPickupRefusal(fakeClient(), tweak, { mode: 'off', cap: 3 })).code, 'AUTO_PICKUP_OFF');
+});
+
+test('the lock is taken before either count, on the one project-wide key', async () => {
+  const c = fakeClient();
+  assert.equal(await autoPickupRefusal(c, tweak, on), null);
+  assert.equal(LOCK_KEY, 'page-tweak/autopickup');
+  assert.deepEqual(c.calls, ['lock:page-tweak/autopickup', 'round', 'month']);
+});
+
+test('a third automatic apply of one round is refused', async () => {
+  assert.equal(MAX_AUTO_APPLIES_PER_ROUND, 2);
+  assert.equal(await autoPickupRefusal(fakeClient({ round: 1 }), tweak, on), null);
+  const r = await autoPickupRefusal(fakeClient({ round: 2 }), tweak, on);
+  assert.equal(r.code, 'AUTO_PICKUP_ROUND_LIMIT');
+  assert.match(r.message, /waits for a person/);
+});
+
+test('the monthly cap refuses at the cap and admits below it', async () => {
+  assert.equal(await autoPickupRefusal(fakeClient({ month: 2 }), tweak, on), null);
+  const r = await autoPickupRefusal(fakeClient({ month: 3 }), tweak, on);
+  assert.equal(r.code, 'AUTO_PICKUP_CAP_REACHED');
+  assert.equal(r.cap, 3);
+});
+
+// ---- 3. claimTask wiring ----------------------------------------------------
+
+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 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');
+  assert.match(body, /\$\{autoPickup \? ', auto_pickup' : ''\}/);
+  assert.match(body, /goal_id, source FROM tasks WHERE id = \$1 FOR UPDATE/, 'the task row carries its source');
+});
+
+test('POST /claims accepts auto_pickup and maps every refusal to a 409', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'claims.js'), 'utf8');
+  assert.match(src, /auto_pickup: \{ type: 'boolean' \}/);
+  assert.match(src, /autoPickup: autoPickup === true/);
+  for (const code of ['AUTO_PICKUP_NOT_A_TWEAK', 'AUTO_PICKUP_OFF', 'AUTO_PICKUP_CAP_REACHED', 'AUTO_PICKUP_ROUND_LIMIT']) {
+    assert.match(src, new RegExp(`err.code === '${code}' \\? 409`));
+  }
+});
+
+// ---- 4. the routes ----------------------------------------------------------
+
+const fakeRes = () => ({
+  code: null, statusCode: 200, payload: null, headers: {},
+  fail(code, opts) { this.code = code; this.statusCode = opts?.status ?? 400; this.payload = { error: code, ...(opts || {}) }; return this; },
+  status(c) { this.statusCode = c; return this; },
+  set(k, v) { this.headers[k] = v; return this; },
+  json(p) { this.payload = p; return this; },
+});
+
+function buildRouter({ used = 4 } = {}) {
+  const ps = api.projectSettings;
+  const saved = { resolve: ps.resolveTweakAutopickup, set: ps.set };
+  const writes = [];
+  const state = { mode: 'off', cap: 20 };
+  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;
+  };
+  const autopickup = require('../modules/lifecycle/autopickup.js');
+  const savedCount = autopickup.countThisMonth;
+  autopickup.countThisMonth = async () => used;
+  const file = path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js');
+  delete require.cache[require.resolve(file)];
+  const router = require(file)();
+  const route = (method, p) => router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]).route;
+  const restore = () => { ps.resolveTweakAutopickup = saved.resolve; ps.set = saved.set; autopickup.countThisMonth = savedCount; };
+  return { route, writes, restore };
+}
+const handler = (r) => r.stack[r.stack.length - 1].handle;
+
+test('the read is open to any builder and reports this month\'s count against the cap', async () => {
+  const { route, restore } = buildRouter({ used: 4 });
+  try {
+    const get = route('get', '/project-settings/tweak-autopickup');
+    assert.equal(get.stack.length, 2, 'requireBuilder + the handler');
+    const res = fakeRes();
+    await handler(get)({}, res);
+    assert.equal(res.payload.mode, 'off');
+    assert.equal(res.payload.used_this_month, 4);
+    assert.equal(res.payload.remaining_this_month, 16);
+    assert.equal(res.payload.per_round_limit, 2);
+    assert.equal(res.headers['Cache-Control'], 'no-store');
+  } finally { restore(); }
+});
+
+test('the write is gated on project.settings.manage and the Rules decision rule', () => {
+  const { route, restore } = buildRouter();
+  try {
+    const write = route('patch', '/project-settings/tweak-autopickup').stack;
+    assert.equal(write.length, 4);
+    assert.equal(write[2].handle.name, 'actAloneGate');
+    const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js'), 'utf8');
+    assert.match(src, /router\.patch\('\/project-settings\/tweak-autopickup', api\.requireBuilder, api\.requirePermission\('project\.settings\.manage'\)/);
+  } finally { restore(); }
+});
+
+test('a half-valid body writes nothing; a good one writes both and echoes the new read', async () => {
+  const { route, writes, restore } = buildRouter({ used: 0 });
+  try {
+    const patch = handler(route('patch', '/project-settings/tweak-autopickup'));
+    const bad = fakeRes();
+    await patch({ body: { mode: 'on', cap: 0 }, builder: { id: 7 } }, bad);
+    assert.equal(bad.code, 'bad_tweak_autopickup');
+    assert.equal(writes.length, 0);
+
+    const empty = fakeRes();
+    await patch({ body: {}, builder: { id: 7 } }, empty);
+    assert.equal(empty.code, 'bad_tweak_autopickup');
+
+    const good = fakeRes();
+    await patch({ body: { mode: 'ON', cap: 5 }, builder: { id: 7 } }, good);
+    assert.equal(good.code, null);
+    assert.deepEqual(writes, [
+      { key: 'tweak.autopickup', value: 'on', by: 7 },
+      { key: 'tweak.autopickup_monthly_cap', value: 5, by: 7 },
+    ]);
+    assert.equal(good.payload.mode, 'on');
+    assert.equal(good.payload.cap, 5);
+  } finally { restore(); }
+});
+
+test('core_275 is additive: one nullable column, recorded in schema_migrations', () => {
+  const sql = fs.readFileSync(path.join(ROOT, 'migrations', 'core_275_claims_auto_pickup.sql'), 'utf8');
+  assert.match(sql, /ALTER TABLE claims ADD COLUMN IF NOT EXISTS auto_pickup boolean;/);
+  assert.doesNotMatch(sql, /NOT NULL|DROP /);
+  assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('core_275_claims_auto_pickup'\)/);
+});

package/tests/autopickup_cap_db.mjs

@@ -0,0 +1,115 @@
+// tests/autopickup_cap_db.mjs — the auto-pickup cap holds under a race, against a
+// REAL Postgres (task 1004677 / BV2.TW19a, ADR 0371 D5).
+//
+// tests/autopickup_cap.mjs proves the refusal ladder DB-free. What it cannot prove
+// is the claim this file exists for: two runners racing for the LAST slot cannot
+// both get it. That is a property of pg_advisory_xact_lock plus the count running
+// inside the claim's transaction, so it needs a real database and two real
+// connections.
+//
+// It SELF-SKIPS (exit 0) with no reachable Postgres, and is listed in
+// run-unit-tests.js's INTEGRATION set so the DB-free lane never runs it. It builds
+// throwaway `tasks` and `claims` tables, so point it at a scratch database.
+//
+// Run:  DATABASE_URL=postgres://... node tests/autopickup_cap_db.mjs
+
+import pg from 'pg';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+
+const require = createRequire(import.meta.url);
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`autopickup_cap_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+const { rows: realRows } = await pool.query(`SELECT to_regclass('public.builders') IS NOT NULL AS has_builders`);
+if (realRows[0].has_builders) {
+  console.log('autopickup_cap_db.mjs SKIPPED — this database has a `builders` table, so it is not a scratch DB.');
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}\n     ${e.message}`); }
+}
+
+await pool.query(`
+  CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY);
+  CREATE TABLE IF NOT EXISTS tasks (id bigint PRIMARY KEY, source text);
+  CREATE TABLE IF NOT EXISTS claims (
+    id bigserial PRIMARY KEY, task_id bigint, builder_id bigint,
+    claimed_at timestamptz DEFAULT now(), released_at timestamptz);
+`);
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+await pool.query(fs.readFileSync(path.join(HERE, '..', 'migrations', 'core_275_claims_auto_pickup.sql'), 'utf8'));
+
+const { autoPickupRefusal, countThisMonth } = require('../modules/lifecycle/autopickup.js');
+
+async function reset() {
+  await pool.query('TRUNCATE claims, tasks');
+  await pool.query(`INSERT INTO tasks (id, source) VALUES (1,'page-tweak'),(2,'page-tweak'),(3,'page-tweak'),(4,'manual')`);
+}
+
+// One marked claim the way claimTask makes it: BEGIN, the gate (which takes the
+// lock and counts), the insert, COMMIT. `pause` holds the transaction open after
+// the count so the other racer's count is forced to happen while it is in flight.
+async function markedClaim(taskId, settings, pause = 0) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const refusal = await autoPickupRefusal(client, { id: taskId, source: 'page-tweak' }, settings);
+    if (refusal) { await client.query('ROLLBACK'); return refusal.code; }
+    if (pause) await new Promise((r) => setTimeout(r, pause));
+    await client.query('INSERT INTO claims (task_id, builder_id, auto_pickup) VALUES ($1, 1, TRUE)', [taskId]);
+    await client.query('COMMIT');
+    return 'claimed';
+  } catch (e) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw e;
+  } finally { client.release(); }
+}
+
+await t('core_275 adds a nullable auto_pickup column', async () => {
+  const { rows } = await pool.query(`SELECT is_nullable, data_type FROM information_schema.columns WHERE table_name='claims' AND column_name='auto_pickup'`);
+  assert.equal(rows[0].data_type, 'boolean');
+  assert.equal(rows[0].is_nullable, 'YES');
+});
+
+await t('two runners racing for the last slot: exactly one wins', async () => {
+  await reset();
+  await pool.query(`INSERT INTO claims (task_id, builder_id, auto_pickup) VALUES (3, 1, TRUE)`); // cap 2, one used
+  const settings = { mode: 'on', cap: 2 };
+  const results = await Promise.all([markedClaim(1, settings, 300), markedClaim(2, settings, 300)]);
+  assert.deepEqual(results.sort(), ['AUTO_PICKUP_CAP_REACHED', 'claimed'], JSON.stringify(results));
+  assert.equal(await countThisMonth(pool), 2);
+});
+
+await t('a round applied twice automatically refuses a third marked claim', async () => {
+  await reset();
+  const settings = { mode: 'on', cap: 20 };
+  assert.equal(await markedClaim(1, settings), 'claimed');
+  assert.equal(await markedClaim(1, settings), 'claimed');
+  assert.equal(await markedClaim(1, settings), 'AUTO_PICKUP_ROUND_LIMIT');
+});
+
+await t('unmarked claims and last month\'s marked claims do not count', async () => {
+  await reset();
+  await pool.query(`INSERT INTO claims (task_id, builder_id, auto_pickup, claimed_at) VALUES
+    (1, 1, NULL, now()), (2, 1, FALSE, now()), (3, 1, TRUE, date_trunc('month', now()) - interval '1 day'),
+    (4, 1, TRUE, now())`); // task 4 is not a page tweak
+  assert.equal(await countThisMonth(pool), 0);
+});
+
+await pool.end();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0); // the doorway's own pool would otherwise hold the process open

package/tests/cosmos_token_contrast.mjs

@@ -515,24 +515,16 @@ test('text is never dimmed by subtree opacity', () => {
   assert.deepEqual(offenders, [], `\n  ${offenders.join('\n  ')}\n`);
 });
 
-test('the .prog strip mirrors .strip: state marks are --sea-ink, ticks are --on-ok', () => {
-  // /create's done panel renders the page-local .prog, NOT cosmos's .strip —
-  // a re-point of one and not the other is exactly how the 1.74:1 dark tick
-  // shipped the first time. State-mark rules (done fill/connector, now
-  // ring/pulse, the tick) must use the derived tokens; raw --sea is only legal
-  // as a tint ingredient (color-mix) or the idle -soft rail.
-  const progRules = [...pageSrc.matchAll(/\.prog[^{}]*\{([^}]*)\}/g)];
-  assert.ok(progRules.length >= 5, 'the .prog rules moved out of projects.html — update this test');
-  const bad = [];
-  for (const m of progRules) {
-    const body = m[1];
-    if (/(?:border(?:-\w+)?|background)\s*:\s*var\(\s*--sea\s*\)/.test(body)) {
-      bad.push(`raw --sea state mark: ${m[0].slice(0, 80)}`);
-    }
-    if (/border-(?:left|bottom)\s*:[^;]*#fff\b/i.test(body)) {
-      bad.push(`hardcoded #fff tick: ${m[0].slice(0, 80)}`);
-    }
-  }
+test('part 03 draws no stage strip, and its fact marks use the status inks, never raw --sea or #fff (task 1004683)', () => {
+  // The done panel's page-local .prog strip (a mirror of cosmos's .strip) left with the
+  // stage dots: part 03 is one list of checked facts now. The mine and manage views keep
+  // cosmos's own .strip. A fact's mark carries its state in the --ok / --err / --accent
+  // inks (which the day room re-points through --wz-*); raw --sea or a literal white
+  // would be the 1.74:1 dark tick this test was first written for.
+  assert.equal([...pageSrc.matchAll(/\.prog[^{}]*\{([^}]*)\}/g)].length, 0, 'no .prog rules are left in projects.html');
+  const marks = [...pageSrc.matchAll(/\.setFact\.(done|bad|now|you) \.d\{([^}]*)\}/g)];
+  assert.ok(marks.length >= 4, 'the four marked fact states are found');
+  const bad = marks.filter((m) => /var\(\s*--sea\s*\)|#fff\b/i.test(m[2])).map((m) => m[0].slice(0, 80));
   assert.deepEqual(bad, [], `\n  ${bad.join('\n  ')}\n`);
 });
 

package/tests/github_handback_any_device.mjs

@@ -82,8 +82,8 @@ function region(startMark, endMark) {
   const e = s < 0 ? -1 : SCRIPT.indexOf(endMark, s);
   return s > 0 && e > s ? SCRIPT.slice(s, e) : null;
 }
-const POLLS = region("    /* ── C8: the wizard's polls run only while the create view is on stage", '    /* ── live build progress (task 2083)');
-const WATCH_VARS = region('    var pollTimer = null;', "    /* The done panel's own flow vocabularies");
+const POLLS = region("    /* ── C8: the wizard's polls run only while the create view is on stage", "    /* ── the owner's instance read (task 2083)");
+const WATCH_VARS = region('    var pollTimer = null;', '    function startProgress(id) {');
 const START_PROGRESS = (SCRIPT.match(/ {4}function startProgress\(id\) \{[\s\S]*?\n {4}\}/) || [null])[0];
 const DOORS = region("    /* ── the hub's three doors ── */", '    return { enter: enter, leave: leave, onAuth: onAuth };');
 
@@ -136,7 +136,8 @@ function page({ url, who, storage = 'empty', name = '', hidden = false, instance
     renderDone() { log.rendered += 1; }, renderSteps() { log.rendered += 1; },
     resetForNewProject() { log.resets += 1; },
     saveDraft() {},
-    setProgress() {}, progressMarkup: () => '', setMoment() {}, renderProgress: () => false, addressReady: () => true,
+    // part 03's facts (task 1004683) are tests/setup_status_facts.mjs; here they only have to exist
+    paintFacts() {}, homeFacts: () => [], ghFacts: () => [], setupReady: () => false, hostOk: () => true, addressReady: () => true,
   };
   sandbox.globalThis = sandbox;
   vm.createContext(sandbox);

package/tests/github_one_trip.mjs

@@ -8,8 +8,8 @@
 //      app's OWN key: the creds read back out of a REAL webEnvBody, a JWT that verifies,
 //      installed / not installed / cannot tell, device flow on / off / cannot tell, and the
 //      tick recording only what GitHub confirmed — never a secret in a log line.
-//   3. the REAL projection (githubSetupRead) run into the REAL page renderers (projects.html,
-//      the vm-slice idiom): each server state draws the step the founder should see.
+//   3. the REAL projection (githubSetupRead) run into the REAL page facts (projects.html,
+//      ghFacts, the vm-slice idiom; task 1004683): each server state draws the fact the founder should see.
 //   4. the device-flow finding is written down where the next builder will look.
 //
 // Run:  node --test tests/github_one_trip.mjs
@@ -185,38 +185,35 @@ test('the window query takes each project\'s LATEST attempt, past placement, sti
   assert.match(fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'provision.js'), 'utf8'), /require\('\.\/provision-github-setup\.js'\)\.verifyGithubAppSetups\(deps\)/, 'it runs on every runner tick, after the conversions');
 });
 
-// ── 3. the real projection into the real renderers ──────────────────────────
+// ── 3. the real projection into the real page facts ─────────────────────────
+// Since task 1004683 part 03 draws FACTS, not checklist markup: ghFacts() is pure over
+// what the reads said, and paintFacts draws it from nodes (tests/setup_status_facts.mjs
+// runs the whole route-to-DOM path). Here: the GitHub half, fed by the real projection.
 
-const RS = SCRIPT.indexOf('    /* The four GitHub steps of part 03');
-const RE = SCRIPT.indexOf('    var STEP_RENDERERS = {', RS);
+const FS = SCRIPT.indexOf('    function ghStep(key) {');
+const FE = SCRIPT.indexOf('    /* ── drawing it: nodes and textContent only', FS);
 const SS = SCRIPT.indexOf('    /* the checklist the server derived (task 1004649)');
 const SE = SCRIPT.indexOf('    function pollManifest(stateToken) {', SS);
-const PS = SCRIPT.indexOf('    function stepsPaint() {');
-const PE = SCRIPT.indexOf('    (function hopInput()', PS);
 
 test('the regions are findable (a rename must fail loudly)', () => {
-  assert.ok(RS > 0 && RE > RS && SS > 0 && SE > SS && PS > 0 && PE > PS);
+  assert.ok(FS > 0 && FE > FS && SS > 0 && SE > SS);
+  assert.match(SCRIPT.slice(FS, FE), /function ghFacts\(now\)/);
 });
 
 function page({ manifest, appSlug = null }) {
   const sandbox = {
-    live: { manifest, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug, setup: null, installUrl: null, instStatus: 'active', addrReady: true },
+    live: { manifest, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug, appOrg: null, setup: null, installUrl: null, pickUp: null, verifying: false, askedPlatform: false, instStatus: 'active', addrReady: true, inst: null, readAt: 0, gone: '', repo: null },
     state: { name: 'Mer<cury', slug: 'mercury', owner: 'acme', repo: 'mercury', step: 2 },
-    autoOpenArmed: false,
-    resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com',
-    esc: (x) => String(x).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
-    GH_ICON: '', manualOauthDetails: () => '', projectPageLink: (t) => t, autoOpenTick: () => '',
-    progressMarkup: (a, b, note) => `<prog>${note}</prog>`, encodeURIComponent, JSON, Array,
+    resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com', addressReady: () => true,
+    document: { hidden: false, hasFocus: () => true },
   };
   vm.createContext(sandbox);
-  vm.runInContext(`${SCRIPT.slice(RS, RE)}\n${SCRIPT.slice(SS, SE)}\n${SCRIPT.slice(PS, PE)}`, sandbox);
+  vm.runInContext(`${SCRIPT.slice(FS, FE)}\n${SCRIPT.slice(SS, SE)}`, sandbox);
   return sandbox;
 }
-const ROWS = ['renderStepOauthApp', 'renderStepAppInstall', 'renderStepFirstSignIn', 'renderStepDeviceFlow'];
-function draw(sb) {
-  return ROWS.map((f) => vm.runInContext(`${f}()`, sb));
-}
-function cls(li) { return ((li.match(/^<li(?: class="([^"]*)")?/) || [])[1] || '').split(/\s+/).filter(Boolean); }
+// vm-born values compared through JSON
+const draw = (sb) => JSON.parse(JSON.stringify(vm.runInContext('ghFacts(Date.now())', sb)));
+const states = (rows) => rows.map((r) => r.state);
 
 async function serverSays(status, appSlug, eventRows) {
   const db = { query: async () => ({ rows: eventRows }) };
@@ -224,55 +221,50 @@ async function serverSays(status, appSlug, eventRows) {
   return GS.githubSetupRead(db, { target_ref: 'acme/mercury' }, row, status);
 }
 
-test('the mockup\'s four steps, in its words and order, the typed name escaped', () => {
-  const sb = page({ manifest: null });
-  const rows = draw(sb);
-  const titles = rows.map((li) => (li.match(/<b>([^<]*)<\/b>/) || [])[1]);
-  assert.deepEqual(titles, ['Approve the Mer&lt;cury app on GitHub', 'Install it on your repo', 'Builders can sign in', 'Command-line sign-in is on']);
-  assert.match(rows[0], /data-action="manifest-start"[^>]*>Connect GitHub ↗/, 'one click starts the one trip');
-  assert.equal(SCRIPT.match(/var STEP_ORDER = \[([^\]]*)\]/)[1], "'github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'device-flow', 'enter-hall'", 'drawn in the mockup\'s order');
+test('the mockup\'s four facts, in its words and order; the typed name is text, never markup', () => {
+  const rows = draw(page({ manifest: null }));
+  assert.deepEqual(rows.map((r) => r.title), ['Approve the Mer<cury app on GitHub', 'Install it on your repo', 'Builders can sign in', 'Command-line sign-in']);
+  assert.deepEqual(rows.map((r) => r.key), ['approve', 'install', 'sign_in', 'device_flow']);
+  assert.equal(rows[0].act, 'connect', 'one click starts the one trip, from inside the Approve fact');
+  assert.equal(rows[0].state, 'you', 'it is the founder\'s turn');
+  assert.equal(rows[3].opt, true, 'command-line sign-in is optional');
+  assert.doesNotMatch(SCRIPT.slice(FS, FE), /esc\(|innerHTML/, 'the facts carry text; the painter writes nodes');
 });
 
-test('each server state draws the step the founder should see — from the REAL projection', async () => {
+test('each server state draws the facts the founder should see — from the REAL projection', async () => {
   // keys placed, nothing verified on GitHub yet
   let sb = page({ manifest: 'converting', appSlug: 'mercury-app' });
   let d = await serverSays('converting', 'mercury-app', []);
-  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)}, ${JSON.stringify(d)})`, sb);
   let rows = draw(sb);
-  assert.deepEqual(rows.map(cls), [['sdone'], [], ['slocked'], ['slocked', 'soptional']]);
-  assert.match(rows[1], /href="https:\/\/github\.com\/apps\/mercury-app\/installations\/new\?state=S1"/, 'the way back to the install, with the attempt');
-  assert.equal(vm.runInContext('stepsPaint.toString().length > 0', sb), true);
+  assert.deepEqual(states(rows), ['done', 'you', 'now', 'todo']);
+  assert.equal(rows[1].href, 'https://github.com/apps/mercury-app/installations/new?state=S1', 'the way back to the install, with the attempt');
+  assert.equal(rows[1].sub, 'acme/mercury', 'the repo the server says it installs on');
+  assert.equal(rows[1].right, 'not yet seen');
 
   // sign-in verified, install still unconfirmed: NOT connected
   sb = page({ manifest: 'done', appSlug: 'mercury-app' });
   d = await serverSays('done', 'mercury-app', []);
-  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)}, ${JSON.stringify(d)})`, sb);
   rows = draw(sb);
-  assert.deepEqual(rows.map(cls), [['sdone'], [], ['sdone'], ['soptional']]);
-  assert.match(rows[3], /Optional — turn it on later\./);
+  assert.deepEqual(states(rows), ['done', 'you', 'done', 'todo']);
+  assert.equal(JSON.stringify(rows[3].sub), JSON.stringify(['Turn it on later in ', { t: 'the app settings', href: 'https://github.com/settings/apps/mercury-app' }, '.']));
   assert.equal(vm.runInContext('setupOpen()', sb), true, 'the page keeps watching for the install');
 
   // GitHub confirmed the install to the runner: connected, device flow still optional
   sb = page({ manifest: 'done', appSlug: 'mercury-app' });
   d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }]);
-  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)}, ${JSON.stringify(d)})`, sb);
   rows = draw(sb);
-  assert.deepEqual(rows.map(cls), [['sdone'], ['sdone'], ['sdone'], ['soptional']]);
-  assert.match(rows[1], /The app is on acme\/mercury/);
+  assert.deepEqual(states(rows), ['done', 'done', 'done', 'todo']);
   assert.equal(vm.runInContext('setupOpen()', sb), false);
-  // the part's state line, from these very rows: the optional step does not hold it back
-  const items = rows.map((li) => ({ classList: { contains: (c) => cls(li).includes(c) } }));
-  const ghState = { textContent: '' };
-  sb.$ = (id) => (id === 'humanSteps' ? { children: items } : id === 'ghState' ? ghState : null);
-  sb.manifestInFlight = () => false;
-  vm.runInContext('stepsPaint()', sb);
-  assert.equal(ghState.textContent, 'connected ✓');
+  assert.equal(vm.runInContext('setupCount([], ghFacts(Date.now()))', sb), 'ready ✓', 'the optional fact does not hold the count back');
 
   // and once GitHub has device flow on, the fourth ticks too
   sb = page({ manifest: 'done', appSlug: 'mercury-app' });
   d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:05:00Z' }]);
-  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
-  assert.deepEqual(cls(draw(sb)[3]), ['sdone', 'soptional']);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)}, ${JSON.stringify(d)})`, sb);
+  assert.equal(draw(sb)[3].state, 'done');
 });
 
 test('seedSetup is change-only, and an install link must be GitHub\'s', () => {
@@ -286,6 +278,12 @@ test('seedSetup is change-only, and an install link must be GitHub\'s', () => {
   vm.runInContext(`seedSetup(${c}, 'javascript:alert(1)')`, sb2);
   assert.equal(vm.runInContext('live.installUrl', sb2), null);
   assert.equal(vm.runInContext('seedSetup(null, null)', sb2), false);
+  // the repo it installs on rides the read, strict
+  const sb3 = page({ manifest: 'done', appSlug: 'a' });
+  vm.runInContext(`seedSetup(${c}, null, { repo: 'acme/mer cury' })`, sb3);
+  assert.equal(vm.runInContext('live.repo', sb3), null, 'a malformed repo never reaches the page');
+  vm.runInContext(`seedSetup(${c}, null, { repo: 'acme/mercury' })`, sb3);
+  assert.equal(vm.runInContext('live.repo', sb3), 'acme/mercury');
 });
 
 // ── 4. the finding is written down ──────────────────────────────────────────

package/tests/github_org_account.mjs

@@ -113,7 +113,7 @@ const PICKER = region("    /* ── whose GitHub account: mine or an organisati
 const ENSURE_REPO = region('    function ensureFreshRepo() {', "    $('doCreate').addEventListener('click'");
 const NOTE_ORG = region("    /* the organisation the server says this attempt's app is on: change-only */", '    function startManifest(btn) {');
 const START = region('    function startManifest(btn) {', '    /* the "start again" offer once a wait has clearly gone wrong');
-const SETTINGS = region('    /* the organisation that owns the app, when the founder made it on one (task 1004651) */', '    /* oauth-app — the ADR 0133 one-click GitHub-App manifest flow');
+const SETTINGS = region('    /* the organisation that owns the app, when the founder made it on one (task 1004651) */', '    /* When a fact was seen, said plainly');
 
 test('the page regions are still findable (a rename must fail loudly, not test nothing)', () => {
   for (const [name, r] of Object.entries({ PICKER, ENSURE_REPO, NOTE_ORG, START, SETTINGS })) assert.ok(r, `${name} region not found`);
@@ -165,7 +165,7 @@ function page({ state = {}, live = {} } = {}) {
     live: { manifest: null, manifestMsg: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, ...live },
     repoAccess: true, instanceId: 42, me: { github_login: 'founder' },
     hopForRepoAccess: () => false, syncHome() {}, saveDraft() {},
-    rememberManifest() {}, renderSteps() {}, pollManifest() {}, watchGhTab() {},
+    rememberManifest() {}, paintFacts() {}, repaintFacts() {}, pollManifest() {}, watchGhTab() {},
   };
   sandbox.manifestStartedAt = 0;
   vm.createContext(sandbox);