@bongos/core 1.19.655 → 1.19.656

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.655",
-  "core_contract": "1.19.655",
-  "source_commit": "0385761c80a2ab6960eb0553532e3d2f3a55714d",
+  "core_version": "1.19.656",
+  "core_contract": "1.19.656",
+  "source_commit": "c0c5d7b3e5b4f9be24da806b898180fc4bf0df47",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T00:16:29.379Z",
+  "built_at": "2026-09-11T00:27:13.017Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 472,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2607,
-  "tree_sha256": "e0d112687c5e0ef345193d8be0fc71fca2ce378fba76eeb0441b4b5b347d160e",
+  "tree_sha256": "90e88ec865416bea870aef7c0ea90db47124defc012e894bc04037bea59f12a6",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -2782,7 +2782,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7ab264db84c1eab7bc17fb54d875a7c56ed6142adc3c55fd45dc4e3470d30dae"
+      "sha256": "448e81f5dfb15330d406be135e4ada5c3cfcf0751fca4457a7c91ab58d836d10"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5662,7 +5662,7 @@
     {
       "path": "modules/lifecycle/db-rank-authz.js",
       "mode": "0000644",
-      "sha256": "ac33825a705a0d541fc7fe94858f967ef8ef9713a2b7a1f1a03ce268494bb317"
+      "sha256": "e5feff1eb42ad631b6c0165c23224d8ac56ef7f40e5d238afb09013501e9db7c"
     },
     {
       "path": "modules/lifecycle/db-shared.js",
@@ -7742,12 +7742,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8bd02249a0695644a522b26a0a2e93519c0359d2b47b10855f69b2e24654d9fb"
+      "sha256": "667fc77f1bfd67239fa405a73b70b64ec77419d97da57bc8350c96ba3c68197b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a0ca266a85fbe549d63f4b62a04e4ac17f72bf1cd0500af154ca5597eb801c70"
+      "sha256": "9bee6edf68d9dc8177a24349a4c444c1829ff77619a511be70c8a49329726ac8"
     },
     {
       "path": "public-docs/index.html",
@@ -9502,7 +9502,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "503fd9b1f372ec8577fff63dc486b9e33a801a3114e5a151cf47d71f818bf4de"
+      "sha256": "3077ef167f846985e33e1d8316b78cefa5e7ff4825b9a0a7e1b71187a49e4636"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10847,7 +10847,7 @@
     {
       "path": "tests/government_claim_eligibility.mjs",
       "mode": "0000644",
-      "sha256": "7eb103c6a201345728af5002aae1be09c1f3b1459b74bef7ea14e990a28dd05b"
+      "sha256": "1989a7e5e39a6bb177dfd86e610c0806c96fdc97f9149800de431af816f2c31a"
     },
     {
       "path": "tests/government_config.mjs",

package/docs/module-api-changelog.md

@@ -1759,5 +1759,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.653 with no explicit bump. run 34544345437. (task 1002620)
   1.19.655 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.654 with no explicit bump. run 34545744588. (task 1002620)
+  1.19.656 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.655 with no explicit bump. run 34546461767. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-rank-authz.js

@@ -80,15 +80,33 @@ function xenosClaimAllowed(rank, newcomerFriendly) {
 
 // claimPermissionsFor — the builder's effective permission set for the claim
 // decision, read through the `governance` kernel PORT (never by importing the
-// module — the one-way rule, ADR 0083). Returns a Set, or NULL when authority
-// cannot be ESTABLISHED, which claimEligibilityAllows reads as "fall back to the
-// incumbent rank rule":
-//   • the governance module is not mounted (no port), or the resolver throws;
-//   • the builder resolves to ZERO permissions — i.e. they hold no role row.
-//     governance_002's backfill is run-once and nothing yet re-assigns a rank-role
-//     when a builder is created or re-ranked, so this is a live gap, not a theory.
-// Every seeded rank-role grants at least twelve permissions, so an empty set never
-// means "a real role that grants nothing" today.
+// module — the one-way rule, ADR 0083).
+//
+// NULL means authority could not be ESTABLISHED, which claimEligibilityAllows
+// reads as "fall back to the incumbent rank rule". Exactly two things mean that:
+//   • the governance module is not mounted (no port), so there is no authority
+//     system to ask;
+//   • the resolver threw, so the answer is unknown rather than empty.
+//
+// AN EMPTY SET IS AN ANSWER, NOT A FAILURE (task 1003816). It used to be folded
+// into the null above, on the stated grounds that governance_002's backfill was
+// run-once and nothing re-assigned a rank-role afterwards — so a builder holding
+// no role row was a live gap rather than a real verdict. That is no longer true,
+// and the three writes that closed it are all shipped:
+//   • BV1.R95b rotates the role inside the rank-change transaction, and syncs it
+//     on every sign-in (src/bongos/auth-admission.js safeSyncRankRole);
+//   • task 1003193 rotates it in-tx on offboard AND reactivation;
+//   • governance_005 repaired the rows already written.
+// governance_005 states the intended reading in as many words — a builder with no
+// role row "resolves to the empty set (denied everywhere)" — and
+// syncGovernanceRankRole calls that same outcome "the fail-closed answer". Folding
+// it back into the rank rule is what stopped those three from being true at the
+// claim gate, so the empty set now flows through as a real deny.
+//
+// The residual way to hold no role row is the sign-in sync failing transiently
+// (it is deliberately best-effort so a governance hiccup cannot block a sign-in).
+// Denying the claim is the correct read of that state, and it self-repairs on the
+// next successful sign-in.
 //
 // Called BEFORE the claim transaction opens: authority is a per-request read (ADR
 // 0016 — resolved server-side, uncached), and taking a second pool connection while
@@ -98,7 +116,9 @@ async function claimPermissionsFor(builderId) {
   if (!governance || typeof governance.resolveBuilderPermissions !== 'function') return null;
   try {
     const keys = await governance.resolveBuilderPermissions(builderId);
-    if (!keys || keys.length === 0) return null;
+    // A non-array is a broken port contract, not a verdict — resolveBuilderPermissions
+    // always returns an array. Treat it as "could not establish", never as "denied".
+    if (!Array.isArray(keys)) return null;
     return new Set(keys);
   } catch (err) {
     console.error('[gds] claim eligibility: permission resolve failed, falling back to the rank rule', err);

package/package-lock.json

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

package/package.json

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

@@ -37,6 +37,13 @@ const LIFECYCLE = path.join(ROOT, 'modules', 'lifecycle');
 const eligibility = require(path.join(LIFECYCLE, 'claim-eligibility.js'));
 const db = require(path.join(LIFECYCLE, 'db.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
+// The doorway, so section D can stand a stub `government` port up in front of the
+// REAL claimPermissionsFor instead of re-implementing its branches in the test.
+const moduleApi = require(path.join(ROOT, 'src', 'module-api.js'));
+// claimPermissionsFor is NOT on the db.js facade — db-claims.js imports it from
+// the authz module directly, so the test reads it from the same place the real
+// caller does rather than from a re-export that does not exist.
+const rankAuthz = require(path.join(LIFECYCLE, 'db-rank-authz.js'));
 import { lifecycleDbSource } from './helpers.mjs';
 
 const { CLAIM_ANY, CLAIM_NEWCOMER, permissionAllowsClaim, claimEligibilityAllows } = eligibility;
@@ -262,3 +269,78 @@ test('the abuse case stays blocked: a xenos cannot reach the general queue by an
   assert.equal(permissionAllowsClaim(held, false), false);
   assert.equal(permissionAllowsClaim(held, true), true);
 });
+
+// --- D. claimPermissionsFor's three-way answer (task 1003816) ---------------
+//
+// The function this section covers had NO test of its own: every case above
+// drives the pure consumer (claimEligibilityAllows) with a hand-made
+// heldPermissions value, so nothing proved which value the REAL reader produces.
+// That is exactly where the bug lived — an empty permission set was folded in
+// with "could not establish authority" and silently became a rank-rule fallback.
+//
+// The distinction is the whole point, so it is asserted as a distinction: null
+// (fall back) for the two unestablished cases, a Set (a real verdict, denied when
+// empty) whenever the resolver actually answered.
+const realResolveOptional = moduleApi.resolveOptional;
+async function withGovernance(stub, fn) {
+  moduleApi.resolveOptional = (name) => (name === 'government' ? stub : realResolveOptional.call(moduleApi, name));
+  try { return await fn(); } finally { moduleApi.resolveOptional = realResolveOptional; }
+}
+
+test('no governance port — authority cannot be established, so the rank rule decides', async () => {
+  await withGovernance(undefined, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+  // A port object that does not implement the resolver is the same situation.
+  await withGovernance({}, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+});
+
+test('the resolver throwing is UNKNOWN, not empty — still the rank rule', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => { throw new Error('synthetic resolver outage'); } }, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+});
+
+test('a broken port contract (non-array) is unknown, never a deny', async () => {
+  for (const bad of [null, undefined, 'task.claim.any', 42, {}]) {
+    await withGovernance({ resolveBuilderPermissions: async () => bad }, async () => {
+      assert.equal(await rankAuthz.claimPermissionsFor('42'), null, `a ${typeof bad} return must not read as "denied"`);
+    });
+  }
+});
+
+test('ZERO permissions is a real verdict now, not a fallback (the 1003816 fix)', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => [] }, async () => {
+    const held = await rankAuthz.claimPermissionsFor('42');
+    assert.ok(held instanceof Set, 'an answered resolve returns a Set, so the rank rule is NOT consulted');
+    assert.equal(held.size, 0);
+    // And the consumer turns that into a deny for every queue, however permissive
+    // the incumbent rank rule would have been.
+    for (const nf of NF_VALUES) {
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: held, newcomerFriendly: nf, rankRuleAllows: true }),
+        false,
+        'a builder with no role row is denied even where the rank rule would allow',
+      );
+    }
+  });
+});
+
+test('a real permission set is passed through as the verdict', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => [CLAIM_ANY] }, async () => {
+    const held = await rankAuthz.claimPermissionsFor('42');
+    assert.ok(held instanceof Set);
+    assert.equal(held.has(CLAIM_ANY), true);
+    assert.equal(claimEligibilityAllows({ heldPermissions: held, newcomerFriendly: false, rankRuleAllows: false }), true);
+  });
+});
+
+test('the doc comment no longer argues for the fallback it describes retiring', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'db-rank-authz.js'), 'utf8');
+  assert.ok(
+    !/nothing yet re-assigns a rank-role/.test(src),
+    'the stale "nothing yet re-assigns a rank-role" claim is false since BV1.R95b + task 1003193 — it must not survive the fix',
+  );
+});