@bongos/core 1.19.293 → 1.19.295

package/scripts/gds/spark.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Mark one of YOUR OWN quick ideas as a Big Idea Spark — "I have the spark but
+// not the full picture, someone develop this" (task 1002920 / BV1.R144, goal
+// 1000062).
+//
+// The mark is the CONSENT that makes cross-builder development fair: until an
+// author sets it, their quick idea is not available for someone else to develop.
+// So this command only ever works on ideas you filed — the server enforces that
+// against idea_inbox.captured_by, and no rank can override it.
+//
+// It exists as its own command rather than a flag on capture.js because sparking
+// is an act on an EXISTING idea, not a way to file one (capture refuses
+// grade='spark' for the same reason). The builders-hall control is R154; this is
+// the terminal path, and the two hit the same route.
+//
+// Usage:
+//   node scripts/gds/spark.js 123              # mark idea 123 as a spark
+//   node scripts/gds/spark.js 123 --undo       # withdraw the mark (back to quick)
+//
+// Exit codes:
+//   0  the idea now carries the grade you asked for (including when it already did)
+//   1  api / network error, or the server refused (not yours / not a quick idea)
+//   2  bad invocation
+
+const { cliClient, requireSession, hasFlag } = require('./cli-lib');
+
+// The server's refusals, in the ideator's own words. Anything unmapped falls
+// through to the raw envelope — a new server-side rule should be visible, not
+// swallowed by a generic "failed".
+const REFUSALS = {
+  not_your_idea: (d) =>
+    'That idea is not yours to mark. The spark mark is the author\'s consent to have their\n'
+    + 'idea developed, so only the builder who filed it can give or withdraw it.',
+  not_a_quick_idea: (d) =>
+    `That idea is already a Full Idea (grade=${d.grade || 'full'}). It carries the developed\n`
+    + 'picture the spark mark asks for — there is nothing to hand off.',
+  idea_not_open: (d) =>
+    `That idea is ${d.status || 'no longer open'}, so it is not awaiting development.\n`
+    + '(You can still withdraw an existing mark with --undo.)',
+  idea_not_found: () => 'No idea with that id.',
+};
+
+// The envelope is ADR 0116's { error: { code, message, details } } — the extras a
+// route passes as res.fail's third argument land under `details`, NOT spread onto
+// `error`. Reading them off the wrong level is a silent "undefined" in the
+// message rather than a crash, so tests/idea_spark_mark.mjs pins explain()
+// against the real envelope() builder.
+function explain(status, data) {
+  const err = data && data.error;
+  const code = err && typeof err === 'object' ? err.code : err;
+  const detail = (err && typeof err === 'object' && err.details) || {};
+  const say = typeof code === 'string' ? REFUSALS[code] : null;
+  if (say) return say(detail);
+  let rendered;
+  try { rendered = JSON.stringify(data, null, 2); } catch { rendered = String(data); }
+  return `spark failed (${status}): ${rendered}`;
+}
+
+async function main() {
+  await requireSession();
+
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith('-'));
+  const id = Number(positional[0]);
+  const undo = hasFlag('--undo');
+
+  if (!Number.isInteger(id) || id <= 0) {
+    console.error('usage: node scripts/gds/spark.js <idea-id> [--undo]');
+    process.exit(2);
+  }
+
+  const api = await cliClient();
+  const r = undo
+    ? await api.inbox.deleteInboxIdSpark({ id })
+    : await api.inbox.postInboxIdSpark({ id, body: {} });
+
+  if (!r.ok) {
+    console.error(explain(r.status, r.data));
+    process.exit(1);
+  }
+
+  const { idea, sparked, unchanged } = r.data;
+  const title = idea && idea.title ? ` — ${idea.title}` : '';
+  if (unchanged) {
+    console.log(`Idea ${id} was already ${sparked ? 'a spark' : 'a quick idea'}${title}. Nothing changed.`);
+  } else if (sparked) {
+    console.log(`Idea ${id} is now a Big Idea Spark${title}.`);
+    console.log('Another builder can develop it into a Full Idea; you keep the attribution.');
+  } else {
+    console.log(`Idea ${id} is a quick idea again${title}. The mark is withdrawn.`);
+  }
+}
+
+// Only explain() is exported — tests/idea_spark_mark.mjs pins its message layer
+// against the real envelope. REFUSALS stays private: it is the message table,
+// reachable through explain(), and a second export would be dead surface.
+module.exports = { explain };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}

package/scripts/gds/strand-watch.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/strand-watch.js — say out loud that a ship got stuck (task 1003163).
+//
+// THE GAP. Nothing watched for a stranded ship. On 2026-08-22 a manual status sweep found
+// task 1002483 parked at `completed` for THREE DAYS carrying 651 lines of tested work on a
+// local branch, task 1002792 parked two days behind it, and task 1002459 sitting at
+// `confirmed` for FOUR DAYS with no artifact anywhere. Not one of the three had produced a
+// single signal; all were found by accident.
+//
+// WHY land-watch.js IS NOT THIS (it looks like it should be). land-watch.js renders the
+// SHIPPED banner after an async CI land (task 1687). It cannot detect a strand: it reads
+// machine-local breadcrumbs that ship.js writes only at CONFIRMED-exit — so a task parked at
+// `completed` never gets one — it DROPS a breadcrumb after 30 minutes by design, and it is
+// per-machine, so a strand on a box nobody reopens is invisible forever.
+//
+// THE SIGNAL ALREADY EXISTS. This is the part worth knowing: the publish-reconciler ALREADY
+// diagnoses the worst case and already writes it down. Task 1002459 has carried
+// `needs_rebase_reason = 'strand:land_not_proven'` since 2026-08-18 — the reconciler probed
+// it, could not prove a land, gave up, and recorded exactly that. Nobody ever read the field.
+// So this module is not a detector. It is the READOUT of a diagnosis the system performs and
+// then discards, which is why it is small.
+//
+// SHAPE COPIED FROM deploy-divergence.js, deliberately. That check was written after the
+// ten-day staleness incident (blocker 1000097 / task 1002521), is wired into SessionStart in
+// .claude/settings.json, and on 2026-08-22 it reported the stale pin in the first message of
+// the session — which is how that whole day's work started. A cheap check, on a path that
+// already runs, reporting loudly, beats a monitoring subsystem that can itself silently stop.
+// So: fail-open, bounded, and SILENT when the board is clean.
+//
+// Usage:
+//   node scripts/gds/strand-watch.js                 # human-readable report
+//   node scripts/gds/strand-watch.js --line          # ONE line, or nothing; always exit 0
+//   node scripts/gds/strand-watch.js --json          # machine shape
+//   node scripts/gds/strand-watch.js --hours N       # override the `completed` threshold
+//
+// Exit codes: 0 always on --line (fail-open). Otherwise 0 clean, 1 strands found, 2 undetermined.
+
+const { apiCall, arg, hasFlag } = require('./cli-lib');
+
+// ---- thresholds -------------------------------------------------------------
+// Reasoned, not magic. Written down because a future reader will want to retune them.
+//
+// `confirmed` means the grade PASSED and only the land is outstanding. The publish-reconciler
+// sweeps every ~5 minutes, so one hour is twelve missed sweeps — already anomalous, while
+// still leaving room for a slow CI queue or a transient GitHub failure.
+const CONFIRMED_STALE_MS = 60 * 60 * 1000;
+// `completed` means the grade did NOT pass. A builder may legitimately be mid-recovery for
+// hours (see the /grade-recover loop), so this is deliberately generous: 12 hours means the
+// strand survived a night, which no active recovery does. The three real cases were 2–3 DAYS.
+const COMPLETED_STALE_MS = 12 * 60 * 60 * 1000;
+
+// A reconciler-recorded strand needs NO threshold. The reconciler already probed every branch
+// convention, failed to prove a land, and wrote the reason down; waiting longer cannot change
+// that verdict, and task 1002459 proves the alternative is sitting for days.
+const STRAND_REASON_PREFIX = 'strand:';
+
+const WATCHED = ['completed', 'confirmed'];
+const DEFAULT_TIMEOUT_MS = 8000;
+// Page size per watched status. A queue past this would silently lose the OLDEST strands —
+// exactly the class of quiet cap this whole check exists to abolish — so a full page is
+// reported as `truncated` rather than passed off as complete. 200 is far above any healthy
+// board (the real numbers were 1 and 2).
+const PAGE_LIMIT = 200;
+
+// ---- classification (pure — this is the unit-testable core) -----------------
+
+// Task ids are numeric and reconciler reasons come from a fixed vocabulary, so both are safe
+// to print. TITLES ARE NOT, and that omission is deliberate — see the trust-boundary note on
+// `line()` below.
+const safeId = (v) => (/^\d{1,19}$/.test(String(v)) ? String(v) : null);
+const safeReason = (v) => (typeof v === 'string' && /^[a-z0-9_:.-]{1,64}$/i.test(v) ? v : null);
+
+function humanAge(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  const h = ms / 3600000;
+  if (h < 1) return `${Math.max(1, Math.round(ms / 60000))}m`;
+  if (h < 48) return `${Math.round(h)}h`;
+  return `${Math.round(h / 24)}d`;
+}
+
+// Decide whether ONE task is a strand, and if so which shape and what fixes it. The two
+// shapes need opposite responses, which is the whole reason to distinguish them:
+//   completed -> the GRADE parked it; re-grade or fix findings (/grade-recover).
+//   confirmed -> the grade passed and the LAND is outstanding (/merge-mode is the fallback).
+// A reconciler-recorded strand is called out separately because it is terminal without a
+// human: the automated healers have already refused it.
+function classifyStrand(task, { nowMs, confirmedStaleMs = CONFIRMED_STALE_MS, completedStaleMs = COMPLETED_STALE_MS } = {}) {
+  const t = task || {};
+  const status = String(t.status || '');
+  if (!WATCHED.includes(status)) return null;
+
+  const id = safeId(t.id);
+  if (!id) return null;
+
+  const updated = Date.parse(t.updated_at || '');
+  const ageMs = Number.isFinite(updated) && Number.isFinite(nowMs) ? nowMs - updated : NaN;
+
+  const reason = safeReason(t.needs_rebase_reason);
+  const reconcilerGaveUp = status === 'confirmed'
+    && t.needs_rebase === true
+    && !!reason
+    && reason.toLowerCase().startsWith(STRAND_REASON_PREFIX);
+
+  if (reconcilerGaveUp) {
+    return {
+      id, status, ageMs, age: humanAge(ageMs), shape: 'unprovable', reason,
+      remedy: 'check whether any artifact exists at all — a confirm with no branch and nothing on main was codeless',
+    };
+  }
+
+  const limit = status === 'confirmed' ? confirmedStaleMs : completedStaleMs;
+  // An unreadable updated_at must not manufacture a strand — fail QUIET on bad data here,
+  // because this text is injected into every session and a false alarm trains people to
+  // scroll past the real one.
+  if (!Number.isFinite(ageMs) || ageMs <= limit) return null;
+
+  return status === 'confirmed'
+    ? { id, status, ageMs, age: humanAge(ageMs), shape: 'unlanded', reason: null,
+        remedy: '/merge-mode is the documented manual fallback' }
+    : { id, status, ageMs, age: humanAge(ageMs), shape: 'ungraded', reason: null,
+        remedy: '/grade-recover diagnoses which of the three shapes parked it' };
+}
+
+// Sort worst-first so a truncated line shows the most urgent: reconciler-refused, then oldest.
+const SHAPE_RANK = { unprovable: 0, unlanded: 1, ungraded: 2 };
+function rankStrands(strands) {
+  return strands.slice().sort((a, b) => {
+    const d = (SHAPE_RANK[a.shape] ?? 9) - (SHAPE_RANK[b.shape] ?? 9);
+    return d !== 0 ? d : (b.ageMs || 0) - (a.ageMs || 0);
+  });
+}
+
+// ---- fetch ------------------------------------------------------------------
+
+async function check({ nowMs = Date.now(), timeoutMs = DEFAULT_TIMEOUT_MS, confirmedStaleMs, completedStaleMs, call = apiCall } = {}) {
+  // CONCURRENT, not sequential. This runs on the SessionStart path beside deploy-divergence,
+  // so a serial loop would double the latency the builder waits through for no reason.
+  const withTimeout = (p, label) => Promise.race([
+    p,
+    new Promise((_, rej) => setTimeout(() => rej(new Error(`timed out after ${timeoutMs}ms`)), timeoutMs)),
+  ]).catch((e) => { throw new Error(`could not read ${label} tasks: ${e.message || e}`); });
+
+  let pages;
+  try {
+    pages = await Promise.all(WATCHED.map(async (status) => {
+      const res = await withTimeout(call('GET', `/api/gds/tasks?status=${status}&limit=${PAGE_LIMIT}`), status);
+      const body = res && (res.data || res);
+      const tasks = body && Array.isArray(body.tasks) ? body.tasks : null;
+      if (!tasks) throw new Error(`unexpected shape from /tasks?status=${status}`);
+      return { status, tasks };
+    }));
+  } catch (e) {
+    return { undetermined: true, reason: e.message || String(e), strands: [], truncated: [] };
+  }
+
+  const strands = [];
+  const truncated = [];
+  for (const { status, tasks } of pages) {
+    if (tasks.length >= PAGE_LIMIT) truncated.push(status);
+    for (const t of tasks) {
+      const s = classifyStrand(t, { nowMs, confirmedStaleMs, completedStaleMs });
+      if (s) strands.push(s);
+    }
+  }
+  return { undetermined: false, ok: strands.length === 0 && !truncated.length, strands: rankStrands(strands), truncated };
+}
+
+// ---- rendering --------------------------------------------------------------
+
+// ONE line for SessionStart, or null. Null IS the silence: a clean board must say nothing,
+// or the line becomes wallpaper and the real warning gets scrolled past.
+//
+// TRUST BOUNDARY — why no task titles. A task title is builder-authored free text, and this
+// string is injected into an agent's context at the start of every session. Interpolating a
+// title raw would hand anyone who can file a task a standing prompt-injection channel, which
+// is the same reasoning deploy-divergence.js applies to the /version response it reads (it
+// accepts only a strict semver for exactly this purpose). Ids and a fixed reason vocabulary
+// carry all the signal that is needed and none of the risk — the agent can GET the task.
+function line(r, { max = 3 } = {}) {
+  if (!r || r.undetermined) return null;
+  const trunc = Array.isArray(r.truncated) && r.truncated.length
+    ? ` (the ${r.truncated.join(' and ')} queue${r.truncated.length > 1 ? 's' : ''} filled a full ${PAGE_LIMIT}-row page, so older strands may be unlisted)`
+    : '';
+  if (!r.strands.length) {
+    // A full page with no strand still means coverage was capped — say so rather than imply
+    // a clean board, which is the silent-cap failure this check is against.
+    return trunc ? `Strand check could not see the whole board${trunc}. Run: node scripts/gds/strand-watch.js` : null;
+  }
+  const shown = r.strands.slice(0, max)
+    .map((s) => `task ${s.id} (${s.status}, ${s.age}${s.reason ? `, ${s.reason}` : ''})`);
+  const more = (r.strands.length > shown.length ? ` +${r.strands.length - shown.length} more` : '') + trunc;
+  const worst = r.strands[0];
+  // Lead with what the WORST shape actually means. "work is finished but not landed" is true
+  // of a confirmed strand and false of a completed one (the grade parked that, so the work may
+  // not be finished at all) — one generic sentence for both would be wrong half the time.
+  const lead = {
+    unprovable: 'the reconciler already probed this and gave up, so it will never self-heal',
+    unlanded: 'the grade passed and only the land is outstanding',
+    ungraded: 'the grade parked this; it is not waiting on a land',
+  }[worst.shape] || 'parked mid-pipeline';
+  return `Stranded ship${r.strands.length === 1 ? '' : 's'}: ${shown.join('; ')}${more}. `
+    + `Worst: ${lead} — ${worst.remedy}. `
+    + 'A strand produces no signal of its own; this line is the only one.';
+}
+
+function report(r) {
+  if (!r) { console.error('strand-watch: no result'); return; }
+  if (r.undetermined) { console.error(`strand-watch: undetermined — ${r.reason}`); return; }
+  console.log('');
+  console.log('  Stranded ships');
+  console.log('  ──────────────────────────────────────────────────────────');
+  if (Array.isArray(r.truncated) && r.truncated.length) {
+    console.log(`  ! coverage capped: the ${r.truncated.join(' and ')} queue(s) returned a full ${PAGE_LIMIT}-row page,`);
+    console.log('    so strands older than the cutoff are NOT listed below.');
+  }
+  if (r.ok) {
+    console.log('  ✓ none — nothing parked at completed or confirmed past its threshold.');
+    console.log('');
+    return;
+  }
+  for (const s of r.strands) {
+    console.log(`  task ${s.id}  ${s.status.padEnd(9)} ${String(s.age).padStart(4)}  ${s.shape}${s.reason ? ` (${s.reason})` : ''}`);
+    console.log(`      ${s.remedy}`);
+  }
+  console.log('');
+  console.log('  "completed" means the grade parked it. "confirmed" means it passed and the');
+  console.log('  land never finished. Neither state produces a signal on its own.');
+  console.log('');
+}
+
+async function main() {
+  const hours = Number(arg('--hours'));
+  const opts = Number.isFinite(hours) && hours > 0 ? { completedStaleMs: hours * 3600000 } : {};
+
+  // --line: the SessionStart shape. FAIL-OPEN — a strand is context for the agent, and an
+  // unreachable API is nothing at all; neither is a failure of the session this rides into.
+  // Note it sets exitCode and RETURNS rather than calling process.exit: an explicit exit here
+  // races libuv's teardown of the request socket and aborts the process on Windows/Node 24
+  // (the documented `UV_HANDLE_CLOSING` assertion — see cli-lib's cliExit note and
+  // deploy-divergence's identical comment).
+  if (hasFlag('--line')) {
+    try {
+      const one = line(await check(opts));
+      if (one) console.log(one);
+    } catch { /* no session, offline, unreadable — all silence */ }
+    process.exitCode = 0;
+    return;
+  }
+
+  const r = await check(opts);
+  if (hasFlag('--json')) console.log(JSON.stringify(r, null, 2));
+  else report(r);
+  process.exitCode = r.undetermined ? 2 : (r.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch((e) => { console.error('strand-watch: failed —', e.message || e); process.exit(2); });
+}
+
+module.exports = {
+  check, line, report, classifyStrand, rankStrands, humanAge,
+  CONFIRMED_STALE_MS, COMPLETED_STALE_MS, STRAND_REASON_PREFIX, WATCHED, PAGE_LIMIT,
+};

package/src/bongos/route-rank-check.js

@@ -416,6 +416,15 @@ const MODULE_EXPECTED_RANKS = {
     // requireBuilder + an in-handler author|triage gate. Deliberately a separate
     // route from the triage-gated PATCH /inbox/:id, which keeps its own rank.
     'PATCH /inbox/:id/body': 'any-builder',
+    // task 1002920 (BV1.R144): the Big Idea Spark mark is AUTHOR-ONLY, which is a
+    // narrower rule than any rank expresses — the gate is "whose thought is this",
+    // enforced in-handler against captured_by. Pinned 'any-builder' for the same
+    // reason POST /goals/:id/members is: the pin's job here is to catch an
+    // accidental TIGHTENING to a rank floor (which would lock authors out of their
+    // own ideas and break the consent the mark exists to record) as loudly as it
+    // catches a gate being dropped.
+    'POST /inbox/:id/spark': 'any-builder',
+    'DELETE /inbox/:id/spark': 'any-builder',
     'POST /inbox/:id/ratify': 'perm:idea.ratify',
   },
   // Cross-builder memory READS — the counterpart to the BFG cross-builder WRITE the

package/src/module-api.js

@@ -1013,8 +1013,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.291 with no explicit bump. run 32582800234. (task 1002620)
 //   1.19.293 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.292 with no explicit bump. run 32586174253. (task 1002620)
+//   1.19.294 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.293 with no explicit bump. run 32588977219. (task 1002620)
+//   1.19.295 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.294 with no explicit bump. run 32590508145. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.293'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.295'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/idea_spark_mark.mjs

@@ -0,0 +1,231 @@
+// tests/idea_spark_mark.mjs
+//
+// task 1002920 (BV1.R144, goal 1000062) — mark a Quick Idea as a Big Idea Spark.
+//
+// The done-when, as assertions: ONLY the original author can mark their idea
+// (the mark is the consent that makes cross-builder development fair, so a
+// non-author is a 403 and writes NOTHING); the mark is REVERSIBLE (DELETE puts
+// the idea back to quick); and a spark is visibly DISTINCT from both a quick and
+// a full idea (the grade comes back on the row, and a Full Idea is refused
+// rather than being flattened into a spark).
+//
+// DB-free the idea_full_capture.mjs way (pool.query patched on the doorway
+// before the modules load), driving the REAL route handlers through a stub
+// req/res — the same author gate, the same error map a client sees.
+//
+// Run:  node tests/idea_spark_mark.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 one idea every test reads, reshaped per-test. `captured_by: '9'` is the
+// stub builder below, so the default row IS author-owned.
+let idea = null;
+let queries = [];
+
+api.pool.query = async (sql, params = []) => {
+  queries.push({ sql, params });
+  if (/INSERT INTO ideas_grades/i.test(sql)) {
+    return { rows: [{ idea_id: params[0], grade: params[1], template_key: params[2], field_values: JSON.parse(params[3]), completeness_score: params[4] }] };
+  }
+  // Any read of idea_inbox is getIdea — return the row under test (or nothing).
+  if (/FROM idea_inbox/i.test(sql)) {
+    return { rows: idea ? [idea] : [] };
+  }
+  return { rows: [] };
+};
+
+const routesFactory = require('../modules/ideas/routes/inbox.js');
+const router = routesFactory({});
+
+// Pull the real handlers off the mounted router — the last handler in each
+// stack, i.e. after requireBuilder.
+function handlerFor(pathStr, method) {
+  const layer = router.stack.find((l) => l.route && l.route.path === pathStr && l.route.methods[method]);
+  assert.ok(layer, `route ${method.toUpperCase()} ${pathStr} is not mounted`);
+  const stack = layer.route.stack.map((s) => s.handle);
+  return stack[stack.length - 1];
+}
+const postSpark = handlerFor('/inbox/:id/spark', 'post');
+const deleteSpark = handlerFor('/inbox/:id/spark', 'delete');
+
+function call(handler, { builderId = '9' } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = { params: { id: '77' }, body: {}, query: {}, builder: { id: builderId, rank: 'xenos' } };
+    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 || {}) } });
+      },
+    };
+    // asyncHandler owns the catch in production; surface a throw as a failure here.
+    Promise.resolve(handler(req, res, (err) => reject(err || new Error('next() called')))).catch(reject);
+  });
+}
+
+const gradeWrites = () => queries.filter((q) => /INSERT INTO ideas_grades/i.test(q.sql));
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  queries = [];
+  idea = { id: '77', title: 'a thought', status: 'open', captured_by: '9', grade: 'quick', template_key: null, field_values: null, completeness_score: null };
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// --- the author gate: the whole point of the mark ------------------------
+
+await test('the AUTHOR can mark their quick idea as a spark', async () => {
+  const r = await call(postSpark);
+  assert.equal(r.status, 200);
+  assert.equal(r.payload.sparked, true);
+  assert.equal(r.payload.unchanged, false);
+  assert.equal(r.payload.idea.grade, 'spark', 'the row comes back carrying its new grade');
+  const w = gradeWrites();
+  assert.equal(w.length, 1);
+  assert.equal(w[0].params[1], 'spark');
+});
+
+await test('a NON-author is a 403 and nothing is written — the consent is not theirs to give', async () => {
+  const r = await call(postSpark, { builderId: '12' });
+  assert.equal(r.status, 403);
+  assert.equal(r.payload.error, 'not_your_idea');
+  assert.equal(gradeWrites().length, 0);
+});
+
+await test('an idea with NO author cannot be sparked by anyone (no consent to read)', async () => {
+  idea.captured_by = null;
+  const r = await call(postSpark);
+  assert.equal(r.status, 403);
+  assert.equal(r.payload.error, 'not_your_idea');
+  assert.equal(gradeWrites().length, 0);
+});
+
+await test('a non-author cannot WITHDRAW the mark either', async () => {
+  idea.grade = 'spark';
+  const r = await call(deleteSpark, { builderId: '12' });
+  assert.equal(r.status, 403);
+  assert.equal(gradeWrites().length, 0);
+});
+
+// --- reversible ----------------------------------------------------------
+
+await test('the mark is REVERSIBLE: DELETE puts the idea back to quick', async () => {
+  idea.grade = 'spark';
+  const r = await call(deleteSpark);
+  assert.equal(r.status, 200);
+  assert.equal(r.payload.sparked, false);
+  assert.equal(r.payload.unchanged, false);
+  assert.equal(r.payload.idea.grade, 'quick');
+  const w = gradeWrites();
+  assert.equal(w.length, 1);
+  assert.equal(w[0].params[1], 'quick', 'un-sparking writes an EXPLICIT quick row (R140: it reads as quick either way)');
+});
+
+await test('both directions are idempotent and report `unchanged` rather than erroring', async () => {
+  idea.grade = 'spark';
+  const again = await call(postSpark);
+  assert.equal(again.status, 200);
+  assert.equal(again.payload.unchanged, true);
+  assert.equal(gradeWrites().length, 0, 'no write for a no-op');
+
+  queries = [];
+  idea.grade = 'quick';
+  const off = await call(deleteSpark);
+  assert.equal(off.status, 200);
+  assert.equal(off.payload.sparked, false);
+  assert.equal(off.payload.unchanged, true);
+  assert.equal(gradeWrites().length, 0);
+});
+
+// --- distinct from a FULL idea ------------------------------------------
+
+await test('a FULL idea is refused 409 — and its field_values are never touched', async () => {
+  const fields = { purpose: 'x'.repeat(60), big_picture: 'y'.repeat(60) };
+  idea.grade = 'full';
+  idea.field_values = fields;
+  idea.completeness_score = 80;
+  const r = await call(postSpark);
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'not_a_quick_idea');
+  assert.equal(r.payload.grade, 'full');
+  assert.equal(gradeWrites().length, 0, 'a spark write would have WIPED the five fields');
+  assert.deepEqual(idea.field_values, fields);
+});
+
+await test('un-sparking a FULL idea is refused too — it is not a withdrawn spark', async () => {
+  idea.grade = 'full';
+  const r = await call(deleteSpark);
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'not_a_quick_idea');
+  assert.equal(gradeWrites().length, 0);
+});
+
+// --- only an OPEN idea awaits development -------------------------------
+
+await test('a promoted idea cannot be newly marked — the spark queue must stay pickable', async () => {
+  idea.status = 'promoted';
+  const r = await call(postSpark);
+  assert.equal(r.status, 409);
+  assert.equal(r.payload.error, 'idea_not_open');
+  assert.equal(r.payload.status, 'promoted');
+  assert.equal(gradeWrites().length, 0);
+});
+
+await test('but a stale mark can always be WITHDRAWN, whatever the status', async () => {
+  idea.status = 'discarded';
+  idea.grade = 'spark';
+  const r = await call(deleteSpark);
+  assert.equal(r.status, 200);
+  assert.equal(r.payload.idea.grade, 'quick');
+  assert.equal(gradeWrites().length, 1, 'housekeeping a dead idea\'s mark is never blocked');
+});
+
+// --- plumbing -----------------------------------------------------------
+
+await test('a missing idea is a 404, not a 500', async () => {
+  idea = null;
+  const r = await call(postSpark);
+  assert.equal(r.status, 404);
+  assert.equal(r.payload.error, 'idea_not_found');
+  assert.equal(gradeWrites().length, 0);
+});
+
+// --- the CLI's message layer, against the REAL envelope -----------------
+//
+// The stub res.fail above spreads its extras onto the payload for terseness (the
+// idea_full_capture.mjs idiom). Production does NOT: ADR 0116's envelope nests
+// them under error.details. So the CLI's explain() is checked against the real
+// builder, not the stub — that mismatch is a silent "grade=undefined" in an
+// ideator's terminal, which no route-level assertion above would catch.
+const { explain } = require('../scripts/gds/spark.js');
+const { envelope } = require('../src/bongos/api-errors.js');
+
+await test('the CLI reads each refusal off the REAL envelope shape', async () => {
+  const full = explain(409, envelope('not_a_quick_idea', undefined, { grade: 'full' }));
+  assert.match(full, /already a Full Idea \(grade=full\)/);
+  assert.doesNotMatch(full, /undefined/);
+
+  const closed = explain(409, envelope('idea_not_open', undefined, { status: 'promoted' }));
+  assert.match(closed, /is promoted, so it is not awaiting development/);
+  assert.doesNotMatch(closed, /undefined/);
+
+  assert.match(explain(403, envelope('not_your_idea')), /not yours to mark/);
+  assert.match(explain(404, envelope('idea_not_found')), /No idea with that id/);
+});
+
+await test('an UNMAPPED server refusal is shown raw, never swallowed', async () => {
+  const out = explain(409, envelope('some_future_rule', undefined, { hint: 'x' }));
+  assert.match(out, /spark failed \(409\)/);
+  assert.match(out, /some_future_rule/, 'a new server-side rule must stay visible');
+});
+
+console.log(`\nidea_spark_mark: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);