@bongos/core 1.19.925 → 1.19.927

package/modules/hall-ui/public/idea.js

@@ -212,6 +212,193 @@
     return `<p class="ig-meta">${bits.join('')}</p>`;
   }
 
+  // ---- the descent (task 1004094 / BV2.R10) ---------------------------------
+  //
+  // One thought at the top, everything it caused falling away below — including
+  // the branches that went out. This REPLACES the one-line "became task N"
+  // outcome statusLine() used to carry alone: that line was all the page could
+  // say while the read was one hop (profile.js says the same of its own capped
+  // three, and links here for the rest, which is what makes this the full view).
+  //
+  // WHAT A ROW IS MARKED BY, and this is the design decision in the file. The
+  // agreed shape (docs/design/mocks/ideator-surface/Descent.dc.html) tags each
+  // row with one of the FIVE OBJECTS. It is deliberately not built that way.
+  // The five objects are a property of an IDEA, derived once in
+  // modules/ideas/idea-state.js from that idea's status, its brightness and its
+  // tasks (ADR 0322) — and the whole reason that file exists is that a state
+  // decided a second time is a second state. A descendant here is a TASK, and
+  // this page has no idea-level facts about it to derive one from; inventing a
+  // per-task object would be exactly the re-derivation the resolver was written
+  // to prevent, and it would disagree with the sky the first time the two were
+  // read side by side.
+  //
+  // So the origin at the top carries the one real object (idea.state), and each
+  // row below is marked by its own two ledger facts instead:
+  //   RELATION — rewrite / split / merge / fold / cascade, the edge that put it
+  //     there. This is the better mark anyway: the done-when is that a thing
+  //     shipped months later can be traced back THROUGH rewrites, splits and
+  //     merges, and the relation is the word that traces it.
+  //   ALIVE OR OUT — whether the project has CONFIRMED this hop's work removed
+  //     (idea.removed_tasks, read from the lifecycle verdict, never a diff).
+  // The mock is a shape, not a pixel contract, and this keeps its shape.
+
+  // The edge that put a node where it is, as a reader's word rather than the
+  // column's. An unknown relation passes through verbatim rather than being
+  // dropped: a relation this page has not heard of is a real edge someone
+  // wrote, and showing it unstyled beats showing nothing.
+  const RELATION_WORD = {
+    rewrite: 'rewritten',
+    split: 'split off',
+    merge: 'merged in',
+    fold: 'folded in',
+    cascade: 'caused by',
+  };
+
+  // A task status is not a state object — see the block above. It says one
+  // thing here: whether this hop has landed yet.
+  const LANDED = 'shipped';
+
+  // descentRows — the roots and the descent, as ONE ordered list.
+  //
+  // The two halves come from different places on purpose. attachDescentToTrail
+  // deliberately leaves an idea's own root tasks OUT of descent_tasks (the trail
+  // already names them as what the idea became, and repeating them there would
+  // double-count the first hop for the payout). The picture needs them, so they
+  // are re-added here at depth 0, from the same lineage_tasks the server walked
+  // from — never re-derived, just re-joined.
+  function descentRows(idea) {
+    const rows = [];
+    const seen = new Set();
+
+    const lineage = Array.isArray(idea.lineage_tasks) ? idea.lineage_tasks : [];
+    for (const t of lineage) {
+      if (!t || t.task_id == null) continue;
+      const id = String(t.task_id);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      rows.push({ task_id: id, depth: 0, relation: null, title: t.title, status: t.status });
+    }
+    // The legacy column is the ONLY answer for a promotion that predates
+    // ideas_task_lineage, and the guard above is what stops an idea carrying
+    // both from listing its first task twice.
+    if (rows.length === 0 && idea.promoted_to_task_id != null) {
+      const id = String(idea.promoted_to_task_id);
+      seen.add(id);
+      rows.push({ task_id: id, depth: 0, relation: null, title: idea.promoted_task_title, status: idea.promoted_task_status });
+    }
+
+    const descent = Array.isArray(idea.descent_tasks) ? idea.descent_tasks : [];
+    for (const d of descent) {
+      if (!d || d.task_id == null) continue;
+      const id = String(d.task_id);
+      if (seen.has(id)) continue;
+      seen.add(id);
+      // depth + 1: the server counts hops FROM a root, so its depth 1 is the
+      // first thing below a root, which this list draws at depth 0.
+      rows.push({ task_id: id, depth: Number(d.depth) + 1, relation: d.relation, title: d.title, status: d.status, version_id: d.version_id });
+    }
+    return rows;
+  }
+
+  // One row. The glyph is not decoration — it restates in shape what the row
+  // also says in words, which is the sheet's own rule for the grade badge: a
+  // mark distinguished only by colour tells a colour-blind reader nothing.
+  function descentRow(row, removedMap, homeVersion) {
+    const out = removedMap ? removedMap[row.task_id] : null;
+    const landed = row.status === LANDED;
+    const mark = out ? 'out' : (landed ? 'live' : 'pending');
+
+    const bits = [];
+    if (row.relation) bits.push(escapeHtml(RELATION_WORD[row.relation] || row.relation));
+    else if (row.depth === 0) bits.push('became work');
+    if (row.status) bits.push(escapeHtml(row.status));
+    // A version that is not the idea's own is the interesting case, not an
+    // anomaly to hide: the descent crosses version boundaries deliberately
+    // (ADR 0312) and the read carries version_id so a surface can SAY so.
+    if (row.version_id && homeVersion && String(row.version_id) !== String(homeVersion)) {
+      bits.push('in ' + escapeHtml(String(row.version_id)));
+    }
+
+    // WHY it went out, not only that it did. A removal names the ship that did
+    // it, and that ship is a task a reader can open.
+    const gone = out
+      ? '<span class="ig-desc__out">went out' + (out.ship_task_id
+          ? ' — removed by <a href="' + hallBase() + '/task/' + encodeURIComponent(out.ship_task_id) + '">task ' + escapeHtml(String(out.ship_task_id)) + '</a>'
+          : '') + '</span>'
+      : '';
+
+    return '\n      <li class="ig-desc__row" data-mark="' + escapeHtml(mark) + '" style="--d:' + Math.min(row.depth, 8) + '">'
+      + '\n        <span class="ig-desc__glyph" aria-hidden="true"></span>'
+      + '\n        <span class="ig-desc__body">'
+      + '\n          <a class="ig-desc__title" href="' + hallBase() + '/task/' + encodeURIComponent(row.task_id) + '">' + escapeHtml(row.title || ('Task ' + row.task_id)) + '</a>'
+      + '\n          <span class="ig-desc__meta">' + bits.join(' · ') + (gone ? ' · ' + gone : '') + '</span>'
+      + '\n        </span>'
+      + '\n        <span class="ig-desc__id">' + escapeHtml(String(row.task_id)) + '</span>'
+      + '\n      </li>';
+  }
+
+  // The figures over the list. Size is the server's number verbatim (spec
+  // decision 4) — this computes none of it.
+  function descentFigures(idea, rows, removedMap) {
+    const figs = [];
+    const size = idea.size;
+    if (size && typeof size.credits === 'number' && size.credits > 0) {
+      // A historical size was computed from the descent an idea already had
+      // rather than from payouts actually made (spec decision 17), so the label
+      // says so wherever the number is shown. Anything else lets it claim to be
+      // money that was never spent.
+      figs.push({
+        n: size.credits,
+        label: size.historical === true ? 'size — part historical' : 'size — credits',
+        tone: 'warm',
+      });
+    }
+    figs.push({ n: rows.length, label: rows.length === 1 ? 'thing it caused' : 'things it caused', tone: '' });
+    // Only stated when the removal facts were READABLE. `null` means the
+    // lifecycle module could not be asked, and drawing that as a zero would
+    // promise a reader that nothing died (the distinction brightness draws with
+    // share: null).
+    if (removedMap) {
+      const n = Object.keys(removedMap).length;
+      if (n > 0) figs.push({ n: n, label: 'went out', tone: 'dim' });
+    }
+    return '<div class="ig-desc__figs">' + figs.map(function (f) {
+      return '\n      <div class="ig-desc__fig"' + (f.tone ? ' data-tone="' + escapeHtml(f.tone) + '"' : '') + '>'
+        + '\n        <span class="ig-desc__n">' + escapeHtml(String(f.n)) + '</span>'
+        + '\n        <span class="ig-desc__flabel">' + escapeHtml(f.label) + '</span>'
+        + '\n      </div>';
+    }).join('') + '</div>';
+  }
+
+  // The section, or nothing at all.
+  //
+  // NOTHING AT ALL IS THE RIGHT ANSWER FOR A THOUGHT THAT CAUSED NOTHING — not
+  // an empty rail with a heading over it. That is the same judgement the page
+  // already makes about a quick idea's five-field skeleton: a heading over
+  // nothing tells a builder they did something wrong, which is the opposite of
+  // what an unignited thought is for. statusLine() still says "still open", and
+  // that is the whole truth about it.
+  function descentSection(idea) {
+    const rows = descentRows(idea);
+    if (rows.length === 0) return '';
+    // `removed_tasks` is `{}` when nothing went out and `null` when the facts
+    // could not be read. Only the second suppresses the figure and the marks —
+    // "nothing was removed" and "we could not look" are different answers and
+    // only one of them may be drawn as a descent that is wholly alive.
+    const unreadable = idea.removed_tasks === null || idea.removed_tasks === undefined;
+    const removedMap = unreadable ? null
+      : ((idea.removed_tasks && typeof idea.removed_tasks === 'object') ? idea.removed_tasks : null);
+
+    return '\n      <section class="ig-desc" aria-labelledby="ig-desc-h">'
+      + '\n        <h2 class="ig-desc__h" id="ig-desc-h">Everything that fell out of it</h2>'
+      + '\n        ' + descentFigures(idea, rows, removedMap)
+      + '\n        <ol class="ig-desc__list">' + rows.map(function (r) { return descentRow(r, removedMap, idea.suggested_version); }).join('') + '</ol>'
+      + '\n        <p class="ig-desc__foot">The origin tag rides along through every rewrite, split and merge. That is the only reason this reads as a story instead of a link.'
+      + (unreadable ? ' Which of these are still alive could not be read.' : '')
+      + '</p>'
+      + '\n      </section>';
+  }
+
   // ---------------------------------------------------------------------------
   // render
   // ---------------------------------------------------------------------------
@@ -261,6 +448,11 @@
       }
     }
 
+    // The descent goes UNDER the record and ABOVE the one write on the page:
+    // it is the largest thing here and the last thing read, and the mark
+    // control is an action, which belongs at the end of a read.
+    parts.push(descentSection(idea));
+
     parts.push(markControl(idea, viewer));
 
     $('#idea-body').innerHTML = parts.join('');

package/modules/ideas/inbox.js

@@ -833,6 +833,7 @@ module.exports = {
   // drops out of the one surface that answers "what happened to my idea".
   listIdeaTrailForBuilder: trail.listIdeaTrailForBuilder,
   countIdeaTrailForBuilder: trail.countIdeaTrailForBuilder,
+  getIdeaTrailRow: trail.getIdeaTrailRow,
   IDEA_TRAIL_DEFAULT_LIMIT: trail.IDEA_TRAIL_DEFAULT_LIMIT,
   IDEA_TRAIL_MAX_LIMIT: trail.IDEA_TRAIL_MAX_LIMIT,
   // criterion-proposal ratification (V3.R31 / #252)

package/modules/ideas/routes/inbox.js

@@ -44,6 +44,7 @@ const { attachDescentToTrail } = require('../trail-descent');
 // ratchet, and a ledger read keyed by idea is a third relation again.
 const { attachSizeToTrail } = require('../trail-size');
 const { attachStateToTrail } = require('../idea-state');
+const { attachRemovalToDescent } = require('../trail-removal');
 // The walk itself, published as the `ideas.descent` port below.
 const descent = require('../descent');
 // Full Idea capture (task 1002919 / BV1.R143): the template validator (R141)
@@ -693,8 +694,30 @@ module.exports = function buildInboxRouter() {
     const id = parseId(req, res, { code: 'bad_id', positiveInt: true });
     if (id === null) return;
     try {
-      const idea = await inbox.getIdea(id);
+      // THE TRAIL ROW, NOT getIdea() (task 1004094 / BV2.R10). The four
+      // attachers below read this row by field name — `lineage_tasks` for the
+      // descent's roots, `promoted_task_goal_id` and `promoted_task_status`
+      // for the well and the nod — and getIdea()'s projection carries none of
+      // them. Handed that row they would not fail; they would answer "no
+      // descent, protostar, open space" for a thought with a descent, which is
+      // the wrong answer wearing the right shape. trail.js spells the
+      // projection once so this can never drift from the page read.
+      const idea = await inbox.getIdeaTrailRow(id);
       if (!idea) return res.fail('idea_not_found', 404);
+      // The same four the trail page composes, in the same order and for the
+      // same reasons (see GET /inbox/by-builder/:id above): the walk, then what
+      // it paid, then which of the five objects it is — state last because it
+      // takes its share off the `byTask` breakdown size leaves on the row, so
+      // the page pays one ledger read rather than two.
+      //
+      // THE FOURTH IS ONLY HERE. This is the surface that draws the descent
+      // NODE BY NODE, so it is the only one that needs to know WHICH hops went
+      // out rather than what share of the thought survived. The trail page
+      // draws the share and does not pay for this.
+      await attachDescentToTrail([idea]);
+      await attachSizeToTrail([idea]);
+      await attachStateToTrail([idea]);
+      await attachRemovalToDescent([idea]);
       res.json({ idea });
     } catch (err) {
       log.error('[gds] GET /inbox/:id', err);

package/modules/ideas/trail-removal.js

@@ -0,0 +1,115 @@
+// modules/ideas/trail-removal.js — WHICH NODES OF A DESCENT WENT OUT (task
+// 1004094 / BV2.R10, goal 1000095, criterion `ideator-tag-survives-the-fork`;
+// spec docs/specs/bongos-v2-ideator-surface.md, under ADR 0313 + 0321).
+//
+// WHAT THIS ADDS THAT BRIGHTNESS DOES NOT. `reward.ideaBrightness` already reads
+// the removal facts, but it reduces them to a SHARE — one number for the whole
+// thought. The descent surface draws the descent node by node, and its done-when
+// names the branches that went out explicitly, so it needs the per-node answer
+// the share was computed from: not "this star is 60% lit" but "this hop is the
+// dark one". A renderer handed only the share cannot recover which.
+//
+// IT DOES NOT RE-DERIVE ANYTHING. The verdict is a person's answer, stored
+// (ADR 0313), and this reads it through the same kernel-mediated
+// `lifecycle.removals` port brightness reads — never a cross-module require
+// (ADR 0083 rule 1), and never a diff. A removal the project has not CONFIRMED
+// is not a removal here, which is why a refactor, a rename and a file move
+// darken nothing.
+//
+// WHY IT IS NOT FOLDED INTO attachStateToTrail, which already holds a
+// brightness result carrying `removedTasks`. That attacher's job is the five
+// states (ADR 0322) and its contract is consumed by three surfaces; widening it
+// so one of them can draw a second thing would make the other two pay for a read
+// they do not use. This composes beside it instead, exactly as the descent, the
+// size and the state already compose beside each other on the route — and it is
+// mounted only on the read that draws per-node, so the trail page's cost is
+// unchanged.
+//
+// THE ROOTS ARE INCLUDED, NOT JUST THE DESCENT. `attachDescentToTrail`
+// deliberately leaves an idea's own root tasks out of `descent_tasks` (the trail
+// already names them as what the idea became, and repeating them would
+// double-count the first hop). But a root can be removed like any other node —
+// it is the commonest case of a thought whose work was torn out — so the roots
+// are asked about here too, and the answer is keyed by TASK ID so a renderer can
+// look up either.
+
+// Reached through `api.resolveOptional(...)` rather than a destructured
+// `const { resolveOptional } = api`. Both resolve the registry at CALL time, so
+// this is not a correctness fix — the difference is that the property can be
+// swapped, which is how tests/idea_descent_surface.mjs §8 exercises the
+// readable / empty / unreadable answers without a lifecycle module and without
+// a test-only argument on the function below. ./idea-state.js reaches the
+// `reward` port the same way, for the same reason.
+const api = require('../../src/module-api');
+const { directRootsForIdea } = require('./trail-descent');
+
+// A positive integer id as it arrives off a row, where a bigint may be a string.
+// Never coerced with Number() — the guard the sibling reads use, for the same
+// precision reason.
+function idOf(v) {
+  return /^[1-9]\d*$/.test(String(v)) ? String(v) : null;
+}
+
+// attachRemovalToDescent — hangs `removed_tasks` on every idea, in place.
+//
+// The value is an object keyed by task id string, NOT a Map and NOT an array:
+// this rides to a browser through JSON, where a Map serialises to `{}` and an
+// array costs the renderer a scan per row it draws. (`idea.size.byTask` is a Map
+// for exactly the reason this is not — it never leaves the server.) Each entry
+// is `{ proposal_task_id, ship_task_id, paths, decided_at }`, snake_cased to
+// match every other field the route already returns.
+//
+// AN IDEA WITH NOTHING REMOVED GETS `{}`, NEVER A MISSING KEY, and an idea whose
+// removal facts COULD NOT BE READ gets `null`. Those are three different
+// answers and only two of them may be drawn as "nothing went out" — the same
+// posture brightness takes with `share: null` and size with `historical: null`.
+// A surface that treats an unreadable descent as a whole one silently promises a
+// reader that nothing died.
+async function attachRemovalToDescent(ideas, { client = null } = {}) {
+  const list = Array.isArray(ideas) ? ideas : [];
+  if (list.length === 0) return list;
+
+  // Every task drawn on the page: the descent nodes AND the roots they hang
+  // below. One set, so one port call however many ideas are here.
+  const perIdea = new Map();
+  const all = new Set();
+  for (const idea of list) {
+    const ids = new Set();
+    for (const r of directRootsForIdea(idea)) ids.add(r);
+    const descent = Array.isArray(idea.descent_tasks) ? idea.descent_tasks : [];
+    for (const row of descent) {
+      const id = idOf(row && row.task_id);
+      if (id) ids.add(id);
+    }
+    perIdea.set(String(idea.id), ids);
+    for (const id of ids) all.add(id);
+  }
+
+  const port = api.resolveOptional && api.resolveOptional('lifecycle.removals');
+  const readable = !!(port && typeof port.confirmedRemovalsForTasks === 'function');
+  // The port is there and there is simply nothing to ask about: that is an
+  // established answer — nothing removed — not an unreadable one.
+  const confirmed = readable && all.size > 0
+    ? await port.confirmedRemovalsForTasks([...all], { client })
+    : new Map();
+
+  for (const idea of list) {
+    if (!readable) { idea.removed_tasks = null; continue; }
+    const out = {};
+    for (const taskId of perIdea.get(String(idea.id)) || []) {
+      const hit = confirmed.get(taskId);
+      if (!hit) continue;
+      out[taskId] = {
+        proposal_task_id: hit.proposalTaskId == null ? null : String(hit.proposalTaskId),
+        ship_task_id: hit.shipTaskId == null ? null : String(hit.shipTaskId),
+        paths: Array.isArray(hit.paths) ? hit.paths : [],
+        decided_at: hit.decidedAt || null,
+      };
+    }
+    idea.removed_tasks = out;
+  }
+
+  return list;
+}
+
+module.exports = { attachRemovalToDescent };

package/modules/ideas/trail.js

@@ -52,6 +52,44 @@ const { skillFrictionHiddenClause } = require('./skill-friction');
 // filing that did not convert and is deliberately not what ./idea-state.js
 // reads. Two nullable columns on joins the query already makes, so this costs
 // no round trip.
+// TRAIL_ROW_SELECT — the shape of a trail row, spelled ONCE.
+//
+// Two reads want it now: the page keyed by person (listIdeaTrailForBuilder)
+// and the single row the idea detail page needs (getIdeaTrailRow, below). They
+// differ only in their WHERE, and the SELECT is the part that must not diverge:
+// every one of the three attachers that hang off these rows reads fields from
+// it by name — `lineage_tasks` for the descent roots, `promoted_task_goal_id`
+// and `promoted_task_status` for the well and the nod — and a hand-copied
+// second projection that quietly stopped carrying one of them would not error.
+// It would render an idea with a real descent as a protostar in open space,
+// which is a wrong answer that looks exactly like a right one.
+//
+// So the detail read is NOT getIdea() from ./reads.js with the attachers bolted
+// on. That row carries no lineage at all, so the descent would fall back to the
+// legacy `promoted_to_task_id` alone and silently lose every idea that became
+// more than one task (ideas_task_lineage, task 1002997).
+const TRAIL_ROW_SELECT = `SELECT ${IDEA_COLS_Q}, ${GRADE_COLS_Q},
+            pt.title  AS promoted_task_title,
+            pt.status AS promoted_task_status,
+            pt.goal_id AS promoted_task_goal_id,
+            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,
+                  'goal_id', lt.goal_id
+                ) 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`;
+
 const IDEA_TRAIL_DEFAULT_LIMIT = 20;
 const IDEA_TRAIL_MAX_LIMIT = 100;
 
@@ -75,27 +113,7 @@ async function listIdeaTrailForBuilder(builderId, { limit = IDEA_TRAIL_DEFAULT_L
   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,
-            pt.goal_id AS promoted_task_goal_id,
-            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,
-                  'goal_id', lt.goal_id
-                ) 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
+    `${TRAIL_ROW_SELECT}
       WHERE ${where}
       ORDER BY i.captured_at DESC, i.id DESC
       LIMIT $${params.length - 1} OFFSET $${params.length}`,
@@ -115,9 +133,26 @@ async function countIdeaTrailForBuilder(builderId, { viewerRank = null } = {}, d
   return rows[0].n;
 }
 
+// getIdeaTrailRow — ONE idea, in the trail row shape, for the idea detail page
+// (task 1004094 / BV2.R10). Keyed by idea id rather than by person, and
+// therefore NOT gated on captured_by: /idea/:id is a record anyone signed in
+// may read, and the descent below it is the same record read further down. The
+// skill-friction gate is not applied here either, for the same reason the
+// existing GET /inbox/:id does not apply it — that route is the deep-link
+// resolver, and a ref that resolves for one reader and 404s for another is a
+// worse answer than the one the route already gives.
+//
+// Returns null for an id that is not there, which the route turns into a 404.
+async function getIdeaTrailRow(ideaId, deps = {}) {
+  const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
+  const { rows } = await activePool.query(`${TRAIL_ROW_SELECT}\n      WHERE i.id = $1`, [ideaId]);
+  return rows[0] ?? null;
+}
+
 module.exports = {
   IDEA_TRAIL_DEFAULT_LIMIT,
   IDEA_TRAIL_MAX_LIMIT,
   listIdeaTrailForBuilder,
   countIdeaTrailForBuilder,
+  getIdeaTrailRow,
 };

package/modules/provisioning/control-plane-guard.js

@@ -30,10 +30,18 @@
 //                  the door task 1003159 builds.
 //   restart      — the liveness remedy (task 1003238). Restarting the platform is
 //                  recoverable and already owner-initiated elsewhere.
+//   core-upgrade-preflight
+//                — `upgrade.js --dry-run`. It RUNS NOTHING: it returns at pre-flight
+//                  before the pin moves, before npm, before any restart. Refusing it
+//                  here protected the box from nothing and removed the feature from
+//                  everyone, because the control plane is the ONLY instance that runs
+//                  the provisioning module — so its hall is the only one with an
+//                  Upgrade page at all. A preview that cannot run where the button
+//                  lives is not a preview (task 1004125).
 //
 // Adding to this list is a deliberate edit someone has to argue for. It is pinned
 // by name in tests/core_upgrade_door.mjs so it cannot grow as a side effect.
-const CONTROL_PLANE_ACTIONS = Object.freeze(['core-upgrade', 'restart']);
+const CONTROL_PLANE_ACTIONS = Object.freeze(['core-upgrade', 'core-upgrade-preflight', 'restart']);
 
 /**
  * May this intent action be aimed at an instance of this hosting shape? PURE.

package/modules/provisioning/core-upgrade.js

@@ -149,7 +149,12 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
   return async function coreUpgradeHandler(req, res) {
     const id = parseId(req, res);
     if (!id) return;
-    if (validateOrRespond(req, res, { to: { type: 'string', maxLength: 32 } }, { strict: true })) return;
+    // Under `strict: true` an undeclared field is not ignored — it is a 400 before the
+    // handler runs. So `dry_run` must be DECLARED here, not merely read below.
+    if (validateOrRespond(req, res, {
+      to: { type: 'string', maxLength: 32 },
+      dry_run: { type: 'boolean' },
+    }, { strict: true })) return;
     try {
       const inst = await provisioning.getInstanceById(pool, id);
       if (!inst) return res.fail('instance_not_found', 404);
@@ -204,6 +209,17 @@ function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond
       });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/core-upgrade', err);
+      // A REFUSAL IS NOT AN OUTAGE. The control-plane guard throws an error carrying
+      // `code`, `status` and a `publicMessage` it wrote for exactly this moment — and
+      // this catch used to discard all three, so every guard refusal reached the owner
+      // as a 500 "internal error" while the real sentence sat in the journal. Nothing
+      // in the repo honoured `publicMessage`; it was assigned once and read never
+      // (task 1004125). Only an error that has already declared itself public is
+      // forwarded — anything else still gets the opaque 500, because an unexpected
+      // throw may carry anything.
+      if (err && err.publicMessage && err.code && err.status) {
+        return res.fail(err.code, { status: err.status, message: err.publicMessage });
+      }
       return res.fail('core_upgrade_failed', { status: 500, message: 'internal error' });
     }
   };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.925",
+  "version": "1.19.927",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.925",
+      "version": "1.19.927",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.925",
+  "version": "1.19.927",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.925'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.927'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');