@bongos/core 1.19.324 → 1.19.326

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 300 endpoints across 47 route files.
+> **Generated from the live route files** — the route file is authoritative. 304 endpoints across 48 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -258,6 +258,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 |---|---|---|---|---|
 | GET | `/api/bongos/healthz` | `public` | — | liveness probe; the status dashboard (status.<apex>) hits this anonymously. |
 
+## `help-requests` (4)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/help-requests` | `any-builder` | `needs_craft`, `needs_builder_id`, `what_is_stuck`, `task_id`, `goal_id` | asking for help is not a privileged act, and gating it would exclude exactly the newcomers most likely to be stuck. |
+| PATCH | `/api/bongos/help-requests/:id` | `any-builder` | `status` | Only the ASKER settles their own request: 'answered' when someone helped, 'withdrawn' when they no longer need it. |
+| GET | `/api/bongos/help-requests/for-me` | `any-builder` | — | The addressed read — C01's answer to "and fires a notification". |
+| GET | `/api/bongos/help-requests/mine` | `any-builder` | — | your own asks, so you can settle them. |
+
 ## `inbox` (14)
 
 | Method | Path | Rank | Body | Description |

package/modules/builder-settings/builder-needs.js

@@ -86,9 +86,42 @@ function artKeyNeed(ctx) {
   };
 }
 
+// ---- someone asked for your help (task 1003171 / C01, goal 1000075) --------
+//
+// The criterion is "a builder who is stuck can post a request for assistance, AND
+// IT REACHES THE RIGHT CRAFT". Storing the request is not reaching anyone, so the
+// reach lands here — the roster every surface already renders (the hall Standing
+// card and the CLI session nudge both read this shape), rather than in a second
+// notification system invented alongside it.
+//
+// ctx.openHelpRequests — count of OPEN requests addressed to this builder, by
+//                        craft or by name. The kernel's /me fills it from the
+//                        lifecycle port; absent (undefined) on an instance whose
+//                        lifecycle module is off, which reads as "nothing asked".
+//
+// It is 'action_needed' because a person is waiting on a human answer — that is
+// exactly what this roster means — and it says WHO ASKED IS WAITING rather than
+// nagging about a setting. Zero requests returns null, not a cheerful
+// "nobody needs you": an empty state is not an input the system needs from you.
+function helpRequestsNeed(ctx) {
+  const n = Number(ctx.openHelpRequests) || 0;
+  if (n <= 0) return null;
+  const people = n === 1 ? 'Someone' : `${n} people`;
+  const verb = n === 1 ? 'has' : 'have';
+  return {
+    id: 'help_requests',
+    title: n === 1 ? 'Someone asked for your help' : 'People asked for your help',
+    what: 'A builder who is stuck addressed a request to your craft, or to you by name.',
+    state: 'action_needed',
+    severity: 'info',
+    message: `${people} ${verb} asked for help you can give. Answering is optional and declining costs nothing.`,
+    action: { label: n === 1 ? 'See the request' : 'See the requests', href: '/#/collab' },
+  };
+}
+
 // The registry. To add a future input the system needs from a builder, append a
 // pure (ctx) => need|null function here — every renderer picks it up for free.
-const NEEDS = [artKeyNeed];
+const NEEDS = [artKeyNeed, helpRequestsNeed];
 
 // ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
 //
@@ -166,6 +199,7 @@ module.exports = {
   computeNeeds,
   // exported for tests / direct reuse
   artKeyNeed,
+  helpRequestsNeed,
   foundingGraceActive,
   FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -393,6 +393,16 @@ function createClient(opts = {}) {
       // GET /healthz — rank: public — GET /healthz
       getHealthz: (args) => request("GET", "/healthz", { hasBody: false }, args),
     },
+    "helpRequests": {
+      // POST /help-requests — rank: any-builder — POST /help-requests
+      postHelpRequests: (args) => request("POST", "/help-requests", { hasBody: true }, args),
+      // PATCH /help-requests/{id} — rank: any-builder — PATCH /help-requests/:id
+      patchHelpRequestsId: (args) => request("PATCH", "/help-requests/{id}", { hasBody: true }, args),
+      // GET /help-requests/for-me — rank: any-builder — GET /help-requests/for-me
+      getHelpRequestsForMe: (args) => request("GET", "/help-requests/for-me", { hasBody: false }, args),
+      // GET /help-requests/mine — rank: any-builder — GET /help-requests/mine
+      getHelpRequestsMine: (args) => request("GET", "/help-requests/mine", { hasBody: false }, args),
+    },
     "inbox": {
       // GET /inbox — rank: any-builder — GET /inbox
       getInbox: (args) => request("GET", "/inbox", { hasBody: false }, args),

package/modules/lifecycle/help-requests.js

@@ -0,0 +1,219 @@
+// modules/lifecycle/help-requests.js — "I am stuck": the data layer for a request
+// for help (task 1003171 / C01, goal 1000075; criterion collab-ask-for-help).
+//
+// A request names WHAT KIND of help it needs — a craft, or one specific person —
+// carries what is stuck, and optionally the task or goal it is about. Craft is the
+// primary axis because the goal's founding premise is that the person you need is
+// often not another one of you.
+//
+// THIS STANDS ALONE ON PURPOSE. The criterion is satisfiable before anything
+// social exists, so nothing here touches closeness, mingle or the Agora — and it
+// must stay that way, or C01 stops being independently shippable.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const { pool } = require('../../src/module-api');
+
+// ADR 0174's crafts. Note the vocabulary seam: `builders.preferred_disciplines`
+// spells this same craft 'engineer', not 'builder'. THIS FUNCTION IS THE ONE PLACE
+// that knows the mapping — the matching surface (C02) must consume it rather than
+// re-deriving, or the two spellings drift and a builder silently matches nothing.
+const HELP_CRAFTS = Object.freeze(['artist', 'builder', 'ideator']);
+const CRAFT_TO_DISCIPLINE = Object.freeze({ artist: 'artist', ideator: 'ideator', builder: 'engineer' });
+
+const DISCIPLINE_TO_CRAFT = Object.freeze({ artist: 'artist', ideator: 'ideator', engineer: 'builder' });
+
+function helpCrafts() { return [...HELP_CRAFTS]; }
+function disciplineForCraft(craft) { return CRAFT_TO_DISCIPLINE[craft] || null; }
+function craftForDiscipline(d) { return DISCIPLINE_TO_CRAFT[d] || null; }
+
+// The caller's OWN crafts, read from builders.preferred_disciplines. This exists
+// because the first version of the addressed read took the craft from a QUERY
+// PARAM and validated it only against the enum — so any authenticated builder
+// could read every open request addressed to a craft they do not belong to, just
+// by trying each value. The route's own comment claimed "you only ever see what is
+// addressed to you", which the code did not do (grader, task 1003171).
+//
+// A builder who has set no disciplines has no crafts, and therefore sees only
+// requests addressed to them BY NAME. That is the correct fail-closed answer:
+// belonging to a craft is a claim about yourself the system should not assume.
+async function craftsForBuilder(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    'SELECT preferred_disciplines FROM builders WHERE id = $1', [builderId]
+  );
+  const list = rows[0] && Array.isArray(rows[0].preferred_disciplines) ? rows[0].preferred_disciplines : [];
+  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 MAX_STUCK = 4000;
+// Defence in depth: both reads are bounded today (open-status churn, per-builder
+// scope), but an unsettled pile should degrade the page, not the server.
+const MAX_ROWS = 200;
+function capRows(n) {
+  const v = Number(n);
+  return Number.isInteger(v) && v > 0 && v <= MAX_ROWS ? v : MAX_ROWS;
+}
+
+// PURE. Returns { ok, errors } — so the route can 400 with named fields before a
+// query runs, and every branch is testable without a database.
+//
+// The rules are the table's CHECK constraints restated in JS on purpose: a
+// constraint violation surfaces as a 500 with a Postgres string, which tells the
+// caller nothing about WHICH field was wrong. The constraints remain the authority;
+// these exist so the refusal is a named 400.
+function validateHelpRequest(input) {
+  const errors = [];
+  const b = input || {};
+  const craft = b.needs_craft == null ? null : String(b.needs_craft);
+  const person = b.needs_builder_id == null ? null : Number(b.needs_builder_id);
+
+  if (craft === null && person === null) {
+    errors.push({ field: null, reason: 'no_addressee' });
+  } else if (craft !== null && person !== null) {
+    // Refused rather than resolved: picking one would send the request somewhere
+    // the asker did not choose.
+    errors.push({ field: null, reason: 'two_addressees' });
+  }
+  if (craft !== null && !HELP_CRAFTS.includes(craft)) {
+    errors.push({ field: 'needs_craft', reason: 'unknown_craft' });
+  }
+  if (person !== null && (!Number.isInteger(person) || person <= 0)) {
+    errors.push({ field: 'needs_builder_id', reason: 'bad_builder_id' });
+  }
+
+  const stuck = typeof b.what_is_stuck === 'string' ? b.what_is_stuck.trim() : '';
+  if (!stuck) errors.push({ field: 'what_is_stuck', reason: 'required' });
+  else if (stuck.length > MAX_STUCK) errors.push({ field: 'what_is_stuck', reason: 'too_long' });
+
+  if (b.task_id != null && b.goal_id != null) {
+    errors.push({ field: null, reason: 'two_contexts' });
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// Existence check so a bad addressee is a named 400 rather than an FK violation
+// rendered as a 500. The constraint stays the authority — this only improves the
+// message, and a row deleted between check and insert still fails safely there.
+async function builderExists(id, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query('SELECT 1 FROM builders WHERE id = $1', [id]);
+  return rows.length > 0;
+}
+
+async function createHelpRequest(input, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_help_requests
+       (requested_by, needs_craft, needs_builder_id, what_is_stuck, task_id, goal_id)
+     VALUES ($1, $2, $3, $4, $5, $6)
+     RETURNING ${COLS}`,
+    [input.requestedBy, input.needsCraft ?? null, input.needsBuilderId ?? null,
+      String(input.whatIsStuck).trim(), input.taskId ?? null, input.goalId ?? null]
+  );
+  return rows[0];
+}
+
+// The read the Collab page (C02) is built on, and the closest thing C01 has to
+// "fires a notification": an addressed request is immediately answerable by the
+// person or craft it names. A real PUSH notification belongs in the builder-needs
+// feed, which is in `builder-settings` — outside this goal's scope wall, so it is
+// recorded as a gap rather than reached for.
+//
+// `craft` is the viewer's craft; `builderId` is the viewer. A request addressed to
+// a person reaches only that person; a craft request reaches everyone of that craft
+// EXCEPT its author, since answering your own request is not help.
+async function listOpenForBuilder({ builderId, crafts = [], limit = MAX_ROWS }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const safeCrafts = (Array.isArray(crafts) ? crafts : []).filter((c) => HELP_CRAFTS.includes(c));
+  const { rows } = await activePool.query(
+    `SELECT ${COLS} FROM lifecycle_help_requests
+      WHERE status = 'open'
+        AND requested_by <> $1
+        AND (needs_builder_id = $1 OR needs_craft = ANY($2::text[]))
+      ORDER BY created_at DESC, id DESC
+      LIMIT $3`,
+    [builderId, safeCrafts, capRows(limit)]
+  );
+  return rows;
+}
+
+// The needs-feed read: how many open requests are addressed to this builder. A
+// COUNT rather than the rows, because the nudge only needs a number and /me runs
+// on every session open — the hot path should not carry request bodies it will
+// not render.
+async function countOpenForBuilder(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  // ONE round trip, not two: the caller's crafts are derived in a subquery rather
+  // than fetched first. This read sits on /me, the session-open hot path, so a
+  // second sequential query is a cost every builder pays on every open (grader).
+  // The discipline->craft mapping is expressed here as SQL and MUST agree with
+  // DISCIPLINE_TO_CRAFT above; craftMapSql() is generated from it so it cannot drift.
+  const { rows } = await activePool.query(
+    `SELECT count(*)::int AS n
+       FROM lifecycle_help_requests h
+      WHERE h.status = 'open'
+        AND h.requested_by <> $1
+        AND (
+          h.needs_builder_id = $1
+          OR h.needs_craft = ANY(
+            SELECT ${craftMapSql('d')}
+              FROM builders b, unnest(b.preferred_disciplines) AS d
+             WHERE b.id = $1
+          )
+        )`,
+    [builderId]
+  );
+  return rows[0] ? rows[0].n : 0;
+}
+
+// The DISCIPLINE_TO_CRAFT map as a SQL CASE, generated from the same object the
+// JS path uses — so the two can never disagree about what an 'engineer' is.
+function craftMapSql(col) {
+  const whens = Object.entries(DISCIPLINE_TO_CRAFT)
+    .map(([d, c]) => `WHEN '${d}' THEN '${c}'`).join(' ');
+  return `CASE ${col} ${whens} ELSE NULL END`;
+}
+
+async function listMine({ builderId, status = null, limit = MAX_ROWS }, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT ${COLS} FROM lifecycle_help_requests
+      WHERE requested_by = $1 AND ($2::text IS NULL OR status = $2)
+      ORDER BY created_at DESC, id DESC
+      LIMIT $3`,
+    [builderId, status, capRows(limit)]
+  );
+  return rows;
+}
+
+async function getHelpRequest(id, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(`SELECT ${COLS} FROM lifecycle_help_requests WHERE id = $1`, [id]);
+  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 = {}) {
+  const activePool = deps.pool || pool;
+  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'
+     RETURNING ${COLS}`,
+    [id, builderId, status]
+  );
+  return rows[0] || null;
+}
+
+module.exports = {
+  HELP_CRAFTS, helpCrafts, disciplineForCraft, craftForDiscipline, craftsForBuilder,
+  validateHelpRequest, MAX_STUCK, MAX_ROWS, capRows,
+  builderExists, createHelpRequest, listOpenForBuilder, listMine, getHelpRequest, setHelpRequestStatus,
+  countOpenForBuilder, craftMapSql,
+};

package/modules/lifecycle/lifecycle.js

@@ -18,6 +18,7 @@
 
 const db = require('./db');
 const classifier = require('./task-classifier');
+const helpRequests = require('./help-requests');
 
 module.exports = {
   // --- retired doorway leaks (ADR 0093 §3) ---------------------------------
@@ -35,6 +36,9 @@ module.exports = {
 
   // --- work-tracking READS the staying-core read routes resolve --------------
   // public.js (the status surface): version/ship feed + grade trend.
+  // task 1003171 (C01): the count of open help requests addressed to a builder,
+  // so the kernel's /me can put it in the needs ctx WITHOUT importing this module.
+  openHelpRequestsFor: (...a) => helpRequests.countOpenForBuilder(...a),
   getTask: (...a) => db.getTask(...a),
   listVersions: (...a) => db.listVersions(...a),
   versionProgress: (...a) => db.versionProgress(...a),

package/modules/lifecycle/migrations/lifecycle_004_help_requests.sql

@@ -0,0 +1,70 @@
+-- lifecycle_004_help_requests.sql — "I am stuck": a request for help that names
+-- who it needs (task 1003171 / C01, goal 1000075; criterion collab-ask-for-help).
+--
+-- WHY CRAFT IS THE PRIMARY AXIS. The goal's founding premise is that the person
+-- you need is often NOT another one of you — an engineer stuck on whether a thing
+-- reads right needs an artist or an ideator, not a second engineer. So a request
+-- addresses a CRAFT, or one specific person by name, and nothing else.
+--
+-- SUB-SPECIALITY IS DELIBERATELY ABSENT. The criterion says "and later on
+-- sub-speciality"; modelling it now would invent a taxonomy before anyone has
+-- asked a real question through this surface.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed, so fitness check 11 permits it: this is
+-- a NEW table the lifecycle module owns outright, unlike `goals`/`tasks` which are
+-- core tables it only queries (ADR 0083 §Decision #5).
+
+CREATE TABLE IF NOT EXISTS lifecycle_help_requests (
+  id                bigserial PRIMARY KEY,
+  requested_by      bigint NOT NULL REFERENCES builders(id),
+
+  -- Exactly ONE of these. A request addressed to everyone is a broadcast, not a
+  -- request for help, and one addressed to nobody cannot be routed at all.
+  needs_craft       text,
+  needs_builder_id  bigint REFERENCES builders(id),
+
+  what_is_stuck     text NOT NULL,
+
+  -- Optional context. At most one: a request is about a task OR a goal, and
+  -- allowing both invites two answers to "what is this about".
+  task_id           bigint REFERENCES tasks(id),
+  goal_id           bigint REFERENCES goals(id),
+
+  status            text NOT NULL DEFAULT 'open',
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+
+  -- The craft vocabulary is ADR 0174's: Artist, Builder, Ideator. Note that
+  -- `builders.preferred_disciplines` spells the same craft 'engineer' — the
+  -- matching surface (C02) must map, and helpCrafts() in help-requests.js is the
+  -- single place that knows it.
+  CONSTRAINT lifecycle_help_requests_craft_chk
+    CHECK (needs_craft IS NULL OR needs_craft IN ('artist', 'builder', 'ideator')),
+
+  CONSTRAINT lifecycle_help_requests_addressee_chk
+    CHECK ((needs_craft IS NOT NULL) <> (needs_builder_id IS NOT NULL)),
+
+  CONSTRAINT lifecycle_help_requests_context_chk
+    CHECK (NOT (task_id IS NOT NULL AND goal_id IS NOT NULL)),
+
+  CONSTRAINT lifecycle_help_requests_stuck_chk
+    CHECK (length(btrim(what_is_stuck)) > 0),
+
+  CONSTRAINT lifecycle_help_requests_status_chk
+    CHECK (status IN ('open', 'answered', 'withdrawn'))
+);
+
+-- The read C02 will live on: "open requests addressed to me". Partial, because a
+-- settled request is history and never needs routing again.
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_open_craft_idx
+  ON lifecycle_help_requests (needs_craft) WHERE status = 'open';
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_open_person_idx
+  ON lifecycle_help_requests (needs_builder_id) WHERE status = 'open';
+CREATE INDEX IF NOT EXISTS lifecycle_help_requests_mine_idx
+  ON lifecycle_help_requests (requested_by, status);
+
+COMMENT ON TABLE lifecycle_help_requests IS
+  'A builder''s request for help, addressed to a craft or one person (task 1003171). Sub-speciality is deliberately not modelled yet.';
+
+INSERT INTO schema_migrations (version) VALUES ('lifecycle_004_help_requests')
+ON CONFLICT (version) DO NOTHING;

package/modules/lifecycle/module.json

@@ -1,14 +1,31 @@
 {
   "key": "lifecycle",
   "title": "Lifecycle (the build state machine)",
-  "description": "The build state machine — tasks · claims · versions · done-when criteria · goals · dependencies · the claim→ship→grade→credit lifecycle · override requests · the ship/confirm/promote orchestration · github-push + merge-lease + conflict-resolve + the publish reconciler. The LAST and most-coupled core domain carved out of the GDS core in BV1.R86 (ADR 0093 §1,§3, 02-module-map §4 — kept whole, never split). default-on; every instance runs the lifecycle. Registers the `lifecycle` kernel PORT (createTask · VOTABLE_TASK_STATUSES · classifyTaskKind · tallyPeerVotes + the work-tracking reads) that core read routes + the ideas/discord/autonomy modules resolve. As a transaction-participant it RESOLVES the `reward` + `onboarding` ports inside its claim/ship/confirm txns — but via resolveOptional (graceful, like sessions→reward), so consumes is empty: a vanilla instance without those modules degrades the credit/onboarding writes to best-effort no-ops, it does not fail.",
+  "description": "The build state machine \u2014 tasks \u00b7 claims \u00b7 versions \u00b7 done-when criteria \u00b7 goals \u00b7 dependencies \u00b7 the claim\u2192ship\u2192grade\u2192credit lifecycle \u00b7 override requests \u00b7 the ship/confirm/promote orchestration \u00b7 github-push + merge-lease + conflict-resolve + the publish reconciler. The LAST and most-coupled core domain carved out of the GDS core in BV1.R86 (ADR 0093 \u00a71,\u00a73, 02-module-map \u00a74 \u2014 kept whole, never split). default-on; every instance runs the lifecycle. Registers the `lifecycle` kernel PORT (createTask \u00b7 VOTABLE_TASK_STATUSES \u00b7 classifyTaskKind \u00b7 tallyPeerVotes + the work-tracking reads) that core read routes + the ideas/discord/autonomy modules resolve. As a transaction-participant it RESOLVES the `reward` + `onboarding` ports inside its claim/ship/confirm txns \u2014 but via resolveOptional (graceful, like sessions\u2192reward), so consumes is empty: a vanilla instance without those modules degrades the credit/onboarding writes to best-effort no-ops, it does not fail.",
   "coreVersion": "^1.12.0",
   "default": true,
-  "maintenance": { "status": "core-maintained" },
+  "maintenance": {
+    "status": "core-maintained"
+  },
   "contributes": {
-    "routes": ["tasks", "claims", "versions", "done-when", "goals", "dependencies", "gate-approvals", "analytics", "lifecycle"],
-    "pollers": ["publish-reconciler"]
+    "routes": [
+      "tasks",
+      "claims",
+      "versions",
+      "done-when",
+      "goals",
+      "dependencies",
+      "gate-approvals",
+      "analytics",
+      "lifecycle",
+      "help-requests"
+    ],
+    "pollers": [
+      "publish-reconciler"
+    ]
   },
-  "provides": ["lifecycle"],
+  "provides": [
+    "lifecycle"
+  ],
   "consumes": []
 }

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

@@ -0,0 +1,117 @@
+// modules/lifecycle/routes/help-requests.js — the write path and the addressed
+// read for "I am stuck" (task 1003171 / C01, goal 1000075; criterion
+// collab-ask-for-help).
+//
+// Four routes, no more: ask, see what is addressed to me, see my own, 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".
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const help = require('../help-requests');
+
+const { asyncHandler, validateOrRespond, parseId } = api;
+
+module.exports = function buildHelpRequestsRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — asking for help is not a privileged act, and gating it
+  // would exclude exactly the newcomers most likely to be stuck.
+  router.post('/help-requests', api.requireBuilder, asyncHandler('POST /help-requests', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      needs_craft: { type: 'string', maxLength: 32 },
+      needs_builder_id: { type: 'integer', min: 1 },
+      what_is_stuck: { required: true, type: 'string', minLength: 1, maxLength: help.MAX_STUCK },
+      task_id: { type: 'integer', min: 1 },
+      goal_id: { type: 'integer', min: 1 },
+    })) return;
+
+    // The table's CHECK constraints are the authority; this restates them so the
+    // refusal names the field instead of surfacing a Postgres string as a 500.
+    const v = help.validateHelpRequest(req.body);
+    if (!v.ok) {
+      return res.fail('invalid_help_request', 400, {
+        errors: v.errors,
+        crafts: help.helpCrafts(),
+      });
+    }
+
+    // A referenced builder that does not exist would otherwise hit the FK and
+    // surface as a generic 500, telling the asker nothing (grader). Checked here
+    // so the refusal names the field; the FK remains the authority.
+    if (req.body.needs_builder_id != null) {
+      const exists = await help.builderExists(req.body.needs_builder_id);
+      if (!exists) {
+        return res.fail('invalid_help_request', 400, {
+          errors: [{ field: 'needs_builder_id', reason: 'no_such_builder' }],
+        });
+      }
+    }
+
+    const row = await help.createHelpRequest({
+      requestedBy: req.builder.id,
+      needsCraft: req.body.needs_craft ?? null,
+      needsBuilderId: req.body.needs_builder_id ?? null,
+      whatIsStuck: req.body.what_is_stuck,
+      taskId: req.body.task_id ?? null,
+      goalId: req.body.goal_id ?? null,
+    });
+    return res.status(201).json({ ok: true, help_request: row });
+  }, { errorCode: 'help_request_failed' }));
+
+  // The addressed read — C01's answer to "and fires a notification". A request is
+  // immediately visible to the person or craft it names. A true PUSH lives in the
+  // builder-needs feed (`builder-settings`), which is outside this goal's scope
+  // wall, so it is recorded as a gap rather than reached for.
+  //
+  // rank: any-builder — you only ever see what is addressed to you.
+  router.get('/help-requests/for-me', api.requireBuilder, asyncHandler('GET /help-requests/for-me', async (req, res) => {
+    // The caller's crafts come from THEIR OWN profile, never from the query — a
+    // ?craft= param validated only against the enum let any builder read requests
+    // addressed to a craft they do not belong to (grader, task 1003171). The param
+    // may now only NARROW what they already have.
+    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 });
+    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 });
+    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.
+  //
+  // rank: any-builder — ownership is enforced in the UPDATE's WHERE, not by rank.
+  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;
+    if (validateOrRespond(req, res, {
+      status: { required: true, type: 'string', enum: ['answered', 'withdrawn'] },
+    })) return;
+
+    const row = await help.setHelpRequestStatus({ id, builderId: req.builder.id, status: req.body.status });
+    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',
+      });
+    }
+    return res.json({ ok: true, help_request: row });
+  }, { errorCode: 'help_request_update_failed' }));
+
+  return router;
+};

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.324",
+  "version": "1.19.326",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/control-manifest.js

@@ -74,6 +74,47 @@ const CONTROLS = [
     wiredIn: { file: '.claude/scheduled-tasks/redteam-weekly/SKILL.md', needle: 'redteam-patrol.js' },
     alsoExists: ['scripts/gds/redteam-patrol.js'],
   },
+
+  // ── goal 1000077's four guards (task 1003169 / G05) ──────────────────────
+  //
+  // Same reasoning as the goal-1000076 controls above, applied to the goal that
+  // exists BECAUSE prose documented four failure modes and nothing refused them.
+  // A guard that can silently stop existing is not a guard — and these four are
+  // exactly the kind that can: three are one line in fitness.js's CHECKS array
+  // (delete the line and the check simply never runs, with nothing red), and the
+  // fourth is a module the ship pipeline requires.
+  //
+  // `alsoExists` names each guard's TEST on purpose. A check whose test is gone
+  // still runs, but nothing then proves it can still fail — and this session
+  // produced three tests that were green for the wrong reason, so an untested
+  // guard is a guard on trust.
+  {
+    label: 'guard: a doc that names a CLI matches the real CLI (G01)',
+    file: 'scripts/gds/doc-cli-guard.js',
+    wiredIn: { file: 'scripts/gds/fitness.js', needle: 'doc-cli-guard' },
+    alsoExists: ['tests/doc_cli_guard.mjs'],
+  },
+  {
+    label: 'guard: no ops script hardcodes a version id (G02)',
+    file: 'scripts/gds/version-literal-guard.js',
+    wiredIn: { file: 'scripts/gds/fitness.js', needle: 'version-literal-guard' },
+    alsoExists: ['tests/version_literals.mjs', 'scripts/gds/version-select.js'],
+  },
+  {
+    label: 'guard: an ops skill declares the machine it needs (G03)',
+    file: 'scripts/gds/skill-preflight.js',
+    wiredIn: { file: 'scripts/gds/fitness.js', needle: 'skill-preflight' },
+    alsoExists: ['tests/skill_preflight.mjs'],
+  },
+  {
+    // Not a fitness check: a module the ship pipeline requires. Wired in
+    // ship-flow.js, which is where the carve left the resume path — and where a
+    // missing import silently broke every regrade until task 1003166 hit it.
+    label: 'guard: a ship cannot lie about how far it got (G04)',
+    file: 'scripts/gds/ship-honesty.js',
+    wiredIn: { file: 'scripts/gds/ship-flow.js', needle: 'ship-honesty' },
+    alsoExists: ['tests/ship_cannot_lie.mjs'],
+  },
 ];
 
 // Pure evaluation — exported for the test. deps.exists/deps.read override fs.
@@ -107,7 +148,7 @@ function checkControlsExist() {
     warnings: [],
     note: violations.length
       ? 'a shipped security/quality control disappeared or came unwired — restore it or update control-manifest.js in the same change'
-      : `all ${CONTROLS.length} goal-1000076 controls present and wired (the assurance-of-assurance the ADR 0022 audit found missing)`,
+      : `all ${CONTROLS.length} controls present and wired — goal 1000076's plus goal 1000077's four guards (task 1003169). The assurance-of-assurance the ADR 0022 audit found missing.`,
   };
 }