@bongos/core 1.19.1005 → 1.19.1007

package/modules/lifecycle/help-requests.js

@@ -48,7 +48,7 @@ async function craftsForBuilder(builderId, deps = {}) {
   return [...new Set(list.map(craftForDiscipline).filter(Boolean))];
 }
 
-const COLS = 'id, requested_by, needs_craft, needs_builder_id, what_is_stuck, task_id, goal_id, status, created_at, updated_at, settled_by';
+const COLS = 'id, requested_by, needs_craft, needs_builder_id, what_is_stuck, task_id, goal_id, status, created_at, updated_at, settled_by, settled_reason';
 // The two list reads also NAME the people on a row — who is asking (the fact
 // the collab page owes a helper: "who to answer", task 1003471) and who a
 // by-name ask is addressed to — through two LEFT JOINs on builders. COLS stays
@@ -57,10 +57,20 @@ const LIST_COLS = `${COLS.split(', ').map((c) => `h.${c}`).join(', ')}, `
   + 'a.github_login AS requested_by_login, a.display_name AS requested_by_name, '
   + 'a.avatar_url AS requested_by_avatar_url, '
   + 'n.github_login AS needs_builder_login, n.display_name AS needs_builder_name, '
-  + 'n.avatar_url AS needs_builder_avatar_url';
+  + 'n.avatar_url AS needs_builder_avatar_url, '
+  // The ARCHIVE's two extra facts (task 1004224). A settled row has to say HOW it
+  // ended, and neither half of that is on the row itself: `settled_by` is an id
+  // with no name, and `task_id` is a number with no title. Both are on the open
+  // reads too rather than on a separate archive-only projection — one projection
+  // between the query and the page is the whole reason the open and archived
+  // rows can share a renderer.
+  + 's.github_login AS settled_by_login, s.display_name AS settled_by_name, '
+  + 't.title AS task_title, t.status AS task_status';
 const LIST_FROM = 'FROM lifecycle_help_requests h '
   + 'LEFT JOIN builders a ON a.id = h.requested_by '
-  + 'LEFT JOIN builders n ON n.id = h.needs_builder_id';
+  + 'LEFT JOIN builders n ON n.id = h.needs_builder_id '
+  + 'LEFT JOIN builders s ON s.id = h.settled_by '
+  + 'LEFT JOIN tasks t ON t.id = h.task_id';
 const MAX_STUCK = 4000;
 // Defence in depth: both reads are bounded today (open-status churn, per-builder
 // scope), but an unsettled pile should degrade the page, not the server.
@@ -222,6 +232,91 @@ async function listOpenAll({ limit = MAX_ROWS } = {}, deps = {}) {
   return rows;
 }
 
+// ---- the ledger settles its own asks (task 1004224) -------------------------
+//
+// THE ASK THAT NOBODY NEEDED TO CLOSE. A request naming a task is a question
+// ABOUT that task, and when the task ships the question is over — but until this
+// existed, the row stayed open until its author remembered it. So Collab kept a
+// to-do list of questions the rest of Bongos had already answered.
+//
+// IT TAKES NO ARGUMENTS, AND THAT IS THE SECURITY PROPERTY. The PATCH path's
+// WHERE clause is the entire permission model for this table: who may close what.
+// A settle helper that accepted an id, or a task id, or a builder id would be a
+// second writer of `status` with no such clause — a way to close somebody else's
+// ask by naming it. This one is derivable from ledger state alone: every row it
+// can possibly touch is a row whose named task is already `shipped`, and no
+// caller can make that true by asking. A request body cannot reach it, because
+// there is no parameter for one to reach.
+//
+// ONLY 'shipped'. Not 'completed' and not 'confirmed' — those are stations on the
+// way to landing, and a question closed at 'confirmed' would reopen as a lie if
+// the ship then stranded. Not 'abandoned' either: a task nobody finished is the
+// case where the asker most needs their question still standing.
+//
+// ONLY rows WITH a task. An ask carrying no task_id has no ledger fact to settle
+// it, and inventing one — treating a reply as an answer, say — would close the
+// clarifying question that was asking for more detail. Those still need a person.
+//
+// IDEMPOTENT, and safe to run on every list read: the WHERE matches only rows
+// that are still open, so a second run within the same page load finds nothing.
+async function settleFromLedger(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_help_requests h
+        SET status = 'answered', settled_reason = 'task_shipped', updated_at = now()
+      WHERE h.status = 'open'
+        AND h.task_id IS NOT NULL
+        AND EXISTS (SELECT 1 FROM tasks t WHERE t.id = h.task_id AND t.status = 'shipped')
+     RETURNING h.id, h.task_id`
+  );
+  return rows;
+}
+
+// The ARCHIVE, addressee side: settled asks that were addressed to THIS reader —
+// by name, or through a craft they belong to. The predicate is deliberately the
+// same one listOpenForBuilder uses, inverted on status only.
+//
+// `crafts` comes from the CALLER'S OWN PROFILE and the route must keep it that
+// way. C01's grader found this surface's one real hole: a ?craft= query param
+// validated against the enum but never against the caller, which let any builder
+// read every request addressed to a craft they did not belong to. An archive is a
+// larger prize than an open board — it is the whole history — so the filter here
+// is applied to a craft list the caller cannot choose, and the route derives it
+// from `builders.preferred_disciplines` exactly as the open read does.
+//
+// The author exclusion stays too: your own settled asks are the OTHER list.
+async function listArchivedForBuilder({ builderId, crafts = [], limit = MAX_ROWS }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const safeCrafts = (Array.isArray(crafts) ? crafts : []).filter((c) => HELP_CRAFTS.includes(c));
+  const { rows } = await activePool.query(
+    `SELECT ${LIST_COLS} ${LIST_FROM}
+      WHERE h.status <> 'open'
+        AND h.requested_by <> $1
+        AND (h.needs_builder_id = $1 OR h.needs_craft = ANY($2::text[]))
+      ORDER BY h.updated_at DESC, h.id DESC
+      LIMIT $3`,
+    [builderId, safeCrafts, capRows(limit)]
+  );
+  return rows;
+}
+
+// The ARCHIVE, asker side: settled asks this reader made of other people.
+// listMine already filters by one exact status; this asks the other question —
+// "everything that is no longer open" — which an exact-status filter cannot
+// express without the caller enumerating the vocabulary and the two drifting the
+// next time a status is added.
+async function listArchivedMine({ builderId, limit = MAX_ROWS }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT ${LIST_COLS} ${LIST_FROM}
+      WHERE h.requested_by = $1 AND h.status <> 'open'
+      ORDER BY h.updated_at DESC, h.id DESC
+      LIMIT $2`,
+    [builderId, capRows(limit)]
+  );
+  return rows;
+}
+
 async function getHelpRequest(id, deps = {}) {
   const activePool = deps.pool || pool;
   const { rows } = await activePool.query(`SELECT ${COLS} FROM lifecycle_help_requests WHERE id = $1`, [id]);
@@ -356,6 +451,7 @@ module.exports = {
   HELP_CRAFTS, helpCrafts, disciplineForCraft, craftForDiscipline, craftsForBuilder,
   validateHelpRequest, MAX_STUCK, MAX_ROWS, capRows,
   builderExists, createHelpRequest, listOpenForBuilder, listMine, listOpenAll, getHelpRequest, setHelpRequestStatus,
+  settleFromLedger, listArchivedForBuilder, listArchivedMine,
   countOpenForBuilder, craftMapSql,
   MAX_REPLY, MAX_THREAD_ON_LIST, validateReply, createReply, listReplies, repliesForRequests,
 };

package/modules/lifecycle/migrations/lifecycle_012_collab_self_settling.sql

@@ -0,0 +1,114 @@
+-- lifecycle_012_collab_self_settling.sql — Collab stops waiting to be told
+-- (task 1004224, goal 1000095; owner direction 2026-09-24).
+--
+-- THE DEFECT. Both collab tables settle only when a HUMAN ticks a row:
+-- lifecycle_004's help request waits for its asker (widened to the addressee by
+-- ADR 0330), and lifecycle_005's recommendation waits for a decline or a
+-- withdrawal. So a request whose SUBJECT is already finished — the task it names
+-- has shipped, the task it recommended has been taken up — sits open forever,
+-- and the person who asked has to go and close a question the ledger answered
+-- days ago. Collab is the one surface in Bongos that could not read the ledger
+-- it lives in.
+--
+-- WHAT THIS MIGRATION ADDS IS A REASON, NOT A MECHANISM. The settling itself is
+-- an UPDATE derived entirely from `tasks` and `claims` (settleFromLedger() in
+-- help-requests.js and task-recommendations.js) — it takes no parameters at all,
+-- precisely so it can never become a second, unguarded way for a caller to close
+-- somebody else's row. The columns here exist so the RECORD can tell the two
+-- kinds of settlement apart.
+--
+-- WHY settled_by IS NOT ENOUGH. `settled_by` is a builder id, and an automatic
+-- close has no builder behind it. Leaving it NULL would make an auto-settled row
+-- indistinguishable from one settled before ADR 0330 added the column — so the
+-- archive would have to say "closed by nobody" about two quite different things.
+-- `settled_reason` names WHICH mechanism ended the row, and NULL still means the
+-- old thing it always meant: a person did it.
+--
+-- WHY 'taken_up' IS NOT 'accepted'. lifecycle_005's header argues at length that
+-- this table must have no 'accepted' status: accepting a recommendation IS
+-- claiming the task, which is the claims table's job, and a status here saying
+-- "accepted" would be a second, weaker record of holding work. Nothing about
+-- that changed. 'taken_up' is not the recipient accepting anything — it is the
+-- ledger OBSERVING, after the fact, that the claim already exists somewhere
+-- else, and closing a recommendation that has nothing left to recommend. The
+-- claims table remains the only record of who holds a task; this status is
+-- derived FROM it and grants nothing. It is also, deliberately, not settable
+-- through any route: the decline and withdraw writes still name their own
+-- statuses explicitly.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it: both
+-- tables are ones the lifecycle module owns outright (ADR 0083 §Decision #5).
+-- `tasks` and `claims` are core tables this module only READS, here and in the
+-- settle queries — no core table is altered.
+
+ALTER TABLE lifecycle_help_requests
+  ADD COLUMN IF NOT EXISTS settled_reason text;
+
+-- Enumerated rather than free text: the archive renders a different sentence per
+-- reason, and a value nothing renders would show a reader a blank where the
+-- explanation should be. NULL is the open row and the human-settled row alike.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'lifecycle_help_requests_settled_reason_chk'
+  ) THEN
+    ALTER TABLE lifecycle_help_requests
+      ADD CONSTRAINT lifecycle_help_requests_settled_reason_chk
+      CHECK (settled_reason IS NULL OR settled_reason IN ('task_shipped'));
+  END IF;
+END $$;
+
+COMMENT ON COLUMN lifecycle_help_requests.settled_reason IS
+  'Why this ask stopped being open, when it was not a person who closed it. NULL = open, or settled by the builder in settled_by. ''task_shipped'' = the task it named reached shipped and the ledger closed it (task 1004224).';
+
+ALTER TABLE lifecycle_task_recommendations
+  ADD COLUMN IF NOT EXISTS settled_reason text;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'lifecycle_task_recommendations_settled_reason_chk'
+  ) THEN
+    ALTER TABLE lifecycle_task_recommendations
+      ADD CONSTRAINT lifecycle_task_recommendations_settled_reason_chk
+      CHECK (settled_reason IS NULL OR settled_reason IN ('recipient_took_it_up'));
+  END IF;
+END $$;
+
+-- The status vocabulary gains 'taken_up'. See the header for why this is not
+-- 'accepted' and why no route may write it.
+ALTER TABLE lifecycle_task_recommendations
+  DROP CONSTRAINT IF EXISTS lifecycle_task_recommendations_status_chk;
+ALTER TABLE lifecycle_task_recommendations
+  ADD CONSTRAINT lifecycle_task_recommendations_status_chk
+  CHECK (status IN ('open', 'declined', 'withdrawn', 'taken_up'));
+
+COMMENT ON COLUMN lifecycle_task_recommendations.settled_reason IS
+  'Why this recommendation stopped being open, when neither party acted on it. NULL = open, declined or withdrawn. ''recipient_took_it_up'' = the recipient now holds or shipped the task, so there is nothing left to recommend (task 1004224).';
+
+-- The settle reads. Each UPDATE scans for OPEN rows that have a subject to
+-- check, so the partial index is on exactly that predicate: on a project where
+-- nothing has just shipped these queries should touch almost nothing, and they
+-- run on the Collab page's own load path.
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_open_task_idx
+  ON lifecycle_help_requests (task_id) WHERE status = 'open' AND task_id IS NOT NULL;
+
+-- `(task_id, recommended_to)` rather than a bare partial index on status: the
+-- UPDATE's outer filter is `status = 'open'` alone, so the two columns do not
+-- narrow the scan — they are there so the per-row subqueries against `claims`
+-- and `tasks` can be satisfied from the index rather than by fetching the heap
+-- row. An index-only scan, not a better filter; do not read more into it.
+CREATE INDEX IF NOT EXISTS lifecycle_task_recommendations_open_task_idx
+  ON lifecycle_task_recommendations (task_id, recommended_to) WHERE status = 'open';
+
+-- The ARCHIVE reads, which are the mirror image of lifecycle_004's two partial
+-- 'open' indexes: settled asks, addressed to a person or to a craft. Without
+-- these the archive is a sequential scan over the whole history of the table —
+-- the half of it that only ever grows.
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_settled_person_idx
+  ON lifecycle_help_requests (needs_builder_id) WHERE status <> 'open';
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_settled_craft_idx
+  ON lifecycle_help_requests (needs_craft) WHERE status <> 'open';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_012_collab_self_settling')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/routes/help-requests.js

@@ -15,6 +15,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const help = require('../help-requests');
+const settle = require('../collab-settle');
 
 const { asyncHandler, validateOrRespond, parseId } = api;
 
@@ -29,6 +30,41 @@ async function withReplies(rows) {
   return rows.map((r) => ({ ...r, replies: threads.get(String(r.id)) || [] }));
 }
 
+// COLLAB UPDATES ITSELF (task 1004224). Every list read below settles first, so
+// an ask whose task has shipped is already 'answered' by the time the rows come
+// back — nobody has to close a question the ledger answered days ago.
+//
+// IN FRONT OF THE READ, NOT BESIDE IT. The page makes three of these reads in one
+// fan-out and then renders an archive from a fourth. If a row settled between two
+// of them it would leave one block and appear in another in the SAME load — shown
+// twice, counted twice, and the figures at the top of the page lying about both.
+// Settling before each read cannot prevent that on its own, but it makes the
+// window a race between concurrent requests rather than the guaranteed outcome of
+// a single page load: after the first read of a load has settled everything
+// eligible, the later ones find nothing left to settle.
+//
+// help.settleFromLedger TAKES NO ARGUMENTS. Nothing from the request — not the
+// caller, not the query, not the body — can steer which rows it touches; see its
+// own header for why that is the security property and not merely tidiness.
+//
+// THROTTLED TO ONE SETTLE PER SHORT WINDOW (collab-settle.js). Calling it on
+// every read is correct — it is idempotent and bounded — but one Collab page
+// load fans out across four of these routes, and three of those UPDATEs found
+// nothing and wrote nothing. That is wasted write volume on a read path, and
+// avoidable row-lock contention when several builders open Collab at once.
+//
+// Failure is swallowed, but it is LOGGED: a settle that could not run must
+// degrade to "the old rows are still open" rather than to a Collab page that
+// will not load — and a surface that silently stopped settling would look
+// exactly like one with nothing to settle, which is the harder thing to notice.
+async function settleFirst() {
+  try {
+    await settle.throttled('help_requests', () => help.settleFromLedger());
+  } catch (err) {
+    console.error('help-requests: settleFromLedger failed; rows stay as they were', err);
+  }
+}
+
 module.exports = function buildHelpRequestsRouter() {
   const router = express.Router();
 
@@ -83,6 +119,7 @@ module.exports = function buildHelpRequestsRouter() {
   //
   // rank: any-builder — you only ever see what is addressed to you.
   router.get('/help-requests/for-me', api.requireBuilder, asyncHandler('GET /help-requests/for-me', async (req, res) => {
+    await settleFirst();
     // The caller's crafts come from THEIR OWN profile, never from the query — a
     // ?craft= param validated only against the enum let any builder read requests
     // addressed to a craft they do not belong to (grader, task 1003171). The param
@@ -96,16 +133,59 @@ module.exports = function buildHelpRequestsRouter() {
 
   // rank: any-builder — your own asks, so you can settle them.
   router.get('/help-requests/mine', api.requireBuilder, asyncHandler('GET /help-requests/mine', async (req, res) => {
+    await settleFirst();
     const status = typeof req.query.status === 'string' ? req.query.status : null;
     const rows = await withReplies(await help.listMine({ builderId: req.builder.id, status }));
     return res.json({ help_requests: rows, count: rows.length });
   }, { errorCode: 'help_request_list_failed' }));
 
+
+  // THE ARCHIVE (task 1004224, owner direction): what a settled ask becomes.
+  //
+  // Until now a settled ask simply vanished from Collab. That was tolerable while
+  // settling meant a person had decided the ask was done — they knew. It stops
+  // being tolerable the moment the LEDGER settles asks on its own: a row can now
+  // leave the page without anybody having watched it go, and a surface that
+  // silently disappears its own history is asking to be distrusted.
+  //
+  // TWO LISTS, NOT ONE, and the split is the owner's: asks made OF YOU and asks
+  // you made OF OTHERS are different questions with different follow-ups, and a
+  // merged list would need a per-row label to say which it was — which is the
+  // same information, said worse.
+  //
+  // ONE ROUTE FOR BOTH. They share a settle, a bound and a shape, and the page
+  // draws them side by side in one section; two routes would be two round trips
+  // for one collapsed block and two places for the projection to drift.
+  //
+  // rank: any-builder, and the scoping matches the open reads exactly — you see
+  // what was addressed to you and what you asked, and nothing else. `crafts`
+  // comes from `builders.preferred_disciplines` through craftsForBuilder, NEVER
+  // from the query string. That is not caution: a ?craft= param validated only
+  // against the enum is precisely the hole C01's grader found on the open read,
+  // and an archive is the larger prize because it is the whole history rather
+  // than today's board. This route accepts no craft, no builder and no status
+  // from the caller, so there is nothing here to narrow or widen.
+  router.get('/help-requests/archive', api.requireBuilder, asyncHandler('GET /help-requests/archive', async (req, res) => {
+    await settleFirst();
+    const crafts = await help.craftsForBuilder(req.builder.id);
+    const [askedOfYou, askedOfOthers] = await Promise.all([
+      help.listArchivedForBuilder({ builderId: req.builder.id, crafts }),
+      help.listArchivedMine({ builderId: req.builder.id }),
+    ]);
+    return res.json({
+      asked_of_you: askedOfYou,
+      asked_of_others: askedOfOthers,
+      count: askedOfYou.length + askedOfOthers.length,
+      crafts,
+    });
+  }, { errorCode: 'help_request_list_failed' }));
+
   // The BOARD read (task 1003942): every open ask in the project, newest first,
   // for the Collab page's "all open asks" block. rank: any-builder — an ask is
   // addressed inside this project and every reader here is a member; the route
   // takes no craft and no builder from the caller, so there is nothing to widen.
   router.get('/help-requests', api.requireBuilder, asyncHandler('GET /help-requests', async (req, res) => {
+    await settleFirst();
     const rows = await withReplies(await help.listOpenAll());
     return res.json({ help_requests: rows, count: rows.length });
   }, { errorCode: 'help_request_list_failed' }));

package/modules/lifecycle/routes/recommendations.js

@@ -27,6 +27,22 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const recs = require('../task-recommendations');
+const settle = require('../collab-settle');
+
+// COLLAB UPDATES ITSELF (task 1004224), the recommendations half. A recommendation
+// whose recipient now holds or has shipped the task has already succeeded, so the
+// read settles before it lists and the sender stops seeing 'open' about something
+// that is done. recs.settleFromLedger TAKES NO ARGUMENTS — see its own header for
+// why that is what stops it becoming a second, unguarded writer of the status
+// column. Failures are swallowed: the rows stay as they were rather than taking a
+// page down.
+async function settleFirst() {
+  try {
+    await settle.throttled('task_recommendations', () => recs.settleFromLedger());
+  } catch (err) {
+    console.error('recommendations: settleFromLedger failed; rows stay as they were', err);
+  }
+}
 
 const { asyncHandler, validateOrRespond, parseId } = api;
 
@@ -87,6 +103,7 @@ module.exports = function buildTaskRecommendationsRouter() {
   // holds the task. It carries the task's own status so the recipient can judge,
   // and that is all. Claiming is a separate, deliberate act on their part.
   router.get('/task-recommendations/for-me', api.requireBuilder, asyncHandler('GET /task-recommendations/for-me', async (req, res) => {
+    await settleFirst();
     const rows = await recs.listForRecipient({ builderId: req.builder.id });
     return res.json({ recommendations: rows, count: rows.length });
   }, { errorCode: 'recommendation_list_failed' }));
@@ -96,6 +113,7 @@ module.exports = function buildTaskRecommendationsRouter() {
   // "the recommendation and its author are readable afterwards".
   router.get('/task-recommendations/mine', api.requireBuilder, asyncHandler('GET /task-recommendations/mine', async (req, res) => {
     const status = typeof req.query.status === 'string' ? req.query.status : null;
+    await settleFirst();
     const rows = await recs.listFromSender({ builderId: req.builder.id, status });
     return res.json({ recommendations: rows, count: rows.length });
   }, { errorCode: 'recommendation_list_failed' }));
@@ -111,6 +129,7 @@ module.exports = function buildTaskRecommendationsRouter() {
   router.get('/tasks/:id/recommendations', api.requireBuilder, asyncHandler('GET /tasks/:id/recommendations', async (req, res) => {
     const id = parseId(req, res, { code: 'bad_task_id', positiveInt: true });
     if (id === null) return;
+    await settleFirst();
     const rows = await recs.listForTask({ taskId: id });
     return res.json({ recommendations: rows, count: rows.length });
   }, { errorCode: 'recommendation_list_failed' }));

package/modules/lifecycle/task-recommendations.js

@@ -32,7 +32,7 @@
 
 const { pool } = require('../../src/module-api');
 
-const COLS = 'id, task_id, recommended_by, recommended_to, reason, status, created_at, updated_at';
+const COLS = 'id, task_id, recommended_by, recommended_to, reason, status, created_at, updated_at, settled_reason';
 
 const MAX_REASON = 2000;
 // Defence in depth, matching help-requests: both reads are bounded today (open
@@ -125,7 +125,7 @@ async function listForRecipient({ builderId, limit = MAX_ROWS }, deps = {}) {
   const activePool = deps.pool || pool;
   const { rows } = await activePool.query(
     `SELECT r.id, r.task_id, r.recommended_by, r.recommended_to, r.reason,
-            r.status, r.created_at, r.updated_at,
+            r.status, r.settled_reason, r.created_at, r.updated_at,
             t.title       AS task_title,
             t.status      AS task_status,
             b.github_login AS recommended_by_login,
@@ -148,7 +148,7 @@ async function listFromSender({ builderId, status = null, limit = MAX_ROWS }, de
   const activePool = deps.pool || pool;
   const { rows } = await activePool.query(
     `SELECT r.id, r.task_id, r.recommended_by, r.recommended_to, r.reason,
-            r.status, r.created_at, r.updated_at,
+            r.status, r.settled_reason, r.created_at, r.updated_at,
             t.title       AS task_title,
             t.status      AS task_status,
             b.github_login AS recommended_to_login,
@@ -173,7 +173,7 @@ async function listForTask({ taskId, limit = MAX_ROWS }, deps = {}) {
   const activePool = deps.pool || pool;
   const { rows } = await activePool.query(
     `SELECT r.id, r.task_id, r.recommended_by, r.recommended_to, r.reason,
-            r.status, r.created_at, r.updated_at,
+            r.status, r.settled_reason, r.created_at, r.updated_at,
             sender.github_login    AS recommended_by_login,
             sender.display_name    AS recommended_by_name,
             recipient.github_login AS recommended_to_login,
@@ -189,6 +189,72 @@ async function listForTask({ taskId, limit = MAX_ROWS }, deps = {}) {
   return rows;
 }
 
+// ---- the ledger settles its own recommendations (task 1004224) --------------
+//
+// A recommendation says "you should look at this task". When the person it was
+// sent to is holding that task, or has shipped it, there is nothing left to
+// recommend — and yet the row stayed open until somebody declined or withdrew
+// it, which are both the wrong word for what happened. The sender's own list
+// reported "open" about a recommendation that had entirely succeeded.
+//
+// 'taken_up' IS NOT 'accepted', AND THE DISTINCTION IS THE WHOLE POINT. This
+// module's header argues that accepting a recommendation IS claiming the task,
+// so a status here meaning "accepted" would be a second, weaker record of
+// holding work and would make this table look like a place claims come from.
+// Nothing about that changed: 'taken_up' grants nothing, transfers nothing and
+// is written by nobody. It is this table READING the claims table after the fact
+// and admitting the question is closed. Who holds the task is still answered by
+// joining claims — never by this column.
+//
+// IT TAKES NO ARGUMENTS, for the same reason settleFromLedger in help-requests.js
+// takes none: declineRecommendation and withdrawRecommendation enforce who may
+// settle in their WHERE clauses, and a helper that closed "the row for task N"
+// on request would be a third writer of `status` with no such clause. Every row
+// this can touch is one whose own recipient already holds or shipped its task,
+// and no caller can make that true by asking.
+//
+// NOT 'the task shipped' ALONE — shipped BY THE RECIPIENT, or held by them right
+// now. A task somebody ELSE shipped is the case where the recommendation was
+// never taken up at all, and closing it as 'taken_up' would put a success in the
+// sender's ledger that did not happen.
+//
+// A RELEASED CLAIM DOES NOT COUNT, and that is a correction rather than a
+// simplification. The first version accepted any claim ever made, reasoning that
+// looking at the task is what a recommendation asks for — but a builder who
+// claimed a task and handed it back has arrived at the same place as one who
+// declined, and recording that as 'taken_up' is the same class of mistake as
+// closing on somebody else's ship. The two branches still cover the whole
+// success path: a live claim catches work in progress, and `shipped_by` catches
+// work finished (whose claim is released by then, with outcome 'shipped').
+//
+// It is also the indexable shape, which matters because this runs on a read
+// path: `uniq_active_claim_per_task` is a partial index on `claims (task_id)
+// WHERE released_at IS NULL`, so the live-claim predicate can use it. The
+// any-claim version had no index to reach for — `claims` carries none on
+// `task_id` unpartialled — and this module may not add one, because `claims` is
+// a core table it only reads (ADR 0083 §Decision #5). So each open recommendation
+// would have degraded toward a scan of a table that only grows.
+//
+// IDEMPOTENT, and safe on every list read: only open rows match.
+async function settleFromLedger(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_task_recommendations r
+        SET status = 'taken_up', settled_reason = 'recipient_took_it_up', updated_at = now()
+      WHERE r.status = 'open'
+        AND (
+          EXISTS (SELECT 1 FROM claims c
+                   WHERE c.task_id = r.task_id AND c.builder_id = r.recommended_to
+                     AND c.released_at IS NULL)
+          OR EXISTS (SELECT 1 FROM tasks t
+                      WHERE t.id = r.task_id AND t.status = 'shipped'
+                        AND t.shipped_by = r.recommended_to)
+        )
+     RETURNING r.id, r.task_id, r.recommended_to`
+  );
+  return rows;
+}
+
 // The recipient declines. Costs nothing — see the header: this sets a status and
 // returns the row, and writes nothing anywhere else about either party.
 //
@@ -241,6 +307,7 @@ module.exports = {
   validateRecommendation,
   builderExists, taskExists,
   createRecommendation,
+  settleFromLedger,
   listForRecipient, listFromSender, listForTask,
   declineRecommendation, withdrawRecommendation,
   countOpenForRecipient,

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1005",
+  "version": "1.19.1007",
   "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.1005'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1007'; // 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');