@bongos/core 1.19.524 → 1.19.526

package/modules/lifecycle/tests/cascade.mjs

@@ -0,0 +1,197 @@
+// modules/lifecycle/tests/cascade.mjs — the cross-role cascade (task 1003549 /
+// goal 1000074, the artist's loop).
+//
+// The mechanism's whole value is that a ship in one role can generate work in
+// another WITHOUT ever putting that generation in the ship's way. So the four
+// properties the header of cascade.js promises are what these pin, and three of
+// them are about what must NOT happen:
+//
+//   1. it never blocks the ship — every failure shape resolves to a report
+//   2. it is idempotent — the same ship twice files one task
+//   3. it says where it came from
+//   4. it files at backlog, never ready
+//
+// The production table ships EMPTY (R04 writes the first rule), so the rules
+// below are the test's OWN declarations — which is also the point: a mechanism
+// proved by a rule its consumer has not written yet is proved against the
+// contract rather than against one example.
+//
+// DB-free: the runner takes its three database calls as injected functions.
+
+import { strict as assert } from 'node:assert';
+import path from 'node:path';
+import url from 'node:url';
+import { createRequire } from 'node:module';
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const require_ = createRequire(import.meta.url);
+const cascade = require_(path.join(HERE, '..', 'cascade.js'));
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+console.log('\nlifecycle: a ship in one role generates work in another');
+
+const shipped = (over = {}) => ({
+  id: '9001',
+  version_id: 'BONGOS-V1',
+  goal_id: '1000074',
+  title: 'R09 · Reword the hall empty states',
+  discipline: 'engineer',
+  kind: 'feature',
+  status: 'shipped',
+  ...over,
+});
+
+// A rule of the shape R04 will write: an engineer's ship becomes an artist's task.
+const REVIEW_RULE = {
+  key: 'test-artist-review',
+  discipline: 'artist',
+  when: (t) => t.discipline === 'engineer',
+  title: (t) => `Review the copy that shipped in task ${t.id}`,
+  body: (t) => `Look at what ${t.title} put in front of a person.`,
+};
+
+const stubs = (over = {}) => {
+  const created = [];
+  return {
+    created,
+    deps: {
+      rules: [REVIEW_RULE],
+      getTask: async () => shipped(),
+      findTaskBySourceRef: async () => null,
+      createTask: async (spec) => { created.push(spec); return { id: String(9100 + created.length) }; },
+      ...over,
+    },
+  };
+};
+
+await test('an engineer ship files a task FOR THE ARTIST — the push the queues never had', async () => {
+  const { created, deps } = stubs();
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+
+  assert.equal(report.errors.length, 0, report.errors.join(' | '));
+  assert.equal(created.length, 1);
+  const spec = created[0];
+  assert.equal(spec.discipline, 'artist', 'the generated work is for a DIFFERENT role than the ship');
+  assert.equal(report.created[0].discipline, 'artist');
+  assert.match(spec.title, /9001/);
+});
+
+await test('the generated task files at backlog and inherits its goal and version', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  const spec = created[0];
+  assert.equal(spec.status, 'backlog', 'generated work is a REQUEST — auto-filing claimable work mints claims nobody asked for');
+  assert.equal(spec.goalId, 1000074);
+  assert.equal(spec.versionId, 'BONGOS-V1');
+});
+
+await test('it says where it came from, in the ref and in the prose', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  const spec = created[0];
+  assert.equal(spec.source, 'cascade');
+  assert.equal(spec.sourceRef, 'cascade-test-artist-review-9001');
+  assert.match(spec.description, /task 9001 shipped/);
+  assert.match(spec.description, /test-artist-review/);
+  assert.match(spec.description, /Look at what/, 'the rule\'s own body survives the preamble');
+  // NOT a subtask: cascaded work outlives its trigger and belongs to another role.
+  assert.equal(spec.parentTaskId, undefined);
+});
+
+await test('the same ship twice files ONE task — a reconciler re-sweep is a no-op', async () => {
+  const { created, deps } = stubs();
+  await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1);
+
+  // Second pass: the row now exists under the same (source, source_ref).
+  deps.findTaskBySourceRef = async ({ source, sourceRef }) => (
+    source === 'cascade' && sourceRef === 'cascade-test-artist-review-9001' ? { id: '9101' } : null
+  );
+  const again = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1, 'no second row');
+  assert.equal(again.created.length, 0);
+  assert.deepEqual(again.skipped[0], { key: 'test-artist-review', taskId: '9101', reason: 'already filed' });
+});
+
+await test('a rule that does not match files nothing, quietly', async () => {
+  const { created, deps } = stubs({ getTask: async () => shipped({ discipline: 'artist' }) });
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 0);
+  assert.equal(report.errors.length, 0, 'a non-match is not a problem');
+});
+
+// --- property 1: nothing here may reach the ship ----------------------------
+
+await test('NOTHING a cascade does can fail the ship — every failure shape resolves', async () => {
+  const shapes = {
+    'when() throws': stubs({ rules: [{ ...REVIEW_RULE, when: () => { throw new Error('boom'); } }] }),
+    'title() throws': stubs({ rules: [{ ...REVIEW_RULE, title: () => { throw new Error('boom'); } }] }),
+    'createTask rejects': stubs({ createTask: async () => { throw new Error('db down'); } }),
+    'findTaskBySourceRef rejects': stubs({ findTaskBySourceRef: async () => { throw new Error('db down'); } }),
+    'getTask rejects': stubs({ getTask: async () => { throw new Error('db down'); } }),
+    'getTask returns nothing': stubs({ getTask: async () => null }),
+    'a malformed rule': stubs({ rules: [{ key: 'broken' }] }),
+  };
+  for (const [name, { created, deps }] of Object.entries(shapes)) {
+    const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+    assert.ok(report && Array.isArray(report.errors), `${name}: returned a report`);
+    assert.ok(report.errors.length > 0, `${name}: and said what went wrong`);
+    assert.equal(created.length, 0, `${name}: filed nothing`);
+  }
+
+  // The payload itself being junk is the same story.
+  for (const junk of [null, undefined, {}, { id: null }]) {
+    const { deps } = stubs();
+    const report = await cascade.runCascadesForShip(junk, deps);
+    assert.ok(report.errors.length > 0, `${JSON.stringify(junk)}: reported rather than threw`);
+  }
+});
+
+await test('one broken rule costs only its own task', async () => {
+  const good = { ...REVIEW_RULE, key: 'good-one' };
+  const bad = { ...REVIEW_RULE, key: 'bad-one', when: () => { throw new Error('boom'); } };
+  const { created, deps } = stubs({ rules: [bad, good] });
+  const report = await cascade.runCascadesForShip({ id: '9001' }, deps);
+  assert.equal(created.length, 1, 'the healthy rule still filed');
+  assert.equal(created[0].sourceRef, 'cascade-good-one-9001');
+  assert.equal(report.errors.length, 1);
+  assert.match(report.errors[0], /bad-one/);
+});
+
+// --- the declaration itself --------------------------------------------------
+
+await test('the production table is valid, and a duplicate key is refused', () => {
+  assert.deepEqual(cascade.validateCascades(), [], 'the shipped CASCADES table must be well-formed');
+  assert.ok(Array.isArray(cascade.CASCADES));
+  assert.equal(Object.isFrozen(cascade.CASCADES), true);
+
+  // Two rules sharing a key would collide on source_ref and silently suppress
+  // one another — the failure that is invisible in production.
+  const errs = cascade.validateCascades([REVIEW_RULE, { ...REVIEW_RULE }]);
+  assert.equal(errs.length, 1);
+  assert.match(errs[0], /duplicate key/);
+
+  // A rule missing any required field is named, field by field.
+  const shape = cascade.assertRuleShape({ key: 'x' });
+  assert.ok(shape.some((p) => /discipline/.test(p)));
+  assert.ok(shape.some((p) => /when/.test(p)));
+  assert.ok(shape.some((p) => /title/.test(p)));
+  assert.ok(shape.some((p) => /body/.test(p)));
+});
+
+await test('the production table ships EMPTY, deliberately — R04 writes the first rule', () => {
+  // If this fails because a rule was added, that is fine: replace the assertion
+  // with one that pins the new rule's key and discipline. It exists so the
+  // emptiness is a DECISION on the record (see cascade.js's header) rather than
+  // something nobody noticed.
+  assert.equal(cascade.CASCADES.length, 0);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.524",
+  "version": "1.19.526",
   "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/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.524'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.526'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/collab_page.mjs

@@ -97,10 +97,67 @@ test('the page NEVER sends a craft — matching is the server\'s job', () => {
 });
 
 test('a craft request and a by-name request read differently', () => {
+  // `addressedTo` is GONE (task 1003274) — it named the addressee only when the
+  // viewer WAS the addressee, so the asker's own list rendered anonymously, which
+  // is the whole owner report. directionLine replaced it on both axes and had to
+  // take the tonal split with it, which is what this now asserts.
   const L = lib();
-  assert.match(L.addressedTo({ needs_craft: 'artist' }, 1), /artists/);
-  assert.match(L.addressedTo({ needs_builder_id: 7 }, 7), /by name/);
-  assert.match(L.addressedTo({ needs_builder_id: 7 }, 9), /one person/);
+  assert.equal(L.addressedTo, undefined, 'the superseded helper is not left exported');
+  assert.match(L.directionLine({ needs_craft: 'artist' }, 'out'), /artists/);
+  assert.match(L.directionLine({ needs_builder_id: 7, needs_builder_name: 'Ada' }, 'out'), /by name/);
+});
+
+// ── DIRECTION: the owner's report (task 1003274) ────────────────────────────
+//
+// "the ask went to me, not Lars it seems... It says Lars- as your asks but I am
+// not Lars." Nothing was misrouted: the owner was reading their OWN outgoing ask,
+// addressed to Lars, under "Your asks" — and the row said neither who it went to
+// nor which way it pointed. The label read "asked of one person".
+//
+// The reason the old code could not name them is worth keeping: it named the
+// addressee only when the VIEWER was the addressee, so the single most common
+// case for that branch — the asker reading their own list — was the one case it
+// rendered anonymously.
+
+test('THE REPORTED CASE: your own by-name ask names the person you asked', () => {
+  const L = lib();
+  const req = { needs_builder_id: 3, needs_builder_name: 'Lars', requested_by: 1000025 };
+  const line = L.directionLine(req, 'out');
+  assert.match(line, /Lars/, 'the addressee is named — this is the whole bug');
+  assert.match(line, /^You asked/, 'and it says which way it points');
+});
+
+test('DIRECTION cannot be mistaken: outgoing and incoming read as opposites', () => {
+  const L = lib();
+  const out = L.directionLine({ needs_builder_id: 3, needs_builder_name: 'Lars' }, 'out');
+  const inc = L.directionLine({ needs_builder_id: 9, requested_by_name: 'Lars' }, 'in');
+  assert.match(out, /^You asked Lars by name$/);
+  assert.match(inc, /^Lars asked you by name$/);
+});
+
+test('direction comes from the LIST, not from comparing ids', () => {
+  // The two server reads already answer the question by construction
+  // (/help-requests/mine vs /for-me), so directionLine takes no viewer id. That
+  // is what makes the asker's own list impossible to render anonymously — there
+  // is no comparison left to get wrong.
+  const L = lib();
+  assert.equal(L.directionLine.length, 2, 'req + dir, and no viewerId');
+});
+
+test('the craft tone survives — a craft ask is not a personal one', () => {
+  // ADR 0187 §3's split, which the fix was told to keep: "asked of builders" is a
+  // call anyone of that craft may take; a by-name ask is personal and says so.
+  const L = lib();
+  assert.match(L.directionLine({ needs_craft: 'artist' }, 'out'), /^You asked artists$/);
+  assert.match(L.directionLine({ needs_craft: 'artist', requested_by_name: 'Lars' }, 'in'),
+    /^Lars asked artists$/, 'incoming craft asks say the craft, not "you"');
+});
+
+test('an unnamed addressee still says which way it points', () => {
+  // An older server sends no join. Losing the name must not lose the direction.
+  const L = lib();
+  assert.match(L.directionLine({ needs_builder_id: 3 }, 'out'), /^You asked one person$/);
+  assert.match(L.directionLine({ needs_builder_id: 3 }, 'in'), /^Someone asked you by name$/);
 });
 
 test('context links to the task or goal, and to neither when absent', () => {

package/tests/hall_collab_world.mjs

@@ -77,8 +77,25 @@ test('collab renders WHO IS ASKING, as a door to their profile', () => {
   assert.equal(L.askerOf({ requested_by: 92 }), 'builder 92', 'an older server\'s bare id is still a name, never nothing');
   const js = read('collab.js');
   assert.match(js, /L\.askerOf\(req\)/, 'the row asks the lib who is asking');
-  assert.match(js, /\/builders\/profile\?id=\$\{escapeHtml\(String\(req\.requested_by\)\)\}/, 'and links the hall\'s per-builder profile');
-  assert.match(js, /asked by \$\{who\}/, 'as a fact on the row');
+  // The link is built by personLink(id, name) now rather than inline per row —
+  // task 1003274 made BOTH people on a row a door (the asker on an incoming row,
+  // the addressee on your own), so the href moved to one helper taking an id.
+  assert.match(js, /\/builders\/profile\?id=\$\{escapeHtml\(String\(id\)\)\}/,
+    'and links the hall\'s per-builder profile');
+  // The wording is L.directionLine's, not this file's: task 1003274 replaced
+  // "asked by X" with a sentence that also says WHICH WAY the ask points, because
+  // the owner read their own outgoing ask as an incoming one. The sentence is
+  // asserted in tests/collab_page.mjs where the lib can be executed.
+  assert.match(js, /L\.directionLine\(req, dir\)/, 'as a fact on the row');
+  assert.ok(!/asked by \$\{who\}/.test(js), 'the direction-less wording is gone');
+
+  // The link is spliced with a REPLACER FUNCTION. As a replacement STRING,
+  // `$&`/`$$`/"$`"/`$'` inside it are special to String.prototype.replace — and
+  // the name it carries is builder-chosen. Measured: a display_name of `$&Bob`
+  // rendered as `$&Bobamp;Bob`. Not an injection (both halves are escaped),
+  // but a way to corrupt your own row by picking a name.
+  assert.match(js, /\.replace\(escapeHtml\(name\), \(\) => link\)/,
+    'the replacement is a function, so $-sequences in a name are literal');
 });
 
 test('the server names the people on a row through a join, and the writes stay bare', () => {
@@ -115,7 +132,9 @@ test('"asked of you" reads in runs — by name first, then each craft', () => {
   const L = lib();
   assert.equal(L.groupOf({ needs_builder_id: 95 }).id, 'you');
   assert.equal(L.groupOf({ needs_craft: 'artist' }).label, 'asked of artists');
-  assert.match(L.addressedTo({ needs_builder_id: 7, needs_builder_name: 'Preview Alpha' }, 9), /Preview Alpha by name/, 'a named addressee is named');
+  // task 1003274: the naming moved to directionLine, which also says WHICH WAY
+  // the ask points — the half the owner's report was actually about.
+  assert.match(L.directionLine({ needs_builder_id: 7, needs_builder_name: 'Preview Alpha' }, 'out'), /Preview Alpha by name/, 'a named addressee is named');
   const js = read('collab.js');
   assert.match(js, /ov-group__head/, 'each run has the family\'s group head');
   assert.match(js, /Number\(b\.id === 'you'\) - Number\(a\.id === 'you'\)/, 'and the personal run sorts first');