@bongos/core 1.19.640 → 1.19.641

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.640",
-  "core_contract": "1.19.640",
-  "source_commit": "2ab73a01133b60e930ce77745cd7bab2be53d517",
+  "core_version": "1.19.641",
+  "core_contract": "1.19.641",
+  "source_commit": "7af21a0086bc6cbc069a459b0a30b90f1646f82e",
   "source_ref": "HEAD",
-  "built_at": "2026-09-10T17:05:44.826Z",
+  "built_at": "2026-09-10T17:12:24.520Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 470,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2104,
+    "functional_verbatim": 2106,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2598,
-  "tree_sha256": "5d4e0f8138d98ccd04fe0ae74d565738470c6b6210f6ccad1084e067ed8eab63",
+  "file_count": 2600,
+  "tree_sha256": "1fd37a4de38d4265a2f0956b03da63ce66a9e84de7ce8a24e1c66ae4465ea028",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "27b63233558ace04674687e72734ac62bf14b5ff1bc8f0f218ace0b708121a82"
+      "sha256": "967b335b7e06715fb8c07cea7af1141fa2dd3acb0da7873017048bb63aad15d0"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4297,7 +4297,7 @@
     {
       "path": "modules/discord/discord-bugs.js",
       "mode": "0000644",
-      "sha256": "52b463955cd7e57f8d194c161a76e2ade83481f3ee0a16759019a5b1f873b374"
+      "sha256": "000c766b483804e00ac523850e5cd8bc06a8f25aecf622a8629e1987014447b7"
     },
     {
       "path": "modules/discord/discord-channels.js",
@@ -4307,7 +4307,7 @@
     {
       "path": "modules/discord/discord-inbound.js",
       "mode": "0000644",
-      "sha256": "86099070386ff606ec14330375ac8c3145365307ae2ac354539731aebcc16563"
+      "sha256": "4779118709c5e5365c1acc7b7348bf2d812726530876ac99d9f28777db0477b2"
     },
     {
       "path": "modules/discord/discord-message-buffer.js",
@@ -4317,13 +4317,18 @@
     {
       "path": "modules/discord/discord-reaction.js",
       "mode": "0000644",
-      "sha256": "010766b857bd4c6727acdb2272de0442febaf81da6ba2da497b525a3e9d07df6"
+      "sha256": "6d5cd39f63c1f8d6d84e713606844eead96fc2366e720523067f46d845c10c8d"
     },
     {
       "path": "modules/discord/discord-role-sync.js",
       "mode": "0000644",
       "sha256": "852abc58bdec011b6d3bf222a35e198c6ea98a761d57a76be85477ef85ae54f5"
     },
+    {
+      "path": "modules/discord/lifecycle-port.js",
+      "mode": "0000644",
+      "sha256": "f5c7bb703d5c230f334322128129dfc02c6cc03fa9d8d37e00b67493de80a25d"
+    },
     {
       "path": "modules/discord/migrations/discord_001_board_messages.sql",
       "mode": "0000644",
@@ -7717,12 +7722,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "cd5ac6c00223a78f16aae563bafeadb8d919a15eb46aa70a955b31f1e4a4d14b"
+      "sha256": "9a655dfca70f3edf6083c6533004860a8a6da53455d732526dea6c0c37f3fcf1"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "3220018d398311cd5dad8ad43c895021eb38edcfa607bcbd72d16afae8323a6f"
+      "sha256": "80d6ffe532ebbd4d2165171ec5e2887487599e42c53e5411bb4048074d2eb0fb"
     },
     {
       "path": "public-docs/index.html",
@@ -9477,7 +9482,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ae0011557d1a9e04d4193538369dfc2c1cad08dfcefa0898c904566fd2374fe5"
+      "sha256": "cc274e241228f0ad4bb534674500d4daf228abcf6434241fed7152e49590f43f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10389,6 +10394,11 @@
       "mode": "0000644",
       "sha256": "c4e01ac01a3f01fc1a7aece34457a1660034164ab7cb65039f26d4a72d92a403"
     },
+    {
+      "path": "tests/discord_lifecycle_port.mjs",
+      "mode": "0000644",
+      "sha256": "eaa289f4e1fa413b30f23cc23a0aea166bd1d9c18a1992d07a0694b28c9fa3c2"
+    },
     {
       "path": "tests/discord_message_buffer.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1729,5 +1729,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.638 with no explicit bump. run 34502609272. (task 1002620)
   1.19.640 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.639 with no explicit bump. run 34506041899. (task 1002620)
+  1.19.641 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.640 with no explicit bump. run 34506718627. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/discord/discord-bugs.js

@@ -57,6 +57,7 @@ const { auditDiscordBot } = require('./discord-audit');
 const auth = require('./auth');
 const attachments = require('./bug-attachments');
 const { combineParts, createMessageAggregator } = require('./discord-message-buffer');
+const { lifecycleMethod } = require('./lifecycle-port');
 const api = require('../../src/module-api');
 const { LIMITS } = api;
 const log = api.logger('discord');
@@ -134,14 +135,10 @@ const realDeps = {
   // module rule, ADR 0083/0093). `ideas.capture` is the same door #ideas uses;
   // `lifecycle` answers which goal, on which still-open version.
   captureIdea: (...a) => api.resolve('ideas.capture')(...a),
-  // resolveOptional, not resolve: an instance running without the lifecycle module
-  // has no goals to suggest, and that is a reason to file the report WITHOUT a
-  // home — never a reason to lose it. Returns null, which lands it in the inbox.
-  suggestGoalForCapture: async (...a) => {
-    const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
-    if (!lifecycle || !lifecycle.suggestGoalForCapture) return null;
-    return lifecycle.suggestGoalForCapture(...a);
-  },
+  // Optional, not required: an instance running without the lifecycle module has
+  // no goals to suggest, and that is a reason to file the report WITHOUT a home
+  // — never a reason to lose it. Resolves null, which lands it in the inbox.
+  suggestGoalForCapture: lifecycleMethod('suggestGoalForCapture', () => null),
   insertAuditLog: db.insertAuditLog,
   persistImages: attachments.persistImages,
 };

package/modules/discord/discord-inbound.js

@@ -49,6 +49,7 @@ const { auditDiscordBot } = require('./discord-audit');
 const auth = require('./auth');
 const attachments = require('./bug-attachments');
 const { createMessageAggregator } = require('./discord-message-buffer');
+const { lifecycleMethod } = require('./lifecycle-port');
 const { LIMITS } = api;
 const log = api.logger('discord');
 
@@ -88,21 +89,13 @@ const realDeps = {
   // Lazy: resolve the `ideas.capture` port at CALL time, so the ideas module's
   // registration (at its route-factory mount) need not precede this module's load.
   captureIdea: (...a) => api.resolve('ideas.capture')(...a),
-  // resolveOptional, not resolve: a vanilla instance without the lifecycle
-  // module has no goals to suggest, and that is a reason to skip the hint —
-  // never a reason to lose the idea (the discord-bugs.js precedent).
-  suggestGoalForCapture: async (...a) => {
-    const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
-    if (!lifecycle || !lifecycle.suggestGoalForCapture) return null;
-    return lifecycle.suggestGoalForCapture(...a);
-  },
-  // Same resolveOptional posture — a vanilla instance without lifecycle has no
-  // versions to default to, which is a reason to skip the default, never the idea.
-  listVersions: async () => {
-    const lifecycle = api.resolveOptional && api.resolveOptional('lifecycle');
-    if (!lifecycle || !lifecycle.listVersions) return [];
-    return lifecycle.listVersions();
-  },
+  // Optional, not required: a vanilla instance without the lifecycle module has
+  // no goals to suggest, and that is a reason to skip the hint — never a reason
+  // to lose the idea (the discord-bugs.js precedent).
+  suggestGoalForCapture: lifecycleMethod('suggestGoalForCapture', () => null),
+  // Same posture — a vanilla instance without lifecycle has no versions to
+  // default to, which is a reason to skip the default, never the idea.
+  listVersions: lifecycleMethod('listVersions', () => []),
   insertAuditLog: db.insertAuditLog,
   persistImages: attachments.persistImages,
 };

package/modules/discord/discord-reaction.js

@@ -32,14 +32,13 @@ const { pool } = require('../../src/module-api');
 const db = require('./db');
 const { auditDiscordBot } = require('./discord-audit');
 const auth = require('./auth');
-const api = require('../../src/module-api');
-// VOTABLE_TASK_STATUSES is the lifecycle module's votable-status set, resolved via
+const { lifecycleMember } = require('./lifecycle-port');
+// VOTABLE_TASK_STATUSES is the lifecycle module's votable-status set, read via
 // the `lifecycle` kernel PORT (the doorway leak retired at BV1.R86) — a vote only
-// lands on confirmed/shipped work. Resolved at call time (this file runs under the
-// discord bot poller, well after the lifecycle port registers at boot). A
-// #ship-feed message is always about a shipped task, but we re-check rather than
-// trust the channel.
-const votableStatuses = () => api.resolveOptional('lifecycle')?.VOTABLE_TASK_STATUSES || new Set();
+// lands on confirmed/shipped work. lifecycle-port.js keeps the resolve late and
+// the absent-module fallback empty. A #ship-feed message is always about a
+// shipped task, but we re-check rather than trust the channel.
+const votableStatuses = () => lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set());
 const VOTING_RANKS = new Set(['metic', 'archon']);
 
 // PURE — extract the GDS task id from a #ship-feed message. The producer

package/modules/discord/lifecycle-port.js

@@ -0,0 +1,69 @@
+// modules/discord/lifecycle-port.js — the one place this module reaches the
+// OPTIONAL `lifecycle` kernel port.
+//
+// Why this file exists: four call sites across discord-bugs.js,
+// discord-inbound.js and discord-reaction.js each hand-rolled the same
+// resolveOptional('lifecycle') dance — resolve the port at call time, check the
+// member is actually there, fall back to an empty value when it is not. The
+// duplication was a grader nit on task 1003068 and the goal 1000071 R11 ship.
+//
+// THE POSTURE — resolveOptional, never resolve. `lifecycle` is an optional
+// module: a vanilla Cloud Bongos instance runs without it, so it has no goals
+// to suggest and no versions to default to. That is a reason to skip the hint,
+// NEVER a reason to lose the idea or drop the bug report. Every accessor here
+// degrades to an empty value, and nothing in this file throws.
+//
+// LATE BINDING IS LOAD-BEARING. The port is resolved inside each accessor, not
+// once at require time, because this module's files are loaded before the
+// lifecycle module registers its provider at boot. Hoisting the resolve to
+// module scope would pin the fallback forever — which is why every accessor
+// below is a function, and why none of them caches.
+//
+// A module may import only the published doorway (src/module-api.js), so this
+// helper lives beside its callers rather than in core (ADR 0083/0093).
+
+const api = require('../../src/module-api');
+
+// The port itself, or null. The `api.resolveOptional &&` guard is kept because
+// three of the four original copies carried it; discord-reaction.js was the odd
+// one out, so routing every caller through here also settles that inconsistency
+// in favour of the guard.
+function lifecyclePort() {
+  return (api.resolveOptional && api.resolveOptional('lifecycle')) || null;
+}
+
+// Read one member off the `lifecycle` port, or produce an empty stand-in.
+//
+// `makeFallback` is a FACTORY, not a value, and deliberately so: the fallbacks
+// in play are mutable (`[]`, `new Set()`), and handing every caller one shared
+// instance would turn a mutation by any one of them into a cross-call leak.
+// Each call gets a fresh fallback, exactly as the hand-rolled copies did.
+//
+// Reading as `lifecycle[member]` also keeps the port's GETTERS working —
+// VOTABLE_TASK_STATUSES is one (`get VOTABLE_TASK_STATUSES()`), so it must be
+// read off the object rather than destructured ahead of time.
+function lifecycleMember(member, makeFallback) {
+  const lifecycle = lifecyclePort();
+  const value = lifecycle ? lifecycle[member] : undefined;
+  return value === undefined || value === null ? makeFallback() : value;
+}
+
+// Wrap an optional lifecycle METHOD as an always-callable async function: it
+// forwards to the port when the module is present, and resolves to a fresh
+// fallback when either the module or that method is absent. The caller cannot
+// tell the two absences apart, and does not need to.
+//
+// `fn.call(lifecycle, …)`, not `fn(…)`: the call sites this replaced invoked
+// `lifecycle.method(...)`, so the port was the receiver. Every member the port
+// exports today is a delegating arrow that ignores `this`, so nothing currently
+// depends on it — which is exactly why dropping it would go unnoticed until a
+// provider that DOES use `this` broke silently. Preserve it.
+function lifecycleMethod(member, makeFallback) {
+  return async (...args) => {
+    const lifecycle = lifecyclePort();
+    const fn = lifecycle ? lifecycle[member] : undefined;
+    return typeof fn === 'function' ? fn.call(lifecycle, ...args) : makeFallback();
+  };
+}
+
+module.exports = { lifecycleMember, lifecycleMethod };

package/package-lock.json

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

package/package.json

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

@@ -0,0 +1,153 @@
+// tests/discord_lifecycle_port.mjs — the optional `lifecycle` port accessor
+// (task 1003630).
+//
+// The four hand-rolled resolveOptional('lifecycle') wrappers this helper
+// replaced were never covered: every existing discord test injects `deps`, so
+// the real `realDeps` wrappers — and specifically their absent-module branch —
+// ran only in production. That branch is the whole point of the file (a vanilla
+// Cloud Bongos instance has no lifecycle module), so it is what these pin:
+//
+//   1. present module  → the port's own member/method is used
+//   2. absent module   → a fresh empty fallback, and NO throw
+//   3. absent MEMBER on a present module → the same fallback (the caller cannot
+//      tell the two absences apart, and must not need to)
+//   4. the fallback is a FACTORY — each call gets its own instance, so one
+//      caller mutating an empty [] or Set() cannot leak into the next
+//   5. binding is LATE — a provider registered after require() is still seen
+//   6. the RECEIVER survives — `lifecycle.method(...)` was the original call
+//      shape, so `this` inside a method must still be the port, and a getter
+//      member must still fire
+//
+// DB-free and bot-free: it drives the seam registry directly.
+//
+// WHY IT LIVES HERE and not in modules/discord/tests/: module-owned tests are
+// discovered but gated by isModuleEnabled('discord'), and `discord` is OFF in
+// the vanilla pack (config/modules.neutral.json) with no config/modules.json in
+// the repo — so a module-owned copy is skipped in CI and would never actually
+// run. The runner's MODULE_TESTS map is curated and does not list discord, so
+// top-level tests/discord_*.mjs run unconditionally. This sits beside its three
+// siblings (discord_reaction, discord_inbound, discord_bugs) for that reason.
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const seams = require('../src/module-seams.js');
+const { lifecycleMember, lifecycleMethod } = require('../modules/discord/lifecycle-port.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+console.log('\ndiscord: the optional lifecycle port degrades instead of throwing');
+
+// ---- 1. the module is present ---------------------------------------------
+
+await test('lifecycleMember reads the real member off a registered port', () => {
+  seams._reset();
+  const statuses = new Set(['confirmed', 'shipped']);
+  seams.registerProvider('lifecycle', { VOTABLE_TASK_STATUSES: statuses });
+  assert.equal(lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set()), statuses);
+});
+
+await test('lifecycleMethod forwards args to the real method and returns its value', async () => {
+  seams._reset();
+  const seen = [];
+  seams.registerProvider('lifecycle', {
+    suggestGoalForCapture: async (draft, extra) => { seen.push([draft, extra]); return { goal_id: '1000091' }; },
+  });
+  const suggest = lifecycleMethod('suggestGoalForCapture', () => null);
+  assert.deepEqual(await suggest({ title: 'x' }, 7), { goal_id: '1000091' });
+  assert.deepEqual(seen, [[{ title: 'x' }, 7]], 'every argument is forwarded, in order');
+});
+
+// ---- 2. the module is absent (the vanilla instance) ------------------------
+
+await test('lifecycleMember falls back when NO provider is registered', () => {
+  seams._reset();
+  const out = lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set());
+  assert.ok(out instanceof Set);
+  assert.equal(out.size, 0, 'an empty votable set, so no vote can land');
+});
+
+await test('lifecycleMethod resolves the fallback rather than throwing', async () => {
+  seams._reset();
+  assert.equal(await lifecycleMethod('suggestGoalForCapture', () => null)({ title: 'x' }), null);
+  assert.deepEqual(await lifecycleMethod('listVersions', () => [])(), []);
+});
+
+// ---- 3. present module, absent member -------------------------------------
+
+await test('a present port MISSING the member falls back the same way', async () => {
+  seams._reset();
+  seams.registerProvider('lifecycle', { somethingElse: () => 'nope' });
+  assert.deepEqual(lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set()), new Set());
+  assert.equal(await lifecycleMethod('suggestGoalForCapture', () => null)({}), null);
+});
+
+await test('a member present but NOT a function still falls back', async () => {
+  seams._reset();
+  seams.registerProvider('lifecycle', { listVersions: 'not callable' });
+  assert.deepEqual(await lifecycleMethod('listVersions', () => [])(), []);
+});
+
+// ---- 4. the fallback is a factory, not a shared instance -------------------
+
+await test('each fallback is a FRESH instance — a mutation cannot leak forward', async () => {
+  seams._reset();
+  const first = lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set());
+  first.add('poisoned');
+  const second = lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set());
+  assert.equal(second.size, 0, 'the second caller must not see the first caller\'s write');
+  assert.notEqual(first, second);
+
+  const listVersions = lifecycleMethod('listVersions', () => []);
+  const a = await listVersions();
+  a.push('poisoned');
+  assert.deepEqual(await listVersions(), [], 'the same holds across method calls');
+});
+
+// ---- 6. the receiver and getters survive the indirection -------------------
+
+await test('a method still sees the PORT as `this` (not undefined)', async () => {
+  seams._reset();
+  const port = {
+    marker: 'the-port',
+    // A plain method, so `this` is meaningful — unlike the delegating arrows the
+    // real lifecycle module exports today.
+    async suggestGoalForCapture() { return this && this.marker; },
+  };
+  seams.registerProvider('lifecycle', port);
+  assert.equal(
+    await lifecycleMethod('suggestGoalForCapture', () => null)({}),
+    'the-port',
+    'fn.call(lifecycle, …) — dropping the receiver would return undefined here',
+  );
+});
+
+await test('a GETTER member is read off the object, so it actually fires', () => {
+  seams._reset();
+  let reads = 0;
+  seams.registerProvider('lifecycle', {
+    get VOTABLE_TASK_STATUSES() { reads += 1; return new Set(['shipped']); },
+  });
+  assert.deepEqual(lifecycleMember('VOTABLE_TASK_STATUSES', () => new Set()), new Set(['shipped']));
+  assert.equal(reads, 1, 'the real port defines this member as a getter');
+});
+
+// ---- 5. binding is late ----------------------------------------------------
+
+await test('a provider registered AFTER require() is still picked up', async () => {
+  seams._reset();
+  const suggest = lifecycleMethod('suggestGoalForCapture', () => null);
+  assert.equal(await suggest({}), null, 'nothing registered yet — the fallback');
+  seams.registerProvider('lifecycle', { suggestGoalForCapture: async () => ({ goal_id: '42' }) });
+  assert.deepEqual(await suggest({}), { goal_id: '42' }, 'the late registration is seen without a re-require');
+});
+
+seams._reset();
+console.log(`\n  ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);