@bongos/core 1.19.966 → 1.19.968

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.966",
-  "core_contract": "1.19.966",
-  "source_commit": "f9a2fd36c3e7b4edf4651b14bdac01a5aaa6d67e",
+  "core_version": "1.19.968",
+  "core_contract": "1.19.968",
+  "source_commit": "8ccf04d976e2b856bc48cbfc6ad7d6563522bc51",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T22:38:24.701Z",
+  "built_at": "2026-09-22T23:25:06.335Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 515,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2364,
+    "functional_verbatim": 2365,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2905,
-  "tree_sha256": "7fa554d04d9424f09eebccfd76a2315c83cd011643b44de050c21147363196a4",
+  "file_count": 2906,
+  "tree_sha256": "4ccb083b8cb616dd5c4c9c49f498b566996a1ead6ea244f46e5344d7a726a322",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2697,7 +2697,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0620b648ea2eb9cca6c68ff28eade7cae3b27bf3e9d9276ae6c3c08a2d7546d8"
+      "sha256": "aa4b0d91bfda4df6b776aa7ea600750b3f24be1e0ffee255ceb170184df90636"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8102,12 +8102,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3a5c55425b2f034c483d12ab1884eb78bdd36386c577fc67a877efefd5f284c0"
+      "sha256": "a4f60be63bc56da8ba3332e604d1fbb0b4b3288f9b3cf14a52d05227e040a3f4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "bc300eff0b46e3231039eea8ec41caf14b02beec57a09e52735b75ccea9a533e"
+      "sha256": "4d9fb5822b9ba10648ba9d9e0c2bd7c5659215e65bb8395455913b7b14c43998"
     },
     {
       "path": "public-docs/index.html",
@@ -10112,7 +10112,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "0c962d6b334caf231259b5a5b7c394b648916dd7753d5bc518c5e6cd2683cfc0"
+      "sha256": "4f5478f0a18dbb167df7e86861ae757cceaf084a43436461af1fca4855256505"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12529,6 +12529,11 @@
       "mode": "0000644",
       "sha256": "cf0d082fad9bd7fdb3071016fac252fd59e5d24cec8280aab72c760c416d1482"
     },
+    {
+      "path": "tests/liveness_notify.mjs",
+      "mode": "0000644",
+      "sha256": "8bd62820c232cae7346129c9d54aa9b56e3e50ed0d7488b238993c78c004c55e"
+    },
     {
       "path": "tests/llm-cache-route.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2406,5 +2406,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.964 with no explicit bump. run 35790478196. (task 1002620)
   1.19.966 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.965 with no explicit bump. run 35793400408. (task 1002620)
+  1.19.967 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.966 with no explicit bump. run 35795807836. (task 1002620)
+  1.19.968 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.967 with no explicit bump. run 35797263467. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.966",
+  "version": "1.19.968",
   "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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.966'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.968'; // 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/liveness_notify.mjs

@@ -0,0 +1,204 @@
+// tests/liveness_notify.mjs
+//
+// The three rules that keep the liveness heartbeat from becoming a siren
+// (task 1004151; the rules themselves are task 1002894's, from idea 1000703).
+//
+// WHY THIS FILE EXISTS AT ALL. `modules/provisioning/pollers/liveness-notify.js` decides
+// what reaches the owner's Discord when a project stops answering, and until now none of
+// its rules had a test. Its CLAUDE.md row cited `tests/liveness-notify.mjs` as its proof
+// and **that file had never existed** — `git log --all --diff-filter=A` for it is empty,
+// and nothing under `tests/` named `DOWN_CONFIRM`, `FLEET_GUARD` or `noticeText`. Found
+// while building the sibling poller under task 1004000.
+//
+// THE REASON IT MATTERS MORE THAN AN ORDINARY COVERAGE GAP: all three rules fail
+// SILENTLY, and toward noise or silence rather than error. A broken edge check
+// re-announces every outage on every control-plane restart. A broken confirm streak turns
+// one refused connection into an owner-facing alarm. A broken collapse turns a
+// prober-side blip into one message per project. Each of those reaches a human's Discord
+// and none of them throws, so nothing but an assertion can catch them.
+//
+// EVERY CASE HERE WAS CHECKED BY DELETING THE RULE AND WATCHING IT GO RED — a guard is
+// not finished until its test has been seen to fail. The mutation each case survives is
+// named in its own comment, so a later reader can re-run the experiment instead of
+// trusting this sentence.
+//
+// `planNotices` is pure over (observations, state) and mutates only the Map it is handed,
+// so none of this needs a sweep, a database or a network.
+//
+// Run:  node tests/liveness_notify.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { planNotices, noticeText, DOWN_CONFIRM, FLEET_GUARD } = require('../modules/provisioning/pollers/liveness-notify.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// An observation as the sweep builds it: { id, slug, isPublic, up, prevUp }. `prevUp` is
+// what recordLivenessProbe returned as the row's PRIOR verdict — the only place a fall is
+// visible, which is what the edge rule is built on.
+const obs = (over = {}) => ({ id: 1, slug: 'lantern', isPublic: true, up: false, prevUp: true, ...over });
+
+// Drive N consecutive identical sweeps over one state Map and collect every notice.
+function ticks(n, observations, state = new Map(), opts) {
+  const all = [];
+  for (let i = 0; i < n; i++) all.push(...planNotices(observations, state, opts).notices);
+  return { notices: all, state };
+}
+
+console.log('rule 1 — EDGE, not state:');
+
+t('a project already down when the process started is NEVER announced, however long it stays down', () => {
+  // The rule: a fall is visible only in `prevUp`, so a row that was already down before
+  // this process began watching has no edge to see. Without it, every control-plane
+  // restart re-announces every ongoing outage — the exact siren this is built to avoid.
+  //
+  // MUTATION CHECKED: deleting the `else continue` arm (so an absent prev starts a streak
+  // of 1) makes this case fail on the second tick.
+  const { notices, state } = ticks(5, [obs({ prevUp: false })]);
+  assert.deepEqual(notices, [], 'no notice, no matter how many sweeps see it down');
+  assert.equal(state.size, 0, 'and it is not even tracked — there is nothing to announce later');
+});
+
+t('a null prevUp — a row never probed before — is also not an edge', () => {
+  // recordLivenessProbe returns null for a row with no prior verdict. That is "unknown",
+  // not "was up", and reading it as a fall would announce every brand-new project that
+  // happens to be mid-standup.
+  const { notices } = ticks(3, [obs({ prevUp: null })]);
+  assert.deepEqual(notices, []);
+});
+
+t('a fall OBSERVED in this process is announced — the edge rule is not just "stay quiet"', () => {
+  // The control for the two cases above: the same project, with prevUp true, does reach a
+  // notice. Without this, "announces nothing ever" would pass the edge tests too.
+  const { notices } = ticks(DOWN_CONFIRM, [obs({ prevUp: true })]);
+  assert.equal(notices.length, 1);
+  assert.equal(notices[0].kind, 'down');
+});
+
+console.log('\nrule 2 — CONFIRM before speaking:');
+
+t('one down probe followed by a recovery says NOTHING — a blip costs nothing', () => {
+  // The rule: wait DOWN_CONFIRM consecutive sweeps. One refused connection is not an
+  // outage, and a project that heals in between was never announced, so nothing needs
+  // unsaying.
+  //
+  // MUTATION CHECKED: lowering the gate to `streak >= 1` makes this case fail — it posts
+  // a down, and then an all-clear for an outage nobody experienced.
+  const state = new Map();
+  const first = planNotices([obs({ up: false, prevUp: true })], state);
+  assert.deepEqual(first.notices, [], 'the first down is not yet news');
+  const healed = planNotices([obs({ up: true })], state);
+  assert.deepEqual(healed.notices, [], 'and the recovery is not news either, because the fall never was');
+  assert.equal(state.size, 0, 'the streak is dropped, so a later fall starts clean');
+});
+
+t('two consecutive downs post EXACTLY ONE message, and staying down adds none', () => {
+  // MUTATION CHECKED: dropping the `notified` latch makes the third tick post again.
+  const { notices, state } = ticks(6, [obs()]);
+  assert.equal(notices.length, 1, `one message for one outage, got ${notices.length}`);
+  assert.equal(notices[0].kind, 'down');
+  assert.equal(state.get(1).notified, true, 'the latch is what keeps it quiet afterwards');
+});
+
+t('DOWN_CONFIRM is honoured as configured, not hardcoded at two', () => {
+  // The threshold is an env knob; a test that pinned "2" would pass on a deployment that
+  // had raised it and was therefore silent for longer than anyone expected.
+  const state = new Map();
+  for (let i = 1; i < DOWN_CONFIRM; i++) {
+    assert.deepEqual(planNotices([obs()], state).notices, [], `silent at ${i} of ${DOWN_CONFIRM}`);
+  }
+  assert.equal(planNotices([obs()], state).notices.length, 1, `speaks at ${DOWN_CONFIRM}`);
+});
+
+console.log('\nrecovery is scoped to what was actually announced:');
+
+t('an all-clear fires ONLY where a down notice really went out', () => {
+  // MUTATION CHECKED: pushing to `ups` without the `prev.notified` guard makes the blip
+  // case above emit an unpaired "is answering again" for an outage never reported.
+  const state = new Map();
+  ticks(DOWN_CONFIRM, [obs()], state);              // announced
+  const back = planNotices([obs({ up: true })], state);
+  assert.equal(back.notices.length, 1);
+  assert.equal(back.notices[0].kind, 'up');
+  assert.equal(state.size, 0, 'and the row is forgotten, so a later fall is a fresh edge');
+  assert.deepEqual(planNotices([obs({ up: true })], state).notices, [], 'the all-clear is not repeated');
+});
+
+console.log('\nrule 3 — COLLAPSE a fan-out:');
+
+t('FLEET_GUARD simultaneous falls become ONE message that names no project', () => {
+  // The rule: when several projects fall in the same sweep the cause is almost always on
+  // this side — a control-plane restart, a prober-side blip — so one message says that,
+  // rather than N messages that read like N independent faults.
+  //
+  // MUTATION CHECKED: returning `rows.map(...)` unconditionally from collapse() makes this
+  // case fail with FLEET_GUARD separate notices.
+  const many = Array.from({ length: FLEET_GUARD }, (_, i) => obs({ id: i + 1, slug: `p${i + 1}` }));
+  const state = new Map();
+  let out;
+  for (let i = 0; i < DOWN_CONFIRM; i++) out = planNotices(many, state);
+  assert.equal(out.notices.length, 1, `one collapsed message, got ${out.notices.length}`);
+  assert.equal(out.notices[0].ids.length, FLEET_GUARD, 'it carries every id');
+  assert.equal(out.suppressed, FLEET_GUARD, 'and reports how many it stood in for');
+  for (const o of many) {
+    assert.ok(!out.notices[0].text.includes(o.slug), `a collapsed message must not name ${o.slug}`);
+  }
+  assert.match(out.notices[0].text, /usually the platform's own check/, 'it says where to look first');
+});
+
+t('one BELOW the guard stays per-project, so the collapse is a threshold and not the default', () => {
+  const few = Array.from({ length: FLEET_GUARD - 1 }, (_, i) => obs({ id: i + 1, slug: `p${i + 1}` }));
+  const state = new Map();
+  let out;
+  for (let i = 0; i < DOWN_CONFIRM; i++) out = planNotices(few, state);
+  assert.equal(out.notices.length, FLEET_GUARD - 1, 'one message each');
+  assert.equal(out.suppressed, 0);
+  assert.ok(out.notices.every((n) => n.ids.length === 1));
+});
+
+console.log('\nthe privacy rule (the one with a consequence):');
+
+t('a project that is not public on the map is DESCRIBED, never named', () => {
+  // A private project's slug must not ride a Discord channel. This is the rule in this
+  // file whose failure is a disclosure rather than noise.
+  //
+  // MUTATION CHECKED: passing `r.slug` instead of `r.isPublic ? r.slug : null` in
+  // collapse() makes this case fail with the slug in the text.
+  const state = new Map();
+  let out;
+  for (let i = 0; i < DOWN_CONFIRM; i++) out = planNotices([obs({ isPublic: false, slug: 'secret-thing' })], state);
+  assert.equal(out.notices.length, 1);
+  assert.ok(!out.notices[0].text.includes('secret-thing'), 'the slug must never appear');
+  assert.match(out.notices[0].text, /A private project/, 'it is described instead');
+  // The recovery half has the same obligation — it is a second message about the same row.
+  const back = planNotices([obs({ isPublic: false, slug: 'secret-thing', up: true })], state);
+  assert.ok(!back.notices[0].text.includes('secret-thing'), 'and the all-clear must not leak it either');
+});
+
+t('a public project IS named — the control for the rule above', () => {
+  const state = new Map();
+  let out;
+  for (let i = 0; i < DOWN_CONFIRM; i++) out = planNotices([obs({ isPublic: true, slug: 'lantern' })], state);
+  assert.match(out.notices[0].text, /lantern/);
+});
+
+console.log('\nthe copy:');
+
+t('noticeText makes no wall-clock promise, and says what happens next', () => {
+  // The owner is being told something is wrong; a message that promises "back shortly"
+  // is a commitment nothing here can keep.
+  const down = noticeText({ kind: 'down', name: 'lantern' });
+  assert.doesNotMatch(down, /shortly|briefly|minute|second|soon\b/i);
+  assert.match(down, /say so here when the project answers again/, 'it says what the platform will do');
+  assert.match(noticeText({ kind: 'up', name: 'lantern' }), /answering again/);
+  assert.match(noticeText({ kind: 'up', count: 4 }), /All 4 projects/, 'the collapsed all-clear counts them');
+});
+
+console.log(`\nliveness_notify: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);