@bongos/core 1.19.533 → 1.19.535

package/tests/project_modules_ui.mjs

@@ -0,0 +1,318 @@
+// tests/project_modules_ui.mjs — adding and removing a project's extras AFTER
+// creation, EXECUTED (BV1.R23, task 1002342, ADR 0245).
+//
+// tests/provisioning_module_selection.mjs pins the ROUTE half of "add modules
+// later"; this file pins the surface an owner actually uses. It lifts the manage
+// page's extras region out of modules/public-landing/public/projects.html —
+// ensureModsCatalog, modsSelected, renderMods, doModToggle and the delegated
+// click — runs it in a vm under a minimal DOM stub, PARSES the markup it writes
+// into innerHTML, and drives a real click on a toggle.
+//
+// The precedent is tests/project_door_ui.mjs beside it (there is no jsdom in this
+// repo), including its rule that the slice boundaries are themselves asserted, so
+// a rename can never leave this file quietly executing an empty string.
+//
+// What it proves, and why each matters:
+//   • the optional CATALOG renders — one row per module the server offers, with
+//     the owner-facing line, and nothing the server did not offer
+//   • the project's CURRENT set is what is switched on, resolved by the SERVER
+//     (a skipped picker reads as its bundle, and this page never re-derives that
+//     rule — the one way two surfaces name different modules for one project)
+//   • a toggle issues the write, as the WHOLE list in catalog order, on the
+//     own-scoped detail channel
+//   • the band repaints from the platform's answer, never from what was sent —
+//     and a refusal puts it back to what the row still says
+//   • the always-on core is stated and is not on the band at all
+//   • the done panel carries one pointer at this surface for the project just
+//     created, so a skipped picker is never a dead end
+//
+// Run:  node --test --test-reporter=tap tests/project_modules_ui.mjs
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8')
+  .replace(/\r\n/g, '\n');
+const SCRIPT = (HUB.match(/<script>([\s\S]*?)<\/script>\s*<\/body>/) || [, ''])[1];
+
+const START = SCRIPT.indexOf('var modsCatalog = null;');
+const END = SCRIPT.indexOf('/* ── on the map (task 1002324)');
+assert.ok(START > 0, 'the extras region must start at modsCatalog');
+assert.ok(END > START, 'the extras region must end before the join-door section');
+const REGION = SCRIPT.slice(START, END);
+for (const fn of ['function ensureModsCatalog(', 'function renderMods(', 'function doModToggle(']) {
+  assert.ok(REGION.includes(fn), `the region must carry ${fn}`);
+}
+
+// ── the fixture catalog ──────────────────────────────────────────────────────
+// A FIXTURE, not a live require: this file asserts the band reads the shape, and
+// tests/provisioning_starter_bundles.mjs asserts the route emits it. Two files,
+// one shape, neither taking the other's word for it (the module-picker rule).
+const CATALOG = {
+  core: ['memory', 'lifecycle', 'hall-ui'],
+  optional: [
+    { key: 'dev-box', label: 'Dev box', summary: 'A shared machine your builders work on.' },
+    { key: 'discord', label: 'Discord', summary: 'Mirrors what ships into a Discord channel.' },
+    { key: 'agents', label: 'Agents', summary: 'Lets AI builders claim and ship work on their own.' },
+  ],
+};
+
+// ── the DOM stub ─────────────────────────────────────────────────────────────
+// Narrow on purpose (the task_detail_ui.mjs rule): it supports exactly what the
+// region uses, so it stays honest about what it can prove.
+
+const ROW = /<button type="button" class="modOpt" data-mod="([^"]*)" aria-pressed="(true|false)"( disabled)?><b>([^<]*)<\/b><small>([^<]*)<\/small><\/button>/g;
+
+function parseRows(html) {
+  return [...String(html).matchAll(ROW)].map((m) => ({
+    key: m[1], on: m[2] === 'true', disabled: !!m[3], label: m[4], summary: m[5],
+  }));
+}
+
+// Boot the region against a scripted catalog + detail channel and hand back the
+// handles a test drives it with.
+function boot({ selected = ['dev-box'], source = 'chosen', catalog = CATALOG, catalogOk = true, patchAnswer } = {}) {
+  const requests = [];
+  const els = new Map();
+  const listeners = new Map();
+
+  const makeEl = (id) => ({
+    _id: id, _html: '', textContent: '', className: '', disabled: false,
+    set innerHTML(v) { this._html = String(v); },
+    get innerHTML() { return this._html; },
+    addEventListener(type, fn) {
+      if (type !== 'click') return;
+      if (!listeners.has(id)) listeners.set(id, []);
+      listeners.get(id).push(fn);
+    },
+  });
+  const $ = (id) => {
+    if (!els.has(id)) els.set(id, makeEl(id));
+    return els.get(id);
+  };
+  const slotHtml = () => ($('mMods')._html || '');
+
+  // `_json` is what jsonOrEmpty hands back (the PATCH path); `json()` is what
+  // ensureModsCatalog calls directly (the GET path) — the region uses both.
+  const answer = (body, { ok = true, status = 200 } = {}) =>
+    Promise.resolve({ ok, status, _json: body, json: () => Promise.resolve(body) });
+  const fetch = (url, init = {}) => {
+    const method = init.method || 'GET';
+    requests.push({ url, method, body: init.body, credentials: init.credentials, headers: init.headers });
+    if (method === 'GET') {
+      return catalogOk ? answer(catalog) : answer({}, { ok: false, status: 500 });
+    }
+    if (patchAnswer) return patchAnswer;
+    // the platform's own answer: what the row now resolves to (effectiveModules)
+    const sent = JSON.parse(init.body).modules;
+    return answer({ ok: true, modules: { core: catalog.core, selected: sent, modules: catalog.core.concat(sent), source: 'chosen', adjustments: [] } });
+  };
+
+  const sandbox = {
+    $, fetch, console, Promise, JSON, String, Object, Array, Error, RegExp,
+    encodeURIComponent, setTimeout, clearTimeout,
+    API: '/api/bongos',
+    manageId: '18',
+    manageInst: { id: 18, status: 'active', modules: { core: catalog.core, selected: selected.slice(), modules: catalog.core.concat(selected), source, adjustments: [] } },
+    esc: (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;'),
+    jsonOrEmpty: (res) => Promise.resolve(res._json),
+    apiError: (data, status) => ({ code: (data && data.error && data.error.code) || 'error', message: (data && data.error && data.error.message) || `HTTP ${status}` }),
+    signInAgain: () => '<a href="/signin">Sign in again</a>',
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(REGION, sandbox, { filename: 'projects.html#project-extras' });
+
+  const settle = async () => { for (let i = 0; i < 40; i++) await Promise.resolve(); };
+  return {
+    requests, sandbox, settle,
+    rows: () => parseRows(slotHtml()),
+    slot: () => slotHtml(),
+    msg: () => $('mModMsg'),
+    async render() { sandbox.renderMods(sandbox.manageInst); await settle(); },
+    async click(key) {
+      const handlers = listeners.get('mMods') || [];
+      assert.equal(handlers.length, 1, 'the section wires exactly one delegated click handler');
+      const row = parseRows(slotHtml()).find((r) => r.key === key);
+      assert.ok(row, `the band carries a row for ${key}`);
+      handlers[0]({
+        target: {
+          closest: (sel) => (sel === '.modOpt[data-mod]'
+            ? { disabled: row.disabled, getAttribute: (a) => (a === 'data-mod' ? key : null) }
+            : null),
+        },
+      });
+      await settle();
+    },
+  };
+}
+
+// ── the tests ────────────────────────────────────────────────────────────────
+
+test('the band renders the optional catalog the server offered — a row and a sentence each', async () => {
+  // Arrange
+  const ui = boot({ selected: ['dev-box'] });
+
+  // Act
+  await ui.render();
+
+  // Assert
+  assert.deepEqual(ui.rows().map((r) => r.key), ['dev-box', 'discord', 'agents']);
+  assert.deepEqual(ui.rows().map((r) => r.label), ['Dev box', 'Discord', 'Agents']);
+  for (const r of ui.rows()) assert.ok(r.summary.length > 20, `${r.label} says what it is for`);
+});
+
+test('what the project runs today is what is switched on — resolved by the server, not re-derived here', async () => {
+  // A project that SKIPPED the picker reads as its own starter bundle, and the
+  // band must show that set rather than an empty one: the whole point of
+  // effectiveModules resolving `source: 'bundle'` on the way out.
+  const ui = boot({ selected: ['dev-box', 'discord'], source: 'bundle' });
+
+  await ui.render();
+
+  assert.deepEqual(ui.rows().filter((r) => r.on).map((r) => r.key), ['dev-box', 'discord']);
+  assert.deepEqual(ui.rows().filter((r) => !r.on).map((r) => r.key), ['agents']);
+});
+
+test('the always-on core is COUNTED and stated, and is not a row anyone can switch off', async () => {
+  const ui = boot({ selected: [] });
+
+  await ui.render();
+
+  assert.match(ui.slot(), /the same 3 core parts/, 'the clause names how many, from the server\'s own list');
+  assert.deepEqual(ui.rows().map((r) => r.key), ['dev-box', 'discord', 'agents'], 'and no core key is on the band');
+  for (const key of CATALOG.core) {
+    assert.equal(ui.rows().some((r) => r.key === key), false, `${key} is not a choice`);
+  }
+});
+
+test('a toggle issues the write — the WHOLE list, in catalog order, on the own-scoped detail channel', async () => {
+  // Arrange
+  const ui = boot({ selected: ['discord'] });
+  await ui.render();
+
+  // Act — switch the dev box ON
+  await ui.click('dev-box');
+
+  // Assert
+  const patch = ui.requests.find((r) => r.method === 'PATCH');
+  assert.ok(patch, 'a PATCH was sent');
+  assert.equal(patch.url, '/api/bongos/provisioning/instances/18/detail');
+  assert.deepEqual(JSON.parse(patch.body), { modules: ['dev-box', 'discord'] },
+    'catalog order, exactly as the column stores it — never append order');
+  assert.equal(patch.credentials, 'same-origin', 'the cookie session is the auth — this page carries no token');
+});
+
+test('a toggle can REMOVE one too — the same list, one key shorter', async () => {
+  const ui = boot({ selected: ['dev-box', 'agents'] });
+  await ui.render();
+
+  await ui.click('agents');
+
+  const patch = ui.requests.find((r) => r.method === 'PATCH');
+  assert.deepEqual(JSON.parse(patch.body), { modules: ['dev-box'] });
+});
+
+test('switching the last one off sends an empty list — a real answer, not a skipped write', async () => {
+  const ui = boot({ selected: ['agents'] });
+  await ui.render();
+
+  await ui.click('agents');
+
+  const patch = ui.requests.find((r) => r.method === 'PATCH');
+  assert.ok(patch, 'the write still happens');
+  assert.deepEqual(JSON.parse(patch.body), { modules: [] });
+});
+
+test('the band repaints from the PLATFORM’S answer, and says the save changed nothing running', async () => {
+  const ui = boot({ selected: [] });
+  await ui.render();
+
+  await ui.click('discord');
+
+  assert.deepEqual(ui.rows().filter((r) => r.on).map((r) => r.key), ['discord']);
+  assert.equal(ui.sandbox.manageInst.modules.source, 'chosen', 'the row is answered now, not still reading its bundle');
+  assert.equal(ui.msg().className, 'projMsg ok');
+  assert.match(ui.msg().textContent, /nothing to restart/i, 'this channel pushes nothing at the instance');
+});
+
+test('a refusal is SAID in the server’s own words, and the band goes back to what the row still holds', async () => {
+  const ui = boot({
+    selected: ['dev-box'],
+    patchAnswer: Promise.resolve({ ok: false, status: 400, _json: { error: { code: 'bad_modules', message: 'Unknown module "discrod" — the choices are: dev-box, discord, agents.' } } }),
+  });
+  await ui.render();
+
+  await ui.click('discord');
+
+  assert.equal(ui.msg().className, 'projMsg err');
+  assert.match(ui.msg().textContent, /Unknown module "discrod"/);
+  assert.deepEqual(ui.rows().filter((r) => r.on).map((r) => r.key), ['dev-box'],
+    'a refused write leaves the band showing the project’s real set');
+});
+
+test('a signed-out save offers a way back in rather than a dead end', async () => {
+  const ui = boot({
+    selected: [],
+    patchAnswer: Promise.resolve({ ok: false, status: 401, _json: {} }),
+  });
+  await ui.render();
+
+  await ui.click('agents');
+
+  assert.match(ui.msg().innerHTML, /Sign in again/);
+});
+
+test('a catalog that ANSWERED badly says so; nothing about the project is claimed to have changed', async () => {
+  const ui = boot({ selected: ['dev-box'], catalogOk: false });
+
+  await ui.render();
+  await ui.settle();
+  await ui.render();
+
+  assert.match(ui.slot(), /couldn’t load the list of extras/i);
+  assert.match(ui.slot(), /Nothing about your project has changed/);
+  assert.equal(ui.rows().length, 0, 'and no band is painted from a catalog we do not have');
+});
+
+test('the catalog is read ONCE however often the section repaints', async () => {
+  const ui = boot({ selected: [] });
+
+  await ui.render();
+  await ui.render();
+  await ui.click('agents');
+
+  const gets = ui.requests.filter((r) => r.method === 'GET');
+  assert.equal(gets.length, 1, 'memoised like the wizard picker’s own read');
+  assert.equal(gets[0].url, '/api/bongos/provisioning/starter-bundles');
+});
+
+// ── the done panel's one pointer (criterion B) ───────────────────────────────
+// A source pin, the tests/projects_hub.mjs idiom: the line is one sentence in a
+// panel this file does not execute. What matters is that it exists, that it
+// names THIS project rather than the list, and that it stays one line.
+
+test('the wizard’s done panel points at the project’s settings for its extras', () => {
+  assert.match(HUB, /<p class="samePath" id="doneModules"><\/p>/, 'the panel carries the slot');
+  assert.match(SCRIPT, /\$\('doneModules'\)\.innerHTML = 'Add or remove modules later in ' \+ projectPageLink\('the project’s settings'\) \+ '\.';/,
+    'and renderDone fills it with one sentence pointing at the manage page');
+  assert.equal((SCRIPT.match(/doneModules/g) || []).length, 1, 'one line, written in one place');
+  assert.match(SCRIPT, /function projectPageLink\(label\) \{\s*return '<a href="' \+ \(instanceId \? '\?view=manage&id=' \+ encodeURIComponent\(instanceId\)/,
+    'and the link names the instance just created, not the list');
+});
+
+test('a manage link inside the wizard carries its project id through the in-page router', () => {
+  // setView reads `manageId`, never the href — so a done-panel link that only
+  // matched `view=(\w+)` would land every owner on a manage page with no
+  // project, which is what this pointer would have done.
+  const handler = SCRIPT.slice(SCRIPT.indexOf("var a = ev.target.closest && ev.target.closest('a[href^=\"?view=\"]');"));
+  assert.match(handler.slice(0, 900), /var mid = \(href\.match\(\/\[\?&\]id=\(\[\^&\]\*\)\/\) \|\| \[\]\)\[1\];/,
+    'the id is lifted out of the href');
+  assert.match(handler.slice(0, 900), /if \(to === 'manage' && mid\) return goToManage\(decodeURIComponent\(mid\)\);/,
+    'and handed to goToManage, which is what sets manageId');
+});

package/tests/projects_hub.mjs

@@ -2167,7 +2167,12 @@ test('the picker reads ONE public declaration, and it is the one the bundles com
   // A second source for "what may be chosen" is exactly what would let a
   // preselect name a module the panel has no row for (ADR 0237 §5).
   assert.match(SCRIPT, /fetch\(API \+ '\/provisioning\/starter-bundles'/, 'the picker reads the starter-bundles route');
-  assert.equal((SCRIPT.match(/'\/provisioning\/starter-bundles'/g) || []).length, 1, 'exactly once');
+  // Two READERS since task 1002342 — the wizard's panel and the manage page's
+  // extras band — but still ONE declaration: the count is what guards against a
+  // second SOURCE, so it moves only when a reader is added, and both of these
+  // name the same route.
+  assert.equal((SCRIPT.match(/'\/provisioning\/starter-bundles'/g) || []).length, 2,
+    'the create picker and the manage page, and nothing else');
   // and it is a public read — no other module-catalog call joins it
   assert.doesNotMatch(SCRIPT, /fetch\(API \+ '\/modules'/, 'no signed-in catalog read from a signed-out wizard');
 });

package/tests/projects_hub_pre_uat.mjs

@@ -496,8 +496,8 @@ test('a manifest error says a plain sentence, folds the route text, and sends a
     'and it is named by id whenever the flow has one');
   // every done-panel pointer that names a CONTROL goes the same way; the ones
   // that only say "watch it there" still name the list, which does show it
-  assert.equal((SCRIPT.match(/projectPageLink\(/g) || []).length, 6,
-    'the helper and its five callers: the locked step, the domain_required snag, the domainless standup, the snagged retry, the torn-down revive');
+  assert.equal((SCRIPT.match(/projectPageLink\(/g) || []).length, 7,
+    'the helper and its six callers: the locked step, the domain_required snag, the domainless standup, the snagged retry, the torn-down revive, and the extras pointer (task 1002342)');
   for (const dead of ['Retry it \\(and see the technical details\\) from <a href="\\?view=mine">',
                       'Bring it back any time from <a href="\\?view=mine">']) {
     assert.doesNotMatch(SCRIPT, new RegExp(dead), 'a control the list no longer has must not be pointed at there');

package/tests/provision_settings_apply.mjs

@@ -60,6 +60,7 @@ PGDATABASE=spike
 ${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY=public
 ${NEUTRAL_PREFIX}_JOINABILITY=apply
 ${NEUTRAL_PREFIX}_VISIBILITY=public
+${NEUTRAL_PREFIX}_JOIN_GRANT=full
 `;
 
 t('replaces an existing KEY= line where it stands; every other line survives byte-for-byte', () => {
@@ -112,7 +113,7 @@ t('is PURE: same input, same output; empty body yields just the lines', () => {
 t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at standup, under the pack prefix', () => {
   const inst = { slug: 'spike', port: 3010, db_name: 'spike', hosting_shape: 'standalone', target_ref: 'jaxri/spike', settings: { platform_visibility: 'gated' } };
   const vars = P.settingsEnvVarsFor(inst);
-  assert.deepEqual(vars, { [`${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY`]: 'gated', [`${NEUTRAL_PREFIX}_JOINABILITY`]: 'apply', [`${NEUTRAL_PREFIX}_VISIBILITY`]: 'public' });
+  assert.deepEqual(vars, { [`${NEUTRAL_PREFIX}_PLATFORM_VISIBILITY`]: 'gated', [`${NEUTRAL_PREFIX}_JOINABILITY`]: 'apply', [`${NEUTRAL_PREFIX}_VISIBILITY`]: 'public', [`${NEUTRAL_PREFIX}_JOIN_GRANT`]: 'full' });
   const body = P.webEnvBody(inst, {});
   for (const [k, v] of Object.entries(vars)) assert.match(body, new RegExp(`^${k}=${v}$`, 'm'), `${k} at standup`);
 });
@@ -123,10 +124,10 @@ const GATED = { settings: { platform_visibility: 'gated', joinability: 'invite_o
 const manifestWith = (project) => JSON.stringify({ schema: 'instance-manifest/v1', brand: project === undefined ? {} : { project } });
 
 t('true when every pushed key matches brand.project (camelCase, the ENV_OVERRIDES targets)', () => {
-  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public' }), GATED), true);
+  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' }), GATED), true);
 });
 t('false when the instance still reports a different value', () => {
-  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'public', joinability: 'invite_only', visibility: 'public' }), GATED), false);
+  assert.equal(P.settingsConsumed(manifestWith({ platformVisibility: 'public', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' }), GATED), false);
   assert.equal(P.settingsConsumed(manifestWith({ joinability: 'invite_only' }), GATED), false, 'a missing key is a mismatch, not a pass');
 });
 t('null (unknown) when the manifest carries no project block — a core that predates task 1003139 — or does not parse', () => {
@@ -144,7 +145,7 @@ t('instanceManifestCmd asks the instance on loopback, like healthzCmd', () => {
 function recorder({ apply = false, envBody = LIVE_ENV, readFails = false, healthzFails = false, privileged = false,
   manifest = 'match', restartThrows = false, writeThrows = false } = {}) {
   const cmds = [], writes = [], events = [], probes = [], cleared = [], logs = [];
-  const manifestOut = manifest === 'match' ? manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public' })
+  const manifestOut = manifest === 'match' ? manifestWith({ platformVisibility: 'gated', joinability: 'invite_only', visibility: 'public', joinGrant: 'full' })
     : manifest === 'mismatch' ? manifestWith({ platformVisibility: 'public', joinability: 'apply', visibility: 'public' })
     : manifest === 'none' ? manifestWith(undefined) : 'nope';
   const exec = (cmd, opts = {}) => {
@@ -213,7 +214,7 @@ await ta('dry-run PLANS the patch: reads nothing real, writes NOTHING (no synthe
   assert.equal(r.ok, true);
   assert.equal(r.healthy, null, 'nothing ran, nothing observed');
   assert.equal(writes.length, 0, 'a dry-run must not plan a two-line overwrite of web.env');
-  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
+  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
   assert.ok(cmds.some((c) => /restart spike/.test(c)), 'the restart is still in the plan');
   assert.ok(logs.some((l) => /dry-run — nothing ran/.test(l)), 'the closing line does not claim a restart happened');
 });

package/tests/provisioning_module_selection.mjs

@@ -30,7 +30,8 @@ import http from 'node:http';
 // ESM named imports off the CJS module on purpose — knip cannot trace a
 // createRequire() import, so these would read as dead exports (the repo's knip
 // learning; tests/provisioning_starter_bundles.mjs does the same).
-import { ALWAYS_ON_CORE, bundleForProjectType, effectiveModules } from '../modules/provisioning/starter-bundles.js';
+import { ALWAYS_ON_CORE, bundleForProjectType, effectiveModules, normalizeModuleSelection }
+  from '../modules/provisioning/starter-bundles.js';
 
 const require = createRequire(import.meta.url);
 const provisioning = require('../modules/provisioning/provisioning.js');
@@ -178,6 +179,10 @@ provisioning.updateInstanceDetail = async (_db, _id, patch) => {
   if (patch.detail !== undefined) {
     lastUpdatedRow.detail = { ...(detailRow.detail || {}), ...provisioning.normalizeProjectDetail(patch.detail) };
   }
+  // `modules` REPLACES and is normalized on the way in — the real statement's
+  // `modules = $n::jsonb` over normalizeModuleSelection (BV1.R23, task 1002342).
+  // A stub that merged would hide the removal half of "add modules later".
+  if (patch.modules !== undefined) lastUpdatedRow.modules = normalizeModuleSelection(patch.modules);
   return lastUpdatedRow;
 };
 
@@ -286,8 +291,9 @@ await ta('POST /instances: modules must be an array of strings', async () => {
 });
 
 await ta('POST /instances: a re-request never changes an existing project\'s modules — and SAYS so', async () => {
-  // Same honesty as type_ignored (task 1002772). There is no mutation route yet
-  // (R23, task 1002342 is "add modules later"), so the receipt does not name one.
+  // Same honesty as detail_ignored (task 1002334): since BV1.R23 (task 1002342)
+  // there IS a way back, so the receipt names it rather than leaving the owner
+  // to hunt for one.
   existingRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['agents'], detail: {} };
   const res = await post('/provisioning/instances', {
     slug: 'mercury', hosting_shape: 'standalone', modules: ['discord'],
@@ -295,6 +301,7 @@ await ta('POST /instances: a re-request never changes an existing project\'s mod
   assert.equal(res.status, 200, res.raw);
   assert.ok(res.body.modules_ignored, 'the dropped answer is reported, not swallowed');
   assert.match(res.body.modules_ignored.hint, /never changes/);
+  assert.match(res.body.modules_ignored.hint, /\/detail/, 'and names the route that does change it');
   assert.deepEqual(res.body.instance.modules.selected, ['agents'], 'and the stored answer is what reads back');
   existingRow = null;
 });
@@ -341,6 +348,160 @@ await ta('PATCH /detail: a description-only patch answers with modules too — t
   detailRow = null; lastUpdatedRow = null;
 });
 
+// ── Adding (and removing) a module AFTER creation ──────────────────────────
+// BV1.R23, task 1002342, ADR 0244. The picker is optional at creation, and an
+// optional step is only a default rather than a dead end if there is a way back
+// — the same argument that made PATCH …/detail exist for the About step beside
+// it. So the way back is that route's `modules` key, not a new endpoint: the
+// same platform row, the same ownership gate, the same receipt.
+
+await ta('PATCH /detail: an owner who skipped the picker can add one module later', async () => {
+  // Arrange — a game project that skipped: the column is NULL and the read
+  // resolves the type's bundle.
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: null, detail: {} };
+  lastUpdatedRow = null;
+  const before = effectiveModules(detailRow);
+  assert.equal(before.source, 'bundle', 'the fixture really is an unanswered project');
+
+  // Act — the owner adds `agents` on top of what the bundle gave them
+  const res = await patch('/provisioning/instances/41/detail', {
+    modules: before.selected.concat(['agents']),
+  });
+
+  // Assert — stored, and the read-back is the answer rather than the bundle
+  assert.equal(res.status, 200, res.raw);
+  assert.ok(lastUpdatedRow, 'the route ran the update');
+  assert.deepEqual(lastUpdatedRow.modules, normalizeModuleSelection(before.selected.concat(['agents'])),
+    'in catalog order, exactly as the creation write stores it');
+  assert.ok(res.body.modules.selected.includes('agents'), 'the added module is there');
+  assert.equal(res.body.modules.source, 'chosen', 'an answered project is no longer reading the bundle');
+  assert.deepEqual(res.body.modules, effectiveModules(lastUpdatedRow), 'the reply is the POST-patch resolution');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: a module can be REMOVED later too — the list replaces, it never merges', async () => {
+  // The half a merging write would make impossible, which is why
+  // updateInstanceDetail replaces `modules` and merges `detail`.
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['dev-box', 'discord'], detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: ['discord'] });
+
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(lastUpdatedRow.modules, ['discord']);
+  assert.deepEqual(res.body.modules.selected, ['discord'], 'dev-box is gone, not still merged in');
+  assert.equal(res.body.modules.source, 'chosen');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: switching them all off later is an answer, and it stays off', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['discord'], detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: [] });
+
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(lastUpdatedRow.modules, [], 'an empty answer is stored as one, never as NULL');
+  assert.deepEqual(res.body.modules.selected, []);
+  assert.equal(res.body.modules.source, 'chosen', 'a project that switched the bundle off does not get it back');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: the always-on core cannot be removed — it was never on the list', async () => {
+  // Two guards, both pinned: the route REFUSES a core key by name, and the read
+  // re-adds the whole core regardless of what was stored.
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['discord'], detail: {} };
+  lastUpdatedRow = null;
+
+  const refused = await patch('/provisioning/instances/41/detail', { modules: ['memory'] });
+  assert.equal(refused.status, 400, refused.raw);
+  assert.equal(refused.body.error.code, 'bad_modules');
+  assert.match(refused.body.error.message, /always on/i);
+  assert.equal(lastUpdatedRow, null, 'a refused write touches nothing');
+
+  const emptied = await patch('/provisioning/instances/41/detail', { modules: [] });
+  assert.deepEqual(emptied.body.modules.core, [...ALWAYS_ON_CORE], 'the core rides every read');
+  assert.deepEqual(emptied.body.modules.modules, [...ALWAYS_ON_CORE], 'and every project still has it');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: an unknown module is refused and NAMED, exactly as at creation', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: null, detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: ['discrod'] });
+
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_modules');
+  assert.match(res.body.error.message, /discrod/, 'the message names what was wrong');
+  assert.match(res.body.error.message, /agents/, 'and what the choices are');
+  assert.equal(lastUpdatedRow, null);
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: modules must be an array of strings here too', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: null, detail: {} };
+  const notArray = await patch('/provisioning/instances/41/detail', { modules: 'discord' });
+  assert.equal(notArray.status, 400, notArray.raw);
+  assert.equal(notArray.body.error.code, 'validation_failed');
+
+  const notStrings = await patch('/provisioning/instances/41/detail', { modules: [7] });
+  assert.equal(notStrings.status, 400, notStrings.raw);
+  assert.equal(notStrings.body.error.code, 'validation_failed');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: a modules-only body is a real change, not an empty one', async () => {
+  // The "nothing to change" guard predates this key; a body carrying only
+  // modules must not be turned away by it.
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: null, detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: ['agents'] });
+
+  assert.equal(res.status, 200, res.raw);
+  assert.ok(lastUpdatedRow, 'the update ran off modules alone');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: null modules cannot UN-ASK the question — the skip state is not writable', async () => {
+  // ADR 0240 §2's three-valued contract: NULL means "nobody answered". A later
+  // edit that could write NULL back would make a project that HAD answered
+  // indistinguishable from one that never was, permanently.
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['discord'], detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: null, description: 'Still here.' });
+
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(lastUpdatedRow.modules, ['discord'], 'the stored answer is untouched');
+  assert.equal(res.body.modules.source, 'chosen');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: a body with only a null modules key is still nothing to change', async () => {
+  detailRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: null, detail: {} };
+  const res = await patch('/provisioning/instances/41/detail', { modules: null });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_detail');
+  assert.match(res.body.error.message, /modules/, 'and the message names the third thing it accepts');
+  detailRow = null; lastUpdatedRow = null;
+});
+
+await ta('PATCH /detail: another builder’s project is a 404, not a module change', async () => {
+  // The ownership wall is instanceAccessDenied's, shared with every sibling
+  // route — pinned here because this key is new on it.
+  detailRow = { id: 41, owner_builder_id: 99, slug: 'not-mine', status: 'active', type: 'game', modules: null, detail: {} };
+  lastUpdatedRow = null;
+
+  const res = await patch('/provisioning/instances/41/detail', { modules: ['agents'] });
+
+  assert.equal(res.status, 404, res.raw);
+  assert.equal(res.body.error.code, 'instance_not_found');
+  assert.equal(lastUpdatedRow, null, 'nothing was written');
+  detailRow = null; lastUpdatedRow = null;
+});
+
 server.close();
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);