@bongos/core 1.19.582 → 1.19.583

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.582",
-  "core_contract": "1.19.582",
-  "source_commit": "e08eecbc1ea83f6a28a974941d34596df6e8679c",
+  "core_version": "1.19.583",
+  "core_contract": "1.19.583",
+  "source_commit": "fb22777c0f055003ba879a32ce83f133c3bcf404",
   "source_ref": "HEAD",
-  "built_at": "2026-09-07T20:40:15.927Z",
+  "built_at": "2026-09-07T21:24:48.534Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 453,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2053,
+    "functional_verbatim": 2055,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2530,
-  "tree_sha256": "29108b672d011aaae1b40a09256ee01d2920dea6dc75314b191b4c4f2bf3d59c",
+  "file_count": 2532,
+  "tree_sha256": "bd94f04eed1f7a4c89844c53856157cdb9a14e2281876e6025d511ca9c446b7a",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1832,7 +1832,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "c3a329219460b2508d51009ff8f77bdc4733f3a17ad2776553dc7bce483555c4"
+      "sha256": "75ba055326939ec1c827d01cdf088f564e94f372d9906759483fd1bad2328375"
     },
     {
       "path": "docs/architecture.md",
@@ -2707,7 +2707,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "adf481b84f3a8f77597056fad9643d39362e5333ac86b0c1ca7b122456dfd2fa"
+      "sha256": "a73cb53670674b790e02461ef7c11e001a5ed0ebb38498ffa222034263058932"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6279,6 +6279,11 @@
       "mode": "0000644",
       "sha256": "31f14cbf3d649c25f1f17c508ae19be2f39d9e1991fde17cdce08cb15837ffa1"
     },
+    {
+      "path": "modules/provisioning/paid-shape-gate.js",
+      "mode": "0000644",
+      "sha256": "a72f2961ba04739648b8622d86a85a75aef613d5d7c50fbb2f43ae8cf2c4adae"
+    },
     {
       "path": "modules/provisioning/pollers/catalog-backfill.js",
       "mode": "0000644",
@@ -6312,7 +6317,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "60c583e1ae977c85575709abf74af7d0dc5147788509f11d1b26cad459d7b4cf"
+      "sha256": "19dcadc78c74d7702a31fcb3d75d4c5fd45d08aab0e32c2a876668ec6dea85ec"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7572,12 +7577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "24d6748a6c6816752b86ef695eb75e27076d682ba1d3639763c6377389fcd17b"
+      "sha256": "b37aec87b322bad5e71296695b690719db6952a401e63afe00c277863e109082"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4dd5996574d3f875f81509651c5af05ff6313b45774b9f65737086658240c927"
+      "sha256": "5ddfb97b2d19da1f5631fd5fcd81102c1fb3188a855b4ea9a2e640447dad2403"
     },
     {
       "path": "public-docs/index.html",
@@ -9287,7 +9292,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "15e5aa2886df30346a374c4b4fa988ff471a73a113a10c13061ce174f1aacfde"
+      "sha256": "4cae7c47e642670fbd78fa75a65b4cee629fbc43df0a9c34a69fc465c434330e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11754,6 +11759,11 @@
       "mode": "0000644",
       "sha256": "97d04ee39cc06b720d4a5b42f3e3cc614f64d9462b27471a1af7598b5e2929be"
     },
+    {
+      "path": "tests/provisioning_paid_shape_gate.mjs",
+      "mode": "0000644",
+      "sha256": "a2c8a1761cf44bd0434766cb9e42c34dbc61d7133218440f046d82da802d8217"
+    },
     {
       "path": "tests/provisioning_recommendations.mjs",
       "mode": "0000644",

package/docs/api/openapi.json

@@ -11520,7 +11520,7 @@
           "provisioning"
         ],
         "summary": "POST /provisioning/instances",
-        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource). ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier?, onboard_mode? (greenfield|adopt) }. onboard_mode is LOAD-BEARING, not a label (task 1002562): the control-plane runner branches its repo scaffold on it. 'adopt' means target_ref is a repo the owner ALREADY has, so the runner must clone + layer onto its history instead of pushing a fresh tree at `main` (which an existing repo rejects as unrelated history). Absent → 'greenfield', the safe default.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "POST /provisioning/instances — request a new instance. rank: any authenticated builder (own resource); a `dedicated` (metered) shape additionally requires provisioning.fleet.manage — see requireAuthorityForMeteredShape above. ENQUEUES a 'provision' intent + records the request; the runner (task P3) does the real standup. Idempotent on slug for the SAME owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409. Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated), domain?, tier?, onboard_mode? (greenfield|adopt) }. onboard_mode is LOAD-BEARING, not a label (task 1002562): the control-plane runner branches its repo scaffold on it. 'adopt' means target_ref is a repo the owner ALREADY has, so the runner must clone + layer onto its history instead of pushing a fresh tree at `main` (which an existing repo rejects as unrelated history). Absent → 'greenfield', the safe default.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "requestBody": {

package/docs/module-api-changelog.md

@@ -1613,5 +1613,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.580 with no explicit bump. run 34158683008. (task 1002620)
   1.19.582 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.581 with no explicit bump. run 34160253741. (task 1002620)
+  1.19.583 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.582 with no explicit bump. run 34162998083. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/paid-shape-gate.js

@@ -0,0 +1,57 @@
+// modules/provisioning/paid-shape-gate.js — who may ask for METERED infrastructure
+// (task 1003682).
+//
+// The create route is open to any authenticated builder, and it must stay that way:
+// standing up a project is the platform's front door, not a privilege. But one of the
+// hosting shapes it accepts is not free. `dedicated` is the only shape whose runner leg
+// allocates a real droplet (`scripts/gds/provision.js` — billed monthly, defaulting to
+// s-2vcpu-4gb when no tier is named); every other shape co-tenants on infrastructure the
+// platform already pays for, which is why `costEstimateUsd` returns 0 for all of them.
+//
+// So the authority question belongs to the SHAPE, not the route. Gating the whole route
+// would make ordinary project creation require a rank — the wrong trade entirely, and the
+// reason this is a middleware over one field rather than a floor on the endpoint.
+//
+// The atom is `provisioning.fleet.manage` (floor: metic), deliberately the same one that
+// already guards the fleet cost-ledger and force-teardown. Spending on the fleet and
+// managing the fleet are one authority, and before this the route that SPENDS money was
+// less gated than the route that stops it.
+//
+// Split into its own file rather than inlined beside the route for two reasons, both
+// mechanical: `routes/provisioning.js` sits at its 1500-line fitness ratchet (the same
+// pressure that produced `callback-page.js` under task 1003570), and a bare `req.body`
+// read placed between two route declarations is attributed by the ADR 0118 body-validation
+// scanner to the PRECEDING route, which turns a correct gate into a false "unvalidated
+// write route" failure on an unrelated endpoint.
+'use strict';
+
+// The shapes that cost money. Kept as a set of one rather than a bare `=== 'dedicated'`
+// so a second metered shape is a one-line change here instead of a hunt through gates;
+// `tests/provisioning_paid_shape_gate.mjs` pins HOSTING_SHAPES so adding one without
+// revisiting this file fails loudly.
+const METERED_SHAPES = Object.freeze(new Set(['dedicated']));
+
+// isMeteredShape — does this hosting shape allocate infrastructure someone is billed for?
+// Matches the exact wire value: the route's own validator refuses anything not in
+// HOSTING_SHAPES, so a case or whitespace variant is rejected as a bad shape rather than
+// admitted here as a cheap one.
+function isMeteredShape(shape) {
+  return METERED_SHAPES.has(shape);
+}
+
+// requireAuthorityForMeteredShape — the create route's paid-shape gate. Mount it AFTER
+// requireBuilder and BEFORE the handler, so a refusal leaves no row behind for the runner
+// to drain later. `requirePermission` is injected (rather than required here) so the gate
+// is exercisable without standing up the auth stack.
+function requireAuthorityForMeteredShape(requirePermission) {
+  const gate = requirePermission('provisioning.fleet.manage');
+  return function meteredShapeGate(req, res, next) {
+    if (!isMeteredShape(req.body && req.body.hosting_shape)) return next();
+    return gate(req, res, next);
+  };
+}
+
+// Only the gate is exported. METERED_SHAPES and isMeteredShape are deliberately private:
+// nothing outside this file needs to ask "is this shape metered" separately from being
+// gated on it, and an export nobody consumes is one more thing to keep true.
+module.exports = { requireAuthorityForMeteredShape };

package/modules/provisioning/routes/provisioning.js

@@ -12,6 +12,9 @@
 //
 //   own-scoped (requireBuilder — the caller's OWN instances):
 //     POST   /provisioning/instances               — request a new instance
+//                                                     (a `dedicated` shape ALSO needs
+//                                                      provisioning.fleet.manage — it is the
+//                                                      only shape that bills; ../paid-shape-gate.js)
 //     GET    /provisioning/instances               — list the caller's instances
 //     GET    /provisioning/instances/:id           — read one of the caller's instances
 //                                                     (also SELF-HEALS its catalog projection,
@@ -45,6 +48,7 @@ const { onboardPlan, stepsForShape } = require('../onboard-plan');
 const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModules, effectiveModules } = require('../starter-bundles');
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
+const { requireAuthorityForMeteredShape } = require('../paid-shape-gate');
 const catalogBridge = require('../catalog-bridge');
 const { callbackPage } = require('./callback-page');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -342,7 +346,9 @@ module.exports = function provisioningRoutes() {
   });
 
   // POST /provisioning/instances — request a new instance. rank: any authenticated
-  // builder (own resource). ENQUEUES a 'provision' intent + records the request;
+  // builder (own resource); a `dedicated` (metered) shape additionally requires
+  // provisioning.fleet.manage — see requireAuthorityForMeteredShape above.
+  // ENQUEUES a 'provision' intent + records the request;
   // the runner (task P3) does the real standup. Idempotent on slug for the SAME
   // owner (re-request returns the existing row); a slug owned by ANOTHER builder → 409.
   // Body: { slug (required), target_ref?, hosting_shape? (co-tenant|dedicated),
@@ -353,7 +359,7 @@ module.exports = function provisioningRoutes() {
   // ALREADY has, so the runner must clone + layer onto its history instead of pushing a
   // fresh tree at `main` (which an existing repo rejects as unrelated history). Absent →
   // 'greenfield', the safe default.
-  router.post('/provisioning/instances', auth.requireBuilder, async (req, res) => {
+  router.post('/provisioning/instances', auth.requireBuilder, requireAuthorityForMeteredShape(auth.requirePermission), async (req, res) => {
     if (validateOrRespond(req, res, {
       slug: { required: true, type: 'string', maxLength: 40 },
       target_ref: { type: 'string', maxLength: 200 },

package/package-lock.json

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

package/package.json

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

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.582'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.583'; // 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/provisioning_paid_shape_gate.mjs

@@ -0,0 +1,172 @@
+// tests/provisioning_paid_shape_gate.mjs
+//
+// The paid-shape gate on POST /provisioning/instances (task 1003682).
+//
+// Before this, the create route's only gate was requireBuilder, and `hosting_shape` was
+// caller-supplied and validated only against the allowed set. `dedicated` is the ONE shape
+// whose runner leg creates a real DigitalOcean droplet (scripts/gds/provision.js — billed
+// monthly, defaulting to s-2vcpu-4gb), so any authenticated builder — a Xenos included —
+// could queue recurring infrastructure spend the owner never approved. The route that
+// SPENDS was less gated than force-teardown, which stops spending and sits behind
+// provisioning.fleet.manage.
+//
+// The fix gates the SHAPE, not the route: every $0 shape (standalone, co-tenant) stays open
+// to any authenticated builder, because ordinary project creation must not require a rank.
+// Only `dedicated` demands provisioning.fleet.manage — deliberately the same atom that
+// already guards the fleet cost-ledger and force-teardown, since spending on the fleet and
+// managing the fleet are one authority.
+//
+// DB-free: the pool is never reached (createInstance is stubbed), auth is faked. No network
+// beyond a loopback listener.
+//
+// Run:  node tests/provisioning_paid_shape_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ── stubs: the route's data access + auth ────────────────────────────────────────
+let lastCreateArgs = null;
+provisioning.createInstance = async (_db, args) => {
+  lastCreateArgs = args;
+  return { instance: { id: 42, owner_builder_id: 7, slug: args.slug, hosting_shape: args.hostingShape }, created: true };
+};
+provisioning.enqueueIntent = async () => ({ intent: { id: 1, state: 'pending' }, created: true });
+provisioning.recordEvent = async () => {};
+provisioning.getInstanceBySlug = async () => null;
+
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+
+// The permission gate, faked at the same seam the real one uses. `held` is flipped per
+// case below so one mounted app covers both the denied and the admitted builder.
+let held = [];
+api.requirePermission = (...perms) => async (req, res, next) => {
+  if (perms.every((p) => held.includes(p))) return next();
+  return res.fail('permission_forbidden', {
+    status: 403,
+    message: `missing permission: ${perms.filter((p) => !held.includes(p)).join(', ')}`,
+    details: { required: perms, held: perms.filter((p) => held.includes(p)) },
+  });
+};
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(details || (typeof opts === 'object' ? opts : {})) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function post(path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+// ── the $0 shapes stay open — this is the half a careless fix would break ─────────
+
+await ta('standalone: a builder with NO fleet permission still creates (the live wizard path)', async () => {
+  held = [];
+  lastCreateArgs = null;
+  const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: 'standalone', no_address: true });
+  assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
+  assert.equal(lastCreateArgs && lastCreateArgs.hostingShape, 'standalone');
+});
+
+await ta('co-tenant (and an absent shape, which defaults to it) stays open with no permission', async () => {
+  for (const body of [
+    { slug: 'demo', hosting_shape: 'co-tenant', no_address: true },
+    { slug: 'demo', no_address: true },
+  ]) {
+    held = [];
+    const res = await post('/provisioning/instances', body);
+    assert.equal(res.status, 201, `expected 201 for ${JSON.stringify(body)}, got ${res.status} ${res.raw}`);
+  }
+});
+
+// ── dedicated is the metered one ──────────────────────────────────────────────────
+
+await ta('dedicated: REFUSED for a builder without provisioning.fleet.manage', async () => {
+  held = [];
+  lastCreateArgs = null;
+  const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: 'dedicated', no_address: true });
+  assert.equal(res.status, 403, `expected 403, got ${res.status} ${res.raw}`);
+  assert.equal(res.body.error.code, 'permission_forbidden');
+  // requirePermission reports the gate's literal list under `details` (the same envelope
+  // requireRank uses), so the denial names the atom a caller has to be granted.
+  assert.deepEqual(res.body.error.details.required, ['provisioning.fleet.manage']);
+  assert.equal(lastCreateArgs, null, 'no row is created when the shape is refused');
+});
+
+await ta('dedicated: ADMITTED for a builder holding provisioning.fleet.manage', async () => {
+  held = ['provisioning.fleet.manage'];
+  lastCreateArgs = null;
+  const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: 'dedicated', no_address: true });
+  assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
+  assert.equal(lastCreateArgs && lastCreateArgs.hostingShape, 'dedicated');
+});
+
+await ta('the gate refuses BEFORE the row exists — a denied dedicated create leaves nothing behind', async () => {
+  // The denial must land ahead of createInstance, not after it: a refused-but-inserted row
+  // would still be drained by the runner, which reads the column, not the HTTP status.
+  held = [];
+  lastCreateArgs = null;
+  await post('/provisioning/instances', { slug: 'spendy', hosting_shape: 'dedicated', tier: 's-4vcpu-8gb' });
+  assert.equal(lastCreateArgs, null);
+});
+
+// ── the gate cannot be walked around ──────────────────────────────────────────────
+
+await ta('a case-variant shape does not slip past the gate INTO a dedicated row', async () => {
+  // The gate matches the exact wire value, and so does the shape validator — so a variant
+  // is refused as a bad shape rather than admitted as a cheap one and stored as dedicated.
+  // The property that matters is not WHICH error comes back, it is that no dedicated row
+  // is ever created without the permission.
+  for (const shape of ['DEDICATED', 'Dedicated', ' dedicated', 'dedicated ']) {
+    held = [];
+    lastCreateArgs = null;
+    const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: shape, no_address: true });
+    assert.ok(res.status === 400 || res.status === 403, `${JSON.stringify(shape)} → expected refusal, got ${res.status} ${res.raw}`);
+    assert.equal(lastCreateArgs, null, `${JSON.stringify(shape)} must not create a row`);
+  }
+});
+
+await ta('HOSTING_SHAPES still carries exactly the three shapes the gate reasons about', () => {
+  // If a fourth, also-metered shape is ever added, this test is the tripwire that says the
+  // gate's single-shape assumption needs revisiting.
+  assert.deepEqual([...provisioning.HOSTING_SHAPES].sort(), ['co-tenant', 'dedicated', 'standalone']);
+});
+
+server.close();
+console.log(`\nprovisioning_paid_shape_gate: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);