@bongos/core 1.19.1005 → 1.19.1006

package/tests/collab_self_settling.mjs

@@ -0,0 +1,382 @@
+// tests/collab_self_settling.mjs — Collab stops waiting to be told, and settled
+// asks get a two-sided archive (task 1004224, goal 1000095; owner direction
+// 2026-09-24).
+//
+// Two properties are worth more than the rest here, and both are tested by
+// RUNNING the real functions against a recording pool rather than by grepping
+// their source:
+//
+//   1. THE SETTLE TAKES NOTHING FROM A CALLER. The PATCH path's WHERE clause is
+//      the entire permission model for these tables; a second writer of `status`
+//      that accepted an id would be a way to close somebody else's ask. So the
+//      test asserts on the ARITY and on the bound parameters — a settle that
+//      grew a parameter would still pass a source scan for "no req.body here".
+//
+//   2. THE ARCHIVE CANNOT BE WIDENED BY A QUERY PARAM. C01's grader found this
+//      surface's one real hole (a ?craft= validated against the enum and not
+//      against the caller), and an archive is the larger prize because it is the
+//      whole history rather than today's board.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const help = require(path.join(ROOT, 'modules', 'lifecycle', 'help-requests.js'));
+const recs = require(path.join(ROOT, 'modules', 'lifecycle', 'task-recommendations.js'));
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+
+// Records every query the function under test issues, so a test can assert on
+// what actually reached Postgres rather than on what the source appears to say.
+function recorder(rows = []) {
+  const calls = [];
+  return { calls, pool: { query: async (sql, params) => { calls.push({ sql, params }); return { rows }; } } };
+}
+
+// ---- 1. the ledger settles the ask ----------------------------------------
+
+test('a help request naming a SHIPPED task settles itself', async () => {
+  const r = recorder([{ id: 4, task_id: 900 }]);
+  const settled = await help.settleFromLedger({ pool: r.pool });
+  const { sql } = r.calls[0];
+  assert.match(sql, /UPDATE lifecycle_help_requests/);
+  assert.match(sql, /status = 'answered'/, 'the ask is answered, not deleted');
+  assert.match(sql, /settled_reason = 'task_shipped'/, 'and the record says the ledger did it');
+  assert.match(sql, /FROM tasks t WHERE t\.id = h\.task_id AND t\.status = 'shipped'/);
+  assert.deepEqual(settled, [{ id: 4, task_id: 900 }], 'it reports what it settled');
+});
+
+test('an ask with NO task is never settled automatically', async () => {
+  // There is no ledger fact that answers it. Inventing one — treating a reply as
+  // an answer, say — would close the clarifying question that was asking for
+  // more detail.
+  //
+  // ASSERTED AS A PURE CONJUNCTION, not as a substring. The first version of this
+  // matched /h\.task_id IS NOT NULL/ and stayed GREEN when the guard was
+  // neutered to `(h.task_id IS NOT NULL OR TRUE)` — the substring survives its
+  // own defeat, which makes it a test of the spelling rather than of the rule.
+  // Every clause in this WHERE is load-bearing and ANDed; a disjunction anywhere
+  // in it is a widening, so the absence of OR is the property worth pinning.
+  const r = recorder();
+  await help.settleFromLedger({ pool: r.pool });
+  const where = r.calls[0].sql.slice(r.calls[0].sql.indexOf('WHERE'), r.calls[0].sql.indexOf('RETURNING'));
+  assert.match(where, /h\.task_id IS NOT NULL/);
+  assert.ok(!/\bOR\b/.test(where), `the settle predicate is a pure conjunction, so no clause can be bypassed: ${where}`);
+});
+
+test('only a LANDED task settles an ask — not completed, confirmed or abandoned', async () => {
+  // completed and confirmed are stations on the way to landing, and a question
+  // closed at confirmed would reopen as a lie if the ship then stranded. An
+  // abandoned task is the case where the asker most needs the question standing.
+  const r = recorder();
+  await help.settleFromLedger({ pool: r.pool });
+  const { sql } = r.calls[0];
+  for (const status of ['completed', 'confirmed', 'abandoned']) {
+    assert.ok(!sql.includes(`'${status}'`), `${status} must not settle an ask`);
+  }
+});
+
+test('an already-settled ask is not touched again', async () => {
+  const r = recorder();
+  await help.settleFromLedger({ pool: r.pool });
+  assert.match(r.calls[0].sql, /h\.status = 'open'/, 'idempotent, so it is safe on every read');
+});
+
+test('THE SECURITY PROPERTY: the settle accepts nothing a caller could supply', async () => {
+  // The whole reason this is safe to run on an unauthenticated-shaped read path.
+  // Arity FIRST: a settle that grew an `id` or `taskId` parameter would still
+  // pass a source scan for "no req.body in here", and would be a way to close
+  // any row by naming it.
+  // 0, because `deps = {}` is a DEFAULTED parameter and does not count toward
+  // arity. A settle that grew a required `id` or `taskId` would read 1 here.
+  assert.equal(help.settleFromLedger.length, 0, 'no required parameter — no id, no task, no builder');
+  assert.equal(recs.settleFromLedger.length, 0, 'and the same on the recommendations half');
+  const r = recorder();
+  await help.settleFromLedger({ pool: r.pool });
+  assert.equal(r.calls[0].params, undefined, 'and it binds no parameters at all');
+});
+
+// ---- 2. the recommendation settles too ------------------------------------
+
+test('a recommendation settles when its RECIPIENT takes the task up', async () => {
+  const r = recorder([{ id: 2, task_id: 900, recommended_to: 7 }]);
+  await recs.settleFromLedger({ pool: r.pool });
+  const { sql } = r.calls[0];
+  assert.match(sql, /FROM claims c/, 'a claim by the recipient is the signal');
+  assert.match(sql, /c\.builder_id = r\.recommended_to/);
+  assert.match(sql, /t\.shipped_by = r\.recommended_to/, 'or they shipped it');
+});
+
+test('a RELEASED claim does not settle it — handing a task back is not taking it up', async () => {
+  // A builder who claimed and gave the task back has arrived where a decline
+  // arrives, and recording that as 'taken_up' would put a success in the
+  // sender's ledger that did not happen. It is also the indexable shape:
+  // uniq_active_claim_per_task is partial on `released_at IS NULL`, and this
+  // module may not add an index to `claims`, which is a core table it only reads.
+  const r = recorder();
+  await recs.settleFromLedger({ pool: r.pool });
+  const claimBranch = r.calls[0].sql.slice(r.calls[0].sql.indexOf('FROM claims c'),
+    r.calls[0].sql.indexOf('OR EXISTS'));
+  assert.match(claimBranch, /c\.released_at IS NULL/,
+    'only a LIVE claim — a released one is covered by shipped_by if it shipped');
+});
+
+test('a task somebody ELSE shipped does not settle the recommendation', async () => {
+  // That is the case where the recommendation was never taken up at all, and
+  // closing it as taken_up would put a success in the sender's ledger that did
+  // not happen. Both branches are bound to recommended_to; neither is a bare
+  // "the task shipped".
+  const r = recorder();
+  await recs.settleFromLedger({ pool: r.pool });
+  const { sql } = r.calls[0];
+  const shipBranch = sql.slice(sql.indexOf('FROM tasks t'));
+  assert.match(shipBranch, /shipped_by = r\.recommended_to/,
+    'the ship branch names the recipient, so an unrelated ship cannot close it');
+});
+
+test("'taken_up' is NOT an 'accepted' in disguise, and no route can write it", () => {
+  // lifecycle_005's header argues at length that this table must have no
+  // 'accepted': accepting a recommendation IS claiming the task, and a status
+  // here saying so would be a second, weaker record of holding work.
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_012_collab_self_settling.sql');
+  assert.match(sql, /status IN \('open', 'declined', 'withdrawn', 'taken_up'\)/);
+  // Scoped to the STATEMENTS, not the file: the migration's own header argues at
+  // length about why the word is rejected, and a whole-file scan flags that.
+  const statements = sql.split(/\r?\n/).filter((l) => !l.trim().startsWith('--')).join('\n');
+  assert.ok(!/'accepted'/.test(statements), 'the rejected word stays rejected');
+
+  const routes = read('modules', 'lifecycle', 'routes', 'recommendations.js');
+  assert.ok(!/taken_up/.test(routes), 'no route writes it — it is derived, never sent');
+  const lib = read('modules', 'lifecycle', 'task-recommendations.js');
+  const writes = lib.match(/SET status = '[a-z_]+'/g) || [];
+  assert.deepEqual(writes.sort(), ["SET status = 'declined'", "SET status = 'taken_up'", "SET status = 'withdrawn'"],
+    'exactly three status writes, each with its own guard');
+});
+
+// ---- 2b. one settle per burst, not one per route --------------------------
+
+const settle = require(path.join(ROOT, 'modules', 'lifecycle', 'collab-settle.js'));
+
+test('a page load that hits four list routes settles ONCE', async () => {
+  // The defect: settling is idempotent and bounded, so calling it on every read
+  // is correct — but one Collab load fans out across four routes and three of
+  // those UPDATEs wrote nothing. Wasted write volume on a read path, and
+  // avoidable row-lock contention when several builders open Collab at once.
+  settle._reset();
+  let runs = 0;
+  const run = async () => { runs += 1; };
+  await Promise.all([1, 2, 3, 4].map(() => settle.throttled('k', run)));
+  assert.equal(runs, 1, 'four routes, one UPDATE');
+});
+
+test('SERIALLY too — four reads that finish one after another still settle once', async () => {
+  // The concurrent case above is caught by the in-flight promise, not by the
+  // window, so on its own it leaves the window untested: neutering the window
+  // check left it green. A page's reads can also land one after another, and
+  // that is the case only the window covers.
+  settle._reset();
+  let runs = 0;
+  const run = async () => { runs += 1; };
+  for (let i = 0; i < 4; i += 1) await settle.throttled('k', run);
+  assert.equal(runs, 1, 'the window collapses a serial burst too');
+});
+
+test('a concurrent caller AWAITS the in-flight settle rather than skipping it', async () => {
+  // Returning early would hand the second request the PRE-settle rows while
+  // claiming the settle had happened — the two reads of one page load would
+  // then disagree, which is the double-count this whole ordering exists to stop.
+  settle._reset();
+  let resolveRun;
+  let finished = false;
+  const run = () => new Promise((res) => { resolveRun = () => { finished = true; res(); }; });
+  const first = settle.throttled('k', run);
+  // A tick, because the throttle starts `run` in a microtask — without this,
+  // `resolveRun` is still undefined and the test would be measuring its own
+  // scheduling rather than the throttle's.
+  await Promise.resolve();
+  const second = settle.throttled('k', run);
+  resolveRun();
+  await Promise.all([first, second]);
+  assert.ok(finished, 'the second caller did not return before the settle completed');
+});
+
+test('the two tables do not share a window', async () => {
+  // A Collab page load settles help requests; a surface reading recommendations
+  // must not be told the work is done because somebody opened Collab a moment ago.
+  settle._reset();
+  const ran = [];
+  await settle.throttled('help_requests', async () => ran.push('help'));
+  await settle.throttled('task_recommendations', async () => ran.push('recs'));
+  assert.deepEqual(ran, ['help', 'recs']);
+});
+
+test('a FAILED settle does not hold the window shut', async () => {
+  // Marking the window on entry and never clearing would turn one transient
+  // database error into a silent stall for the rest of the window.
+  settle._reset();
+  let runs = 0;
+  await assert.rejects(() => settle.throttled('k', async () => { runs += 1; throw new Error('boom'); }));
+  await settle.throttled('k', async () => { runs += 1; });
+  assert.equal(runs, 2, 'the next read retried instead of waiting the window out');
+});
+
+test('the window is short — a burst collapser, never a staleness budget', () => {
+  // The latency this can add is bounded by the window, so a task that ships now
+  // is reflected on the next load a second later. Minutes would quietly turn a
+  // correctness property into a staleness budget nobody asked for.
+  assert.ok(settle.WINDOW_MS <= 5000, `window is ${settle.WINDOW_MS}ms`);
+});
+
+test('a settle failure is LOGGED, not silently swallowed', () => {
+  // A surface that quietly stopped settling looks exactly like one with nothing
+  // to settle, which is the harder of the two to notice.
+  for (const file of ['help-requests.js', 'recommendations.js']) {
+    const src = read('modules', 'lifecycle', 'routes', file);
+    const fn = src.slice(src.indexOf('async function settleFirst'), src.indexOf('module.exports'));
+    assert.match(fn, /console\.error/, `${file} says so when a settle fails`);
+    assert.match(fn, /settle\.throttled\(/, `${file} settles through the throttle`);
+  }
+});
+
+// ---- 3. the archive, and the hole it must not reopen ----------------------
+
+test('the archive addressee read uses the SAME predicate as the open read', async () => {
+  const r = recorder();
+  await help.listArchivedForBuilder({ builderId: 7, crafts: ['artist'] }, { pool: r.pool });
+  const { sql, params } = r.calls[0];
+  assert.match(sql, /h\.status <> 'open'/, 'settled, the mirror of the open read');
+  assert.match(sql, /h\.requested_by <> \$1/, 'your own settled asks are the OTHER list');
+  assert.match(sql, /h\.needs_builder_id = \$1 OR h\.needs_craft = ANY\(\$2::text\[\]\)/);
+  assert.deepEqual(params[1], ['artist'], 'crafts are bound, never interpolated');
+});
+
+test('a craft the caller does not hold is dropped before it binds', async () => {
+  // The C01 hole, one surface over: a craft value that did not come from the
+  // caller's own profile must never widen a scope.
+  const r = recorder();
+  await help.listArchivedForBuilder({ builderId: 7, crafts: ['wizard', 'ideator'] }, { pool: r.pool });
+  assert.deepEqual(r.calls[0].params[1], ['ideator']);
+});
+
+test('the archive ROUTE reads crafts from the profile and takes nothing from the query', () => {
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  // From the router.get line, not the handler name — requireBuilder sits between
+  // the two, and slicing from the name would silently skip the gate.
+  const idx = routes.indexOf("router.get('/help-requests/archive'");
+  assert.ok(idx > 0, 'the archive route exists');
+  const body = routes.slice(idx, routes.indexOf('errorCode', idx));
+  assert.match(body, /craftsForBuilder\(req\.builder\.id\)/);
+  assert.ok(!/req\.query|req\.body/.test(body), 'no caller-supplied narrowing OR widening');
+  assert.match(body, /api\.requireBuilder/ , 'and it is behind a sign-in like its siblings');
+});
+
+test('both archive reads are BOUNDED like every other read here', async () => {
+  const r = recorder();
+  await help.listArchivedForBuilder({ builderId: 7, crafts: [], limit: 99999 }, { pool: r.pool });
+  assert.equal(r.calls[0].params[2], help.MAX_ROWS, 'an absurd limit is capped, not honoured');
+  const r2 = recorder();
+  await help.listArchivedMine({ builderId: 7, limit: -3 }, { pool: r2.pool });
+  assert.equal(r2.calls[0].params[1], help.MAX_ROWS);
+});
+
+test('the asker-side archive is everything NOT open, not one named status', async () => {
+  // An exact-status filter would need the caller to enumerate the vocabulary,
+  // and the two would drift the next time a status is added.
+  const r = recorder();
+  await help.listArchivedMine({ builderId: 7 }, { pool: r.pool });
+  assert.match(r.calls[0].sql, /h\.requested_by = \$1 AND h\.status <> 'open'/);
+});
+
+// ---- 4. the open blocks and the archive must agree ------------------------
+
+test('every list read settles BEFORE it lists, so a row is never in both at once', () => {
+  // The failure this prevents: a row that settles between two reads of one page
+  // load leaves one block and appears in another in the same render — shown
+  // twice, counted twice, and the figure strip lying about both.
+  const routes = read('modules', 'lifecycle', 'routes', 'help-requests.js');
+  for (const name of ['GET /help-requests/for-me', 'GET /help-requests/mine',
+    'GET /help-requests/archive', 'GET /help-requests']) {
+    const idx = routes.indexOf(`'${name}'`);
+    assert.ok(idx > 0, `${name} exists`);
+    const body = routes.slice(idx, routes.indexOf('errorCode', idx));
+    assert.match(body, /await settleFirst\(\)/, `${name} settles before it lists`);
+    const settleAt = body.indexOf('settleFirst()');
+    const listAt = body.search(/help\.list(Open|Mine|Archived)/);
+    assert.ok(settleAt < listAt, `${name} settles BEFORE the read, not after it`);
+  }
+});
+
+test('the open reads carry the settled facts too, so one projection feeds both', () => {
+  // A hand-built archive-only projection between the query and the page is how a
+  // new field silently stops reaching the renderer that needs it.
+  const lib = read('modules', 'lifecycle', 'help-requests.js');
+  const listCols = lib.slice(lib.indexOf('const LIST_COLS'), lib.indexOf('const LIST_FROM'));
+  assert.match(listCols, /settled_by_login/);
+  assert.match(listCols, /settled_by_name/);
+  assert.match(listCols, /task_title/, 'a task id with no title cannot be rendered as a fact');
+  assert.match(lib, /const COLS = .*settled_reason/, 'and the write path returns the reason it wrote');
+});
+
+// ---- 5. how a row says it ended (pure) ------------------------------------
+
+const L = (() => {
+  const src = read('modules', 'hall-ui', 'public', 'collab-lib.js');
+  const win = {};
+  // eslint-disable-next-line no-new-func
+  new Function('window', src)(win);
+  return win.OTBCollabLib;
+})();
+
+test('an OPEN row has no outcome sentence', () => {
+  assert.equal(L.outcomeLine({ status: 'open' }), '');
+});
+
+test('an automatic close says the LEDGER did it, and names the task', () => {
+  // Rendering it as a bare "Closed" would read as an anonymous person; rendering
+  // it as the asker's act would attribute something nobody did.
+  const line = L.outcomeLine({ status: 'answered', settled_reason: 'task_shipped', task_id: 1004224 });
+  assert.match(line, /by itself/);
+  assert.match(line, /1004224/);
+});
+
+test('a human close names the human', () => {
+  assert.equal(L.outcomeLine({ status: 'answered', settled_by: 9, settled_by_name: 'Lars' }),
+    'Closed by Lars.');
+  // A GENERIC login, not a real one: audit-authorship.sh scans tests too, and a
+  // hardcoded reference to the original Archon fails it (the hit is invisible to
+  // ship-check and surfaces only in CI).
+  assert.equal(L.outcomeLine({ status: 'withdrawn', settled_by: 9, settled_by_login: 'amelia-w' }),
+    'Withdrawn by amelia-w.');
+});
+
+test('a settled row with no settler and no reason still says something true', () => {
+  // Real state: settled before ADR 0330 added settled_by. "Closed." is honest;
+  // a blank right column is not.
+  assert.equal(L.outcomeLine({ status: 'answered' }), 'Closed.');
+  assert.equal(L.outcomeLine({ status: 'withdrawn' }), 'Withdrawn.');
+});
+
+// ---- 6. the migration stays inside the module's own wall ------------------
+
+test('the migration alters only lifecycle-owned tables', () => {
+  // tasks and claims are core tables this module only READS. Fitness check 11
+  // permits a module migration on its own lifecycle_-prefixed tables and nothing
+  // else (ADR 0083 §Decision #5).
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_012_collab_self_settling.sql');
+  const altered = [...sql.matchAll(/ALTER TABLE\s+(\w+)/g)].map((m) => m[1]);
+  assert.ok(altered.length > 0, 'it does alter something');
+  for (const t of altered) {
+    assert.ok(t.startsWith('lifecycle_'), `${t} is not this module's to alter`);
+  }
+});
+
+test('the settle predicates are indexed, since they run on the page load path', () => {
+  const sql = read('modules', 'lifecycle', 'migrations', 'lifecycle_012_collab_self_settling.sql');
+  assert.match(sql, /lifecycle_help_requests_open_task_idx/);
+  assert.match(sql, /lifecycle_task_recommendations_open_task_idx/);
+  assert.match(sql, /lifecycle_help_requests_settled_person_idx/);
+  assert.match(sql, /lifecycle_help_requests_settled_craft_idx/);
+});

package/tests/hall_collab_world.mjs

@@ -230,11 +230,26 @@ test('the door and the copy control are on the row, and the copy control is reac
   // its id, its asker, its task and the instruction — none of which is on the
   // face however short the ask is. So the shortest asks, the ones a session can
   // act on fastest, stopped being the only ones you could not take away.
+  //
+  // AND SINCE TASK 1004224 the control is built into its own `copy` binding
+  // rather than written inline in the bar, because an ARCHIVED row drops it —
+  // copying an ask for a session start is the affordance for going and doing it,
+  // and nobody is waiting on a settled ask. So this reads the binding and the
+  // bar separately. The invariant is unchanged and is what is asserted: the
+  // copy control is gated on `spent` and on nothing else — never on `s.more`,
+  // which would make the shortest asks the only ones you could not take away.
+  const copy = js.slice(js.indexOf('const copy = spent'), js.indexOf(';', js.indexOf('const copy = spent')));
+  assert.match(copy, /Copy for Session Start/, 'the copy control, in the owner\'s words');
+  assert.ok(!/s\.more/.test(copy), 'and it is not gated on there being more to read');
+  assert.ok(!/hidden/.test(copy), 'nor hidden');
+
   const bar = js.slice(js.indexOf('<div class="cb-ask">'), js.indexOf('</div>', js.indexOf('<div class="cb-ask">')));
-  assert.match(bar, /\$\{door\}/, 'the door is in the bar');
-  assert.match(bar, /Copy for Session Start/, 'and so is the copy control, in the owner\'s words');
+  assert.match(bar, /\$\{door\}\$\{copy\}/, 'the door and the copy control share one bar');
   assert.ok(!/hidden/.test(bar), 'the bar itself is never hidden');
-  assert.ok(!/s\.more/.test(bar), 'and the copy control is not gated on there being more to read');
+  // An archived row asks for the words without the affordance, and gets a bar
+  // with neither rather than an empty one.
+  assert.match(js, /if \(!door && !copy\) return html \+ full;/, 'no empty bar when both are absent');
+  assert.match(js, /askHtml\(req, key, true\)/, 'and the archive is the caller that spends it');
   assert.match(js, /<p class="cb-ask__full" id="\$\{fid\}" hidden>/, 'only the ask is hidden');
 
   // What lands on the clipboard is the SESSION START — the skill, the id, the