@bongos/core 1.19.804 → 1.19.806

package/tests/session_upload_health.mjs

@@ -0,0 +1,329 @@
+// tests/session_upload_health.mjs — the session-upload outage signal
+// (task 1003865, goal 1000118).
+//
+// THE INCIDENT. A Windows path-encoding bug made every transcript lookup miss, so
+// each ship skipped its session upload with `transcript_not_found`. No
+// session_records row was written, so no `session.token_reward` credit booked, and
+// since ADR 0146 made cost-plus the SOLE reward stream the affected builder earned
+// nothing for real shipped work — for weeks, before a human noticed. The only
+// trace was a jsonl file on that builder's own laptop, which never reaches the
+// server: from here, a skipped upload and a builder who did not work are the same
+// absence.
+//
+// WHAT THIS FILE PINS, in order of what would actually go wrong:
+//   (1) the firing condition, against the REAL outage window's measured numbers;
+//   (2) that it stays quiet on the real healthy months, because a check that
+//       cries wolf is the state we started in with extra steps;
+//   (3) that the predicate never touches session_records.task_ids, which is EMPTY
+//       on 54% of rows and would report the linkage gap as an outage;
+//   (4) that the alert names the builder, the arithmetic, and the consequence.
+//
+// Run:  node tests/session_upload_health.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const health = require('../modules/sessions/upload-health.js');
+const poller = require('../modules/sessions/pollers/session-upload-health.js');
+
+// ---------------------------------------------------------------------------
+// (1)+(2) THE REAL NUMBERS.
+//
+// Measured 2026-09-16 against the live corpora (4,495 session records and 2,640
+// ships carrying shipped_at + shipped_by, paged out of /sessions/search and
+// /tasks), replaying the check as a rolling 14-day lookback stepped one day at a
+// time over the ~92 evaluable days. These are per-builder counts within one
+// lookback, not inventions: the OUTAGE rows are the real peak, and the HEALTHY
+// rows are the real 2026-09 shape the same sweep saw.
+//
+// The COUNTS are the measurement and are exact. The logins are NOT — real builder
+// identities have no business in a fixture (audit-authorship.sh forbids the
+// founder's outright, and the others are people too), so they are anonymised to
+// the roles that matter: the builder whose uploads broke, and the ones whose
+// did not.
+// ---------------------------------------------------------------------------
+
+// 2026-07-25, the peak of the outage: one builder, 19 ships, not one covered.
+// The row's own account says "at least 16 ships" — this found 19 without being
+// told where to look.
+const OUTAGE_PEAK = [
+  { builder_id: '900001', github_login: 'affected-builder', ships: 19, uncovered: 19 },
+  { builder_id: '900002', github_login: 'healthy-builder', ships: 41, uncovered: 0 },
+];
+
+// 2026-08-05, the last day the sweep fired — a PARTIAL outage, which is the shape
+// that matters most: a check tuned only to total failure would have gone quiet
+// here while the builder was still losing pay.
+const OUTAGE_TAIL = [
+  { builder_id: '900001', github_login: 'affected-builder', ships: 30, uncovered: 11 },
+  { builder_id: '900002', github_login: 'healthy-builder', ships: 22, uncovered: 0 },
+];
+
+// A healthy fortnight: the real 2026-09 shape (0.2% corpus-wide uncovered).
+const HEALTHY = [
+  { builder_id: '900003', github_login: 'third-builder', ships: 200, uncovered: 0 },
+  { builder_id: '900001', github_login: 'affected-builder', ships: 147, uncovered: 1 },
+  { builder_id: '900002', github_login: 'healthy-builder', ships: 78, uncovered: 0 },
+];
+
+test('it fires on the real outage peak, and says whose machine', () => {
+  const v = health.uploadHealthVerdict(OUTAGE_PEAK);
+  assert.equal(v.firing, true, 'the outage this task was filed about must fire');
+  assert.equal(v.status, 'uploads-missing');
+  assert.equal(v.offenders.length, 1, 'exactly the one builder, not the whole roster');
+  assert.equal(v.offenders[0].github_login, 'affected-builder');
+  // Naming the builder is what makes it actionable — the failure was one machine.
+  assert.match(v.reason, /affected-builder/);
+  assert.match(v.reason, /19 of 19/, 'carries its own arithmetic');
+  // And it must say what a missing row COSTS, or it reads as missing telemetry.
+  assert.match(v.reason, /reward is not booking/i);
+});
+
+test('it still fires on the partial tail of the same outage', () => {
+  // 11 of 30 is 36.7% — well under half. A threshold set at "mostly broken" would
+  // have gone quiet here while the builder was still losing pay for real ships.
+  const v = health.uploadHealthVerdict(OUTAGE_TAIL);
+  assert.equal(v.firing, true);
+  assert.equal(v.offenders[0].github_login, 'affected-builder');
+  assert.ok(v.offenders[0].uncovered_share < 0.5, 'and it is genuinely a partial outage');
+});
+
+test('it stays quiet on the real healthy month', () => {
+  const v = health.uploadHealthVerdict(HEALTHY);
+  assert.equal(v.firing, false, 'a healthy fortnight must not page anyone');
+  assert.equal(v.status, 'healthy');
+  assert.deepEqual(v.offenders, []);
+});
+
+test('THE CORPUS-WIDE SHARE IS THE WRONG STATISTIC — the reason for per-builder', () => {
+  // The design decision, pinned because it is not obvious and the obvious version
+  // is worse than nothing. Folded into one row the way a corpus-wide check would
+  // fold it, the real outage peak is 19 uncovered out of 60 ships — and its own
+  // tail is 11 of 52, which a single ratio cannot separate from noise. Measured
+  // corpus-wide, the outage MONTH ran at 3.4% against 1.7-2.0% in healthy ones.
+  const folded = (rows) => [{
+    builder_id: 'all', github_login: null,
+    ships: rows.reduce((a, r) => a + r.ships, 0),
+    uncovered: rows.reduce((a, r) => a + r.uncovered, 0),
+  }];
+  assert.equal(health.uploadHealthVerdict(folded(OUTAGE_TAIL)).firing, false,
+    'folded into one number, the real outage tail does not fire — which is why the SQL groups by builder');
+  // And the same rows, kept per builder, do fire. Same data, different key.
+  assert.equal(health.uploadHealthVerdict(OUTAGE_TAIL).firing, true);
+});
+
+test('a quiet fortnight is refused, not judged', () => {
+  // Three uncovered out of four is 75% and means nothing. A check that fires on
+  // someone's slow week teaches people to mute it, which is the state this task
+  // is fixing.
+  const v = health.uploadHealthVerdict([
+    { builder_id: '9', github_login: 'someone', ships: 4, uncovered: 4 },
+  ]);
+  assert.equal(v.firing, false);
+  assert.equal(v.status, 'insufficient-data');
+  assert.match(v.reason, /not enough to judge/);
+  // But the SAME share over enough ships is the outage.
+  const loud = health.uploadHealthVerdict([
+    { builder_id: '9', github_login: 'someone', ships: 20, uncovered: 15 },
+  ]);
+  assert.equal(loud.firing, true);
+});
+
+test('garbage counts cannot manufacture an outage', () => {
+  // These rows come from SQL, but the verdict decides whether someone is woken
+  // up: an uncovered count above the ship count is a query bug, not an outage
+  // several times over.
+  const v = health.uploadHealthVerdict([
+    { builder_id: '9', github_login: 'x', ships: 20, uncovered: 400 },
+    { builder_id: null, github_login: 'ghost', ships: 99, uncovered: 99 },
+    null,
+  ]);
+  assert.equal(v.builders.length, 1, 'a row with no builder is dropped, not trusted');
+  assert.equal(v.builders[0].uncovered, 20, 'uncovered is clamped to ships');
+  assert.equal(health.uploadHealthVerdict(null).status, 'insufficient-data', 'and no rows at all is not an outage');
+  assert.equal(health.uploadHealthVerdict([]).firing, false);
+});
+
+test('the clamps bound what reaches an SQL interval', () => {
+  assert.equal(health.clampLookbackDays(undefined), health.DEFAULT_LOOKBACK_DAYS);
+  assert.equal(health.clampLookbackDays('nonsense'), health.DEFAULT_LOOKBACK_DAYS);
+  assert.equal(health.clampLookbackDays(1e9), 365, 'a hostile ?days cannot ask for the whole history');
+  assert.equal(health.clampLookbackDays(-5), 1);
+  assert.equal(health.clampWindowHours(1e9), 720);
+  assert.equal(health.clampWindowHours(0), 1);
+  assert.equal(health.clampSampleLimit(null), 20);
+  assert.equal(health.clampSampleLimit(10_000), 100, 'the sample is evidence, never the corpus');
+});
+
+// ---------------------------------------------------------------------------
+// (3) THE PREDICATE, as SQL — the trap the scoping task measured and warned about.
+// ---------------------------------------------------------------------------
+
+test('the emitted SQL keys on builder_id + time and never on task_ids', async () => {
+  // Captured from the query the db slice ACTUALLY runs, not grepped from source:
+  // both files mention task_ids in prose explaining why they do not use it, so a
+  // source scan would pass on a version that used it.
+  const api = require('../src/module-api.js');
+  const db = require('../modules/sessions/db.js');
+  const seen = [];
+  const prev = api.pool.query;
+  api.pool.query = async (sql, params) => { seen.push({ sql: String(sql), params }); return { rows: [] }; };
+  try {
+    await db.sessionUploadCoverage({ days: 14, windowHours: 24 });
+    await db.shipsMissingSessionRecord({ days: 14, windowHours: 24, limit: 20 });
+  } finally {
+    api.pool.query = prev;
+  }
+  assert.equal(seen.length, 2, 'both queries ran');
+  for (const { sql, params } of seen) {
+    assert.ok(!/task_ids/.test(sql), 'task_ids is EMPTY on 54% of rows — keying on it reports the linkage gap as an outage');
+    assert.match(sql, /sr\.builder_id = t\.shipped_by/, 'keyed on the builder');
+    assert.match(sql, /sr\.uploaded_at >=[\s\S]*sr\.uploaded_at <=/, 'and bounded by a time window on both sides');
+    assert.match(sql, /status = 'shipped'/, 'over ships, which is the half the server knows for certain');
+    // The interval inputs are BOUND, never interpolated — they come from a URL.
+    assert.ok(sql.includes("$1 * interval '1 day'"), 'the lookback is a bound parameter');
+    assert.ok(sql.includes("$2 * interval '1 hour'"), 'and so is the window');
+    assert.equal(params[0], 14);
+    assert.equal(params[1], 24);
+  }
+});
+
+test('the clamps are applied by the db slice, not merely available to it', async () => {
+  // The route is not the only caller, so a clamp the route applies is not a bound.
+  const api = require('../src/module-api.js');
+  const db = require('../modules/sessions/db.js');
+  const seen = [];
+  const prev = api.pool.query;
+  api.pool.query = async (sql, params) => { seen.push({ sql: String(sql), params }); return { rows: [] }; };
+  try {
+    await db.sessionUploadCoverage({ days: 1e9, windowHours: 1e9 });
+    await db.shipsMissingSessionRecord({ days: 1e9, windowHours: 1e9, limit: 1e9 });
+  } finally {
+    api.pool.query = prev;
+  }
+  assert.deepEqual(seen[0].params.slice(0, 2), [365, 720]);
+  assert.deepEqual(seen[1].params.slice(0, 2), [365, 720]);
+  assert.match(seen[1].sql, /LIMIT 100\b/, 'the sample limit is clamped into the SQL, not passed through');
+});
+
+test('the healthy path costs one query — the sample is only fetched when it exists', async () => {
+  const api = require('../src/module-api.js');
+  const db = require('../modules/sessions/db.js');
+  const prev = api.pool.query;
+  let calls = 0;
+  api.pool.query = async () => {
+    calls += 1;
+    return { rows: calls === 1 ? [{ builder_id: '3', github_login: 'x', ships: 40, uncovered: 0 }] : [] };
+  };
+  try {
+    const clean = await db.sessionUploadHealth({});
+    assert.equal(calls, 1, 'nothing uncovered, so no sample query');
+    assert.equal(clean.verdict.firing, false);
+    assert.deepEqual(clean.sample, []);
+
+    calls = 0;
+    api.pool.query = async () => {
+      calls += 1;
+      return { rows: calls === 1 ? [{ builder_id: '3', github_login: 'x', ships: 40, uncovered: 30 }] : [{ id: '7' }] };
+    };
+    const bad = await db.sessionUploadHealth({});
+    assert.equal(calls, 2, 'something uncovered, so the evidence is fetched');
+    assert.equal(bad.verdict.firing, true);
+    assert.deepEqual(bad.sample, [{ id: '7' }]);
+  } finally {
+    api.pool.query = prev;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (4) THE ALERT. A line that says "unhealthy" and no more is the same silence
+// with a timestamp on it.
+// ---------------------------------------------------------------------------
+
+test('the firing log line names the builder, the cost, and where to look', () => {
+  const lines = poller.logLinesFor({
+    days: 14,
+    verdict: health.uploadHealthVerdict(OUTAGE_PEAK),
+    sample: [{ id: '1002101' }, { id: '1002100' }],
+  }).join('\n');
+  assert.match(lines, /ALERT/);
+  assert.match(lines, /affected-builder/, 'whose machine');
+  assert.match(lines, /19 of 19/, 'the arithmetic');
+  assert.match(lines, /unpaid shipped work/, 'what it costs — not "missing telemetry"');
+  assert.match(lines, /sessions\/upload-health/, 'where to look next');
+  assert.match(lines, /session-upload-skips\.jsonl/, 'and the likely client-side cause');
+  assert.match(lines, /#1002101/, 'with the uncovered ships named, so the unpaid work is recoverable');
+});
+
+test('the quiet log line is one line, and says which quiet it is', () => {
+  const quiet = poller.logLinesFor({ days: 14, verdict: health.uploadHealthVerdict(HEALTHY), sample: [] });
+  assert.equal(quiet.length, 1, 'a healthy sweep must not be noisy — hourly, that is 24 lines a day');
+  assert.match(quiet[0], /healthy/);
+  // 'insufficient-data' must not read as healthy: they are different situations
+  // and only one of them is evidence that uploads work.
+  const thin = poller.logLinesFor({ days: 14, verdict: health.uploadHealthVerdict([]), sample: [] });
+  assert.match(thin[0], /insufficient-data/);
+});
+
+test('runSweep is the whole chain, and the loader calls IT — not the helpers', async () => {
+  // The (helper-nothing-calls) lesson: logLinesFor and sessionUploadHealth can
+  // both be perfect while the poller the loader actually starts reaches neither.
+  // Drive the entry point end to end against a patched pool and read what it
+  // would have logged.
+  const api = require('../src/module-api.js');
+  const prevQuery = api.pool.query;
+  const prevLogger = api.logger;
+  const emitted = [];
+  api.logger = () => ({
+    info: (...a) => emitted.push(['info', a.map(String).join(' ')]),
+    error: (...a) => emitted.push(['error', a.map(String).join(' ')]),
+  });
+  let calls = 0;
+  api.pool.query = async () => {
+    calls += 1;
+    return {
+      rows: calls === 1
+        ? [{ builder_id: '900001', github_login: 'affected-builder', ships: 19, uncovered: 19 }]
+        : [{ id: '1002101' }],
+    };
+  };
+  // The logger is resolved at module load, so re-import the poller under the stub.
+  const fresh = require('node:module').createRequire(import.meta.url);
+  delete fresh.cache[fresh.resolve('../modules/sessions/pollers/session-upload-health.js')];
+  const live = fresh('../modules/sessions/pollers/session-upload-health.js');
+  try {
+    const health = await live.runSweep();
+    assert.equal(health.verdict.firing, true, 'the sweep reaches the verdict');
+    assert.equal(calls, 2, 'and fetches the evidence when there is any');
+    const errors = emitted.filter(([lvl]) => lvl === 'error');
+    assert.ok(errors.length >= 1, 'a firing sweep logs at ERROR so a level filter cannot hide it');
+    assert.match(errors.map(([, m]) => m).join('\n'), /ALERT[\s\S]*affected-builder/,
+      'and what it logs is the alert, not a bare status');
+  } finally {
+    api.pool.query = prevQuery;
+    api.logger = prevLogger;
+    delete fresh.cache[fresh.resolve('../modules/sessions/pollers/session-upload-health.js')];
+  }
+});
+
+test('the poller reports and never writes', () => {
+  // It runs beside the reward reconciler, which MOVES MONEY. A telemetry sweep
+  // that could book, delete or update anything would need its own safety
+  // argument; this one needs none, and that must stay true.
+  const src = require('node:fs').readFileSync(
+    new URL('../modules/sessions/pollers/session-upload-health.js', import.meta.url), 'utf8');
+  const code = src.replace(/\/\/[^\n]*/g, '');
+  for (const forbidden of ['INSERT', 'UPDATE', 'DELETE', 'withTx', 'reconcile', 'award']) {
+    assert.ok(!new RegExp(forbidden, 'i').test(code), `the health sweep must not ${forbidden}`);
+  }
+  assert.match(code, /db\.sessionUploadHealth/, 'it reads through the one read entry point');
+  assert.equal(typeof poller.start, 'function');
+  assert.equal(typeof poller.stop, 'function');
+  // Kill-switched and separate from the payout sweep's switch, so silencing the
+  // telemetry can never silence the money.
+  assert.match(code, /SESSION_UPLOAD_HEALTH_DISABLED/);
+  assert.ok(!/SESSION_REWARD_RECONCILE/.test(code), 'and it does not share the payout poller\'s switch');
+});

package/tests/setup_device_flow_fallback.mjs

@@ -120,7 +120,7 @@ const server = http.createServer((req, res) => {
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(body));
   };
-  if (req.method === 'GET' && req.url.endsWith('/api/gds/me')) {
+  if (req.method === 'GET' && req.url.endsWith('/api/bongos/me')) {
     if ((req.headers.authorization || '') === `Bearer ${GOOD_TOKEN}`) {
       return send(200, { builder: { id: 6, github_login: 'newbuilder', display_name: 'New Builder' } });
     }

package/tests/skill_ask_for_help.mjs

@@ -27,11 +27,11 @@ test('/ask-for-help files a help request and routes its near-neighbours', (t) =>
   const md = readFileSync(SKILL, 'utf8');
 
   // The write path, named literally — this is the whole point of the skill.
-  assert.match(md, /POST \/(?:api\/gds\/)?help-requests/, 'names the help-request write route');
+  assert.match(md, /POST \/(?:api\/bongos\/)?help-requests/, 'names the help-request write route');
   assert.match(md, /--body-file/, 'files via --body-file (api.js drops a positional body)');
 
   // Resolve the addressee — never guess a builder id.
-  assert.match(md, /GET \/api\/gds\/builders\/directory/, 'resolves a named builder through the directory');
+  assert.match(md, /GET \/api\/bongos\/builders\/directory/, 'resolves a named builder through the directory');
   assert.match(md, /never guess/i, 'forbids guessing a builder id');
 
   // The two XOR rules the table's CHECK constraints enforce.
@@ -57,7 +57,7 @@ test('/ask-for-help files a help request and routes its near-neighbours', (t) =>
   assert.match(md, /help-requests\/for-me/, 'names the addressed read the recipient sees');
 
   // Settling is the asker's job — an unsettled pile is noise.
-  assert.match(md, /PATCH \/api\/gds\/help-requests\/<id>/, 'names the settle route');
+  assert.match(md, /PATCH \/api\/bongos\/help-requests\/<id>/, 'names the settle route');
   assert.match(md, /answered/, 'names the answered status');
   assert.match(md, /withdrawn/, 'names the withdrawn status');
 

package/tests/skill_grade_audit.mjs

@@ -23,9 +23,9 @@ test('/grade-audit exists, covers the sweep legs, and stays describe-and-queue o
   const md = readFileSync(SKILL, 'utf8');
 
   // Data surfaces.
-  assert.match(md, /\/api\/gds\/public\/recent-shipped/, 'sweeps the recent-shipped window');
+  assert.match(md, /\/api\/bongos\/public\/recent-shipped/, 'sweeps the recent-shipped window');
   assert.match(md, /include=grade/, 'reads each task\'s persisted grade');
-  assert.match(md, /\/api\/gds\/override-requests/, 'cross-references the override ledger');
+  assert.match(md, /\/api\/bongos\/override-requests/, 'cross-references the override ledger');
 
   // Leg 1 — override ledger: shipped-with-failing-grade, infra vs real split.
   assert.match(md, /panel_outcome='unavailable'/, 'splits infra outage from a real fail');

package/tests/skill_grader_health.mjs

@@ -22,9 +22,9 @@ test('/grader-health exists and covers the four health axes on live data', (t) =
   const md = readFileSync(SKILL, 'utf8');
 
   // Live data surfaces, named concretely.
-  assert.match(md, /\/api\/gds\/public\/grades/, 'reads the public grade trend');
-  assert.match(md, /\/api\/gds\/grades\/by-builder/, 'reads the per-builder split (Archon)');
-  assert.match(md, /\/api\/gds\/public\/cost-summary/, 'reads grader spend');
+  assert.match(md, /\/api\/bongos\/public\/grades/, 'reads the public grade trend');
+  assert.match(md, /\/api\/bongos\/grades\/by-builder/, 'reads the per-builder split (Archon)');
+  assert.match(md, /\/api\/bongos\/public\/cost-summary/, 'reads grader spend');
 
   // Axis 1 — outage runs: the 21×0.0 pattern and outage-vs-rejection confirmation.
   assert.match(md, /n_unavailable/, 'names the outage bucket the aggregates expose');

package/tests/smoke_write_contract.mjs

@@ -47,7 +47,7 @@ test('goal_id is the RESOLVED id, never a literal', () => {
 });
 
 test('GOAL_ID is resolved at runtime, from the is_maintenance flag', () => {
-  assert.match(SH, /GOAL_ID=\$\(call GET "\/api\/gds\/goals\?version=\$\{VERSION_ID\}"/,
+  assert.match(SH, /GOAL_ID=\$\(call GET "\/api\/bongos\/goals\?version=\$\{VERSION_ID\}"/,
     'it asks the API for this version-s goals');
   assert.match(SH, /is_maintenance/, 'and picks the maintenance goal by its flag');
   // Exactly one open maintenance goal exists per version (BV1.R18). Ambiguity here