@bongos/core 1.19.429 → 1.19.431

package/modules/platform-identity/account-visibility.js

@@ -34,6 +34,11 @@
 //   scoutingListableSql                    THE DIRECTORY — numbers AND reach,
 //       the ONE predicate the recruiting directory joins (ADR 0210, task
 //       1002290). Composed, never restated.
+//   recruiterSliverVisibleSql / isRecruiterSliverVisible  THE PRE-ACCEPT
+//       SLIVER — consent AND reach, WITHOUT the existence axis (ADR 0215, task
+//       1002968; privacy spec D3). The one predicate that deliberately does not
+//       floor on accountVisibleSql, because a PRIVATE, discoverable account is
+//       precisely its subject. Composed, never restated.
 //
 // The rollup pair was originally left to "the rollup readers" to apply. Task
 // 1002967 moved it here for the reason this file exists: there are two such
@@ -200,6 +205,46 @@ function scoutingListableSql(alias) {
   return `(${rollupVisibleSql(alias)} AND ${recruiterReachSql(alias)})`;
 }
 
+// recruiterSliverVisibleSql — THE predicate the PRE-ACCEPT recruiter sliver
+// joins: the CONSENT floor AND the reach axis (ADR 0215, privacy spec D3; task
+// 1002968). modules/platform-identity/recruiter-sliver.js is its one reader.
+//
+// WHY IT FLOORS ON CONSENT AND NOT ON EXISTENCE — the one deliberate difference
+// in this file. Every other public answer here ANDs accountVisibleSql, which
+// carries account_visibility = 'public'. This one must not, because the account
+// the D3 sliver EXISTS to serve is the private, explicitly-discoverable one —
+// the privacy spec's D2 "private, discoverable" row. Flooring on the existence
+// axis would empty the sliver of exactly its subject and leave it a redundant,
+// poorer copy of the directory.
+//
+// THAT IS SAFE ONLY BECAUSE THE REACH HALF IS AN EXPLICIT OPT-IN FOR A PRIVATE
+// ACCOUNT. recruiterReachSql is COALESCE(recruiter_discoverable, visibility =
+// 'public'): for a private account the NULL default resolves to FALSE, so a
+// private account reaches this surface only when its owner set the flag to true
+// by hand. Dropping the existence axis therefore widens nothing on its own — it
+// hands the decision to the account, which is what consent means.
+//
+// profile_state = 'active' still floors it, so a PROVISIONAL account is never
+// recruiter-visible (spec D3, said out loud). And this predicate answers only
+// WHO may appear; WHAT appears is the whitelist in recruiter-sliver.js, which
+// shrinks to name-only under hide_stats. Never authority (ADR 0016): being
+// reachable by a recruiter grants the account nothing and costs it nothing.
+function recruiterSliverVisibleSql(alias) {
+  // Validated here as well as in both delegates, for the scoutingListableSql
+  // reason: a security property must not rest on template evaluation order, and
+  // the error should name the function the caller actually called.
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('recruiterSliverVisibleSql: alias must be a bare SQL identifier');
+  }
+  return `(${accountActiveSql(alias)} AND ${recruiterReachSql(alias)})`;
+}
+
+// The JS twin of recruiterSliverVisibleSql, for a reader that already holds the
+// row. Fail-closed on an absent account, like every port above it.
+function isRecruiterSliverVisible(account) {
+  return isAccountActive(account) && isRecruiterDiscoverable(account);
+}
+
 module.exports = {
   isAccountVisible,
   accountVisibleSql,
@@ -211,4 +256,6 @@ module.exports = {
   isRecruiterDiscoverable,
   recruiterReachSql,
   scoutingListableSql,
+  recruiterSliverVisibleSql,
+  isRecruiterSliverVisible,
 };

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

@@ -947,9 +947,9 @@ async function setAccountHideStats({ githubId, githubLogin, displayName, avatarU
 // touches ONLY the flags the caller sent — never identity re-sync, never
 // profile_state (activation stays /sso/authorize's alone, D3), never hide_stats
 // (which keeps its own writer, setAccountHideStats).
-//
-// recruiter_discoverable accepts null on purpose: that is the caller RESETTING
-// the flag to "follow visibility", not an omitted field.
+// recruiter_discoverable accepts null on purpose (the caller RESETTING it to
+// "follow visibility"), and GOING PRIVATE resets it too unless the PATCH names
+// it — a true set while PUBLIC is not consent to be seen once private (ADR 0215).
 async function setAccountPrivacy({ githubId, githubLogin, displayName, avatarUrl, fields = {} }, { pool = defaultPool } = {}) {
   if (!isNumericGithubId(githubId)) return { error: 'no_account' };
   const setVisibility = 'account_visibility' in fields;
@@ -970,7 +970,7 @@ async function setAccountPrivacy({ githubId, githubLogin, displayName, avatarUrl
        account_visibility     = CASE WHEN $7::boolean THEN EXCLUDED.account_visibility
                                      ELSE platform_identity_accounts.account_visibility END,
        recruiter_discoverable = CASE WHEN $8::boolean THEN EXCLUDED.recruiter_discoverable
-                                     ELSE platform_identity_accounts.recruiter_discoverable END,
+                                     WHEN $7::boolean AND EXCLUDED.account_visibility = 'private' THEN NULL ELSE platform_identity_accounts.recruiter_discoverable END,
        updated_at = now()
      RETURNING github_id, github_login, profile_state, hide_stats,
                account_visibility, recruiter_discoverable, handle`,

package/modules/platform-identity/recruiter-sliver.js

@@ -0,0 +1,197 @@
+// modules/platform-identity/recruiter-sliver.js — THE PRE-ACCEPT BOUNDARY: what
+// a recruiter may see of a builder BEFORE that builder has accepted anything
+// (privacy spec D3, owner-signed 2026-08-16; ADR 0215, task 1002968).
+//
+// WHAT IT IS. One bounded projection — handle, display name, avatar, the
+// disciplines union, and a COARSE "active in the last 30 days" boolean — and
+// nothing else. It exists so a recruiter has enough to decide whether to reach
+// out, and so a builder who has decided nothing yet gives up no more than that.
+// Under `hide_stats` the last two drop (they are rollup-derived) and the sliver
+// is NAME-ONLY, exactly as the Settings toggle promises.
+//
+// NEVER IN IT, and each absence is load-bearing rather than an oversight:
+//   credits / works shipped / karma  — the numbers are the post-accept record.
+//   project names / project count    — "the aggregate is not the leak, the name
+//                                       is" (ADR 0171 D6), and a count beside a
+//                                       hidden total is a leak by subtraction,
+//                                       so there is no count either.
+//   last_active as a TIMESTAMP       — the signal is coarse ON PURPOSE; a date
+//                                       is a behavioural trace, a boolean is a
+//                                       yes/no. Only the boolean crosses.
+//   github_id / github_login as FIELDS — neither is a key of the sliver. Note
+//                                       the LIMIT, stated rather than glossed:
+//                                       the avatar D3 grants is GitHub's own URL
+//                                       and embeds the account id verbatim, so
+//                                       granting the avatar grants the id inside
+//                                       it. Recorded in ADR 0215's honest limits
+//                                       and asserted precisely in the proof (the
+//                                       id may ride the avatar and nothing else).
+//   a profile-page link              — spec D3 forbids it outright. The handle
+//                                       is an ADDRESS, not a door: for a private
+//                                       account GET /profiles/:handle joins
+//                                       accountVisibleSql and answers 404, so
+//                                       handing a recruiter the handle hands
+//                                       them no page. That is the whole meaning
+//                                       of "pre-accept": the sliver is the
+//                                       ceiling, not a step toward the rollup.
+//
+// WHY ITS OWN FILE. The spec says "a port beside getPublicProfileExtras", and
+// platform-identity.js sits ON the 1500-line ratchet with no headroom — the
+// account-visibility.js / scouting-authz.js / application-echo.js precedent.
+// Beside in the module, not in the file.
+//
+// WHO MAY READ IT is not this file's question — routes/scouting.js gates the one
+// surface, on the same door the recruiting directory uses. WHO MAY APPEAR IN IT
+// is enforced HERE, in the query, by the shared recruiterSliverVisibleSql:
+// consent (profile_state='active' — a provisional account is never
+// recruiter-visible) AND recruiting reach. Deliberately NOT the existence axis:
+// the private, explicitly-discoverable account is the row D3 exists to serve,
+// and reach for a private account is an opt-IN the owner had to set by hand.
+//
+// NOT AUTHORITY (ADR 0016). Appearing here confers nothing on the builder and
+// buys the recruiter nothing but a name to write to; nothing in this repo reads
+// the sliver to decide anything. The rollup it is derived from is descriptive
+// analytics, and a projection of descriptive data is still descriptive.
+//
+// Fail-closed everywhere: an absent row, an unreachable account, a non-numeric
+// principal and an unusable handle all answer the SAME null, so a caller cannot
+// tell "no such builder" from "not discoverable" (the ADR 0171 D4 rule).
+//
+// tests/recruiter_sliver_boundary.mjs is the proof — a whitelist over the exact
+// key set, planted sentinels asserted absent from the whole response body, and
+// the 404 that shows the boundary holds.
+'use strict';
+
+const pi = require('./platform-identity');
+const { recruiterSliverVisibleSql } = require('./account-visibility');
+
+// The complete, closed key set of a FULL sliver, in the order D3 names them.
+// Exported because the proof asserts against this list rather than a copy of it:
+// a key added to the projection and quietly added to the test's own expectation
+// is the failure mode a whitelist is supposed to make impossible.
+const SLIVER_KEYS = ['handle', 'display_name', 'avatar_url', 'disciplines', 'active_recently'];
+
+// The key set that survives `hide_stats`. The other two are rollup-derived, so
+// hiding the cross-project record hides them too — and they are ABSENT, not
+// null: the sliver does not carry an empty box where a number used to be.
+const SLIVER_KEYS_HIDDEN = ['handle', 'display_name', 'avatar_url'];
+
+// "Recently" is 30 days (spec D3). A named constant because it is a privacy
+// parameter, not a tuning knob — widening it widens what the boolean discloses.
+const ACTIVE_WINDOW_DAYS = 30;
+
+// The two columns a sliver may be addressed BY, as a closed vocabulary. The
+// lookup key is the one thing interpolated into the statement below, so it may
+// never come from a caller's string: a route passes one of these constants or
+// nothing at all (the account-visibility.js alias-guard posture).
+const BY_GITHUB_ID = 'github_id';
+const BY_HANDLE = 'lower(handle)';
+const ADDRESSABLE_BY = [BY_GITHUB_ID, BY_HANDLE];
+
+// readSliverAccount(by, value, { pool }) — the ONE account read behind both
+// entry points: the identity columns of an account that passes the shared
+// pre-accept predicate, or null. `hide_stats` is fetched because it decides the
+// SHAPE of the answer; it never crosses into one.
+async function readSliverAccount(by, value, { pool }) {
+  if (!ADDRESSABLE_BY.includes(by)) {
+    throw new Error('readSliverAccount: unknown lookup column');
+  }
+  const { rows } = await pool.query(
+    `SELECT github_id, handle, display_name, avatar_url, hide_stats
+       FROM platform_identity_accounts
+      WHERE ${recruiterSliverVisibleSql()} AND ${by} = $1
+      LIMIT 1`,
+    [value],
+  );
+  return rows[0] || null;
+}
+
+// readSliverActivity(githubId, { pool }) — the rollup-derived half: the
+// disciplines union across every project, and whether ANY of them saw activity
+// inside the window. Aggregated over the UN-FANNED activity table with the
+// disciplines union computed separately, mirroring getRollupForBuilder (the
+// pre-GROUP-BY unnest fan-out was bug task 1002911).
+//
+// The comparison happens in SQL and only its BOOLEAN comes back — the timestamp
+// never enters this process, so no later refactor can accidentally serialize it.
+// A builder with no activity rows at all yields NULL, coerced to false by the
+// caller: "not known to be active" and "not active" are the same answer here.
+async function readSliverActivity(githubId, { pool }) {
+  const { rows } = await pool.query(
+    `WITH act AS (
+       SELECT max(a.last_active) AS last_active
+         FROM platform_identity_builder_project_activity a
+        WHERE a.github_id = $1
+     ), disc AS (
+       SELECT array_agg(DISTINCT x.d) AS disciplines
+         FROM (SELECT unnest(a.disciplines) AS d
+                 FROM platform_identity_builder_project_activity a
+                WHERE a.github_id = $1) x
+        WHERE x.d IS NOT NULL
+     )
+     SELECT (act.last_active > now() - make_interval(days => $2::int)) AS active_recently,
+            disc.disciplines
+       FROM act LEFT JOIN disc ON true`,
+    [githubId, ACTIVE_WINDOW_DAYS],
+  );
+  return rows[0] || null;
+}
+
+// projectSliver(account, activity) — the WHITELIST, built literally. Every key
+// is written out by hand; no row is ever spread, so a column added to either
+// query cannot ride along into a response. `activity` is null for a hidden
+// account, and the two rollup-derived keys are then absent entirely.
+function projectSliver(account, activity) {
+  const sliver = {
+    handle: account.handle ?? null,
+    display_name: account.display_name ?? null,
+    avatar_url: account.avatar_url ?? null,
+  };
+  if (!activity) return sliver;
+  return {
+    ...sliver,
+    disciplines: Array.isArray(activity.disciplines) ? activity.disciplines : [],
+    active_recently: activity.active_recently === true,
+  };
+}
+
+// sliverFor(account, { pool }) — shared tail of both entry points: decide the
+// shape, and for a hidden account DO NOT ISSUE the activity read at all. Not
+// merely dropping the fields after fetching them is the point — the cheapest way
+// for a future edit to leak a number is for the number to already be in hand.
+async function sliverFor(account, { pool }) {
+  if (!account) return null;
+  if (account.hide_stats) return projectSliver(account, null);
+  return projectSliver(account, await readSliverActivity(account.github_id, { pool }));
+}
+
+// getRecruiterSliver(githubId) — THE port the spec names (D3), keyed by the hub
+// account id. Null unless the account consents and is recruiter-reachable.
+// A non-numeric principal (core's 'system:bfg' shape) answers null rather than
+// throwing a bigint cast mid-request, like every other read in this module.
+async function getRecruiterSliver(githubId, { pool } = {}) {
+  if (!pi.isNumericGithubId(githubId)) return null;
+  return sliverFor(await readSliverAccount(BY_GITHUB_ID, String(githubId), { pool }), { pool });
+}
+
+// getRecruiterSliverByHandle(handle) — the same answer, addressed the way the
+// platform addresses a builder publicly (spec Decision 3). An unusable handle
+// answers null without a query.
+//
+// A PREVIOUS handle is deliberately NOT resolved here, unlike resolveHandle: the
+// public page answers 301 so a shared link survives a rename, and a recruiting
+// read has no shared links to keep working. Answering 404 instead of a redirect
+// also keeps this surface from confirming that a rename happened.
+async function getRecruiterSliverByHandle(handle, { pool } = {}) {
+  const norm = pi.normalizeHandle(handle);
+  if (!norm) return null;
+  return sliverFor(await readSliverAccount(BY_HANDLE, norm, { pool }), { pool });
+}
+
+module.exports = {
+  SLIVER_KEYS,
+  SLIVER_KEYS_HIDDEN,
+  ACTIVE_WINDOW_DAYS,
+  getRecruiterSliver,
+  getRecruiterSliverByHandle,
+};

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/scouting.js

@@ -16,6 +16,19 @@
 // surface honors both the hide flag and the recruiting opt-out by construction,
 // and widening WHO may read it could not widen WHAT is shown.
 //
+// TWO READS, TWO AUDIENCES — and the difference is the point (ADR 0215 D4, task
+// 1002968). `GET /scouting` is the DIRECTORY: the full rollup for builders who
+// are publicly visible, unhidden and reachable, read by a `project.curate` holder
+// OR a project owner. `GET /scouting/:handle` is the PRE-ACCEPT SLIVER: a bounded
+// projection (name, avatar, disciplines, a coarse activity boolean) of ONE
+// builder — including the private-but-discoverable account the directory
+// deliberately omits — and it is gated at the ARCHON floor, because it is the
+// first surface here that discloses a private account and privacy spec D3 pins it
+// to an archon-floor atom that has not been minted. Sharing one gate would have
+// been tidier; it would also have widened an owner-signed privacy decision by
+// implementation convenience. The blocker on the route below asks the owner
+// whether the wider recruiting audience is authorized.
+//
 // Reaches core only through the doorway (ADR 0083).
 'use strict';
 
@@ -23,6 +36,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const scoutingAuthz = require('../scouting-authz');
+const recruiterSliver = require('../recruiter-sliver');
 
 const { pool, requireBuilder, parsePagination } = api;
 
@@ -64,6 +78,10 @@ module.exports = function scoutingRoutes() {
       const { limit } = parsePagination(req, { defaultLimit: 100, maxLimit: 500 });
       try {
         const builders = await pi.listScoutingRollup({ limit, pool });
+        // Same rollup-derived data as the sliver, so the same rule: hide and the
+        // recruiting opt-out must beat any cache (ADR 0171 D5). This route
+        // predates that posture and was the only rollup read still missing it.
+        res.set('Cache-Control', 'no-store');
         res.json({ builders });
       } catch (err) {
         log.error(`GET /scouting failed: ${err && err.message}`);
@@ -72,5 +90,45 @@ module.exports = function scoutingRoutes() {
     },
   );
 
+  // rank: archon — the PRE-ACCEPT SLIVER for ONE builder (privacy spec D3, ADR
+  // 0215 D4, task 1002968). This is the FIRST surface on the platform that
+  // discloses a PRIVATE account, and its audience is deliberately NOT the
+  // directory's.
+  //
+  // WHY A RANK GATE AND NOT THE RECRUITING DOOR ABOVE. Spec D3 gates this read on
+  // `project.recruit`, an atom whose declared shape is FLOOR ARCHON, widenable
+  // per instance (spec D1). That atom does not exist — ADR 0201 D3 and ADR 0210
+  // both refuse to mint it outside the project-admin-console wave that defines it
+  // (spike 1002786 R3), and this task does not either. The directory's door
+  // (`project.curate` at metic, OR any project owner — ADR 0210 D2) is WIDER than
+  // the signed floor on both halves, so adopting it here would widen an
+  // owner-signed privacy decision by implementation convenience. Until the atom
+  // lands, the honest reading of D3 is its floor, held by rank. Whether the wider
+  // recruiting audience is authorized for this surface is the owner's call and is
+  // filed as a blocker, NOT resolved here; when it is answered, this one line
+  // moves and nothing else does.
+  //
+  // 404, never 403, for a builder who is not recruiter-reachable: a 403 would
+  // confirm the handle exists, which is the disclosure the opt-out removes. The
+  // sliver's own predicate does the deciding, inside the module.
+  router.get(
+    '/scouting/:handle',
+    requireBuilder,
+    api.requireRank('archon'),
+    async (req, res) => {
+      try {
+        const sliver = await recruiterSliver.getRecruiterSliverByHandle(req.params.handle, { pool });
+        // The rollup half is live-derived and hide must beat any cache
+        // (ADR 0171 D5) — the /profiles/:handle posture, for the same reason.
+        res.set('Cache-Control', 'no-store');
+        if (!sliver) return res.fail('builder_not_found', 404);
+        res.json({ sliver });
+      } catch (err) {
+        log.error(`GET /scouting/:handle failed: ${err && err.message}`);
+        res.fail('sliver_read_failed', { status: 500, message: 'internal error' });
+      }
+    },
+  );
+
   return router;
 };

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' });