@bongos/core 1.19.428 → 1.19.430

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

@@ -0,0 +1,137 @@
+// modules/hall-ui/public/profile-canonical.js — the canonical-profile wiring on
+// the hall's profile page (P08, task 1002804; ADR 0214, ADR 0171 D1,
+// profile-page spec Decision 1).
+//
+// ONE ANSWER, THREE BEHAVIOURS. A builder has exactly one canonical public
+// profile, at <hub>/u/<handle>. What this page does about that depends on which
+// instance is serving it, and the two cases are opposites:
+//
+//   * THE HUB serves the same person's canonical page itself, from the same
+//     database. Two URLs for one page on one host is the duplication Decision 1
+//     exists to end, so the numeric ?id= form REDIRECTS to the handle URL.
+//   * A FEDERATED INSTANCE shows its OWN rank, works and achievements here —
+//     genuinely different content — so it must not redirect. It stays the local
+//     view, declares the hub page canonical, and LINKS OUT to the cross-project
+//     record rather than inlining numbers it would have to keep fresh
+//     (ADR 0171 D1: an instance-side copy is stale the moment a builder hides).
+//   * A VANILLA INSTANCE has no hub. Nothing here does anything.
+//
+// A page cannot both redirect to a URL and declare it canonical, and it does not
+// have to: those are two different instances.
+//
+// IT IS ALL DARK TODAY, ON PURPOSE. `/u/<handle>` does not exist yet — the page
+// is goal 1000048 R14, and the ADR that fixes its PATH (R01) is unwritten. A
+// rel=canonical naming a 404 consolidates nothing and risks the one page that
+// works, so CANONICAL_PROFILE_PAGE_LIVE is false and every branch below is a
+// no-op. ADR 0214 D1 carries the argument.
+//
+// NOTHING HERE IS AUTHORITY (ADR 0016): a canonical URL is an address, never a
+// grant. And nothing here decides who is visible — the server already did that
+// by omitting `handle` for an account that is absent, provisional or private,
+// identically in all three cases (ADR 0214 D5).
+
+(() => {
+  'use strict';
+
+  // BOUNDARY-FORCED DUPLICATION (the ADR 0091 §2 pattern, as
+  // platform-identity.js already does for the display-name cap): a browser
+  // script cannot require modules/platform-identity/canonical-profile.js, so the
+  // two constants below MIRROR it. tests/canonical_profile_url.mjs reads both
+  // files and fails if they ever disagree, which is what keeps this a mirror
+  // rather than a second opinion. Flip the module's copy and this one together.
+  const CANONICAL_PROFILE_PAGE_LIVE = false;
+  const CANONICAL_PROFILE_PREFIX = '/u/';
+
+  // Same charset the module re-checks: a handle is about to be interpolated into
+  // an href and a <link rel=canonical>, so it is validated here too rather than
+  // trusted because it arrived over the wire.
+  const HANDLE_RE = /^[a-z0-9-]{1,39}$/;
+
+  // The hub apex, stamped server-side into a <meta> (never a script global, and
+  // never straight into an href — an empty value in an href would silently
+  // become a same-host relative URL claiming to be the hub). Absent or empty
+  // means "no hub", and every branch below then does nothing.
+  function hubOrigin() {
+    const meta = document.querySelector('meta[name="hub-origin"]');
+    const raw = ((meta && meta.getAttribute('content')) || '').trim().replace(/\/+$/, '');
+    if (!raw) return null;
+    // Bare https origin only — a canonical must never name a downgraded scheme,
+    // and a value carrying a path is not an origin.
+    try {
+      const url = new URL(raw);
+      if (url.protocol !== 'https:' || url.username || url.password) return null;
+      if (url.pathname !== '/' || url.search || url.hash) return null;
+      return url.origin;
+    } catch (err) { return null; }
+  }
+
+  // The canonical public profile URL, or null when we must not point anywhere:
+  // the page is not live, no hub is known, or the account has no public handle
+  // (absent / provisional / private — indistinguishable by design).
+  function canonicalProfileUrl(handle) {
+    if (!CANONICAL_PROFILE_PAGE_LIVE) return null;
+    const origin = hubOrigin();
+    if (!origin) return null;
+    const h = String(handle == null ? '' : handle).trim().toLowerCase();
+    if (!HANDLE_RE.test(h)) return null;
+    return `${origin}${CANONICAL_PROFILE_PREFIX}${h}`;
+  }
+
+  // "Am I the hub?" — the enabled-module set the server injects. `platform-
+  // identity` IS the hub flag rather than a proxy for it (src/platform-server.js
+  // says so), so this asks the instance what it is and nothing has to know the
+  // platform's hostname.
+  function isHub() {
+    const mods = window.__MODULES__;
+    return Array.isArray(mods) ? mods.includes('platform-identity') : !!(mods && mods['platform-identity']);
+  }
+
+  function setCanonicalLink(url) {
+    let link = document.querySelector('link[rel="canonical"]');
+    if (!link) {
+      link = document.createElement('link');
+      link.setAttribute('rel', 'canonical');
+      document.head.appendChild(link);
+    }
+    link.setAttribute('href', url);
+  }
+
+  // The visible link-out — ADR 0171 D1's federated render path. It reuses the
+  // page's existing cross-project section, which on a federated instance is
+  // empty and hidden (the response carries no cross_project key there), so the
+  // heading a reader already understands gets the link instead of numbers.
+  function renderLinkOut(url) {
+    const section = document.getElementById('xp-scroll');
+    const body = document.getElementById('xp-body');
+    if (!section || !body) return;
+    // Defence in depth, and honestly UNOBSERVABLE today: canonicalProfileUrl has
+    // already refused anything outside `https://<bare origin>/u/[a-z0-9-]{1,39}`,
+    // so no value reaching here can contain a character this changes. It is the
+    // second wall for the day someone loosens the handle charset — a mutation
+    // test cannot make it bite, and that is the point rather than a gap.
+    const escapeHtml = (window.OTB && window.OTB.escapeHtml) || ((s) => String(s));
+    body.innerHTML = `<p class="scroll__lede">This builder's work spans more than this project. `
+      + `<a href="${escapeHtml(url)}" rel="noopener">See the cross-project record</a>.</p>`;
+    section.hidden = false;
+  }
+
+  // render(data) — called by profile.js once the profile response is in hand.
+  // `data.handle` is present iff the builder has a PUBLICLY VISIBLE platform
+  // account; absent for no account, provisional and private alike, so nothing
+  // here can tell those apart and neither can a visitor watching it.
+  function render(data) {
+    const url = canonicalProfileUrl(data && data.handle);
+    if (!url) return;
+    if (isHub()) {
+      // The hub's numeric form is an address for a page the hub also serves at
+      // the canonical URL. `replace`, not `assign`: the numeric URL should not
+      // sit in history as a place Back returns to.
+      if (new URLSearchParams(location.search).get('id')) location.replace(url);
+      return;
+    }
+    setCanonicalLink(url);
+    renderLinkOut(url);
+  }
+
+  window.OTBCanonical = { render, canonicalProfileUrl, hubOrigin, isHub };
+})();

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

@@ -45,14 +45,18 @@
 // why `hide_stats` does not suppress it — hiding your stats hides the numbers
 // beside an edge, not the edge itself (ADR 0202 D4 §3).
 //
-// ADDRESSING. The connections API names a counterparty by HANDLE; this page
-// knows only a builder's github_login. It hands that login to
-// GET /connections/degree/:handle, which resolves the current handle or the
-// single previous-handle rename slot and echoes the CANONICAL handle back —
-// and that echoed handle, never the login, is what every write here sends. A
-// login resolving to neither answers 404 and the section stays hidden, the same
-// fail-closed answer a private or provisional account gets. The handle-addressed
-// hub page (/u/<handle>) will not need this hop at all.
+// ADDRESSING. The connections API names a counterparty by HANDLE. Since task
+// 1002804 the profile response carries the canonical `handle` itself (whenever
+// the builder has a publicly visible platform account), so this page addresses
+// by that and the login hop is only the FALLBACK for a server that predates it.
+// That fallback is the one with the hole, and it is why the widening mattered:
+// GET /connections/degree/:handle resolves a login against the current handle or
+// the SINGLE previous-handle rename slot, so a twice-renamed builder matched
+// neither, answered 404, and the section silently never appeared — the honest
+// gap ADR 0212 named and left open. Either way the API echoes the CANONICAL
+// handle back, and that echoed handle, never the login, is what every write here
+// sends. An address resolving to nothing answers 404 and the section stays
+// hidden, the same fail-closed answer a private or provisional account gets.
 
 (() => {
   'use strict';
@@ -288,7 +292,14 @@
     const builder = (data && data.builder) || {};
     const isSelf = selfId != null && String(builder.id) === String(selfId);
     try {
-      const shown = isSelf ? await renderOwn(body) : await renderOther(body, builder.github_login);
+      // Address by the CANONICAL handle when the response carries one (task
+      // 1002804 widened the profile read to include it), and fall back to the
+      // github_login hop for a server that predates that. The fallback is the
+      // thing with the hole: the rename window is a SINGLE previous_handle slot,
+      // so a twice-renamed builder's login matches neither and the section
+      // silently never appears — the honest gap ADR 0212 named and this closes.
+      const address = (data && typeof data.handle === 'string' && data.handle) || builder.github_login;
+      const shown = isSelf ? await renderOwn(body) : await renderOther(body, address);
       section.hidden = !shown;
       if (shown && body.addEventListener && !body.dataset.connWired) {
         body.dataset.connWired = '1';

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

@@ -5,6 +5,11 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Profile — {{worldName}}</title>
   <meta name="description" content="A builder of {{worldName}} — rank, works shipped, standing, and achievements.">
+  <!-- The platform hub's apex, stamped server-side (P08, task 1002804; ADR 0214
+       D2). Empty on a vanilla instance, and profile-canonical.js renders nothing
+       then — a meta, never an href, so an empty value cannot degrade into a
+       same-host URL claiming to be the hub. -->
+  <meta name="hub-origin" content="{{hubOrigin}}">
   <link rel="icon" href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><text x='16' y='24' font-size='24' text-anchor='middle' font-family='sans-serif'>⌂</text></svg>">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
@@ -145,6 +150,10 @@
      exists by the time renderProfile runs; profile.js guards on it anyway, so a
      page that omits this script simply has no connections section. -->
 <script src="/builders/profile-connections.js?v=2026-08-29-r20"></script>
+<!-- Canonical-profile wiring (P08). Loaded BEFORE profile.js so
+     window.OTBCanonical exists when renderProfile runs; profile.js guards on it,
+     so a page that omits this script simply declares no canonical. -->
+<script src="/builders/profile-canonical.js?v=2026-08-29-p08"></script>
 <script src="/builders/profile.js?v=2026-08-27-activity"></script>
 </body>
 </html>

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

@@ -538,6 +538,11 @@
     // reveals its own section or leaves it hidden. Optional by design: a page
     // that does not load it simply has no connections section.
     if (window.OTBConnections) window.OTBConnections.render(data, selfId);
+    // Canonical-profile wiring (P08, task 1002804) — the rel=canonical + the
+    // link-out to the cross-project record on a federated instance, and the
+    // numeric-id redirect on the hub. Optional the same way: a page without the
+    // script declares no canonical rather than breaking.
+    if (window.OTBCanonical) window.OTBCanonical.render(data);
   }
 
   // Render the friendly "no builder chosen" empty state for a signed-out visitor

package/modules/platform-identity/canonical-profile.js

@@ -0,0 +1,143 @@
+// modules/platform-identity/canonical-profile.js — THE one answer to "where
+// does this builder's canonical public profile live, and is it safe to point
+// there?" (P08, task 1002804; ADR 0214; profile-page spec Decision 1, ADR 0171
+// D1/D8).
+//
+// WHY ITS OWN FILE. Three surfaces need the same answer — the `rel=canonical`
+// a federated instance emits, the visible "see the cross-project record" link
+// beside it, and the numeric-id redirect the hub performs. Three surfaces each
+// building their own URL is three ways to disagree about where a profile lives
+// and, worse, three independent judgements about whether the target exists yet.
+// One resolver removes both. (platform-identity.js is also at its file-size
+// ratchet with zero headroom, which is why this lands beside it rather than in
+// it — the account-visibility.js precedent.)
+//
+// THE FLAG IS THE POINT. `/u/<handle>` does not exist: the page is goal 1000048
+// R14 (task 1002365, `backlog`), the SEO-namespace ADR that fixes its PATH is
+// R01 (`ready`, unwritten), and R03 in the same goal proposes moving platform
+// pages under /bongos/…. A rel=canonical naming a URL that 404s consolidates
+// nothing — a 404 cannot be indexed — while risking the one page that does
+// work. So the resolver answers null and every consumer renders nothing.
+// ADR 0214 D1 carries the full argument and the flip checklist.
+//
+// Not authority (ADR 0016): a canonical URL is an address, never a grant.
+'use strict';
+
+const { isAccountVisible } = require('./account-visibility');
+
+// The canonical profile namespace on the hub (profile-page spec Decision 1).
+// One spelling, so nothing hardcodes '/u/' a second time.
+const CANONICAL_PROFILE_PREFIX = '/u/';
+
+// FALSE until the page at CANONICAL_PROFILE_PREFIX actually resolves. Flipping
+// this turns on the canonical link, the link-out and the numeric-id redirect
+// together, everywhere, at once — which is exactly why it is one boolean and
+// not three.
+//
+// Flip it only when ALL FOUR hold (ADR 0214 D1):
+//   1. goal 1000048 R14 (task 1002365) serves the page at this path;
+//   2. R01 has ratified that path — R03 may still move platform pages;
+//   3. the page answers 404, never 403, for absent / provisional / private,
+//      matching GET /profiles/:handle;
+//   4. P09's noindex-until-first-ship is in place, so flipping does not publish
+//      a farm of empty profiles.
+// tests/canonical_profile_url.mjs fails if a /u/ page route lands in the tree
+// while this is still false, so the flag cannot silently fall behind the page.
+const CANONICAL_PROFILE_PAGE_LIVE = false;
+
+// A handle is the URL key, so it may only ever be the charset P01 normalizes to
+// (lowercase alnum + hyphen). Re-checked HERE rather than trusted, because this
+// value is about to be interpolated into a URL that goes into an href and a
+// <link rel=canonical>: a resolver that builds URLs should refuse anything it
+// cannot vouch for rather than rely on every future caller having normalized.
+const HANDLE_RE = /^[a-z0-9-]{1,39}$/;
+
+// An origin is only usable as a canonical target if it is a bare https origin —
+// no path, no query, no credentials. http is refused outright: a canonical
+// pointing at a downgraded scheme is a signal we should never emit.
+function normalizeHubOrigin(origin) {
+  const raw = String(origin ?? '').trim().replace(/\/+$/, '');
+  if (!raw) return null;
+  let url;
+  try { url = new URL(raw); } catch { return null; }
+  if (url.protocol !== 'https:') return null;
+  if (url.username || url.password) return null;
+  if (url.pathname !== '/' || url.search || url.hash) return null;
+  return url.origin;
+}
+
+// canonicalProfilePath(handle) — the path half, or null for a handle this
+// resolver will not vouch for. Split out from the URL so the composition rules
+// stay provable while the liveness flag below is false: a gate that short-
+// circuits everything would otherwise leave the interesting logic untested.
+function canonicalProfilePath(handle) {
+  const h = String(handle ?? '').trim().toLowerCase();
+  return HANDLE_RE.test(h) ? `${CANONICAL_PROFILE_PREFIX}${h}` : null;
+}
+
+// canonicalProfileUrl(hubOrigin, handle) — the canonical public profile URL, or
+// null when we must not point anywhere: the page is not live, no hub origin is
+// known (a vanilla instance), the origin is not a bare https origin, or the
+// handle is absent/malformed. EVERY consumer renders nothing on null; none of
+// them may fall back to a guess.
+function canonicalProfileUrl(hubOrigin, handle) {
+  if (!CANONICAL_PROFILE_PAGE_LIVE) return null;
+  const origin = normalizeHubOrigin(hubOrigin);
+  const path = canonicalProfilePath(handle);
+  return origin && path ? `${origin}${path}` : null;
+}
+
+// getPublicHandle(githubId) — the account's PUBLIC handle, or null.
+//
+// Floors on the SHARED existence predicate (isAccountVisible), never a variant:
+// active AND public. Deliberately NOT the rollup predicate — `hide_stats`
+// suppresses NUMBERS and never existence (account-visibility.js; resolveHandle
+// says the same), so a builder who hides their stats still has a public profile
+// at a canonical URL, it just carries no numbers. Gating the handle on
+// hide_stats would deny a canonical URL and a connect button to exactly the
+// people who chose a public profile without public numbers.
+//
+// A null is returned identically for "no account", "provisional" and "private"
+// — the three cases ADR 0171 D2 requires to stay indistinguishable — so a
+// caller can never tell them apart, and neither can anything downstream of one.
+async function getPublicHandle(githubId, { pool }) {
+  if (githubId === null || githubId === undefined) return null;
+  const id = String(githubId);
+  // Non-numeric principals (the `system:*` ids) would blow up the bigint cast;
+  // they have no account, so answer the same null an absent row gets.
+  if (!/^\d+$/.test(id)) return null;
+  // THE ROW CARRIES EVERY COLUMN THE THREE SHARED PREDICATES READ, not just the
+  // ones this function happens to need — the getPublicProfileExtras shape.
+  //
+  // Two different reasons, both learned the hard way:
+  //  * `terms_accepted_at` is REQUIRED. Task 1002913 moved the T&C witness into
+  //    isAccountActive, which isAccountVisible composes from, so a row without
+  //    the column reads as un-consented and this function fail-closes to null
+  //    for EVERYONE. Fail-closed is the safe direction, but it is still broken.
+  //  * `hide_stats` is NOT read here, and is selected anyway so the CHOICE of
+  //    predicate is the only thing deciding the answer. Omit it and
+  //    isAccountVisible and isRollupVisible agree on every row — the predicate
+  //    looks load-bearing while being decorative, and a later swap to the wrong
+  //    one fails OPEN in silence.
+  //
+  // The rule this leaves behind: a reader that applies a shared predicate must
+  // SELECT that predicate's whole column set, or it is deciding on absent data.
+  const { rows } = await pool.query(
+    `SELECT handle, profile_state, account_visibility, terms_accepted_at, hide_stats
+       FROM platform_identity_accounts WHERE github_id = $1::bigint`,
+    [id],
+  );
+  const row = rows[0];
+  if (!isAccountVisible(row)) return null;
+  const handle = String(row.handle ?? '').trim().toLowerCase();
+  return HANDLE_RE.test(handle) ? handle : null;
+}
+
+module.exports = {
+  CANONICAL_PROFILE_PREFIX,
+  CANONICAL_PROFILE_PAGE_LIVE,
+  canonicalProfilePath,
+  canonicalProfileUrl,
+  normalizeHubOrigin,
+  getPublicHandle,
+};

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

@@ -17,6 +17,12 @@ const pi = require('../platform-identity');
 const projectStats = require('../project-stats');
 
 const { pool, requireBuilder, requirePermission, validateOrRespond, parseId, corsPublicGet } = api;
+const log = api.logger('platform-identity');
+
+// a catalog origin's host, the way the hub's sky joins it to an owned instance
+function hostOfOrigin(origin) {
+  try { return new URL(String(origin)).hostname.replace(/^www\./, '').toLowerCase(); } catch { return ''; }
+}
 
 module.exports = function projectsRoutes() {
   const router = express.Router();
@@ -127,6 +133,23 @@ module.exports = function projectsRoutes() {
       } catch (err) {
         console.error('[platform-identity] project stats enrichment failed (non-fatal):', err.message);
       }
+      // The owners' planets (task 1003347): a project's owner may have chosen how
+      // the platform draws it. The choice lives on the provisioning row, so it
+      // reaches this public feed through the `provisioning.projectPlanets` port —
+      // optional, because an instance without that module has no choices to
+      // carry — host-matched, the join the sky makes. Best-effort like the stats:
+      // a failed read leaves every project on the platform's own pick.
+      let planets = {};
+      try {
+        planets = await api.resolveOptional('provisioning.projectPlanets', async () => ({}))(projects.map((p) => hostOfOrigin(p.origin)));
+      } catch (err) {
+        log.warn('project planets enrichment failed (non-fatal):', err.message);
+      }
+      // the wire always carries both keys: null = the platform's own pick
+      const planetOf = (p) => {
+        const c = (planets && planets[hostOfOrigin(p.origin)]) || {};
+        return { planet_template: c.planet_template || null, planet_accent: c.planet_accent || null };
+      };
       // The enrichment's keys (builders, tags, owner, owner_avatar, faces,
       // shipped_30d, shipped_30d_capped, hall_origin) never collide with the
       // catalog's; a project that did not answer carries the ONE shared null
@@ -137,6 +160,7 @@ module.exports = function projectsRoutes() {
           ...p,
           art_url: projectStats.httpUrl(p.art_url, 2048),
           ...(stats[p.origin] || projectStats.NULL_STATS),
+          ...planetOf(p),
         })),
       });
     } catch (err) {

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

@@ -18,6 +18,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const scoutingAuthz = require('../scouting-authz');
+const canonicalProfile = require('../canonical-profile');
 const hubKeys = require('../hub-keys');
 const hubDevice = require('../hub-device');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -120,6 +121,12 @@ function registerSeams() {
       // The ownership fact lives in this module, so the answer does too; core
       // asks through the port and treats an absent one as a denial.
       isProjectOwner: (githubId) => scoutingAuthz.hasOwnerMembership(githubId, { pool }),
+      // task 1002804 (P08, ADR 0214 D3): the account's PUBLIC handle — the
+      // canonical profile address — so the numeric profile route can name a
+      // builder by the rename-proof key instead of a mutable github_login.
+      // Floors on the EXISTENCE predicate, not the rollup one: hide_stats
+      // suppresses numbers, never addressability.
+      getPublicHandle: (githubId) => canonicalProfile.getPublicHandle(githubId, { pool }),
     });
   }
 }

package/modules/provisioning/module.json

@@ -14,6 +14,6 @@
     "migrations": true,
     "pollers": ["liveness-sweep"]
   },
-  "provides": ["provisioning.instanceState"],
+  "provides": ["provisioning.instanceState", "provisioning.projectPlanets"],
   "consumes": []
 }

package/modules/provisioning/provisioning.js

@@ -124,6 +124,26 @@ const SETTINGS_VOCAB = Object.freeze({
 });
 const DEFAULT_SETTINGS = Object.freeze({ platform_visibility: 'public', joinability: 'apply' });
 
+// 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
+// (shape × material × style, the thirty-six names platform-identity's
+// PROJECT_TEMPLATES pins; mirrored here so provisioning never imports the hub's
+// module, the PROJECT_TYPES precedent) and its accent (one of the world's five
+// TOKEN NAMES — a name, never a colour: the Fifteen Rule). Stored in the same
+// jsonb `settings` column, but deliberately NOT in SETTINGS_VOCAB: a setting is a
+// policy the instance obeys (it rides web.env and a restart applies it); the
+// planet is the platform's to draw, so it has no default (null = the platform's
+// own pick: a curated template, else the walk), never rides the env transport,
+// and never restarts anything.
+const PLANET_SHAPES = ['blob', 'pair', 'bead'];
+const PLANET_MATERIALS = ['frost', 'gold', 'obsidian'];
+const PLANET_TEMPLATES = Object.freeze([
+  ...PLANET_SHAPES.flatMap((s) => ['tint', 'wash', 'chrome'].map((y) => `${s}-${y}`)),
+  ...PLANET_SHAPES.flatMap((s) => PLANET_MATERIALS.flatMap((m) => ['tint', 'wash', 'plain'].map((y) => `${s}-${m}-${y}`))),
+]);
+const PLANET_ACCENTS = Object.freeze(['sea', 'terracotta', 'gold-soft', 'sun-lit', 'accent']);
+const PLANET_VOCAB = Object.freeze({ planet_template: PLANET_TEMPLATES, planet_accent: PLANET_ACCENTS });
+
 // The optional project-detail interview (BV1.R15, task 1002334) — the "tell us
 // about your project" step every creation form offers and every owner may skip.
 // The interview asks two things, and the vocabulary is the contract for the
@@ -285,6 +305,10 @@ function publicInstance(row) {
     // instances so a declaration shows before the catalog carries it. Nullable:
     // rows predating provisioning_007, or a declined answer, project null.
     type: row.type || null,
+    // The owner's planet (task 1003347): how the platform draws this project —
+    // null = the platform's own pick. Public by nature (the sky shows it), so
+    // the list and the manage page read it off the row, no second read.
+    ...planetChoice(row),
     // The optional project-detail interview (task 1002334): what the owner said
     // they are building, and the answers that feed R17's recommendations. Both
     // are legitimately empty — the step is skippable by design — and `description`
@@ -366,6 +390,18 @@ function effectiveSettings(row) {
   return out;
 }
 
+// The owner's planet choice as READ (task 1003347): each key its stored
+// on-vocabulary value or null — unset, or a name that has since left the
+// vocabulary, which never leaks. PURE; the shape is constant so a wire never
+// drops a key.
+function planetChoice(row) {
+  const stored = row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings)
+    ? row.settings : {};
+  const out = {};
+  for (const [key, vocab] of Object.entries(PLANET_VOCAB)) out[key] = vocab.includes(stored[key]) ? stored[key] : null;
+  return out;
+}
+
 // A description as it may be STORED: trimmed, collapsed of runaway whitespace,
 // capped, and empty-means-absent. Returns null for anything that isn't real prose,
 // because null is what leaves the project dark-matter — an empty string stored in a
@@ -1033,6 +1069,30 @@ async function instanceStateForSlug(db, slug) {
   };
 }
 
+// The `provisioning.projectPlanets` port (task 1003347): the owners' planet
+// choices for a set of HOSTS (the catalog's origins, host-matched — the join the
+// hub's sky makes), so platform-identity's public featured feed can carry them
+// without importing this module. The newest row per host wins; a host with no
+// row, or no choice, is absent. Read-only.
+async function planetChoicesForHosts(db, hosts) {
+  const wanted = [...new Set((hosts || []).map((h) => String(h || '').toLowerCase()).filter(Boolean))];
+  if (!wanted.length) return {};
+  const { rows } = await db.query(
+    `SELECT lower(domain) AS host, settings
+       FROM provisioning_instances
+      WHERE domain IS NOT NULL AND lower(domain) = ANY($1)
+      ORDER BY updated_at DESC`,
+    [wanted],
+  );
+  const out = {};
+  for (const r of rows) {
+    if (out[r.host]) continue;
+    const choice = planetChoice(r);
+    if (choice.planet_template || choice.planet_accent) out[r.host] = choice;
+  }
+  return out;
+}
+
 // Fleet cost ledger (Archon): per-instance monthly estimate + a total, over the
 // instances that still cost something (not torn_down). VISIBILITY only (ADR 0111 §6).
 async function costLedger(db, { limit = 500 } = {}) {
@@ -1066,9 +1126,10 @@ module.exports = {
   RESTART_FROM, RESTART_SHAPES,
   TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
   SETTINGS_VOCAB, DEFAULT_SETTINGS, PROJECT_DETAIL_VOCAB, DESCRIPTION_MAX,
+  PLANET_TEMPLATES, PLANET_ACCENTS, PLANET_VOCAB,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
-  defaultDomainForSlug, isReservedHostname, effectiveSettings,
+  defaultDomainForSlug, isReservedHostname, effectiveSettings, planetChoice,
   normalizeDescription, normalizeProjectDetail, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
@@ -1080,7 +1141,7 @@ module.exports = {
   createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings, updateInstanceDetail,
   createInstance, setInstanceStatus, updateInstanceDomain, clearReleasedDomains, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, enqueueSettingsApply, enqueueRestart, getOpenIntent, claimNextIntent, resolveIntent,
-  recordEvent, instanceStateForSlug, costLedger,
+  recordEvent, instanceStateForSlug, planetChoicesForHosts, costLedger,
   // data access — GitHub App Manifest attempts (task 2080)
   createOAuthManifest, getOAuthManifestByState, attachManifestCode,
   getLatestOAuthManifestForInstance, claimNextOAuthManifest, resolveOAuthManifest,

package/modules/provisioning/routes/provisioning.js

@@ -253,9 +253,13 @@ function callbackPage({ ok, title, body, state, domain }) {
 //   • PROVIDES port `provisioning.instanceState` (slug) → { status, … } | null.
 //     Lets other code read an instance's provisioning status via
 //     resolveOptional without importing this module (box.hasEverConnected pattern).
+//   • PROVIDES port `provisioning.projectPlanets` (hosts[]) → { host: { planet_template,
+//     planet_accent } } — the owners' planet choices (task 1003347), so the hub's
+//     public featured feed can carry them without importing this module.
 function registerProvisioningSeams() {
   if (api.hasProvider('provisioning.instanceState')) return;
   api.registerProvider('provisioning.instanceState', (slug) => provisioning.instanceStateForSlug(pool, slug));
+  api.registerProvider('provisioning.projectPlanets', (hosts) => provisioning.planetChoicesForHosts(pool, hosts));
 }
 
 // Project an instance row for the fleet view — the owner identity + the same
@@ -764,7 +768,10 @@ module.exports = function provisioningRoutes() {
     try {
       const inst = await provisioning.getInstanceById(pool, id);
       if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
-      res.json({ ok: true, settings: provisioning.effectiveSettings(inst), options: provisioning.SETTINGS_VOCAB });
+      // `planet` rides beside `settings` (task 1003347): the same row, read by a
+      // different rule — no defaults, null = the platform's own pick.
+      res.json({ ok: true, settings: provisioning.effectiveSettings(inst), planet: provisioning.planetChoice(inst),
+        options: { ...provisioning.SETTINGS_VOCAB, ...provisioning.PLANET_VOCAB } });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id/settings', err);
       res.fail('settings_read_failed', { status: 500, message: 'internal error' });
@@ -792,14 +799,18 @@ module.exports = function provisioningRoutes() {
     if (validateOrRespond(req, res, {
       platform_visibility: { type: 'string', enum: provisioning.SETTINGS_VOCAB.platform_visibility },
       joinability: { type: 'string', enum: provisioning.SETTINGS_VOCAB.joinability },
+      // the planet (task 1003347): nullable on purpose — null hands the pick back to the platform
+      planet_template: { type: 'string', enum: provisioning.PLANET_VOCAB.planet_template },
+      planet_accent: { type: 'string', enum: provisioning.PLANET_VOCAB.planet_accent },
     })) return;
+    const settingKeys = [...Object.keys(provisioning.SETTINGS_VOCAB), ...Object.keys(provisioning.PLANET_VOCAB)];
     const patch = {};
-    for (const key of Object.keys(provisioning.SETTINGS_VOCAB)) {
+    for (const key of settingKeys) {
       if ((req.body || {})[key] !== undefined) patch[key] = req.body[key];
     }
     if (!Object.keys(patch).length) {
       return res.fail('bad_settings', { status: 400,
-        message: `The body carries no settings to change — send any of: ${Object.keys(provisioning.SETTINGS_VOCAB).join(', ')}.` });
+        message: `The body carries no settings to change — send any of: ${settingKeys.join(', ')}.` });
     }
     try {
       const inst = await provisioning.getInstanceById(pool, id);
@@ -811,8 +822,17 @@ module.exports = function provisioningRoutes() {
       // whole-form save or a retried request must not bounce a live project. The
       // one exception is the owner re-kick (the domain route's F19 shape): the same
       // values re-sent while a retired push left its error_note re-queue the push.
-      const before = provisioning.effectiveSettings(inst);
+      const before = { ...provisioning.effectiveSettings(inst), ...provisioning.planetChoice(inst) };
       const changed = Object.entries(patch).some(([k, v]) => before[k] !== v);
+      // The planet is the platform's to draw (task 1003347): a change to it
+      // alone is applied the moment it is read back — the sky, the list and the
+      // card repaint from the row — so it queues no push and restarts nothing.
+      // Only a POLICY key (SETTINGS_VOCAB) reaches the instance, and only a
+      // policy key re-sent over a retired push's error_note re-kicks that push.
+      const policyKeys = Object.keys(provisioning.SETTINGS_VOCAB);
+      const policyTouched = policyKeys.some((k) => patch[k] !== undefined);
+      const policyChanged = policyKeys.some((k) => patch[k] !== undefined && before[k] !== patch[k]);
+      const policyResent = !!inst.error_note && policyTouched;
       const updated = changed ? await provisioning.updateInstanceSettings(pool, id, patch) : inst;
       if (changed) {
         await provisioning.recordEvent(pool, {
@@ -834,8 +854,10 @@ module.exports = function provisioningRoutes() {
       const reachable = provisioning.SETTINGS_APPLY_SHAPES.has(inst.hosting_shape);
       const receipt = (fields) => ({ reachable, ...fields });
       let push;
-      if (!changed && !inst.error_note) {
+      if (!changed && !policyResent) {
         push = receipt({ queued: false, restart: false, message: 'No change — this project already has these settings.' });
+      } else if (!policyChanged && !policyResent) {
+        push = receipt({ queued: false, restart: false, message: 'Saved. The sky, your list and the card draw it this way from here; nothing on your project restarts for it.' });
       } else if (!provisioning.SETTINGS_APPLY_FROM.has(inst.status)) {
         const offline = inst.status === 'torn_down' || inst.status === 'tearing_down';
         push = receipt({ queued: false, restart: false, message: offline
@@ -867,7 +889,7 @@ module.exports = function provisioningRoutes() {
             : 'Saved. A restart is already queued for this project and will carry this change.' });
         }
       }
-      res.json({ ok: true, saved: provisioning.effectiveSettings(updated), push });
+      res.json({ ok: true, saved: provisioning.effectiveSettings(updated), planet: provisioning.planetChoice(updated), push });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/settings', err);
       res.fail('settings_update_failed', { status: 500, message: 'internal error' });