@bongos/core 1.19.221 → 1.19.222

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.221",
-  "core_contract": "1.19.221",
-  "source_commit": "30b2efb16495a941d6a4b70fd03b772cd69bce23",
+  "core_version": "1.19.222",
+  "core_contract": "1.19.222",
+  "source_commit": "4425d4ace9a3b996b50be1b59002e4cf85f027db",
   "source_ref": "HEAD",
-  "built_at": "2026-08-18T03:23:47.936Z",
+  "built_at": "2026-08-18T03:36:13.104Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 311,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1635,
-  "tree_sha256": "aa35386f9d066c748b4374cf27b4dc5fbf48ccfef32dfb8ef8c60cf44fdb8c96",
+  "tree_sha256": "6bf87d2a8bb013b102f3ae8287a56fd6fe7ed99ed49b48f4607abcb047f59f74",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -397,7 +397,7 @@
     {
       "path": "config/government.neutral.json",
       "mode": "0000644",
-      "sha256": "70fe731d06dd9744178a27ec4379ee8c769f9a45d9a585f095b1765433767afc"
+      "sha256": "7ab2f7aff4bc52d09ee1a4aa3b76a7646ff2ee462bbc459941a468a9cc1246eb"
     },
     {
       "path": "config/modules.neutral.json",
@@ -2902,7 +2902,7 @@
     {
       "path": "modules/government/config.js",
       "mode": "0000644",
-      "sha256": "183bca92e8ba897871287aeb58e6f9cfebcf9510b15d6cd9701066ce7c108edd"
+      "sha256": "dc4784b8d1f39c10c62ee935c6ff7d2d85db42f80479750e2ca2b8ca2877ebc6"
     },
     {
       "path": "modules/government/db.js",
@@ -4292,12 +4292,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "5b55ea236b725452ef02e308616d3827927f68e82a483022a856e4066864dc99"
+      "sha256": "44f9bf150c24b1bed1d68bcd0a9661b4c659a32e5087a268a21b7b4370d7099a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ec221145b014962cce2d2c9fc9e231a0b296bb65153ba8079e30f2f4e80b9df7"
+      "sha256": "231179c4f9a0fffdd0ecdb48ceb161e99e7aab4e3058296762561d510f15281a"
     },
     {
       "path": "public-docs/index.html",
@@ -5912,7 +5912,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4aa9331871262decd3e4b2a16e1cd9ca58b4e4000228cde02086ad209a1bb4b7"
+      "sha256": "e999662a04f1981cbf01b2a9b5d18d33e71034311702fac6e5a6e0a0a209dcc0"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6847,7 +6847,7 @@
     {
       "path": "tests/government_config.mjs",
       "mode": "0000644",
-      "sha256": "979deef4473243dc86ab13b9284104bce71f6a1ee839acc6c5a6db04770cd62c"
+      "sha256": "330372412c80d8d33698eba68a5c19e79daff17b0d820a9a797c883071a5641f"
     },
     {
       "path": "tests/government_fold.mjs",

package/config/government.neutral.json

@@ -17,5 +17,12 @@
       "label": "Archon",
       "description": "Seeded rank \u2014 top authority. Adds the admin + system (non-grantable) powers."
     }
+  },
+  "_board_note": "The CONSTITUTION \u2014 the Board Room's rule set (BV1.R05 of goal 1000069, ADR 0175). Day one runs the real machinery configured to MONARCHY: membership 'rank:archon', pass_rule 'first_ratifier', no clock. That is a set of VALUES, never a separate code path \u2014 the same resolver, tally and window run whatever the numbers say, so flipping to a full board later changes configuration and not a branch that has never executed. RECOMMENDED once a project has a board worth sitting: all Archons, one vote each, pass_rule 'consent', window_minutes 90 \u2014 documented here, deliberately not the default. membership is the predicate 'rank:<key>'; it may name a CUSTOM rank, and WHO HOLDS that rank stays a DB row resolved per request (this file grants nobody anything). pass_rule is one of first_ratifier | consent. window_minutes is null for no clock, else whole minutes up to 7 days. Every unreadable field falls back to ITS OWN default, and the fallbacks are the STRICT end of both axes, so a malformed constitution can never resolve to a board that is wider or easier to pass than this one. To customise, copy to config/government.json and edit there \u2014 not by env var: a label is cosmetic, a constitution is not.",
+  "board": {
+    "membership": "rank:archon",
+    "pass_rule": "first_ratifier",
+    "window_minutes": null,
+    "close_early_on_full_turnout": true
   }
 }

package/modules/government/config.js

@@ -126,6 +126,78 @@ function sanitizeRole(key, raw) {
   });
 }
 
+// ── the constitution: who governs, how an item passes, how long a sitting runs ──
+// BV1.R05 of goal 1000069 (ADR 0175). The Board Room's rule set is CONFIGURATION on
+// the real machinery, never a separate code path: day one runs the same resolver,
+// the same tally and the same window as a full consent board, with the numbers set
+// to monarchy (owner decision 1). Flipping the switch later changes values, not a
+// branch that has never executed.
+//
+// It lives here, beside the rank templates, for the same reason ADR 0175 put the
+// board tables inside modules/government/: this is an AUTHORITY question, and
+// authority is this module's territory.
+//
+// STILL NOT A SOURCE OF AUTHORITY TRUTH. Same wall as the rest of this file — the
+// predicate says which RANK governs; who actually holds that rank stays a DB row,
+// resolved per request by R06's membership resolver. Nothing here names a builder,
+// and a config edit cannot make anyone a board member.
+const BOARD_DEFAULTS = Object.freeze({
+  membership: 'rank:archon',
+  pass_rule: 'first_ratifier',
+  window_minutes: null,          // null = no clock; monarchy does not sit
+  close_early_on_full_turnout: true,
+});
+
+// The pass rules that EXIST, not the ones a project should pick. `consent` is the
+// documented recommendation once a project has a board worth sitting (all Archons,
+// one vote each, consent, a 90-minute window); `first_ratifier` is the day-one
+// default and what an unreadable value falls back to.
+const PASS_RULES = Object.freeze(['first_ratifier', 'consent']);
+
+// A membership predicate is `rank:<key>` — the only grammar v1 defines. It is NOT
+// validated against catalog.RANK_ORDER on purpose: a project may govern by a CUSTOM
+// rank, and custom ranks are DB rows this file cannot see (checking here would make
+// config authoritative over a live rank list, which is exactly the inversion the
+// header forbids). R06 resolves the predicate against the live ranks and yields an
+// empty board if it names nothing — fail-closed there, shape-checked here.
+const MEMBERSHIP_RE = /^rank:[a-z][a-z0-9_-]*$/;
+
+// A sitting longer than a week is indistinguishable from no clock at all, and a
+// zero/negative window would close every item the instant it opened. Both are far
+// likelier to be a typo than an intent, so both fall back to the default.
+const MAX_WINDOW_MINUTES = 7 * 24 * 60;
+
+// Sanitize the board block. Every unreadable field falls back to ITS OWN default
+// independently, so one typo costs one setting rather than the whole constitution.
+//
+// THE INVARIANT THAT MATTERS: a malformed constitution must never resolve to a board
+// that is WIDER or EASIER to pass than the platform default. `rank:archon` is the
+// narrowest membership this project can express, and `first_ratifier` demands an
+// affirmative act by a member where `consent` lets an empty window pass unopposed
+// (owner decision 6). So the fallbacks are the strict end of both axes — a broken
+// config cannot quietly enfranchise anyone or lower the bar.
+function sanitizeBoard(raw) {
+  const r = isObj(raw) ? raw : {};
+  const membership = typeof r.membership === 'string' && MEMBERSHIP_RE.test(r.membership)
+    ? r.membership
+    : BOARD_DEFAULTS.membership;
+  const passRule = PASS_RULES.includes(r.pass_rule) ? r.pass_rule : BOARD_DEFAULTS.pass_rule;
+  // null is a MEANINGFUL value (no clock), so it is accepted rather than defaulted.
+  // Anything else must be a whole number of minutes inside the sane band.
+  const w = r.window_minutes;
+  const windowMinutes = w === null ? null
+    : (Number.isInteger(w) && w > 0 && w <= MAX_WINDOW_MINUTES ? w : BOARD_DEFAULTS.window_minutes);
+  const closeEarly = typeof r.close_early_on_full_turnout === 'boolean'
+    ? r.close_early_on_full_turnout
+    : BOARD_DEFAULTS.close_early_on_full_turnout;
+  return Object.freeze({
+    membership,
+    pass_rule: passRule,
+    window_minutes: windowMinutes,
+    close_early_on_full_turnout: closeEarly,
+  });
+}
+
 // Pure resolver — all inputs injected, so tests drive it with zero I/O (the
 // resolveBranding pattern).
 function resolveGovernmentConfig({ neutral, instance, env = process.env } = {}) {
@@ -146,7 +218,16 @@ function resolveGovernmentConfig({ neutral, instance, env = process.env } = {})
   for (const key of catalog.RANK_ORDER) {
     if (!ranks[key]) ranks[key] = sanitizeRole(key, {});
   }
-  return Object.freeze({ ranks: Object.freeze(ranks) });
+  // The board block merges FIELD BY FIELD, neutral under instance, so a project that
+  // wants only a different window keeps the platform's answer for everything else
+  // rather than having to restate the whole constitution to change one number.
+  //
+  // Deliberately NOT env-overridable. applyLabelOverrides exists because a label is
+  // cosmetic; the constitution is not, and an env var that could change who governs
+  // would be a way to alter authority from outside the checkout AND outside the DB.
+  // Changing the constitution is a board act (owner decision 11), not a deploy flag.
+  const board = sanitizeBoard({ ...((neutral || {}).board || {}), ...((instance || {}).board || {}) });
+  return Object.freeze({ ranks: Object.freeze(ranks), board });
 }
 
 // READ, never require(): a bare require('../../config/X.json') of a boundary-excluded
@@ -179,6 +260,10 @@ module.exports = {
   resolveGovernmentConfig,
   loadGovernmentConfig,
   grantableOnly,
+  sanitizeBoard,
+  BOARD_DEFAULTS,
+  PASS_RULES,
+  MAX_WINDOW_MINUTES,
   NEUTRAL_PATH,
   INSTANCE_PATH,
 };

package/package-lock.json

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

package/package.json

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

@@ -869,8 +869,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.219 with no explicit bump. run 32094701831. (task 1002620)
 //   1.19.221 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.220 with no explicit bump. run 32095276039. (task 1002620)
+//   1.19.222 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.221 with no explicit bump. run 32096034408. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.221'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.222'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // 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_config.mjs

@@ -18,7 +18,8 @@ const GOV = path.join(ROOT, 'modules', 'government');
 const config = require(path.join(GOV, 'config.js'));
 const catalog = require(path.join(GOV, 'catalog.js'));
 const { envPrefix } = require(path.join(ROOT, 'src', 'instance-config'));
-const { resolveGovernmentConfig, loadGovernmentConfig, grantableOnly, NEUTRAL_PATH, INSTANCE_PATH } = config;
+const { resolveGovernmentConfig, loadGovernmentConfig, grantableOnly, sanitizeBoard,
+        BOARD_DEFAULTS, PASS_RULES, MAX_WINDOW_MINUTES, NEUTRAL_PATH, INSTANCE_PATH } = config;
 
 const NEUTRAL = JSON.parse(fs.readFileSync(NEUTRAL_PATH, 'utf8'));
 // No env by default — every precedence test injects exactly the env it is asserting on.
@@ -158,11 +159,20 @@ test('the neutral starter carries no host-specific identity (a vanilla instance
   const { scanPromptIdentity } = require(path.join(ROOT, 'scripts', 'gds', 'fitness.js'));
   const raw = fs.readFileSync(NEUTRAL_PATH, 'utf8');
   assert.deepEqual(scanPromptIdentity('config/government.neutral.json', raw, '.json'), []);
-  // And it carries only templates — never a live per-builder assignment.
-  assert.deepEqual(Object.keys(NEUTRAL).filter((k) => k !== '_note'), ['ranks']);
+  // And it carries only templates — never a live per-builder assignment. The key list
+  // is an ALLOWLIST on purpose: a new top-level key has to be justified here before it
+  // can ship, which is what stops a live grant or assignment arriving unnoticed.
+  // `board` joined it in R05 (goal 1000069) — it is the CONSTITUTION, a rule shape, and
+  // the assertion below pins that it names no builder. `_`-prefixed keys are prose notes.
+  assert.deepEqual(Object.keys(NEUTRAL).filter((k) => !k.startsWith('_')).sort(), ['board', 'ranks']);
   for (const rank of Object.values(NEUTRAL.ranks)) {
     assert.ok(!('permissions' in rank), 'the neutral seeded ranks carry labels only, never grants');
   }
+  // The constitution says which RANK governs, never WHO. A builder id, login or handle
+  // here would make config authoritative over membership, which is R06's DB question.
+  assert.match(NEUTRAL.board.membership, /^rank:/, 'membership is a rank predicate, not a person');
+  assert.equal(JSON.stringify(NEUTRAL.board).includes('builder'), false,
+    'the neutral constitution must not reference any builder');
 });
 
 test('the two config paths are the branding-shaped neutral/instance pair under config/', () => {
@@ -185,3 +195,137 @@ test('the neutral starter publishes with the core (a packaged vanilla instance n
   assert.equal(isPublishable('config/government.neutral.json'), true);
   assert.equal(isPublishable('config/government.json'), false, "a host's filled-in pack is instance content");
 });
+
+// ── the constitution (BV1.R05 of goal 1000069, ADR 0175) ────────────────────────
+//
+// The board block is CONFIGURATION on the real machinery, not a second code path.
+// These tests pin the two things that make that safe: the platform default really is
+// monarchy, and a malformed constitution can never resolve to a board that is WIDER
+// or EASIER to pass than that default. A config file is editable by anyone who can
+// write the checkout — the same trust argument the permission tests above make.
+
+test('day one is monarchy: the neutral starter ships the Archon-ratifies constitution', () => {
+  const out = resolveGovernmentConfig({ neutral: NEUTRAL, env: NO_ENV });
+  assert.deepEqual(out.board, {
+    membership: 'rank:archon',
+    pass_rule: 'first_ratifier',
+    window_minutes: null,               // no clock — monarchy does not sit
+    close_early_on_full_turnout: true,
+  }, 'owner decision 1: the real machinery, configured to monarchy');
+  assert.deepEqual(NEUTRAL.board, out.board, 'the shipped file and the resolved value must agree');
+});
+
+test('a project with no board block at all still gets the full default constitution', () => {
+  // The vanilla-boot case, and the upgrade case: an instance whose config predates
+  // R05 has no board key. It must resolve to monarchy, not to undefined fields that
+  // R06 would then have to guess at.
+  const out = resolveGovernmentConfig({ neutral: {}, instance: {}, env: NO_ENV });
+  assert.deepEqual(out.board, BOARD_DEFAULTS);
+});
+
+test('the instance pack overrides the constitution FIELD BY FIELD', () => {
+  // Changing one number must not require restating the whole constitution.
+  const out = resolveGovernmentConfig({
+    neutral: NEUTRAL,
+    instance: { board: { pass_rule: 'consent', window_minutes: 90 } },
+    env: NO_ENV,
+  });
+  assert.equal(out.board.pass_rule, 'consent');
+  assert.equal(out.board.window_minutes, 90);
+  assert.equal(out.board.membership, 'rank:archon', 'untouched fields keep the neutral answer');
+  assert.equal(out.board.close_early_on_full_turnout, true);
+});
+
+test('the documented recommendation is expressible as pure configuration', () => {
+  // "all Archons, one vote each, consent, a 90-minute window" — the spec's recommended
+  // starting point. If this could not be reached by config alone, the "values not code
+  // paths" claim would be false.
+  const out = resolveGovernmentConfig({
+    neutral: NEUTRAL,
+    instance: { board: { membership: 'rank:archon', pass_rule: 'consent', window_minutes: 90 } },
+    env: NO_ENV,
+  });
+  assert.deepEqual(out.board, {
+    membership: 'rank:archon',
+    pass_rule: 'consent',
+    window_minutes: 90,
+    close_early_on_full_turnout: true,
+  });
+});
+
+test('a malformed constitution can never widen the franchise or lower the bar', () => {
+  // The invariant, enumerated over every junk shape a hand-edited file can take.
+  // rank:archon is the narrowest membership expressible; first_ratifier demands an
+  // affirmative act by a member where consent lets an empty window pass (decision 6).
+  const junk = [
+    undefined, null, 42, 'consent', [],
+    { membership: 'everyone' },
+    { membership: 'rank:' },
+    { membership: 'RANK:ARCHON' },          // grammar is lowercase
+    { membership: '' },
+    { membership: { rank: 'archon' } },
+    { pass_rule: 'unanimous' },
+    { pass_rule: 'majority' },
+    { pass_rule: null },
+    { membership: 'rank:xenos; DROP TABLE government_ranks' },
+  ];
+  for (const raw of junk) {
+    const b = sanitizeBoard(raw);
+    assert.equal(b.membership, BOARD_DEFAULTS.membership, `${JSON.stringify(raw)} must not widen membership`);
+    assert.equal(b.pass_rule, BOARD_DEFAULTS.pass_rule, `${JSON.stringify(raw)} must not lower the pass bar`);
+  }
+});
+
+test('one unreadable field costs one setting, not the whole constitution', () => {
+  const b = sanitizeBoard({ membership: 'rank:metic', pass_rule: 'nonsense', window_minutes: 30 });
+  assert.equal(b.membership, 'rank:metic', 'a VALID field survives its neighbour being junk');
+  assert.equal(b.window_minutes, 30);
+  assert.equal(b.pass_rule, BOARD_DEFAULTS.pass_rule, 'only the broken field falls back');
+});
+
+test('membership accepts a CUSTOM rank — config cannot be authoritative over the live rank list', () => {
+  // Deliberately NOT validated against catalog.RANK_ORDER: custom ranks are DB rows
+  // this file cannot see, and checking here would invert the config/DB boundary.
+  // R06 resolves the predicate against live ranks and yields an empty board if it
+  // names nothing, so the fail-closed step happens where the truth lives.
+  assert.equal(sanitizeBoard({ membership: 'rank:triage-helper' }).membership, 'rank:triage-helper');
+  assert.equal(sanitizeBoard({ membership: 'rank:board_member' }).membership, 'rank:board_member');
+});
+
+test('window_minutes: null means no clock, and only a sane whole-minute band is accepted', () => {
+  assert.equal(sanitizeBoard({ window_minutes: null }).window_minutes, null, 'null is MEANINGFUL, not missing');
+  assert.equal(sanitizeBoard({ window_minutes: 90 }).window_minutes, 90);
+  assert.equal(sanitizeBoard({ window_minutes: MAX_WINDOW_MINUTES }).window_minutes, MAX_WINDOW_MINUTES);
+  for (const bad of [0, -5, 1.5, '90', NaN, Infinity, MAX_WINDOW_MINUTES + 1]) {
+    assert.equal(sanitizeBoard({ window_minutes: bad }).window_minutes, BOARD_DEFAULTS.window_minutes,
+      `window_minutes ${String(bad)} must fall back — a zero window closes on open, a huge one is not a sitting`);
+  }
+});
+
+test('no env var can change the constitution', () => {
+  // applyLabelOverrides exists because a label is cosmetic. Authority is not: an env
+  // var that could move the board would be a way to change who governs from outside
+  // both the checkout and the DB. Changing it is a board act (owner decision 11).
+  const p = envPrefix();
+  const hostile = {
+    [`${p}_GOVERNMENT_BOARD_MEMBERSHIP`]: 'rank:xenos',
+    [`${p}_GOVERNMENT_BOARD_PASS_RULE`]: 'consent',
+    [`${p}_GOVERNMENT_BOARD`]: JSON.stringify({ membership: 'rank:xenos' }),
+    [`${p}_GOVERNMENT_RANK_LABELS`]: 'archon=Owner',
+  };
+  const out = resolveGovernmentConfig({ neutral: NEUTRAL, env: hostile });
+  assert.deepEqual(out.board, NEUTRAL.board, 'the constitution is untouched by env');
+  assert.equal(out.ranks.archon.label, 'Owner', 'while the LABEL override still works — proving env was read');
+});
+
+test('the resolved constitution is frozen, like the rest of the config contract', () => {
+  const out = resolveGovernmentConfig({ neutral: NEUTRAL, env: NO_ENV });
+  assert.ok(Object.isFrozen(out.board));
+  assert.throws(() => { 'use strict'; out.board.membership = 'rank:xenos'; });
+});
+
+test('PASS_RULES is the closed set the rest of the goal codes against', () => {
+  assert.deepEqual([...PASS_RULES].sort(), ['consent', 'first_ratifier']);
+  assert.ok(Object.isFrozen(PASS_RULES));
+  assert.ok(PASS_RULES.includes(BOARD_DEFAULTS.pass_rule), 'the default must be a member of the set');
+});