@bongos/core 1.20.58 → 1.20.60

package/modules/provisioning/look.js

@@ -0,0 +1,169 @@
+// modules/provisioning/look.js — a project's look, night tint and logo, as the
+// platform stores and pushes them (ADR 0358, task 1004421; spec D2 + D8).
+//
+// `look` and `night_tint` are POLICY settings: they join SETTINGS_VOCAB, ride web.env
+// and a restart applies them, like every other key there (src/hall-look.js reads them
+// on the instance). Their two companions are values, not choices from a list, so they
+// are reserved settings-jsonb keys written only by routes/look.js:
+//
+//   look_accent  a custom look's ONE accent, stored AFTER lookAdjustAccent made it
+//                readable in both modes, so the instance never has to judge it.
+//   logo_url     the content-addressed public address of the stored logo.
+//
+// Neither is in SETTINGS_VOCAB, so the generic settings PATCH cannot write them, and
+// neither leaks through effectiveSettings.
+'use strict';
+
+const crypto = require('node:crypto');
+
+// The style library's looks (modules/ui-design/styles/, ADR 0219) — a test pins this
+// list to the directory — plus `own` (the instance's own pack: today's hall, and the
+// default) and `custom` (one accent over the chrome world).
+const LIBRARY_LOOKS = Object.freeze(['chrome-world', 'expedition', 'grove', 'blueprint']);
+const LOOK_SETTINGS_VOCAB = Object.freeze({
+  look: Object.freeze(['own', ...LIBRARY_LOOKS, 'custom']),
+  night_tint: Object.freeze(['on', 'off']),
+});
+// `own` is today's behaviour. The tint defaults ON (owner D2), and only ever tints a
+// hall that wears a look, so the default changes nothing for a hall that chose none.
+const LOOK_DEFAULTS = Object.freeze({ look: 'own', night_tint: 'on' });
+
+const HEX = /^#[0-9a-f]{6}$/i;
+const LOGO_URL = /^https:\/\/[^\s"'<>()\\]+$/;
+const storedOf = (row) => (row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings) ? row.settings : {});
+const lookAccentOf = (row) => (HEX.test(String(storedOf(row).look_accent || '')) ? String(storedOf(row).look_accent).toLowerCase() : '');
+const logoUrlOf = (row) => (LOGO_URL.test(String(storedOf(row).logo_url || '')) ? String(storedOf(row).logo_url) : '');
+
+// The companion env (SETTINGS_COMPANION_ENV): always emitted, empty meaning none, so a
+// value that came and went never leaves a stale line in a patched web.env.
+const LOOK_COMPANION_ENV = Object.freeze({ LOOK_ACCENT: lookAccentOf, LOGO_URL: logoUrlOf });
+
+// The project's look as the manage page and the wizard read it. PURE.
+function lookChoice(row, effective) {
+  return {
+    look: effective.look,
+    night_tint: effective.night_tint,
+    look_accent: lookAccentOf(row) || null,
+    logo_url: logoUrlOf(row) || null,
+  };
+}
+
+// ONE algorithm, two copies: the create wizard and the manage page carry this exact
+// function (modules/public-landing/public/projects.html), and
+// tests/provisioning_look.mjs pins the two texts equal. The founder picks one colour;
+// it must read in both modes, against everything the hall paints with it:
+//   * the dark ink the hall puts on an accent fill (#2a1305, --accent-on);
+//   * the light mode's derived accent ink (45% accent into #240e00) on the chrome
+//     world's paper and card;
+//   * the accent itself as text on the black grounds and on the tinted ones
+//     (src/night-tint.js, which mixes this same accent in);
+//   * the hall's info chip on the tinted card (--info on --info-weak, both mixed from
+//     the chrome world's sea and that card) — the thinnest pair a tint moves.
+// 4.6 rather than 4.5 leaves rounding room; the info chip is held at exactly 4.5,
+// computed as tests/hall_tokens.mjs computes it, because 4.6 there would move library
+// accents that already pass. A colour that passes comes back as it
+// was; one that fails keeps its hue and saturation and moves to the nearest
+// lightness that passes. null only for a value that is not #rrggbb.
+function lookAdjustAccent(hex) {
+  var m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
+  if (!m) return null;
+  var n = parseInt(m[1], 16);
+  var rgb = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+  function mix(a, p, b) { return [0, 1, 2].map(function (i) { return a[i] * p + b[i] * (1 - p); }); }
+  function lum(c) {
+    var v = c.map(function (x) { x /= 255; return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); });
+    return 0.2126 * v[0] + 0.7152 * v[1] + 0.0722 * v[2];
+  }
+  function ratio(a, b) { var x = lum(a), y = lum(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05); }
+  function reads(c) {
+    var ink = mix(c, 0.45, [36, 14, 0]);
+    var darks = [[0, 0, 0], [16, 16, 18], mix(c, 0.06, [0, 0, 0]), mix(c, 0.05, [16, 16, 18])];
+    var info = mix([91, 111, 208], 0.8, [255, 255, 255]);
+    return ratio([42, 19, 5], c) >= 4.6 && ratio(ink, [237, 236, 238]) >= 4.6 && ratio(ink, [251, 250, 252]) >= 4.6 &&
+      darks.every(function (d) { return ratio(c, d) >= 4.6; }) && ratio(info, mix(info, 0.14, darks[3])) >= 4.5;
+  }
+  function toHex(c) { return '#' + c.map(function (x) { var s = Math.round(x).toString(16); return s.length < 2 ? '0' + s : s; }).join(''); }
+  var r = rgb[0] / 255, g = rgb[1] / 255, b = rgb[2] / 255;
+  var max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2, h = 0, s = 0, d = max - min;
+  if (d) {
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    h = max === r ? (g - b) / d + (g < b ? 6 : 0) : max === g ? (b - r) / d + 2 : (r - g) / d + 4;
+    h /= 6;
+  }
+  function hsl(L) {
+    function f(p, q, t) { t = (t + 1) % 1; return t < 1 / 6 ? p + (q - p) * 6 * t : t < 1 / 2 ? q : t < 2 / 3 ? p + (q - p) * (2 / 3 - t) * 6 : p; }
+    if (!s) return [L * 255, L * 255, L * 255];
+    var q = L < 0.5 ? L * (1 + s) : L + s - L * s, p = 2 * L - q;
+    return [f(p, q, h + 1 / 3) * 255, f(p, q, h) * 255, f(p, q, h - 1 / 3) * 255];
+  }
+  if (reads(rgb)) return { hex: toHex(rgb), adjusted: false };
+  for (var step = 1; step <= 200; step++) {
+    var tries = [l + step / 200, l - step / 200];
+    for (var t = 0; t < 2; t++) {
+      if (tries[t] < 0 || tries[t] > 1) continue;
+      var c = hsl(tries[t]).map(Math.round);
+      if (reads(c)) return { hex: toHex(c), adjusted: true };
+    }
+  }
+  return null;
+}
+
+// ── the logo ────────────────────────────────────────────────────────────────
+// PNG, JPEG or WebP, at most 256 KB, checked by its bytes. Never SVG: an SVG is a
+// document, and a document can carry script. The task-visuals screen
+// (modules/lifecycle/task-visuals.js) is the precedent; this is its narrower cousin.
+const LOGO_MAX_BYTES = 256 * 1024;
+const LOGO_TYPES = Object.freeze({ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' });
+const LOGO_MIME = Object.freeze({ png: 'image/png', jpg: 'image/jpeg', webp: 'image/webp' });
+
+function sniffLogo(buf) {
+  if (!buf || buf.length < 12) return null;
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'png';
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'jpg';
+  if (buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+      buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50) return 'webp';
+  return null;
+}
+
+// { ok:true, ext, mime, sha } or { ok:false, reason, message }. PURE; never throws.
+function screenLogo(buf, contentType) {
+  const declared = LOGO_TYPES[String(contentType || '').split(';')[0].trim().toLowerCase()];
+  if (!declared) return { ok: false, reason: 'bad_type', message: 'A logo must be a PNG, JPEG or WebP image.' };
+  if (!buf || !buf.length) return { ok: false, reason: 'empty', message: 'The image is empty.' };
+  if (buf.length > LOGO_MAX_BYTES) {
+    return { ok: false, reason: 'too_big', message: `The image is ${Math.round(buf.length / 1024)} KB — a logo can be at most ${LOGO_MAX_BYTES / 1024} KB.` };
+  }
+  const ext = sniffLogo(buf);
+  if (ext !== declared) return { ok: false, reason: 'sniff_mismatch', message: 'The file is not really the kind of image it says it is.' };
+  return { ok: true, ext, mime: LOGO_MIME[ext], sha: crypto.createHash('sha256').update(buf).digest('hex') };
+}
+
+// The stored logo's public file name: content-addressed, so the address changes when
+// the image does (no stale cache), is unguessable, and names no project.
+const logoFileName = (sha, ext) => `${sha}.${ext}`;
+const LOGO_FILE = /^([0-9a-f]{64})\.(png|jpg|webp)$/;
+
+// The logo's three statements. The route calls them through this module object, so a
+// test can stand in for the database without one.
+async function upsertLogo(db, instanceId, { sha, ext, mime }, buf) {
+  await db.query(
+    `INSERT INTO provisioning_logos (instance_id, sha256, ext, mime, bytes)
+     VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (instance_id) DO UPDATE
+       SET sha256 = EXCLUDED.sha256, ext = EXCLUDED.ext, mime = EXCLUDED.mime, bytes = EXCLUDED.bytes, updated_at = now()`,
+    [instanceId, sha, ext, mime, buf]);
+}
+async function deleteLogo(db, instanceId) {
+  await db.query('DELETE FROM provisioning_logos WHERE instance_id = $1', [instanceId]);
+}
+async function readLogo(db, sha, ext) {
+  const { rows } = await db.query('SELECT mime, bytes FROM provisioning_logos WHERE sha256 = $1 AND ext = $2 LIMIT 1', [sha, ext]);
+  return rows[0] || null;
+}
+
+module.exports = {
+  upsertLogo, deleteLogo, readLogo,
+  LIBRARY_LOOKS, LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV,
+  lookChoice, lookAdjustAccent, lookAccentOf, logoUrlOf,
+  LOGO_MAX_BYTES, LOGO_MIME, screenLogo, sniffLogo, logoFileName, LOGO_FILE,
+};

package/modules/provisioning/migrations/provisioning_034_project_logo.sql

@@ -0,0 +1,35 @@
+-- provisioning_034_project_logo.sql — a project's logo, kept by the platform
+-- (task 1004421, BV2.PS06; ADR 0358 D6; goal 1000121, spec docs/specs/bongos-v2-project-startup.md).
+--
+-- WHY THIS EXISTS. A founder can give a project a logo at creation, and an existing
+-- project's owner can add one on its manage page (spec D8). The hall shows it in its mark
+-- and uses it as the browser tab's icon, and the hall is a different machine from the
+-- platform — so the platform keeps the image and serves it at a public address the hall
+-- is told (the LOGO_URL setting companion). An instance has no shared disk with the
+-- platform, and the platform's own disk is replaced on every core upgrade, so the bytes
+-- live here.
+--
+-- WHAT IT ADDS. One row per project that has a logo:
+--   instance_id  the project (provisioning_instances.id); deleting the project row drops it.
+--   sha256       hex digest of the bytes. The public address is <sha256>.<ext>, so it is
+--                content-addressed: it changes when the image does, names no project and
+--                cannot be guessed.
+--   ext / mime   png | jpg | webp, from the bytes' own magic number (never SVG, which is a
+--                document that can carry script). The route refuses anything else.
+--   bytes        the image itself, at most 256 KB (enforced by the route).
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS provisioning_logos (
+  instance_id bigint  PRIMARY KEY REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+  sha256      text        NOT NULL,
+  ext         text        NOT NULL CHECK (ext IN ('png', 'jpg', 'webp')),
+  mime        text        NOT NULL,
+  bytes       bytea       NOT NULL,
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS provisioning_logos_sha256 ON provisioning_logos (sha256);
+
+COMMIT;

package/modules/provisioning/module.json

@@ -19,7 +19,8 @@
       "core-upgrade",
       "env-manifest",
       "repo-private",
-      "render-standup"
+      "render-standup",
+      "look"
     ],
     "migrations": true,
     "pollers": [

package/modules/provisioning/provisioning.js

@@ -24,6 +24,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 // projection both have to read them.
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
 const { softLimitsFor } = require('./soft-limits');
+const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look');
 
 // ---------------------------------------------------------------------------
 // Constants (mirror the CHECK constraints in provisioning_001_tables.sql)
@@ -198,7 +199,7 @@ const SETTINGS_VOCAB = Object.freeze({
   visibility: ['public', 'private', 'stealth'],
   join_grant: ['view', 'apply', 'full'],
   artist_gate: ['off', 'advisory', 'strict'],
-  spend_payer: ['none', 'project', 'builder'],
+  spend_payer: ['none', 'project', 'builder'], ...LOOK_SETTINGS_VOCAB, // + the look, ADR 0358 (look.js)
 });
 // 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
@@ -206,7 +207,7 @@ const SETTINGS_VOCAB = Object.freeze({
 // owner's ruling rather than the status quo — see the note above it.
 const DEFAULT_SETTINGS = Object.freeze({
   platform_visibility: 'public', joinability: 'apply', visibility: 'public', join_grant: 'full',
-  artist_gate: 'strict', spend_payer: 'none',
+  artist_gate: 'strict', spend_payer: 'none', ...LOOK_DEFAULTS,
 });
 
 // The project's PLANET (task 1003347, direction record §16): how the platform
@@ -517,7 +518,7 @@ function settingsEnvVars(row, prefix) {
 // cutoff and every unresolved review counts, which is the right answer for a
 // project that has been strict since it stood up.
 const SETTINGS_COMPANION_ENV = Object.freeze({
-  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '',
+  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, // + accent, logo (look.js)
 });
 
 // The web.env block the runner writes at STANDUP (task 1003139): a comment that

package/modules/provisioning/routes/look.js

@@ -0,0 +1,204 @@
+// modules/provisioning/routes/look.js — a project's look, night tint and logo
+// (task 1004421, BV2.PS06; ADR 0358; spec D2 + D8).
+//
+//   GET    /provisioning/instances/:id/look   the look as stored: { look, night_tint, look_accent, logo_url }
+//   PATCH  /provisioning/instances/:id/look   { look?, night_tint?, accent? } — a custom look's accent is
+//                                             nudged until it reads in both modes (lookAdjustAccent) and
+//                                             the reply names the colour actually kept
+//   PUT    /provisioning/instances/:id/logo   { image_b64, content_type } — PNG, JPEG or WebP, ≤256 KB
+//   DELETE /provisioning/instances/:id/logo
+//   GET    /provisioning/logos/:file          the stored image, public and content-addressed
+//
+// The four own-scoped routes are the owner's, with the archon override (the settings
+// route's rule, 404 for anyone else so an id confirms nothing). Every write that changes
+// what the hall wears answers through settings-push.js, exactly as PATCH …/settings
+// does: an ACTIVE project restarts to pick it up, any other state takes it at standup.
+//
+// Its own routes file (declared in module.json) because routes/provisioning.js sits at
+// the size ratchet — the routes/disconnect.js precedent.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const look = require('../look');
+const { settingsPush, failPushConflict } = require('../settings-push');
+const { failFrom } = require('../public-refusal');
+
+const log = api.logger('provisioning');
+
+// The JSON cap for the logo upload: 256 KB decoded is ~342 KB of base64. Two layers,
+// like the task-visual upload: this bounds the ENCODED body, screenLogo the bytes.
+const LOGO_BODY_LIMIT = '400kb';
+const LOGO_B64_MAX = 360 * 1024;
+
+// The platform's own public origin — where the hall is told to fetch the logo. The
+// provisioning front door when there is one, else the platform's public origin (the
+// mothershipOrigin rule in routes/provisioning.js). '' when unconfigured.
+function platformOrigin() {
+  try {
+    const d = api.branding().domains || {};
+    return String(d.provisioningOrigin || d.publicOrigin || '').replace(/\/+$/, '');
+  } catch { return ''; }
+}
+
+async function ownInstance(req, res) {
+  const id = parseId(req, res); // sends 400 bad_id + returns null on failure
+  if (!id) return null;
+  const inst = await provisioning.getInstanceById(pool, id);
+  const isOwner = !!inst && String(inst.owner_builder_id) === String(req.builder.id);
+  if (!inst || (!isOwner && req.builder.rank !== 'archon')) {
+    res.fail('instance_not_found', 404);
+    return null;
+  }
+  return inst;
+}
+
+const actorFor = (inst, builder) => (String(inst.owner_builder_id) === String(builder.id) ? 'api:self' : `api:archon:${builder.id}`);
+const choiceOf = (row) => look.lookChoice(row, provisioning.effectiveSettings(row));
+
+// Write a look change and answer it — the shared tail of PATCH …/look and both logo
+// writes. `stored` is the jsonb patch; `changed` says whether the hall's look moves.
+async function saveAndPush({ req, res, inst, stored, changed, event, extra = {} }) {
+  const id = inst.id;
+  const actor = actorFor(inst, req.builder);
+  const pushOwed = provisioning.settingsPushOwed(inst);
+  // The owner re-kick (the settings route's rule): the same values re-sent over a push
+  // that never got carried, or that ran and failed, queue it again.
+  const policyResent = provisioning.ownsErrorNote(inst, 'settings-apply') || pushOwed;
+  const updated = changed ? await provisioning.updateInstanceSettings(pool, id, stored) : inst;
+  if (changed) {
+    await provisioning.recordEvent(pool, { instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'settings', detail: event, actor }).catch(() => {});
+  }
+  const { push, conflict } = await settingsPush({ pool, provisioning, inst, id, actor, changed, policyChanged: changed,
+    policyResent, pushOwed, log, logTag: `${req.method} ${req.route && req.route.path}` });
+  if (conflict) return failPushConflict(res, conflict);
+  return res.json({ ok: true, look: choiceOf(updated || inst), push, ...extra });
+}
+
+module.exports = function buildLookRouter() {
+  const router = express.Router();
+
+  // GET — rank: any authenticated builder (own resource; archon may read any).
+  router.get('/provisioning/instances/:id/look', api.requireBuilder, async (req, res) => {
+    try {
+      const inst = await ownInstance(req, res);
+      if (!inst) return;
+      res.json({ ok: true, look: choiceOf(inst), options: look.LOOK_SETTINGS_VOCAB, logo_max_bytes: look.LOGO_MAX_BYTES });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/instances/:id/look', err);
+      failFrom(res, err, 'look_read_failed');
+    }
+  });
+
+  // PATCH — rank: any authenticated builder (own resource; archon may change any). A
+  // custom look needs an accent, sent now or already stored; the stored one is the
+  // ADJUSTED colour, and `adjusted` in the reply says when it differs from what came in.
+  router.patch('/provisioning/instances/:id/look', api.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      look: { type: 'string', enum: look.LOOK_SETTINGS_VOCAB.look },
+      night_tint: { type: 'string', enum: look.LOOK_SETTINGS_VOCAB.night_tint },
+      accent: { type: 'string', maxLength: 16 },
+    })) return;
+    const body = req.body || {};
+    if (body.look === undefined && body.night_tint === undefined && body.accent === undefined) {
+      return res.fail('bad_look', { status: 400, message: 'The body carries nothing to change — send any of: look, night_tint, accent.' });
+    }
+    try {
+      const inst = await ownInstance(req, res);
+      if (!inst) return;
+      const before = provisioning.effectiveSettings(inst);
+      const beforeAccent = look.lookAccentOf(inst);
+      const stored = {};
+      if (body.look !== undefined) stored.look = body.look;
+      if (body.night_tint !== undefined) stored.night_tint = body.night_tint;
+      let adjusted = null;
+      if (body.accent !== undefined) {
+        const a = look.lookAdjustAccent(body.accent);
+        if (!a) return res.fail('bad_accent', { status: 400, message: 'An accent is a colour written #rrggbb, for example #b48cf2.' });
+        stored.look_accent = a.hex;
+        if (a.adjusted) adjusted = { from: String(body.accent).trim().toLowerCase(), to: a.hex };
+      }
+      const nextLook = stored.look || before.look;
+      if (nextLook === 'custom' && !(stored.look_accent || beforeAccent)) {
+        return res.fail('accent_required', { status: 400, message: 'Your own look needs an accent colour — send accent as #rrggbb.' });
+      }
+      const changed = Object.entries(stored).some(([k, v]) => (k === 'look_accent' ? beforeAccent !== v : before[k] !== v));
+      const event = `look changed: ${Object.entries(stored).map(([k, v]) => `${k}=${v}`).join(', ')}`;
+      return await saveAndPush({ req, res, inst, stored, changed, event, extra: { adjusted } });
+    } catch (err) {
+      log.error('[provisioning] PATCH /provisioning/instances/:id/look', err);
+      failFrom(res, err, 'look_update_failed');
+    }
+  });
+
+  // PUT …/logo — rank: any authenticated builder (own resource; archon may change any).
+  // The image is screened by its bytes, stored, and the hall told its new address.
+  router.put('/provisioning/instances/:id/logo', api.requireBuilder, express.json({ limit: LOGO_BODY_LIMIT }), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      image_b64: { required: true, type: 'string', minLength: 1, maxLength: LOGO_B64_MAX },
+      content_type: { required: true, type: 'string', minLength: 1, maxLength: 100 },
+    })) return;
+    try {
+      const inst = await ownInstance(req, res);
+      if (!inst) return;
+      // Buffer.from drops what it cannot decode, so a mangled body arrives as wrong
+      // bytes, and the sniff below refuses those.
+      const screened = look.screenLogo(Buffer.from(req.body.image_b64, 'base64'), req.body.content_type);
+      if (!screened.ok) return res.fail(`logo_${screened.reason}`, { status: 400, message: screened.message });
+      const origin = platformOrigin();
+      if (!/^https:\/\//.test(origin)) {
+        return res.fail('logo_unavailable', { status: 409, message: 'This platform has no public https address configured, so a hall could not load the logo from it.' });
+      }
+      const buf = Buffer.from(req.body.image_b64, 'base64');
+      await look.upsertLogo(pool, inst.id, screened, buf);
+      const url = `${origin}/api/bongos/provisioning/logos/${look.logoFileName(screened.sha, screened.ext)}`;
+      const changed = look.logoUrlOf(inst) !== url;
+      return await saveAndPush({ req, res, inst, stored: { logo_url: url }, changed, event: 'logo set' });
+    } catch (err) {
+      log.error('[provisioning] PUT /provisioning/instances/:id/logo', err);
+      failFrom(res, err, 'logo_update_failed');
+    }
+  });
+
+  // DELETE …/logo — rank: any authenticated builder (own resource; archon may change any).
+  router.delete('/provisioning/instances/:id/logo', api.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {})) return;
+    try {
+      const inst = await ownInstance(req, res);
+      if (!inst) return;
+      await look.deleteLogo(pool, inst.id);
+      const had = !!look.logoUrlOf(inst);
+      // An empty string, not a removed key: the merge-only settings write cannot drop a
+      // key, and logoUrlOf reads '' as no logo, so the companion env goes out empty.
+      return await saveAndPush({ req, res, inst, stored: { logo_url: '' }, changed: had, event: 'logo removed' });
+    } catch (err) {
+      log.error('[provisioning] DELETE /provisioning/instances/:id/logo', err);
+      failFrom(res, err, 'logo_update_failed');
+    }
+  });
+
+  // rank: public — a logo is shown on a public hall, and its address is its own sha256,
+  // so it names no project and cannot be guessed. Served as an image only: nosniff, a
+  // sandboxing CSP, and a cache that never goes stale because a new image is a new name.
+  router.get('/provisioning/logos/:file', async (req, res) => {
+    const m = look.LOGO_FILE.exec(String(req.params.file || ''));
+    if (!m) return res.fail('logo_not_found', 404);
+    try {
+      const logo = await look.readLogo(pool, m[1], m[2]);
+      if (!logo) return res.fail('logo_not_found', 404);
+      res.setHeader('Content-Type', look.LOGO_MIME[m[2]]);
+      res.setHeader('X-Content-Type-Options', 'nosniff');
+      res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+      res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+      res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+      res.end(logo.bytes);
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/logos/:file', err);
+      failFrom(res, err, 'logo_read_failed');
+    }
+  });
+
+  return router;
+};

package/modules/provisioning/routes/provisioning.js

@@ -63,6 +63,7 @@ const { callbackPage } = require('./callback-page');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
 const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
+const { settingsPush, failPushConflict } = require('../settings-push');   // a settings save's push + receipt, shared with routes/look.js (task 1004421)
 // the kernel ports this module provides (moved out at the size ratchet, task 1003578)
 const { registerProvisioningSeams } = require('../seams');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
@@ -927,65 +928,10 @@ module.exports = function provisioningRoutes() {
         // 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
-      // for the process lifetime — so an ACTIVE instance on a reachable shape gets
-      // a 'settings-apply' intent (web.env patched in place + RESTART, drained by
-      // the runner; the web tier holds no tokens, ADR 0111 §2). The owner decided
-      // the restart is acceptable and that the surface must SAY so plainly. Every
-      // other state stores the value and says when it takes effect. One receipt
-      // shape on every branch — `restart` = a restart is what applies it,
-      // `reachable` = the platform can perform that restart — and state-only
-      // sentences throughout (the F16 rule): no wall-clock promises.
-      const reachable = provisioning.SETTINGS_APPLY_SHAPES.has(inst.hosting_shape);
-      const receipt = (fields) => ({ reachable, ...fields });
-      let push;
-      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
-          ? 'Saved. This project is offline, so there is nothing to apply it to yet — it takes effect if the project is brought back.'
-          : inst.status === 'error'
-            ? 'Saved. This project’s standup stopped partway, so nothing is applying changes right now — it takes effect the next time the project is stood up.'
-            : 'Saved. It takes effect when the project finishes standing up.' });
-      } else if (!reachable) {
-        // A dedicated droplet has no runner write path — refuse the push honestly
-        // rather than queue one that never lands (the runner refuses it too).
-        push = receipt({ queued: false, restart: true, message:
-          'Saved on the platform. This project runs on a machine the platform doesn’t manage, so it can’t be restarted from here — whoever runs that machine has to apply it there.' });
-      } else {
-        let r = null;
-        try { r = await provisioning.enqueueSettingsApply(pool, id, actor); }
-        catch (err) {
-          // The value IS saved — say so; a 500 here would deny a durable write.
-          log.error('[provisioning] PATCH /provisioning/instances/:id/settings enqueue', err);
-          // The remedy this sentence names has to WORK (task 1003524): nothing is
-          // going to carry the saved value, so record the debt. Best-effort — a failed
-          // marker write must never turn a durable settings write into a 500.
-          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
-          push = receipt({ queued: false, restart: true, message: 'Saved, but the restart could not be queued just now — send it again to apply it.' });
-        }
-        if (r && r.conflict) {
-          // Saved, but the slot is held by work that will not carry this change, so
-          // "send it again once that settles" has to re-queue when they do (task 1003524).
-          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
-          return res.fail('intent_conflict', { status: 409,
-            message: `The change was saved, but a '${r.intent.action}' run is currently ${r.intent.state} for this project — send it again once that settles to apply it.`,
-            details: { action: r.intent.action, state: r.intent.state, recorded: true } });
-        }
-        if (r) {
-          // A push is now in hand — fresh, or a PENDING one that has not read the row
-          // yet — so either way it carries the current settings. Only written when
-          // there IS a debt, so the hot path stays a single UPDATE.
-          if (pushOwed) await provisioning.recordSettingsPushOwed(pool, id, false).catch(() => {});
-          push = receipt({ queued: r.created, restart: true, message: r.created
-            ? 'Saved. Your project will restart to pick this up — until then it keeps its current setting.'
-            : 'Saved. A restart is already queued for this project and will carry this change.' });
-        }
-      }
+      // The push and its receipt (task 1003140) — settings-push.js, shared with PATCH …/look.
+      const { push, conflict } = await settingsPush({ pool, provisioning, inst, id, actor, changed, policyChanged,
+        policyResent, pushOwed, log, logTag: 'PATCH /provisioning/instances/:id/settings' });
+      if (conflict) return failPushConflict(res, conflict);
       res.json({ ok: true, saved: provisioning.effectiveSettings(updated), planet: provisioning.planetChoice(updated), push });
     } catch (err) {
       log.error('[provisioning] PATCH /provisioning/instances/:id/settings', err);

package/modules/provisioning/settings-push.js

@@ -0,0 +1,76 @@
+// modules/provisioning/settings-push.js — after a settings save: queue the push that
+// carries it to a running project, and say what happens next (task 1003140; shared
+// with the look route by task 1004421, ADR 0358).
+//
+// The row is the platform's truth, but a RUNNING instance reads its settings from
+// web.env through a pack memoized for the process lifetime — so an ACTIVE instance on
+// a reachable shape gets a 'settings-apply' intent (web.env patched in place + RESTART,
+// drained by the runner; the web tier holds no tokens, ADR 0111 §2). The owner decided
+// the restart is acceptable and that the surface must SAY so plainly. Every other
+// state stores the value and says when it takes effect. One receipt shape on every
+// branch — `restart` = a restart is what applies it, `reachable` = the platform can
+// perform that restart — and state-only sentences throughout (the F16 rule): no
+// wall-clock promises.
+//
+// Moved out of routes/provisioning.js (at its size ratchet) so PATCH …/settings and
+// PATCH …/look answer from one copy. Returns { push } or { conflict } — the 409 the
+// caller sends when the open slot is held by other work (the change IS saved).
+'use strict';
+
+async function settingsPush({ pool, provisioning, inst, id, actor, changed, policyChanged, policyResent, pushOwed, log, logTag }) {
+  const reachable = provisioning.SETTINGS_APPLY_SHAPES.has(inst.hosting_shape);
+  const receipt = (fields) => ({ reachable, ...fields });
+  if (!changed && !policyResent) {
+    return { push: receipt({ queued: false, restart: false, message: 'No change — this project already has these settings.' }) };
+  }
+  if (!policyChanged && !policyResent) {
+    return { 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.' }) };
+  }
+  if (!provisioning.SETTINGS_APPLY_FROM.has(inst.status)) {
+    const offline = inst.status === 'torn_down' || inst.status === 'tearing_down';
+    return { push: receipt({ queued: false, restart: false, message: offline
+      ? 'Saved. This project is offline, so there is nothing to apply it to yet — it takes effect if the project is brought back.'
+      : inst.status === 'error'
+        ? 'Saved. This project’s standup stopped partway, so nothing is applying changes right now — it takes effect the next time the project is stood up.'
+        : 'Saved. It takes effect when the project finishes standing up.' }) };
+  }
+  if (!reachable) {
+    // A dedicated droplet has no runner write path — refuse the push honestly
+    // rather than queue one that never lands (the runner refuses it too).
+    return { push: receipt({ queued: false, restart: true, message:
+      'Saved on the platform. This project runs on a machine the platform doesn’t manage, so it can’t be restarted from here — whoever runs that machine has to apply it there.' }) };
+  }
+  let r = null;
+  try { r = await provisioning.enqueueSettingsApply(pool, id, actor); }
+  catch (err) {
+    // The value IS saved — say so; a 500 here would deny a durable write.
+    log.error(`[provisioning] ${logTag} enqueue`, err);
+    // The remedy this sentence names has to WORK (task 1003524): nothing is
+    // going to carry the saved value, so record the debt. Best-effort — a failed
+    // marker write must never turn a durable settings write into a 500.
+    await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
+    return { push: receipt({ queued: false, restart: true, message: 'Saved, but the restart could not be queued just now — send it again to apply it.' }) };
+  }
+  if (r && r.conflict) {
+    // Saved, but the slot is held by work that will not carry this change, so
+    // "send it again once that settles" has to re-queue when they do (task 1003524).
+    await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
+    return { conflict: r };
+  }
+  // A push is now in hand — fresh, or a PENDING one that has not read the row
+  // yet — so either way it carries the current settings. Only written when
+  // there IS a debt, so the hot path stays a single UPDATE.
+  if (pushOwed) await provisioning.recordSettingsPushOwed(pool, id, false).catch(() => {});
+  return { push: receipt({ queued: r.created, restart: true, message: r.created
+    ? 'Saved. Your project will restart to pick this up — until then it keeps its current setting.'
+    : 'Saved. A restart is already queued for this project and will carry this change.' }) };
+}
+
+// The 409 a conflicted push answers with — one wording for both routes.
+function failPushConflict(res, r) {
+  return res.fail('intent_conflict', { status: 409,
+    message: `The change was saved, but a '${r.intent.action}' run is currently ${r.intent.state} for this project — send it again once that settles to apply it.`,
+    details: { action: r.intent.action, state: r.intent.state, recorded: true } });
+}
+
+module.exports = { settingsPush, failPushConflict };

package/modules/public-landing/public/assets/cosmos.css

@@ -1603,7 +1603,7 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
 /* the six-step strip as the rail: six hairlines, a 7px dot, one lit step on the
    accent with its halo, the number in the display voice, the name in the label
    face; a step already answered (role=button) stays a way back */
-#view-new .steps{display:grid;grid-template-columns:repeat(8,1fr);gap:0 10px;align-items:start;margin:0 0 40px;}
+#view-new .steps{display:grid;grid-template-columns:repeat(9,1fr);gap:0 10px;align-items:start;margin:0 0 40px;}
 #view-new .steps li{display:block;position:relative;border-top:1px solid var(--rule);padding:12px 0 0;gap:0;}
 #view-new .steps li::before{content:"";position:absolute;top:-4px;left:0;right:auto;width:7px;height:7px;margin:0;border-radius:50%;border:1px solid var(--rule);background:var(--bg);}
 #view-new .steps .snum{display:block;width:auto;height:auto;border:0;border-radius:0;background:none;font-family:var(--font-display);font-weight:300;font-size:22px;letter-spacing:-.02em;line-height:1.1;color:var(--ink-faint);margin-bottom:2px;}