@bongos/core 1.19.358 → 1.19.359

package/modules/lifecycle/routes/recommendations.js

@@ -0,0 +1,148 @@
+// modules/lifecycle/routes/recommendations.js — the write path and the reads for
+// recommending a task to someone (task 1003173 / C03, goal 1000075; criterion
+// collab-pass-a-task, ADR 0187 §3).
+//
+// WHY NOT `task-recommendations.js`, WHICH IS THE OBVIOUS NAME. `task-*.js` in
+// this directory is a RESERVED PREFIX: tests/helpers.mjs taskRoutesSource()
+// concatenates tasks.js with every sibling matching `task-*.js` and reads the
+// result as ONE source, because the tasks router was carved into pieces that must
+// still be asserted together. A separate surface named task-recommendations.js is
+// swept into that family and silently breaks assertions about the tasks router —
+// est_advisory and goal_advisory both matched THIS file's 201 body instead of the
+// task-create one. This surface is a sibling of help-requests.js, not a piece of
+// the tasks router, so it is named like help-requests.js. Do not rename it back.
+//
+// FIVE ROUTES, AND NOTHING THAT CLAIMS. Send one, see what is waiting on me, see
+// what I sent, decline, withdraw. There is deliberately no "accept" route: accepting
+// a recommendation IS claiming the task, which POST /claims already owns and which
+// is the recipient's own action. A route here that claimed on the recipient's
+// behalf would be the transfer this criterion exists to refuse, and even an
+// "accept" that only flipped a status would make this table look like the place
+// claims come from.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const recs = require('../task-recommendations');
+
+const { asyncHandler, validateOrRespond, parseId } = api;
+
+module.exports = function buildTaskRecommendationsRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — recommending is not a privileged act. It grants the
+  // recipient nothing they did not already have (the task was claimable by them
+  // or it was not), so gating it by rank would only stop newcomers from pointing
+  // at something useful.
+  router.post('/task-recommendations', api.requireBuilder, asyncHandler('POST /task-recommendations', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      task_id: { required: true, type: 'integer', min: 1 },
+      recommended_to: { required: true, type: 'integer', min: 1 },
+      reason: { required: true, type: 'string', minLength: 1, maxLength: recs.MAX_REASON },
+    })) return;
+
+    // The CHECK constraints are the authority; this restates them so the refusal
+    // names the field rather than surfacing a Postgres string as a 500. The
+    // sender comes from the SESSION, never the body — self-recommendation is
+    // checked against the authenticated builder.
+    const v = recs.validateRecommendation(req.body, req.builder.id);
+    if (!v.ok) return res.fail('invalid_recommendation', 400, { errors: v.errors });
+
+    // Referenced rows that do not exist would otherwise hit the FKs and surface
+    // as a generic 500, telling the sender nothing. Checked here so the refusal
+    // names the field; the FKs remain the authority.
+    if (!(await recs.taskExists(req.body.task_id))) {
+      return res.fail('invalid_recommendation', 400, {
+        errors: [{ field: 'task_id', reason: 'no_such_task' }],
+      });
+    }
+    if (!(await recs.builderExists(req.body.recommended_to))) {
+      return res.fail('invalid_recommendation', 400, {
+        errors: [{ field: 'recommended_to', reason: 'no_such_builder' }],
+      });
+    }
+
+    const out = await recs.createRecommendation({
+      taskId: req.body.task_id,
+      recommendedBy: req.builder.id,
+      recommendedTo: req.body.recommended_to,
+      reason: req.body.reason,
+    });
+    if (!out.ok) {
+      // Not a body the sender can fix — the same recommendation is already open.
+      return res.fail('recommendation_already_open', 409, {
+        task_id: req.body.task_id,
+        recommended_to: req.body.recommended_to,
+      });
+    }
+    return res.status(201).json({ ok: true, recommendation: out.recommendation });
+  }, { errorCode: 'recommendation_failed' }));
+
+  // rank: any-builder — you only ever see what is addressed to you.
+  //
+  // NOTE WHAT THIS RESPONSE DOES NOT CONTAIN: any signal that the recipient now
+  // 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) => {
+    const rows = await recs.listForRecipient({ builderId: req.builder.id });
+    return res.json({ recommendations: rows, count: rows.length });
+  }, { errorCode: 'recommendation_list_failed' }));
+
+  // rank: any-builder — what I recommended, and what became of it. Unfiltered by
+  // default: a declined recommendation stays readable, which is the criterion's
+  // "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;
+    const rows = await recs.listFromSender({ builderId: req.builder.id, status });
+    return res.json({ recommendations: rows, count: rows.length });
+  }, { errorCode: 'recommendation_list_failed' }));
+
+  // The per-task audit read: who recommended this task, to whom, and why.
+  //
+  // rank: any-builder, and deliberately NOT scoped to the two parties. The
+  // criterion's argument for a ledger is that an untraced recommendation is
+  // indistinguishable from a task quietly changing hands — a trace only the two
+  // people involved can read does not answer that. Tasks are already visible to
+  // every builder, and a recommendation says nothing more private than "this
+  // person thought that person should look at this".
+  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;
+    const rows = await recs.listForTask({ taskId: id });
+    return res.json({ recommendations: rows, count: rows.length });
+  }, { errorCode: 'recommendation_list_failed' }));
+
+  // Decline. Costs nothing, and this route is where that is visible: it flips a
+  // status and returns the row. No karma call, no counter, no notification to the
+  // sender beyond the row itself turning up in their own list.
+  //
+  // rank: any-builder — ownership is enforced in the UPDATE's WHERE, not by rank.
+  router.patch('/task-recommendations/:id', api.requireBuilder, asyncHandler('PATCH /task-recommendations/:id', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_recommendation_id', positiveInt: true });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      status: { required: true, type: 'string', enum: ['declined', 'withdrawn'] },
+    })) return;
+
+    // Who may set which: the RECIPIENT declines, the SENDER withdraws. Each
+    // update scopes itself to the right party in its own WHERE.
+    const row = req.body.status === 'declined'
+      ? await recs.declineRecommendation({ id, builderId: req.builder.id })
+      : await recs.withdrawRecommendation({ id, builderId: req.builder.id });
+
+    if (!row) {
+      // ONE refusal for every miss: absent, not yours to settle, or already
+      // settled. Looking the row up to say which would let a caller enumerate
+      // existing ids — the lesson help-requests learned from its grader round.
+      return res.fail('recommendation_not_settleable', 404, {
+        reason: 'no open recommendation you can settle with that id',
+      });
+    }
+    return res.json({ ok: true, recommendation: row });
+  }, { errorCode: 'recommendation_update_failed' }));
+
+  return router;
+};

package/modules/lifecycle/task-recommendations.js

@@ -0,0 +1,247 @@
+// modules/lifecycle/task-recommendations.js — "you should look at this": the data
+// layer for recommending a task to someone (task 1003173 / C03, goal 1000075;
+// criterion collab-pass-a-task, ADR 0187 §3).
+//
+// THE ONE RULE THIS FILE EXISTS TO HOLD. A pass RECOMMENDS; it never transfers.
+// Nothing here writes to `claims`, and nothing here reads a claim in order to move
+// one. The recipient still claims the task themselves through the ordinary claim
+// path, so claim/release stays the single way to hold work and nobody acquires a
+// task without opting in. There is deliberately no transfer function and no seam
+// for one: the decision was recommend-only, and an unused seam is a cost that
+// later reads as an intention.
+//
+// THE REASON IS REQUIRED, NOT OPTIONAL. The criterion's own argument is that an
+// untraced recommendation is indistinguishable from a task quietly changing hands.
+// So a reason the sender must write is what makes this a ledger rather than a
+// nudge, and it is enforced in three places that agree: the CHECK constraint (the
+// authority), validateRecommendation() (so the refusal names the field instead of
+// surfacing a Postgres string), and the route's body schema.
+//
+// DECLINING COSTS NOTHING. That is a claim about what this module does NOT do:
+// no counter, no cooldown, no karma or credit call, nothing written to either
+// builder. `decline` sets a status and returns the row. If a penalty ever appears
+// anywhere for declining, it did not come from here.
+//
+// Sibling of ./help-requests.js under the same goal, and deliberately shaped like
+// it — same deps.pool injection, same capRows bound, same pure-validator split —
+// so the two collab surfaces read as one thing.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+
+const COLS = 'id, task_id, recommended_by, recommended_to, reason, status, created_at, updated_at';
+
+const MAX_REASON = 2000;
+// Defence in depth, matching help-requests: both reads are bounded today (open
+// status, per-builder scope), but an unsettled pile should degrade the page rather
+// than the server.
+const MAX_ROWS = 200;
+
+function capRows(n) {
+  const v = Number(n);
+  return Number.isInteger(v) && v > 0 && v <= MAX_ROWS ? v : MAX_ROWS;
+}
+
+// PURE. Returns { ok, errors } so the route can 400 with named fields before any
+// query runs, and every branch is testable without a database. The table's CHECK
+// constraints remain the authority; these exist so a refusal is a named 400
+// instead of a 500 carrying a Postgres string.
+//
+// `senderId` is passed rather than read from the body on purpose: self-recommendation
+// is checked against the AUTHENTICATED builder, never against a client-supplied id.
+function validateRecommendation(input, senderId) {
+  const errors = [];
+  const b = input || {};
+
+  const taskId = b.task_id == null ? null : Number(b.task_id);
+  if (taskId === null) errors.push({ field: 'task_id', reason: 'required' });
+  else if (!Number.isInteger(taskId) || taskId <= 0) errors.push({ field: 'task_id', reason: 'bad_task_id' });
+
+  const to = b.recommended_to == null ? null : Number(b.recommended_to);
+  if (to === null) errors.push({ field: 'recommended_to', reason: 'required' });
+  else if (!Number.isInteger(to) || to <= 0) errors.push({ field: 'recommended_to', reason: 'bad_builder_id' });
+  else if (senderId != null && String(to) === String(senderId)) {
+    // Recommending a task to yourself is not a recommendation. Caught here so the
+    // refusal names the field; the not-self CHECK stays the authority.
+    errors.push({ field: 'recommended_to', reason: 'cannot_recommend_to_self' });
+  }
+
+  // The trace. See the header for why this is not nullable.
+  const reason = typeof b.reason === 'string' ? b.reason.trim() : '';
+  if (!reason) errors.push({ field: 'reason', reason: 'required' });
+  else if (reason.length > MAX_REASON) errors.push({ field: 'reason', reason: 'too_long' });
+
+  return { ok: errors.length === 0, errors };
+}
+
+// Existence checks so a bad reference is a named 400 rather than an FK violation
+// rendered as a 500. The FKs remain the authority — a row deleted between the
+// check and the insert still fails safely there.
+async function builderExists(id, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query('SELECT 1 FROM builders WHERE id = $1', [id]);
+  return rows.length > 0;
+}
+
+async function taskExists(id, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query('SELECT 1 FROM tasks WHERE id = $1', [id]);
+  return rows.length > 0;
+}
+
+// Send one. Returns { ok: true, recommendation } or { ok: false, reason }.
+//
+// ON CONFLICT DO NOTHING against the partial unique index, rather than letting the
+// 23505 escape as a 500: a second send of the same task to the same person while
+// one is still open is the same judgement repeated, and the caller should be told
+// that plainly. It is NOT an error the sender can fix by changing the body, so it
+// reads as `already_open`, not as a validation failure.
+async function createRecommendation(input, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_task_recommendations
+       (task_id, recommended_by, recommended_to, reason)
+     VALUES ($1, $2, $3, $4)
+     ON CONFLICT DO NOTHING
+     RETURNING ${COLS}`,
+    [input.taskId, input.recommendedBy, input.recommendedTo, String(input.reason).trim()]
+  );
+  if (!rows[0]) return { ok: false, reason: 'already_open' };
+  return { ok: true, recommendation: rows[0] };
+}
+
+// The recipient's read: what has been recommended to me, and by whom. Joined to
+// the task and the sender because a bare id list cannot be acted on — the whole
+// point is that the recipient can judge whether to go and claim it.
+//
+// It reports `recommended_task_status` rather than a "can I claim this" boolean.
+// Claimability is the claim path's answer (deps, touches, rank, an existing
+// claim), and duplicating that judgement here would be a second, staler copy of a
+// rule that already has an owner.
+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,
+            t.title       AS task_title,
+            t.status      AS task_status,
+            b.github_login AS recommended_by_login,
+            b.display_name AS recommended_by_name
+       FROM lifecycle_task_recommendations r
+       JOIN tasks t    ON t.id = r.task_id
+       JOIN builders b ON b.id = r.recommended_by
+      WHERE r.recommended_to = $1 AND r.status = 'open'
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT $2`,
+    [builderId, capRows(limit)]
+  );
+  return rows;
+}
+
+// The sender's read: what I have recommended, and what became of it. NOT filtered
+// to open — the criterion asks that a recommendation and its author stay readable
+// afterwards, so a declined row is still here, still naming who declined it.
+async function listFromSender({ builderId, status = null, 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,
+            t.title       AS task_title,
+            t.status      AS task_status,
+            b.github_login AS recommended_to_login,
+            b.display_name AS recommended_to_name
+       FROM lifecycle_task_recommendations r
+       JOIN tasks t    ON t.id = r.task_id
+       JOIN builders b ON b.id = r.recommended_to
+      WHERE r.recommended_by = $1 AND ($2::text IS NULL OR r.status = $2)
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT $3`,
+    [builderId, status, capRows(limit)]
+  );
+  return rows;
+}
+
+// "Who recommended this task, and why" — the per-task audit read, and the direct
+// answer to the criterion's "the recommendation and its author are readable
+// afterwards". Every status, oldest-relevant-first ordering aside, because the
+// history is the point: a declined recommendation still records that someone
+// thought this person should see this task.
+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,
+            sender.github_login    AS recommended_by_login,
+            sender.display_name    AS recommended_by_name,
+            recipient.github_login AS recommended_to_login,
+            recipient.display_name AS recommended_to_name
+       FROM lifecycle_task_recommendations r
+       JOIN builders sender    ON sender.id    = r.recommended_by
+       JOIN builders recipient ON recipient.id = r.recommended_to
+      WHERE r.task_id = $1
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT $2`,
+    [taskId, capRows(limit)]
+  );
+  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.
+//
+// Ownership is enforced in the WHERE, not by rank, and ONE refusal covers all
+// three miss cases (absent, not addressed to you, already settled) so a caller
+// cannot enumerate existing ids by reading which one it was — the same lesson
+// help-requests learned from its own grader round.
+async function declineRecommendation({ id, builderId }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_task_recommendations
+        SET status = 'declined', updated_at = now()
+      WHERE id = $1 AND recommended_to = $2 AND status = 'open'
+     RETURNING ${COLS}`,
+    [id, builderId]
+  );
+  return rows[0] || null;
+}
+
+// The sender takes it back. Same shape, other party, same silence about it.
+async function withdrawRecommendation({ id, builderId }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_task_recommendations
+        SET status = 'withdrawn', updated_at = now()
+      WHERE id = $1 AND recommended_by = $2 AND status = 'open'
+     RETURNING ${COLS}`,
+    [id, builderId]
+  );
+  return rows[0] || null;
+}
+
+// The needs-feed read: how many open recommendations are waiting on this builder.
+// A COUNT rather than the rows, for the same reason countOpenForBuilder is a count
+// in help-requests — /me runs on every session open and should not carry bodies it
+// will not render.
+async function countOpenForRecipient(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int AS n
+       FROM lifecycle_task_recommendations
+      WHERE recommended_to = $1 AND status = 'open'`,
+    [builderId]
+  );
+  return rows[0] ? rows[0].n : 0;
+}
+
+module.exports = {
+  MAX_REASON, MAX_ROWS, capRows,
+  validateRecommendation,
+  builderExists, taskExists,
+  createRecommendation,
+  listForRecipient, listFromSender, listForTask,
+  declineRecommendation, withdrawRecommendation,
+  countOpenForRecipient,
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.358",
+  "version": "1.19.359",
   "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/bongos/routes/me.js

@@ -84,6 +84,7 @@ module.exports = function buildMeRouter() {
       builder, activeClaims, estVsActual, unlocked, lockedWithProgress, streakInfo,
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, boxConnected, cliAuthed,
       behaviorPrefs, geminiKeyRow, needsRebaseTasks, foundingBuilder, helpRequestCount,
+      taskRecommendationCount,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -160,6 +161,16 @@ module.exports = function buildMeRouter() {
           return await lifecycle.openHelpRequestsFor(req.builder.id);
         } catch (_) { return 0; }
       })(),
+      // task 1003173 (C03): open task recommendations waiting on this builder.
+      // Same port, same fan-out slot, same fail-open posture as the help-request
+      // count above — a collab read must never be able to break a profile.
+      (async () => {
+        try {
+          const lifecycle = lc();
+          if (!lifecycle || !lifecycle.openTaskRecommendationsFor) return 0;
+          return await lifecycle.openTaskRecommendationsFor(req.builder.id);
+        } catch (_) { return 0; }
+      })(),
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -301,6 +312,10 @@ module.exports = function buildMeRouter() {
         // module (ADR 0093); undefined when lifecycle is off, which the need reads
         // as "nothing asked".
         openHelpRequests: helpRequestCount,
+        // task 1003173 (C03, goal 1000075): open task recommendations waiting on
+        // this builder, read through the same `lifecycle` port so core never
+        // imports the module (ADR 0093).
+        openTaskRecommendations: taskRecommendationCount,
       }) : [],
     };
     // Module→core contribution seam (BV1.R42, ADR 0083). Let each enabled module

package/src/module-api.js

@@ -1146,8 +1146,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.356 with no explicit bump. run 32871335939. (task 1002620)
 //   1.19.358 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.357 with no explicit bump. run 32872551850. (task 1002620)
+//   1.19.359 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.358 with no explicit bump. run 32877754251. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.358'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.359'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');