@bongos/core 1.19.915 → 1.19.917

package/modules/ideas/grades.js

@@ -0,0 +1,317 @@
+// modules/ideas/grades.js — the quick / spark / full grade domain (task 1004115).
+//
+// Carved out of inbox.js verbatim: the spark queue (R145), the grade writes
+// (R140), developSpark (R146) and the grade-row read. One file because they are
+// one relation — ideas_grades — and because the guarantees interlock:
+// setIdeaGrade writes the WHOLE row so a re-grade cannot inherit stale
+// field_values, developSpark deliberately steps OUTSIDE that contract for
+// developed_by/developed_at, and the queue exists only because grade=spark is
+// never implicit. Those three arguments read as one argument here and read as
+// three scattered comments when they are 300 lines apart in a 1,500-line file.
+//
+// The grade VOCABULARY (VALID_GRADES, the template caps, the COALESCE default)
+// stays in projection.js, not here: every idea read returns a grade, so the
+// vocabulary is shared and the writes are not.
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const {
+  IDEA_COLS_Q, GRADE_COLS_Q,
+  VALID_GRADES, DEFAULT_TEMPLATE_KEY, TEMPLATE_KEY_RE, TEMPLATE_KEY_MAX, FIELD_VALUES_MAX,
+} = require('./projection');
+const { skillFrictionHiddenClause } = require('./skill-friction');
+// developSpark reads the whole idea back to build the idea.graded.full payload.
+// From ./reads, never from ./inbox — see the cycle note in reads.js.
+const { getIdea } = require('./reads');
+
+// -------------------------------------------------------------------------
+// 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;
+}
+
+module.exports = {
+  listSparkQueue,
+  countSparkQueue,
+  setIdeaGrade,
+  setIdeaCompleteness,
+  developSpark,
+  getIdeaGrade,
+};