@bongos/core 1.19.998 → 1.19.1000

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

@@ -57,6 +57,13 @@
   // blocks and the API sends ids as strings.
   const askById = new Map();
   let forMeRows = [];
+  // Who is reading, and which crafts they answer for — the two facts L.canClose
+  // needs. Read from /me on load, never from a query param: the whole reason the
+  // addressed read takes its crafts from the profile is that a caller-supplied
+  // craft was this surface's privacy hole.
+  let meId = null;
+  let myCrafts = [];
+  let replying = false;
 
   // The hall answers on two shapes — /builders on the site, or builders.<domain>
   // as its own host. A pasted prompt is opened somewhere that is not this page,
@@ -125,6 +132,44 @@
       </div>${full}`;
   }
 
+  // ---- the thread (task 1004216, ADR 0330) -----------------------------------
+  //
+  // An ask can be ANSWERED on the page now. What this draws is deliberately thin:
+  // who said it, when, and what they said, oldest first — no avatars on replies
+  // (the row already leads with a face and a second column of them would read as
+  // a chat), no edit, no delete, no reactions, no threading of replies to
+  // replies. The restraint is the argument: this is the answer surface ADR 0330
+  // opens, not the chat surface ADR 0187 §4a declined.
+  function replyHtml(reply, nowMs) {
+    return `<li class="cb-reply">
+      <span class="cb-reply__who">${escapeHtml(L.replyAuthor(reply))}</span>
+      <span class="cb-reply__when">${escapeHtml(L.saidLabel(reply.created_at, nowMs))}</span>
+      <p class="cb-reply__body">${escapeHtml(String(reply.body == null ? '' : reply.body))}</p>
+    </li>`;
+  }
+
+  // The composer is CLOSED until asked for. A textarea open on every row would
+  // turn a page you read into a page you are being asked to type on, and the
+  // blocks are condensed to three rows precisely so the page stays readable.
+  function threadHtml(req, key, nowMs) {
+    const thread = L.threadOf(req);
+    const id = escapeHtml(String(req.id));
+    const fid = `cb-reply-${escapeHtml(key)}-${id}`;
+    const list = thread.length
+      ? `<ul class="cb-thread">${thread.map((r) => replyHtml(r, nowMs)).join('')}</ul>`
+      : '';
+    return `${list}<div class="cb-reply-bar">
+        <button class="cb-ask__door" type="button" data-reply-open="${fid}">${thread.length ? 'Add a reply' : 'Reply'}</button>
+      </div>
+      <form class="cb-reply-form" id="${fid}" data-reply-form="${id}" hidden>
+        <textarea class="cb-reply-input" name="body" rows="3" maxlength="${L.MAX_REPLY}" placeholder="Moot — the metrics stack was removed on the 15th, so there is nothing left to rotate."></textarea>
+        <div class="cb-reply-actions">
+          <button class="btn-accent" type="submit" data-reply-send="${id}">Post reply</button>
+          <button class="btn-ghost" type="button" data-reply-cancel="${fid}">Cancel</button>
+        </div>
+      </form>`;
+  }
+
   function contextChip(req) {
     const ctx = L.contextOf(req);
     if (!ctx) return '';
@@ -208,12 +253,22 @@
   // call on this reader, so its row is the LIT one (.cb-row--live).
   function forMeRow(req, nowMs, extra, key, baseline) {
     const live = req.needs_builder_id != null ? ' cb-row--live' : '';
+    // CLOSING IS THE HALF THIS BLOCK NEVER HAD (task 1004216). Until now the only
+    // write on a row addressed to you was copying it; the person being asked
+    // could answer nowhere and close nothing, so a dealt-with ask stayed open
+    // until its author happened to remember it. L.canClose decides whether to
+    // draw it and the server's own WHERE decides whether it works — so the worst
+    // a wrong answer here can do is offer a button that refuses.
+    const close = L.canClose(req, meId, myCrafts)
+      ? `<div class="ov-row__actions"><button class="btn-ghost" data-settle="answered" data-id="${escapeHtml(String(req.id))}">Close this ask</button></div>`
+      : '';
     return `<li class="ov-row ov-row--lead cb-row${live}" data-id="${escapeHtml(String(req.id))}"${extra ? ' data-extra hidden' : ''}>
       ${faceHtml(L.faceOf(req, 'in'))}
       <div class="ov-row__main">${askHtml(req, key)}
         <div class="ov-row__facts">${directionFact(req, 'in')}${contextChip(req)}</div>
+        ${threadHtml(req, key, nowMs)}
       </div>
-      <div class="ov-row__right">${ageChip(req, nowMs, baseline)}</div>
+      <div class="ov-row__right">${ageChip(req, nowMs, baseline)}${close}</div>
     </li>`;
   }
 
@@ -235,6 +290,7 @@
       ${faceHtml(L.faceOf(req, 'out'))}
       <div class="ov-row__main">${askHtml(req, key)}
         <div class="ov-row__facts">${directionFact(req, 'out')}${contextChip(req)}${ageChip(req, nowMs, baseline)}</div>
+        ${threadHtml(req, key, nowMs)}
       </div>
       <div class="ov-row__right">
         <div class="ov-row__actions">
@@ -252,6 +308,7 @@
       ${faceHtml(L.faceOf(req, 'in'))}
       <div class="ov-row__main">${askHtml(req, key)}
         <div class="ov-row__facts">${boardFact(req)}${contextChip(req)}</div>
+        ${threadHtml(req, key, nowMs)}
       </div>
       <div class="ov-row__right">${ageChip(req, nowMs, baseline)}</div>
     </li>`;
@@ -434,17 +491,28 @@
 
   async function load() {
     const nowMs = Date.now();
-    const [forMe, mine, all] = await Promise.all([
+    const [forMe, mine, all, me] = await Promise.all([
       api.helpRequests.getHelpRequestsForMe({}),
       api.helpRequests.getHelpRequestsMine({ query: { status: 'open' } }),
       // The board read (task 1003942) — GET /help-requests, every open ask in the
       // project. Through api.request because the generated client predates it.
       api.request('GET', '/help-requests'),
+      // WHO IS READING (task 1004216), IN the fan-out rather than in front of it.
+      // The close control needs the viewer's id, and a serialized await here
+      // would put a round trip in front of every other read on the page.
+      api.me.getMe({}),
     ]);
 
     const rowsOf = (r) => ((r && r.ok && r.data && r.data.help_requests) || []);
     const crafts = (forMe.ok && forMe.data && forMe.data.crafts) || [];
 
+    // FAILS CLOSED. A /me that errored leaves meId null, L.canClose says no, and
+    // the page simply draws no close control — the same shape a reader with no
+    // right to close sees. Guessing an id from any other response would offer a
+    // button the server then refuses.
+    meId = (me && me.ok && me.data && me.data.builder && me.data.builder.id) || null;
+    myCrafts = crafts;
+
     // Re-indexed on every load, not merged into: a request settled elsewhere
     // must disappear from the copy path at the same moment it disappears from
     // the rows, or a stale entry would keep handing a session work that is done.
@@ -548,8 +616,11 @@
 
     const r = await api.request('GET', '/mingle');
     const pairs = (r.ok && r.data && r.data.open_pairs) || [];
-    const meId = (r.ok && r.data && r.data.you) || null;
-    paint('#cb-mingle', '#cb-mingle-empty', pairs.map((p) => mingleRow(p, meId)).join(''), pairs.length);
+    // Named apart from the module-level `meId` on purpose: mingle asks the mingle
+    // route who you are, and two different reads answering to one name in one
+    // file is how a shadowed binding becomes a bug nobody can see.
+    const mingleMe = (r.ok && r.data && r.data.you) || null;
+    paint('#cb-mingle', '#cb-mingle-empty', pairs.map((p) => mingleRow(p, mingleMe)).join(''), pairs.length);
   }
 
   async function decideMingle(id, decision) {
@@ -571,6 +642,49 @@
     }
   }
 
+  // Post a reply. One in flight at a time (the `replying` latch), the same guard
+  // `settling` gives the settle actions: a double-submit on an APPEND-ONLY table
+  // writes the answer twice and there is no edit or delete to take it back with.
+  async function postReply(form) {
+    if (replying) return;
+    const id = form.getAttribute('data-reply-form');
+    const input = form.querySelector('.cb-reply-input');
+    const v = L.validateReplyBody(input && input.value);
+    if (!v.ok) {
+      // Refused here rather than at the server, so an empty reply costs no round
+      // trip and the message names the field the reader is looking at.
+      toast(v.reason === 'empty' ? 'Write something first.' : `A reply is at most ${L.MAX_REPLY} characters.`);
+      if (input) input.focus();
+      return;
+    }
+    replying = true;
+    const send = form.querySelector('[data-reply-send]');
+    if (send) { send.disabled = true; send.textContent = 'Posting…'; }
+    try {
+      const r = await api.request('POST', `/help-requests/${id}/replies`, { body: v.body });
+      if (!r.ok) {
+        toast(window.OTB.errMessage ? window.OTB.errMessage(r.data) : 'Could not post that reply.');
+        return;
+      }
+      if (input) input.value = '';
+      toast('Replied.');
+      await load();
+    } finally {
+      replying = false;
+      if (send) { send.disabled = false; send.textContent = 'Post reply'; }
+    }
+  }
+
+  function toggleReply(fid, open) {
+    const form = document.getElementById(fid);
+    if (!form) return;
+    form.hidden = !open;
+    if (open) {
+      const input = form.querySelector('.cb-reply-input');
+      if (input) input.focus();
+    }
+  }
+
   async function settle(id, status) {
     if (settling) return;
     settling = true;
@@ -580,7 +694,7 @@
         toast(window.OTB.errMessage ? window.OTB.errMessage(r.data) : 'Could not update that request.');
         return;
       }
-      toast(status === 'answered' ? 'Marked answered.' : 'Withdrawn.');
+      toast(status === 'answered' ? 'Closed.' : 'Withdrawn.');
       await load();
     } finally {
       settling = false;
@@ -597,6 +711,10 @@
     if (copyBtn) { ev.preventDefault(); copyAsk(copyBtn); return; }
     const copyAll = closest('#cb-for-me-copy');
     if (copyAll) { ev.preventDefault(); copyQueue(); return; }
+    const replyOpen = closest('[data-reply-open]');
+    if (replyOpen) { ev.preventDefault(); toggleReply(replyOpen.getAttribute('data-reply-open'), true); return; }
+    const replyCancel = closest('[data-reply-cancel]');
+    if (replyCancel) { ev.preventDefault(); toggleReply(replyCancel.getAttribute('data-reply-cancel'), false); return; }
     const mingleBtn = closest('[data-mingle]');
     if (mingleBtn) {
       ev.preventDefault();
@@ -609,6 +727,17 @@
     settle(Number(btn.getAttribute('data-id')), btn.getAttribute('data-settle'));
   });
 
+  // A form, not a click handler on the button: submit is what Enter does in a
+  // textarea's form and what a screen reader announces, and a control that only
+  // answered a mouse would be a reply surface you could not reach from a
+  // keyboard.
+  document.addEventListener('submit', (ev) => {
+    const form = ev.target && ev.target.closest ? ev.target.closest('[data-reply-form]') : null;
+    if (!form) return;
+    ev.preventDefault();
+    postReply(form);
+  });
+
   load().catch(() => {
     const sub = $('#cb-sub');
     // V6: a message that stops someone points at the next move in the same breath.

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';
+const COLS = 'id, requested_by, needs_craft, needs_builder_id, what_is_stuck, task_id, goal_id, status, created_at, updated_at, settled_by';
 // 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
@@ -228,24 +228,134 @@ async function getHelpRequest(id, deps = {}) {
   return rows[0] || null;
 }
 
-// Only the ASKER settles their own request. Answering is not a claim on anyone —
-// nobody is assigned by being asked, which is the same consent posture passing a
-// task takes (ADR 0187 §3).
-async function setHelpRequestStatus({ id, builderId, status }, deps = {}) {
+// THE ASKER OR THE ADDRESSEE settles the request (ADR 0330, widening the
+// asker-only rule lifecycle_004 shipped with).
+//
+// Asker-only was coherent while there was nothing to say on the row: the only
+// person who could know an ask had been answered was the person who had gone and
+// got the answer somewhere else. Replies change that — the answer is now ON the
+// ask, and a request addressed to someone who has just answered it in front of
+// everyone and still cannot close it is a surface arguing with itself. So the
+// person a request NAMES may close it too, by id or through a craft they belong
+// to, and `settled_by` records which of them did.
+//
+// WHAT DOES NOT WIDEN: 'withdrawn' stays the ASKER'S ALONE. Withdrawing means "I
+// no longer need this", which is a statement only the person who needed it can
+// make; letting an addressee withdraw would hand them a way to make an ask
+// disappear without ever answering it. An addressee who wants rid of an ask
+// answers it and closes it, in the open, with their name on both.
+//
+// Consent is untouched. Being asked still assigns nobody anything (ADR 0187 §3) —
+// closing an ask is not accepting work, it is ending a question.
+async function setHelpRequestStatus({ id, builderId, status, crafts = [] }, deps = {}) {
   const activePool = deps.pool || pool;
+  const safeCrafts = (Array.isArray(crafts) ? crafts : []).filter((c) => HELP_CRAFTS.includes(c));
+  const askerOnly = status === 'withdrawn';
   const { rows } = await activePool.query(
     `UPDATE lifecycle_help_requests
-        SET status = $3, updated_at = now()
-      WHERE id = $1 AND requested_by = $2 AND status = 'open'
+        SET status = $3, updated_at = now(), settled_by = $2
+      WHERE id = $1 AND status = 'open'
+        AND (requested_by = $2
+             OR ($4::boolean IS FALSE
+                 AND (needs_builder_id = $2 OR needs_craft = ANY($5::text[]))))
      RETURNING ${COLS}`,
-    [id, builderId, status]
+    [id, builderId, status, askerOnly, safeCrafts]
   );
   return rows[0] || null;
 }
 
+// ---- replies (task 1004216) -------------------------------------------------
+//
+// APPEND-ONLY, and the table's own trigger is the authority — there is deliberately
+// no updateReply and no deleteReply here, and adding one would not work if you
+// tried. A reply is a thing somebody said; the record of what was said at the time
+// is the entire point.
+const MAX_REPLY = 4000;
+const REPLY_COLS = 'r.id, r.help_request_id, r.builder_id, r.body, r.created_at, '
+  + 'b.github_login AS builder_login, b.display_name AS builder_name, b.avatar_url AS builder_avatar_url';
+const REPLY_FROM = 'FROM lifecycle_help_request_replies r LEFT JOIN builders b ON b.id = r.builder_id';
+
+// PURE, for the same reason validateHelpRequest is: the route refuses with a named
+// field before a query runs, and every branch is testable without a database.
+function validateReply(input) {
+  const errors = [];
+  const body = typeof (input || {}).body === 'string' ? input.body.trim() : '';
+  if (!body) errors.push({ field: 'body', reason: 'required' });
+  else if (body.length > MAX_REPLY) errors.push({ field: 'body', reason: 'too_long' });
+  return { ok: errors.length === 0, errors };
+}
+
+async function createReply({ helpRequestId, builderId, body }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_help_request_replies (help_request_id, builder_id, body)
+     VALUES ($1, $2, $3)
+     RETURNING id, help_request_id, builder_id, body, created_at`,
+    [helpRequestId, builderId, String(body).trim()]
+  );
+  return rows[0];
+}
+
+// Oldest first — the order a conversation is read in, and the opposite of every
+// other list on the Collab page, which sorts by what needs attention. A thread is
+// not a queue.
+async function listReplies(helpRequestId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT ${REPLY_COLS} ${REPLY_FROM}
+      WHERE r.help_request_id = $1
+      ORDER BY r.created_at ASC, r.id ASC
+      LIMIT ${MAX_ROWS}`,
+    [helpRequestId]
+  );
+  return rows;
+}
+
+// The most replies one thread contributes to a LIST read. A page draws a thread
+// under every row, so the bound that matters is per-ask, not overall: a single
+// global LIMIT would let one busy ask eat the budget and hand the rows below it
+// empty threads, which reads as "nobody answered" — the exact lie this whole
+// surface exists to stop telling.
+const MAX_THREAD_ON_LIST = 20;
+
+// Every reply on a set of asks in ONE query, so a page rendering twenty rows makes
+// one round trip rather than twenty. Returns a Map keyed by help_request_id.
+//
+// BOUNDED, like every other read here. listReplies caps at MAX_ROWS; this one
+// backs three list routes on the page's own load path, so an unbounded result set
+// would be the one place a busy project could make the Collab page arrive by the
+// megabyte. The window is per help_request_id, and the ORDER inside it is the
+// same one listReplies uses, so the first N a list shows are the first N the
+// single-thread read shows — never a different N in a different order.
+async function repliesForRequests(ids, deps = {}) {
+  const activePool = deps.pool || pool;
+  const wanted = [...new Set((Array.isArray(ids) ? ids : []).map(Number).filter(Number.isInteger))];
+  if (!wanted.length) return new Map();
+  const { rows } = await activePool.query(
+    `SELECT * FROM (
+       SELECT ${REPLY_COLS},
+              ROW_NUMBER() OVER (PARTITION BY r.help_request_id
+                                 ORDER BY r.created_at ASC, r.id ASC) AS thread_pos
+         ${REPLY_FROM}
+        WHERE r.help_request_id = ANY($1::bigint[])
+     ) t
+      WHERE t.thread_pos <= ${MAX_THREAD_ON_LIST}
+      ORDER BY t.created_at ASC, t.id ASC`,
+    [wanted]
+  );
+  const out = new Map();
+  for (const row of rows) {
+    const key = String(row.help_request_id);
+    if (!out.has(key)) out.set(key, []);
+    out.get(key).push(row);
+  }
+  return out;
+}
+
 module.exports = {
   HELP_CRAFTS, helpCrafts, disciplineForCraft, craftForDiscipline, craftsForBuilder,
   validateHelpRequest, MAX_STUCK, MAX_ROWS, capRows,
   builderExists, createHelpRequest, listOpenForBuilder, listMine, listOpenAll, getHelpRequest, setHelpRequestStatus,
   countOpenForBuilder, craftMapSql,
+  MAX_REPLY, MAX_THREAD_ON_LIST, validateReply, createReply, listReplies, repliesForRequests,
 };

package/modules/lifecycle/migrations/lifecycle_011_help_request_replies.sql

@@ -0,0 +1,113 @@
+-- lifecycle_011_help_request_replies.sql — an ask can finally be ANSWERED where it
+-- was asked (task 1004216, goal 1000095; ADR 0330, amending ADR 0187 §4a).
+--
+-- THE HOLE THIS FILLS. lifecycle_004 gave a builder a way to ask for help and gave
+-- the ASKER a way to mark their own row answered. It gave the person being asked
+-- nothing at all. So the answer — the thing the whole surface exists to produce —
+-- happened somewhere Bongos cannot see, and the row sat open until its author
+-- happened to remember it. Six asks addressed to the owner were open between four
+-- and thirteen days when this was written, every one of them already answerable.
+--
+-- WHY THIS IS NOT THE SURFACE ADR 0187 RULED OUT. §4a put conversation out of
+-- scope and deferred it to the Agora (task 1002946, goal 1000064) — "this goal
+-- must not quietly reimplement the Agora to get around it". That deferral no
+-- longer has an addressee: task 1002946 is ABANDONED and goal 1000064 is ARCHIVED,
+-- verified 2026-09-23. The surface that was to own replies will not be built.
+--
+-- The restraint survives the reversal, and it lives in the schema rather than in a
+-- comment asking nicely. A reply is APPEND-ONLY: there is no updated_at, no
+-- edited_by, no deleted_at, no parent_reply_id, no reaction table and no mention
+-- table. What you can do is add one, and read them in order. That is an answer
+-- surface; a thing you can edit, nest, react to and address at people is a chat,
+-- and a chat is what §4a declined to build here.
+--
+-- WHY THE FK RESTRICTS RATHER THAN CASCADES, which is the opposite of what it
+-- first said. `ON DELETE CASCADE` reads right — a reply has no meaning without
+-- the ask it answers — but it CONTRADICTS append-only, and Postgres says so out
+-- loud: a cascade is an ordinary `DELETE FROM lifecycle_help_request_replies`,
+-- the trigger below refuses it, and deleting a help request that had ever been
+-- answered failed outright. Caught by running the migration on a real database
+-- rather than by reading it.
+--
+-- Restrict is the honest resolution rather than the lesser evil. Nothing deletes
+-- a help request: it is SETTLED (`status`), and there is no DELETE route for one
+-- anywhere in this module. So the FK forbids a thing that does not happen, and
+-- if it ever must, "you cannot silently destroy answers as a side effect of
+-- removing the question" is the right refusal for an append-only record to give.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it (ADR 0083
+-- §Decision #5): a new table the lifecycle module owns outright, plus one column
+-- on a table it already owns.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS lifecycle_help_request_replies (
+  id               bigserial PRIMARY KEY,
+  help_request_id  bigint NOT NULL REFERENCES lifecycle_help_requests(id) ON DELETE RESTRICT,
+  builder_id       bigint NOT NULL REFERENCES builders(id),
+  body             text NOT NULL,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+
+  -- Same shape as what_is_stuck's own check: whitespace is not an answer.
+  CONSTRAINT lifecycle_help_request_replies_body_chk
+    CHECK (length(btrim(body)) > 0)
+);
+
+-- Every read is "the replies on this ask, oldest first" — the order a
+-- conversation is read in, and the order the page renders.
+CREATE INDEX IF NOT EXISTS lifecycle_help_request_replies_thread_idx
+  ON lifecycle_help_request_replies (help_request_id, created_at);
+
+COMMENT ON TABLE lifecycle_help_request_replies IS
+  'Answers on a help request, append-only and oldest-first (task 1004216). No edit, no delete, no nesting, no reactions, no mentions — that restraint is what keeps this an answer surface rather than the chat surface ADR 0187 4a declined to build.';
+
+-- WHO SETTLED IT. Until now only the asker could, so the answer was never in
+-- question. ADR 0330 lets the ADDRESSEE close an ask too — a request addressed to
+-- someone who has answered it and cannot close it is the defect that widening
+-- fixes — which makes "who closed this" a real question for the first time.
+-- Nullable, and null for every historical row: a settle that predates this column
+-- was the asker's by construction, and backfilling requested_by would invent a
+-- fact rather than record one.
+ALTER TABLE lifecycle_help_requests
+  ADD COLUMN IF NOT EXISTS settled_by bigint REFERENCES builders(id);
+
+COMMENT ON COLUMN lifecycle_help_requests.settled_by IS
+  'The builder who moved this request out of open — the asker or, since ADR 0330, its addressee. NULL on rows settled before the column existed; that absence means "not recorded", never "the asker".';
+
+-- The table must be append-only in the DATABASE, not merely in the routes that
+-- happen to exist today. A later route, a migration, or a hand-run UPDATE would
+-- otherwise silently rewrite what somebody said — and the whole value of a reply
+-- as a record is that it is what was said at the time.
+CREATE OR REPLACE FUNCTION lifecycle_help_request_replies_append_only()
+RETURNS trigger AS $$
+BEGIN
+  RAISE EXCEPTION
+    'lifecycle_help_request_replies is append-only (ADR 0330): a reply cannot be % once written',
+    CASE TG_OP WHEN 'UPDATE' THEN 'edited' ELSE 'deleted' END;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS lifecycle_help_request_replies_no_update ON lifecycle_help_request_replies;
+CREATE TRIGGER lifecycle_help_request_replies_no_update
+  BEFORE UPDATE OR DELETE ON lifecycle_help_request_replies
+  FOR EACH ROW EXECUTE FUNCTION lifecycle_help_request_replies_append_only();
+
+-- Proof the guard is armed, checked here rather than trusted: a migration that
+-- silently failed to attach the trigger would leave the table editable, and every
+-- test of the ROUTES would still pass.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_trigger
+     WHERE tgrelid = 'lifecycle_help_request_replies'::regclass
+       AND tgname = 'lifecycle_help_request_replies_no_update'
+       AND NOT tgisinternal
+  ) THEN
+    RAISE EXCEPTION 'lifecycle_011: the append-only trigger is not attached — the table would accept an UPDATE or DELETE';
+  END IF;
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_011_help_request_replies')
+ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

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

@@ -2,10 +2,11 @@
 // read for "I am stuck" (task 1003171 / C01, goal 1000075; criterion
 // collab-ask-for-help).
 //
-// Five routes: ask, see what is addressed to me, see my own, see the whole open
-// board (task 1003942), settle mine.
-// The Collab PAGE is C02 and the matching rules beyond craft are its job — this
-// surface deliberately stops at "the request is addressed and answerable".
+// Seven routes: ask, see what is addressed to me, see my own, see the whole open
+// board (task 1003942), settle it, and — since task 1004216 — REPLY to one and
+// read its replies. The Collab PAGE is C02 and the matching rules beyond craft
+// are its job; this surface stops at "the request is addressed, answerable, and
+// answered".
 //
 // Reaches core only through the doorway (ADR 0083).
 
@@ -17,6 +18,17 @@ const help = require('../help-requests');
 
 const { asyncHandler, validateOrRespond, parseId } = api;
 
+// Hang each row's replies on it in ONE query (task 1004216). The page renders a
+// thread under every ask, and fetching them per row would turn one list read into
+// twenty — the shape that makes a page feel slow for reasons no single request
+// explains. An empty thread is `[]`, never absent: a reader of this response
+// should never have to tell "no replies" apart from "this response does not carry
+// replies".
+async function withReplies(rows) {
+  const threads = await help.repliesForRequests(rows.map((r) => r.id));
+  return rows.map((r) => ({ ...r, replies: threads.get(String(r.id)) || [] }));
+}
+
 module.exports = function buildHelpRequestsRouter() {
   const router = express.Router();
 
@@ -78,14 +90,14 @@ module.exports = function buildHelpRequestsRouter() {
     const mine = await help.craftsForBuilder(req.builder.id);
     const want = typeof req.query.craft === 'string' ? req.query.craft : null;
     const crafts = want ? mine.filter((c) => c === want) : mine;
-    const rows = await help.listOpenForBuilder({ builderId: req.builder.id, crafts });
+    const rows = await withReplies(await help.listOpenForBuilder({ builderId: req.builder.id, crafts }));
     return res.json({ help_requests: rows, count: rows.length, crafts });
   }, { errorCode: 'help_request_list_failed' }));
 
   // 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) => {
     const status = typeof req.query.status === 'string' ? req.query.status : null;
-    const rows = await help.listMine({ builderId: req.builder.id, status });
+    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' }));
 
@@ -94,15 +106,23 @@ module.exports = function buildHelpRequestsRouter() {
   // 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) => {
-    const rows = await help.listOpenAll();
+    const rows = await withReplies(await help.listOpenAll());
     return res.json({ help_requests: rows, count: rows.length });
   }, { errorCode: 'help_request_list_failed' }));
 
-  // Only the ASKER settles their own request: 'answered' when someone helped,
-  // 'withdrawn' when they no longer need it. Nobody is assigned by being asked —
-  // the same consent posture ADR 0187 §3 gives task recommendations.
+  // THE ASKER OR THE ADDRESSEE settles the request: 'answered' when it has been
+  // dealt with, 'withdrawn' when the asker no longer needs it. ADR 0330 widened
+  // 'answered' to the person the request NAMES — once a reply puts the answer on
+  // the row itself, an addressee who has answered in the open and still cannot
+  // close it is a surface arguing with itself. 'withdrawn' stays the asker's
+  // alone: only the person who needed something can say they no longer need it.
+  //
+  // Nobody is assigned by being asked — closing an ask ends a question, it does
+  // not accept work (ADR 0187 §3).
   //
-  // rank: any-builder — ownership is enforced in the UPDATE's WHERE, not by rank.
+  // rank: any-builder — who may settle is enforced in the UPDATE's WHERE, not by
+  // rank. The caller's crafts come from THEIR OWN profile, never from the body,
+  // for the same reason the addressed read refuses a ?craft= it was handed.
   router.patch('/help-requests/:id', api.requireBuilder, asyncHandler('PATCH /help-requests/:id', async (req, res) => {
     const id = parseId(req, res, { code: 'bad_help_request_id', positiveInt: true });
     if (id === null) return;
@@ -110,18 +130,78 @@ module.exports = function buildHelpRequestsRouter() {
       status: { required: true, type: 'string', enum: ['answered', 'withdrawn'] },
     })) return;
 
-    const row = await help.setHelpRequestStatus({ id, builderId: req.builder.id, status: req.body.status });
+    const crafts = await help.craftsForBuilder(req.builder.id);
+    const row = await help.setHelpRequestStatus({
+      id, builderId: req.builder.id, status: req.body.status, crafts,
+    });
     if (!row) {
       // ONE refusal for three cases: absent, someone else's, or already settled.
       // The first version looked the row up to say WHICH, which let a caller
       // enumerate existing ids — and contradicted this very comment (grader, task
       // 1003171). The lookup is gone; the comment and the code now agree.
       return res.fail('help_request_not_settleable', 404, {
-        reason: 'no open help request of yours with that id',
+        reason: 'no open help request with that id that you asked or were asked',
       });
     }
     return res.json({ ok: true, help_request: row });
   }, { errorCode: 'help_request_update_failed' }));
 
+  // ---- replies (task 1004216, ADR 0330) -------------------------------------
+  //
+  // THE HALF THIS SURFACE SHIPPED WITHOUT. A builder could ask, and the asker
+  // could mark their own row answered; the person being ASKED had no write at all,
+  // so the answer happened somewhere Bongos could not see it.
+  //
+  // ANY BUILDER MAY REPLY, deliberately. The board read (GET /help-requests) is
+  // already project-wide, so every member can see every open ask — and a reply
+  // says nothing more private than the ask it hangs under. Restricting replies to
+  // the addressee would also break the common good case: somebody who is not who
+  // you asked turns out to know the answer.
+  //
+  // APPEND-ONLY, with no edit and no delete route. That is not an omission to fill
+  // in later: the table's own trigger refuses an UPDATE or a DELETE, and the
+  // restraint is what keeps this an answer surface rather than the chat surface
+  // ADR 0187 §4a declined to build here.
+  router.post('/help-requests/:id/replies', api.requireBuilder, asyncHandler('POST /help-requests/:id/replies', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_help_request_id', positiveInt: true });
+    if (id === null) return;
+    if (validateOrRespond(req, res, {
+      body: { required: true, type: 'string', minLength: 1, maxLength: help.MAX_REPLY },
+    })) return;
+
+    const v = help.validateReply(req.body);
+    if (!v.ok) return res.fail('invalid_reply', 400, { errors: v.errors });
+
+    // Checked rather than left to the FK, so a reply to an id that never existed
+    // is a named 404 instead of a Postgres string rendered as a 500.
+    const target = await help.getHelpRequest(id);
+    if (!target) return res.fail('help_request_not_found', 404, { reason: 'no help request with that id' });
+
+    const reply = await help.createReply({
+      helpRequestId: id, builderId: req.builder.id, body: req.body.body,
+    });
+    return res.status(201).json({ ok: true, reply });
+  }, { errorCode: 'help_request_reply_failed' }));
+
+  // rank: any-builder, matching the board read this hangs under.
+  //
+  // AN UNKNOWN ID ANSWERS `[]`, NOT 404, and that asymmetry with the POST above is
+  // deliberate rather than an oversight (raised by the grader). This surface has
+  // already had one lesson about existence lookups: PATCH used to look a row up to
+  // say WHICH of three things was wrong, which let a caller enumerate ids by
+  // watching the refusal change. A 404 here would rebuild exactly that oracle on
+  // the cheapest possible request — a GET, repeatable, with nothing written.
+  //
+  // The POST can afford the 404 because it is a WRITE: it costs an attempt, it is
+  // rate-limited by being a write, and a reply to a phantom ask has to fail with a
+  // reason or fail as an FK 500 that tells the caller nothing useful. A read has no
+  // such excuse, and "no replies" is a true answer about an ask that does not exist.
+  router.get('/help-requests/:id/replies', api.requireBuilder, asyncHandler('GET /help-requests/:id/replies', async (req, res) => {
+    const id = parseId(req, res, { code: 'bad_help_request_id', positiveInt: true });
+    if (id === null) return;
+    const replies = await help.listReplies(id);
+    return res.json({ replies, count: replies.length });
+  }, { errorCode: 'help_request_reply_list_failed' }));
+
   return router;
 };