@bongos/core 1.19.515 → 1.19.517

package/docs/module-api-changelog.md

@@ -1467,5 +1467,9 @@ 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)
+  1.19.517 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.516 with no explicit bump. run 33799755382. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/hall-ui/public/drachmae.html

@@ -102,6 +102,9 @@
 <!-- jump palette (Ctrl/Cmd-K). Optional by design: without it the shell's slot stays hidden. -->
 <script src="/builders/palette.js" defer></script>
 <script src="/builders/md-reader.js?v=2026-09-02-mdreader-2"></script>
+<!-- The chart primitive, for the treasury section (task 1003446). Before
+     drachmae.js, which reads window.OTBKit when it inserts that section. -->
+<script src="/builders/hall-kit.js" defer></script>
 <script src="/builders/drachmae.js?v=2026-09-02-drachmae-2" defer></script>
 <script src="/builders/copy-on-click.js?v=2026-06-01-copy-1" defer></script>
 </body>

package/modules/hall-ui/public/drachmae.js

@@ -31,6 +31,15 @@
   // The doc lives at docs/onboarding/, so relative links resolve against it.
   const DOC_DIR = 'docs/onboarding/';
   const BOUNTY_URL = '/api/gds/public/bounty-table';
+  // task 1003446: the treasury feed. NOT a new endpoint — this is the same
+  // /public/cost-summary the signed-out status page already draws as a
+  // cumulative line and the Work board already fetches to read ONE scalar off
+  // (`total_value_credits`). Its own route comment calls `daily[]` "the
+  // treasury chart's cumulative line"; the series was in the payload the whole
+  // time, and the stranger got the chart while the builder got the number.
+  const TREASURY_URL = '/api/gds/public/cost-summary';
+  const TREASURY_SECTION_ID = 'the-treasury';
+  const TREASURY_SECTION_TITLE = 'The treasury, so far';
   const BOUNTY_SECTION_ID = 'security-bounty-rates';
   const BOUNTY_SECTION_TITLE = 'Security bounty rates';
   // The section the live table is inserted AHEAD of: the doc's closing links.
@@ -109,6 +118,129 @@
     return true;
   }
 
+  // ---- the treasury (task 1003446) -----------------------------------------
+
+  // One cumulative figure: the plot, the number it ends on, and the table twin
+  // that keeps it out of picture-only territory. `fmt` renders a value for a
+  // human; `rows` is the twin's own text, so the money and the credits can read
+  // differently without the chart knowing about either.
+  function treasuryFigure({ id, title, points, fmt, foot }) {
+    const kit = window.OTBKit;
+    const esc = window.OTBMdReader.escapeHtml;
+    if (!points.length) return '';
+    const last = points[points.length - 1];
+    const series = kit.timeStepSeriesHtml(points, {
+      x0: points[0].x,
+      x1: last.x,
+      yMax: last.value,
+    });
+    const { endX, endY } = series.geometry;
+    const day = (t) => new Date(t).toISOString().slice(0, 10);
+    // Every 7th day plus the last: a twin with one row per calendar day since
+    // May would be ~120 rows behind a disclosure nobody finishes reading.
+    const twinRows = points.filter((p, i) => i % 7 === 0 || i === points.length - 1);
+    return `<figure class="pchart" id="${esc(id)}">
+      <figcaption class="pchart__title">${esc(title)}</figcaption>
+      ${kit.plotSvgHtml({
+    series: series.body,
+    // No readout is wired here, so no focus stop and no dead crosshair.
+    interactive: false,
+    ariaLabel: `${title}: ${fmt(last.value)} as of ${day(last.x)}`,
+    label: kit.plotValueLabelHtml(endX, endY - 8, fmt(last.value), 'end'),
+    leftTick: day(points[0].x),
+    rightTick: day(last.x),
+  })}
+      <details class="pchart__twin">
+        <summary>Read it as a table</summary>
+        <table class="ledger pchart__table"><thead><tr><th>Day</th><th>${esc(title)}</th></tr></thead><tbody>
+        ${twinRows.map((p) => `<tr><td>${esc(day(p.x))}</td><td>${esc(fmt(p.value))}</td></tr>`).join('')}
+        </tbody></table>
+      </details>
+      <p class="pchart__foot">${esc(foot)}</p>
+    </figure>`;
+  }
+
+  // The live treasury as a real section of the article, ahead of the rate card.
+  // Returns false when the summary can't be read: the prose stays and no empty
+  // panel or outline entry that leads nowhere is rendered — the same contract
+  // insertBountySection keeps.
+  async function insertTreasurySection(article) {
+    if (!window.OTBKit) {
+      console.warn('[drachmae] OTBKit missing — the treasury section needs the chart primitive');
+      return false;
+    }
+    let payload;
+    try {
+      const r = await fetch(TREASURY_URL, { credentials: 'same-origin' });
+      if (!r.ok) throw new Error(`${TREASURY_URL} → ${r.status}`);
+      payload = await r.json();
+    } catch (err) {
+      console.warn('[drachmae] cost summary unavailable:', err.message);
+      return false;
+    }
+    const esc = window.OTBMdReader.escapeHtml;
+    const kit = window.OTBKit;
+    const currency = (window.__BRANDING__ && window.__BRANDING__.currency
+      && window.__BRANDING__.currency.label) || 'credits';
+    const Currency = currency.charAt(0).toUpperCase() + currency.slice(1);
+    const usd = (n) => `$${Number(n || 0).toLocaleString(undefined, { maximumFractionDigits: 0 })}`;
+    const num = (n) => Number(n || 0).toLocaleString();
+
+    // The server already ran generate_series, so every calendar day is present
+    // and a flat run is a real flat run rather than a missing sample.
+    const spend = kit.cumulateByDay(payload.daily, { valueOf: (r) => r.amount_usd });
+    const earned = kit.cumulateByDay(payload.daily_credits, { valueOf: (r) => r.credits });
+    // Both series empty is a treasury with nothing in it yet — one honest line,
+    // not two empty plots.
+    if (!spend.length && !earned.length) return false;
+
+    const figures = [
+      treasuryFigure({
+        id: 'treasury-spend',
+        title: 'Spent, cumulative',
+        points: spend,
+        fmt: usd,
+        foot: 'Every recorded cost — API, infra, compute, art — added up day by day.',
+      }),
+      treasuryFigure({
+        id: 'treasury-earned',
+        title: `${Currency} awarded, cumulative`,
+        points: earned,
+        fmt: num,
+        foot: `What the project has paid builders, in ${esc(currency)}, day by day.`,
+      }),
+    ].filter(Boolean).join('');
+
+    // Where the money went, as the kit's bar series rather than a fourth
+    // hand-rolled one. Categories arrive sorted biggest-first.
+    const byCategory = (payload.by_category || []).slice(0, 8);
+    const categories = byCategory.length
+      ? `<h3 id="treasury-by-category">Where it went</h3>`
+        + kit.barSeriesHtml(
+          byCategory.map((c) => ({ label: c.category, value: c.total_usd, valueLabel: usd(c.total_usd) })),
+          { list: true, ariaLabel: 'Spend by category', valueWidth: '84px' },
+        )
+      : '';
+
+    const section = document.createElement('section');
+    section.innerHTML =
+      `<h2 id="${esc(TREASURY_SECTION_ID)}">${esc(TREASURY_SECTION_TITLE)}</h2>`
+      + `<p>These are this project's real numbers, read from the server when you `
+      + `opened this page. It has spent <strong>${esc(usd(payload.total_usd))}</strong> `
+      + `and awarded <strong>${esc(num(payload.total_value_credits))} ${esc(currency)}</strong> `
+      + `for the work that money bought.</p>`
+      + `<div class="pcharts">${figures}</div>`
+      + categories;
+
+    const bounty = article.querySelector(`#${BOUNTY_SECTION_ID}`);
+    const closing = [...article.querySelectorAll('h2')].find((h) => CLOSING_H2.test(h.textContent.trim()));
+    // Ahead of the rate card if it landed first, else ahead of the closing
+    // links, else appended: the doc keeps ending on "dig deeper" either way.
+    const before = (bounty && bounty.parentElement === article ? bounty : null) || closing;
+    if (before) article.insertBefore(section, before); else article.appendChild(section);
+    return true;
+  }
+
   // The outline is read from the RENDERED headings rather than the parser's raw
   // text, so `*not*` and a [link](…) in a heading arrive as plain words, and so
   // the live section inserted above is simply one more heading in order.
@@ -276,9 +408,13 @@
     article.innerHTML = parsed.html.replace(/^\s*<h1\b[^>]*>[\s\S]*?<\/h1>\s*/, '');
     article.removeAttribute('aria-busy');
     show('article');
-    // Awaited before the outline is built so the rate card gets its entry and a
-    // scrollspy target; the article itself is already on screen by now.
+    // Awaited before the outline is built so both live sections get their
+    // entries and scrollspy targets; the article itself is already on screen by
+    // now. The rate card goes in FIRST so the treasury can land ahead of it by
+    // id — the doc then reads prose, then what actually happened, then the
+    // published rates, then "dig deeper".
     await insertBountySection(article);
+    await insertTreasurySection(article);
     addAnchors(article);
     setupTocToggle();
     setupScrollspy(renderToc(collectHeadings(article)));

package/modules/hall-ui/public/hall-kit.js

@@ -663,6 +663,35 @@
     return chartNums(values).map((v) => (run += v));
   }
 
+  // Timestamped rows → [{ x, value }] ascending, one point per calendar day
+  // that HAS a row, value cumulative. The third consumer of this shape put it
+  // here (task 1003446): the profile's works and credits lines, and
+  // /drachmae's treasury. Two callers is a coincidence; three is a primitive.
+  //
+  // `dateOf`/`valueOf` are the caller's, because only the caller knows which
+  // column is the date — `shipped_at` on an activity row, `recorded_at` on a
+  // credits row, `day` on a gap-filled daily feed. A row whose date will not
+  // parse is DROPPED rather than counted at the epoch, where it would stretch
+  // the axis back to 1970 and flatten every real point against the floor.
+  function cumulateByDay(rows, opts = {}) {
+    const dateOf = opts.dateOf || ((r) => r && r.day);
+    const valueOf = opts.valueOf || ((r) => r && r.value);
+    const byDay = new Map();
+    for (const r of rows || []) {
+      const t = Date.parse(dateOf(r));
+      if (!Number.isFinite(t)) continue;
+      // The epoch-day floor — UTC midnight, so two rows on one day land on one
+      // point. Same value as setUTCHours(0,0,0,0) without a Date per row, and
+      // the same expression profile-charts.js's own `midnight` used before this
+      // moved, so no series shifts by a day.
+      const d = Math.floor(t / 86400000) * 86400000;
+      byDay.set(d, (byDay.get(d) || 0) + (Number(valueOf(r)) || 0));
+    }
+    const days = [...byDay.keys()].sort((a, b) => a - b);
+    const totals = cumulate(days.map((d) => byDay.get(d)));
+    return days.map((d, i) => ({ x: d, value: totals[i] }));
+  }
+
   // The line geometry, separated from the markup so a chart that needs the
   // maths without this SVG can take just this. Returns { points, x, y, nums }.
   //
@@ -867,21 +896,30 @@
     return { body, xs, base, py, max };
   }
 
-  // The plot itself: the series a geometry built, on the axis, with the hidden
-  // crosshair a caller's readout moves and the two end ticks. `tabindex="0"` is
-  // deliberate and paired with the readout — the chart is walkable by arrow
-  // key, so it has to be reachable by tab.
+  // The plot itself: the series a geometry built, on the axis, with the two end
+  // ticks — and, when the caller wires a readout, the hidden crosshair it moves
+  // plus the `tabindex` that makes an arrow-key-walkable chart reachable by tab.
+  //
+  // `interactive: false` (task 1003446) drops BOTH of those, and the pairing is
+  // the point: a `role="img"` with a `tabindex="0"` is a focus stop a keyboard
+  // reader lands on with nothing to do there, and a crosshair nothing moves is
+  // markup that only looks like a feature. A plot whose whole reading is its
+  // aria-label and its table twin says so.
   function plotSvgHtml(opts = {}) {
     const { width, height, pad, base } = plotBox(opts);
+    const interactive = opts.interactive !== false;
     const tick = (x, text, anchor) => (text
       ? `<text class="kit-plot__tick" x="${x}" y="${height - 6}"`
         + `${anchor ? ` text-anchor="${anchor}"` : ''}>${esc(text)}</text>`
       : '');
-    return `<svg class="kit-plot" viewBox="0 0 ${width} ${height}" role="img" tabindex="0"`
+    return `<svg class="kit-plot" viewBox="0 0 ${width} ${height}" role="img"`
+      + (interactive ? ' tabindex="0"' : '')
       + ` aria-label="${esc(opts.ariaLabel || '')}">`
       + (opts.series || '')
       + `<line class="kit-plot__axis" x1="${pad.l}" y1="${base}" x2="${width - pad.r}" y2="${base}"></line>`
-      + `<line class="kit-plot__hair" x1="0" y1="${pad.t}" x2="0" y2="${base}" style="visibility:hidden"></line>`
+      + (interactive
+        ? `<line class="kit-plot__hair" x1="0" y1="${pad.t}" x2="0" y2="${base}" style="visibility:hidden"></line>`
+        : '')
       + (opts.label || '')
       + tick(pad.l, opts.leftTick)
       + tick(width - pad.r, opts.rightTick, 'end')
@@ -918,7 +956,7 @@
     // charts (task 1003445) — the ONE place the hall draws a series.
     // linePoints/cumulate are the maths on their own, for a chart that wants
     // the geometry without this SVG (the profile's timeChart).
-    sparklineHtml, barSeriesHtml, chartCardHtml, linePoints, cumulate,
+    sparklineHtml, barSeriesHtml, chartCardHtml, linePoints, cumulate, cumulateByDay,
     // plotted charts: the axis frame + the two series shapes that ride it
     plotSvgHtml, plotValueLabelHtml, timeStepSeriesHtml, timeStepGeometry, columnSeriesHtml,
     // plotBox is exported so a caller mapping pointer x back into viewBox

package/modules/hall-ui/public/profile-charts.js

@@ -101,20 +101,13 @@
   // point; a row with no parsable date is skipped, not zeroed. The lookback
   // clips this for drawing (clipToWindow) rather than re-accumulating, so the
   // running total stays true.
+  // The grouping AND the running total are the kit's since task 1003446, when
+  // /drachmae's treasury became the third caller of this shape. This wrapper
+  // survives only to keep the `{ day, value }` key this page's callers and
+  // clipToWindow already read; the arithmetic has one home.
   function cumulativeByDay(rows, valueOf, dateOf = (r) => r && r.shipped_at) {
-    const byDay = new Map();
-    for (const r of rows || []) {
-      const t = Date.parse(dateOf(r));
-      if (!Number.isFinite(t)) continue;
-      const d = midnight(t);
-      byDay.set(d, (byDay.get(d) || 0) + Number(valueOf(r)) || 0);
-    }
-    // The grouping is this function's; the running total is the kit's
-    // (task 1003445), so the hall has ONE accumulator rather than two that
-    // could disagree about what a hole in the series means.
-    const days = [...byDay.keys()].sort((a, b) => a - b);
-    const totals = window.OTBKit.cumulate(days.map((d) => byDay.get(d)));
-    return days.map((d, i) => ({ day: d, value: totals[i] }));
+    return window.OTBKit.cumulateByDay(rows, { dateOf, valueOf })
+      .map((p) => ({ day: p.x, value: p.value }));
   }
 
   // Clip a cumulative series to [windowStart, ∞) for drawing. The line must

package/modules/hall-ui/public/profile.css

@@ -119,41 +119,12 @@
    (glass on the card, like settings' quote), the series in the accent and every
    word in ink. The SVG scales with its card; the axis band is inside the
    viewBox, so the card grows with its content and never scrolls. */
-.pcharts {
-  display: grid;
-  grid-template-columns: repeat(2, minmax(0, 1fr));
-  gap: var(--sp-sm);
-}
-.pchart {
-  margin: 0;
-  padding: var(--sp-xs) var(--sp-sm) var(--sp-xs);
-  background: var(--glass);
-  border: var(--line) solid var(--glass-edge);
-  border-radius: var(--radius-sm);
-  min-width: 0;
-}
-.pchart__title { margin: 0; font-size: 13.5px; font-weight: 500; color: var(--ink); }
-.pchart__read { margin: 2px 0 var(--sp-hair); font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-soft); min-height: 1.4em; }
-/* The plot itself — the svg, the line, the columns, the axis, the crosshair,
-   the ticks — is OTBKit's `.kit-plot*` in style.css (task 1003445). It was
-   written twice in this file's own script, and the goal's next charts want it
-   again. The dataviz spec moved verbatim; what stays below is this page's
-   FIGURE: the caption, the live readout, the table twin and the foot. */
-.pchart__twin { margin-top: var(--sp-hair); }
-.pchart__twin > summary { display: inline-flex; align-items: center; min-height: 24px; padding: 0 4px; margin: 0 -4px; font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-soft); cursor: pointer; border-radius: var(--radius-sm); }
-.pchart__twin > summary:hover { color: var(--ink); background: var(--glass-strong); }
-.pchart__table { margin-top: var(--sp-hair); font-size: 12.5px; }
-.pchart__table td, .pchart__table th { padding: 3px 6px; }
-.pchart__foot { margin: var(--sp-hair) 0 0; font-size: 12px; color: var(--ink-faint); }
-.pchart__note { margin: 0; font-size: 14px; color: var(--ink-soft); }
-/* the craft mix: label, bar, count — a row is its own table row */
-/* The craft mix is OTBKit.barSeriesHtml (task 1003445) — the .pmix family was
-   the hall's third copy of one horizontal bar. Only the vertical air around it
-   is this page's; the row, the track and the 24px floor are the kit's. */
-.pchart .kit-bars { margin: var(--sp-hair) 0; }
-@media (max-width: 720px) {
-  .pcharts { grid-template-columns: minmax(0, 1fr); }
-}
+/* The plot is OTBKit's `.kit-plot*` (task 1003445) and the FIGURE around it —
+   `.pcharts` / `.pchart` / `__title` / `__read` / `__twin` / `__table` /
+   `__foot` — moved to style.css beside it in task 1003446, when /drachmae's
+   treasury became its second consumer. The names did not change: they are
+   spelled into profile.js AND drachmae.js. What stays in this sheet is the one
+   thing only this page has, the lookback control below. */
 
 /* the lookback control (task 1003489, owner request) — one segmented row above
    the grid, scoping every chart. The pressed side takes the accent TINT the

package/modules/hall-ui/public/style.css

@@ -2047,6 +2047,41 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
 .kit-plot__end { font-family: var(--font-body); font-size: 11.5px; font-weight: 500; fill: var(--ink); }
 .kit-plot__tick { font-family: var(--label-face); font-size: 10px; letter-spacing: var(--label-space); text-transform: var(--label-case); fill: var(--ink-faint); }
 
+/* The FIGURE a plot sits in — a card one tonal step down from the panel (glass
+   on the card, like settings' quote), its caption, its live readout, its
+   <details> table twin and its foot. Moved here from profile.css in task
+   1003446, when /drachmae's treasury became the second consumer; the `.pchart`
+   names are unchanged because they are spelled into profile.js and drachmae.js.
+   The kit does NOT emit these — a page composes its own figure and the kit
+   draws the series inside it. */
+.pcharts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--sp-sm);
+}
+.pchart {
+  margin: 0;
+  padding: var(--sp-xs) var(--sp-sm) var(--sp-xs);
+  background: var(--glass);
+  border: var(--line) solid var(--glass-edge);
+  border-radius: var(--radius-sm);
+  min-width: 0;
+}
+.pchart__title { margin: 0; font-size: 13.5px; font-weight: 500; color: var(--ink); }
+.pchart__read { margin: 2px 0 var(--sp-hair); font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-soft); min-height: 1.4em; }
+.pchart__twin { margin-top: var(--sp-hair); }
+.pchart__twin > summary { display: inline-flex; align-items: center; min-height: 24px; padding: 0 4px; margin: 0 -4px; font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: var(--label-case); color: var(--ink-soft); cursor: pointer; border-radius: var(--radius-sm); }
+.pchart__twin > summary:hover { color: var(--ink); background: var(--glass-strong); }
+.pchart__table { margin-top: var(--sp-hair); font-size: 12.5px; }
+.pchart__table td, .pchart__table th { padding: 3px 6px; }
+.pchart__foot { margin: var(--sp-hair) 0 0; font-size: 12px; color: var(--ink-faint); }
+.pchart__note { margin: 0; font-size: 14px; color: var(--ink-soft); }
+/* The bar series inside a figure keeps the figure's own vertical air. */
+.pchart .kit-bars { margin: var(--sp-hair) 0; }
+@media (max-width: 720px) {
+  .pcharts { grid-template-columns: minmax(0, 1fr); }
+}
+
 .curve__kinds { display: flex; flex-direction: column; gap: 6px; margin-top: 16px; }
 
 /* ---------- onboarding checklist ---------- */

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>