@bongos/core 1.19.733 → 1.19.734

package/modules/agents/lib/spend-ceiling.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// modules/agents/lib/spend-ceiling.js — the per-payer MONTHLY SPEND CEILING
+// (task 1003884).
+//
+// WHY THIS IS NOT fire-budget.js, and must never become it. That file is a
+// sliding-window ceiling on how OFTEN a builder may fire, and its own header says
+// what it is not: "A CEILING, NOT A BUDGET. This bounds the blast radius of a
+// loop; it does not decide what agents may cost... Do not grow this into a budget
+// — a ceiling that silently became the accounting would be a second, wrong answer
+// to 'what did agents cost'." This file is the other half it deferred to: it reads
+// the REAL accounting, `agents_runs.cost_usd`, which the grade port bills through
+// the shared LLM cost cache, and refuses a fire when the payer has spent their
+// month.
+//
+// The two bound different things and neither substitutes for the other:
+//
+//   fire-budget   10 fires/hour/BUILDER    bounds a runaway loop, in real time
+//   spend-ceiling $N/month/PAYER           bounds the BILL, off the real ledger
+//
+// A rate ceiling cannot bound a bill (ten fires an hour is ~$650/month/builder),
+// and a spend ceiling cannot bound a loop (it reads spend that has already landed).
+// Both run, in that order, on every fire.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// IT FAILS CLOSED, AND THAT IS THE WHOLE POINT.
+//
+// The prior art is task 1001393, which was filed because the autonomy spend-brake
+// was structurally BLIND: gatherSignals() read month-to-date spend from a database
+// that was unreachable from where the spender ran, so the precheck FAILED OPEN and
+// the brake never tripped once. A spend guard that answers "I don't know" with
+// "go ahead" is not a guard. So every one of these refuses:
+//
+//   • no cap configured, or a cap that is not a positive finite number
+//     — an unbounded ceiling is the defect above, wearing a cap's name;
+//   • no payer to bill — an unattributable spend is what the ledger exists to
+//     prevent, the same fail-closed reading fire-budget gives an unidentified
+//     caller;
+//   • the ledger read THREW — the exact failure 1001393 named. "The database is
+//     unreachable" is the moment a ceiling matters most, not least;
+//   • the payer has spent at or past the cap.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// THE KNOWN OVERSHOOT, stated rather than hidden. A fire is checked BEFORE it
+// runs and its cost lands AFTER it finishes (a pending run carries cost_usd NULL),
+// so fires already in flight are invisible to this read. The overshoot is
+// therefore bounded by concurrent-fires × ~$0.90 — and what bounds the concurrent
+// count is fire-budget. That is the second reason both exist: each one's blind
+// spot is the other's window.
+//
+// Requires nothing (ADR 0083): the pool is passed in, the clock is injected, and
+// the cap comes from env — so the whole file is testable without a database.
+
+// The default is deliberately SMALL. A default cap is the number that applies to
+// an instance whose owner never thought about this, and for them the right answer
+// is "enough to try it, not enough to hurt". At the historian exemplar's ~$0.90 a
+// fire that is roughly 27 fires a month. An instance that means to spend more says
+// so with one env var; an instance that meant to spend nothing was never going to
+// be saved by a generous default.
+const DEFAULT_CAP_USD = 25;
+
+// Calendar month, UTC. It matches the window agents_001's spend index was built
+// for ("What did agents cost this month?") and the $/month cap fire-budget's
+// header defers to — and a calendar month is the unit a bill arrives in, which is
+// the unit an owner reasons about.
+function monthStartUtc(at) {
+  const d = new Date(at);
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
+}
+
+function envNumber(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+// WHO PAYS for one fire, given the project's setting and who asked. PURE.
+//
+// Two settings map to a payer directly; `none` — and anything unset, misspelled,
+// or from a newer core — attributes to the PROJECT, because that is who the money
+// actually came from. `none` is not a third kind of payer, it is the owner not
+// having said, and its real consequence lands at config load: src/modules.js
+// refuses to enable a metered module on an OPEN-door instance whose owner has not
+// said. On a closed-door instance the module keeps working and the project's own
+// ceiling bounds it, which is today's behaviour made explicit rather than changed.
+//
+// AN EVENT FIRE HAS NO CALLER, so `builder` cannot apply to one: nobody asked for
+// it and there is nobody to bill. It falls to the project, which is the only
+// honest answer — and never to "no payer", which would make an event fire the one
+// unbounded path through this file.
+function payerFor(spendPayer, requestedByBuilderId) {
+  if (spendPayer === 'builder' && requestedByBuilderId !== null && requestedByBuilderId !== undefined) {
+    return { payer_kind: 'builder', payer_builder_id: requestedByBuilderId };
+  }
+  return { payer_kind: 'project', payer_builder_id: null };
+}
+
+function createSpendCeiling({
+  capUsd = envNumber('BONGOS_AGENTS_SPEND_CAP_USD', DEFAULT_CAP_USD),
+  now = () => Date.now(),
+} = {}) {
+  return {
+    capUsd,
+
+    /**
+     * May this payer spend right now?
+     *
+     * Unlike fire-budget.check this records NOTHING: the ledger row the spawn
+     * writes is the record, and a ceiling that also kept its own tally would be
+     * the second, disagreeing answer this module is careful not to have.
+     *
+     * @returns {{ok: boolean, spentUsd: number|null, capUsd: number, remainingUsd: number, reason: string|null}}
+     */
+    async check(pool, payer) {
+      const cap = Number(capUsd);
+      const deny = (reason) => ({ ok: false, spentUsd: null, capUsd: cap, remainingUsd: 0, reason });
+
+      if (!Number.isFinite(cap) || cap <= 0) return deny('no_spend_cap_configured');
+      const kind = payer && payer.payer_kind;
+      if (kind !== 'project' && kind !== 'builder') return deny('no_payer');
+      const builderId = payer.payer_builder_id ?? null;
+      if (kind === 'builder' && builderId === null) return deny('no_payer');
+      if (!pool || typeof pool.query !== 'function') return deny('ledger_unreadable');
+
+      const since = monthStartUtc(now());
+      let spent;
+      try {
+        // Summed BY PAYER, so a builder-paid instance gives each builder their own
+        // month and a project-paid one sums the instance. Rows written before
+        // agents_002 carry no payer_kind and match neither, which is the
+        // conservative direction: nobody is charged for spend that was not
+        // attributed to them.
+        const { rows } = await pool.query(
+          `SELECT COALESCE(SUM(cost_usd), 0) AS spent
+             FROM agents_runs
+            WHERE cost_usd IS NOT NULL
+              AND created_at >= $1
+              AND payer_kind = $2
+              AND payer_builder_id IS NOT DISTINCT FROM $3`,
+          [since, kind, builderId],
+        );
+        const raw = rows && rows[0] ? rows[0].spent : undefined;
+        // NOT `Number(raw)` alone. Number(null) is 0, so a sum that came back as
+        // SQL NULL — a shape COALESCE should make impossible, and would therefore
+        // only appear if this query or that table changed under us — would read
+        // as "this payer has spent nothing" and admit the fire. That is the
+        // fail-OPEN direction wearing a plausible number, which is the whole
+        // failure mode task 1001393 was filed about, so an absent value is
+        // rejected BEFORE it can be coerced into a permissive one.
+        spent = (raw === null || raw === undefined) ? Number.NaN : Number(raw);
+      } catch (_) {
+        // THE 1001393 CASE. An unreadable ledger is the one this file exists for.
+        return deny('ledger_unreadable');
+      }
+      // A sum that is not a number is the same "I don't know" as a throw, and gets
+      // the same answer. NUMERIC comes back as a string from pg, so this catches a
+      // genuinely unparseable value, not the ordinary one.
+      if (!Number.isFinite(spent) || spent < 0) return deny('ledger_unreadable');
+
+      const remaining = cap - spent;
+      if (remaining <= 0) {
+        return { ok: false, spentUsd: spent, capUsd: cap, remainingUsd: 0, reason: 'spend_cap_reached' };
+      }
+      return { ok: true, spentUsd: spent, capUsd: cap, remainingUsd: remaining, reason: null };
+    },
+  };
+}
+
+module.exports = { createSpendCeiling, payerFor, monthStartUtc, DEFAULT_CAP_USD };

package/modules/agents/migrations/agents_002_payer.sql

@@ -0,0 +1,87 @@
+-- agents_002_payer.sql — WHO PAYS for a fire (task 1003884).
+--
+-- agents_001 recorded what a fire COST (`cost_usd`, billed through the shared LLM
+-- cost cache) and who ASKED for it (`requested_by_builder_id`). It did not record
+-- who is on the HOOK for it, and those are not the same question: with
+-- `spend_payer: project` the instance pays for a fire a stranger requested, and
+-- with `spend_payer: builder` the requester does. Without the answer stored, a
+-- per-payer ceiling has nothing to sum and a change to the setting would silently
+-- re-interpret every historical row.
+--
+-- WHY IT IS STORED AND NOT DERIVED. `payer_kind` is derivable TODAY from the
+-- project's setting plus `requested_by_builder_id` — and that is exactly the trap.
+-- The setting is a live knob an owner may flip; deriving would make last month's
+-- bill change when they do, and a ledger whose past moves is not a ledger. The
+-- run records the answer that was true when it fired, the same reason `model`
+-- stores the concrete model id rather than the tier that resolved it.
+--
+-- THE VOCABULARY IS TWO WORDS, AND 'none' IS NOT ONE OF THEM. The project setting
+-- has a third value (`none` — the owner has never said), but a RUN always has a
+-- real payer: `none` attributes to the project, because that is who the money
+-- actually came from. `none` does its work at config load instead, where
+-- src/modules.js refuses to ENABLE a module that meters spend on an instance whose
+-- join door is `open` and whose owner has not said who pays.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5). Idempotent: safe to re-run.
+
+BEGIN;
+
+-- 'project' (whoever runs the instance) | 'builder' (the caller who spent it).
+ALTER TABLE agents_runs ADD COLUMN IF NOT EXISTS payer_kind text;
+-- WHICH builder, when the payer is one. ON DELETE SET NULL matches
+-- requested_by_builder_id: deleting a person must not erase what the instance
+-- spent, and `payer_kind` survives to say the bill had an owner.
+ALTER TABLE agents_runs ADD COLUMN IF NOT EXISTS payer_builder_id bigint
+  REFERENCES builders(id) ON DELETE SET NULL;
+
+-- Idempotent constraint adds: ADD CONSTRAINT has no IF NOT EXISTS, so each is
+-- guarded by its own catalog lookup rather than by a re-runnable DDL form.
+DO $$
+BEGIN
+  -- The closed vocabulary, for the same fail-closed reason every other enum in
+  -- agents_001 is text + CHECK: an unwired payer name is refused, never stored.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_payer_kind_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_payer_kind_chk
+      CHECK (payer_kind IS NULL OR payer_kind IN ('project', 'builder'));
+  END IF;
+
+  -- A builder payer must NAME the builder; a project payer must name none. Either
+  -- half missing would leave a row that says it is attributed while being
+  -- unsummable — the shape a per-payer ceiling silently reads as zero.
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_payer_ref_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_payer_ref_chk
+      CHECK (
+        payer_kind IS NULL
+        OR (payer_kind = 'builder' AND payer_builder_id IS NOT NULL)
+        OR (payer_kind = 'project' AND payer_builder_id IS NULL)
+      );
+  END IF;
+
+  -- THE INVARIANT THE TASK ASKS FOR: a run that cost money says who pays. A
+  -- no-go costs nothing and needs no payer (agents_001 already forbids it a
+  -- cost), and a pending run has no cost yet.
+  --
+  -- NOT VALID, deliberately. The constraint binds every INSERT and UPDATE from
+  -- here on, but does not scan rows written before this column existed — a
+  -- self-hosted instance that already ran agents has history that predates the
+  -- concept, and failing its migration to punish it for that would be the wrong
+  -- trade. Those rows stay honestly un-attributed; the ceiling sums by payer and
+  -- so counts none of them, which is the conservative direction (it never credits
+  -- a payer with spend that was someone else's).
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agents_runs_cost_needs_payer_chk') THEN
+    ALTER TABLE agents_runs ADD CONSTRAINT agents_runs_cost_needs_payer_chk
+      CHECK (cost_usd IS NULL OR cost_usd = 0 OR payer_kind IS NOT NULL) NOT VALID;
+  END IF;
+END $$;
+
+-- "What has this payer spent this month?" — the ceiling's only read, and it is on
+-- the invoke hot path. Partial on cost_usd for the same reason
+-- agents_runs_spend_idx is: a row that cost nothing contributes nothing to a
+-- spend sum and would only dilute the scan.
+CREATE INDEX IF NOT EXISTS agents_runs_payer_spend_idx
+  ON agents_runs (payer_kind, payer_builder_id, created_at DESC)
+  WHERE cost_usd IS NOT NULL;
+
+COMMIT;

package/modules/agents/module.json

@@ -1,11 +1,12 @@
 {
   "key": "agents",
   "title": "Agents (declarative agent registry)",
-  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083.",
+  "description": "Declarative agent definitions (.claude/agents/*.md) reconciled at deploy into a DB-backed registry (agents_definitions) plus a per-fire ledger (agents_runs) — BONGOS-V1 goal 1000038, Phase 1. Files-are-source: agents-sync upserts file-sourced definitions and never clobbers an instance-authored db row, and stamps author_rank from the author's LIVE DB rank because a committed file cannot grant authority (ADR 0016). Spawns consume the EXISTING `grade` port (runSubagentCached), which is fixed read-only, so v1 agents are observe-and-report only — no write principals — and every fire bills through the shared LLM cost cache. default:false: shipped is not enabled, and an instance opts in per ADR 0083. spend.requiresPayer (task 1003884): a fire spends real money for whoever called it (~$0.90, and POST /agents/:name/invoke answers 202 without waiting), so the core refuses to ENABLE this module on an instance whose join door is `open` with no payer configured — an account created seconds ago would otherwise spend the instance's money with nobody to bill. Every run then records its payer beside cost_usd (agents_002_payer.sql) and a per-payer monthly ceiling fails closed when it is exhausted OR unreadable (lib/spend-ceiling.js) — distinct from lib/fire-budget.js, which stays a rate ceiling.",
   "coreVersion": "^1.19.0",
   "default": false,
   "maintenance": { "status": "core-maintained" },
   "contributes": { "routes": ["agents"], "migrations": true },
+  "spend": { "requiresPayer": true },
   "provides": [],
   "consumes": ["grade"]
 }

package/modules/agents/routes/agents.js

@@ -81,6 +81,7 @@ const authoring = require('../lib/authoring');
 const { gateFor } = require('../lib/gate');
 const { createAnswerHold } = require('../lib/answer-hold');
 const { createFireBudget } = require('../lib/fire-budget');
+const { createSpendCeiling, payerFor } = require('../lib/spend-ceiling');
 const { spawnAgent } = require('../spawn');
 
 const log = api.logger('agents');
@@ -90,6 +91,28 @@ const log = api.logger('agents');
 // per-router for the opposite reason — it is a delivery buffer, and a split one
 // only means an answer is collected where it was produced.
 const fireBudget = createFireBudget();
+// ONE INSTANCE, module-level, for the reason fire-budget's header gives about two
+// call sites each building their own: two ceilings look identical in review and
+// are not one ceiling. This one holds no state — it reads the ledger every time —
+// so the singleton is about the CAP being one number, not about a shared bucket.
+const spendCeiling = createSpendCeiling();
+
+// The project's `spend_payer` policy, read through branding (src/branding.js maps
+// <PREFIX>_SPEND_PAYER onto project.spendPayer). Read per request rather than
+// memoized here because branding already memoizes for the process — a second copy
+// would only add a way for the two to disagree.
+function projectSpendPayer() {
+  try {
+    const pack = api.branding ? api.branding() : null;
+    return (pack && pack.project && pack.project.spendPayer) || null;
+  } catch (_) {
+    // An unreadable pack is NOT an unbounded fire: payerFor treats a null policy
+    // as the project paying, and the ceiling then bounds the project. The
+    // fail-closed reading of an unreadable posture is src/modules.js's job, and it
+    // makes it once, at config load.
+    return null;
+  }
+}
 
 // The columns the serializer needs. Spelled out rather than `SELECT *` so that a
 // column added later (an author's email, a raw credential) cannot reach a
@@ -541,6 +564,42 @@ module.exports = function agentsRoutes() {
       });
     }
     try {
+      // THE SPEND CEILING, after the rate ceiling and before anything is read or
+      // written. The two are deliberately separate refusals with separate codes:
+      // 429 says "too fast, try later", 402 says "this month's money is gone",
+      // and an operator who cannot tell those apart cannot tell a runaway loop
+      // from a budget that is simply too small. See ../lib/spend-ceiling.js.
+      //
+      // It FAILS CLOSED — including when the ledger cannot be read, which is the
+      // exact defect task 1001393 was filed about.
+      //
+      // INSIDE the try, unlike the synchronous rate ceiling above it. This is the
+      // first `await` in the handler, and express 4 does not catch a rejected
+      // async handler — an unhandled rejection is a process-level crash that takes
+      // every other in-flight request with it, which is the same hazard the
+      // detached `done` promise below is careful about. check() is written not to
+      // throw; the try is what makes that a property of the route rather than a
+      // promise the ceiling has to keep forever.
+      const spendPayer = projectSpendPayer();
+      const payer = payerFor(spendPayer, req.builder.id);
+      const room = await spendCeiling.check(api.pool, payer);
+      if (!room.ok) {
+        return res.fail('spend_cap_reached', {
+          status: 402,
+          message: room.reason === 'spend_cap_reached'
+            ? `agent spend for this ${payer.payer_kind} has reached its $${room.capUsd} monthly cap — each fire spends real money`
+            : `agent fires are refused because the spend ceiling could not be established (${room.reason}) — a ceiling that cannot be read must not be assumed`,
+          details: {
+            scope: 'agent-spend',
+            reason: room.reason,
+            payer_kind: payer.payer_kind,
+            cap_usd: room.capUsd,
+            // null whenever the refusal was a failure to READ the ledger, which
+            // is the honest answer: a number here would claim a sum we do not have.
+            spent_usd: room.spentUsd,
+          },
+        });
+      }
       const { rows } = await api.pool.query(
         `SELECT ${COLUMNS}, persona FROM agents_definitions WHERE name = $1`, [name]
       );
@@ -554,7 +613,7 @@ module.exports = function agentsRoutes() {
       // call — the reason it can stay synchronous while the go path cannot.
       if (gate.decision !== 'go') {
         const skipped = await spawnAgent({
-          definition, trigger, gate, requestedByBuilderId: req.builder.id,
+          definition, trigger, gate, requestedByBuilderId: req.builder.id, spendPayer,
         }, {});
         return res.fail('agent_refused', {
           status: 409,
@@ -572,6 +631,7 @@ module.exports = function agentsRoutes() {
         trigger,
         gate,
         requestedByBuilderId: req.builder.id,
+        spendPayer,
       }, {
         // Wrap the port's runner to keep the reply, which spawnAgent does not
         // return — it records what a fire DID, not what it said.
@@ -669,3 +729,4 @@ module.exports.serializeRun = serializeRun;
 // The module-level ceiling, exported so a test can reset it between cases —
 // a singleton otherwise carries one case's spend into the next.
 module.exports.fireBudget = fireBudget;
+module.exports.spendCeiling = spendCeiling;

package/modules/agents/spawn.js

@@ -34,6 +34,7 @@
 // happened, and "the agent didn't run" then has two causes nobody can tell apart.
 
 const api = require('../../src/module-api');
+const { payerFor } = require('./lib/spend-ceiling');
 
 // tier → concrete model id. The mapping is BRANDING, not a constant here: an
 // instance retunes its own tiers, and the DB constraint already limits the
@@ -53,8 +54,20 @@ function resolveModel(tier, brandingModels) {
 
 // The insert shape for one fire, decided BEFORE anything spawns. Pure, so the
 // schema's invariants can be tested without a database.
-function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null } = {}) {
+function plannedRow({
+  definition = {}, trigger = {}, gate = {}, model = null, requestedByBuilderId = null,
+  // The project's `spend_payer` policy as it stands AT THIS FIRE. Passed in rather
+  // than read here so this stays pure, and stamped into the row rather than
+  // derived later so a flip of the setting cannot rewrite what last month cost
+  // (agents_002_payer.sql says why at length).
+  spendPayer = null,
+} = {}) {
   const go = gate.decision === 'go';
+  // WHO PAYS — recorded on EVERY row, including a no-go. A refusal costs nothing
+  // and the schema forbids it a cost, but it is still a fire somebody would have
+  // been billed for, and a ledger that attributes only the expensive half cannot
+  // answer "what would this have cost us".
+  const payer = payerFor(spendPayer, requestedByBuilderId);
   return {
     definition_id: definition.id ?? null,
     agent_name: definition.name || null,
@@ -71,6 +84,11 @@ function plannedRow({ definition = {}, trigger = {}, gate = {}, model = null, re
     // never be re-read through today's tier mapping.
     model: go ? model : null,
     requested_by_builder_id: requestedByBuilderId ?? null,
+    // Distinct from requested_by_builder_id above, and the distinction is the
+    // point: that field is who ASKED, these are who is on the HOOK. They are the
+    // same person only when the project put the bill on its builders.
+    payer_kind: payer.payer_kind,
+    payer_builder_id: payer.payer_builder_id,
   };
 }
 
@@ -135,14 +153,14 @@ async function finishRun(pool, id, patch) {
 // agent's bad day.
 async function spawnAgent({
   definition, input = null, trigger = {}, gate = { decision: 'go' },
-  requestedByBuilderId = null, cache = null,
+  requestedByBuilderId = null, cache = null, spendPayer = null,
 } = {}, deps = {}) {
   const pool = deps.pool || api.pool;
   const now = deps.now || (() => Date.now());
   const brandingModels = deps.brandingModels || (api.branding && api.branding().models) || {};
   const model = resolveModel(definition && definition.model_tier, brandingModels);
 
-  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId });
+  const row = plannedRow({ definition, trigger, gate, model, requestedByBuilderId, spendPayer });
   let runId = null;
   try {
     runId = await insertRun(pool, row);

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.733",
+  "version": "1.19.734",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.733",
+      "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.733",
+  "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.733'; // 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');