@bongos/core 1.19.524 → 1.19.526

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/gds/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 1646,
-    "unique_ids": 1428,
-    "certain": 1646,
+    "strings": 1645,
+    "unique_ids": 1427,
+    "certain": 1645,
     "heuristic": 0,
     "duplicate_ids": 154
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 73,
-      "strings": 1188
+      "strings": 1187
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -2072,7 +2072,7 @@
       "surface": "builders-hall",
       "text": "A {…} — you are a {…}. Mingle pairs across crafts.",
       "file": "modules/hall-ui/public/collab.js",
-      "line": 173,
+      "line": 196,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -3467,7 +3467,7 @@
       "surface": "builders-hall",
       "text": "Could not load requests.",
       "file": "modules/hall-ui/public/collab.js",
-      "line": 251,
+      "line": 274,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -6383,7 +6383,7 @@
       "surface": "builders-hall",
       "text": "Not now",
       "file": "modules/hall-ui/public/collab.js",
-      "line": 173,
+      "line": 196,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -7760,7 +7760,7 @@
       "surface": "builders-hall",
       "text": "Say yes",
       "file": "modules/hall-ui/public/collab.js",
-      "line": 173,
+      "line": 196,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8246,7 +8246,7 @@
       "surface": "builders-hall",
       "text": "Someone helped",
       "file": "modules/hall-ui/public/collab.js",
-      "line": 90,
+      "line": 113,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10302,15 +10302,6 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
-    {
-      "id": "09db3fd4355b",
-      "surface": "builders-hall",
-      "text": "asked by {…}",
-      "file": "modules/hall-ui/public/collab.js",
-      "line": 69,
-      "origin": "js-markup",
-      "confidence": "certain"
-    },
     {
       "id": "63bd14f73960",
       "surface": "builders-hall",

package/docs/module-api-changelog.md

@@ -1485,5 +1485,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.522 with no explicit bump. run 33816191865. (task 1002620)
   1.19.524 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.523 with no explicit bump. run 33818285201. (task 1002620)
+  1.19.525 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.524 with no explicit bump. run 33823218193. (task 1002620)
+  1.19.526 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.525 with no explicit bump. run 33824700579. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -51,19 +51,42 @@
     return (ta || 0) - (tb || 0);
   }
 
-  // Who a request is addressed to, in words. A craft request and a by-name
-  // request read differently on purpose: "asked of builders" is a call anyone of
-  // that craft may take, "asked of you" is personal and should feel it. A
-  // by-name ask that is not yours names the person when the server joined a
-  // name, and says "one person" when it did not.
-  function addressedTo(req, viewerId) {
-    if (req && req.needs_builder_id != null) {
-      if (String(req.needs_builder_id) === String(viewerId)) return 'asked of you by name';
-      var name = req.needs_builder_name || req.needs_builder_login;
-      return name ? 'asked of ' + name + ' by name' : 'asked of one person';
+  // `addressedTo(req, viewerId)` WAS HERE and is gone (task 1003274). It named
+  // the addressee only when the VIEWER was the addressee, which is why the
+  // asker's own list — the most common case for that branch — rendered "asked of
+  // one person" and produced the owner's report. directionLine below supersedes
+  // it on both axes (it names the person AND says which way the ask points), and
+  // it had no other caller, so keeping it would have left a second, wronger
+  // answer to the same question sitting exported next to the right one.
+
+  // DIRECTION, in words (owner report, task 1003274). The report is the whole
+  // reason this exists: the owner read their own outgoing ask, addressed to Lars,
+  // sitting under "Your asks", and concluded it had been sent to the wrong person.
+  // Nothing was misrouted — the row simply never said WHO, and never said which
+  // way it pointed.
+  //
+  // DIRECTION IS THE LIST, NOT A COMPARISON. `dir` is 'out' for your own asks and
+  // 'in' for what was asked of you, because the two server reads already answer
+  // that question by construction (GET /help-requests/mine vs /for-me). Deriving
+  // it instead from `requested_by === viewerId` is what the old code did, and it
+  // is how a page with no viewer id in hand ends up rendering the anonymous
+  // fallback for the single most common case — the asker reading their own list.
+  //
+  // The tonal split the report asks to KEEP: a craft ask is a call anyone of that
+  // craft may take; a by-name ask is personal and says so.
+  function directionLine(req, dir) {
+    if (!req) return '';
+    var craft = req.needs_craft;
+    if (dir === 'out') {
+      if (req.needs_builder_id != null) {
+        var to = req.needs_builder_name || req.needs_builder_login;
+        return to ? 'You asked ' + to + ' by name' : 'You asked one person';
+      }
+      return craft ? 'You asked ' + craft + 's' : 'You asked';
     }
-    if (req && req.needs_craft) return 'asked of ' + req.needs_craft + 's';
-    return 'asked';
+    var who = askerOf(req) || 'Someone';
+    if (req.needs_builder_id != null) return who + ' asked you by name';
+    return craft ? who + ' asked ' + craft + 's' : who + ' asked';
   }
 
   // Who is ASKING, in words — the fact a helper needs to answer. The name the
@@ -107,7 +130,8 @@
 
   window.OTBCollabLib = {
     BANDS: BANDS, ageBand: ageBand, byAgeOldestFirst: byAgeOldestFirst,
-    addressedTo: addressedTo, askerOf: askerOf, contextOf: contextOf,
+    askerOf: askerOf, contextOf: contextOf,
+    directionLine: directionLine,
     titleOf: titleOf, groupOf: groupOf,
   };
 })();

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

@@ -59,14 +59,37 @@
     return `<a class="fact-chip" href="${escapeHtml(ctx.href)}">${escapeHtml(ctx.kind)} #${escapeHtml(String(ctx.id))}</a>`;
   }
 
-  // Who to answer: the asker's name, as a door to their profile.
-  function askerFact(req) {
-    const name = L.askerOf(req);
+  // A name as a door to that builder's profile, or plain text when the server
+  // sent no id to link to.
+  function personLink(id, name) {
     if (!name) return '';
-    const who = req.requested_by != null
-      ? `<a href="/builders/profile?id=${escapeHtml(String(req.requested_by))}">${escapeHtml(name)}</a>`
+    return id != null
+      ? `<a href="/builders/profile?id=${escapeHtml(String(id))}">${escapeHtml(name)}</a>`
       : escapeHtml(name);
-    return `<span class="ov-fact">asked by ${who}</span>`;
+  }
+
+  // DIRECTION, on the row (owner report, task 1003274): "<name> asked you by
+  // name" incoming, "You asked <name> by name" outgoing — so an outgoing ask can
+  // never be mistaken for an incoming one, which is exactly the mistake the
+  // report describes. The sentence itself is L.directionLine (pure, tested); this
+  // only splices the profile link over the person's name inside it, so the words
+  // a test asserts and the words a builder reads cannot drift.
+  function directionFact(req, dir) {
+    const line = L.directionLine(req, dir);
+    if (!line) return '';
+    const name = dir === 'in' ? L.askerOf(req) : (req.needs_builder_name || req.needs_builder_login);
+    const id = dir === 'in' ? req.requested_by : req.needs_builder_id;
+    const link = personLink(id, name);
+    // The replacement is a FUNCTION, not a string. String.prototype.replace
+    // treats `$&`, `$$`, "$`" and `$'` specially in a string replacement, and the
+    // name here is builder-controlled (a display_name or login) — so a display
+    // name containing `$&` would duplicate or mangle the sentence around it. Not
+    // an injection (both halves are escaped either way), but a real way to
+    // corrupt someone else's row by choosing your own name.
+    const html = (name && link)
+      ? escapeHtml(line).replace(escapeHtml(name), () => link)
+      : escapeHtml(line);
+    return `<span class="ov-fact">${html}</span>`;
   }
 
   // A row for the "asked of you" list. There is deliberately NO "claim this"
@@ -77,7 +100,7 @@
   function forMeRow(req, nowMs) {
     return `<li class="ov-row" data-id="${escapeHtml(String(req.id))}">
       <div class="ov-row__main">${titleHtml(req)}
-        <div class="ov-row__facts">${askerFact(req)}${contextChip(req)}</div>
+        <div class="ov-row__facts">${directionFact(req, 'in')}${contextChip(req)}</div>
       </div>
       <div class="ov-row__right">${ageChip(req, nowMs)}${whenLine(req.created_at)}</div>
     </li>`;
@@ -89,7 +112,7 @@
     const id = escapeHtml(String(req.id));
     return `<li class="ov-row" data-id="${id}">
       <div class="ov-row__main">${titleHtml(req)}
-        <div class="ov-row__facts"><span class="ov-fact">${escapeHtml(L.addressedTo(req, null))}</span>${contextChip(req)}</div>
+        <div class="ov-row__facts">${directionFact(req, 'out')}${contextChip(req)}</div>
       </div>
       <div class="ov-row__right">${ageChip(req, nowMs)}
         <div class="ov-row__actions">

package/modules/lifecycle/cascade.js

@@ -0,0 +1,238 @@
+'use strict';
+
+// modules/lifecycle/cascade.js — a ship in one role GENERATES work in another
+// (task 1003549, goal 1000074's the artist's loop; the split R04 asked for).
+//
+// WHAT WAS MISSING, precisely — the gap is PUSH vs PULL. Two surfaces already
+// let one role take work from another, and both are LISTINGS of rows somebody
+// had already created: the spark queue (goal 1000062 / task 1002921) returns
+// open sparks awaiting development, and the copy-desk flag queue (R02 / task
+// 1003113) returns surfaces anyone flagged. A role could READ what another
+// produced; nothing GENERATED work on a state transition. R04's requirement is
+// the other direction — "every ship with copy or visuals generates one [review
+// task]", automatic, never hand-filed — and there was no mechanism for it.
+//
+// WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT. It is a DECLARATION TABLE plus
+// a runner, not a rules engine. A cascade is one frozen entry saying: when a
+// shipped task looks like THIS, file THAT task, for THAT discipline. There is no
+// condition language, no stored rules, no per-project configuration and no UI —
+// every one of those is a thing to add when a second and third cascade exist and
+// have shown what they have in common. Today `CASCADES` ships EMPTY: the
+// mechanism, its idempotency and its non-blocking property are proved by the
+// tests' own declarations, and R04 (task 1003115) writes the first production
+// entry. A mechanism whose first real rule is written by the task that needs it
+// is honest; one that ships a rule nobody asked for is a guess.
+//
+// THE FOUR PROPERTIES THAT MAKE IT SAFE, each of which the tests pin:
+//
+//   1. IT NEVER BLOCKS THE SHIP IT REACTS TO. The runner is driven by the
+//      `task.shipped` kernel event, which fires POST-COMMIT and whose emitters
+//      already wrap it in try/catch; on top of that `runCascadesForShip` catches
+//      everything and returns a report. A cascade that throws, or a database
+//      that is down, changes nothing about the ship — the work is landed, graded
+//      and paid before this code runs at all. This is not a nicety: ADR 0241
+//      settled that an artist's review may hold a DEPLOY and never a builder's
+//      ship, and a generator that could fail a ship would smuggle that gate back
+//      in through the back door.
+//
+//   2. IT IS IDEMPOTENT, using machinery that already exists. Each generated
+//      task carries `source: 'cascade'` and `source_ref: cascade-<key>-<id>`,
+//      and `createTask`'s (source, source_ref) idempotency read returns the
+//      original row instead of minting a second one. So a reconciler re-sweep, a
+//      re-ship, or both emitters firing for the same task are no-ops. The
+//      runner ALSO checks first, so the common case is a read rather than a
+//      write that gets rejected.
+//
+//   3. IT SAYS WHERE IT CAME FROM. Every generated task inherits the source
+//      task's `goal_id` and `version_id`, carries the originating task's id
+//      inside its `source_ref`, and opens its description with that id and the
+//      rule key. A task that appears on the board with no author has to be able
+//      to explain itself, or the next person deletes it. NOT `parent_task_id`:
+//      that column models a SUBTASK, and cascaded work is not a part of the ship
+//      that triggered it — it is separate work, for a different role, that
+//      outlives its trigger. The attribution belongs in the ref and the prose.
+//
+//   4. IT FILES AT `backlog`, NEVER `ready`. Generated work is a REQUEST, and
+//      it goes through the board's ordinary triage like a copy proposal (ADR
+//      0233 §6) or any capture. Auto-filing claimable work would let a rule
+//      nobody re-read mint claims.
+//
+// PURE ABOVE `runCascadesForShip`: the declaration shape, the matching and the
+// task spec are all synchronous functions over plain objects, so a cascade can
+// be pinned without a database.
+
+// ---------------------------------------------------------------------------
+// The declaration
+// ---------------------------------------------------------------------------
+
+// A cascade rule:
+//   key         string, stable + unique. It is half the source_ref, so RENAMING
+//               a key re-files every task the rule ever generated. Treat it as
+//               permanent.
+//   discipline  the role the generated work is FOR ('artist', 'ideator',
+//               'engineer'). This is the whole point of the mechanism: the
+//               discipline of the generated task is not the discipline of the
+//               ship that caused it.
+//   when(task)  a predicate over the shipped task row. Must be pure and total —
+//               a throw is caught and treated as "no match", because a broken
+//               predicate must not stop the other rules.
+//   title(task) / body(task)  the generated task's title and description.
+//   kind        optional task kind; defaults to 'chore'.
+//
+// Production rules live here. It is empty by design — see the header.
+const CASCADES = Object.freeze([]);
+
+// The (source, source_ref) pair the generated task is keyed on. `source` is a
+// constant so every cascade-generated row is findable as a class; the ref pins
+// it to one rule and one originating ship.
+const CASCADE_SOURCE = 'cascade';
+
+function cascadeSourceRef(ruleKey, sourceTaskId) {
+  return `cascade-${ruleKey}-${sourceTaskId}`;
+}
+
+// Validate a declaration at the moment it is used rather than trusting it. A
+// malformed rule is a wiring bug that should be loud in a test, not a silent
+// missing task in production six weeks later.
+function assertRuleShape(rule) {
+  const problems = [];
+  if (!rule || typeof rule !== 'object') return ['rule is not an object'];
+  if (typeof rule.key !== 'string' || !rule.key) problems.push('key must be a non-empty string');
+  if (typeof rule.discipline !== 'string' || !rule.discipline) problems.push('discipline must be a non-empty string');
+  if (typeof rule.when !== 'function') problems.push('when must be a function');
+  if (typeof rule.title !== 'function') problems.push('title must be a function');
+  if (typeof rule.body !== 'function') problems.push('body must be a function');
+  return problems;
+}
+
+// Every rule in a table, checked, with duplicate keys reported — two rules
+// sharing a key would collide on source_ref and silently suppress one another.
+function validateCascades(rules = CASCADES) {
+  const errors = [];
+  const seen = new Set();
+  rules.forEach((rule, i) => {
+    for (const p of assertRuleShape(rule)) errors.push(`cascade[${i}]: ${p}`);
+    const key = rule && rule.key;
+    if (typeof key === 'string' && key) {
+      if (seen.has(key)) errors.push(`cascade[${i}]: duplicate key "${key}" — keys are half the source_ref and must be unique`);
+      seen.add(key);
+    }
+  });
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Matching + the generated task spec
+// ---------------------------------------------------------------------------
+
+// The task rows a shipped task cascades into. Pure: no database, no clock, no
+// side effect — hand it a task-shaped object and a rule table and it returns
+// the specs that would be filed.
+//
+// A rule whose `when` THROWS is treated as no-match and reported in `errors`,
+// never propagated: one broken predicate must not cost the other rules their
+// tasks, and it certainly must not reach the ship.
+function cascadesFor(task, rules = CASCADES) {
+  const matched = [];
+  const errors = [];
+  if (!task || task.id == null) return { matched, errors: ['no task'] };
+  for (const rule of rules) {
+    const shape = assertRuleShape(rule);
+    if (shape.length) { errors.push(`cascade "${rule && rule.key}": ${shape.join('; ')}`); continue; }
+    let hit = false;
+    try {
+      hit = rule.when(task) === true;
+    } catch (e) {
+      errors.push(`cascade "${rule.key}": when() threw (${e && e.message}) — treated as no match`);
+      continue;
+    }
+    if (!hit) continue;
+    try {
+      matched.push({ rule, spec: cascadeTaskSpec(rule, task) });
+    } catch (e) {
+      errors.push(`cascade "${rule.key}": title/body threw (${e && e.message})`);
+    }
+  }
+  return { matched, errors };
+}
+
+// The createTask payload for one matched rule. The attribution preamble is
+// prepended here rather than left to each rule, so no rule can forget it.
+function cascadeTaskSpec(rule, task) {
+  const body = String(rule.body(task) || '').trim();
+  const preamble =
+    `Filed automatically when task ${task.id} shipped — the "${rule.key}" cascade `
+    + `(modules/lifecycle/cascade.js). Nobody typed this; it is a REQUEST, filed at backlog, `
+    + `and it goes through the board's ordinary triage. If the rule that made it is wrong, fix `
+    + `the rule rather than only this task.`;
+  return {
+    versionId: task.version_id,
+    goalId: task.goal_id != null ? Number(task.goal_id) : null,
+    title: String(rule.title(task) || '').trim(),
+    description: `${preamble}\n\n${body}`,
+    discipline: rule.discipline,
+    kind: rule.kind || 'chore',
+    status: 'backlog',
+    source: CASCADE_SOURCE,
+    sourceRef: cascadeSourceRef(rule.key, task.id),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The runner — the only part that touches a database
+// ---------------------------------------------------------------------------
+
+// React to one shipped task. Returns a report, NEVER throws and never rejects:
+// property 1 in the header. `deps` is injected so the whole runner is testable
+// with two stubs and no database.
+//
+//   deps.getTask(id)                 -> the full task row (the event payload is
+//                                       the ship RETURNING row and carries no
+//                                       goal_id / version_id / discipline)
+//   deps.findTaskBySourceRef({...})  -> an existing row or null
+//   deps.createTask(spec)            -> the created row
+//   deps.log                         -> optional { info, error }
+async function runCascadesForShip(shipped, deps = {}) {
+  const report = { created: [], skipped: [], errors: [] };
+  const log = deps.log || null;
+  try {
+    const id = shipped && (shipped.id ?? shipped.task_id);
+    if (id == null) { report.errors.push('cascade: ship payload carried no task id'); return report; }
+
+    const task = deps.getTask ? await deps.getTask(id) : null;
+    if (!task) { report.errors.push(`cascade: task ${id} not readable after ship`); return report; }
+
+    const { matched, errors } = cascadesFor(task, deps.rules || CASCADES);
+    report.errors.push(...errors);
+
+    for (const { rule, spec } of matched) {
+      try {
+        const existing = deps.findTaskBySourceRef
+          ? await deps.findTaskBySourceRef({ source: CASCADE_SOURCE, sourceRef: spec.sourceRef })
+          : null;
+        if (existing) { report.skipped.push({ key: rule.key, taskId: existing.id, reason: 'already filed' }); continue; }
+        const created = await deps.createTask(spec);
+        report.created.push({ key: rule.key, taskId: created && created.id, discipline: rule.discipline });
+        log?.info?.(`[cascade] task ${id} shipped → filed ${created && created.id} for ${rule.discipline} ("${rule.key}")`);
+      } catch (e) {
+        // One rule failing costs that rule its task and nothing else.
+        report.errors.push(`cascade "${rule.key}": ${e && e.message}`);
+      }
+    }
+  } catch (e) {
+    report.errors.push(`cascade: ${e && e.message}`);
+  }
+  if (report.errors.length) log?.error?.(`[cascade] ${report.errors.length} problem(s): ${report.errors.join(' | ')}`);
+  return report;
+}
+
+module.exports = {
+  CASCADES,
+  CASCADE_SOURCE,
+  cascadeSourceRef,
+  assertRuleShape,
+  validateCascades,
+  cascadesFor,
+  cascadeTaskSpec,
+  runCascadesForShip,
+};

package/modules/lifecycle/routes/lifecycle.js

@@ -26,11 +26,36 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const lifecycle = require('../lifecycle');
+const db = require('../db');
+const cascade = require('../cascade');
+
+// task 1003549 — the cross-role cascade listener. `task.shipped` already exists
+// as a kernel event (emitted post-commit by the publish reconciler and the ship
+// routes, consumed today by discord's broadcast and sessions' deferred reward),
+// so a ship generating work in ANOTHER role needs no new bus: it is one more
+// listener on the event that already says a ship happened. Registered here for
+// the same reason the port is — `mountModuleRoutes` is the one boot hook that
+// runs in the live server AND whenever a test rebuilds the router.
+//
+// The handle is kept so a re-mount replaces the listener instead of stacking a
+// second one (the discord `_shipListenerOff` precedent); a doubled listener
+// would be harmless anyway, since filing is idempotent on (source, source_ref),
+// but "harmless because something downstream catches it" is not a reason to
+// leave it. Nothing here can affect the ship: the emitters fire post-commit and
+// already wrap the emit, and `runCascadesForShip` resolves rather than throws.
+let _cascadeListenerOff = null;
 
 function registerSeams() {
   if (!api.hasProvider('lifecycle')) {
     api.registerProvider('lifecycle', lifecycle);
   }
+  if (_cascadeListenerOff) _cascadeListenerOff();
+  _cascadeListenerOff = api.on('task.shipped', (shipped) => cascade.runCascadesForShip(shipped, {
+    getTask: (id) => db.getTask(id),
+    findTaskBySourceRef: (ref) => db.findTaskBySourceRef(ref),
+    createTask: (spec) => db.createTask(spec),
+    log: api.logger ? api.logger('lifecycle') : null,
+  }));
 }
 
 module.exports = function buildLifecycleRouter() {