@bongos/core 1.19.915 → 1.19.916

package/modules/ideas/inbox.js

@@ -22,6 +22,24 @@ const { pool } = api;
 const { decideLanding, authorizeRoutedLanding, routedPriority } = require('./routing');
 // The home a goal-less bug lands in (task 1003691, ADR 0262).
 const { resolveHomelessHome } = require('./homeless-home');
+// The two per-instance ideator dials (task 1004084, BV2.R05). Only the ignite
+// floor is read here; see the decideLanding call below for why that is narrow.
+const ideasConfig = require('./config');
+// The shape every idea read returns, and the grade vocabulary that rides on it
+// (task 1004115). The bottom of the module: it requires nothing, which is what
+// keeps the carve acyclic.
+const {
+  IDEA_COLS, IDEA_COLS_Q, GRADE_COLS_Q, IDEA_JOIN_GRADE, ungradedProjection,
+  DEFAULT_GRADE, VALID_GRADES, DEFAULT_TEMPLATE_KEY, TEMPLATE_KEY_MAX, FIELD_VALUES_MAX,
+} = require('./projection');
+// The carved domains. Each is re-exported at the bottom of this file, so every
+// existing caller of `require('./inbox')` keeps working unchanged — the same
+// facade rule docs/design/demonolith-plan.md sets for every split, and the same
+// one ./skill-friction.js already follows below.
+const { listOpenIdeas, getIdea, countOpenIdeas } = require('./reads');
+const trail = require('./trail');
+const grades = require('./grades');
+const ratify = require('./ratify');
 
 const VALID_KINDS = [
   'feature',
@@ -51,81 +69,9 @@ const VALID_KINDS = [
 ];
 const VALID_STATUSES = ['open', 'promoted', 'discarded', 'merged'];
 
-// The one column list every idea read returns. Four copies had to stay in step
-// (capture / list / get / update-RETURNING); core_195 added two columns to each,
-// so it is now a constant rather than four places to forget. Kept as names rather
-// than a string so the qualified form (task 1002916 joined the grade table in, and
-// an unqualified `id` is ambiguous across a join) is derived, not a fifth copy.
-const IDEA_COL_NAMES = [
-  'id', 'title', 'body_md', 'kind', 'suggested_version', 'suggested_priority',
-  'captured_at', 'captured_by', 'status', 'promoted_to_task_id', 'reviewed_at',
-  'merged_into_idea_id', 'triage_note',
-  // core_222 (task 1003060, BV1.R02): the routing HINT — "this probably belongs
-  // to goal N" — on a row that did NOT convert. Added to the shared list because
-  // R02 shipped the column and nothing read it: /idea-triage (R13) cannot walk
-  // homeless-only work if the read that feeds it never returns the hint. Strictly
-  // advisory: no rank check, no scope wall, and no payout may read it (see the
-  // migration's own header). The BINDING home for "which goal" is tasks.goal_id.
-  'suggested_goal_id',
-];
-const IDEA_COLS = IDEA_COL_NAMES.join(', ');
-const IDEA_COLS_Q = IDEA_COL_NAMES.map((c) => `i.${c}`).join(', ');
-
 // A discard reason / merge note is a sentence, not a document.
 const TRIAGE_NOTE_MAX = 1000;
 
-// -------------------------------------------------------------------------
-// Idea grades (task 1002916 / BV1.R140, goal 1000062)
-//
-// Three grades, from the owner's brief:
-//   quick — title + description, open to every role, aimed at turning a thought
-//           into a task fast. NOT a draft Full Idea.
-//   spark — a Quick Idea whose AUTHOR marked it as needing development. The mark
-//           is the consent that makes cross-builder development fair (R144).
-//   full  — carries the base template's five fields, scored on completeness.
-//
-// AN IDEA WITH NO ideas_grades ROW READS AS QUICK. That is the design, not a
-// fallback: every idea captured before this shipped keeps grade='quick' without
-// a row being written or a column being backfilled. The COALESCE below is where
-// that rule lives, and it is the reason the reads LEFT JOIN rather than JOIN.
-// An explicit quick row is equally legal (un-sparking writes one) and reads the
-// same, so callers never have to care which of the two they are looking at.
-const DEFAULT_GRADE = 'quick';
-const VALID_GRADES = ['quick', 'spark', 'full'];
-
-// Which template `field_values` was written against. Stored per row so a project
-// that later defines its own shape (R156) does not retro-reinterpret ideas
-// written against the base one. R141 declares what 'base-v1' actually contains —
-// this module only records which template a row used.
-const DEFAULT_TEMPLATE_KEY = 'base-v1';
-const TEMPLATE_KEY_RE = /^[a-z][a-z0-9-]*$/;
-const TEMPLATE_KEY_MAX = 64;
-
-// Mirrors ideas_grades_field_values_size_chk. Declared here too so an oversize
-// payload gets a structured 400 instead of a constraint-violation 500.
-const FIELD_VALUES_MAX = 32768;
-
-// The grade half of an idea read: the COALESCE above, plus the template-shaped
-// store and the score. `g.*` columns are NULL for an ungraded idea, which is
-// exactly right — it has no template and no score, it just has a default grade.
-// developed_by/developed_at (ideas_005, task 1002922 / BV1.R146) ride along on
-// EVERY idea read rather than needing a second query: "who developed this" is
-// part of an idea's identity once it has been developed, and the R145 queue, the
-// hall detail view (R153) and the R147 credit split all want it. NULL for the
-// overwhelming majority of rows — a quick idea and a self-authored Full Idea were
-// never developed by anyone — which is the honest answer, not a missing one.
-const GRADE_COLS_Q = `COALESCE(g.grade, '${DEFAULT_GRADE}') AS grade,
-            g.template_key, g.field_values, g.completeness_score,
-            g.developed_by, g.developed_at`;
-const IDEA_JOIN_GRADE = `LEFT JOIN ideas_grades g ON g.idea_id = i.id`;
-
-// The same projection for a row that provably has no grade row yet (a just-
-// INSERTed idea), so INSERT…RETURNING does not need a second round trip to
-// return the same shape every other read returns.
-function ungradedProjection() {
-  return { grade: DEFAULT_GRADE, template_key: null, field_values: null, completeness_score: null, developed_by: null, developed_at: null };
-}
-
 // -------------------------------------------------------------------------
 // Skill-friction: the marker a row carries and the rank gate that hides it.
 // Pure, and its own file (./skill-friction.js) for the reason written there —
@@ -242,8 +188,39 @@ async function captureIdea({
   }
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
 
-  // The decision, before any write. Pure — see ./routing.js. `trustedRanks` is the per-instance ignite floor (BV2.R05; ./config.js says why it is narrow); required inline because this file sits ON the 1500-line ratchet ceiling and require() is cached.
-  const landing = decideLanding({ goalId, kind: resolvedKind, grade, filerRank, vector, trustedRanks: require('./config').TRUSTED_FILER_RANKS });
+  // The decision, before any write. Pure — see ./routing.js.
+  //
+  // `trustedRanks` is the PER-INSTANCE IGNITE FLOOR (task 1004084, BV2.R05):
+  // who may turn a reported bug straight into claimable work rather than into
+  // a row awaiting a nod. A project of one wants every thought claimable; a
+  // project of fifty wants the nod. So it is a dial, resolved in ./config.js.
+  //
+  // IT IS DELIBERATELY NARROW, AND THAT IS THE WHOLE POINT OF THE DIAL
+  // (ADR 0316 — "the ignite floor is not the trusted tier"). routing.js spells
+  // METIC_PLUS once but READS it for four different gates: the two decideLanding
+  // bug branches (this one), `mayProposeCriterion`, and the protected-scope wall.
+  // Only the first two are the floor. Had the constant itself been made
+  // configurable — which is what BV2.R05 was written as — an instance opening its
+  // floor to `xenos` would ALSO have gained the right to file criterion-proposals
+  // and to route work into the permission / ship / deploy core. So the floor is
+  // passed IN as a ready-made Set and routing.js stays pure and never reads
+  // config, while METIC_PLUS stays a fixed constant for the other two gates.
+  // tests/filing_abuse_matrix.mjs pins that literal precisely so a later change
+  // cannot quietly widen them; a failure there is almost certainly this mistake
+  // being made again.
+  //
+  // The default is a true no-op: floor `metic` resolves to exactly the METIC_PLUS
+  // set, so an instance that never touches a dial behaves rank-for-rank as before.
+  //
+  // This was an inline `require('./config')` INSIDE the call expression until task
+  // 1004115, with the whole argument above compressed onto one line — not because
+  // either was better, but because inbox.js sat at exactly the 1,500-line ratchet
+  // ceiling and a top-level require would have cost the line that redded CI. The
+  // carve bought the headroom; this is it being spent.
+  const landing = decideLanding({
+    goalId, kind: resolvedKind, grade, filerRank, vector,
+    trustedRanks: ideasConfig.TRUSTED_FILER_RANKS,
+  });
   if (landing.route) {
     return routeIdeaToGoal({
       title, bodyMd, resolvedKind, suggestedVersion, suggestedPriority,
@@ -479,168 +456,6 @@ async function routeIdeaToGoal({
   }
 }
 
-// -------------------------------------------------------------------------
-// Read
-// -------------------------------------------------------------------------
-
-// viewerRank gates skill-friction visibility (V3.R70 / #289): Xenos must not
-// see skill-friction rows; Metic+ (or unknown rank, pre-R04) see everything.
-// We filter in SQL when the viewer is positively Xenos so the LIMIT still
-// returns up to `limit` *visible* rows rather than `limit` rows that then get
-// thinned out in JS. The marker is a kind OR a legacy title prefix — see
-// skillFrictionHiddenClause, which is the only place that knows that.
-async function listOpenIdeas({ kind = null, limit = 50, viewerRank = null } = {}) {
-  const params = [];
-  const where = [`i.status = 'open'`];
-  if (kind) {
-    params.push(kind);
-    where.push(`i.kind = $${params.length}`);
-  }
-  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
-  if (hideFriction) where.push(hideFriction);
-  params.push(limit);
-  const { rows } = await pool.query(
-    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q}
-       FROM idea_inbox i
-       ${IDEA_JOIN_GRADE}
-      WHERE ${where.join(' AND ')}
-      ORDER BY i.captured_at DESC
-      LIMIT $${params.length}`,
-    params
-  );
-  return rows;
-}
-
-// The by-id read. It carries the two people's LOGINS as well as their ids
-// (task 1002929 / R153): an idea's attribution is a claim about humans, and
-// "captured_by: 41" is not attribution to anyone reading it. Named to match the
-// R145 spark queue's `filed_by_login` so the two idea surfaces agree.
-//
-// Both joins are LEFT: a builder row can be missing (an FK that went
-// ON DELETE SET NULL), and an idea nobody developed has no developer at all —
-// which is the common case, not an error. A plain JOIN here would drop most of
-// the inbox, the same trap the grade join documents above.
-async function getIdea(id) {
-  const { rows } = await pool.query(
-    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
-            ba.github_login AS filed_by_login,
-            bd.github_login AS developed_by_login
-       FROM idea_inbox i
-       ${IDEA_JOIN_GRADE}
-       LEFT JOIN builders ba ON ba.id = i.captured_by
-       LEFT JOIN builders bd ON bd.id = g.developed_by
-      WHERE i.id = $1`,
-    [id]
-  );
-  return rows[0] ?? null;
-}
-
-// viewerRank applies the SAME skill-friction visibility gate as listOpenIdeas
-// (V3.R70 / #289) so the count a viewer is shown matches the rows they can see:
-// a Xenos must not be told there are N open ideas when [skill-friction] rows
-// are filtered out of their list. Default null preserves the old "count
-// everything" behaviour for callers that don't have (or don't gate on) a rank.
-async function countOpenIdeas({ viewerRank = null } = {}) {
-  const params = [];
-  const where = [`status = 'open'`];
-  const hideFriction = skillFrictionHiddenClause(viewerRank, params);
-  if (hideFriction) where.push(hideFriction);
-  const { rows } = await pool.query(
-    `SELECT count(*)::int AS n FROM idea_inbox WHERE ${where.join(' AND ')}`,
-    params
-  );
-  return rows[0].n;
-}
-
-// -------------------------------------------------------------------------
-// The idea TRAIL — every idea one builder filed, and what became of it
-// (task 1003281, goal 1000072, criterion legibility-activity-by-role).
-//
-// THE READ THAT EXISTS NOWHERE ELSE, and the reason the criterion was written:
-// the owner could file an idea and then never find out what happened to it.
-// Every other idea read is scoped to what is STILL OPEN — listOpenIdeas, the
-// spark queue, the nod queue — so a promoted, discarded or merged idea drops
-// out of every surface the moment it is triaged, which is exactly when its
-// outcome becomes interesting. This read is scoped to a PERSON instead of to a
-// status, so nothing they filed ever leaves it.
-//
-// NO NEW STORAGE. The four outcomes are already on the row: `status` says which
-// one, `promoted_to_task_id` + ideas_task_lineage say which task a promotion
-// produced, `merged_into_idea_id` says which idea absorbed a merge, and
-// `triage_note` carries the triager's sentence (core_195, task 1002447). The
-// joins below turn those ids into names so a reader gets "became task #1003281
-// — See what you did, by role" rather than a number they must go look up.
-//
-// AN OPEN IDEA IS AN OUTCOME. It reads as "still open", never as an absence —
-// one of the four the criterion names. That is why status is returned verbatim
-// and the surface renders it, rather than the read filtering open rows out.
-//
-// LINEAGE, NOT JUST THE LEGACY COLUMN. One idea can become MANY tasks
-// (ideas_task_lineage, task 1002997), while `promoted_to_task_id` holds only the
-// first. Both are returned: the lineage array is the complete answer, the legacy
-// column is the only answer for promotions that predate the lineage table. The
-// LATERAL is bounded by the page window, so this stays one query, not an N+1.
-const IDEA_TRAIL_DEFAULT_LIMIT = 20;
-const IDEA_TRAIL_MAX_LIMIT = 100;
-
-// The WHERE this list and its count share, so the pager can never claim rows the
-// list will not show. viewerRank applies the SAME skill-friction gate as every
-// other idea read (V3.R70 / #289) — including on a builder reading their OWN
-// trail: the gate is about what a rank may see, not about authorship.
-function ideaTrailWhere(builderId, viewerRank, params) {
-  params.push(builderId);
-  const where = [`i.captured_by = $${params.length}`];
-  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
-  if (hideFriction) where.push(hideFriction);
-  return where.join(' AND ');
-}
-
-async function listIdeaTrailForBuilder(builderId, { limit = IDEA_TRAIL_DEFAULT_LIMIT, offset = 0, viewerRank = null } = {}, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
-  const lim = Math.min(Math.max(Number.isInteger(Number(limit)) ? Number(limit) : IDEA_TRAIL_DEFAULT_LIMIT, 1), IDEA_TRAIL_MAX_LIMIT);
-  const off = Number.isInteger(Number(offset)) && Number(offset) > 0 ? Number(offset) : 0;
-  const params = [];
-  const where = ideaTrailWhere(builderId, viewerRank, params);
-  params.push(lim, off);
-  const { rows } = await activePool.query(
-    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
-            pt.title  AS promoted_task_title,
-            pt.status AS promoted_task_status,
-            mi.title  AS merged_into_idea_title,
-            mi.status AS merged_into_idea_status,
-            COALESCE(lin.tasks, '[]'::json) AS lineage_tasks
-       FROM idea_inbox i
-       ${IDEA_JOIN_GRADE}
-       LEFT JOIN tasks pt ON pt.id = i.promoted_to_task_id
-       LEFT JOIN idea_inbox mi ON mi.id = i.merged_into_idea_id
-       LEFT JOIN LATERAL (
-         SELECT json_agg(json_build_object(
-                  'task_id', l.task_id, 'origin', l.origin,
-                  'title', lt.title, 'status', lt.status
-                ) ORDER BY l.task_id) AS tasks
-           FROM ideas_task_lineage l
-           JOIN tasks lt ON lt.id = l.task_id
-          WHERE l.idea_id = i.id
-       ) lin ON true
-      WHERE ${where}
-      ORDER BY i.captured_at DESC, i.id DESC
-      LIMIT $${params.length - 1} OFFSET $${params.length}`,
-    params
-  );
-  return rows;
-}
-
-async function countIdeaTrailForBuilder(builderId, { viewerRank = null } = {}, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
-  const params = [];
-  const where = ideaTrailWhere(builderId, viewerRank, params);
-  const { rows } = await activePool.query(
-    `SELECT count(*)::int AS n FROM idea_inbox i WHERE ${where}`,
-    params
-  );
-  return rows[0].n;
-}
-
 // -------------------------------------------------------------------------
 // Update / merge
 // -------------------------------------------------------------------------
@@ -963,477 +778,6 @@ async function countRoutedAwaitingNod(deps = {}) {
   return rows[0] ? rows[0].n : 0;
 }
 
-// -------------------------------------------------------------------------
-// The spark queue (task 1002921 / BV1.R145, goal 1000062)
-//
-// "What Big Idea Sparks are awaiting development?" — the ideator craft's pickup
-// surface, and the first place in this codebase where one craft sources work
-// from another craft's output.
-//
-// THE PREDICATE IS grade='spark' AND status='open', AND THAT IS THE WHOLE
-// QUEUE. There is deliberately no `developed` flag and no separate queue table:
-// R146 develops a spark into a Full Idea IN PLACE on the same idea_inbox row
-// (same id, same captured_by), which flips its grade spark→full — so a developed
-// spark leaves this queue as a CONSEQUENCE of being developed, not because
-// anything remembered to remove it. A second source of truth for "still
-// waiting" is a thing that can disagree with the grade; this cannot.
-//
-// AN INNER JOIN, WHICH INVERTS THIS MODULE'S USUAL RULE ON PURPOSE. Every other
-// idea read LEFT JOINs ideas_grades and COALESCEs to 'quick', because an
-// un-graded idea must still appear. Here the opposite is correct and safe:
-// grade='spark' can never be implicit — absence of a row means quick — so a
-// spark ALWAYS has a real row, and starting from ideas_grades lets
-// ideas_grades_grade_score_idx (ideas_001, written for this very read) drive the
-// scan instead of filtering a full idea_inbox pass afterwards.
-//
-// ORDERING — "newest-or-best first", and only the newest half is real. A spark
-// carries no completeness score by construction (it has no template fields to
-// score), so there is no "best" signal to sort by: upvotes live on builders as
-// karma, not per-idea, and inventing a quality metric for an undeveloped thought
-// is exactly the guess this queue should not be making. captured_at DESC, id
-// DESC as a stable tiebreak for same-timestamp rows. When a real per-idea
-// signal exists, this ORDER BY is the one line that changes.
-//
-// The skill-friction visibility gate (V3.R70) is applied here too, on the same
-// title-prefix rule listOpenIdeas uses. A routine-filed friction row is unlikely
-// to ever be sparked (marking requires an author), but the two idea listings
-// agreeing by construction beats them agreeing by accident.
-function sparkQueueWhere(viewerRank, params) {
-  const where = [`g.grade = 'spark'`, `i.status = 'open'`];
-  const hideFriction = skillFrictionHiddenClause(viewerRank, params, 'i');
-  if (hideFriction) where.push(hideFriction);
-  return where;
-}
-
-async function listSparkQueue({ limit = 50, viewerRank = null } = {}, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
-  const params = [];
-  const where = sparkQueueWhere(viewerRank, params);
-  params.push(limit);
-  const { rows } = await activePool.query(
-    // `b.github_login` because attribution is the POINT of this surface: an
-    // ideator picking work up should see whose thought they are developing, and
-    // R146 has to preserve that name. LEFT JOIN — a builder row can be missing.
-    `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
-            b.github_login AS filed_by_login
-       FROM ideas_grades g
-       JOIN idea_inbox i ON i.id = g.idea_id
-       LEFT JOIN builders b ON b.id = i.captured_by
-      WHERE ${where.join(' AND ')}
-      ORDER BY i.captured_at DESC, i.id DESC
-      LIMIT $${params.length}`,
-    params
-  );
-  return rows;
-}
-
-// The count behind the queue's pill — the SAME predicate as the list (the
-// countRoutedAwaitingNod / countOpenIdeas precedent), so the number a viewer is
-// shown can never disagree with the rows they can actually see. It deliberately
-// takes viewerRank too: a count that ignored the visibility gate would tell a
-// Xenos there are sparks they cannot find.
-async function countSparkQueue({ viewerRank = null } = {}, deps = {}) {
-  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
-  const params = [];
-  const where = sparkQueueWhere(viewerRank, params);
-  const { rows } = await activePool.query(
-    `SELECT COUNT(*)::int AS n
-       FROM ideas_grades g
-       JOIN idea_inbox i ON i.id = g.idea_id
-      WHERE ${where.join(' AND ')}`,
-    params
-  );
-  return rows[0] ? rows[0].n : 0;
-}
-
-// -------------------------------------------------------------------------
-// Grade writes (task 1002916 / BV1.R140)
-//
-// setIdeaGrade writes the WHOLE grade row — it does not merge with what is
-// already there. That is deliberate: a partial-merge upsert reads innocently at
-// the call site and silently preserves stale field_values from a previous grade,
-// which is the bug that would make "develop this spark into a full idea" (R146)
-// quietly inherit whatever was there before. Callers that only want to move the
-// score have setIdeaCompleteness below; anyone changing the grade states the
-// whole row.
-//
-// Structured throws (not raw constraint violations) so the routes that land on
-// top of this — R143's Full Idea capture, R144's mark-as-spark — return a clean
-// 400/404 rather than a 500 with a Postgres message in it.
-function assertGradePayload({ grade, templateKey, fieldValues, completenessScore }) {
-  if (!VALID_GRADES.includes(grade)) {
-    throw { code: 'BAD_GRADE', grade, valid: VALID_GRADES };
-  }
-  if (typeof templateKey !== 'string' || !TEMPLATE_KEY_RE.test(templateKey) || templateKey.length > TEMPLATE_KEY_MAX) {
-    throw { code: 'BAD_TEMPLATE_KEY', template_key: templateKey };
-  }
-  // A map, never a scalar or an array — the scorer and the read path walk it by
-  // key. `typeof null === 'object'`, hence the explicit null check.
-  if (fieldValues === null || typeof fieldValues !== 'object' || Array.isArray(fieldValues)) {
-    throw { code: 'BAD_FIELD_VALUES' };
-  }
-  if (JSON.stringify(fieldValues).length > FIELD_VALUES_MAX) {
-    throw { code: 'FIELD_VALUES_TOO_LARGE', max: FIELD_VALUES_MAX };
-  }
-  if (completenessScore !== null) {
-    if (!Number.isInteger(completenessScore) || completenessScore < 0 || completenessScore > 100) {
-      throw { code: 'BAD_COMPLETENESS', completeness_score: completenessScore };
-    }
-  }
-}
-
-async function setIdeaGrade(ideaId, {
-  grade,
-  templateKey = DEFAULT_TEMPLATE_KEY,
-  fieldValues = {},
-  completenessScore = null,
-} = {}) {
-  assertGradePayload({ grade, templateKey, fieldValues, completenessScore });
-  try {
-    const { rows } = await pool.query(
-      `INSERT INTO ideas_grades (idea_id, grade, template_key, field_values, completeness_score)
-       VALUES ($1, $2, $3, $4::jsonb, $5)
-       ON CONFLICT (idea_id) DO UPDATE
-          SET grade              = EXCLUDED.grade,
-              template_key       = EXCLUDED.template_key,
-              field_values       = EXCLUDED.field_values,
-              completeness_score = EXCLUDED.completeness_score
-       RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                 created_at, updated_at`,
-      [ideaId, grade, templateKey, JSON.stringify(fieldValues), completenessScore]
-    );
-    return rows[0];
-  } catch (err) {
-    // 23503 = FK violation on idea_id: the idea does not exist. Worth its own
-    // code because "you graded a missing idea" is a 404, not a 500.
-    if (err && err.code === '23503') throw { code: 'IDEA_NOT_FOUND', idea_id: ideaId };
-    throw err;
-  }
-}
-
-// The score-only write, so the R142 scorer never has to restate the grade and
-// the fields just to move a number (and so it cannot wipe them by forgetting).
-// Returns null when the idea has no grade row: an ungraded idea is quick, and a
-// quick idea has nothing to score — that is a no-op, not an error.
-async function setIdeaCompleteness(ideaId, completenessScore) {
-  if (completenessScore !== null && (!Number.isInteger(completenessScore) || completenessScore < 0 || completenessScore > 100)) {
-    throw { code: 'BAD_COMPLETENESS', completeness_score: completenessScore };
-  }
-  const { rows } = await pool.query(
-    `UPDATE ideas_grades
-        SET completeness_score = $2
-      WHERE idea_id = $1
-      RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                created_at, updated_at`,
-    [ideaId, completenessScore]
-  );
-  return rows[0] ?? null;
-}
-
-// -------------------------------------------------------------------------
-// developSpark — turn a Big Idea Spark into a Full Idea IN PLACE
-// (task 1002922 / BV1.R146, goal 1000062)
-//
-// The pickup half of the spark handoff: R144 recorded the author's consent, R145
-// made the spark findable, and this is another builder filling in the five
-// template fields.
-//
-// IN PLACE, ON THE SAME ROW, AND THAT IS A DONE-WHEN. idea_inbox.id,
-// captured_by and captured_at are NOT touched — only the grade row moves. A new
-// row for the developed version would break the hall's /#/idea/N deep link,
-// ideas_task_lineage.idea_id, and the per-idea credit_log reason key. The
-// author's claim on their own thought is precisely what must survive being
-// developed by someone else; it is what the R147 split pays against.
-//
-// ONE GUARDED UPDATE, WHICH IS WHERE "ONLY ONCE" ACTUALLY LIVES. The predicate
-// carries `AND grade = 'spark'`, so the database decides whether this row was
-// still developable. A read-then-write ("is it a spark? ok, develop it") looks
-// identical in a test and loses a race in production: two builders picking the
-// same spark off the R145 queue at the same moment would both pass the check and
-// the second would overwrite the first's work AND their attribution. Here the
-// second UPDATE matches zero rows and the route turns that into a 409. Zero rows
-// is therefore NOT an error condition to log — it is the answer.
-//
-// It is also why this is not expressed as setIdeaGrade + a second write:
-// two statements cannot carry one guard, and a Full Idea with no recorded
-// developer is the exact state the done-when forbids.
-//
-// THE STATUS HALF OF THE GUARD, AND WHY IT IS NOT REDUNDANT WITH THE ROUTE'S
-// PRE-CHECK. Triage (`updateIdea`) writes idea_inbox.status and NEVER touches
-// ideas_grades — so a spark that a Metic+ triager discards, merges or promotes
-// keeps grade='spark' forever. Grade alone therefore does NOT mean "still
-// developable", and a develop that trusted it would resurrect content the triage
-// flow already decided was dead, opening a fresh board ratification window for
-// it. The R145 queue already filters on status and the R144 mark already requires
-// it; this closes the same hole on the write. In the PREDICATE rather than only
-// in the handler because a triager discarding an idea mid-request is the same
-// class of race as two developers colliding — and the fix for a race is never a
-// check that ran earlier.
-//
-// NOTE ON setIdeaGrade's whole-row contract: developed_by/developed_at are
-// deliberately OUTSIDE it. That contract exists so a grade change cannot inherit
-// stale field_values; but a developer is a historical FACT about who did the
-// work, not current content, and setIdeaGrade's ON CONFLICT SET list omits both
-// columns — so a later re-score or an author's R13 resubmission preserves the
-// developer's attribution instead of silently erasing it.
-async function developSpark(ideaId, { developedBy, templateKey = DEFAULT_TEMPLATE_KEY, fieldValues = {}, completenessScore = null } = {}) {
-  // Reuse the R140 payload validator so a bad template key or an oversize
-  // field_values map is a structured throw here rather than a constraint
-  // violation surfacing as a 500 (the assertGradePayload contract).
-  assertGradePayload({ grade: 'full', templateKey, fieldValues, completenessScore });
-  if (developedBy == null) throw { code: 'MISSING_DEVELOPER' };
-  const { rows } = await pool.query(
-    `UPDATE ideas_grades
-        SET grade              = 'full',
-            template_key       = $2,
-            field_values       = $3::jsonb,
-            completeness_score = $4,
-            developed_by       = $5,
-            developed_at       = now()
-      WHERE idea_id = $1
-        AND grade = 'spark'
-        AND EXISTS (
-          SELECT 1 FROM idea_inbox i WHERE i.id = $1 AND i.status = 'open'
-        )
-      RETURNING idea_id, grade, template_key, field_values, completeness_score,
-                developed_by, developed_at, created_at, updated_at`,
-    [ideaId, templateKey, JSON.stringify(fieldValues), completenessScore, developedBy]
-  );
-  // null = "this row was not a developable spark when we looked". THREE ways to
-  // get here, and the caller re-reads to say which: it was never a spark,
-  // somebody else developed it first, or a triager closed the idea underneath us.
-  const graded = rows[0] ?? null;
-
-  // task 1003856: a Full Idea is the ideator's hand-off point, and the
-  // cross-role cascade that turns it into an engineer's scoping request needs a
-  // transition to hang on. Emitted only on a REAL transition — the UPDATE's
-  // `AND grade = 'spark'` means a no-op re-grade returns null and fires nothing,
-  // so the event cannot repeat for one idea.
-  //
-  // Wrapped and awaited-free by the same reasoning as every other kernel emit
-  // here: a listener must never be able to fail the write that preceded it. The
-  // cascade runner catches everything of its own accord as well.
-  if (graded) {
-    // The payload carries the WHOLE idea, not just its id. The listener lives in
-    // the lifecycle module, which owns no idea table and has no read port for one
-    // (ideas provides only `ideas.capture`) — so the read happens here, inside the
-    // module that owns the row, rather than by widening another module's surface.
-    try {
-      const idea = await getIdea(ideaId);
-      api.emit('idea.graded.full', {
-        ...(idea || {}),
-        id: ideaId,
-        idea_id: ideaId,
-        grade: 'full',
-        completeness_score: graded.completeness_score,
-        developed_by: graded.developed_by,
-      });
-    } catch { /* a listener, or the read that feeds it, must never cost the ideator their grade */ }
-  }
-  return graded;
-}
-
-// The grade row on its own. null = no row, which reads as grade='quick'
-// everywhere the idea itself is read (see DEFAULT_GRADE).
-async function getIdeaGrade(ideaId) {
-  const { rows } = await pool.query(
-    `SELECT idea_id, grade, template_key, field_values, completeness_score,
-            created_at, updated_at
-       FROM ideas_grades
-      WHERE idea_id = $1`,
-    [ideaId]
-  );
-  return rows[0] ?? null;
-}
-
-// -------------------------------------------------------------------------
-// Criterion-proposal ratification (V3.R31 / #252)
-//
-// Atomically promotes an idea_inbox row with kind='criterion-proposal' into a
-// real done_when_criteria row, marks the idea as promoted, awards karma to
-// the proposer (delta=+3, reason='proposal_ratified'), and writes an audit
-// row capturing who proposed / who ratified / when / what.
-//
-// Called by POST /api/bongos/inbox/:id/ratify (Archon-only, gated by requireRank
-// in the router). The body_md of the source idea is parsed as JSON with the
-// shape { target_version, criterion_md, sort_order_hint }; malformed bodies
-// throw BAD_BODY so the route can return a structured 400.
-//
-// Karma amount is tunable; V3.R28 (#248) sets it to +3 to recognize good civic
-// input without overweighting it relative to peer-upvote signals that arrive
-// in volume. criterion_id on the new done_when_criteria row defaults to
-// "proposal-<idea_id>" so the (version_id, criterion_id) UNIQUE constraint
-// fires if someone ratifies the same idea twice — the second attempt fails the
-// transaction rather than creating a duplicate criterion silently.
-const KARMA_RATIFY_DELTA = 3;
-const KARMA_RATIFY_REASON = 'proposal_ratified';
-
-function parseProposalBody(bodyMd) {
-  if (!bodyMd || typeof bodyMd !== 'string') {
-    throw { code: 'BAD_BODY', reason: 'body_md_empty' };
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(bodyMd);
-  } catch (err) {
-    throw { code: 'BAD_BODY', reason: 'body_md_not_json', detail: err.message };
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw { code: 'BAD_BODY', reason: 'body_md_not_object' };
-  }
-  const { target_version, criterion_md, sort_order_hint } = parsed;
-  if (!target_version || typeof target_version !== 'string') {
-    throw { code: 'BAD_BODY', reason: 'target_version_required' };
-  }
-  if (!criterion_md || typeof criterion_md !== 'string') {
-    throw { code: 'BAD_BODY', reason: 'criterion_md_required' };
-  }
-  let hint = null;
-  if (sort_order_hint != null) {
-    const n = Number(sort_order_hint);
-    if (!Number.isFinite(n) || !Number.isInteger(n)) {
-      throw { code: 'BAD_BODY', reason: 'sort_order_hint_not_integer' };
-    }
-    hint = n;
-  }
-  return { target_version, criterion_md, sort_order_hint: hint };
-}
-
-async function ratifyCriterionProposal(ideaId, ratifierId, { notesMd = '' } = {}) {
-  const id = Number(ideaId);
-  if (!Number.isFinite(id)) {
-    throw { code: 'BAD_ID' };
-  }
-  const rid = Number(ratifierId);
-  if (!Number.isFinite(rid)) {
-    throw { code: 'BAD_RATIFIER' };
-  }
-  const client = await pool.connect();
-  try {
-    await client.query('BEGIN');
-
-    // a. Read + lock the idea row.
-    const { rows: ideaRows } = await client.query(
-      `SELECT id, title, body_md, kind, status, captured_by
-         FROM idea_inbox
-        WHERE id = $1
-        FOR UPDATE`,
-      [id]
-    );
-    if (ideaRows.length === 0) throw { code: 'IDEA_NOT_FOUND' };
-    const idea = ideaRows[0];
-    if (idea.kind !== 'criterion-proposal') {
-      throw { code: 'WRONG_KIND', kind: idea.kind, expected: 'criterion-proposal' };
-    }
-    if (idea.status !== 'open') {
-      throw { code: 'IDEA_NOT_OPEN', status: idea.status };
-    }
-
-    // b. Parse body_md.
-    const proposal = parseProposalBody(idea.body_md);
-
-    // c. Verify target version exists. (FK on done_when_criteria.version_id
-    //    would catch this too, but giving a 400 instead of a 23503 is friendlier.)
-    const { rows: verRows } = await client.query(
-      `SELECT id FROM versions WHERE id = $1`,
-      [proposal.target_version]
-    );
-    if (verRows.length === 0) {
-      throw { code: 'VERSION_NOT_FOUND', version_id: proposal.target_version };
-    }
-
-    // d. Resolve sort_order: prefer the hint; otherwise max(existing)+1, or 100
-    //    if no rows exist yet (matches the migration 006 default).
-    let sortOrder = proposal.sort_order_hint;
-    if (sortOrder == null) {
-      const { rows: maxRows } = await client.query(
-        `SELECT COALESCE(MAX(sort_order), 0) + 1 AS next
-           FROM done_when_criteria
-          WHERE version_id = $1`,
-        [proposal.target_version]
-      );
-      sortOrder = maxRows[0].next;
-    }
-
-    // e. INSERT done_when_criteria with criterion_id = 'proposal-<idea_id>'.
-    //    The UNIQUE (version_id, criterion_id) constraint provides natural
-    //    idempotency — re-ratifying the same idea would 23505 here.
-    const criterionRefId = `proposal-${idea.id}`;
-    const { rows: critRows } = await client.query(
-      `INSERT INTO done_when_criteria
-         (version_id, criterion_id, criterion_md, sort_order)
-       VALUES ($1, $2, $3, $4)
-       RETURNING id, version_id, criterion_id, criterion_md, sort_order`,
-      [proposal.target_version, criterionRefId, proposal.criterion_md, sortOrder]
-    );
-    const criterion = critRows[0];
-
-    // f. Mark the idea promoted. promoted_to_task_id stays NULL — a criterion
-    //    is not a task. reviewed_at is stamped to now() so triage views skip it.
-    await client.query(
-      `UPDATE idea_inbox
-          SET status              = 'promoted',
-              promoted_to_task_id = NULL,
-              reviewed_at         = now()
-        WHERE id = $1`,
-      [idea.id]
-    );
-
-    // g. Award karma to the proposer. captured_by may be NULL on legacy rows;
-    //    skip the karma insert in that case (no proposer to credit) but still
-    //    record the audit row.
-    let karmaAwarded = 0;
-    if (idea.captured_by != null) {
-      await client.query(
-        `INSERT INTO karma_log (builder_id, delta, reason, granted_by)
-         VALUES ($1, $2, $3, $4)`,
-        [idea.captured_by, KARMA_RATIFY_DELTA, KARMA_RATIFY_REASON, rid]
-      );
-      karmaAwarded = KARMA_RATIFY_DELTA;
-
-      // Note: prior to 2026-05-30 this also ticked a 'first_vote_received'
-      // onboarding stage. That stage was removed (migration 059) — graduation
-      // no longer waits on a peer vote — so there is nothing to mark here now.
-    }
-
-    // h. Audit row — durable record of the ratification event.
-    const { rows: auditRows } = await client.query(
-      `INSERT INTO criterion_proposal_audit
-         (idea_id, criterion_id, proposed_by, ratified_by,
-          target_version, criterion_md, sort_order_hint, notes_md)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
-       RETURNING id, ratified_at`,
-      [
-        idea.id,
-        criterion.id,
-        idea.captured_by,
-        rid,
-        proposal.target_version,
-        proposal.criterion_md,
-        proposal.sort_order_hint,
-        notesMd || '',
-      ]
-    );
-
-    await client.query('COMMIT');
-    return {
-      criterion_id: criterion.id,
-      criterion_ref: criterion.criterion_id,
-      version_id: criterion.version_id,
-      sort_order: criterion.sort_order,
-      audit_id: auditRows[0].id,
-      ratified_at: auditRows[0].ratified_at,
-      karma_awarded: karmaAwarded,
-      proposer_id: idea.captured_by,
-    };
-  } catch (err) {
-    await client.query('ROLLBACK').catch(() => {});
-    throw err;
-  } finally {
-    client.release();
-  }
-}
-
 // -------------------------------------------------------------------------
 // Helpers used by CLI defaults
 // -------------------------------------------------------------------------
@@ -1465,14 +809,14 @@ module.exports = {
   listOpenIdeas,
   getIdea,
   countOpenIdeas,
-  getIdeaGrade,
+  getIdeaGrade: grades.getIdeaGrade,
   // mutate
   updateIdea,
   updateIdeaBody,
-  setIdeaGrade,
-  setIdeaCompleteness,
+  setIdeaGrade: grades.setIdeaGrade,
+  setIdeaCompleteness: grades.setIdeaCompleteness,
   // develop a spark into a Full Idea, in place (task 1002922, BV1.R146)
-  developSpark,
+  developSpark: grades.developSpark,
   // idea → task lineage (task 1002997 / BV1.R173) — the one-idea-many-tasks
   // link stream 1 (IC4) pays against
   linkIdeaTask,
@@ -1482,18 +826,18 @@ module.exports = {
   listRoutedAwaitingNod,
   countRoutedAwaitingNod,
   // the spark queue (task 1002921, BV1.R145) — sparks awaiting development
-  listSparkQueue,
-  countSparkQueue,
+  listSparkQueue: grades.listSparkQueue,
+  countSparkQueue: grades.countSparkQueue,
   // the idea TRAIL (task 1003281) — every idea one builder filed, with what
   // became of it. Scoped to a person, not to a status, so a triaged idea never
   // drops out of the one surface that answers "what happened to my idea".
-  listIdeaTrailForBuilder,
-  countIdeaTrailForBuilder,
-  IDEA_TRAIL_DEFAULT_LIMIT,
-  IDEA_TRAIL_MAX_LIMIT,
+  listIdeaTrailForBuilder: trail.listIdeaTrailForBuilder,
+  countIdeaTrailForBuilder: trail.countIdeaTrailForBuilder,
+  IDEA_TRAIL_DEFAULT_LIMIT: trail.IDEA_TRAIL_DEFAULT_LIMIT,
+  IDEA_TRAIL_MAX_LIMIT: trail.IDEA_TRAIL_MAX_LIMIT,
   // criterion-proposal ratification (V3.R31 / #252)
-  ratifyCriterionProposal,
-  parseProposalBody,
-  KARMA_RATIFY_DELTA,
-  KARMA_RATIFY_REASON,
+  ratifyCriterionProposal: ratify.ratifyCriterionProposal,
+  parseProposalBody: ratify.parseProposalBody,
+  KARMA_RATIFY_DELTA: ratify.KARMA_RATIFY_DELTA,
+  KARMA_RATIFY_REASON: ratify.KARMA_RATIFY_REASON,
 };