@bongos/core 1.19.273 → 1.19.275

package/tests/idea_routing.mjs

@@ -0,0 +1,571 @@
+// tests/idea_routing.mjs
+//
+// The CAPTURE-TIME ROUTING CORE — task 1003065 (BV1.R01, goal 1000071 "Idea
+// routing — work that has a home lands in it"). Spec:
+// docs/specs/bongos-v1-idea-routing.md.
+//
+// TWO THINGS UNDER TEST, and the split is the design:
+//   1. modules/ideas/routing.js — the landing matrix. PURE, so every cell is
+//      pinned here directly, with no Postgres and no fixture.
+//   2. modules/ideas/inbox.js captureIdea — the ONE TRANSACTION a routed capture
+//      runs. Driven through the #538 `deps.pool` seam (NODE_ENV==='test' only)
+//      with a SQL-aware fake client, the tests/goal_tier.mjs posture: we assert
+//      the STATEMENT SEQUENCE and the bound params, because the sequence IS the
+//      contract — an idea row, a task, and a lineage row that commit together or
+//      not at all.
+//
+// WHY THE ROLLBACK CASES ARE THE HEART OF THIS FILE. This goal exists because
+// Discord #bugs creates tasks with no idea row and no lineage, so the ideator
+// credit lane (goal 1000067) has nothing to pay against. A routed capture that
+// committed a task and lost its lineage row would manufacture that exact bug on
+// the path whose whole promise is that attribution survives (criterion C3). So
+// "a failure after the task insert leaves NOTHING behind" is not an edge case
+// here — it is the property.
+//
+// Run:  node tests/idea_routing.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const routing = require('../modules/ideas/routing.js');
+const { decideLanding, routedPriority, DEFAULT_ROUTED_PRIORITY } = routing;
+
+// The lifecycle port is how the ideas module reaches createTask (never an
+// import — the one-way module rule, ADR 0083). Register a stub provider, the
+// production wiring, exactly as tests/onboarding_route_signals.mjs does.
+const seams = require('../src/module-seams.js');
+seams._reset();
+let createTaskCalls = [];
+let createTaskImpl = async () => ({ id: 9001, status: 'backlog', goal_id: 7 });
+seams.registerProvider('lifecycle', {
+  createTask: async (args, deps) => {
+    createTaskCalls.push({ args, deps });
+    return createTaskImpl(args, deps);
+  },
+});
+
+const inbox = require('../modules/ideas/inbox.js');
+const { captureIdea } = inbox;
+
+const { test, summary } = makeRunner();
+
+const norm = (sql) => String(sql).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(norm(q.sql)));
+const seq = (queries) => queries.map((q) => norm(q.sql));
+
+// A routable goal: open, on a version that is still building.
+const LIVE_GOAL = { id: 7, status: 'open', version_id: 'BONGOS-V1', version_status: 'building' };
+const IDEA_ROW = {
+  id: 555, title: 'the thing is broken', body_md: 'steps', kind: 'bug',
+  suggested_version: null, suggested_priority: null, captured_at: 'T0', captured_by: 42,
+  status: 'promoted', promoted_to_task_id: null, reviewed_at: 'T0',
+  merged_into_idea_id: null, triage_note: null, suggested_goal_id: 7,
+};
+
+// A fake pool whose `connect()` and `query()` share ONE call log, so a test can
+// assert the whole transaction in order. Mirrors tests/goal_tier.mjs's fakePool.
+function fakePool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return {
+    query: (sql, params) => c._client.query(sql, params),
+    connect: c.connect,
+    queries: c._client.queries,
+  };
+}
+
+// The happy-path handler: a live goal, an idea row, and empty results elsewhere.
+function routableHandler(overrides = {}) {
+  return (s) => {
+    if (/FROM goals g JOIN versions v/.test(s)) {
+      return { rows: overrides.goalRows ?? [LIVE_GOAL] };
+    }
+    if (/INSERT INTO idea_inbox/.test(s)) return { rows: [{ ...IDEA_ROW, ...(overrides.idea || {}) }] };
+    return null;
+  };
+}
+
+function reset() {
+  createTaskCalls = [];
+  createTaskImpl = async () => ({ id: 9001, status: 'backlog', goal_id: 7 });
+}
+
+// =========================================================================
+// 1. The landing matrix — pure, every cell
+// =========================================================================
+
+await test('matrix: NO GOAL means the inbox, and that is the default path', () => {
+  for (const goalId of [null, undefined, '']) {
+    const d = decideLanding({ goalId, kind: 'bug', filerRank: 'archon' });
+    assert.equal(d.route, false, `goalId=${JSON.stringify(goalId)} must not route`);
+    assert.equal(d.reason, 'no_goal');
+  }
+  // A bug filed by an Archon is the MOST routable thing there is — proving it
+  // still stays put without a goal is what pins "routing is strictly additive".
+});
+
+await test('matrix: a bug from a trusted filer HARD-LANDS at ready (criterion C1)', () => {
+  for (const rank of ['metic', 'archon', 'ARCHON', 'Metic']) {
+    const d = decideLanding({ goalId: 7, kind: 'bug', filerRank: rank });
+    assert.deepEqual(d, { route: true, status: 'ready', reason: 'bug_trusted_filer' }, `rank ${rank}`);
+  }
+});
+
+await test('matrix: a bug from a sub-Metic filer soft-lands, awaiting a nod', () => {
+  for (const rank of ['xenos', 'thetes', 'XENOS']) {
+    const d = decideLanding({ goalId: 7, kind: 'bug', filerRank: rank });
+    assert.deepEqual(d, { route: true, status: 'backlog', reason: 'bug_awaiting_nod' }, `rank ${rank}`);
+  }
+});
+
+await test('matrix: FAIL-CLOSED — an absent or unrecognised rank never hard-lands', () => {
+  // The property that matters: no rank input can reach 'ready' except a real
+  // trusted tier. A landing decision that misfires puts unvetted work in the
+  // claimable queue, so every uncertainty resolves downward.
+  for (const rank of [null, undefined, '', 'archon-ish', 'admin', 'root', 0, {}, []]) {
+    const d = decideLanding({ goalId: 7, kind: 'bug', filerRank: rank });
+    assert.equal(d.status, 'backlog', `rank ${JSON.stringify(rank)} must not reach ready`);
+    assert.equal(d.reason, 'bug_awaiting_nod');
+  }
+});
+
+await test('matrix: every non-bug kind soft-lands, whoever files it (interview Q1)', () => {
+  // "Bugs are urgent-true; the rest gets a nod." cleanup/refactor/infra were the
+  // open question the owner settled — they soft-land like features, not like bugs.
+  for (const kind of ['feature', 'cleanup', 'refactor', 'infra', 'learning-capture',
+    'blocker-resolution', 'unclassified', 'spike']) {
+    const d = decideLanding({ goalId: 7, kind, filerRank: 'archon' });
+    assert.deepEqual(d, { route: true, status: 'backlog', reason: 'soft_landing' }, `kind ${kind}`);
+  }
+});
+
+await test('matrix: a Full Idea never auto-routes — it is the Board Room\'s subject', () => {
+  for (const grade of ['full', 'FULL', 'Full']) {
+    const d = decideLanding({ goalId: 7, kind: 'feature', grade, filerRank: 'archon' });
+    assert.deepEqual(d, { route: false, reason: 'full_idea_never_routes' }, `grade ${grade}`);
+  }
+  // ...while quick/spark/absent route exactly as their kind says.
+  for (const grade of ['quick', 'spark', null, undefined]) {
+    assert.equal(decideLanding({ goalId: 7, kind: 'feature', grade }).route, true, `grade ${grade}`);
+  }
+});
+
+await test('matrix: judgment kinds never auto-route', () => {
+  for (const kind of ['criterion-proposal', 'decision']) {
+    assert.deepEqual(
+      decideLanding({ goalId: 7, kind, filerRank: 'archon' }),
+      { route: false, reason: 'judgment_kind' },
+      `kind ${kind}`
+    );
+  }
+});
+
+await test('matrix: decideLanding never throws, on any input', () => {
+  for (const args of [undefined, {}, null && {}, { goalId: 7 }, { goalId: 7, kind: null }]) {
+    assert.doesNotThrow(() => decideLanding(args));
+  }
+  assert.equal(decideLanding().route, false, 'no args ⇒ no route');
+});
+
+await test('routedPriority: the filer\'s suggestion when sane, else the middle of the band', () => {
+  for (const p of [1, 2, 3, 4, 5]) assert.equal(routedPriority(p), p);
+  for (const p of [0, 6, -1, 99, null, undefined, 'high', 2.5, NaN]) {
+    assert.equal(routedPriority(p), DEFAULT_ROUTED_PRIORITY, `${JSON.stringify(p)} ⇒ default`);
+  }
+  assert.equal(DEFAULT_ROUTED_PRIORITY, 3);
+});
+
+// =========================================================================
+// 2. captureIdea — the NON-routing path is byte-for-byte today's behaviour
+// =========================================================================
+
+await test('capture with no goal: ONE insert, status open, no transaction at all', async () => {
+  reset();
+  const pool = fakePool((s) => (/INSERT INTO idea_inbox/.test(s)
+    ? { rows: [{ ...IDEA_ROW, status: 'open', suggested_goal_id: null, reviewed_at: null }] }
+    : null));
+  const idea = await captureIdea({ title: 'a thought', capturedBy: 42 }, { pool });
+  const sqls = seq(pool.queries);
+  assert.equal(sqls.filter((q) => /^BEGIN$/.test(q)).length, 0, 'no transaction is opened');
+  assert.equal(sqls.length, 1, 'exactly one statement');
+  assert.match(sqls[0], /INSERT INTO idea_inbox/);
+  assert.match(sqls[0], /'open'/, "status is 'open'");
+  assert.equal(createTaskCalls.length, 0, 'no task is created');
+  assert.deepEqual(idea.routing, { routed: false, reason: 'no_goal' });
+});
+
+await test('a named goal the matrix DECLINES is kept as the core_222 hint, not dropped', async () => {
+  reset();
+  const pool = fakePool((s) => (/INSERT INTO idea_inbox/.test(s)
+    ? { rows: [{ ...IDEA_ROW, kind: 'decision', status: 'open' }] } : null));
+  const idea = await captureIdea(
+    { title: 'which cache?', kind: 'decision', goalId: 7, capturedBy: 42, filerRank: 'archon' },
+    { pool }
+  );
+  const ins = find(pool.queries, /INSERT INTO idea_inbox/);
+  assert.match(norm(ins.sql), /suggested_goal_id/, 'the hint column is written');
+  assert.equal(ins.params[6], 7, 'the declined goal is carried forward as the hint');
+  assert.equal(createTaskCalls.length, 0, 'a judgment kind mints no task');
+  assert.deepEqual(idea.routing, { routed: false, reason: 'judgment_kind' },
+    'and the reason says WHY it declined, so a filer is not left guessing');
+});
+
+await test('the pre-routing validations still fire before any write', async () => {
+  reset();
+  const pool = fakePool(() => null);
+  await assert.rejects(() => captureIdea({ title: '', goalId: 7 }, { pool }),
+    (e) => e.code === 'TITLE_REQUIRED');
+  await assert.rejects(() => captureIdea({ title: 'x', kind: 'nonsense', goalId: 7 }, { pool }),
+    (e) => e.code === 'BAD_KIND');
+  await assert.rejects(() => captureIdea({ title: 'x', suggestedPriority: 9, goalId: 7 }, { pool }),
+    (e) => e.code === 'BAD_PRIORITY');
+  assert.equal(pool.queries.length, 0, 'a bad payload touches the database zero times');
+});
+
+// =========================================================================
+// 3. captureIdea — the ROUTED path: one transaction, in order
+// =========================================================================
+
+await test('a routed bug: idea + task + lineage in ONE transaction, in FK order', async () => {
+  reset();
+  createTaskImpl = async () => ({ id: 9001, status: 'ready', goal_id: 7, version_id: 'BONGOS-V1' });
+  const pool = fakePool(routableHandler());
+  const out = await captureIdea(
+    { title: 'the thing is broken', bodyMd: 'steps', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'archon' },
+    { pool }
+  );
+  const sqls = seq(pool.queries);
+  assert.equal(sqls[0], 'BEGIN', 'opens a transaction first');
+  assert.equal(sqls[sqls.length - 1], 'COMMIT', 'and commits last');
+
+  // The order is forced by the foreign keys, not by taste: lineage references
+  // BOTH rows, so idea → task → lineage is the only legal sequence.
+  const iGoal = sqls.findIndex((q) => /FROM goals g JOIN versions v/.test(q));
+  const iIdea = sqls.findIndex((q) => /INSERT INTO idea_inbox/.test(q));
+  const iLin = sqls.findIndex((q) => /INSERT INTO ideas_task_lineage/.test(q));
+  const iUpd = sqls.findIndex((q) => /UPDATE idea_inbox SET promoted_to_task_id/.test(q));
+  assert.ok(iGoal > 0 && iGoal < iIdea, 'the goal is validated BEFORE anything is written');
+  assert.ok(iIdea < iLin, 'the idea row exists before the lineage row references it');
+  assert.ok(iLin < iUpd, 'and promoted_to_task_id is closed out last');
+
+  // The idea is 'promoted' from birth — routing's claim is that it never needed
+  // a triage pass, and reviewed_at is stamped so the triage walk skips it.
+  const ins = find(pool.queries, /INSERT INTO idea_inbox/);
+  assert.match(norm(ins.sql), /'promoted'/, "status is 'promoted', not 'open'");
+  assert.match(norm(ins.sql), /reviewed_at/, 'reviewed_at is stamped');
+
+  // origin='route' — the third provenance ideas_003 widened the CHECK for.
+  const lin = find(pool.queries, /INSERT INTO ideas_task_lineage/);
+  assert.match(norm(lin.sql), /'route'/, "origin is 'route', not 'promote'");
+  assert.deepEqual(lin.params, [9001, 555], 'lineage binds (task_id, idea_id)');
+
+  assert.equal(out.routing.routed, true);
+  assert.equal(out.routing.task_id, 9001);
+  assert.equal(out.promoted_to_task_id, 9001, 'the returned row already reflects the link');
+  assert.equal(out.routed_task.id, 9001, 'and the task itself comes back');
+});
+
+await test('the task INSERT is ENLISTED in the transaction — the whole point', async () => {
+  reset();
+  const pool = fakePool(routableHandler());
+  await captureIdea(
+    { title: 'broken', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'metic' },
+    { pool }
+  );
+  assert.equal(createTaskCalls.length, 1);
+  const { args, deps } = createTaskCalls[0];
+  assert.ok(deps && deps.client, 'createTask is handed the tx client, not left on the pool');
+  assert.equal(typeof deps.client.query, 'function');
+  // If this ever regresses to a pool write, the task commits independently of
+  // its lineage row and we have rebuilt the Discord #bugs bug.
+});
+
+await test('the routed task carries the goal, the matrix status, and honest provenance', async () => {
+  reset();
+  const pool = fakePool(routableHandler());
+  await captureIdea(
+    { title: 'broken', bodyMd: 'the body', kind: 'bug', goalId: 7, capturedBy: 42, filerRank: 'archon' },
+    { pool }
+  );
+  const { args } = createTaskCalls[0];
+  assert.equal(args.goalId, 7, 'in the goal it was filed against');
+  assert.equal(args.versionId, 'BONGOS-V1', "on the GOAL'S version, never a caller-supplied one");
+  assert.equal(args.status, 'ready', 'at the matrix status');
+  assert.equal(args.kind, 'bug');
+  assert.equal(args.title, 'broken');
+  assert.equal(args.description, 'the body');
+  assert.equal(args.source, 'idea-route');
+  assert.equal(args.sourceRef, 'idea-555', 'keyed to the idea, so one idea mints one task');
+  // Deliberately absent: an explicit rank floor and a reward. createTask derives
+  // the ADR 0084/0085 floor itself and auto-assigns the capped reward; a filer
+  // must not be able to hand either one in.
+  assert.equal(args.requiresRank, undefined, 'no filer-supplied rank floor');
+  assert.equal(args.creditsReward, undefined, 'no filer-supplied reward');
+});
+
+await test('priority: the filer\'s suggestion rides through, else the band middle', async () => {
+  reset();
+  let pool = fakePool(routableHandler({ idea: { suggested_priority: 1 } }));
+  await captureIdea({ title: 'x', kind: 'bug', goalId: 7, suggestedPriority: 1, filerRank: 'archon' }, { pool });
+  assert.equal(createTaskCalls[0].args.priority, 1);
+
+  reset();
+  pool = fakePool(routableHandler());
+  await captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool });
+  assert.equal(createTaskCalls[0].args.priority, DEFAULT_ROUTED_PRIORITY);
+});
+
+// =========================================================================
+// 4. The refusals — a named goal that is not a LIVE HOME
+// =========================================================================
+
+await test('a goal that does not exist: 404-shaped refusal, nothing written', async () => {
+  reset();
+  const pool = fakePool(routableHandler({ goalRows: [] }));
+  await assert.rejects(
+    () => captureIdea({ title: 'x', kind: 'bug', goalId: 404, filerRank: 'archon' }, { pool }),
+    (e) => e.code === 'GOAL_NOT_FOUND' && e.goal_id === 404
+  );
+  assert.equal(find(pool.queries, /INSERT INTO idea_inbox/), undefined, 'no idea row');
+  assert.equal(createTaskCalls.length, 0, 'no task');
+  assert.ok(find(pool.queries, /^ROLLBACK$/), 'and the transaction is rolled back');
+});
+
+await test('an achieved or archived goal is not a home', async () => {
+  for (const status of ['achieved', 'archived']) {
+    reset();
+    const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, status }] }));
+    await assert.rejects(
+      () => captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool }),
+      (e) => e.code === 'GOAL_NOT_OPEN' && e.status === status,
+      `goal status ${status}`
+    );
+    assert.equal(createTaskCalls.length, 0);
+    assert.ok(find(pool.queries, /^ROLLBACK$/));
+  }
+});
+
+await test('THE 1000771 FAILURE: a non-building version can never receive routed work', async () => {
+  // The bug this whole goal was filed over — Discord #bugs hardcoded a SHIPPED
+  // version, so every reported bug landed in a shipped version's catch-all where
+  // nobody would look again. A route refuses rather than filing into a tomb.
+  for (const version_status of ['shipped', 'planning', 'frozen']) {
+    reset();
+    const pool = fakePool(routableHandler({ goalRows: [{ ...LIVE_GOAL, version_status }] }));
+    await assert.rejects(
+      () => captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool }),
+      (e) => e.code === 'VERSION_NOT_BUILDING' && e.version_status === version_status,
+      `version status ${version_status}`
+    );
+    assert.equal(createTaskCalls.length, 0, `no task on a ${version_status} version`);
+  }
+});
+
+// =========================================================================
+// 5. Atomicity — the property, not an edge case
+// =========================================================================
+
+await test('a task-create failure leaves NO orphan idea row (rollback)', async () => {
+  reset();
+  createTaskImpl = async () => { throw new Error('tasks table is on fire'); };
+  const pool = fakePool(routableHandler());
+  await assert.rejects(
+    () => captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool }),
+    /on fire/
+  );
+  assert.ok(find(pool.queries, /INSERT INTO idea_inbox/), 'the insert was attempted...');
+  assert.ok(find(pool.queries, /^ROLLBACK$/), '...and then rolled back');
+  assert.equal(find(pool.queries, /^COMMIT$/), undefined, 'never committed');
+});
+
+await test('a LINEAGE failure rolls the task back too — attribution or nothing (C3)', async () => {
+  reset();
+  const pool = fakePool((s) => {
+    if (/INSERT INTO ideas_task_lineage/.test(s)) throw new Error('lineage check violated');
+    return routableHandler()(s);
+  });
+  await assert.rejects(
+    () => captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool }),
+    /lineage/
+  );
+  assert.ok(find(pool.queries, /^ROLLBACK$/));
+  assert.equal(find(pool.queries, /^COMMIT$/), undefined,
+    'a task with no lineage row IS the bug this goal abolishes — it must not commit');
+});
+
+await test('the goal row is LOCKED, so it cannot be archived mid-route', async () => {
+  reset();
+  const pool = fakePool(routableHandler());
+  await captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool });
+  const sel = find(pool.queries, /FROM goals g JOIN versions v/);
+  assert.match(norm(sel.sql), /FOR SHARE OF g/, 'the goal row is held for the transaction');
+  assert.match(norm(sel.sql), /v\.status AS version_status/,
+    'and the version status is read in the SAME statement, not a second round trip');
+});
+
+await test('no lifecycle port ⇒ a loud refusal, never a silent inbox row', async () => {
+  reset();
+  const saved = seams.resolveOptional('lifecycle');
+  seams._reset();
+  try {
+    const pool = fakePool(routableHandler());
+    await assert.rejects(
+      () => captureIdea({ title: 'x', kind: 'bug', goalId: 7, filerRank: 'archon' }, { pool }),
+      (e) => e.code === 'LIFECYCLE_UNAVAILABLE'
+    );
+    assert.ok(find(pool.queries, /^ROLLBACK$/));
+    // The alternative — degrading to an inbox row — would tell the filer their
+    // bug became a task when it did not. Refusing is the honest failure.
+  } finally {
+    seams._reset();
+    seams.registerProvider('lifecycle', saved);
+  }
+});
+
+// =========================================================================
+// 6. THE ROUTE — POST /inbox, through the real handler
+//
+// The layer test above proves the transaction. This proves the CONTRACT a client
+// sees: where the filer's rank comes from, what the refusals look like, and that
+// omitting goal_id leaves the endpoint exactly as it was. Driven the
+// tests/idea_full_capture.mjs way — patch the doorway pool, pull the real
+// handler off the mounted router, stub req/res — so the same validator and the
+// same error map a client hits are the ones under test.
+// =========================================================================
+
+const apiDoorway = require('../src/module-api.js');
+
+let routeGoalRows = [LIVE_GOAL];
+apiDoorway.pool.query = async (sql) => {
+  if (/SELECT COUNT|count\(/i.test(String(sql))) return { rows: [{ n: '3', count: '3' }] };
+  if (/INSERT INTO idea_inbox/i.test(String(sql))) {
+    return { rows: [{ ...IDEA_ROW, status: 'open', suggested_goal_id: null }] };
+  }
+  return { rows: [] };
+};
+apiDoorway.pool.connect = async () => makeSqlAwareClient((s) => {
+  if (/FROM goals g JOIN versions v/.test(s)) return { rows: routeGoalRows };
+  if (/INSERT INTO idea_inbox/.test(s)) return { rows: [IDEA_ROW] };
+  return null;
+}).connect();
+
+const postInbox = (() => {
+  const router = require('../modules/ideas/routes/inbox.js')({});
+  const layer = router.stack.find((l) => l.route && l.route.path === '/inbox' && l.route.methods.post);
+  const handlers = layer.route.stack.map((h) => h.handle);
+  return handlers[handlers.length - 1]; // past requireBuilder
+})();
+
+// The res double the ADR 0116 envelope needs: res.fail is what every refusal in
+// this module calls, so a test that only implements .json would see a crash
+// instead of the 4xx a client gets.
+function call(body, builder = { id: '42', rank: 'archon' }) {
+  return new Promise((resolve) => {
+    const out = { status: 200, body: null };
+    const res = {
+      status(c) { out.status = c; return this; },
+      json(b) { out.body = b; resolve(out); return this; },
+      fail(code, statusOrOpts, details) {
+        const st = typeof statusOrOpts === 'number' ? statusOrOpts : (statusOrOpts && statusOrOpts.status) || 400;
+        out.status = st;
+        out.body = { error: { code, details: details || null } };
+        resolve(out);
+        return this;
+      },
+    };
+    Promise.resolve(postInbox({ body, builder, query: {} }, res)).catch((e) => {
+      out.status = 500; out.body = { threw: String(e && e.message) }; resolve(out);
+    });
+  });
+}
+
+await test('route: POST /inbox with a goal_id returns the TASK it became', async () => {
+  reset();
+  routeGoalRows = [LIVE_GOAL];
+  createTaskImpl = async () => ({ id: 9001, status: 'ready', goal_id: 7, version_id: 'BONGOS-V1' });
+  const r = await call({ title: 'the thing is broken', kind: 'bug', goal_id: 7 });
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.routed_task.id, 9001, 'the task is at the TOP level, not buried in the idea');
+  assert.equal(r.body.idea.routing.routed, true);
+  assert.equal(r.body.idea.routing.reason, 'bug_trusted_filer');
+  assert.equal(r.body.idea.routed_task, undefined, 'and is not duplicated inside the idea row');
+});
+
+await test('route: THE FILER\'S RANK COMES FROM AUTH, never from the body', async () => {
+  // The property that decides whether filing can outrun rank (criterion C4),
+  // asserted from both sides.
+  //
+  // (a) A forged rank in the body is refused outright — the BV1.R109c
+  //     unknown-field validator answers before the handler runs. A stronger
+  //     answer than ignoring it, and it means the matrix never sees the value.
+  reset();
+  routeGoalRows = [LIVE_GOAL];
+  const forged = await call({ title: 'broken', kind: 'bug', goal_id: 7, rank: 'archon' }, { id: '99', rank: 'xenos' });
+  assert.equal(forged.status, 400, JSON.stringify(forged.body));
+  assert.equal(forged.body.error.code, 'validation_failed');
+  assert.deepEqual(forged.body.error.details, [{ field: 'rank', reason: 'unknown_field' }]);
+  assert.equal(createTaskCalls.length, 0, 'and nothing was created');
+
+  // (b) With an IDENTICAL legal body, the landing differs purely by the
+  //     authenticated builder's rank — which is the positive proof that
+  //     req.builder.rank is what reaches the matrix.
+  const body = { title: 'broken', kind: 'bug', goal_id: 7 };
+  reset();
+  createTaskImpl = async (a) => ({ id: 1, status: a.status, goal_id: 7 });
+  const asArchon = await call({ ...body }, { id: '1', rank: 'archon' });
+  assert.equal(asArchon.status, 201, JSON.stringify(asArchon.body));
+  assert.equal(asArchon.body.idea.routing.status, 'ready');
+
+  reset();
+  createTaskImpl = async (a) => ({ id: 2, status: a.status, goal_id: 7 });
+  const asXenos = await call({ ...body }, { id: '2', rank: 'xenos' });
+  assert.equal(asXenos.status, 201, JSON.stringify(asXenos.body));
+  assert.equal(asXenos.body.idea.routing.status, 'backlog',
+    'same request, lower rank ⇒ soft landing: filing cannot outrun rank');
+});
+
+await test('route: a sub-Metic filer\'s bug lands at backlog, awaiting a nod', async () => {
+  reset();
+  routeGoalRows = [LIVE_GOAL];
+  createTaskImpl = async (a) => ({ id: 9002, status: a.status, goal_id: 7 });
+  const r = await call({ title: 'broken', kind: 'bug', goal_id: 7 }, { id: '99', rank: 'thetes' });
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.idea.routing.status, 'backlog');
+  assert.equal(r.body.idea.routing.reason, 'bug_awaiting_nod');
+});
+
+await test('route: the refusals map to 404 / 409, with the offending id echoed', async () => {
+  reset();
+  routeGoalRows = [];
+  let r = await call({ title: 'x', kind: 'bug', goal_id: 4040 });
+  assert.equal(r.status, 404, JSON.stringify(r.body));
+  assert.equal(r.body.error.code, 'GOAL_NOT_FOUND');
+
+  reset();
+  routeGoalRows = [{ ...LIVE_GOAL, status: 'archived' }];
+  r = await call({ title: 'x', kind: 'bug', goal_id: 7 });
+  assert.equal(r.status, 409, JSON.stringify(r.body));
+  assert.equal(r.body.error.code, 'GOAL_NOT_OPEN');
+
+  reset();
+  routeGoalRows = [{ ...LIVE_GOAL, version_status: 'shipped' }];
+  r = await call({ title: 'x', kind: 'bug', goal_id: 7 });
+  assert.equal(r.status, 409, JSON.stringify(r.body));
+  assert.equal(r.body.error.code, 'VERSION_NOT_BUILDING');
+});
+
+await test('route: NO goal_id is still the plain old capture — 201, no task', async () => {
+  reset();
+  const r = await call({ title: 'just a thought' });
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.equal(r.body.routed_task, undefined, 'nothing routed');
+  assert.equal(createTaskCalls.length, 0, 'no task created');
+  assert.equal(r.body.idea.routing.reason, 'no_goal');
+  assert.ok('open_count' in r.body, 'and the pre-routing response shape is intact');
+  assert.ok('kind_auto' in r.body);
+});
+
+summary('idea_routing');