@bongos/core 1.19.359 → 1.19.361

package/modules/lifecycle/closeness.js

@@ -0,0 +1,363 @@
+// modules/lifecycle/closeness.js — how close two builders are, and WHY
+// (task 1003174 / C04, goal 1000075; criterion collab-closeness-consented,
+// ADR 0187 §2).
+//
+// THE DECISION. Closeness is a WEIGHTED BLEND — co-claims, co-build sessions,
+// goals shipped together, and comms/mentions once C06 mirrors chat in — not a
+// single signal. The owner took the blend knowing its risk, and attached two
+// conditions that are part of the deliverable rather than follow-ups:
+//
+//   1. THE WEIGHTS ARE DATA. They live in ./closeness-weights.json and are served
+//      verbatim by the route, so the model can be reviewed and changed without a
+//      code-archaeology dig. Nothing in this file hard-codes a weight.
+//
+//   2. "WHY AM I CLOSE TO THEM" IS ANSWERABLE. Every score carries its own
+//      breakdown: per signal, the raw count, what it was divided by, its weight,
+//      and what it contributed. A number that ranks real colleagues and cannot say
+//      what it is made of becomes unfair with nothing to point at, which is
+//      exactly what was raised when the blend was chosen.
+//
+// AN UNAVAILABLE SIGNAL IS NOT A ZERO. comms_mention cannot be measured until the
+// C06 mirror exists. Scoring it as zero would depress every pair identically AND
+// make the explanation say "you never talk", which is not what is true — what is
+// true is that nothing here can see whether you talk. So unavailable signals are
+// dropped and the remaining weights are renormalised, and the breakdown names what
+// was excluded and why.
+//
+// CONSENT. ADR 0171's posture is fail-closed account state with the hide flag
+// enforced in the READ path (task 1002277) — a builder who hid their profile must
+// not reappear as a node in someone else's graph. This file routes EVERY graph
+// read through one gate, `applyConsent`, rather than filtering at each call site,
+// so C05 (task 1003175, "consent is the read path, not a filter bolted on after")
+// has a single structural place to make it so. The gate FAILS CLOSED on error:
+// a consent read that throws drops the graph to empty rather than serving it.
+//
+// A KNOWN PERFORMANCE GAP, measured rather than assumed. The signal joins key on
+// tasks.goal_id (NO index), claims.builder_id and claims.task_id (indexed only
+// partially, on ACTIVE claims — closeness reads history) and tasks.shipped_by
+// (partial too). At today's size that is fine; it scales with total table size
+// rather than goal size. The indexes belong in a core_ migration, not here — a
+// module migration may only touch its own lifecycle_ tables (ADR 0083 §5), and
+// the fitness check enforces it. Filed with the SQL as task 1003268.
+//
+// Reaches core only through the doorway (ADR 0083). The core tables it reads
+// (claims, tasks, session_logs, builders) are read-only here.
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+const WEIGHTS = require('./closeness-weights.json');
+
+const MAX_ROWS = 100;
+// Signals are counted over a trailing window: a collaboration from two years ago
+// is history, not closeness. Long enough that a slow-moving goal still counts.
+const WINDOW_DAYS = 365;
+
+function capRows(n) {
+  const v = Number(n);
+  return Number.isInteger(v) && v > 0 && v <= MAX_ROWS ? v : MAX_ROWS;
+}
+
+// ---------------------------------------------------------------------------
+// The model
+// ---------------------------------------------------------------------------
+
+// The weights file, as loaded. Exposed so the route can serve it verbatim — the
+// audit surface must show the SAME data the scorer used, not a restatement.
+function weightsModel() { return WEIGHTS; }
+
+function availableSignals() { return WEIGHTS.signals.filter((s) => s.available === true); }
+function unavailableSignals() { return WEIGHTS.signals.filter((s) => s.available !== true); }
+
+// PURE. counts -> { score, breakdown, excluded }.
+//
+// `counts` is { [signalKey]: number }. Missing keys are 0 — a signal that IS
+// measurable and simply did not happen is a real zero, unlike an unavailable one.
+//
+// Returns:
+//   score      — 0..1, the weighted sum over AVAILABLE signals with weights
+//                renormalised to sum to 1 across that subset.
+//   breakdown  — one row per available signal: the count, the saturation it was
+//                measured against, the clamped value, the effective (renormalised)
+//                weight, and the contribution to the score. This IS the answer to
+//                "why am I close to them".
+//   excluded   — the unavailable signals, each with the reason, so a surface can
+//                say what the number could not see.
+function scoreCloseness(counts = {}) {
+  const avail = availableSignals();
+  const totalWeight = avail.reduce((sum, s) => sum + (Number(s.weight) || 0), 0);
+
+  // No available signal, or weights that sum to nothing, means there is no model
+  // to score with. Answer 0 with an empty breakdown rather than dividing by zero
+  // and returning NaN dressed up as a closeness.
+  if (!avail.length || totalWeight <= 0) {
+    return { score: 0, breakdown: [], excluded: unavailableSignals().map(excludedRow), scorable: false };
+  }
+
+  // Contributions are computed at full precision and the TOTAL is rounded once.
+  // Summing already-rounded rows instead lost a ten-thousandth per signal, so a
+  // pair at full on every available signal scored 0.9999 rather than 1 — a score
+  // that can never reach its own maximum is a small lie the explanation would
+  // then have to carry.
+  let raw = 0;
+  const breakdown = avail.map((s) => {
+    const count = Math.max(0, Number(counts[s.key]) || 0);
+    const saturation = Math.max(1, Number(s.saturation) || 1);
+    const value = Math.min(count / saturation, 1);
+    const effectiveWeight = (Number(s.weight) || 0) / totalWeight;
+    raw += value * effectiveWeight;
+    return {
+      key: s.key,
+      label: s.label,
+      description: s.description,
+      count,
+      saturation,
+      value: round4(value),
+      declared_weight: Number(s.weight) || 0,
+      effective_weight: round4(effectiveWeight),
+      contribution: round4(value * effectiveWeight),
+    };
+  });
+
+  const score = round4(raw);
+  return { score, breakdown, excluded: unavailableSignals().map(excludedRow), scorable: true };
+}
+
+function excludedRow(s) {
+  return {
+    key: s.key,
+    label: s.label,
+    declared_weight: Number(s.weight) || 0,
+    reason: 'not_measurable_yet',
+    // Why this matters, in the payload rather than only in a comment: a surface
+    // that shows a score must be able to say what the score could not see.
+    explanation: `This signal cannot be measured yet, so it was excluded and its weight redistributed across the others — it was NOT counted as zero.${s.blocked_by ? ` Waiting on ${s.blocked_by}.` : ''}`,
+  };
+}
+
+function round4(n) { return Math.round(n * 10000) / 10000; }
+
+// A one-sentence rendering of a breakdown, for a surface with no room for a table.
+// PURE, and built from the SAME rows the score came from, so the sentence cannot
+// drift from the arithmetic.
+function explainInWords(scored) {
+  if (!scored || !scored.scorable) return 'There is no closeness model available to score this pair.';
+  const contributing = scored.breakdown.filter((r) => r.count > 0);
+  if (!contributing.length) return 'Nothing measurable has happened between you yet.';
+  const parts = contributing
+    .slice()
+    .sort((a, b) => b.contribution - a.contribution)
+    .map((r) => `${r.label.toLowerCase()} (${r.count})`);
+  const tail = scored.excluded.length
+    ? ` Not counted: ${scored.excluded.map((e) => e.label.toLowerCase()).join(', ')} — not measurable yet.`
+    : '';
+  return `Mostly ${parts.join(', then ')}.${tail}`;
+}
+
+// ---------------------------------------------------------------------------
+// The signals, read from the live tables
+// ---------------------------------------------------------------------------
+//
+// Each read answers ONE question for one builder, and returns a Map of
+// otherBuilderId -> count. They are separate queries rather than one join so a
+// signal can be added, removed, or reweighted without touching the others — the
+// same reason the weights are data.
+//
+// EACH TAKES AN OPTIONAL `otherId`, which narrows the same query to a single pair
+// rather than the whole graph. That is deliberately a PARAMETER and not a second
+// set of pair-shaped functions: two hand-written definitions of "what a co-claim
+// is" would drift, and the one that drifted would be the one nobody reads. The
+// graph read passes null; closenessBetween passes the id.
+
+// co_claim — claims by the two builders on tasks in the SAME GOAL whose active
+// windows overlapped. `released_at IS NULL` means still open, so COALESCE to now().
+async function coClaimCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT other.builder_id AS other_id, count(DISTINCT t_mine.goal_id)::int AS n
+       FROM claims mine
+       JOIN tasks  t_mine  ON t_mine.id = mine.task_id AND t_mine.goal_id IS NOT NULL
+       JOIN tasks  t_other ON t_other.goal_id = t_mine.goal_id
+       JOIN claims other   ON other.task_id = t_other.id AND other.builder_id <> $1
+      WHERE mine.builder_id = $1
+        AND ($3::bigint IS NULL OR other.builder_id = $3)
+        AND mine.claimed_at > now() - ($2 || ' days')::interval
+        AND tstzrange(mine.claimed_at,  COALESCE(mine.released_at,  now()))
+         && tstzrange(other.claimed_at, COALESCE(other.released_at, now()))
+      GROUP BY other.builder_id`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+// co_build_session — logged work sessions on tasks in the same goal that overlapped
+// in time. Distinct from co_claim on purpose: a claim can sit open for days, a
+// session is the hours actually spent, so this is the closer measure of presence.
+async function coSessionCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT other.builder_id AS other_id, count(*)::int AS n
+       FROM session_logs mine
+       JOIN tasks t_mine  ON t_mine.id = mine.task_id AND t_mine.goal_id IS NOT NULL
+       JOIN tasks t_other ON t_other.goal_id = t_mine.goal_id
+       JOIN session_logs other ON other.task_id = t_other.id AND other.builder_id <> $1
+      WHERE mine.builder_id = $1
+        AND ($3::bigint IS NULL OR other.builder_id = $3)
+        AND mine.started_at > now() - ($2 || ' days')::interval
+        AND tstzrange(mine.started_at,  mine.ended_at)
+         && tstzrange(other.started_at, other.ended_at)
+      GROUP BY other.builder_id`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+// shipped_together_goal — DISTINCT goals into which both have shipped at least one
+// task. Timing is deliberately ignored: this is the durable record that you both
+// built the same thing, even months apart.
+async function shippedTogetherCounts(builderId, { otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT t_other.shipped_by AS other_id, count(DISTINCT t_mine.goal_id)::int AS n
+       FROM tasks t_mine
+       JOIN tasks t_other ON t_other.goal_id = t_mine.goal_id
+      WHERE t_mine.shipped_by = $1
+        AND t_mine.goal_id IS NOT NULL
+        AND t_mine.shipped_at > now() - ($2 || ' days')::interval
+        AND t_other.shipped_by IS NOT NULL
+        AND t_other.shipped_by <> $1
+        AND ($3::bigint IS NULL OR t_other.shipped_by = $3)
+      GROUP BY t_other.shipped_by`,
+    [builderId, String(WINDOW_DAYS), otherId]
+  );
+  return toCountMap(rows);
+}
+
+function toCountMap(rows) {
+  const m = new Map();
+  for (const r of rows) {
+    if (r.other_id == null) continue;
+    m.set(String(r.other_id), Number(r.n) || 0);
+  }
+  return m;
+}
+
+// ---------------------------------------------------------------------------
+// Consent — ONE gate, fail-closed
+// ---------------------------------------------------------------------------
+//
+// Every graph read passes through here, so C05 has a single structural place to
+// make consent the read path rather than a filter bolted on at each call site.
+//
+// `hiddenIdsFor` is injected: the platform-identity hub owns the hide flag
+// (ADR 0171 D2/D4) and lifecycle must not reach across a module boundary to read
+// it (ADR 0083). The route resolves the port and passes a reader in; where no hub
+// is enabled there is no hub-level hide flag to honour, and NOTHING is suppressed
+// by this mechanism — which is correct, not a hole: on such an instance nobody has
+// been offered the switch. What is NOT tolerated is an ERROR being read as
+// "nobody is hidden", so a throwing reader empties the graph.
+async function applyConsent(entries, hiddenIdsFor) {
+  if (typeof hiddenIdsFor !== 'function') return entries;
+  let hidden;
+  try {
+    hidden = await hiddenIdsFor(entries.map((e) => e.builder_id));
+  } catch (_) {
+    // FAIL CLOSED. An unreadable consent state is not permission.
+    return [];
+  }
+  if (!hidden) return [];                       // ditto: null is not "nobody"
+  const set = hidden instanceof Set ? hidden : new Set((hidden || []).map(String));
+  return entries.filter((e) => !set.has(String(e.builder_id)));
+}
+
+// ---------------------------------------------------------------------------
+// The graph
+// ---------------------------------------------------------------------------
+
+// Everyone this builder has any measurable closeness to, scored and explained,
+// strongest first. `hiddenIdsFor` is the consent gate above.
+// `otherId` narrows every signal query to one pair at the DATABASE, so the pair
+// read does not fetch a hundred rows to keep one. It is threaded through rather
+// than filtered afterwards — see the note above the signal reads.
+async function closenessFor(builderId, { limit = MAX_ROWS, hiddenIdsFor, otherId = null } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  const [coClaim, coSession, shipped] = await Promise.all([
+    coClaimCounts(builderId, { otherId }, { pool: activePool }),
+    coSessionCounts(builderId, { otherId }, { pool: activePool }),
+    shippedTogetherCounts(builderId, { otherId }, { pool: activePool }),
+  ]);
+
+  const ids = new Set([...coClaim.keys(), ...coSession.keys(), ...shipped.keys()]);
+  let entries = [...ids].map((otherId) => {
+    const counts = {
+      co_claim: coClaim.get(otherId) || 0,
+      co_build_session: coSession.get(otherId) || 0,
+      shipped_together_goal: shipped.get(otherId) || 0,
+    };
+    const scored = scoreCloseness(counts);
+    return {
+      builder_id: otherId,
+      score: scored.score,
+      // The explanation travels WITH the score, on every surface, rather than
+      // behind a second call a caller may not make. That is the decision.
+      why: { breakdown: scored.breakdown, excluded: scored.excluded, in_words: explainInWords(scored) },
+    };
+  }).filter((e) => e.score > 0);
+
+  entries = await applyConsent(entries, hiddenIdsFor);
+  entries.sort((a, b) => b.score - a.score || String(a.builder_id).localeCompare(String(b.builder_id)));
+  entries = entries.slice(0, capRows(limit));
+
+  return hydrate(entries, activePool);
+}
+
+// One pair, with the same breakdown the graph carries. Separate from closenessFor
+// so "why am I close to THEM" is answerable directly, without paging a graph.
+async function closenessBetween(builderId, otherId, { hiddenIdsFor } = {}, deps = {}) {
+  const activePool = deps.pool || pool;
+  if (String(builderId) === String(otherId)) return null;
+  // NARROWED AT THE DATABASE, not filtered in memory. This used to call the graph
+  // read and then find() the one row it wanted, which ran three self-joins and a
+  // hydrate over up to a hundred builders to answer a question about one — on
+  // what is likely a per-profile-view route. Passing otherId pushes the narrowing
+  // into the same queries, so there is still exactly one definition of each
+  // signal and the pair read costs a pair.
+  const graph = await closenessFor(builderId, { limit: 1, hiddenIdsFor, otherId }, { pool: activePool });
+  const found = graph.find((e) => String(e.builder_id) === String(otherId));
+  if (found) return found;
+
+  // Not in the graph. That is either "no measurable closeness" or "consent says
+  // no", and this deliberately does not distinguish them: a caller able to tell
+  // the two apart could detect that a specific builder has hidden themselves,
+  // which is the thing the hide flag exists to prevent.
+  return null;
+}
+
+// Attach the names a surface needs. Done once, after scoring and consent, so a
+// suppressed builder's identity is never read at all.
+async function hydrate(entries, activePool) {
+  if (!entries.length) return [];
+  const { rows } = await activePool.query(
+    `SELECT id, github_login, display_name, avatar_url
+       FROM builders WHERE id = ANY($1::bigint[])`,
+    [entries.map((e) => e.builder_id)]
+  );
+  const byId = new Map(rows.map((r) => [String(r.id), r]));
+  return entries.map((e) => {
+    const b = byId.get(String(e.builder_id)) || {};
+    return {
+      ...e,
+      github_login: b.github_login || null,
+      display_name: b.display_name || null,
+      avatar_url: b.avatar_url || null,
+    };
+  });
+}
+
+module.exports = {
+  WINDOW_DAYS, MAX_ROWS, capRows,
+  weightsModel, availableSignals, unavailableSignals,
+  scoreCloseness, explainInWords,
+  coClaimCounts, coSessionCounts, shippedTogetherCounts,
+  applyConsent, closenessFor, closenessBetween,
+};

package/modules/lifecycle/module.json

@@ -20,6 +20,7 @@
       "lifecycle",
       "help-requests",
       "recommendations",
+      "closeness",
       "visuals"
     ],
     "pollers": [

package/modules/lifecycle/routes/claims.js

@@ -1,3 +1,25 @@
+// modules/lifecycle/routes/claims.js — locking a task to one builder's session,
+// and letting go of it again (ADR 0095 backfill).
+//
+// WHY. The claim is what makes PARALLEL builder sessions safe. Several agents work
+// this repo at once; without an atomic lock two of them pick the same task, write
+// the same files, and one loses the work at merge. `POST /claims` is that lock, and
+// it must stay atomic — it refuses with a typed reason rather than racing: already
+// claimed, task not ready, touches conflict, or 409 `DEPS_NOT_SHIPPED` when the
+// dependency graph has not opened the task yet.
+//
+// Every claim ends deliberately, never by drifting: `/claims/:id/resolve` carries
+// both the ship path (credits land) and the release path (no credits, task returns
+// to `ready`). `release-on-behalf` is the privileged escape hatch for a claim whose
+// builder is gone — a crashed session must not strand a task forever.
+//
+// The batch routes serve the multi-claim session flow; `batch/validate` is a DRY
+// RUN, so a builder can see which of several tasks would be refused before locking
+// any of them.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 // Intra-module + the published doorway — a module never requires a core internal.
 const api = require('../../../src/module-api');

package/modules/lifecycle/routes/closeness.js

@@ -0,0 +1,118 @@
+// modules/lifecycle/routes/closeness.js — the closeness graph, and the surface
+// that can explain it (task 1003174 / C04, goal 1000075; criterion
+// collab-closeness-consented, ADR 0187 §2).
+//
+// THREE ROUTES, AND ONE OF THEM IS THE POINT:
+//   GET /closeness/weights           — the scoring model, served VERBATIM from the
+//                                      data file. The owner's condition was that
+//                                      the weights be reviewable without a code
+//                                      dig; this is where they are reviewed.
+//   GET /closeness/for-me            — my graph. Every entry carries its own `why`.
+//   GET /closeness/with/:builderId   — one pair, same breakdown, asked directly.
+//
+// THE EXPLANATION IS NOT A SEPARATE ENDPOINT, deliberately. "Why am I close to
+// them" must be answerable on ANY surface that shows closeness, and a second call
+// a caller may simply not make is how a score ends up on a page with nothing to
+// point at. So `why` rides in the same payload as the number, always.
+//
+// CONSENT is resolved here and passed INTO the read as a gate (see
+// closeness.js applyConsent), never applied to the output afterwards. The hub owns
+// the hide flag (ADR 0171 D2/D4) and lifecycle must not read another module's
+// table (ADR 0083), so the port is resolved optionally and a reader is handed down.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const closeness = require('../closeness');
+
+const { asyncHandler, parseId } = api;
+
+// Build the consent reader the graph gates on, or null where no hub is enabled.
+//
+// NULL IS NOT A HOLE. Where the platform-identity module is off there is no
+// hub-level hide flag to honour, because nobody on that instance has been offered
+// the switch — suppressing everyone would not be consent, it would be an outage.
+// What must never happen is an ERROR being read as "nobody is hidden", and that is
+// why the reader THROWS rather than swallowing: applyConsent catches and empties
+// the graph, which is the fail-closed direction ADR 0171 asks for.
+function consentReader(pool) {
+  const hub = api.resolveOptional('platform-identity.hub');
+  if (!hub || typeof hub.hiddenGithubIds !== 'function') return null;
+
+  return async (builderIds) => {
+    if (!builderIds || !builderIds.length) return new Set();
+    // builder_id -> github_id, from the CORE builders table (a read-only core
+    // read, which the module contract permits; the hub keys consent by github_id
+    // and cannot see our builder ids).
+    const { rows } = await pool.query(
+      'SELECT id, github_id FROM builders WHERE id = ANY($1::bigint[])',
+      [builderIds]
+    );
+    const githubIdByBuilder = new Map(rows.map((r) => [String(r.id), r.github_id]));
+    const hiddenGithub = await hub.hiddenGithubIds([...githubIdByBuilder.values()].filter((g) => g != null));
+    const hiddenSet = hiddenGithub instanceof Set ? hiddenGithub : new Set((hiddenGithub || []).map(String));
+    const hidden = new Set();
+    for (const [builderId, githubId] of githubIdByBuilder) {
+      if (githubId != null && hiddenSet.has(String(githubId))) hidden.add(builderId);
+    }
+    return hidden;
+  };
+}
+
+module.exports = function buildClosenessRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — the MODEL is not private, and publishing it is the whole
+  // point of the weights being data. It describes how the system scores people;
+  // a builder ranked by it is entitled to read it.
+  router.get('/closeness/weights', api.requireBuilder, asyncHandler('GET /closeness/weights', async (req, res) => {
+    // Served verbatim from the file the scorer loads, NOT restated here — an
+    // audit surface that paraphrases the model can drift from it, which would
+    // make it worse than nothing.
+    return res.json({
+      weights: closeness.weightsModel(),
+      window_days: closeness.WINDOW_DAYS,
+      // Named explicitly so a reader does not have to infer the renormalisation
+      // rule from the numbers.
+      note: 'Signals marked available:false are EXCLUDED and their weight is redistributed across the rest — they are never counted as zero. Each score carries the same breakdown this model produces.',
+    });
+  }, { errorCode: 'closeness_weights_failed' }));
+
+  // rank: any-builder, and OWN-SCOPED — your own graph, never someone else's.
+  // Reading another builder's graph would expose who THEY are close to, which is
+  // a fact about third parties they did not consent to share.
+  router.get('/closeness/for-me', api.requireBuilder, asyncHandler('GET /closeness/for-me', async (req, res) => {
+    const rows = await closeness.closenessFor(req.builder.id, {
+      hiddenIdsFor: consentReader(api.pool),
+    });
+    return res.json({ closeness: rows, count: rows.length });
+  }, { errorCode: 'closeness_failed' }));
+
+  // One pair — "why am I close to THEM", asked directly rather than by paging the
+  // graph. Always relative to the CALLER: the pair is (you, them).
+  //
+  // rank: any-builder.
+  router.get('/closeness/with/:builderId', api.requireBuilder, asyncHandler('GET /closeness/with/:builderId', async (req, res) => {
+    const otherId = parseId(req, res, { param: 'builderId', code: 'bad_builder_id', positiveInt: true });
+    if (otherId === null) return;
+
+    const pair = await closeness.closenessBetween(req.builder.id, otherId, {
+      hiddenIdsFor: consentReader(api.pool),
+    });
+    if (!pair) {
+      // ONE answer for "nothing measurable happened" AND "consent says no".
+      // Distinguishing them would let a caller detect that a specific builder has
+      // hidden themselves — the exact thing the hide flag exists to prevent.
+      return res.json({
+        closeness: null,
+        why: { in_words: 'Nothing measurable connects you two.', breakdown: [], excluded: [] },
+      });
+    }
+    return res.json({ closeness: pair, why: pair.why });
+  }, { errorCode: 'closeness_failed' }));
+
+  return router;
+};

package/modules/lifecycle/routes/tasks.js

@@ -1,3 +1,25 @@
+// modules/lifecycle/routes/tasks.js — the HTTP surface of the task itself: what
+// work exists, what is claimable, and how a task moves through its statuses
+// (ADR 0095 backfill).
+//
+// WHY. A task is the unit the whole methodology rests on — "every change is backed
+// by a claimed task" only means something if the task's shape and its status
+// transitions are enforced in ONE place. This is that place. It owns the
+// backlog→ready→active→completed→confirmed→shipped walk (`/promote`, `/demote`,
+// `/ship`, `/confirm`, `/abandon`), the DEPENDENCY graph that gates claimability,
+// and the done-when criteria a version's progress rolls up from.
+//
+// Two invariants that are easy to break from here:
+//   - `/tasks/claimable` computes parallel-safety against everyone's ACTIVE claims.
+//     It is what makes concurrent builder sessions safe; a filter loosened here
+//     hands two builders the same work.
+//   - Dependencies are load-bearing; the `V##.R##` rank prefix is decorative.
+//     Shipping a task auto-promotes its now-unblocked dependents backlog→ready
+//     (ADR 0015), so the graph — not a human — decides what opens up next.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 const fs = require('node:fs');
 const os = require('node:os');

package/modules/lifecycle/routes/versions.js

@@ -1,3 +1,21 @@
+// modules/lifecycle/routes/versions.js — the version as a container of scope, and
+// the question "is it done yet?" (ADR 0095 backfill).
+//
+// WHY. The project ships version-by-version, so a version is not a label — it is
+// the unit scope is committed to and closed against. These routes answer the two
+// things anyone asks about one: what is IN it (`GET /versions`, `POST /versions`)
+// and how far along it is (`/progress`, `/:id/progress` — the roll-up `/status`
+// renders: each done-when criterion → its gating tasks → what remains, ADR 0025).
+//
+// `/versions/close-suggestions` exists because a version that is *actually*
+// finished rarely announces itself — work drifts, criteria get met out of order,
+// and a version can sit open long after its last real task shipped. Delegated to
+// `../version-close.js`, it surfaces the candidates so closing is a decision
+// someone makes rather than one nobody remembers to make.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; never a core internal, never another module.
+
 const express = require('express');
 // Intra-module + the published doorway — a module never requires a core internal.
 const api = require('../../../src/module-api');

package/modules/memory/routes/learnings.js

@@ -1,3 +1,24 @@
+// modules/memory/routes/learnings.js — GET/POST /learnings: pay for a discovery
+// once (ADR 0095 backfill).
+//
+// WHY. A hard-won diagnosis — the kind that costs half an hour of a session — is
+// worth exactly nothing if the next agent has to rediscover it. Learnings are the
+// short-form half of that cure (the long-form half is a recipe under
+// `docs/recipes/`): one durable, searchable rule per finding, captured via
+// `node scripts/gds/learning-capture.js` and surfaced again through `/recall`.
+//
+// Capture is open to any signed-in builder on purpose. The agent that just paid
+// for the discovery is the one holding it, and a rank gate on writing down what
+// you learned would simply mean it never gets written down.
+//
+// PRIVACY: bodies pass through `stripPrivate()` before persisting, so anything
+// fenced in `<private>…</private>` never enters the store or the recall index
+// (ADR 0095 C4). The fence is fail-closed — an unbalanced marker strips to the end
+// rather than leaking what it was meant to hide.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway
+// `src/module-api.js`; `../learnings` is an intra-module sibling.
+
 const express = require('express');
 // Carved into modules/memory/ (BV1.R72 / ADR 0091 §2): auth + the shared request
 // validators (validateOrRespond/LIMITS) via the doorway; the learnings lib is an

package/modules/platform-identity/platform-identity.js

@@ -629,6 +629,33 @@ async function getPublicProfileExtras(githubId, { pool = defaultPool } = {}) {
   return getRollupForBuilder(githubId, { pool });
 }
 
+// The CONSENT read, in bulk (task 1003174 / C04, goal 1000075). Answers exactly
+// one question — "which of these accounts have HIDDEN themselves?" — and returns
+// a Set of the github_ids that have.
+//
+// WHY NOT REUSE getPublicProfileExtras. It returns null for a hidden account AND
+// for one that is merely absent or still provisional, because for a profile
+// rollup those cases are identical: there is nothing to show. For a consent gate
+// they are opposites. A builder who has never federated at the hub has not opted
+// OUT of anything — nobody offered them the switch — so treating their missing
+// row as "hidden" would empty the closeness graph of every builder on a fresh
+// instance and call it consent. HIDDEN means a row exists and hide_stats is true.
+//
+// FAIL-CLOSED is the CALLER's job here, and deliberately so: this function
+// THROWS on a bad read rather than returning an empty set, because an empty set
+// means "nobody is hidden" and a database error must never be able to say that.
+// modules/lifecycle/closeness.js applyConsent catches and empties the graph.
+async function hiddenGithubIds(githubIds, { pool = defaultPool } = {}) {
+  const ids = (Array.isArray(githubIds) ? githubIds : []).filter(isNumericGithubId).map(String);
+  if (!ids.length) return new Set();
+  const { rows } = await pool.query(
+    `SELECT github_id FROM platform_identity_accounts
+      WHERE github_id = ANY($1::bigint[]) AND hide_stats = true`,
+    [ids],
+  );
+  return new Set(rows.map((r) => String(r.github_id)));
+}
+
 // The SELF read (ADR 0171 D2's first narrow side door): a builder inspects their
 // own numbers in Settings regardless of profile_state/hide_stats. Callers MUST
 // key this by the authenticated session's github_id, never a caller-named one.
@@ -1069,6 +1096,7 @@ async function sweepExpiredCodes({ pool = defaultPool } = {}) {
 }
 
 module.exports = {
+  hiddenGithubIds,
   DEFAULT_CODE_TTL_MS,
   // pure helpers
   sha256hex,

package/modules/platform-identity/routes/sso.js

@@ -110,6 +110,10 @@ function registerSeams() {
     api.registerProvider('platform-identity.hub', {
       getPublicProfileExtras: (githubId) => pi.getPublicProfileExtras(githubId, { pool }),
       getOwnProfileExtras: (githubId) => pi.getOwnProfileExtras(githubId, { pool }),
+      // task 1003174 (C04): the bulk consent read the closeness graph gates on.
+      // THROWS on a bad read by design — an empty set means "nobody is hidden",
+      // which a database error must never be allowed to say.
+      hiddenGithubIds: (githubIds) => pi.hiddenGithubIds(githubIds, { pool }),
     });
   }
 }

package/package-lock.json

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