@bongos/core 1.19.515 → 1.19.516

package/docs/module-api-changelog.md

@@ -1467,5 +1467,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.513 with no explicit bump. run 33796959752. (task 1002620)
   1.19.515 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.514 with no explicit bump. run 33797825811. (task 1002620)
+  1.19.516 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.515 with no explicit bump. run 33798954769. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/migrations/provisioning_014_module_selection.sql

@@ -0,0 +1,60 @@
+-- provisioning_014_module_selection.sql — where the creation picker's chosen
+-- module set lands (BV1.R20, task 1002339; goal 1000046 criterion
+-- `proj-module-select`).
+--
+-- R19 (task 1002338, ADR 0237) declared the starter bundles and served them, and
+-- closed with "where a chosen selection lands is R20's decision — there is still
+-- no module-selection column on any table". This is that column.
+--
+-- ONE column, jsonb, NULLABLE — and the nullability is the contract, not an
+-- oversight:
+--
+--   NULL   the owner never answered. They skipped the picker, or the request was
+--          filed by an API caller / the CLI that does not ask. The set they get
+--          is resolved at READ time from the type's starter bundle
+--          (starter-bundles.effectiveModules), so skipping yields exactly the
+--          preselect the panel showed — the same declaration on both ends.
+--   '[]'   the owner answered "none of the opt-ins". A real choice, and a
+--          different fact from never having been asked. A NOT NULL DEFAULT '[]'
+--          would have collapsed the two and made a skip unreadable forever.
+--   '[…]'  the keys the owner picked.
+--
+-- This is the `detail` rule from provisioning_013 applied to a list: absent stays
+-- absent, skipped stays skipped, and nothing is ever back-filled with a guess.
+--
+-- WHY NOT `detail` ITSELF. provisioning_013's comment named R19 as a reason the
+-- column was jsonb, but ADR 0237 §2 then ruled the other way: `detail` holds the
+-- INTERVIEW's answers under PROJECT_DETAIL_VOCAB, a closed map of scalar
+-- vocabularies that `normalizeProjectDetail` filters key-by-value. A list of
+-- module keys is not that shape — carrying it there would have meant teaching the
+-- interview's normalizer, its 400-ing route guard and its read projection about a
+-- value type none of them have, to store something the interview deliberately
+-- does not ask (ADR 0237 §2: "the interview does not ask a second time").
+--
+-- WHY NOT `settings`. A setting is a POLICY the running instance obeys — it rides
+-- web.env and queues a `settings-apply` intent plus a restart. A module selection
+-- is a declaration made before the instance exists; there is nothing running to
+-- apply it to.
+--
+-- WHAT THE COLUMN IS AND IS NOT. It is the owner's DECLARATION, held on the
+-- platform row until a catalog row materializes — the same standing `type` and
+-- `description` have (provisioning_007 / _013). It is NOT yet an input to the
+-- control-plane runner: `provisioning_intents` carries no payload, and turning a
+-- stored selection into the child instance's own config/modules.json is a
+-- separate piece of work (see the ADR's Consequences).
+--
+-- A module selection is NEVER a publish precondition — ADR 0182 D4 fixes that bar
+-- at identity alone, and ADR 0237 §6 restates it for bundles.
+--
+-- Additive + provisioning_-namespaced (ADR 0083 §5): ADD COLUMN only, so the
+-- previous code release still runs against this schema. Idempotent: safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances
+  ADD COLUMN IF NOT EXISTS modules jsonb;
+
+COMMENT ON COLUMN provisioning_instances.modules IS
+  'The opt-in modules the owner chose in the creation picker (BV1.R20), as a jsonb array of module keys. NULLABLE and three-valued: NULL = never answered (the picker was skipped, or the caller does not ask) and the set resolves at read time from the declared type''s starter bundle; ''[]'' = the owner chose none of them, which is a real answer; ''["dev-box",…]'' = what they picked. The always-on core is never listed here — it is the floor every project gets (starter-bundles.ALWAYS_ON_CORE), not a choice. Read through starter-bundles.effectiveModules, never raw.';
+
+COMMIT;

package/modules/provisioning/provisioning.js

@@ -12,6 +12,14 @@
 // unit-testable with a fake `{ query }`. The route factory passes the doorway pool.
 'use strict';
 
+// The one require in this file, and it stays inside the module: starter-bundles.js
+// is the pure declaration beside it (ADR 0237 — no I/O, no core import), so the
+// "no core require / fake `{ query }`" property above is untouched. It is here
+// because the module SELECTION a row carries (BV1.R20, task 1002339) is three-
+// valued, and the value it resolves to when nobody answered is the type's starter
+// bundle — so storage and the read projection both have to read that declaration.
+const { normalizeModuleSelection, effectiveModules } = require('./starter-bundles');
+
 // ---------------------------------------------------------------------------
 // Constants (mirror the CHECK constraints in provisioning_001_tables.sql)
 // ---------------------------------------------------------------------------
@@ -352,6 +360,13 @@ function publicInstance(row) {
     // missing" from a plain instance read, without a second endpoint.
     description: row.description || null,
     detail: projectDetail(row),
+    // The creation picker's module set (task 1002339): the always-on core, what
+    // the owner ends up with, and whether that came from their own toggles or
+    // from the type's starter bundle because they never answered. Resolved, not
+    // raw — a caller must never have to re-derive the skipped-means-the-bundle
+    // rule, which is the one way two surfaces would come to name different
+    // modules for the same project.
+    modules: effectiveModules(row),
     // The verification overlay (task 1002696, redesign direction §3): what the
     // heartbeat last OBSERVED, which is NOT what `status` claims. null = never
     // probed — a different claim from last_verified_up=false, and the UI renders
@@ -800,7 +815,7 @@ async function listAllInstances(db, { status } = {}) {
 // re-fetches the existing row and returns { created:false } so the ROUTE can
 // decide (same owner → idempotent re-request; different owner → 409). Never
 // silently reassigns ownership.
-async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type, description, detail }) {
+async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShape, domain, dbName, port, tier, onboardMode, type, description, detail, modules }) {
   const shape = HOSTING_SHAPES.includes(hostingShape) ? hostingShape : 'co-tenant';
   // Unknown/absent → 'greenfield', matching the column default. Falling back to the
   // SAFE mode matters: greenfield refuses to push over existing history (no --force
@@ -815,16 +830,21 @@ async function createInstance(db, { ownerBuilderId, slug, targetRef, hostingShap
   // updateInstanceDetail is the way back.
   const told = normalizeDescription(description);
   const answers = normalizeProjectDetail(detail);
+  // The creation picker's selection (task 1002339). NULL when the owner never
+  // answered — the column is nullable precisely so a skip stays readable as a
+  // skip, and effectiveModules then resolves the type's bundle at read time. An
+  // explicit empty array is a real answer and is stored as one.
+  const picked = normalizeModuleSelection(modules);
   const cost = costEstimateUsd({ hostingShape: shape, tier });
   try {
     const { rows } = await db.query(
       `INSERT INTO provisioning_instances
-         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type, description, detail)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::jsonb)
+         (owner_builder_id, slug, target_ref, hosting_shape, domain, db_name, port, tier, cost_estimate_usd, onboard_mode, type, description, detail, modules)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::jsonb, $14::jsonb)
        RETURNING *`,
       [ownerBuilderId, slug, targetRef ?? null, shape, domain ?? null,
        dbName ?? null, port ?? null, tier ?? null, cost, mode, declaredType,
-       told, JSON.stringify(answers)]
+       told, JSON.stringify(answers), picked === null ? null : JSON.stringify(picked)]
     );
     return { instance: rows[0], created: true };
   } catch (e) {

package/modules/provisioning/routes/provisioning.js

@@ -36,7 +36,7 @@ const auth = api;
 const { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { onboardPlan, stepsForShape } = require('../onboard-plan');
-const { ALWAYS_ON_CORE, allStarterBundles } = require('../starter-bundles');
+const { ALWAYS_ON_CORE, OPTIONAL_MODULES, allStarterBundles, optionalModules } = require('../starter-bundles');
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -115,6 +115,30 @@ function badProjectDetail(detail) {
   return null;
 }
 
+// The creation picker's module selection, validated LOUDLY (BV1.R20, task
+// 1002339) — badProjectDetail's rule applied to a list. The strict body validator
+// checks that `modules` is an array of strings; it cannot check MEMBERSHIP, and
+// normalizeModuleSelection drops an unknown key silently on the way to storage.
+// Silence is the wrong answer at the boundary: an API caller who names a module
+// that does not exist, or one of the always-on / hub-only ones, has made a
+// mistake and would otherwise be told nothing and handed a project without it.
+// Returns null when clean, or a { code, message } to fail with.
+function badModuleSelection(modules) {
+  if (modules === undefined || modules === null) return null;
+  if (!Array.isArray(modules)) {
+    return { code: 'bad_modules', message: 'modules must be an array of module keys.' };
+  }
+  const offered = OPTIONAL_MODULES.map((m) => m.key);
+  for (const key of modules) {
+    if (offered.includes(key)) continue;
+    if (ALWAYS_ON_CORE.includes(key)) {
+      return { code: 'bad_modules', message: `"${key}" is always on for every project — it is not one of the modules to choose.` };
+    }
+    return { code: 'bad_modules', message: `Unknown module "${key}" — the choices are: ${offered.join(', ')}.` };
+  }
+  return null;
+}
+
 // Minimal HTML escaper for the callback landing page (no template engine here).
 function esc(s) {
   return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
@@ -463,10 +487,20 @@ module.exports = function provisioningRoutes() {
       // (ADR 0182 D4), and PATCH …/detail is the way back.
       description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
       detail: { type: 'object' },
+      // The creation picker's chosen module set (BV1.R20, task 1002339) — the
+      // opt-in keys, never the always-on core. ABSENT means the owner skipped
+      // the picker, which is a supported default: the row stores NULL and the
+      // read resolves the declared type's starter bundle, so a skip yields
+      // exactly the set the panel preselected. An explicit [] is the different
+      // answer "none of them". maxItems is a sanity ceiling well above a catalog
+      // that is three modules wide today.
+      modules: { type: 'array', itemsType: 'string', maxItems: 50 },
     })) return;
     const body = req.body || {};
     const detailFault = badProjectDetail(body.detail);
     if (detailFault) return res.fail(detailFault.code, { status: 400, message: detailFault.message });
+    const modulesFault = badModuleSelection(body.modules);
+    if (modulesFault) return res.fail(modulesFault.code, { status: 400, message: modulesFault.message });
     const slug = String(body.slug || '').trim().toLowerCase();
     if (!provisioning.isValidSlug(slug)) {
       return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
@@ -552,6 +586,9 @@ module.exports = function provisioningRoutes() {
         // The optional detail step's answers (task 1002334) — absent means the
         // owner skipped it, which is the supported default, not an error.
         description: body.description, detail: body.detail,
+        // The picker's selection (task 1002339) — absent for the same reason and
+        // with the same standing: skipped, and resolved from the bundle on read.
+        modules: body.modules,
       });
       // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
       if (!created && String(instance.owner_builder_id) !== String(req.builder.id)) {
@@ -615,6 +652,16 @@ module.exports = function provisioningRoutes() {
           hint: `a re-request never changes an existing instance's project detail — PATCH /provisioning/instances/${instance.id}/detail instead`,
         };
       }
+      // And the same for the picker's module set (task 1002339). Like `type` —
+      // and unlike detail — there is no mutation route yet (R23, task 1002342 is
+      // "add modules later"), so the receipt says the answer was kept rather
+      // than naming a way back that does not exist.
+      let modulesIgnored;
+      if (!created && body.modules !== undefined) {
+        modulesIgnored = {
+          hint: "a re-request never changes an existing instance's module selection",
+        };
+      }
       res.status(created ? 201 : 200).json({
         instance: ownerInstance(instance),
         open_intent: intent ? { action: intent.action, state: intent.state } : null,
@@ -624,6 +671,7 @@ module.exports = function provisioningRoutes() {
         ...(noAddressIgnored ? { no_address_ignored: noAddressIgnored } : {}),
         ...(typeIgnored ? { type_ignored: typeIgnored } : {}),
         ...(detailIgnored ? { detail_ignored: detailIgnored } : {}),
+        ...(modulesIgnored ? { modules_ignored: modulesIgnored } : {}),
       });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances', err);
@@ -1280,8 +1328,17 @@ module.exports = function provisioningRoutes() {
   // rank: public — the signed-out hub wizard (/projects?view=new) reads it while
   // choosing a type, exactly like onboard-plan above; no write, no secret, and the
   // module catalog it names is already public at GET /public/modules.
+  //
+  // `optional` joined the payload for R20's picker (task 1002339): the opt-in
+  // catalog with the owner-facing label + one-line summary each row renders. It
+  // lives here rather than at a module-catalog route because the two things a
+  // picker needs — what is preselected and what may be chosen — have to arrive
+  // in ONE read of ONE declaration, or the panel can preselect a key it has no
+  // row for. The alternatives were both worse: `GET /modules` needs a session
+  // (this wizard is read signed-out) and `GET /public/modules` serves booleans,
+  // not copy. Additive — `core` and `bundles` keep their shape.
   router.get('/provisioning/starter-bundles', (req, res) => {
-    res.json({ core: [...ALWAYS_ON_CORE], bundles: allStarterBundles() });
+    res.json({ core: [...ALWAYS_ON_CORE], bundles: allStarterBundles(), optional: optionalModules() });
   });
 
   // GET /provisioning/recommendations?type=<project type>&team_shape=<interview answer>

package/modules/provisioning/starter-bundles.js

@@ -70,6 +70,42 @@ const ALWAYS_ON_CORE = Object.freeze([
 // refuse them by construction rather than by anyone remembering.
 const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning']);
 
+// The OPT-IN catalog as the creation picker renders it (BV1.R20, task 1002339):
+// every module an owner may actually choose, in the order the picker lists them,
+// with copy written for someone who has met none of them.
+//
+// WHY THE COPY IS DECLARED HERE and not read off the manifests. `module.json`'s
+// `title` + `description` are written for a builder reading a module list —
+// "Outbound ship broadcast + the inbound #ideas/#bugs bot + role-sync … (ADR
+// 0033)" is true and unusable on a creation screen. The hub's own catalog read
+// (`GET /modules`) also needs a session, and this picker is read by a signed-out
+// wizard. So the same decision ADR 0237 §3 already made for the bundle keys
+// applies to the choices: DECLARE them, keep the file pure, and let
+// tests/provisioning_starter_bundles.mjs be the link back to the manifests — it
+// fails the build when the declared set drifts from the on-disk `default: false`
+// modules, so a new opt-in module cannot ship without owner-facing copy.
+const OPTIONAL_MODULES = Object.freeze([
+  Object.freeze({
+    key: 'agents',
+    label: 'Extra agents',
+    summary: 'More AI agents alongside the ones every project gets, for reading, research and review.',
+  }),
+  Object.freeze({
+    key: 'dev-box',
+    label: 'Dev boxes',
+    summary: 'A cloud workspace where a change can be tried out before anyone else sees it. Nothing is charged until someone asks for one.',
+  }),
+  Object.freeze({
+    key: 'discord',
+    label: 'Discord',
+    summary: 'A Discord server that carries your build news, and lets people send ideas and bug reports back.',
+  }),
+]);
+
+// The opt-in keys alone, for the membership tests the normalizer runs. Derived,
+// so the declaration above stays the single place a choice is written down.
+const OPTIONAL_MODULE_KEYS = Object.freeze(OPTIONAL_MODULES.map((m) => m.key));
+
 // The curated presets, keyed by the declared project type (the closed vocabulary
 // owner-decided 2026-08-13 and mirrored in provisioning.PROJECT_TYPES + the
 // provisioning_007 CHECK). `label` and `summary` are the owner-facing copy the
@@ -150,10 +186,65 @@ function allStarterBundles() {
   return Object.keys(STARTER_BUNDLES).map(bundleForProjectType);
 }
 
+// The opt-in catalog, as the picker reads it — fresh copies, so a caller may
+// sort or splice without corrupting the frozen declaration.
+function optionalModules() {
+  return OPTIONAL_MODULES.map((m) => ({ ...m }));
+}
+
+// A MODULE SELECTION as it may be STORED (BV1.R20, task 1002339): opt-in keys
+// only, deduped, in catalog order. Everything else is dropped — an always-on
+// module (it was never a choice), a hub-only one (the control plane's own), and
+// anything not on the catalog.
+//
+// THREE-VALUED ON PURPOSE, and this is the whole contract:
+//
+//   null  the owner never answered — they skipped the picker, or the request
+//         predates it. The set they get is resolved at READ time from the type's
+//         starter bundle (effectiveModules below), the same way effectiveSettings
+//         applies a default it never wrote down. Absent stays absent.
+//   []    the owner answered "none of them" — a real choice, and a different
+//         fact from never having been asked.
+//   [...] what the owner picked.
+//
+// PURE. Mirrors normalizeProjectDetail's rule beside it: an off-vocabulary value
+// is dropped rather than defaulted, because a module nobody chose is worse than
+// no module.
+function normalizeModuleSelection(input) {
+  if (!Array.isArray(input)) return null;
+  const asked = new Set(input.filter((k) => typeof k === 'string'));
+  return OPTIONAL_MODULE_KEYS.filter((k) => asked.has(k));
+}
+
+// What a row's modules READ as: the always-on floor, plus whatever the owner
+// chose — or, when they never answered, the starter bundle for their declared
+// type. `source` says which of the two it is, so a surface can tell a chosen
+// empty set from an unanswered one without re-deriving the rule.
+//
+// This is what makes skipping the picker a supported default rather than a
+// project with nothing on it: the flow's preselect and the server's fallback are
+// the SAME declaration, so the owner gets exactly the set the panel showed them.
+// PURE — takes a row-shaped `{ type, modules }`, touches no database.
+function effectiveModules(row) {
+  const chosen = normalizeModuleSelection(row && row.modules);
+  const preset = bundleForProjectType(row && row.type);
+  const selected = chosen === null ? preset.bundle : chosen;
+  return {
+    core: [...ALWAYS_ON_CORE],
+    selected,
+    modules: [...ALWAYS_ON_CORE, ...selected],
+    source: chosen === null ? 'bundle' : 'chosen',
+  };
+}
+
 module.exports = {
   ALWAYS_ON_CORE,
   HUB_ONLY_MODULES,
+  OPTIONAL_MODULES,
   STARTER_BUNDLES,
   bundleForProjectType,
   allStarterBundles,
+  optionalModules,
+  normalizeModuleSelection,
+  effectiveModules,
 };

package/modules/public-landing/public/assets/cosmos.css

@@ -1459,7 +1459,7 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
 /* the six-step strip as the rail: six hairlines, a 7px dot, one lit step on the
    accent with its halo, the number in the display voice, the name in the label
    face; a step already answered (role=button) stays a way back */
-#view-new .steps{display:grid;grid-template-columns:repeat(6,1fr);gap:0 10px;align-items:start;margin:0 0 40px;}
+#view-new .steps{display:grid;grid-template-columns:repeat(7,1fr);gap:0 10px;align-items:start;margin:0 0 40px;}
 #view-new .steps li{display:block;position:relative;border-top:1px solid var(--rule);padding:12px 0 0;gap:0;}
 #view-new .steps li::before{content:"";position:absolute;top:-4px;left:0;right:auto;width:7px;height:7px;margin:0;border-radius:50%;border:1px solid var(--rule);background:var(--bg);}
 #view-new .steps .snum{display:block;width:auto;height:auto;border:0;border-radius:0;background:none;font-family:var(--font-display);font-weight:300;font-size:22px;letter-spacing:-.02em;line-height:1.1;color:var(--ink-faint);margin-bottom:2px;}