@bongos/core 1.19.936 → 1.19.937

package/tests/idea_goal_ratification.mjs

@@ -0,0 +1,553 @@
+// tests/idea_goal_ratification.mjs
+//
+// task 1004096 (BV2.R17, spec R23, goal 1000095, criterion
+// `ideator-full-idea-shapes-the-space`) — ratifying a Full Idea into a GOAL:
+// the goal half beside the existing criterion half, one transaction, the five
+// answers landing on the goal.
+//
+// THE REAL GATE CODE RUNS. The `lifecycle` port is registered with the ACTUAL
+// modules/lifecycle/goal-from-idea.js, whose db calls all take the transaction
+// client this suite hands them — so the version gate, the protected-scope gate
+// and the admission gate are exercised rather than stubbed. A suite that
+// registered a permissive fake would prove the ideas half calls A port; the
+// question worth answering is whether it calls one that refuses.
+//
+// THE FIVE THINGS MOST LIKELY TO BE WRONG, each with a test that fails loudly:
+//
+//   • THE ANSWERS ARRIVING IN jsonb ORDER. Postgres does not preserve key order,
+//     so a composer that walks Object.keys(field_values) renders the five
+//     answers in whatever order the row happens to have. §1 stores them
+//     SHUFFLED and asserts the declared order comes out.
+//   • THE BOARD GATE BEING DECORATIVE. "The ideator recommends, the board
+//     decides" is a comment unless a ratification with no passing sitting
+//     refuses AND writes nothing. §2.
+//   • THE RECOMMENDATION BECOMING A DECISION. The column must be recorded and
+//     never branched on: an idea whose author said 'criterion' still ratifies as
+//     a goal when the board chose a goal, and NULL survives as NULL. §3.
+//   • A METIC-REACHABLE WAY AROUND POST /goals. `idea.ratify`'s floor is metic
+//     (ADR 0157), so if this path skips the protected-scope, admission or
+//     building-version gates it is a bypass of all three. §4.
+//   • PAYING THE AUTHOR TWICE. The board close already awards karma and credit
+//     on the pass; a karma INSERT here would double-pay invisibly. §5.
+//
+// DB-free the idea_recommendation.mjs way — pool.query AND pool.connect are
+// patched on the doorway before the modules load, so the transaction itself is
+// driven rather than skipped.
+//
+// Run:  node tests/idea_goal_ratification.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const api = require('../src/module-api.js');
+
+// ---------------------------------------------------------------------------
+// the stub transaction client — every statement is recorded, and each write
+// echoes back the row a real one would, so a test can assert what was BOUND.
+// ---------------------------------------------------------------------------
+
+let queries = [];
+// What the idea + grade read returns. Reassigned per test.
+let storedIdea = null;
+// What the version read returns — the R03 gate's whole input.
+let storedVersion = { id: 'TEST-V1', status: 'planning' };
+// Set to a SQL fragment to make the matching statement throw a unique violation.
+let uniqueViolationOn = null;
+
+function answer(sql, params) {
+  if (uniqueViolationOn && new RegExp(uniqueViolationOn, 'i').test(sql)) {
+    const err = new Error('duplicate key value violates unique constraint');
+    err.code = '23505';
+    throw err;
+  }
+  // The idea + its grade row, locked. Matched before the bare idea_inbox read.
+  if (/FROM idea_inbox i/i.test(sql)) return { rows: storedIdea ? [storedIdea] : [] };
+  if (/FROM versions WHERE id/i.test(sql)) return { rows: storedVersion ? [storedVersion] : [] };
+  if (/INSERT INTO goals/i.test(sql) || /WITH next_order/i.test(sql)) {
+    return { rows: [{
+      id: '5001', version_id: params[0], title: params[1], description: params[2],
+      scope_modules: params[3], status: params[4], created_by: params[5], subtitle: params[6],
+    }] };
+  }
+  if (/INSERT INTO done_when_criteria/i.test(sql)) {
+    return { rows: [{
+      id: '6001', version_id: params[0], criterion_id: params[1],
+      criterion_md: params[2], goal_id: params[3], sort_order: params[4], satisfied: false,
+    }] };
+  }
+  if (/INSERT INTO ideas_goal_ratifications/i.test(sql)) {
+    return { rows: [{ id: '7001', ratified_at: 'T' }] };
+  }
+  if (/COALESCE\(MAX\(sort_order\)/i.test(sql)) return { rows: [{ next: 3 }] };
+  if (/SELECT COUNT/i.test(sql)) return { rows: [{ n: 0, count: 0 }] };
+  return { rows: [] };
+}
+
+const record = async (sql, params = []) => {
+  queries.push({ sql, params });
+  return answer(sql, params);
+};
+
+api.pool.query = record;
+api.pool.connect = async () => ({ query: record, release() {} });
+
+// ---------------------------------------------------------------------------
+// the ports — the REAL lifecycle goal-creation policy, and a board stub whose
+// answer each test sets.
+// ---------------------------------------------------------------------------
+
+let boardPass = { item_id: '900', outcome: 'passed', opened_at: 'A', closed_at: 'B' };
+const goalFromIdea = require('../modules/lifecycle/goal-from-idea.js');
+const seams = api;
+if (!seams.hasProvider('lifecycle')) {
+  seams.registerProvider('lifecycle', { createRatifiedGoal: goalFromIdea.createRatifiedGoal });
+}
+if (!seams.hasProvider('government')) {
+  seams.registerProvider('government', { boardPassForIdea: async () => boardPass });
+}
+
+const { BASE_V2_TEMPLATE, fieldOrder } = require('../modules/ideas/templates.js');
+const ratify = require('../modules/ideas/ratify.js');
+const inbox = require('../modules/ideas/inbox.js');
+// inbox.js is required for its `registerSeams()` side effect (the `ideas.capture`
+// and `ideas.descent` port registrations), the way every route-driving suite here
+// builds the module's surface; the route under test lives in its own file because
+// inbox.js is at the size ratchet (see that file's header).
+require('../modules/ideas/routes/inbox.js')({});
+const routesFactory = require('../modules/ideas/routes/ratify-goal.js');
+
+const router = routesFactory({});
+function handlerFor(path, method) {
+  const layer = router.stack.find((l) => l.route && l.route.path === path && l.route.methods[method]);
+  assert.ok(layer, `route ${method.toUpperCase()} ${path} exists`);
+  const stack = layer.route.stack.map((s) => s.handle);
+  return stack[stack.length - 1];
+}
+const postRatifyGoal = handlerFor('/inbox/:id/ratify-goal', 'post');
+
+function drive(handler, { body = {}, params = {}, builderId = '9', rank = 'metic' } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = { body, params, query: {}, builder: { id: builderId, rank } };
+    const res = {
+      statusCode: 200,
+      status(c) { this.statusCode = c; return this; },
+      json(payload) { resolve({ status: this.statusCode, payload }); },
+      fail(code, status, extra) {
+        const s = typeof status === 'number' ? status : (status && status.status) || 500;
+        resolve({ status: s, payload: { error: code, ...(extra || {}) } });
+      },
+    };
+    Promise.resolve(handler(req, res)).catch(reject);
+  });
+}
+
+// The five answers, each recognisable in the rendered prose.
+const ANSWERS = Object.fromEntries(
+  BASE_V2_TEMPLATE.fields.map((f) => [f.key, `ANSWER-${f.key.toUpperCase()}`]),
+);
+
+// A stored row whose field_values keys are in a DIFFERENT order from the
+// declaration — what a jsonb column actually hands back.
+function shuffledAnswers() {
+  const keys = [...Object.keys(ANSWERS)].reverse();
+  return Object.fromEntries(keys.map((k) => [k, ANSWERS[k]]));
+}
+
+function fullIdea(over = {}) {
+  return {
+    id: '77', title: 'a thought that turned out to be a goal', kind: 'feature', status: 'open',
+    captured_by: '42', grade: 'full', template_key: 'base-v2',
+    field_values: shuffledAnswers(), recommendation: 'goal', ...over,
+  };
+}
+
+const goalInsert = () => queries.find((q) => /INSERT INTO goals/i.test(q.sql) || /WITH next_order/i.test(q.sql));
+const criterionInsert = () => queries.find((q) => /INSERT INTO done_when_criteria/i.test(q.sql));
+const auditInsert = () => queries.find((q) => /INSERT INTO ideas_goal_ratifications/i.test(q.sql));
+const ideaUpdate = () => queries.find((q) => /UPDATE idea_inbox/i.test(q.sql));
+const ran = (re) => queries.some((q) => re.test(q.sql));
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  queries = [];
+  storedIdea = fullIdea();
+  storedVersion = { id: 'TEST-V1', status: 'planning' };
+  boardPass = { item_id: '900', outcome: 'passed', opened_at: 'A', closed_at: 'B' };
+  uniqueViolationOn = null;
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+const OK_BODY = { target_version: 'TEST-V1', scope_modules: ['ideas'] };
+
+// ---------------------------------------------------------------------------
+// 1. the five answers land on the goal
+// ---------------------------------------------------------------------------
+
+await test('the whole act commits: a goal, its criterion, the idea promoted, an audit row', async () => {
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 201, JSON.stringify(r.payload));
+  assert.equal(r.payload.goal.id, '5001');
+  assert.equal(r.payload.criterion.id, '6001');
+  assert.ok(goalInsert(), 'a goal was created');
+  assert.ok(criterionInsert(), 'a done-when criterion was created');
+  assert.ok(ideaUpdate(), 'the idea was marked promoted');
+  assert.ok(auditInsert(), 'the ratification was recorded');
+  assert.ok(ran(/^BEGIN$/) && ran(/^COMMIT$/), 'one transaction, committed');
+  assert.ok(!ran(/^ROLLBACK$/), 'and not rolled back');
+});
+
+await test('every one of the five answers reaches the goal description', async () => {
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  const description = goalInsert().params[2];
+  for (const f of BASE_V2_TEMPLATE.fields) {
+    assert.ok(description.includes(f.label), `the ${f.key} LABEL is rendered`);
+    assert.ok(description.includes(ANSWERS[f.key]), `the ${f.key} ANSWER is rendered`);
+  }
+});
+
+await test('the done-when criterion is the success answer, verbatim', async () => {
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  // The mapping the proof task (BV2.R25) names: done-when from "what does a
+  // successful implementation of the idea look like".
+  assert.equal(criterionInsert().params[2], ANSWERS.success);
+  assert.equal(criterionInsert().params[1], 'idea-77', 'criterion_id is derived from the idea, so a re-ratify trips UNIQUE');
+  assert.equal(criterionInsert().params[3], '5001', 'and it hangs on the new goal, not loose on the version');
+});
+
+await test('the success answer ALSO stays in the description', async () => {
+  // Dropping it to avoid "duplication" would take the clearest statement of the
+  // goal's purpose out of the one place a builder reads.
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.ok(goalInsert().params[2].includes(ANSWERS.success));
+});
+
+await test('order comes from the DECLARATION, not from the stored key order', async () => {
+  // storedIdea.field_values is reversed — this is the jsonb defect in the flesh.
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  const description = goalInsert().params[2];
+  const positions = fieldOrder(BASE_V2_TEMPLATE).map((k) => description.indexOf(ANSWERS[k]));
+  const sorted = [...positions].sort((a, b) => a - b);
+  assert.deepEqual(positions, sorted, `answers rendered out of declared order: ${positions.join(',')}`);
+});
+
+await test('the goal takes the idea’s own title, and the origin is stated in its prose', async () => {
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(goalInsert().params[1], 'a thought that turned out to be a goal');
+  assert.match(goalInsert().params[2], /Full Idea .*77/, 'a reader learns where the scope came from');
+});
+
+// ---------------------------------------------------------------------------
+// 2. the board gate
+// ---------------------------------------------------------------------------
+
+await test('no passing sitting: refused 409, and NOTHING is written', async () => {
+  boardPass = null;
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'BOARD_HAS_NOT_PASSED');
+  assert.ok(!goalInsert(), 'no goal');
+  assert.ok(!ideaUpdate(), 'the idea is still open');
+  assert.ok(!auditInsert(), 'nothing recorded');
+  assert.ok(ran(/^ROLLBACK$/), 'the transaction rolled back');
+});
+
+await test('the passing item id is recorded, so the decision is traceable', async () => {
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(auditInsert().params[3], '900');
+});
+
+await test('an instance with no Board Room cannot ratify at all', async () => {
+  // A missing authority system is a denial, never an admission.
+  const realResolve = api.resolveOptional;
+  api.resolveOptional = (k) => (k === 'government' ? undefined : realResolve(k));
+  try {
+    const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+    assert.equal(r.status, 503);
+    assert.equal(r.payload.error, 'NO_BOARD');
+    assert.ok(!ran(/^BEGIN$/), 'refused before the transaction opened');
+  } finally { api.resolveOptional = realResolve; }
+});
+
+// ---------------------------------------------------------------------------
+// 3. the recommendation is recorded, never obeyed
+// ---------------------------------------------------------------------------
+
+await test('an author who recommended CRITERION is still ratified as a goal', async () => {
+  // Spec decision 9: the board may decide the thought was bigger than its author
+  // thought. Refusing here would make the recommendation a decision.
+  storedIdea = fullIdea({ recommendation: 'criterion' });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 201, 'the board decided, not the author');
+  assert.equal(auditInsert().params[6], 'criterion', 'and what they recommended is on the record');
+  assert.equal(r.payload.recommendation_at_filing, 'criterion');
+});
+
+await test('an author who said nothing stays having said nothing', async () => {
+  storedIdea = fullIdea({ recommendation: null });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 201);
+  assert.equal(auditInsert().params[6], null, 'NULL, never a default and never the string "null"');
+  assert.equal(r.payload.recommendation_at_filing, null);
+});
+
+// ---------------------------------------------------------------------------
+// 4. every gate POST /goals applies, applied here
+// ---------------------------------------------------------------------------
+
+await test('a protected scope is refused to a Metic, and creates nothing', async () => {
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { target_version: 'TEST-V1', scope_modules: ['lifecycle'] }, rank: 'metic',
+  });
+  assert.equal(r.status, 403);
+  assert.equal(r.payload.error, 'ARCHON_REQUIRED_FOR_PROTECTED_SCOPE');
+  assert.ok(!goalInsert(), 'no goal — this is the bypass the gate exists to stop');
+  assert.ok(ran(/^ROLLBACK$/));
+});
+
+await test('the same protected scope is allowed to an Archon', async () => {
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { target_version: 'TEST-V1', scope_modules: ['lifecycle'] }, rank: 'archon',
+  });
+  assert.equal(r.status, 201, JSON.stringify(r.payload));
+  assert.deepEqual(goalInsert().params[3], ['lifecycle']);
+});
+
+await test('an unknown module key is a named 400 — a wall that can name nothing is no wall', async () => {
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { target_version: 'TEST-V1', scope_modules: ['not-a-module'] }, rank: 'archon',
+  });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.error, 'UNKNOWN_MODULE');
+  assert.deepEqual(r.payload.unknown, ['not-a-module']);
+  assert.ok(!goalInsert());
+});
+
+await test('a BUILDING version will not take a ratified goal without an admission', async () => {
+  storedVersion = { id: 'TEST-V1', status: 'building' };
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY, rank: 'archon' });
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'version_not_planning');
+  assert.ok(!goalInsert(), 'a version’s scope does not grow because an idea passed');
+});
+
+await test('an Archon admits it with a reason, and the admission is filed', async () => {
+  storedVersion = { id: 'TEST-V1', status: 'building' };
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' },
+    body: { ...OK_BODY, admit_reason: 'the board carried this and it cannot wait for the next version' },
+    rank: 'archon',
+  });
+  assert.equal(r.status, 201, JSON.stringify(r.payload));
+  assert.equal(r.payload.admitted, true);
+  // createGoal's statement carries the admission in its last two params.
+  const params = goalInsert().params;
+  assert.equal(String(params[8]), '9', 'admitted_by is the ratifier');
+  assert.match(String(params[9]), /cannot wait/, 'and the reason survives');
+});
+
+await test('a Metic may not admit, and is told by RANK before the version is read', async () => {
+  storedVersion = { id: 'TEST-V1', status: 'building' };
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { ...OK_BODY, admit_reason: 'I would like this now please' }, rank: 'metic',
+  });
+  assert.equal(r.status, 403);
+  assert.equal(r.payload.error, 'ARCHON_REQUIRED_FOR_ADMISSION');
+  assert.ok(!ran(/FROM versions WHERE id/i), 'a Metic must not learn whether the override would have worked');
+});
+
+await test('a shipped version is closed history, and no admission reopens it', async () => {
+  storedVersion = { id: 'TEST-V1', status: 'shipped' };
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { ...OK_BODY, admit_reason: 'it really is quite important' }, rank: 'archon',
+  });
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'version_closed');
+  assert.ok(!goalInsert());
+});
+
+await test('an unknown version is a 404 from the gate, not an FK violation later', async () => {
+  storedVersion = null;
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY, rank: 'archon' });
+  assert.equal(r.status, 404);
+  assert.equal(r.payload.error, 'version_not_found');
+});
+
+await test('an instance with no lifecycle module cannot create a goal', async () => {
+  const realResolve = api.resolveOptional;
+  api.resolveOptional = (k) => (k === 'lifecycle' ? undefined : realResolve(k));
+  try {
+    const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+    assert.equal(r.status, 503);
+    assert.equal(r.payload.error, 'NO_LIFECYCLE');
+    assert.ok(!ran(/^BEGIN$/));
+  } finally { api.resolveOptional = realResolve; }
+});
+
+// ---------------------------------------------------------------------------
+// 5. who owns it, and who is paid
+// ---------------------------------------------------------------------------
+
+await test('the RATIFIER owns the goal, not whoever had the idea', async () => {
+  // createGoal makes created_by the owner AND inserts a 'lead' membership, and a
+  // lead authors tasks inside the scope wall. Filing an idea is open to every
+  // rank, so owning the goal it became would be an unreviewed grant of authority.
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY, builderId: '9' });
+  assert.equal(String(goalInsert().params[5]), '9', 'created_by is the ratifier');
+  assert.equal(String(auditInsert().params[7]), '42', 'and the author’s claim is on the audit row');
+  assert.equal(String(auditInsert().params[8]), '9');
+  assert.notEqual(String(goalInsert().params[5]), '42', 'the author does not become goal lead by having an idea');
+});
+
+await test('nobody is paid here — the board close already paid the author', async () => {
+  await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.ok(!ran(/karma_log/i), 'no karma INSERT: awardAuthorRatifyKarma already ran at the close');
+  assert.ok(!ran(/credit/i), 'and no credit line');
+});
+
+// ---------------------------------------------------------------------------
+// 6. what cannot be ratified
+// ---------------------------------------------------------------------------
+
+await test('a QUICK idea is not a Full Idea and is refused', async () => {
+  storedIdea = fullIdea({ grade: 'quick', template_key: null, field_values: null });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.error, 'NOT_A_FULL_IDEA');
+  assert.equal(r.payload.grade, 'quick');
+  assert.ok(!goalInsert());
+});
+
+await test('an idea already promoted cannot be ratified again', async () => {
+  storedIdea = fullIdea({ status: 'promoted' });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'IDEA_NOT_OPEN');
+});
+
+await test('a missing idea is a 404', async () => {
+  storedIdea = null;
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 404);
+  assert.equal(r.payload.error, 'IDEA_NOT_FOUND');
+});
+
+await test('a base-v1 Full Idea is refused, naming its vintage', async () => {
+  // v1's five questions contain no answer describing a finished implementation,
+  // so there is nothing to write a done-when FROM — and inventing one is the
+  // never-invent-a-field rule. Its author can resubmit against v2.
+  storedIdea = fullIdea({ template_key: 'base-v1', field_values: { purpose: 'x', big_picture: 'y' } });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.error, 'CANNOT_COMPOSE_GOAL');
+  assert.equal(r.payload.reason, 'template_has_no_goal_shape');
+  assert.equal(r.payload.template_key, 'base-v1');
+  assert.ok(!goalInsert());
+});
+
+await test('a blank success answer is refused rather than made an empty criterion', async () => {
+  // A goal whose only criterion is '' is one the close gate can never satisfy.
+  storedIdea = fullIdea({ field_values: { ...ANSWERS, success: '   ' } });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.reason, 'done_when_answer_missing');
+  assert.equal(r.payload.field, 'success');
+});
+
+await test('a non-numeric ratifier is a named 400, not a generic 500', async () => {
+  // Unreachable under normal auth — req.builder.id is always numeric — so this
+  // is the defensive branch being actually exercised rather than assumed. Left
+  // unmapped it fell through to `ratify_goal_failed`, which says nothing.
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY, builderId: 'not-a-number' });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.error, 'BAD_RATIFIER');
+  assert.ok(!ran(/^BEGIN$/), 'refused before the transaction opened');
+});
+
+await test('a refusal puts named fields on the wire, never the whole thrown object', async () => {
+  // The refusals spread two INTERNAL objects into themselves — the composer's
+  // result and the lifecycle port's verdict — so a `{ ...err }` response body
+  // would publish `ok`, and one edit later `description` and `criterionMd`.
+  storedIdea = fullIdea({ template_key: 'base-v1', field_values: { purpose: 'x' } });
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 400);
+  assert.equal(r.payload.reason, 'template_has_no_goal_shape', 'the useful fields still arrive');
+  assert.equal(r.payload.ok, undefined, 'the composer’s own ok flag does not ride out');
+  assert.equal(r.payload.description, undefined);
+  assert.equal(r.payload.criterionMd, undefined);
+});
+
+await test('a gate refusal keeps its status and its sentence, and nothing else', async () => {
+  const r = await drive(postRatifyGoal, {
+    params: { id: '77' }, body: { target_version: 'TEST-V1', scope_modules: ['lifecycle'] }, rank: 'metic',
+  });
+  assert.equal(r.status, 403, 'the port’s own status is rendered, not re-mapped');
+  assert.deepEqual(r.payload.scope_modules, ['lifecycle'], 'the caller learns which scope refused');
+  assert.equal(r.payload.ok, undefined);
+  assert.equal(r.payload.code, undefined, 'the code rides in the envelope, not twice in the body');
+});
+
+await test('target_version is required — a goal cannot be created nowhere', async () => {
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: { scope_modules: [] } });
+  assert.equal(r.status, 400);
+  assert.ok(!ran(/^BEGIN$/), 'the body validator refuses before anything opens');
+});
+
+await test('a double ratification trips UNIQUE and reads as already ratified', async () => {
+  uniqueViolationOn = 'INSERT INTO ideas_goal_ratifications';
+  const r = await drive(postRatifyGoal, { params: { id: '77' }, body: OK_BODY });
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'IDEA_ALREADY_RATIFIED');
+  assert.ok(ran(/^ROLLBACK$/), 'so the goal the losing transaction made is rolled back');
+});
+
+// ---------------------------------------------------------------------------
+// 7. the composer, exercised directly
+// ---------------------------------------------------------------------------
+
+await test('the goal shape registry maps only vintages it actually declares', async () => {
+  assert.ok(Object.hasOwn(ratify.GOAL_SHAPE_BY_TEMPLATE, 'base-v2'));
+  assert.equal(Object.hasOwn(ratify.GOAL_SHAPE_BY_TEMPLATE, 'base-v1'), false,
+    'v1 has no success answer; mapping it would invent one');
+  // Own-property lookup only — a template_key of 'constructor' must not resolve
+  // up the prototype chain to a truthy non-shape.
+  const r = ratify.composeGoalFromFullIdea({ ideaId: 1, templateKey: 'constructor', fieldValues: ANSWERS });
+  assert.equal(r.ok, false);
+  assert.equal(r.reason, 'unknown_template');
+});
+
+await test('the composer is pure and refuses a missing field_values', async () => {
+  for (const bad of [null, undefined, 'a string', [1, 2]]) {
+    const r = ratify.composeGoalFromFullIdea({ ideaId: 1, templateKey: 'base-v2', fieldValues: bad });
+    assert.equal(r.ok, false, `${JSON.stringify(bad)} is refused`);
+  }
+});
+
+await test('a field the row does not carry is skipped, not rendered as an empty heading', async () => {
+  const { why_had, ...withoutWhyHad } = ANSWERS;
+  const r = ratify.composeGoalFromFullIdea({ ideaId: 1, templateKey: 'base-v2', fieldValues: withoutWhyHad });
+  assert.equal(r.ok, true);
+  const label = BASE_V2_TEMPLATE.fields.find((f) => f.key === 'why_had').label;
+  assert.ok(!r.description.includes(label), 'no heading for a question with no answer under it');
+  assert.ok(r.description.includes(ANSWERS.scope), 'the answers that exist are still rendered');
+});
+
+// ---------------------------------------------------------------------------
+// 8. the facade
+// ---------------------------------------------------------------------------
+
+await test('the facade re-exports the transaction and nothing nobody needs', async () => {
+  assert.equal(inbox.ratifyFullIdeaAsGoal, ratify.ratifyFullIdeaAsGoal);
+  // The pure composer and the shape registry are NOT on the facade — a
+  // re-export no caller needs is an unused export the dead-code ratchet counts.
+  // Anything wanting them requires ./ratify directly, as this file does.
+  assert.equal(inbox.composeGoalFromFullIdea, undefined);
+  assert.equal(inbox.GOAL_SHAPE_BY_TEMPLATE, undefined);
+  // And the criterion half is untouched beside it.
+  assert.equal(typeof inbox.ratifyCriterionProposal, 'function');
+});
+
+console.log(`\nidea_goal_ratification: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);