@bongos/core 1.19.732 → 1.19.734

package/modules/provisioning/provisioning.js

@@ -173,12 +173,28 @@ const RESTART_SHAPES = new Set(['co-tenant', 'standalone']);
 // and coherent because strict holds only the pin: the worst case is a project whose
 // deploy waits on a review nobody has done, which is visible and owner-releasable,
 // never a stranded builder.
+// `spend_payer` is the project's answer to "who pays when a module spends money
+// on a caller's behalf?" (task 1003884). `project` puts the bill on whoever runs
+// the instance; `builder` on the caller who spent it; `none` is no payer at all.
+//
+// It is the one setting that can REFUSE A MODULE. src/modules.js will not enable a
+// module whose manifest declares `spend.requiresPayer` while this project's join
+// door is `open` and this key is `none` — an account created seconds ago could
+// otherwise spend the instance's money with nobody to bill. The refusal is at
+// config load, so the module's routes never mount at all.
+//
+// Its default IS today's behaviour, unlike `artist_gate` above: no project has
+// ever named a payer, and `none` is what every existing row already means. That
+// costs nothing today because the only module declaring metered spend ships
+// `default: false` — an owner who turns it on is the first person this key ever
+// stops, and the warning tells them which two words fix it.
 const SETTINGS_VOCAB = Object.freeze({
   platform_visibility: ['public', 'gated'],
   joinability: ['open', 'apply', 'invite_only'],
   visibility: ['public', 'private', 'stealth'],
   join_grant: ['view', 'apply', 'full'],
   artist_gate: ['off', 'advisory', 'strict'],
+  spend_payer: ['none', 'project', 'builder'],
 });
 // Default = today's behavior on every axis, including the join door: ADR 0182's
 // migration gives the hub column the same `public` default, "existing rows keep
@@ -186,7 +202,7 @@ const SETTINGS_VOCAB = Object.freeze({
 // owner's ruling rather than the status quo — see the note above it.
 const DEFAULT_SETTINGS = Object.freeze({
   platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full',
-  artist_gate: 'strict',
+  artist_gate: 'strict', spend_payer: 'none',
 });
 
 // The project's PLANET (task 1003347, direction record §16): how the platform

package/modules/provisioning/tests/provisioning.mjs

@@ -263,27 +263,27 @@ await ta('recordDnsNote / clearErrorNote are NARROW single-column updates — no
 console.log('\nPer-project settings (task 1003040):');
 
 t('effectiveSettings: defaults for a bare/empty row = today\'s behavior; stored keys overlay; junk falls back', () => {
-  assert.deepEqual(P.effectiveSettings(null), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
-  assert.deepEqual(P.effectiveSettings({}), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
-  assert.deepEqual(P.effectiveSettings({ settings: {} }), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' });
+  assert.deepEqual(P.effectiveSettings(null), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' });
+  assert.deepEqual(P.effectiveSettings({}), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' });
+  assert.deepEqual(P.effectiveSettings({ settings: {} }), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' });
   assert.deepEqual(
     P.effectiveSettings({ settings: { platform_visibility: 'gated' } }),
-    { platform_visibility: 'gated', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' },
+    { platform_visibility: 'gated', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' },
     'a stored key overlays only itself'
   );
   assert.deepEqual(
     P.effectiveSettings({ settings: { platform_visibility: 'bogus', joinability: 'invite_only', future_key: 'x', visibility: 'unlisted', join_grant: 'everything' } }),
-    { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public', join_grant: 'full', artist_gate: 'strict' },
+    { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' },
     'off-vocabulary values fall back to the default; unknown keys never leak out'
   );
   assert.deepEqual(P.effectiveSettings({ settings: ['not', 'an', 'object'] }),
-    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict' }, 'a non-object settings value reads as defaults');
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' }, 'a non-object settings value reads as defaults');
   // the join door reads back like any other policy key (task 1002324)
   assert.deepEqual(P.effectiveSettings({ settings: { visibility: 'stealth' } }),
-    { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth', join_grant: 'full', artist_gate: 'strict' }, 'a stored door overlays only itself');
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth', join_grant: 'full', artist_gate: 'strict', spend_payer: 'none' }, 'a stored door overlays only itself');
   // what a public join grants is a policy key like any other (task 1002331)
   assert.deepEqual(P.effectiveSettings({ settings: { join_grant: 'view' } }),
-    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'view', artist_gate: 'strict' }, 'the grant overlays only itself');
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'view', artist_gate: 'strict', spend_payer: 'none' }, 'the grant overlays only itself');
 });
 
 t('SETTINGS_VOCAB / DEFAULT_SETTINGS: every default is on its own vocabulary (lockstep guard)', () => {

package/modules/ui-design/kit/serve.js

@@ -189,6 +189,7 @@ const STUB_VOCAB = {
   visibility: ['public', 'private', 'stealth'],
   join_grant: ['view', 'apply', 'full'],
   artist_gate: ['off', 'advisory', 'strict'],
+  spend_payer: ['none', 'project', 'builder'],
   planet_template: null,   // the template set is long; shape is checked, not membership
   planet_accent: ['sea', 'terracotta', 'gold-soft', 'sun-lit', 'accent'],
   card_backdrop: ['nebula', 'dust', 'deepfield', 'chrome'],

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.732",
+  "version": "1.19.734",
   "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/scripts/gds/bump-version.js

@@ -138,11 +138,20 @@ function isReleaseCommit(subject) {
 // exactly the distinction the constant was written to make.
 //
 // BOTH failure directions are safe, which is what makes this acceptable on a
-// release-critical lane:
-//   • commit written, publish then failed  → version looks taken, next run bumps
-//     past it. A gap in the version sequence; harmless.
-//   • published, commit push then failed   → version looks free, the publish
-//     retries and npm refuses with EPUBLISHCONFLICT. Loud, and nothing wrong ships.
+// release-critical lane — but only since task 1003914 reordered publish.yml so
+// the bump commit is PUSHED AFTER a successful publish, not before it:
+//   • pack or publish failed  → the bump commit was never pushed (it only ever
+//     existed on the discarded runner), so no version looks taken and the next
+//     run recomputes and retries the SAME version. No gap, nothing burned.
+//   • published, push then failed → version looks free, so the next run bumps to
+//     it and npm refuses the duplicate. publish.yml treats that refusal as
+//     success and falls through to the record step, which commits the release
+//     line main was missing. Self-healing, and nothing wrong ships.
+//
+// Before that reorder the first case was the lossy one: the push landed first,
+// so a failed publish left main declaring a version the registry never had, the
+// cascade terminator no-opped every following run, and only a fresh work merge
+// moved past it. That is how 1.19.716-723 were minted and lost (2026-09-13).
 function laneReleasedVersions(subjects = []) {
   const out = new Set();
   for (const subject of subjects) {

package/scripts/gds/exec-path-guard.js

@@ -91,7 +91,7 @@ const EXEMPTIONS = [
        + 're-opens for review.',
   },
   {
-    at: 'src/module-loader/loader.js:190',
+    at: 'src/module-loader/loader.js:196',
     why: 'The plugin loader, and the second site the audit named (B50 "motivating sites"). It '
        + 'require()s a discovered module\'s route file, so the specifier is a runtime path BY '
        + 'DESIGN — a plugin system whose module paths are compile-time constants is not a plugin '
@@ -103,8 +103,8 @@ const EXEMPTIONS = [
        + 'absorbed into this check.',
   },
   {
-    at: 'src/module-loader/loader.js:293',
-    why: 'The poller twin of the route require at :190 — same DEFAULT_ROOTS bound, same plugin-by-'
+    at: 'src/module-loader/loader.js:299',
+    why: 'The poller twin of the route require at :196 — same DEFAULT_ROOTS bound, same plugin-by-'
        + 'design rationale, same ADR 0107 / task 1003400 follow-on. Listed on its own line so a '
        + 'change to either call re-opens only that one.',
   },

package/src/branding.js

@@ -77,6 +77,12 @@ const ENV_OVERRIDES = [
   // that has been strict since it stood up.
   ['ARTIST_GATE', ['project', 'artistGate']],
   ['ARTIST_GATE_SINCE', ['project', 'artistGateSince']],
+  // Who pays when a module spends money for whoever called it (task 1003884) —
+  // none | project | builder. src/modules.js reads it through this pack at config
+  // load and REFUSES to enable a module that declares metered spend while the join
+  // door is `open` and this is `none`. Like its neighbours it is memoized for the
+  // process, which is why the platform restarts the instance to apply a change.
+  ['SPEND_PAYER', ['project', 'spendPayer']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
@@ -265,6 +271,13 @@ function clientBranding(b = branding()) {
       // DEFAULT, which for this one key is 'strict' rather than today's behaviour
       // — the owner's ruling, ADR 0241 §4.
       artistGate: b.project?.artistGate || 'strict',
+      // Who pays for metered module spend (task 1003884). Published for the same
+      // read-back reason as its neighbours — and for one of its own: this is the
+      // key that can REFUSE a module, so an owner looking at a module that will
+      // not turn on needs the instance's own answer to "what did it restart
+      // with?", not the platform's record of what they saved. The fallback is the
+      // platform default, which for this key IS today's behaviour.
+      spendPayer: b.project?.spendPayer || 'none',
     },
   };
 }

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.732'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.734'; // 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/src/module-loader/loader.js

@@ -128,6 +128,12 @@ function discoveredRegistry(opts) {
       _dir: dir,
       _provides: manifest.provides || [],
       _consumes: manifest.consumes || [],
+      // The module's own declaration that it METERS money on a caller's behalf
+      // (task 1003884). Projected here because src/modules.js refuses to enable
+      // such a module where anyone can sign up and nobody is on the hook — and a
+      // kernel file may not name a module key (fitness Check 10), so the
+      // declaration has to travel WITH the manifest rather than be looked up.
+      _spend: manifest.spend || {},
     };
   }
   return out;

package/src/module-loader/manifest-schema.js

@@ -39,6 +39,12 @@
 //                                       //   the APEX ROOT — never both (ADR 0218).
 //       "migrations":  true             //   true => modules/<key>/migrations/ exists (or an array of names)
 //     },
+//     "spend": {                        // OPTIONAL. This module METERS money on a caller's behalf
+//       "requiresPayer": true           //   (task 1003884) — its surfaces can spend real money for
+//     },                                //   whoever calls them, so the core must know WHO PAYS before
+//                                       //   it may be enabled where anyone can sign up. src/modules.js
+//                                       //   refuses the enablement when the join door is `open` and no
+//                                       //   payer is configured.
 //     "provides":      ["reward"],      // OPTIONAL. seam PORTS this module registers a provider for.
 //     "consumes":      ["grade"],       // OPTIONAL. seam ports this module resolves (required capabilities).
 //     "prerequisites": { "modules": ["economy"] },  // OPTIONAL. other modules that must be enabled.
@@ -77,6 +83,16 @@ const ATTRIBUTION_KEYS = ['author', 'origin', 'license', 'maintainer'];
 //                    optionally a `removeAfter` core version.
 //   orphaned         nobody owns it. Still needs a `note`/`successor` so the
 //                    next reader knows the situation, not just the label.
+// The `spend` block (task 1003884). A module declaring `requiresPayer: true` is
+// saying its surfaces can spend real money on behalf of whoever calls them — so
+// the core refuses to ENABLE it on an instance whose join door is `open` with no
+// configured payer (src/modules.js). Closed key set for the same reason
+// `contributes` and `maintenance` have one: a typo'd "requirespayer" would
+// silently declare NO spend, and that is the direction that costs money.
+// Deliberately NOT exported: the validator and its own error message are the only
+// readers, and an export nothing imports is dead weight the knip ratchet counts.
+const SPEND_KEYS = ['requiresPayer'];
+
 const MAINTENANCE_STATUSES = ['core-maintained', 'maintained', 'deprecated', 'orphaned'];
 const MAINTENANCE_KEYS = ['status', 'since', 'removeAfter', 'successor', 'note'];
 // Statuses that describe a module on its way out — these owe a deprecation path.
@@ -190,6 +206,20 @@ function validateManifest(obj) {
     }
   }
 
+  // --- optional spend declaration (task 1003884) ---
+  if ('spend' in obj) {
+    const sp = obj.spend;
+    if (!isObj(sp)) E('spend: must be an object (e.g. { "requiresPayer": true })');
+    else {
+      for (const k of Object.keys(sp)) {
+        if (!SPEND_KEYS.includes(k)) E(`spend.${k}: unknown key (allowed: ${SPEND_KEYS.join(', ')})`);
+      }
+      if ('requiresPayer' in sp && typeof sp.requiresPayer !== 'boolean') {
+        E('spend.requiresPayer: must be a boolean when present');
+      }
+    }
+  }
+
   // --- optional seam declarations ---
   if ('provides' in obj && !isStrArray(obj.provides)) E('provides: must be an array of non-empty strings (port names)');
   if ('consumes' in obj && !isStrArray(obj.consumes)) E('consumes: must be an array of non-empty strings (port names)');

package/src/modules.js

@@ -118,10 +118,75 @@ function coerceBool(v) {
   return undefined;
 }
 
+// WHO PAYS for metered module spend on this instance (task 1003884). Two
+// answers are a payer and the absence of one is not: `project` puts the bill on
+// whoever runs the instance, `builder` on the caller who spent it. Anything else
+// — unset, empty, a typo, a value from a newer core — is NO payer, which is the
+// reading that costs nobody money by accident.
+const PAYERS = Object.freeze(['project', 'builder']);
+
+// Does this registry entry declare that its surfaces spend real money on behalf
+// of whoever calls them? The declaration lives in the module's own module.json
+// (`"spend": { "requiresPayer": true }`) and rides through the loader as `_spend`,
+// because fitness Check 10 forbids the kernel from naming a module key — the
+// guard below has to be true of any module that says this about itself, not of
+// one the resolver has heard of.
+const metersSpend = (entry) => !!(entry && entry._spend && entry._spend.requiresPayer === true);
+
+// The spend guard's own posture. `joinDoorOpen` is "any GitHub account becomes a
+// builder seconds after signing up" — the composed join door, not the
+// `joinability` knob alone (src/bongos/project-door.js).
+const NO_SPEND_RISK = Object.freeze({ joinDoorOpen: false, payer: null });
+
+// WHICH enabled modules must be REFUSED, and why this is a config-load decision.
+//
+// A module that meters spend for its callers is safe in exactly two situations:
+// the people who can call it were let in deliberately (the door is not open), or
+// somebody is on the hook for the bill (a payer is configured, and the module's
+// own per-payer ceiling bounds it). With an OPEN door and NO payer, an account
+// created seconds ago can spend the instance's money with nobody to bill and no
+// cap to stop it — so the enablement itself is refused.
+//
+// AT CONFIG LOAD, NOT AT FIRST CALL. A per-request check would let the module
+// mount, advertise its routes in the manifest, run its migrations and appear
+// enabled everywhere the UI reads `modules.enabled` — and then refuse one caller
+// at a time, which is a broken feature rather than a closed door. Refusing the
+// enablement means the surface never exists.
+//
+// PURE, and exported for direct unit testing: the fail-closed reading of an
+// UNKNOWN posture belongs to loadModules, which is where "unknown" can arise.
+function spendRefusals(resolved, registry, { joinDoorOpen = false, payer = null } = {}) {
+  if (!joinDoorOpen) return [];
+  if (PAYERS.includes(payer)) return [];
+  return Object.keys(resolved).filter((k) => resolved[k] === true && metersSpend(registry[k]));
+}
+
+// The refusal is LOUD. A module silently resolving to off is how an operator
+// spends an afternoon wondering why their routes 404 — and this one is refusing
+// something they explicitly asked for, so it has to say what to do about it.
+// `log` is injectable for the same reason instance-config's legacy-env warning
+// injects it: a test asserts the warning fired, not only that the value resolved.
+function warnSpendRefusal(key, envPrefix, log = console) {
+  log.warn(
+    `[bongos] module "${key}" is enabled in config but was REFUSED: it spends money on behalf of `
+    + `whoever calls it, this project's join door is \`open\` (anyone may sign up), and no payer is `
+    + `configured — so a stranger's spend would have nobody to bill. Set ${envPrefix}_SPEND_PAYER to `
+    + `${PAYERS.join(' or ')} (the platform pushes it from the project's \`spend_payer\` setting), or `
+    + `close the join door. The module stays OFF until then.`,
+  );
+}
+
 // Pure resolver — all inputs injected, so tests drive it with zero I/O.
 // Returns a frozen { <moduleKey>: boolean } covering EVERY registry key, plus a
 // non-enumerable resolution that throws on an unknown module key (typo guard).
-function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = FALLBACK_ENV_PREFIX, registry = MODULE_REGISTRY } = {}) {
+function resolveModules({
+  neutral = {}, instance = {}, env = {}, envPrefix = FALLBACK_ENV_PREFIX, registry = MODULE_REGISTRY,
+  // The spend guard's inputs (task 1003884). Defaulted to "no risk" so every
+  // caller that does not know about spend resolves exactly as before; loadModules
+  // is the one that reads the real posture, and the one that fails closed when it
+  // cannot.
+  spendGuard = NO_SPEND_RISK, warn = warnSpendRefusal,
+} = {}) {
   // The known-key set + defaults come from the passed registry: callers inject
   // the built-in MODULE_REGISTRY (the default, what the pure unit tests use) or
   // the effective built-in+discovered registry (what loadModules passes). This
@@ -175,6 +240,14 @@ function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = FAL
     const v = key in merged ? coerceBool(merged[key]) : undefined;
     resolved[key] = v === undefined ? registry[key].default : v;
   }
+  // THE SPEND GUARD, applied LAST — after config, after env, after the default.
+  // It is deliberately not another precedence level: a refusal that env could
+  // outrank would be a suggestion, and the whole point is that the one knob an
+  // untrusted-but-cheap deploy would reach for cannot turn it back on.
+  for (const key of spendRefusals(resolved, registry, spendGuard)) {
+    resolved[key] = false;
+    warn(key, envPrefix);
+  }
   return Object.freeze(resolved);
 }
 
@@ -220,9 +293,37 @@ function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.e
   // Reuse the branding env prefix so an instance has ONE prefix, not two.
   let envPrefix = FALLBACK_ENV_PREFIX;
   try { envPrefix = require('./branding').branding().envPrefix || envPrefix; } catch { /* fail-to-default */ }
+  // THE SPEND POSTURE, read once per load (task 1003884): is this project's
+  // composed join door `open`, and has the owner said who pays?
+  //
+  // `effectiveJoinDoor() === 'open'` is LITERALLY the expression openEnrollmentEnabled
+  // is defined as (src/bongos/auth-admission.js), read from the composer rather than
+  // through the gate so this file does not pull in the whole sign-in stack. That
+  // identity is the point: the guard and the gate that actually admits strangers
+  // cannot answer one stranger differently, which is the same argument task 1003579
+  // made when it moved the gate onto the composed door.
+  //
+  // WHAT THE CATCH COVERS, stated precisely rather than generously. A pack that
+  // fails to PARSE never reaches here — effectiveJoinDoor swallows that itself and
+  // resolves the default door, `apply`, which is closed. That is not a fail-open
+  // hole: the real admission gate reads the same broken pack and refuses the same
+  // self-enrolment, so a door this guard reads as closed IS closed. The catch is
+  // for the harder failure — the require itself throwing, in tooling that has no
+  // such file — and THERE the default is the dangerous reading rather than the
+  // convenient one, because the thing being guarded is money leaving the account.
+  // The blast radius of being wrong is one module resolving OFF, and since every
+  // module defaults to off, an instance that never enabled one notices nothing.
+  let spendGuard = { joinDoorOpen: true, payer: null };
+  try {
+    // Both are KERNEL files (fitness Check 12), required lazily for the same
+    // reason branding is just above: require-time must never crash tooling.
+    const { effectiveJoinDoor } = require('./bongos/project-door'); // eslint-disable-line global-require
+    const project = require('./branding').branding().project || {}; // eslint-disable-line global-require
+    spendGuard = { joinDoorOpen: effectiveJoinDoor() === 'open', payer: project.spendPayer || null };
+  } catch { /* unreadable posture — the fail-closed default above stands */ }
   // Resolve against the EFFECTIVE registry (built-in + discovered) so a config
   // flag for a discovered module is honored. No-op until a module exists.
-  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry() });
+  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry(), spendGuard });
 }
 
 // Resolved singleton for app code; lazy so require-time never crashes tooling.
@@ -282,6 +383,10 @@ module.exports = {
   effectiveRegistry,
   knownModules,
   CORE_DISCIPLINES,
+  PAYERS,
+  metersSpend,
+  spendRefusals,
+  warnSpendRefusal,
   resolveModules,
   loadModules,
   modules,