@bongos/core 1.19.965 → 1.19.967

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.965",
-  "core_contract": "1.19.965",
-  "source_commit": "bbaec9cc0649177ca52efa5afa2cea91b9fead9b",
+  "core_version": "1.19.967",
+  "core_contract": "1.19.967",
+  "source_commit": "7f7f99034d971eec4bc9d9741d516decfb6c1f14",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T22:06:32.886Z",
+  "built_at": "2026-09-22T23:07:17.959Z",
   "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": "686c7cbaf16a9143fa9e322b03a8c6dc0fe6d16fa76848b028507a7f528f295f",
+  "file_count": 2906,
+  "tree_sha256": "ddb385e48e6ccbb09169729f409babe82f980fd1d8ee8cee5855194cf955839a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2697,7 +2697,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f84a2fba932e6e634773c3245f5dbe12f370f42ed6285a2e74546227024b07b5"
+      "sha256": "c998e897524293549e03bffbecdabeeecc2ba7f7cd327bdb96f24ce88a7469cc"
     },
     {
       "path": "docs/modules-contract.md",
@@ -8102,12 +8102,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1eb1f4122d6de764110bb2d783bd0c79d3727dff6663d23917edb602a081774f"
+      "sha256": "81ffeea318f60a6abfde034d31d70812372b1e7bc17fad2005f777a0eb759530"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "58625b2583bfd11c6972959c530409e6c63085cc2de47e9f6278bec7c767b9db"
+      "sha256": "bbc2cda2140d830f4faf271399ac8c1c1df06f84781262f849598451861d1c30"
     },
     {
       "path": "public-docs/index.html",
@@ -10112,7 +10112,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a71508cbe155a0041db078c9a66c9e78cc578163d0056ae2cf12c9aa2bcc2df0"
+      "sha256": "5ffee651905384e38b5eba0d85dd725dd3f54b7c3c57fe5de6971e2daa78ba7d"
     },
     {
       "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

@@ -2404,5 +2404,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.963 with no explicit bump. run 35787848112. (task 1002620)
   1.19.965 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.965",
+  "version": "1.19.967",
   "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.965'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.967'; // 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);