@bongos/core 1.19.533 → 1.19.535

package/modules/platform-identity/project-catalog.js

@@ -0,0 +1,202 @@
+// modules/platform-identity/project-catalog.js — CATALOG MEMBERSHIP, split from SSO
+// CREDENTIALS (task 1003576, ADR 0246). How a project the control plane owns gets onto
+// the hub's map at all, and keeps its row current when its owner edits it.
+//
+// THE BUG THIS FILE IS THE ANSWER TO. The owner-facing publish verdict is computed over
+// `provisioning_instances` (the control plane's own row); the public map reads
+// `platform_identity_projects`. The ONLY thing that ever wrote the second from the first
+// was federation — registerClient → upsertProject — which `shouldFederate` refuses for any
+// instance that is not `co-tenant`, and which runs ONCE, at provision time. So a wizard-made
+// (standalone) project was never catalogued at all, and a co-tenant one that answered
+// "tell us about your project" LATER never re-federated. `publishable: true` and an empty
+// map, forever (the BV1.R18 proof, task 1002337 §3).
+//
+// THE SHAPE. The catalog row is a PROJECTION of the provisioning row, re-derived at every
+// write that can change its inputs — not a side effect of standing up a particular hosting
+// shape. Federation mints CREDENTIALS (a secret + a redirect-URI allow-list, so an instance
+// can run the SSO handoff); this mints MEMBERSHIP (a name the map, the invite and the
+// membership directory can resolve). Conflating the two is what made hosting topology decide
+// who is on the map — ADR 0182 D4 says the gate is IDENTITY (a name and a description), and
+// identity has nothing to do with where a project is hosted.
+//
+// A CATALOG-ONLY CLIENT CARRIES NO CREDENTIAL, and that is enforced by the row's own shape
+// rather than by a flag some future caller could forget: `secret_hash = ''` and
+// `redirect_uris = '{}'`. Every SSO leg then refuses it with machinery that already existed —
+// clientSecretValid() fails closed on a secretless client (/sso/token, /sso/membership/check-in,
+// /sso/activity/rollup) and redirectUriAllowed() fails closed on an empty allow-list
+// (/sso/authorize). The ONE leg that checked neither was /sso/device/start, which resolves a
+// client from a typed origin; clientIsCredentialed() below is the guard it now applies.
+// No migration: `secret_hash` is NOT NULL, and '' satisfies NOT NULL while hashing to nothing.
+//
+// TWO CLAIM RULES, because this writes rows keyed on values an owner supplies (a slug, a
+// bring-your-own domain) and neither table proves who owns an origin:
+//   1. THE CLIENT — an existing row is refreshed ONLY when it is uncredentialed. The bridge
+//      can therefore never rewrite a real client's `origin` (which is what binds the CLI
+//      device-mint audience) nor blank its secret. A slug that collides with a credentialed
+//      client is simply not claimed.
+//   2. THE PROJECT — an existing row is refreshed ONLY when its `owner_github_id` already
+//      equals this instance owner's. A NULL owner on either side compares NULL, i.e. not
+//      true, so the hand-seeded catalog rows (owner null) can never be claimed by someone
+//      creating an instance at their address. First INSERT wins and stamps the owner; every
+//      later write must match it.
+// Both are expressed as the ON CONFLICT action's own WHERE, so the check and the write are
+// one statement and there is no read-then-write window to lose.
+//
+// WHAT IS AUTHORITATIVE AND WHAT IS NOT. `description` and `visibility` are written
+// AUTHORITATIVELY (not COALESCEd): clearing a description must take the project OFF the map,
+// and the owner's door must be able to change — a COALESCE is precisely why the catalog kept
+// a NULL description while the owner stared at `publishable: true`. `tagline`, `art_url`,
+// `featured` and `template` are CURATION and are never touched here. `owner_github_id` is
+// ATTRIBUTION, never authority (ADR 0238): ownership stays `provisioning_instances.owner_builder_id`.
+// Proof: ../../tests/project_catalog_bridge.mjs, ../../tests/catalog_only_client.mjs
+'use strict';
+
+const { pool: defaultPool } = require('../../src/module-api');
+const { ORB_BY_STATE, FALLBACK_PROJECT_STATE } = require('./projects-feed');
+
+// The catalog row's operational lifecycle, mirrored from migration 004's CHECK. 'hidden'
+// keeps a reclaimed project out of every listing without deleting its history.
+const CATALOG_STATUSES = Object.freeze(['active', 'hidden']);
+
+// Does this client hold a usable SSO credential? A catalog-only row is stored with an EMPTY
+// secret_hash, so this is the one question that separates "the hub can name this project"
+// from "this project may run the sign-in handoff". Exported because /sso/device/start
+// resolves a client from a typed origin and checks neither the secret nor the redirect
+// allow-list — the other legs fail closed on their own. PURE.
+function clientIsCredentialed(client) {
+  return !!(client && typeof client.secret_hash === 'string' && client.secret_hash.length > 0);
+}
+
+// The entry, normalised to values the two CHECK constraints accept. Both fall back to the
+// CLOSED direction: an unreadable door is anonymous (the feed's own FALLBACK_PROJECT_STATE),
+// and an unreadable lifecycle is hidden. A caller that sends garbage loses visibility, never
+// gains it. PURE.
+function normalizeEntry(entry) {
+  const e = entry || {};
+  const origin = String(e.origin || '').replace(/\/+$/, '');
+  const clientId = String(e.clientId || '');
+  const ownerGithubId = Number(e.ownerGithubId);
+  if (!origin) throw new Error('project-catalog: origin required');
+  if (!clientId) throw new Error('project-catalog: clientId required');
+  // No owner → no claim rule can hold, so the row would be un-refreshable forever. Refuse
+  // to write one rather than strand it (the bridge resolves the owner before calling).
+  if (!Number.isFinite(ownerGithubId) || ownerGithubId <= 0) {
+    throw new Error('project-catalog: ownerGithubId required — the catalog row is un-refreshable without it');
+  }
+  const visibility = Object.prototype.hasOwnProperty.call(ORB_BY_STATE, e.visibility)
+    ? e.visibility : FALLBACK_PROJECT_STATE;
+  const status = CATALOG_STATUSES.includes(e.status) ? e.status : 'hidden';
+  return {
+    origin,
+    clientId,
+    ownerGithubId,
+    name: String(e.name || clientId),
+    description: e.description ? String(e.description) : null,
+    type: e.type ? String(e.type) : null,
+    visibility,
+    status,
+  };
+}
+
+// The catalog-only SSO client — an IDENTITY the invite route and the membership directory can
+// resolve, with no credential attached. The literal '' / '{}' are in the SQL, never bound
+// values, so no caller can hand this function a real secret or an allow-list entry. The
+// ON CONFLICT WHERE is claim rule 1: a credentialed row is left completely alone (its origin
+// binds the CLI mint audience). Returns the row, or null when the client_id is already a real
+// client's. Never touches `status` — a suspended client stays suspended.
+async function upsertCatalogOnlyClient(entry, { pool = defaultPool } = {}) {
+  const e = normalizeEntry(entry);
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_sso_clients
+       (client_id, secret_hash, name, redirect_uris, origin, owner_github_id)
+     VALUES ($1, '', $2, '{}'::text[], $3, $4)
+     ON CONFLICT (client_id) DO UPDATE SET
+       name            = EXCLUDED.name,
+       origin          = EXCLUDED.origin,
+       owner_github_id = EXCLUDED.owner_github_id,
+       updated_at      = now()
+     WHERE platform_identity_sso_clients.secret_hash = ''
+     RETURNING client_id, name, origin, owner_github_id, status`,
+    [e.clientId, e.name, e.origin, e.ownerGithubId],
+  );
+  return rows[0] || null;
+}
+
+// The catalog row itself, keyed on origin. `description` and `visibility` are assigned, not
+// COALESCEd — see the header: a once-at-provision COALESCE is the whole bug. The ON CONFLICT
+// WHERE is claim rule 2 (the owner must already match), so an origin someone else's row
+// occupies is refused rather than overwritten. Returns the row, or null when the claim
+// refused. `featured`, `tagline`, `art_url` and `template` are curation and stay untouched.
+async function upsertOwnedProject(entry, { pool = defaultPool } = {}) {
+  const e = normalizeEntry(entry);
+  const { rows } = await pool.query(
+    `INSERT INTO platform_identity_projects
+       (origin, name, description, owner_github_id, type, visibility, status)
+     VALUES ($1, $2, $3, $4, $5, $6, $7)
+     ON CONFLICT (origin) DO UPDATE SET
+       name        = EXCLUDED.name,
+       description = EXCLUDED.description,
+       visibility  = EXCLUDED.visibility,
+       status      = EXCLUDED.status,
+       type        = COALESCE(EXCLUDED.type, platform_identity_projects.type),
+       updated_at  = now()
+     WHERE platform_identity_projects.owner_github_id = EXCLUDED.owner_github_id
+     RETURNING id, origin, name, description, owner_github_id, type, status, featured, visibility`,
+    [e.origin, e.name, e.description, e.ownerGithubId, e.type, e.visibility, e.status],
+  );
+  return rows[0] || null;
+}
+
+// Take a catalog row OFF the map when its project moved to a different address (the domain
+// re-point, task 1003237): an abandoned origin left `active` would keep drawing an orb that
+// points at a hostname the project no longer answers on — the ADR 0181 §2 leak, in the
+// catalog rather than in DNS. Owner-scoped for the same reason the upsert is, so a re-point
+// can only retire the caller's own row. Returns the retired row or null.
+async function retireOwnedProject({ origin, ownerGithubId }, { pool = defaultPool } = {}) {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  const owner = Number(ownerGithubId);
+  if (!norm || !Number.isFinite(owner) || owner <= 0) return null;
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_projects SET status = 'hidden', updated_at = now()
+      WHERE origin = $1 AND owner_github_id = $2
+      RETURNING id, origin, status`,
+    [norm, owner],
+  );
+  return rows[0] || null;
+}
+
+// ONE control-plane project, projected into the catalog: the identity row first, then the map
+// row, then (on a re-point) the address it left. Both writes are claim-gated, so `claimed`
+// tells the caller whether the map actually carries this project — a false is a refusal, not
+// an error, and the caller decides whether it is worth saying anything about.
+async function publishControlPlaneProject(entry, { retireOrigin = null, pool = defaultPool } = {}) {
+  const e = normalizeEntry(entry);
+  const client = await upsertCatalogOnlyClient(e, { pool });
+  const project = await upsertOwnedProject(e, { pool });
+  let retired = null;
+  if (retireOrigin && String(retireOrigin).replace(/\/+$/, '') !== e.origin) {
+    retired = await retireOwnedProject({ origin: retireOrigin, ownerGithubId: e.ownerGithubId }, { pool });
+  }
+  return { claimed: !!project, client, project, retired };
+}
+
+// The KERNEL SEAM PORT — `project.catalog`, registered by routes/projects.js and declared in
+// module.json. The `project.publishGate` precedent, and for the same reason: provisioning is
+// the plane that OWNS these projects and may not import this module (the ADR 0083 one-way
+// rule), while this module owns the catalog's tables. One definition, reached through the
+// switchboard. `publish` is deliberately the only verb — a consumer maps its own row onto the
+// entry shape, so the catalog never learns another module's schema.
+const projectCatalogPort = Object.freeze({
+  publish: (entry, opts) => publishControlPlaneProject(entry, opts),
+});
+
+module.exports = {
+  CATALOG_STATUSES,
+  clientIsCredentialed,
+  normalizeEntry,
+  upsertCatalogOnlyClient,
+  upsertOwnedProject,
+  retireOwnedProject,
+  publishControlPlaneProject,
+  projectCatalogPort,
+};

package/modules/platform-identity/routes/my-projects.js

@@ -42,13 +42,18 @@ const RELAY_SENTENCE = {
   invite_only: 'This project is invite-only — it doesn’t take requests. Ask its owner for an invite; once invited, sign in to it.',
   open_enrollment: 'This project is open — no request needed. Sign in to it and you’re in.',
   members_only: 'This project is only visible to its members right now, so it can’t take a request from here — ask its owner.',
+  // Dark matter (BV1.R12, task 1002331): the project's own door says it is not
+  // published yet. Relayed as its own outcome rather than left to fall through,
+  // because the fall-through is a 502 "could not be reached" — the exact lie about
+  // someone else's door that ADR 0194 D5 forbids.
+  not_published: 'This project isn’t published yet, so it isn’t taking anyone on. Its owner has to finish setting it up first.',
 };
 function joinRelayOutcome(status, body) {
   const err = (body && body.error) || null;
   const code = err && (err.code || err);
   let outcome;
   if (status >= 200 && status < 300) outcome = 'requested';
-  else if (code === 'invite_only' || code === 'open_enrollment') outcome = code;
+  else if (code === 'invite_only' || code === 'open_enrollment' || code === 'not_published') outcome = code;
   else if (status === 409) outcome = 'already_member';
   else if (status === 401) outcome = 'members_only';
   else return null;
@@ -184,7 +189,7 @@ module.exports = function myProjectsRoutes() {
       }
       if (!outcome) return res.fail('join_relay_failed', { status: 502, message: 'the project could not be reached to request access' });
       // The echo (ADR 0201 D1.3) — written ONLY when the project actually took an
-      // application. 'already_member', the two door refusals and 'members_only'
+      // application. 'already_member', the three door refusals and 'members_only'
       // are not applications and must leave no trace; a re-apply IS one ('requested'
       // covers the project's own already_pending 200, D1.4), and refreshes the date.
       // Best-effort in both directions: a lost echo must never turn a filed

package/modules/platform-identity/routes/projects.js

@@ -21,6 +21,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
+const projectCatalog = require('../project-catalog');
 const projectStats = require('../project-stats');
 
 const { pool, requireBuilder, requirePermission, validateOrRespond, parseId, corsPublicGet } = api;
@@ -41,9 +42,14 @@ function hostOfOrigin(origin) {
 //     catalogued here — ask THIS module's gate whether a project is on the map,
 //     without importing it (the ADR 0083 one-way rule) and without keeping a
 //     second copy of the rule that could drift from publishableSql().
+//   • PROVIDES port `project.catalog` → { publish(entry) } (task 1003576, ADR 0246).
+//     The write half of the same seam: the plane that OWNS a project (provisioning)
+//     projects it into the catalog these tables hold, so getting onto the map stops
+//     depending on whether the project happened to federate as a co-tenant.
 function registerPublishGateSeam() {
   if (api.hasProvider('project.publishGate')) return;
   api.registerProvider('project.publishGate', pi.publishGatePort);
+  api.registerProvider('project.catalog', projectCatalog.projectCatalogPort);
 }
 
 module.exports = function projectsRoutes() {

package/modules/platform-identity/routes/sso.js

@@ -17,6 +17,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
+const projectCatalog = require('../project-catalog');
 const scoutingAuthz = require('../scouting-authz');
 const canonicalProfile = require('../canonical-profile');
 const hubKeys = require('../hub-keys');
@@ -325,8 +326,17 @@ module.exports = function ssoRoutes() {
     try {
       // Resolve the client from the user-typed origin — NOT from any client_id the
       // caller supplies. An unregistered origin has no client → refuse (correct default).
+      //
+      // …and a CATALOG-ONLY client is not a federation partner (task 1003576, ADR 0246).
+      // This is the one SSO leg that checks neither the secret nor the redirect allow-list,
+      // so it is the one that needs the credential asked for explicitly: /sso/token,
+      // /sso/membership/check-in and /sso/activity/rollup already fail closed on a
+      // secretless client (clientSecretValid), and /sso/authorize on an empty allow-list
+      // (redirectUriAllowed). Without this, minting a catalog row for every control-plane
+      // project would hand each of them a device flow nobody registered a credential for.
       const client = await pi.getClientByOrigin(req.body.origin, { pool });
       if (!client || client.status !== 'active') return res.fail('invalid_client', 401);
+      if (!projectCatalog.clientIsCredentialed(client)) return res.fail('invalid_client', 401);
       const out = await hubDevice.startHubGithubDevice(client.client_id);
       res.json(out);
     } catch (err) {

package/modules/provisioning/catalog-bridge.js

@@ -0,0 +1,105 @@
+// modules/provisioning/catalog-bridge.js — the provisioning row → hub catalog projection
+// (task 1003576, ADR 0246). The half of the bridge this module owns: WHAT a control-plane
+// project looks like on the map, and WHEN that picture is re-taken.
+//
+// WHY IT EXISTS. An owner's publish verdict is computed here, over this module's row
+// (`publishVerdict` in routes/provisioning.js). The map is `platform_identity_projects`, a
+// table this module may not touch (ADR 0083's one-way rule). Until this file the ONLY thing
+// that ever carried the first into the second was federation at provision time, gated on
+// `hosting_shape === 'co-tenant'` — so a wizard-made standalone project was never on the map
+// and a co-tenant one that answered later never updated. The projection below is re-taken at
+// every write that can change its inputs (create, the detail answers, the settings door, a
+// re-pointed address), which is the property a once-at-standup write can never have.
+//
+// IT GRANTS NOTHING. The catalog row is attribution (ADR 0238): ownership stays
+// `provisioning_instances.owner_builder_id`, which is what `instanceAccessDenied` already
+// enforces on every route that calls this. The projection carries the owner's github id only
+// so the hub can attribute the row and claim-check its own writes.
+'use strict';
+
+const api = require('../../src/module-api');
+const { effectiveSettings } = require('./provisioning');
+
+const log = api.logger('provisioning');
+
+// The instance states in which the project is being, or has been, reclaimed — the two that
+// map to a HIDDEN catalog row. Every other state is a project that exists: 'requested',
+// 'provisioning' and 'error' are all "the owner is standing this up", and the map is a
+// directory of projects, not an uptime board (an unreachable 'active' instance already stays
+// listed; liveness is an overlay, never a state).
+const CATALOG_HIDDEN_STATES = new Set(['tearing_down', 'torn_down']);
+
+// ONE instance row → the catalog entry, or null when it cannot be catalogued. PURE.
+//
+// Null has exactly two causes, both honest refusals rather than failures:
+//   • NO ADDRESS — the catalog is keyed on `origin`, so a `no_address: true` instance has
+//     nothing to key a row on. That opt-out is a deliberate choice not to have a public
+//     address, and it therefore means not being on the public map.
+//   • NO OWNER GITHUB ID — the hub's claim rule compares owners, so a row written without
+//     one could never be refreshed again. Refusing to write it beats stranding it.
+//
+// The MAPPING is the part this module owns: an instance's `slug` IS its project's name on
+// this plane (the same mapping `publishVerdict` feeds the publish gate) and its `client_id`
+// on the hub (the same one `federateInstance` uses, so a later real federation rotates the
+// SAME row rather than orphaning it). The door comes from `effectiveSettings`, never the raw
+// jsonb, so an off-vocabulary stored value resolves to today's behaviour exactly as it does
+// on every other surface.
+function catalogEntryForInstance(row, { ownerGithubId } = {}) {
+  if (!row || !row.slug || !row.domain) return null;
+  const owner = Number(ownerGithubId);
+  if (!Number.isFinite(owner) || owner <= 0) return null;
+  return {
+    clientId: row.slug,
+    origin: `https://${row.domain}`,
+    name: row.slug,
+    description: row.description || null,
+    type: row.type || null,
+    visibility: effectiveSettings(row).visibility,
+    status: CATALOG_HIDDEN_STATES.has(row.status) ? 'hidden' : 'active',
+    ownerGithubId: owner,
+  };
+}
+
+// The owner's stable GitHub id, for attribution on the catalog row. Reads core's `builders`
+// table directly, which is `federateInstance`'s own precedent for exactly this lookup — a
+// nullable, best-effort field, so a miss must never fail the caller.
+async function ownerGithubIdForInstance(db, row) {
+  if (!row || !row.owner_builder_id) return null;
+  const { rows } = await db.query('SELECT github_id FROM builders WHERE id = $1', [row.owner_builder_id]);
+  return rows[0] ? rows[0].github_id : null;
+}
+
+// Re-take the projection for one instance and hand it to the hub through the `project.catalog`
+// port. `retireOrigin` is the address a re-point moved OFF, so the abandoned row leaves the map
+// with the same call that puts the new one on it.
+//
+// resolveOptional, not resolve, and NOT declared in `consumes` — the publishVerdict precedent:
+// platform-identity is hub-only (`default: false`), so an instance running provisioning without
+// it has no map to be on and the honest result is "not published", never an error.
+//
+// BEST-EFFORT BY CONSTRUCTION. Every caller is a route whose real work — the create, the
+// detail answers, the settings save — is already durably written when this runs. A catalog
+// hiccup must not turn a saved change into a 500, so this never throws; it reports why.
+async function publishInstanceToCatalog(db, row, { retireOrigin = null } = {}) {
+  const catalog = api.resolveOptional('project.catalog');
+  if (!catalog) return { published: false, reason: 'no_catalog' };
+  try {
+    const ownerGithubId = await ownerGithubIdForInstance(db, row);
+    const entry = catalogEntryForInstance(row, { ownerGithubId });
+    if (!entry) return { published: false, reason: row && row.domain ? 'no_owner_identity' : 'no_address' };
+    const out = await catalog.publish(entry, { retireOrigin: retireOrigin ? `https://${retireOrigin}` : null });
+    if (!out.claimed) {
+      log.warn({ slug: row.slug, origin: entry.origin }, 'catalog claim refused — that address is already another project\'s row');
+    }
+    return { published: !!out.claimed, reason: out.claimed ? null : 'origin_held', entry };
+  } catch (err) {
+    log.error({ err: err.message, slug: row && row.slug }, 'catalog projection failed (non-fatal)');
+    return { published: false, reason: 'error' };
+  }
+}
+
+module.exports = {
+  CATALOG_HIDDEN_STATES,
+  catalogEntryForInstance,
+  publishInstanceToCatalog,
+};

package/modules/provisioning/provisioning.js

@@ -136,6 +136,8 @@ const RESTART_SHAPES = new Set(['co-tenant', 'standalone']);
 //   visibility           how the project stands on the PLATFORM's map: named and
 //                        open (public), named and closed (private), or present but
 //                        anonymous (stealth)
+//   join_grant           what a PUBLIC join GRANTS: a look (view), a request the
+//                        owner reviews (apply), or membership itself (full)
 //
 // The name is ADR 0182 D1's deliberate choice — `goals.visibility` established the
 // word and one word across both planes beat an accurate name used in one place —
@@ -148,15 +150,27 @@ const RESTART_SHAPES = new Set(['co-tenant', 'standalone']);
 // so it rides web.env like its two neighbours and a restart applies it. The instance
 // reads it back as `project.visibility` (src/branding.js), which is what lets a later
 // task enforce the door there and report the value to the hub catalog (R08).
+//
+// `join_grant` is the owner's answer to "what does joining my public project GET
+// someone?" (BV1.R12, task 1002331 — the project interview's own words). It is the
+// CEILING on the visibility axis that ADR 0182 D6 says `joinability` may only
+// narrow, and it governs the `public` state alone: `private` and `stealth` set
+// their own ceilings and never consult it. `full` is "this axis narrows nothing",
+// which is why it is the default — DEFAULT_SETTINGS must be today's behaviour, and
+// today a public project runs whatever door its joinability runs. Composed at the
+// door by src/bongos/project-door.js; ADR 0247.
 const SETTINGS_VOCAB = Object.freeze({
   platform_visibility: ['public', 'gated'],
   joinability: ['open', 'apply', 'invite_only'],
   visibility: ['public', 'private', 'stealth'],
+  join_grant: ['view', 'apply', 'full'],
 });
 // Default = today's behavior on every axis, including the join door: ADR 0182's
 // migration gives the hub column the same `public` default, "existing rows keep
 // today's behaviour".
-const DEFAULT_SETTINGS = Object.freeze({ platform_visibility: 'public', joinability: 'apply', visibility: 'public' });
+const DEFAULT_SETTINGS = Object.freeze({
+  platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full',
+});
 
 // The project's PLANET (task 1003347, direction record §16): how the platform
 // DRAWS it on the sky, in the owner's list and on the card — its template
@@ -646,7 +660,14 @@ async function updateInstanceSettings(db, id, patch) {
 // merge. Passing description: null clears it — and un-publishes the project, which
 // is the honest consequence of deleting half the identity gate, not a bug.
 // Undefined leaves the column alone.
-async function updateInstanceDetail(db, id, { description, detail } = {}) {
+//
+// `modules` is the SAME way back for the wizard's other optional step (BV1.R23,
+// task 1002342, ADR 0245). It REPLACES like `description` and unlike `detail`: a
+// module selection is one whole list, so merging would make removing a module
+// impossible — the very half of "add modules later" an owner needs most. Only an
+// array ever reaches here, so the column's NULL ("never asked", ADR 0240 §2)
+// stays reachable only by never answering; no write can un-ask the question.
+async function updateInstanceDetail(db, id, { description, detail, modules } = {}) {
   const sets = ['updated_at = now()'];
   const params = [id];
   if (description !== undefined) {
@@ -657,6 +678,11 @@ async function updateInstanceDetail(db, id, { description, detail } = {}) {
     params.push(JSON.stringify(normalizeProjectDetail(detail)));
     sets.push(`detail = detail || $${params.length}::jsonb`);
   }
+  if (modules !== undefined) {
+    const picked = normalizeModuleSelection(modules);
+    params.push(picked === null ? null : JSON.stringify(picked));
+    sets.push(`modules = $${params.length}::jsonb`);
+  }
   const { rows } = await db.query(
     `UPDATE provisioning_instances SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
     params

package/modules/provisioning/routes/provisioning.js

@@ -42,6 +42,7 @@ const { onboardPlan, stepsForShape } = require('../onboard-plan');
 const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModules, effectiveModules } = require('../starter-bundles');
 const { recommendationsForDetails } = require('../recommendations');
 const { makeAskRateLimiter, clientIp } = require('../rate-limit');
+const catalogBridge = require('../catalog-bridge');
 const { callbackPage } = require('./callback-page');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('provisioning');
@@ -479,6 +480,12 @@ module.exports = function provisioningRoutes() {
           actor: 'api:self',
         }).catch(() => {});
       }
+      // The project joins the hub catalog the moment it EXISTS, not when (or whether) it
+      // later federates as a co-tenant (task 1003576, ADR 0246). It is dark matter until a
+      // description exists — the publish gate alone decides that — but the row has to be
+      // there for the gate to have anything to decide about, and for the wizard's invite
+      // step to have a project to invite into while standup is still running.
+      await catalogBridge.publishInstanceToCatalog(pool, instance).catch(() => {});
       // A re-request cannot change an existing instance's domain — SAY so instead of
       // silently dropping it (task 1002692); the domain route is the real path.
       let domainIgnored;
@@ -520,14 +527,13 @@ 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.
+      // And the same for the picker's module set (task 1002339). Like detail —
+      // and unlike `type` — this one HAS a way back since BV1.R23 (task 1002342),
+      // so the receipt names it instead of leaving the owner to hunt for one.
       let modulesIgnored;
       if (!created && body.modules !== undefined) {
         modulesIgnored = {
-          hint: "a re-request never changes an existing instance's module selection",
+          hint: `a re-request never changes an existing instance's module selection — PATCH /provisioning/instances/${instance.id}/detail with { modules } instead`,
         };
       }
       res.status(created ? 201 : 200).json({
@@ -653,9 +659,9 @@ module.exports = function provisioningRoutes() {
 
   // ── The optional project detail (task 1002334, goal 1000046) ──────────────
   // PATCH /provisioning/instances/:id/detail — answer (or re-answer) the
-  // "tell us about your project" step after creation. Body: any subset of
-  // { description, detail }. rank: any authenticated builder (own resource;
-  // archon may change any — same gate as settings).
+  // wizard's OPTIONAL creation steps after creation. Body: any subset of
+  // { description, detail, modules }. rank: any authenticated builder (own
+  // resource; archon may change any — same gate as settings).
   //
   // THIS ROUTE IS WHAT MAKES THE STEP SKIPPABLE. Skipping at creation leaves the
   // project dark-matter — off the map and un-joinable (ADR 0182 D4) — and that is
@@ -668,19 +674,31 @@ module.exports = function provisioningRoutes() {
   // answers live on the platform row until a catalog row materializes (the
   // provisioning_007 `type` precedent), and R16 (task 1002335) is the surface that
   // reads `description` to compute publishability and name what is still missing.
+  //
+  // `modules` rides the SAME route for the same reason (BV1.R23, task 1002342,
+  // ADR 0245): step 4 of the wizard is skippable exactly as step 3 is, so it needs
+  // the same way back, and it lands on the same platform row under the same
+  // ownership gate. Only an ARRAY is a change — an omitted or null key leaves the
+  // column alone, so the "never asked" NULL (ADR 0240 §2) can never be written by
+  // a later edit. The always-on core stays unremovable by construction:
+  // badModuleSelection refuses its keys and `effectiveModules` re-adds it on read.
   router.patch('/provisioning/instances/:id/detail', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     if (validateOrRespond(req, res, {
       description: { type: 'string', maxLength: provisioning.DESCRIPTION_MAX },
       detail: { type: 'object' },
+      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 });
-    if (body.description === undefined && body.detail === undefined) {
+    const modulesFault = badModuleSelection(body.modules);
+    if (modulesFault) return res.fail(modulesFault.code, { status: 400, message: modulesFault.message });
+    const wantsModules = Array.isArray(body.modules);
+    if (body.description === undefined && body.detail === undefined && !wantsModules) {
       return res.fail('bad_detail', { status: 400,
-        message: 'The body carries nothing to change — send description, detail, or both.' });
+        message: 'The body carries nothing to change — send description, detail, modules, or any mix.' });
     }
     try {
       const inst = await provisioning.getInstanceById(pool, id);
@@ -692,12 +710,18 @@ module.exports = function provisioningRoutes() {
       const patch = {};
       if (body.description !== undefined) patch.description = provisioning.normalizeDescription(body.description);
       if (body.detail !== undefined) patch.detail = body.detail;
+      if (wantsModules) patch.modules = body.modules;
       const updated = await provisioning.updateInstanceDetail(pool, id, patch);
       await provisioning.recordEvent(pool, {
         instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'detail',
         detail: `project detail changed: ${Object.keys(patch).join(', ')}`,
         actor,
       }).catch(() => {});
+      // Re-take the catalog projection (task 1003576, ADR 0246) — this is THE write the
+      // R18 proof caught going nowhere. A description added here has to reach the map, and
+      // one CLEARED here has to leave it, which is why the hub assigns `description`
+      // rather than COALESCEing it.
+      await catalogBridge.publishInstanceToCatalog(pool, updated).catch(() => {});
       res.json({
         ok: true,
         description: updated.description || null,
@@ -809,6 +833,11 @@ module.exports = function provisioningRoutes() {
           detail: `settings changed: ${Object.entries(patch).map(([k, v]) => `${k}=${v}`).join(', ')}`,
           actor,
         }).catch(() => {});
+        // The door the owner just set is what the map draws this project's orb from
+        // (planet / star / black hole), so the catalog projection is re-taken here as well
+        // as on the detail write (task 1003576, ADR 0246). Unlike the push below this
+        // needs no restart and no reachable shape — it is the PLATFORM's own row.
+        await catalogBridge.publishInstanceToCatalog(pool, updated).catch(() => {});
       }
       // The push (task 1003140). The row is now the platform's truth, but a
       // RUNNING instance reads its settings from web.env through a pack memoized
@@ -1054,7 +1083,12 @@ module.exports = function provisioningRoutes() {
       // Record BEFORE enqueueing: the runner reads the row's domain, so the intent
       // must never race ahead of the column it wires. The release queue rides the
       // SAME statement — see updateInstanceDomain.
-      await provisioning.updateInstanceDomain(pool, id, domain, releasing);
+      const rewired = await provisioning.updateInstanceDomain(pool, id, domain, releasing);
+      // The catalog is keyed on ORIGIN, so an address change moves the project's row (task
+      // 1003576, ADR 0246). `retireOrigin` takes the abandoned one off the map in the same
+      // call — a row left `active` at a hostname the project no longer answers on is the
+      // ADR 0181 §2 leak, in the catalog instead of in DNS.
+      await catalogBridge.publishInstanceToCatalog(pool, rewired, { retireOrigin: current }).catch(() => {});
       let queued = false;
       if (inst.status === 'active') {
         const { intent, created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', 'api:self');

package/modules/provisioning/tests/provisioning.mjs

@@ -263,24 +263,27 @@ await ta('recordDnsNote / clearErrorNote are NARROW single-column updates — no
 console.log('\nPer-project settings (task 1003040):');
 
 t('effectiveSettings: defaults for a bare/empty row = today\'s behavior; stored keys overlay; junk falls back', () => {
-  assert.deepEqual(P.effectiveSettings(null), { platform_visibility: 'public', joinability: 'apply', visibility: 'public' });
-  assert.deepEqual(P.effectiveSettings({}), { platform_visibility: 'public', joinability: 'apply', visibility: 'public' });
-  assert.deepEqual(P.effectiveSettings({ settings: {} }), { platform_visibility: 'public', joinability: 'apply', visibility: 'public' });
+  assert.deepEqual(P.effectiveSettings(null), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(P.effectiveSettings({}), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' });
+  assert.deepEqual(P.effectiveSettings({ settings: {} }), { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' });
   assert.deepEqual(
     P.effectiveSettings({ settings: { platform_visibility: 'gated' } }),
-    { platform_visibility: 'gated', joinability: 'apply', visibility: 'public' },
+    { platform_visibility: 'gated', joinability: 'apply', visibility: 'public', join_grant: 'full' },
     'a stored key overlays only itself'
   );
   assert.deepEqual(
-    P.effectiveSettings({ settings: { platform_visibility: 'bogus', joinability: 'invite_only', future_key: 'x', visibility: 'unlisted' } }),
-    { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public' },
+    P.effectiveSettings({ settings: { platform_visibility: 'bogus', joinability: 'invite_only', future_key: 'x', visibility: 'unlisted', join_grant: 'everything' } }),
+    { platform_visibility: 'public', joinability: 'invite_only', visibility: 'public', join_grant: 'full' },
     'off-vocabulary values fall back to the default; unknown keys never leak out'
   );
   assert.deepEqual(P.effectiveSettings({ settings: ['not', 'an', 'object'] }),
-    { platform_visibility: 'public', joinability: 'apply', visibility: 'public' }, 'a non-object settings value reads as defaults');
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full' }, 'a non-object settings value reads as defaults');
   // the join door reads back like any other policy key (task 1002324)
   assert.deepEqual(P.effectiveSettings({ settings: { visibility: 'stealth' } }),
-    { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth' }, 'a stored door overlays only itself');
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'stealth', join_grant: 'full' }, 'a stored door overlays only itself');
+  // what a public join grants is a policy key like any other (task 1002331)
+  assert.deepEqual(P.effectiveSettings({ settings: { join_grant: 'view' } }),
+    { platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'view' }, 'the grant overlays only itself');
 });
 
 t('SETTINGS_VOCAB / DEFAULT_SETTINGS: every default is on its own vocabulary (lockstep guard)', () => {