@bongos/core 1.19.358 → 1.19.360

package/tests/closeness.mjs

@@ -0,0 +1,324 @@
+// tests/closeness.mjs — closeness is a weighted blend that can explain itself
+// (task 1003174 / C04, goal 1000075; criterion collab-closeness-consented,
+// ADR 0187 §2).
+//
+// The criterion names three testable things, and the owner attached two of them
+// as conditions of taking the blend at all rather than as follow-ups:
+//   1. the weights are inspectable DATA;
+//   2. the surface can state the contributing signals for a given pair;
+//   3. a hidden builder appears in no graph.
+//
+// The scorer is pure, so 1 and 2 are driven with real inputs rather than asserted
+// over source. 3 is a consent property of the read, and is driven through the
+// real applyConsent gate with stub readers — including the failure modes, which
+// are the ones that actually matter.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const closeness = require(path.join(ROOT, 'modules', 'lifecycle', 'closeness.js'));
+const WEIGHTS = require(path.join(ROOT, 'modules', 'lifecycle', 'closeness-weights.json'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'closeness.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'closeness.js');
+
+// ── 1. THE WEIGHTS ARE DATA ─────────────────────────────────────────────────
+
+test('THE CONDITION: the weights live in a data file, not in the scorer', () => {
+  // "The weights are DATA, not constants buried in a function, so they can be
+  // reviewed and changed without a code archaeology dig." A numeric weight
+  // literal in the scorer would be exactly the dig.
+  const code = SRC.replace(/^\s*\/\/.*$/gm, '');
+  assert.match(code, /require\('\.\/closeness-weights\.json'\)/);
+  for (const s of WEIGHTS.signals) {
+    assert.ok(!new RegExp(`['"\`]${s.key}['"\`]\\s*:\\s*0?\\.\\d`).test(code),
+      `${s.key}'s weight must not be written into the scorer`);
+  }
+});
+
+test('every signal declares the four things a reviewer needs', () => {
+  // A weight with no label, no description and no saturation is not reviewable —
+  // it is a magic number that happens to live in a .json file.
+  for (const s of WEIGHTS.signals) {
+    assert.ok(s.key && s.label && s.description, `${s.key} is described in words`);
+    assert.equal(typeof s.weight, 'number', `${s.key} has a numeric weight`);
+    assert.ok(s.saturation > 0, `${s.key} declares what "full" means`);
+    assert.equal(typeof s.available, 'boolean', `${s.key} declares whether it can be measured`);
+  }
+});
+
+test('the declared weights sum to 1 across ALL signals', () => {
+  const total = WEIGHTS.signals.reduce((n, s) => n + s.weight, 0);
+  assert.ok(Math.abs(total - 1) < 1e-9, `weights sum to ${total}, not 1`);
+});
+
+test('the route serves the model VERBATIM rather than restating it', () => {
+  // An audit surface that paraphrases the model can drift from it, which makes
+  // it worse than nothing.
+  assert.match(ROUTES, /weights: closeness\.weightsModel\(\)/);
+});
+
+// ── 2. THE SCORE CAN EXPLAIN ITSELF ─────────────────────────────────────────
+
+test('THE CONDITION: every score carries a per-signal breakdown', () => {
+  // "Why am I close to them MUST be answerable on any surface that shows
+  // closeness." The breakdown is that answer, and it must account for the whole
+  // number: the contributions sum to the score.
+  const s = closeness.scoreCloseness({ co_claim: 2, co_build_session: 1, shipped_together_goal: 3 });
+  assert.ok(s.score > 0);
+  assert.equal(s.breakdown.length, closeness.availableSignals().length);
+  const summed = s.breakdown.reduce((n, r) => n + r.contribution, 0);
+  assert.ok(Math.abs(summed - s.score) < 1e-3, `breakdown sums to ${summed}, score is ${s.score}`);
+});
+
+test('a breakdown row shows the arithmetic, not just a verdict', () => {
+  const s = closeness.scoreCloseness({ co_claim: 2 });
+  const row = s.breakdown.find((r) => r.key === 'co_claim');
+  assert.equal(row.count, 2, 'the raw count');
+  assert.ok(row.saturation > 0, 'what it was measured against');
+  assert.ok(row.effective_weight > 0, 'the weight actually applied');
+  assert.ok(row.contribution > 0, 'and what it added');
+  assert.ok(row.description.length > 20, 'in words, too');
+});
+
+test('the explanation travels WITH the score, not behind a second call', () => {
+  // A separate endpoint is how a number ends up on a page with nothing to point
+  // at, because a caller may simply not make the second call.
+  assert.match(SRC, /why: \{ breakdown: scored\.breakdown, excluded: scored\.excluded, in_words: explainInWords\(scored\) \}/);
+  assert.ok(!/\/closeness\/[^\s'"]*why/.test(ROUTES), 'there is no separate why endpoint');
+});
+
+test('a signal saturates — no single runaway count can dominate', () => {
+  const sat = WEIGHTS.signals.find((s) => s.key === 'co_claim').saturation;
+  const atFull = closeness.scoreCloseness({ co_claim: sat });
+  const wayOver = closeness.scoreCloseness({ co_claim: sat * 100 });
+  assert.equal(atFull.score, wayOver.score, 'past saturation the signal stops growing');
+  assert.equal(wayOver.breakdown.find((r) => r.key === 'co_claim').value, 1);
+});
+
+test('no measurable history scores zero and SAYS so', () => {
+  const s = closeness.scoreCloseness({});
+  assert.equal(s.score, 0);
+  assert.match(closeness.explainInWords(s), /Nothing measurable has happened/);
+});
+
+test('the words name the strongest signal first', () => {
+  const s = closeness.scoreCloseness({ co_claim: 1, shipped_together_goal: 3 });
+  const words = closeness.explainInWords(s);
+  const strongest = s.breakdown.slice().sort((a, b) => b.contribution - a.contribution)[0];
+  assert.ok(words.toLowerCase().indexOf(strongest.label.toLowerCase()) >= 0);
+  assert.match(words, /^Mostly /);
+});
+
+// ── AN UNAVAILABLE SIGNAL IS NOT A ZERO ─────────────────────────────────────
+
+test('THE HONESTY RULE: an unmeasurable signal is excluded, not scored as zero', () => {
+  // comms_mention cannot be measured until C06 mirrors chat in. Scoring it 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 can see it.
+  const unavailable = closeness.unavailableSignals();
+  assert.ok(unavailable.length > 0, 'this test is about a real case, not a hypothetical');
+  const s = closeness.scoreCloseness({ co_claim: 99, co_build_session: 99, shipped_together_goal: 99 });
+  assert.ok(Math.abs(s.score - 1) < 1e-9,
+    `every AVAILABLE signal at full must reach 1.0, got ${s.score} — an excluded signal is holding weight`);
+});
+
+test('the excluded signals are NAMED, with the reason, in every payload', () => {
+  const s = closeness.scoreCloseness({ co_claim: 1 });
+  assert.ok(s.excluded.length > 0);
+  for (const e of s.excluded) {
+    assert.equal(e.reason, 'not_measurable_yet');
+    assert.match(e.explanation, /NOT counted as zero/);
+    assert.ok(e.declared_weight > 0, 'and what it would have been worth');
+  }
+  assert.match(closeness.explainInWords(s), /Not counted:/);
+});
+
+test('the unavailable signal points at the task that unblocks it', () => {
+  const comms = WEIGHTS.signals.find((s) => s.key === 'comms_mention');
+  assert.equal(comms.available, false);
+  assert.match(comms.blocked_by, /1003176/);
+});
+
+test('effective weights always sum to 1 over the available subset', () => {
+  const s = closeness.scoreCloseness({});
+  const summed = s.breakdown.reduce((n, r) => n + r.effective_weight, 0);
+  assert.ok(Math.abs(summed - 1) < 1e-3, `effective weights sum to ${summed}`);
+});
+
+// ── 3. CONSENT: a hidden builder appears in NO graph ────────────────────────
+
+const entries = () => [
+  { builder_id: '10', score: 0.9 },
+  { builder_id: '20', score: 0.5 },
+  { builder_id: '30', score: 0.1 },
+];
+
+test('THE CONSENT RULE: a hidden builder is removed from the graph', () => {
+  return closeness.applyConsent(entries(), async () => new Set(['20']))
+    .then((out) => assert.deepEqual(out.map((e) => e.builder_id), ['10', '30']));
+});
+
+test('FAIL CLOSED: a consent read that THROWS empties the graph', async () => {
+  // An unreadable consent state is not permission. This is the direction that
+  // matters: the opposite default would serve a hidden builder on any hiccup.
+  const out = await closeness.applyConsent(entries(), async () => { throw new Error('hub down'); });
+  assert.deepEqual(out, []);
+});
+
+test('FAIL CLOSED: a consent read returning null empties the graph too', async () => {
+  // null is not "nobody is hidden".
+  const out = await closeness.applyConsent(entries(), async () => null);
+  assert.deepEqual(out, []);
+});
+
+test('no consent reader at all leaves the graph intact — that is not a hole', async () => {
+  // Where the hub 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.
+  const out = await closeness.applyConsent(entries(), null);
+  assert.equal(out.length, 3);
+});
+
+test('consent is ONE gate the reads pass through, not a filter at each call site', () => {
+  // C05 (task 1003175) is "consent is the read path, not a filter bolted on
+  // after" — it needs a single structural place, and this is it.
+  assert.equal((SRC.match(/await applyConsent\(/g) || []).length, 1,
+    'exactly one call site applies consent');
+  assert.match(SRC, /entries = await applyConsent\(entries, hiddenIdsFor\);/);
+});
+
+test('a suppressed builder\'s identity is never even read', () => {
+  // hydrate() runs AFTER applyConsent, so a hidden builder\'s name and avatar are
+  // not fetched at all — not fetched and then dropped.
+  const fn = SRC.slice(SRC.indexOf('async function closenessFor'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.ok(body.indexOf('applyConsent') < body.indexOf('return hydrate'),
+    'consent is applied before hydration');
+});
+
+test('the pair read cannot be used to detect that someone hid themselves', () => {
+  // "No measurable closeness" and "consent says no" MUST be indistinguishable —
+  // a caller able to tell them apart has found the hide flag through a side door.
+  const fn = SRC.slice(SRC.indexOf('async function closenessBetween'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  // Scope to the MISS BRANCH — everything after the hit returns. The signature
+  // above it legitimately names hiddenIdsFor, and asserting over the whole
+  // function flagged the parameter as if it were a leak.
+  const miss = body.slice(body.indexOf('if (found) return found;')).replace(/^\s*\/\/.*$/gm, '');
+  assert.ok(!/hidden|consent/i.test(miss), 'the miss branch does not name consent');
+  // ONE answer, and it is the same one a pair with no shared history gets.
+  assert.equal((miss.match(/return\s+null;/g) || []).length, 1);
+});
+
+test('the hub consent read distinguishes HIDDEN from never-federated', () => {
+  // getPublicProfileExtras returns null for a hidden account AND for an absent
+  // one. For a rollup those are the same; for a consent gate they are opposites,
+  // and conflating them would empty the graph on a fresh instance and call it
+  // consent. hiddenGithubIds asks the one question it needs.
+  const pi = read('modules', 'platform-identity', 'platform-identity.js');
+  const fn = pi.slice(pi.indexOf('async function hiddenGithubIds'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /hide_stats = true/);
+  assert.ok(!/profile_state/.test(body), 'an unfederated builder has not opted out of anything');
+});
+
+// ── the graph is own-scoped ─────────────────────────────────────────────────
+
+test("you read your OWN graph, never someone else's", () => {
+  // Another builder's graph exposes who THEY are close to — a fact about third
+  // parties they did not consent to share.
+  assert.match(ROUTES, /closeness\.closenessFor\(req\.builder\.id/);
+  assert.ok(!/closenessFor\(\s*(req\.params|otherId)/.test(ROUTES));
+});
+
+test('the pair read is always relative to the CALLER', () => {
+  assert.match(ROUTES, /closenessBetween\(req\.builder\.id, otherId/);
+});
+
+test('a builder is never close to themselves', () => {
+  return closeness.closenessBetween(5, 5, {}).then((r) => assert.equal(r, null));
+});
+
+// ── bounds + registration ───────────────────────────────────────────────────
+
+test('reads are bounded', () => {
+  assert.equal(closeness.capRows(0), closeness.MAX_ROWS);
+  assert.equal(closeness.capRows(closeness.MAX_ROWS + 1), closeness.MAX_ROWS);
+  assert.equal(closeness.capRows(10), 10);
+});
+
+test('signals are counted over a trailing window, not all of history', () => {
+  // A collaboration from two years ago is history, not closeness.
+  assert.ok(closeness.WINDOW_DAYS > 0);
+  for (const q of ['coClaimCounts', 'coSessionCounts', 'shippedTogetherCounts']) {
+    const fn = SRC.slice(SRC.indexOf(`async function ${q}`));
+    assert.match(fn.slice(0, 1400), /now\(\) - \(\$2 \|\| ' days'\)::interval/, `${q} is windowed`);
+  }
+});
+
+test('the route is registered in the module manifest', () => {
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('closeness'));
+});
+
+test('lifecycle reads the hide flag through the PORT, never the hub table', () => {
+  // ADR 0083: a module must not read another module's table.
+  assert.match(ROUTES, /resolveOptional\('platform-identity\.hub'\)/);
+  for (const src of [SRC, ROUTES]) {
+    assert.ok(!/platform_identity_accounts/.test(src), 'no cross-module table read');
+  }
+});
+
+// ── the pair read costs a pair (grader round 2, task 1003174) ───────────────
+
+test('THE PAIR READ IS NARROWED AT THE DATABASE, not filtered in memory', () => {
+  // Round 1 called the graph read and then find()-ed the one row it wanted —
+  // three self-joins and a hydrate over up to a hundred builders to answer a
+  // question about one, on a likely per-profile-view route. Both the quality and
+  // the efficiency worker flagged it independently.
+  const fn = SRC.slice(SRC.indexOf('async function closenessBetween'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /closenessFor\(builderId, \{ limit: 1, hiddenIdsFor, otherId \}/,
+    'the pair id is pushed into the read, not applied after it');
+});
+
+test('and there is still exactly ONE definition of each signal', () => {
+  // The fix could have been a second set of pair-shaped queries. Two hand-written
+  // definitions of "what a co-claim is" drift, and the one that drifts is the one
+  // nobody reads — so otherId is a PARAMETER on the same query instead.
+  for (const q of ['coClaimCounts', 'coSessionCounts', 'shippedTogetherCounts']) {
+    assert.equal((SRC.match(new RegExp(`async function ${q}\\b`, 'g')) || []).length, 1,
+      `${q} is defined once`);
+    const fn = SRC.slice(SRC.indexOf(`async function ${q}`));
+    assert.match(fn.slice(0, 1500), /\$3::bigint IS NULL OR/,
+      `${q} narrows by parameter, and null means the whole graph`);
+  }
+});
+
+test('the index gap the grader raised is ANSWERED, not left open', () => {
+  // Round 2 could not confirm within budget whether the join columns were
+  // indexed. Checked: tasks.goal_id had NO index, and claims.builder_id /
+  // tasks.shipped_by were indexed only PARTIALLY, by predicates closeness does
+  // not satisfy (open claims / needs_rebase).
+  //
+  // The fix is NOT in this diff, and deliberately so: it was written here first
+  // as a lifecycle_ migration and the fitness check red-carded it, correctly —
+  // a module migration may only touch its own namespaced tables (ADR 0083 §5)
+  // and these are core tables. That makes it a core_ migration, which needs a
+  // reserved number and human eyes. Filed as task 1003268 with the SQL.
+  //
+  // This test pins the REFERENCE so the finding cannot be quietly dropped: if
+  // someone lands the indexes and deletes the note, they should delete this too.
+  assert.match(SRC, /task 1003268/,
+    'the closeness source cites the follow-up that carries the indexes');
+  const files = fs.readdirSync(path.join(ROOT, 'modules', 'lifecycle', 'migrations'));
+  assert.ok(!files.some((f) => /closeness/i.test(f)),
+    'and no module migration tries to index a core table again');
+});

package/tests/task_recommendations.mjs

@@ -0,0 +1,297 @@
+// tests/task_recommendations.mjs — passing a task RECOMMENDS it; it never
+// transfers the claim (task 1003173 / C03, goal 1000075; criterion
+// collab-pass-a-task, ADR 0187 §3).
+//
+// The criterion names four testable promises, and this file is organised around
+// them, because each one is a thing the code could plausibly have done instead:
+//   1. a pass creates a recommendation and never a claim;
+//   2. the recipient's claim is their own action;
+//   3. the recommendation and its author are readable afterwards;
+//   4. declining leaves no penalty on either party.
+//
+// Promises 1 and 4 are ABSENCE claims — "this code does not do X" — so they are
+// asserted against the source, which is the only place an absence is visible. A
+// behavioural test can show that a claim was not created on one path; it cannot
+// show that no path creates one.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const recs = require(path.join(ROOT, 'modules', 'lifecycle', 'task-recommendations.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+const SRC = read('modules', 'lifecycle', 'task-recommendations.js');
+const ROUTES = read('modules', 'lifecycle', 'routes', 'recommendations.js');
+const SQL = read('modules', 'lifecycle', 'migrations', 'lifecycle_005_task_recommendations.sql');
+
+const SENDER = 7;
+const good = { task_id: 42, recommended_to: 9, reason: 'you shipped the last three hall surfaces' };
+const reasons = (input, sender = SENDER) => recs.validateRecommendation(input, sender).errors.map((e) => e.reason);
+
+// ── PROMISE 1: a pass creates a recommendation and NEVER a claim ────────────
+
+test('THE DECISION: nothing in this surface writes a claim', () => {
+  // The criterion exists because a pass that moved a claim would be a task
+  // quietly changing hands. Asserted as an absence over the whole surface: any
+  // INSERT/UPDATE against claims, from either file, is the thing forbidden.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/\bINSERT\s+INTO\s+claims\b/i.test(src), `${name} must not insert a claim`);
+    assert.ok(!/\bUPDATE\s+claims\b/i.test(src), `${name} must not update a claim`);
+    assert.ok(!/\bDELETE\s+FROM\s+claims\b/i.test(src), `${name} must not delete a claim`);
+  }
+});
+
+test('and it does not reach the claim path indirectly either', () => {
+  // A require of the claim machinery would be the seam the decision refuses,
+  // even if today it went unused.
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    assert.ok(!/require\([^)]*claim/i.test(src), `${name} must not require the claim path`);
+    assert.ok(!/claimTask/.test(src), `${name} must not call claimTask`);
+  }
+});
+
+test('THE UNUSED SEAM: there is no transfer function, and no name promising one', () => {
+  // "Do NOT build a transfer path or a seam for one; the decision was
+  // recommend-only, and an unused seam is a cost." A function called transfer/
+  // reassign/handOff would read to the next author as an intention.
+  const exported = Object.keys(recs);
+  const suspect = exported.filter((k) => /transfer|reassign|handoff|hand_off|takeover/i.test(k));
+  assert.deepEqual(suspect, [], `no transfer-shaped export: ${suspect}`);
+});
+
+test('the schema has NO accepted status — accepting is claiming, which lives elsewhere', () => {
+  // A status saying "accepted" would be a second, weaker record of holding work,
+  // and would make this table look like the place claims come from.
+  assert.match(SQL, /status IN \('open', 'declined', 'withdrawn'\)/);
+  // Comments STRIPPED before asserting: both files DISCUSS why there is no
+  // accepted status, and matching the prose that explains the rule as a
+  // violation of it is the over-broad-source-assertion reflex of learning
+  // 1000196 — the same trap the sibling C01 test documents.
+  const sqlCode = SQL.replace(/^\s*--.*$/gm, '');
+  const routeCode = ROUTES.replace(/^\s*\/\/.*$/gm, '');
+  assert.ok(!/'accepted'/.test(sqlCode), 'no accepted status');
+  assert.ok(!/\baccept\b/i.test(routeCode), 'and no accept route');
+});
+
+test('the schema carries no transfer column', () => {
+  const body = SQL.slice(SQL.indexOf('CREATE TABLE'), SQL.indexOf('\n);'));
+  const columns = body.split('\n')
+    .map((l) => l.replace(/--.*$/, '').trim())
+    .filter((l) => l && !/^(CONSTRAINT|CHECK|\))/.test(l));
+  const suspect = columns.filter((l) => /transferred|claimed_by|assigned_to|accepted/i.test(l));
+  assert.deepEqual(suspect, [], `no transfer-shaped column: ${suspect}`);
+});
+
+// ── PROMISE 2: the recipient's claim is their own action ────────────────────
+
+test('the recipient read reports the TASK STATUS, not a claim grant', () => {
+  // What the recipient gets is enough to judge, and nothing that says they now
+  // hold it. Claimability stays the claim path's answer — duplicating that
+  // judgement here would be a second, staler copy of a rule that has an owner.
+  const fn = SRC.slice(SRC.indexOf('async function listForRecipient'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /t\.status\s+AS task_status/, 'the task\'s own status is reported');
+  assert.ok(!/can_claim|claimable|is_claimable/i.test(body), 'and no claimability verdict is invented');
+});
+
+test('a recommendation to yourself is refused', () => {
+  // Not a recommendation. Checked against the AUTHENTICATED sender, never a
+  // client-supplied id — which is why validateRecommendation takes it as an
+  // argument rather than reading it out of the body.
+  assert.ok(reasons({ ...good, recommended_to: SENDER }).includes('cannot_recommend_to_self'));
+  assert.match(ROUTES, /validateRecommendation\(req\.body, req\.builder\.id\)/,
+    'the sender comes from the session');
+});
+
+test('the not-self rule is in the schema too, so neither guard is the only one', () => {
+  assert.match(SQL, /recommended_by <> recommended_to/);
+});
+
+// ── PROMISE 3: the recommendation and its author are readable afterwards ────
+
+test('THE LEDGER: the reason is required, not optional', () => {
+  // The criterion's own argument: an untraced recommendation is indistinguishable
+  // from a task quietly changing hands. A reason the sender must write is what
+  // makes this a record of a judgement rather than a nudge.
+  for (const v of [undefined, null, '', '   ', '\n\t ']) {
+    assert.ok(reasons({ ...good, reason: v }).includes('required'),
+      `${JSON.stringify(v)} is not a reason`);
+  }
+  assert.deepEqual(reasons(good), [], 'a real reason validates');
+});
+
+test('the reason is enforced in the schema and the route body as well', () => {
+  // Three guards that agree: the CHECK is the authority, the validator names the
+  // field, and the route schema refuses before either runs.
+  assert.match(SQL, /reason\s+text NOT NULL/);
+  assert.match(SQL, /length\(btrim\(reason\)\) > 0/);
+  assert.match(ROUTES, /reason: \{ required: true, type: 'string', minLength: 1/);
+});
+
+test('an over-long reason is refused rather than truncated', () => {
+  assert.ok(reasons({ ...good, reason: 'x'.repeat(recs.MAX_REASON + 1) }).includes('too_long'));
+});
+
+test('the per-task history reads EVERY status, so a declined pass stays on the record', () => {
+  // "Readable afterwards" is the point. A history filtered to open would erase
+  // exactly the case the ledger exists to document.
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /WHERE r\.task_id = \$1/);
+  assert.ok(!/status = 'open'/.test(body), 'the per-task history is not filtered to open');
+});
+
+test('the history names the AUTHOR, not just the recommendation', () => {
+  const fn = SRC.slice(SRC.indexOf('async function listForTask'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /sender\.github_login/, 'who recommended it');
+  assert.match(body, /r\.reason/, 'and why');
+});
+
+test("the sender's own list is unfiltered by default", () => {
+  const fn = SRC.slice(SRC.indexOf('async function listFromSender'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /\$2::text IS NULL OR r\.status = \$2/, 'status is an optional narrowing');
+});
+
+// ── PROMISE 4: declining leaves no penalty on either party ──────────────────
+
+test('THE NO-PENALTY RULE: declining touches nothing but its own row', () => {
+  // Asserted as an absence, because that is what "costs nothing" means. If a
+  // penalty ever appears for declining, it did not come from here.
+  const fn = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  assert.match(body, /UPDATE lifecycle_task_recommendations/);
+  assert.ok(!/builders|credits|karma|credit_log|peer_votes/i.test(body),
+    'declining writes nothing about either person');
+});
+
+test('and no penalty machinery is reachable from this surface at all', () => {
+  for (const [name, src] of [['data layer', SRC], ['routes', ROUTES]]) {
+    const code = src.replace(/^\s*\/\/.*$/gm, '');   // comments may DISCUSS karma
+    for (const forbidden of ['karma', 'credit', 'penalt', 'cooldown', 'strike']) {
+      assert.ok(!new RegExp(forbidden, 'i').test(code),
+        `${name} must not reach ${forbidden} machinery`);
+    }
+  }
+});
+
+test('a decline is NOT final — the same task can be recommended again', () => {
+  // A permanent unique key would quietly make declining final, which is a cost.
+  // The uniqueness is partial, on open rows only.
+  assert.match(SQL, /CREATE UNIQUE INDEX[^;]*lifecycle_task_recommendations_open_uniq[^;]*WHERE status = 'open'/s);
+});
+
+test('a duplicate OPEN recommendation is a named conflict, not a 500', () => {
+  // The same judgement repeated. Not something the sender can fix by changing
+  // the body, so it is not a validation error.
+  assert.match(SRC, /ON CONFLICT DO NOTHING/);
+  assert.match(SRC, /reason: 'already_open'/);
+  assert.match(ROUTES, /recommendation_already_open', 409/);
+});
+
+// ── who may settle what ─────────────────────────────────────────────────────
+
+test('the RECIPIENT declines and the SENDER withdraws — each scoped in the WHERE', () => {
+  const dec = SRC.slice(SRC.indexOf('async function declineRecommendation'));
+  assert.match(dec.slice(0, 600), /recommended_to = \$2/, 'ownership is in the WHERE, not in rank');
+  const wd = SRC.slice(SRC.indexOf('async function withdrawRecommendation'));
+  assert.match(wd.slice(0, 600), /recommended_by = \$2/);
+  for (const fn of [dec, wd]) {
+    assert.match(fn.slice(0, 600), /status = 'open'/, 'a settled recommendation cannot be re-settled');
+  }
+});
+
+test('the settle refusal does not let you enumerate ids', () => {
+  // ONE refusal for absent / not-yours / already-settled. Looking the row up to
+  // say which would leak existence — the lesson help-requests learned from its
+  // own grader round (task 1003171).
+  const patch = ROUTES.slice(ROUTES.indexOf("'PATCH /task-recommendations/:id'"));
+  const body = patch.slice(0, patch.indexOf('errorCode'));
+  assert.match(body, /recommendation_not_settleable', 404/);
+  assert.ok(!/getRecommendation|SELECT/i.test(body), 'no lookup before the refusal');
+});
+
+// ── the shape the module contract requires ──────────────────────────────────
+
+test('the table is module-owned and lifecycle-namespaced', () => {
+  // A NEW table the module owns outright, unlike tasks/builders which are core
+  // tables it only references — so fitness check 11 permits it (ADR 0083 §5).
+  assert.match(SQL, /CREATE TABLE IF NOT EXISTS lifecycle_task_recommendations/);
+  assert.ok(!/ALTER TABLE (?!lifecycle_)/.test(SQL), 'it alters no core table');
+});
+
+test('the migration registers itself', () => {
+  assert.match(SQL, /INSERT INTO schema_migrations \(version\) VALUES \('lifecycle_005_task_recommendations'\)/);
+});
+
+test('the route is registered in the module manifest', () => {
+  // A route file nothing mounts is a file, not a surface.
+  const manifest = JSON.parse(read('modules', 'lifecycle', 'module.json'));
+  assert.ok(manifest.contributes.routes.includes('recommendations'));
+});
+
+test('core reaches the count through the PORT, never by importing the module', () => {
+  // ADR 0093: core imports no module. /me needs the count for the needs roster,
+  // so the lifecycle port exposes it the same way it exposes the help-request one.
+  const lifecycle = read('modules', 'lifecycle', 'lifecycle.js');
+  assert.match(lifecycle, /openTaskRecommendationsFor:/);
+  const me = read('src', 'bongos', 'routes', 'me.js');
+  assert.match(me, /lifecycle\.openTaskRecommendationsFor/);
+  assert.ok(!/require\([^)]*task-recommendations/.test(me), 'core does not import the module');
+});
+
+// ── it reaches someone, rather than merely being stored ─────────────────────
+
+const needs = require(path.join(ROOT, 'modules', 'builder-settings', 'builder-needs.js'));
+
+test('a waiting recommendation produces a need, so it is surfaced and not just stored', () => {
+  // C01's grader round established the rule for its sibling: storing is not
+  // reaching. It lands in the needs roster the hall card and the CLI nudge
+  // already render, rather than in a second notification system beside it.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 2 });
+  assert.ok(n, 'a pending recommendation produces a need');
+  assert.match(n.message, /2 tasks/);
+  assert.ok(n.action && n.action.href, 'and it says where to go');
+});
+
+test('the need says plainly that nothing has been assigned', () => {
+  // Wording that pressured the reader would BE the penalty the decision forbids.
+  const n = needs.taskRecommendationsNeed({ openTaskRecommendations: 1 });
+  assert.match(n.message, /Nothing has been assigned/);
+  assert.match(n.message, /declining costs nothing/);
+  assert.match(n.what, /suggestion, not an assignment/);
+});
+
+test('no recommendations produces NO need, not a cheerful empty state', () => {
+  for (const ctx of [{ openTaskRecommendations: 0 }, {}, { openTaskRecommendations: undefined }]) {
+    assert.equal(needs.taskRecommendationsNeed(ctx), null);
+  }
+});
+
+test('the need is registered, so every renderer picks it up', () => {
+  const roster = needs.computeNeeds({ openTaskRecommendations: 1, ownKeySet: true, rank: 'metic' });
+  assert.ok(roster.items.some((i) => i.id === 'task_recommendations'), 'it is in the roster');
+});
+
+// ── bounds ──────────────────────────────────────────────────────────────────
+
+test('reads are bounded, so an unsettled pile degrades the page and not the server', () => {
+  assert.equal(recs.capRows(0), recs.MAX_ROWS);
+  assert.equal(recs.capRows(-1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(recs.MAX_ROWS + 1), recs.MAX_ROWS);
+  assert.equal(recs.capRows(1.5), recs.MAX_ROWS);
+  assert.equal(recs.capRows(25), 25);
+});
+
+test('task_id and recommended_to are required and must be positive ids', () => {
+  assert.ok(reasons({ reason: 'x' }).includes('required'));
+  assert.ok(reasons({ ...good, task_id: 0 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, task_id: 1.5 }).includes('bad_task_id'));
+  assert.ok(reasons({ ...good, recommended_to: -3 }).includes('bad_builder_id'));
+});