@bongos/core 1.19.591 → 1.19.593

package/tests/version_build_slot.mjs

@@ -0,0 +1,157 @@
+// tests/version_build_slot.mjs — exactly one version builds at a time
+// (BV1.R19, task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9).
+//
+// THE INVARIANT EVERY OTHER RULE IN THIS GOAL STANDS ON. R03 refuses a goal on a
+// version that is not `planning`, which presumes "the version that is building"
+// names ONE row. With two, it does not: `currentBuildingVersionId` resolves the
+// ambiguity with `ORDER BY started_at DESC ... LIMIT 1`, so it picks one and says
+// nothing, and R03's gate silently has two answers depending on which row won.
+// The live instance is in exactly that state today (BONGOS-V1 and CB-V1 both
+// `building`) — task 1003614 (R27) resolves it; this file pins that a third can
+// never be created.
+//
+// WHY THE PREDICATE IS TESTED, NOT THE ROUTE. authorizeVersionBuild is pure — no
+// express, no DB, no pool — so its whole truth table runs here, including the
+// shapes a live-Postgres test would never bother to set up: a null in the rows, a
+// non-array, an absent argument. The ROUTE's job is only to gather the facts and
+// render the verdict verbatim, and the source assertions at the bottom pin that
+// it does exactly that and nothing else. Inlining the rule in the handler would
+// leave it testable only by string-matching the source, which passes just as
+// happily on a wrong branch.
+//
+// Run:  node --test tests/version_build_slot.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { authorizeVersionBuild, authorizeVersionCreate } =
+  require('../modules/lifecycle/routes/version-route-authz.js');
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const ROUTES = src('modules/lifecycle/routes/versions.js');
+const MIGRATION = src('migrations/core_233_versions_one_planning_idx.sql');
+
+// ---------------------------------------------------------------------------
+// The rule
+// ---------------------------------------------------------------------------
+
+test('an empty building slot allows the version', () => {
+  assert.deepEqual(authorizeVersionBuild({ building: [] }), { ok: true });
+});
+
+test('no argument at all is allowed — the default is "nothing is building"', () => {
+  assert.deepEqual(authorizeVersionBuild({}), { ok: true });
+});
+
+test('one building version refuses, with a named 409', () => {
+  const v = authorizeVersionBuild({ building: [{ id: 'BONGOS-V1', name: 'Cloud Bongos — platform (V1)' }] });
+  assert.equal(v.ok, false);
+  assert.equal(v.status, 409);
+  assert.equal(v.body.error, 'building_version_exists');
+});
+
+test('the refusal NAMES the version holding the slot, in the message and the payload', () => {
+  const v = authorizeVersionBuild({ building: [{ id: 'BONGOS-V1', name: 'platform' }] });
+  // The whole reason the rows are passed instead of a boolean: a caller told only
+  // "no" has to go look up which version to close, and a caller who looks it up
+  // is one step from cutting a version to get around the gate anyway.
+  assert.match(v.body.message, /BONGOS-V1/);
+  assert.deepEqual(v.body.building, [{ id: 'BONGOS-V1', name: 'platform' }]);
+});
+
+test('the live two-building-version violation refuses, and names the first', () => {
+  const v = authorizeVersionBuild({
+    building: [{ id: 'BONGOS-V1', name: 'platform' }, { id: 'CB-V1', name: 'dogfood' }],
+  });
+  assert.equal(v.ok, false);
+  assert.equal(v.body.building.length, 2);
+  assert.match(v.body.message, /BONGOS-V1/);
+});
+
+// ---------------------------------------------------------------------------
+// Shapes a live-Postgres test would not set up
+// ---------------------------------------------------------------------------
+
+test('nulls in the rows do not count as a version', () => {
+  assert.deepEqual(authorizeVersionBuild({ building: [null, undefined] }), { ok: true });
+});
+
+test('a non-array building is treated as empty, not as truthy', () => {
+  // A caller that hands over a bare count, or a bad DB read that returns an
+  // object, must not be able to LOOSEN the rule by accident — but neither should
+  // it hard-refuse a legitimate create. Both degrade to "nothing is building",
+  // which is the state the pre-check will then re-derive from the real table.
+  for (const bad of [1, 'yes', {}, null, undefined]) {
+    assert.deepEqual(authorizeVersionBuild({ building: bad }), { ok: true }, `building=${JSON.stringify(bad)}`);
+  }
+});
+
+test('the two slot rules are independent — building says nothing about planning', () => {
+  // Guards against a future refactor collapsing them into one status-branching
+  // function: the close flow (task 1003607, R20) promotes a version to `building`
+  // with no caller-supplied status to branch on.
+  assert.deepEqual(authorizeVersionBuild({ building: [] }), { ok: true });
+  assert.equal(authorizeVersionCreate({ status: 'planning', planning: [{ id: 'X' }] }).ok, false);
+  assert.equal(authorizeVersionCreate({ status: 'building', planning: [{ id: 'X' }] }).ok, true);
+});
+
+// ---------------------------------------------------------------------------
+// The wiring: the route gathers the facts and renders the verdict
+// ---------------------------------------------------------------------------
+
+test('POST /versions consults the building slot, and only when status is building', () => {
+  assert.match(ROUTES, /authorizeVersionBuild\(\{/);
+  // The read is CONDITIONAL on the requested status, mirroring the planning one:
+  // creating a `shipped` or `frozen` row is archival bookkeeping and must not pay
+  // for a query, nor be refused by a rule about a slot it is not entering.
+  assert.match(ROUTES, /status === 'building' \? await db\.versionsWithStatus\('building'\) : \[\]/);
+});
+
+test('the route renders the refusal verbatim — it does not restate the rule', () => {
+  assert.match(ROUTES, /if \(!buildDecision\.ok\) \{\s*return res\.status\(buildDecision\.status\)\.json\(buildDecision\.body\);/);
+  // No second copy of the message anywhere in the route.
+  assert.equal(ROUTES.includes('One version builds at a time'), false);
+});
+
+test('a 23505 on the planning index renders as the planning rule, not "id taken"', () => {
+  // The race-loser's pre-check passed because the winner had not committed. If
+  // this fell through to `version_exists` the caller would be told to rename a
+  // version that was never the problem, and would rename and retry forever.
+  assert.match(ROUTES, /err\.constraint\s*\|\|\s*''\)\s*===\s*'versions_one_planning_idx'/);
+  // And it renders that refusal BY RE-RUNNING THE GATE, never by writing the
+  // wording a second time — tests/one_planning_version.mjs pins the absence of
+  // the literal `planning_version_exists` in this handler, and an earlier draft
+  // of this very test asserted its presence, which is how the two suites caught
+  // each other. The gate owns the words; the route owns only the plumbing.
+  assert.match(ROUTES, /const raced = authorizeVersionCreate\(\{/);
+  assert.match(ROUTES, /return res\.status\(raced\.status\)\.json\(raced\.body\);/);
+});
+
+// ---------------------------------------------------------------------------
+// The migration
+// ---------------------------------------------------------------------------
+
+test('core_233 creates the planning index and NOT the building one', () => {
+  assert.match(MIGRATION, /CREATE UNIQUE INDEX IF NOT EXISTS versions_one_planning_idx/);
+  assert.match(MIGRATION, /WHERE status = 'planning'/);
+  // The deliberate omission ADR 0263 §9 asked for and the live data forbids. If a
+  // later edit adds it here, this test is the reminder that the migration will
+  // fail on any instance with two building versions — and that a skipped-with-a-
+  // NOTICE variant marks itself applied and never arms.
+  assert.equal(MIGRATION.includes('versions_one_building_idx'), false,
+    'the building index ships with R27 (task 1003614), in the migration that makes it legal');
+});
+
+test('the migration records WHY the building index is not here', () => {
+  // The reasoning is the artifact: without it the next reader files this as an
+  // oversight and "fixes" it into a wedged deploy.
+  assert.match(MIGRATION, /1003614/);
+});
+
+test('the route points at the same reason', () => {
+  assert.match(ROUTES, /1003614/);
+});

package/tests/version_close_route.mjs

@@ -0,0 +1,261 @@
+// tests/version_close_route.mjs — a version can finally close
+// (BV1.R12, task 1003599, goal 1000086, ADR 0250 D5, ADR 0263 §5).
+//
+// THE HOLE. Tasks close, criteria close, goals close — and a version only ever
+// moved by hand-run SQL on the droplet. `scripts/gds/version-close.js` still
+// prints that the API exposes no version status transitions, and the
+// `version.close` permission has sat at the archon floor since BV1.R105 with
+// NOTHING referencing it. A thing with no closing move does not close, which is
+// how two versions ended up building on one project at the same time.
+//
+// Two things this file is careful about, because both are places a correct
+// planner and a correct writer still add up to a broken endpoint:
+//
+//   THE MAINTENANCE GOAL IS FILTERED BY THE READ, not by the planner. It is
+//   exempt from the close count and always carries forward (ADR 0263 §7), so it
+//   must never appear in a refusal asking the caller to decide about it — asking
+//   someone to disposition a goal they are not allowed to disposition is worse
+//   than not asking.
+//
+//   ROLL_FORWARD WITHOUT A PLANNING VERSION IS A REFUSAL, never an auto-create.
+//   Cutting the successor implicitly inside a close is exactly the "fake hotfix
+//   version" ADR 0250 §3 built the override counter to prevent.
+//
+// Run:  node tests/version_close_route.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { planVersionClose, rollForwardNeedsPlanningVersion } = require('../modules/lifecycle/routes/version-route-authz.js');
+const { closeVersion, maintenanceGoalExemptSql, openNonMaintenanceGoals } = require('../modules/lifecycle/db.js');
+const { test, summary } = makeRunner();
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const BUILDING = { id: 'BONGOS-V1', status: 'building' };
+const GOALS = (...n) => n.map((i) => ({ id: String(i), title: `goal ${i}`, open_tasks: 0 }));
+const plan = (over = {}) => planVersionClose({ version: BUILDING, openGoals: GOALS(1, 2), reason: 'V1 is done', ...over });
+
+function txPool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { connect: c.connect, query: (sql, p) => c._client.query(sql, p), queries: c._client.queries };
+}
+const flat = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+
+// ---- only a building version closes ----------------------------------------
+
+await test('a missing version is a 404, not a refusal about its state', () => {
+  const r = planVersionClose({ version: null });
+  assert.equal(r.ok, false); assert.equal(r.status, 404); assert.equal(r.body.error, 'version_not_found');
+});
+
+await test('only a BUILDING version closes — every other status is refused BY NAME', () => {
+  for (const status of ['planning', 'shipped', 'frozen', 'nonsense', null]) {
+    const r = planVersionClose({ version: { id: 'V', status } });
+    assert.equal(r.ok, false, `'${status}' must not close`);
+    assert.equal(r.body.error, 'version_not_building');
+    assert.equal(r.body.status, status, 'the refusal says WHICH status refused, rather than asserting one');
+  }
+});
+
+await test('a building version holding nothing open closes in ONE call', () => {
+  const r = planVersionClose({ version: BUILDING, openGoals: [] });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, [], 'and needs no reason — nothing is being cut');
+});
+
+// ---- the two-step ----------------------------------------------------------
+
+await test('open goals refuse with a NAMED 409 that RETURNS the goals', () => {
+  const r = plan({ dispositions: null });
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'version_holds_open_goals');
+  assert.deepEqual(r.body.details.goals.map((g) => g.id), ['1', '2'],
+    'the caller decides per goal, so the goals travel with the refusal');
+});
+
+await test('a partial map is refused — nothing is carried or cut by omission', () => {
+  const r = plan({ dispositions: { 1: { verb: 'abandon' } } });
+  assert.equal(r.ok, false);
+  assert.equal(r.body.error, 'disposition_incomplete');
+  assert.deepEqual(r.body.details.goals.map((g) => g.id), ['2'], 'and it names which');
+});
+
+await test('cutting a goal without a reason is refused — the silent discard, one tier up', () => {
+  for (const reason of ['', '  ', null, undefined]) {
+    const r = plan({ dispositions: { 1: { verb: 'abandon' }, 2: { verb: 'abandon' } }, reason });
+    assert.equal(r.ok, false, `reason ${JSON.stringify(reason)} must not pass`);
+    assert.equal(r.body.error, 'close_reason_required');
+  }
+});
+
+await test('only roll_forward and abandon are verbs', () => {
+  for (const verb of ['carry', 'ROLL_FORWARD', 'delete', '', null, 7]) {
+    const r = plan({ dispositions: { 1: { verb }, 2: { verb: 'abandon' } } });
+    assert.equal(r.ok, false, `verb ${JSON.stringify(verb)} must not pass`);
+    assert.equal(r.body.error, 'bad_disposition');
+  }
+});
+
+await test('a complete map plans one step per goal, in the order the goals came in', () => {
+  const r = plan({ dispositions: { 1: { verb: 'roll_forward' }, 2: { verb: 'abandon' } } });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.plan, [{ goalId: 1, verb: 'roll_forward' }, { goalId: 2, verb: 'abandon' }]);
+});
+
+// ---- roll_forward needs somewhere to go ------------------------------------
+
+await test('roll_forward with NO planning version is refused, never auto-created', () => {
+  const r = rollForwardNeedsPlanningVersion({ plan: [{ goalId: 1, verb: 'roll_forward' }], planning: [] });
+  assert.ok(r, 'it must refuse');
+  assert.equal(r.status, 409);
+  assert.equal(r.body.error, 'no_planning_version');
+  assert.match(r.body.message, /Scope the next version first/,
+    'and say what to do — auto-cutting one here is the escape hatch ADR 0250 closed');
+});
+
+await test('an all-abandon close needs no planning version at all', () => {
+  assert.equal(rollForwardNeedsPlanningVersion({ plan: [{ goalId: 1, verb: 'abandon' }], planning: [] }), null);
+});
+
+await test('roll_forward WITH a planning version proceeds', () => {
+  assert.equal(rollForwardNeedsPlanningVersion({
+    plan: [{ goalId: 1, verb: 'roll_forward' }], planning: [{ id: 'BONGOS-V2' }],
+  }), null);
+});
+
+// ---- the maintenance exemption ---------------------------------------------
+
+await test('the exemption has ONE definition, and the open-goals read is its only caller', () => {
+  // R18 (task 1003605) swaps this body for `NOT g.is_maintenance` once the column
+  // exists. One call site is what makes that a one-line change instead of a hunt.
+  assert.equal(maintenanceGoalExemptSql('$1'), "g.title <> ($1 || ' — maintenance')");
+  const dbv = src('modules/lifecycle/db-versions.js');
+  const uses = (dbv.match(/maintenanceGoalExemptSql\(/g) || []).length;
+  assert.equal(uses, 3, 'declaration + the open-goals read + the post-apply re-count, and nothing else');
+});
+
+await test('the open-goals read excludes the maintenance goal and counts unfinished work', async () => {
+  const pool = txPool(() => ({ rows: [] }));
+  await openNonMaintenanceGoals('BONGOS-V1', { pool });
+  const q = flat(pool.queries[0]);
+  assert.match(q, /maintenance/, 'the maintenance goal must not be offered for disposition');
+  assert.match(q, /status = 'open'/);
+  assert.match(q, /open_tasks/, 'each goal carries how much work it still holds — most of the decision');
+  assert.match(q, /NOT IN \('shipped', 'abandoned'\)/, 'and counts it with the shared terminal set');
+});
+
+// ---- the write is one transaction ------------------------------------------
+
+function closePool({ status = 'building', goalStatus = 'open', remaining = 0 } = {}) {
+  return txPool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/FROM versions WHERE id = \$1 FOR UPDATE/.test(q)) return { rows: [{ id: 'V1', status }] };
+    if (/FROM goals WHERE id = \$1 AND version_id = \$2 FOR UPDATE/.test(q)) return { rows: [{ id: 1, title: 'g', status: goalStatus }] };
+    if (/UPDATE tasks SET status = 'abandoned'/.test(q)) return { rows: [{ id: 11 }, { id: 12 }] };
+    if (/count\(\*\)::int AS n FROM goals/.test(q)) return { rows: [{ n: remaining }] };
+    if (/UPDATE versions SET status = 'shipped'/.test(q)) return { rows: [{ id: 'V1', status: 'shipped' }] };
+    return { rows: [] };
+  });
+}
+
+await test('the whole close runs inside ONE transaction, version locked first', async () => {
+  const pool = closePool();
+  const out = await closeVersion({ versionId: 'V1', plan: [{ goalId: 1, verb: 'abandon' }], reason: 'done' }, { pool });
+  assert.equal(out.version.status, 'shipped');
+  assert.deepEqual(out.applied, [{ goal_id: '1', verb: 'abandon', result: 'archived', tasks_abandoned: 2 }]);
+  const sqls = pool.queries.map(flat);
+  assert.equal(sqls.filter((q) => q === 'BEGIN').length, 1);
+  assert.equal(sqls.filter((q) => q === 'COMMIT').length, 1);
+  const lock = sqls.findIndex((q) => /FROM versions WHERE id = \$1 FOR UPDATE/.test(q));
+  const firstWrite = sqls.findIndex((q) => /^UPDATE tasks/.test(q));
+  assert.ok(lock !== -1 && lock < firstWrite, 'lock the version, then apply — a goal must not be created mid-close');
+  assert.ok(sqls.findIndex((q) => /UPDATE versions SET status = 'shipped'/.test(q)) < sqls.indexOf('COMMIT'));
+});
+
+await test('an abandoned goal takes its open tasks with it, stamped with the close reason', async () => {
+  const pool = closePool();
+  await closeVersion({ versionId: 'V1', plan: [{ goalId: 1, verb: 'abandon' }], reason: 'cut in the ten-areas review' }, { pool });
+  const kill = pool.queries.find((q) => /UPDATE tasks SET status = 'abandoned'/.test(flat(q)));
+  assert.ok(kill, 'the tasks must not survive their goal');
+  assert.equal(kill.params[1], 'Abandoned: cut in the ten-areas review',
+    'the same stamp R14 writes — the ledger reads identically whichever door retired the work');
+  assert.match(flat(kill), /NOT IN \('shipped', 'abandoned'\)/, 'and only the unfinished ones');
+});
+
+await test('a roll_forward abandons NOTHING and says the successor is still pending', async () => {
+  const pool = closePool();
+  const out = await closeVersion({ versionId: 'V1', plan: [{ goalId: 1, verb: 'roll_forward' }], reason: 'r' }, { pool });
+  assert.deepEqual(out.applied, [{ goal_id: '1', verb: 'roll_forward', result: 'carried_pending_successor' }]);
+  assert.equal(pool.queries.some((q) => /UPDATE tasks SET status = 'abandoned'/.test(flat(q))), false,
+    'carrying a goal forward must never cut its work');
+  assert.equal(pool.queries.some((q) => /UPDATE goals SET status = 'archived'/.test(flat(q))), false);
+});
+
+await test('a carried goal is EXCLUDED from the post-apply re-count, or a close could never carry anything', async () => {
+  const pool = closePool();
+  await closeVersion({ versionId: 'V1', plan: [{ goalId: 1, verb: 'roll_forward' }], reason: 'r' }, { pool });
+  const recount = pool.queries.find((q) => /count\(\*\)::int AS n FROM goals/.test(flat(q)));
+  assert.match(flat(recount), /NOT \(g\.id = ANY\(\$2::bigint\[\]\)\)/);
+  assert.deepEqual(recount.params[1], [1], 'the carried goal is expected to still be open');
+});
+
+await test('the re-check runs against committed state and rolls back rather than half-closing', async () => {
+  const pool = closePool({ remaining: 2 });
+  await assert.rejects(
+    closeVersion({ versionId: 'V1', plan: [{ goalId: 1, verb: 'abandon' }], reason: 'r' }, { pool }),
+    (e) => e.code === 'CLOSE_INCOMPLETE_AFTER_APPLY' && e.remaining === 2
+  );
+  const sqls = pool.queries.map(flat);
+  assert.ok(sqls.includes('ROLLBACK'));
+  assert.equal(sqls.some((q) => /UPDATE versions SET status = 'shipped'/.test(q)), false, 'the version is not closed');
+});
+
+await test('a version that stopped building mid-call rolls back', async () => {
+  const pool = closePool({ status: 'shipped' });
+  await assert.rejects(
+    closeVersion({ versionId: 'V1', plan: [], reason: 'r' }, { pool }),
+    (e) => e.code === 'VERSION_NOT_BUILDING' && e.versionStatus === 'shipped'
+  );
+  assert.ok(pool.queries.map(flat).includes('ROLLBACK'));
+});
+
+await test('the promotion seam runs INSIDE the transaction, after the flip', async () => {
+  // R20 (task 1003607) hooks here. ensureMaintenanceGoal returns null for a
+  // non-building version, so a carry-over run before the flip silently carries
+  // nothing — the ordering is load-bearing, not stylistic (ADR 0263 §8).
+  const pool = closePool();
+  let sawStatus = null; let ranAt = -1;
+  await closeVersion({ versionId: 'V1', plan: [], reason: 'r' }, {
+    pool,
+    onClosed: async (client) => { ranAt = pool.queries.length; sawStatus = 'called'; await client.query('SELECT 1 AS seam'); return { promoted: null }; },
+  });
+  const sqls = pool.queries.map(flat);
+  assert.equal(sawStatus, 'called', 'the seam must be offered');
+  assert.ok(sqls.findIndex((q) => /UPDATE versions SET status = 'shipped'/.test(q)) < ranAt, 'after the flip');
+  assert.ok(sqls.indexOf('SELECT 1 AS seam') < sqls.indexOf('COMMIT'), 'and before the commit');
+});
+
+// ---- the route is wired to all of it ---------------------------------------
+
+await test('the route declares its body, so a typo cannot read as "no map given"', () => {
+  const V = src('modules/lifecycle/routes/versions.js');
+  const route = V.slice(V.indexOf("router.post('/versions/:id/close'"));
+  assert.match(route, /validateOrRespond\(req, res, \{[\s\S]*?dispositions: \{ type: 'object' \}/);
+  assert.match(route, /requirePermission\('version\.close'\)/, 'behind the permission nothing referenced until now');
+  assert.match(route, /db\.openNonMaintenanceGoals\(versionId\)/, 'the maintenance goal is filtered by the READ');
+  assert.match(route, /rollForwardNeedsPlanningVersion/);
+  const planIdx = route.indexOf('planVersionClose(');
+  const writeIdx = route.indexOf('db.closeVersion(');
+  assert.ok(planIdx !== -1 && writeIdx !== -1 && planIdx < writeIdx, 'decide, then write');
+});
+
+await test('version-close.js no longer being the only door is R23; this route exists for it to call', () => {
+  const V = src('modules/lifecycle/routes/versions.js');
+  assert.match(V, /router\.post\('\/versions\/:id\/close'/, 'the route the CLI will drive');
+});
+
+summary();

package/tests/version_override_visibility.mjs

@@ -0,0 +1,176 @@
+// tests/version_override_visibility.mjs — an override nobody can count is
+// indistinguishable from no gate at all (BV1.R15, task 1003602, goal 1000086,
+// ADR 0250 §3).
+//
+// THE RULE R03 CREATED, AND THE HOLE R15 CLOSES. A goal may only be added to a
+// version still in `planning`; an Archon may override that and admit one into a
+// version already building, recording a reason. R07 (task 1003594) built the
+// record and put the count on `GET /versions/:id/progress`. That route is not a
+// surface anyone opens — the roadmap reads the ROLLUP, the board reads
+// `listGoals`, and neither carried a single bit about admissions. So the
+// override existed, was recorded, and was invisible everywhere a person looks,
+// which is the same accountability as not recording it.
+//
+// WHAT THIS FILE PINS: the count rides the rollup the hall actually reads; the
+// board can tell an admitted goal from a normal one; the detail names WHO and
+// WHY; and the zero case renders nothing, so the line is a signal rather than
+// chrome.
+//
+// Run:  node --test tests/version_override_visibility.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { listGoals, listVersionAdmissions, versionProgress } = require('../modules/lifecycle/db.js');
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const GOALS_RENDER = src('modules/hall-ui/public/goals-render.js');
+const ROADMAP = src('modules/hall-ui/public/roadmap.js');
+
+function fakePool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+
+// ---------------------------------------------------------------------------
+// The rollup — the surface the roadmap reads
+// ---------------------------------------------------------------------------
+
+test('versionProgress asks for the admission count', async () => {
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await versionProgress({ pool });
+  assert.match(seen, /lifecycle_goal_version_admissions/,
+    'the rollup must carry the override count — R07 put it only on /versions/:id/progress, which the roadmap never calls');
+  assert.match(seen, /COALESCE\(adm\.admission_count, 0\)/,
+    'a version nobody widened has no row in the aggregate, so the zero comes from COALESCE, not from a manufactured join row');
+});
+
+test('versionProgress returns admission_count as a number, defaulting to 0', async () => {
+  const pool = fakePool(() => ({
+    rows: [{
+      version_id: 'BONGOS-V1', name: 'platform', status: 'building',
+      shipped_count: 1, total_count: 2, shipped_weight: 1, total_weight: 2,
+      done_when: null, criteria_count: 3,
+      lifecycle_completed_count: 0, lifecycle_confirmed_count: 0, lifecycle_shipped_count: 1,
+      admission_count: 2,
+    }],
+  }));
+  const [row] = await versionProgress({ pool });
+  assert.equal(row.admission_count, 2);
+  assert.equal(typeof row.admission_count, 'number',
+    'the client compares it to 0; a string "2" from the pg driver would render but never equal 0');
+});
+
+// ---------------------------------------------------------------------------
+// The board — which goals were admitted
+// ---------------------------------------------------------------------------
+
+test('listGoals carries an `admitted` flag', async () => {
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await listGoals({ versionId: 'BONGOS-V1' }, { pool });
+  assert.match(seen, /EXISTS \(SELECT 1 FROM lifecycle_goal_version_admissions/);
+  assert.match(seen, /AS admitted/);
+});
+
+test('the board flag is EXISTS, not a join that could duplicate a goal', async () => {
+  // A LEFT JOIN would return one row per admission. There is one today, but the
+  // table has no unique constraint on goal_id, so a second admission row would
+  // silently make the goal appear twice in the board's list.
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await listGoals({}, { pool });
+  assert.equal(/LEFT JOIN lifecycle_goal_version_admissions/.test(seen), false);
+});
+
+test('listGoals still filters and orders as before', async () => {
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await listGoals({ versionId: 'X', status: 'open', limit: 5 }, { pool });
+  assert.match(seen, /version_id = \$1/);
+  assert.match(seen, /status = \$2/);
+  // Unqualified, exactly as before: the admissions EXISTS names `goals.id` in
+  // full so no other line of this query had to change. tests/goal_tier.mjs pins
+  // this literal ordering text.
+  assert.match(seen, /ORDER BY version_id, sort_order, created_at, id/);
+});
+
+// ---------------------------------------------------------------------------
+// The detail — by whom, and why
+// ---------------------------------------------------------------------------
+
+test('listVersionAdmissions resolves the admitter to a NAME', async () => {
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await listVersionAdmissions('BONGOS-V1', { pool });
+  // ADR 0250 §3 asks "by whom". A numeric builder id does not answer it, and
+  // making every caller issue a second lookup per row is how a counter stops
+  // being read.
+  assert.match(seen, /admitted_by_login/);
+  assert.match(seen, /admitted_by_name/);
+});
+
+test('an admission whose admitter was offboarded still appears', async () => {
+  // The one failure mode that matters: an inner JOIN would DROP the row, hiding
+  // exactly the history someone with an interest in hiding it would target.
+  let seen = null;
+  const pool = fakePool((s) => { seen = s; return { rows: [] }; });
+  await listVersionAdmissions('BONGOS-V1', { pool });
+  assert.match(seen, /LEFT JOIN builders b ON b\.id = a\.admitted_by/);
+});
+
+// ---------------------------------------------------------------------------
+// The hall
+// ---------------------------------------------------------------------------
+
+test('the goal detail renders WHO admitted it', () => {
+  assert.match(GOALS_RENDER, /goal-badge--admitted/);
+  assert.match(GOALS_RENDER, /admitted_by_name \|\| adm\.admitted_by_login \|\| \('builder ' \+ adm\.admitted_by\)/,
+    'falls back through name → login → id so an offboarded admitter still renders as someone');
+});
+
+test('the REASON is rendered, not hidden in a title attribute', () => {
+  // A tooltip is invisible on touch and to anyone not already suspicious. An
+  // override you have to hover to justify is the same unaccountable override.
+  assert.match(GOALS_RENDER, /why\.className = 'goal-admission';/);
+  assert.match(GOALS_RENDER, /adm\.reason \? ` — \$\{escapeHtml\(String\(adm\.reason\)\)\}`/);
+});
+
+test('an admission with no recorded reason says so rather than rendering blank', () => {
+  assert.match(GOALS_RENDER, /no reason recorded/);
+});
+
+test('a normally-created goal renders nothing at all', () => {
+  // `admitted` is null for every goal that went through the gate — the positive
+  // fact "this did not skip it", not missing data.
+  assert.match(GOALS_RENDER, /const adm = d\.admitted;/);
+  assert.match(GOALS_RENDER, /const admittedSpan = adm\s*\n?\s*\?/);
+  assert.match(GOALS_RENDER, /if \(adm\) \{/);
+});
+
+test('the board renders one chip, and does not leak the reason onto every row', () => {
+  assert.match(GOALS_RENDER, /fact-chip--admitted/);
+  assert.match(GOALS_RENDER, /g\.admitted\s*\n?\s*\?/);
+  // The chip's own markup must not interpolate a reason: listGoals deliberately
+  // returns a boolean, and an Archon's free text does not belong on a list row.
+  const chip = GOALS_RENDER.slice(GOALS_RENDER.indexOf('const admittedChip'), GOALS_RENDER.indexOf('const factsHtml'));
+  assert.equal(/reason/.test(chip), false);
+});
+
+test('the roadmap renders the count only when it is above zero', () => {
+  assert.match(ROADMAP, /function admissionNote\(v\)/);
+  assert.match(ROADMAP, /if \(n === 0\) return '';/,
+    'a permanent "0 overrides" line is chrome a reader learns to skip — and would go on skipping when it became 2');
+  assert.match(ROADMAP, /admissions: Number\(p\.admission_count\) \|\| 0/);
+  assert.match(ROADMAP, /\$\{admissionNote\(v\)\}/, 'the helper must actually be called from the goals block');
+});
+
+test('the roadmap note pluralises, so "1 goals" never ships', () => {
+  assert.match(ROADMAP, /n === 1 \? '' : 's'/);
+});