@bongos/core 1.19.470 → 1.19.472

package/tests/stale_timer.mjs

@@ -0,0 +1,230 @@
+// tests/stale_timer.mjs — one project, one stale-claim timer
+// (task 1003476, goal 1000072, criterion legibility-sort-and-staleness).
+//
+// THE BUG THIS PINS. "How long may a claim go silent" had three answers living in
+// three files, and nothing made them meet: the sweeper that actually releases claims
+// read GDS_STALE_CLAIM_HOURS (default 6h), the Archon roster that REPORTS staleness
+// hardcoded 24h, and the two session-pulse SQL helpers defaulted to 30 minutes. The
+// visible failure was the eighteen-hour lie: for most of a day after a claim had been
+// auto-released, tagged [auto-released:stale] and handed back to the queue, the roster
+// an Archon opens to decide whether to intervene still showed it healthy.
+//
+// So these assertions are mostly about SAMENESS — that no surface carries its own
+// number — plus the one place the two kinds of caller must legitimately differ: a
+// misconfigured timer makes the READ-ONLY roster degrade and say so, and makes the
+// DESTRUCTIVE sweeper refuse to run at all.
+//
+// Run:  node tests/stale_timer.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
+const st = require(path.join(ROOT, 'src/stale-timer.js'));
+
+const PULSE_CLI = read('scripts/gds/pulse.js');
+const PULSE_LIB = read('modules/sessions/pulse.js');
+const DB_SHIP = read('modules/lifecycle/db-ship.js');
+const ROSTER_ROUTE = read('src/bongos/routes/builders.js');
+const FITNESS = read('scripts/gds/fitness.js');
+const DOORWAY = read('src/module-api.js');
+
+const { test, summary } = makeRunner();
+
+// ---------------------------------------------------------------------------
+// 1. The resolver itself — executed, not described.
+// ---------------------------------------------------------------------------
+
+await test('no env, no override → the sweep default, labelled', () => {
+  const r = st.resolveStaleClaimHours({ env: {} });
+  assert.equal(r.hours, st.DEFAULT_STALE_CLAIM_HOURS);
+  assert.equal(r.hours, 6, 'the default is the SWEEP\'s historical 6h — the surface that acts');
+  assert.equal(r.source, 'default');
+  assert.equal(r.invalid, null);
+});
+
+await test('the live prod env var still resolves — legacy GDS_ prefix honoured', () => {
+  // Nothing in the running deployment may have to change for this to keep working:
+  // instance-config's legacy prefix chain is what carries GDS_STALE_CLAIM_HOURS.
+  const r = st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: '12' } });
+  assert.equal(r.hours, 12);
+  assert.equal(r.source, 'env:GDS_STALE_CLAIM_HOURS');
+  assert.equal(r.invalid, null);
+});
+
+await test('the branded prefix wins over the legacy one', () => {
+  const r = st.resolveStaleClaimHours({
+    env: { CLOUDBONGOS_STALE_CLAIM_HOURS: '3', GDS_STALE_CLAIM_HOURS: '12' },
+  });
+  assert.equal(r.hours, 3);
+  assert.equal(r.source, 'env:CLOUDBONGOS_STALE_CLAIM_HOURS');
+});
+
+await test('an override is a LENS — it never becomes the project answer', () => {
+  const env = { GDS_STALE_CLAIM_HOURS: '12' };
+  assert.equal(st.resolveStaleClaimHours({ override: '48', env }).hours, 48);
+  assert.equal(st.resolveStaleClaimHours({ override: '48', env }).source, 'override');
+  // asking again without the lens gives the project's number back, unchanged
+  assert.equal(st.resolveStaleClaimHours({ env }).hours, 12);
+});
+
+await test('an empty override falls through rather than resolving to 0', () => {
+  for (const override of ['', null, undefined]) {
+    const r = st.resolveStaleClaimHours({ override, env: { GDS_STALE_CLAIM_HOURS: '12' } });
+    assert.equal(r.hours, 12, `override=${JSON.stringify(override)} must not shadow the env`);
+  }
+});
+
+await test('an unusable value REPORTS instead of throwing, and never returns a bad number', () => {
+  for (const [raw, reason] of [['nope', 'not a number'], ['0', 'must be positive'], ['-4', 'must be positive'], ['9999', 'out of range (1..720)']]) {
+    const r = st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: raw } });
+    assert.equal(r.hours, st.DEFAULT_STALE_CLAIM_HOURS, `${raw} must fall back`);
+    assert.equal(r.source, 'default');
+    assert.ok(r.invalid, `${raw} must be reported as invalid`);
+    assert.equal(r.invalid.where, 'env');
+    assert.equal(r.invalid.varName, 'GDS_STALE_CLAIM_HOURS');
+    assert.equal(r.invalid.raw, raw);
+    assert.equal(r.invalid.reason, reason);
+  }
+});
+
+await test('the bound is the one GET /builders/roster already published (1..720)', () => {
+  assert.equal(st.MIN_STALE_CLAIM_HOURS, 1);
+  assert.equal(st.MAX_STALE_CLAIM_HOURS, 720);
+  assert.equal(st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: '720' } }).hours, 720);
+  assert.ok(st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: '721' } }).invalid);
+});
+
+await test('describeStaleTimer names the number AND its provenance', () => {
+  assert.equal(st.describeStaleTimer(st.resolveStaleClaimHours({ env: {} })), '6h (default)');
+  assert.equal(
+    st.describeStaleTimer(st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: '12' } })),
+    '12h (env:GDS_STALE_CLAIM_HOURS)'
+  );
+  const bad = st.describeStaleTimer(st.resolveStaleClaimHours({ env: { GDS_STALE_CLAIM_HOURS: 'nope' } }));
+  assert.match(bad, /^6h \(default\)/);
+  assert.match(bad, /ignoring GDS_STALE_CLAIM_HOURS="nope" \(not a number\)/);
+});
+
+await test('hours→minutes happens in ONE place and never rounds to zero', () => {
+  assert.equal(st.staleClaimMinutes(6), 360);
+  assert.equal(st.staleClaimMinutes(1), 60);
+  assert.equal(st.staleClaimMinutes(0.001), 1, 'a sub-minute timer must still be a minute, not 0');
+  assert.throws(() => st.staleClaimMinutes(0), /positive/);
+  assert.throws(() => st.staleClaimMinutes('x'), /positive/);
+});
+
+// ---------------------------------------------------------------------------
+// 2. Sameness — no surface carries its own number any more.
+// ---------------------------------------------------------------------------
+
+await test('the three old hardcoded defaults are gone from their files', () => {
+  assert.ok(!/thresholdMin = 30\b/.test(PULSE_LIB),
+    'modules/sessions/pulse.js must not default to a third number (30 min)');
+  assert.ok(!/staleHours = 24\b/.test(DB_SHIP),
+    'getBuildersRoster must not default to its own 24h');
+  assert.ok(!/let staleHours = 24\b/.test(ROSTER_ROUTE),
+    'GET /builders/roster must not default to its own 24h');
+});
+
+await test('every staleness surface resolves through the one timer', () => {
+  assert.match(PULSE_CLI, /require\('\.\.\/\.\.\/src\/stale-timer'\)/,
+    'the sweeper CLI must read the shared timer');
+  assert.match(PULSE_LIB, /resolveStaleClaimHours/,
+    'the session-pulse SQL helpers must default to the shared timer');
+  assert.match(DB_SHIP, /api\.resolveStaleClaimHours\(\)/,
+    'getBuildersRoster must default to the shared timer');
+  assert.match(ROSTER_ROUTE, /require\('\.\.\/\.\.\/stale-timer'\)/,
+    'the roster route must read the shared timer');
+});
+
+await test('the sweeper no longer reads the env var itself', () => {
+  // The precedence has ONE home. A second reader is how 6-vs-24 happened.
+  assert.ok(!/process\.env\.GDS_STALE_CLAIM_HOURS/.test(PULSE_CLI),
+    'scripts/gds/pulse.js must not re-read GDS_STALE_CLAIM_HOURS directly');
+});
+
+await test('an explicit argument still overrides at every layer', () => {
+  // The lens must survive: an Archon asking "what would 48h show me?" and an
+  // operator sweeping at a one-off threshold both depend on it.
+  assert.match(PULSE_LIB, /thresholdMin \?\? projectThresholdMin\(\)/);
+  assert.match(DB_SHIP, /staleHours \?\? api\.resolveStaleClaimHours\(\)/);
+  assert.match(ROSTER_ROUTE, /stale_hours != null/);
+});
+
+// ---------------------------------------------------------------------------
+// 3. The asymmetric fail posture: reporting degrades, enforcement refuses.
+// ---------------------------------------------------------------------------
+
+await test('the SWEEP refuses to run on a timer it cannot read', () => {
+  // It releases other people's claims and stamps their session logs. A reload does
+  // not undo that, so guessing is not an option available to it.
+  assert.match(PULSE_CLI, /refusing to sweep on a timer this project cannot read/);
+  const fn = PULSE_CLI.slice(PULSE_CLI.indexOf('function parseThresholdHours'));
+  const body = fn.slice(0, fn.indexOf('\n}\n') + 3);
+  assert.match(body, /if \(resolved\.invalid\)/, 'the refusal must key off the resolver verdict');
+  assert.match(body, /throw new Error/);
+});
+
+// The helper both Archon staleness reads go through.
+const HELPER = (() => {
+  const from = ROSTER_ROUTE.indexOf('function staleHoursFor(req, res)');
+  assert.ok(from > 0, 'the shared helper must exist');
+  return ROSTER_ROUTE.slice(from, ROSTER_ROUTE.indexOf('\n}\n', from) + 3);
+})();
+
+await test('the ROSTER degrades to the default and names the bad value', () => {
+  // 500-ing the roster an Archon opened to find the problem would hide the problem.
+  assert.match(HELPER, /default \(invalid \$\{timer\.invalid\.varName\}/);
+  assert.ok(!/throw/.test(HELPER), 'the roster helper must not throw on a bad timer');
+  assert.match(HELPER, /res\.fail\('bad_stale_hours', 400/,
+    'only an explicitly BAD query param is a 400 — never a bad project timer');
+});
+
+await test('BOTH Archon staleness reads report the number and its provenance', () => {
+  // Two routes, one helper. Before this they were two byte-identical copies of a
+  // hardcoded 24, which is exactly how a second copy drifts into a second policy.
+  const calls = [...ROSTER_ROUTE.matchAll(/= staleHoursFor\(req, res\)/g)];
+  assert.equal(calls.length, 2, 'the roster and its expand view both go through the helper');
+  assert.match(ROSTER_ROUTE, /res\.json\(\{ builders, stale_hours: stale\.hours, stale_hours_source: stale\.source \}\)/);
+  assert.match(ROSTER_ROUTE, /res\.json\(\{ builder_id: targetId, claims, stale_hours: stale\.hours, stale_hours_source: stale\.source \}\)/);
+  assert.match(HELPER, /source: 'query'/, 'a lens must be labelled as a lens');
+});
+
+await test('the expand view cannot disagree with the roster it expands from', () => {
+  assert.ok(!/staleHours = 24\b/.test(ROSTER_ROUTE), 'no route may keep its own 24');
+  assert.ok(!/staleHours = 24\b/.test(DB_SHIP), 'no db helper may keep its own 24');
+  assert.match(DB_SHIP, /staleHours \?\? api\.resolveStaleClaimHours\(\)\.hours/);
+  const both = [...DB_SHIP.matchAll(/staleHours \?\? api\.resolveStaleClaimHours\(\)\.hours/g)];
+  assert.equal(both.length, 2, 'getBuildersRoster AND getActiveClaimsForBuilderWithStale');
+});
+
+// ---------------------------------------------------------------------------
+// 4. The boundary the new kernel file has to keep.
+// ---------------------------------------------------------------------------
+
+await test('src/stale-timer.js is on the KERNEL_FILES roster', () => {
+  // The doorway (itself a KERNEL_FILE) re-exports it, so leaving it off would read as
+  // a kernel→non-kernel leak and red the build on Check 12.
+  const roster = FITNESS.slice(FITNESS.indexOf('const KERNEL_FILES = ['));
+  assert.match(roster.slice(0, roster.indexOf('];')), /'src\/stale-timer\.js'/);
+});
+
+await test('the timer imports only the kernel', () => {
+  const src = read('src/stale-timer.js');
+  const specs = [...src.matchAll(/require\('([^']+)'\)/g)].map((m) => m[1]);
+  assert.deepEqual(specs, ['./instance-config'],
+    'a kernel file may depend only on the kernel — keep this list boring');
+});
+
+await test('the doorway hands modules the timer, not the raw env', () => {
+  assert.match(DOORWAY, /resolveStaleClaimHours: staleTimer\.resolveStaleClaimHours/);
+  assert.match(DOORWAY, /staleClaimMinutes: staleTimer\.staleClaimMinutes/);
+});
+
+summary();