@bongos/core 1.19.789 → 1.19.791

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

@@ -0,0 +1,85 @@
+// modules/hall-ui/public/hall-visual.js — the ship-time task visual, in one place
+// (task 1003835; the renderers themselves are tasks 1003109 and 1003829).
+//
+// A satellite of hall-kit.js rather than a part of it, and that is the decision
+// this file records. These three functions lived in the kit, which is 61KB of
+// pager/ledger/filter/chart machinery. The task record page (task.html) renders a
+// visual and needs NOTHING else the kit holds, so converging it onto the kit's
+// renderer would have meant loading 61KB on the hall's most-visited record page
+// for one function — a real cost, paid on the wrong page. The alternative was to
+// let task.js keep its own copy, which is how the hall ended up with two.
+//
+// So the helpers moved OUT. Any page that renders a visual loads this file; the
+// kit no longer carries them and the pages that only use the kit no longer pay
+// for them. The owner's call (2026-09-16) was that the kit may grow satellites
+// like this one.
+//
+// Contract, identical to the kit's own: dependency-free (its own esc(), no
+// window.OTB use) so load order only needs "before the page script";
+// node-require-safe, so tests/task_visuals.mjs can require it with no DOM;
+// string-template builders returning HTML, no state, no render loop.
+//
+// CSS: each caller supplies its own BEM base, because SIZE is the surface's
+// decision and not this file's — the task record caps at 52vh in a record column
+// (.tk-visual, style.css/task.css), the Studio gives the plate the card's whole
+// width (.studio-plate). The markup, the URL guard and the escaping are shared.
+(() => {
+  'use strict';
+
+  // HTML-escape for text interpolated into innerHTML.
+  function esc(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => ({
+      '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+    }[c]));
+  }
+
+  // Same-origin, SERVER-MINTED paths only. The URL arrives from our own API, but
+  // it lands in an href and a src, so it is matched literally against the shape
+  // modules/lifecycle/task-visuals.js mints rather than trusted. Anything else
+  // renders nothing at all.
+  const VISUAL_URL_RE = /^\/api\/(gds|bongos)\/task-visuals\/task-\d+-[0-9a-f]{16}\.(png|jpg|gif|webp)$/;
+  function isTaskVisualUrl(url) {
+    return VISUAL_URL_RE.test(String(url ?? ''));
+  }
+
+  // The compact thumbnail, for a FEED — where the summary is one line in a list,
+  // so the image appears small and links to the full-size file. Three feeds draw
+  // it (the hall's ship ledger, a profile's recent ships, the status dashboard).
+  // Returns '' when the row carries no visual: a task without one must never look
+  // incomplete, so nothing is drawn and there is no placeholder.
+  function shipVisualThumbHtml(row) {
+    const url = String((row && row.visual_url) ?? '');
+    if (!isTaskVisualUrl(url)) return '';
+    const alt = String((row && row.visual_alt) || `Visual for task ${(row && row.id) ?? ''}`).trim();
+    return `<a href="${esc(url)}" target="_blank" rel="noopener" title="${esc(alt)}">` +
+      `<img class="ship-visual-thumb" src="${esc(url)}" alt="${esc(alt)}" loading="lazy"></a>`;
+  }
+
+  // The FULL-SIZE form: the picture as the thing being looked at, with visual_alt
+  // as its caption. For a surface whose subject IS the image — the task record
+  // (.tk-visual) and the Studio's review card (.studio-plate).
+  //
+  // `className` is the caller's BEM base; it is sanitised because it reaches a
+  // class attribute. Returns '' with no visual, like the thumbnail.
+  function taskVisualFigureHtml(row, { className = 'task-visual' } = {}) {
+    const url = String((row && row.visual_url) ?? '');
+    if (!isTaskVisualUrl(url)) return '';
+    const written = String((row && row.visual_alt) || '').trim();
+    const alt = written || `Visual for task ${(row && row.id) ?? ''}`;
+    const base = String(className).replace(/[^A-Za-z0-9_-]/g, '');
+    // The caption is only drawn when the shipper WROTE one — the fallback alt is
+    // a machine sentence for a screen reader, not a caption to show a reader.
+    const caption = written ? `<figcaption class="${base}__caption">${esc(written)}</figcaption>` : '';
+    return `<figure class="${base}">` +
+      `<a href="${esc(url)}" target="_blank" rel="noopener">` +
+      `<img class="${base}__img" src="${esc(url)}" alt="${esc(alt)}" loading="lazy">` +
+      `</a>${caption}</figure>`;
+  }
+
+  const api = { isTaskVisualUrl, shipVisualThumbHtml, taskVisualFigureHtml };
+
+  // Node-require-safe (the dom-utils.js / hall-kit.js pattern): assignment is the
+  // only eval-time side effect, and only when a window exists.
+  if (typeof window !== 'undefined') window.OTBVisual = api;
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+})();

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

@@ -110,6 +110,7 @@
 <script src="/builders/box-panel.js?v=2026-06-14-domutils" defer></script>
 <!-- task 2166: the shared component kit (window.OTBKit) — pager/ledger/rail.
      Loaded BEFORE hall-widgets.js, whose skeletons call OTBKit.pagerBarHtml(). -->
+<script src="/builders/hall-visual.js?v=2026-09-16-visual1" defer></script>
 <script src="/builders/hall-kit.js" defer></script>
 <!-- BV1.R75: the CORE hall widgets register into window.OTB's hall-widget registry.
      Loaded BEFORE builders.js so the registry is populated when builders.js stamps

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

@@ -196,6 +196,7 @@
 <!-- hall-kit (window.OTBKit) — profile.js renders ship-time task visuals through
      its shared thumbnail helper (task 1003109) and builds the section rail with
      it (task 1003489), so it must load first. -->
+<script src="/builders/hall-visual.js?v=2026-09-16-visual1"></script>
 <script src="/builders/hall-kit.js?v=2026-08-27-activity"></script>
 <!-- Connections (section 6). Loaded BEFORE profile.js so window.OTBConnections
      exists by the time renderProfile runs; profile.js guards on it anyway, so a

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

@@ -176,7 +176,7 @@
     const summary = s.value_summary
       ? `<span style="display:block;margin-top:2px;font-size:12px;color:var(--ink-faint)">${escapeHtml(s.value_summary)}</span>`
       : '';
-    const visual = window.OTBKit && window.OTBKit.shipVisualThumbHtml ? window.OTBKit.shipVisualThumbHtml(s) : '';
+    const visual = window.OTBVisual ? window.OTBVisual.shipVisualThumbHtml(s) : '';
     return `<tr>
         <td class="ledger__num">#${escapeHtml(String(s.id))}</td>
         <td><a href="${taskHref(s.id)}">${escapeHtml(s.title || `Task ${s.id}`)}</a>${summary}${visual ? `<span style="display:block;margin-top:6px">${visual}</span>` : ''}</td>
@@ -473,7 +473,7 @@
         const summary = t.value_summary
           ? `<span style="display:block;margin-top:2px;font-size:12px;color:var(--ink-faint)">${escapeHtml(t.value_summary)}</span>`
           : '';
-        const visual = kit.shipVisualThumbHtml ? kit.shipVisualThumbHtml(t) : '';
+        const visual = window.OTBVisual ? window.OTBVisual.shipVisualThumbHtml(t) : '';
         return `<tr>
           <td class="ledger__num">#${escapeHtml(String(t.id))}</td>
           <td><a href="${taskHref(t.id)}">${escapeHtml(t.title || `Task ${t.id}`)}</a>${summary}${visual ? `<span style="display:block;margin-top:6px">${visual}</span>` : ''}</td>

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

@@ -311,6 +311,10 @@
       // The project's own fundamentals (task 1003280, goal 1000072). Mirrors the
       // server's requireGovernmentPage floor; cosmetic only, as every item here is.
       { id: 'project-settings', label: 'Project settings', icon: 'admin', href: '/project-settings', gate: 'government' },
+      // The deploy door (task 1003159, ADR 0293). Gated 'archon' here to mirror the
+      // `core.pin.move` atom its page and both its routes check — cosmetic only, as
+      // every item in this list is; the wall is server-side.
+      { id: 'deploy', label: 'Deploy', icon: 'admin', href: '/deploy', gate: 'archon' },
       // BV1.R113: the roles-and-permissions tab (ADR 0151). The one genuinely
       // Archon-only item the 'government' gate comment anticipated — cosmetic
       // only. The wall is the `government.manage` atom checked on each of the

package/modules/hall-ui/public/studio.css

@@ -155,7 +155,7 @@
    IS the card: an artist is being asked to LOOK at something, so it is given the
    card's full width and as much height as a screen can spare, not the 44px
    thumbnail a ship feed uses. Markup comes from the kit's one renderer
-   (OTBKit.taskVisualFigureHtml); only the size is this room's decision.
+   (OTBVisual.taskVisualFigureHtml); only the size is this room's decision.
 
    max-height in vh, and MEASURED at 1440x900 rather than chosen. The size an
    artist can judge it at wins over a zero-scroll card — that is the task's own

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

@@ -72,6 +72,7 @@
 <!-- The kit, for its ONE renderer: the full-size ship-time visual figure
      (task 1003829). The copy desk — the artist's other room — already loads it,
      and a fourth hand-rolled <figure> is what the kit exists to stop. -->
+<script src="/builders/hall-visual.js?v=2026-09-16-visual1"></script>
 <script src="/builders/hall-kit.js"></script>
 <script src="/builders/studio.js?v=2026-09-10-studio2"></script>
 </body>

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

@@ -132,7 +132,7 @@
   // ---------------------------------------------------------------------------
 
   // THE PLATE — the reviewed work's ship-time visual, at the size the card can
-  // give it. Through the kit's one renderer (OTBKit.taskVisualFigureHtml, which
+  // give it. Through the one renderer (OTBVisual.taskVisualFigureHtml, which
   // carries the server-minted-URL guard and the escaping) with the Studio's own
   // class, because the size is this surface's decision: here the picture is the
   // subject, not an illustration beside a record.
@@ -141,8 +141,9 @@
   // read, or when the kit is absent — a review with no picture must read as a
   // review, never as an empty frame (the degrade rule).
   function plateHtml(p) {
-    if (!p.shipped || !kit || typeof kit.taskVisualFigureHtml !== 'function') return '';
-    return kit.taskVisualFigureHtml(p.shipped, { className: 'studio-plate' });
+    const vis = window.OTBVisual;
+    if (!p.shipped || !vis || typeof vis.taskVisualFigureHtml !== 'function') return '';
+    return vis.taskVisualFigureHtml(p.shipped, { className: 'studio-plate' });
   }
 
   // The three weights, and the one field they share. Offered only to a viewer

package/modules/hall-ui/public/style.css

@@ -2841,22 +2841,6 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
   overflow-y: auto;
 }
 .td-touches { font-size: 12.5px; color: var(--ink-faint); font-family: var(--font-mono); word-break: break-word; margin: 0 0 12px; }
-/* task 1003109: the ship-time VISUAL, rendered directly under the value summary
-   it restates. Sized to be READ (this exists so a non-engineer can see a change),
-   capped so a tall screenshot can't push the rest of the record off the page, and
-   never drawn at all when a task has no visual. */
-.td-visual { margin: 0 0 12px; }
-.td-visual__img {
-  display: block;
-  max-width: 100%;
-  max-height: 52vh;
-  width: auto;
-  height: auto;
-  border: var(--line) solid var(--rule-soft);
-  border-radius: var(--radius-sm);
-  background: var(--glass);
-}
-.td-visual__caption { font-size: 12.5px; color: var(--ink-faint); margin: 6px 0 0; }
 /* The compact form: a thumbnail beside a value summary in a ship FEED, where the
    summary is one line in a list and a full-width image would drown it. */
 .ship-visual-thumb {

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

@@ -68,6 +68,7 @@
 <script src="/builders/task-detail.js?v=2026-07-03-taskdetail2" defer></script>
 <script src="/builders/brand-apply.js?v=2026-06-19-r56" defer></script>
 <script src="/builders/md-reader.js" defer></script>
+<script src="/builders/hall-visual.js?v=2026-09-16-visual1" defer></script>
 <script src="/builders/task.js?v=2026-07-03-taskpage1" defer></script>
 </body>
 </html>

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

@@ -292,20 +292,17 @@
   // a detail can be opened full-size. The caption (visual_alt) doubles as the alt
   // text, which is why it is stored: an image with no alt tells a screen reader
   // nothing, and "a picture of the change" is exactly the audience that needs it.
+  // The shared renderer (hall-visual.js), not a copy of it — task 1003835. This
+  // page hand-rolled the same <figure> until then; the markup it produced is what
+  // OTBVisual emits, so .tk-visual's rules are unchanged. `className` keeps the
+  // sizing this page's own CSS owns (52vh inside a record column).
+  //
+  // Guarded rather than assumed: hall-visual.js is a separate <script>, so a page
+  // that forgot it should render no picture, never a broken one.
   function taskVisualHtml(t) {
-    const url = String(t.visual_url || '');
-    // Same-origin, server-generated paths only. The URL comes from our own API,
-    // but rendering it into an href/src is a place to be literal rather than
-    // trusting: anything that is not the shape our serve route mints is dropped.
-    if (!/^\/api\/(gds|bongos)\/task-visuals\/task-\d+-[0-9a-f]{16}\.(png|jpg|gif|webp)$/.test(url)) return '';
-    const alt = String(t.visual_alt || `Visual for task ${t.id}`);
-    const caption = t.visual_alt
-      ? `<figcaption class="tk-visual__caption">${escapeHtml(t.visual_alt)}</figcaption>`
-      : '';
-    return `<figure class="tk-visual">` +
-      `<a href="${escapeHtml(url)}" target="_blank" rel="noopener">` +
-      `<img class="tk-visual__img" src="${escapeHtml(url)}" alt="${escapeHtml(alt)}" loading="lazy">` +
-      `</a>${caption}</figure>`;
+    const vis = window.OTBVisual;
+    if (!vis || typeof vis.taskVisualFigureHtml !== 'function') return '';
+    return vis.taskVisualFigureHtml(t, { className: 'tk-visual' });
   }
 
   async function copyText(text) {

package/modules/provisioning/control-plane-guard.js

@@ -0,0 +1,102 @@
+'use strict';
+
+// modules/provisioning/control-plane-guard.js — what may be aimed at the box this
+// software is running on (task 1003159, ADR 0293 D2).
+//
+// WHY THIS EXISTS. `provisioning_intents.instance_id` is NOT NULL REFERENCES
+// provisioning_instances(id), so an intent must name a row. The control plane has
+// never had one — the table holds tenant projects — which is precisely why the
+// owner had no deploy door: there was nothing to point at. Enrolling it as a
+// `hosting_shape='control-plane'` row opens the door.
+//
+// It also puts a 'teardown' button one query away from the platform itself. That
+// is the risk this file exists to close, and it is the reason the shape is a
+// distinct VALUE rather than a reuse of 'standalone': a distinct value is something
+// every destructive leg can refuse BY NAME.
+//
+// AN ALLOW-LIST, NOT A DENY-LIST. Listing today's destructive actions and refusing
+// those would silently admit tomorrow's — a new action added to INTENT_ACTIONS
+// would be permitted on the self row by omission, and the failure mode of
+// "permitted by omission" here is the platform deleting itself. So the rule is
+// inverted: nothing touches the self row unless it is named below.
+//
+// Carved out of provisioning.js rather than living beside INTENT_ACTIONS because
+// that file sits on the oversized-file ratchet; a guard whose whole value is being
+// read before it is edited should not be the thing that reds the build either.
+
+// The only acts that cannot destroy the box they run on.
+//
+//   core-upgrade — moves the pin, health-gated, auto-rollback on failure. This is
+//                  the door task 1003159 builds.
+//   restart      — the liveness remedy (task 1003238). Restarting the platform is
+//                  recoverable and already owner-initiated elsewhere.
+//
+// Adding to this list is a deliberate edit someone has to argue for. It is pinned
+// by name in tests/core_upgrade_door.mjs so it cannot grow as a side effect.
+const CONTROL_PLANE_ACTIONS = Object.freeze(['core-upgrade', 'restart']);
+
+/**
+ * May this intent action be aimed at an instance of this hosting shape? PURE.
+ *
+ * AN UNKNOWN SHAPE IS ORDINARY, NOT CONTROL-PLANE. Deliberate, and the one place
+ * this guard fails OPEN. It protects one specific row; treating every
+ * unrecognised shape as the self row would refuse ordinary provisioning for any
+ * shape added later without touching this file — a far larger blast radius than
+ * the thing being guarded, and one that would present as provisioning mysteriously
+ * breaking rather than as a guard doing its job.
+ *
+ * @param {string} action        an INTENT_ACTIONS member
+ * @param {string} hostingShape  a HOSTING_SHAPES member
+ * @returns {boolean}
+ */
+function intentAllowedForShape(action, hostingShape) {
+  if (hostingShape !== 'control-plane') return true;
+  return CONTROL_PLANE_ACTIONS.includes(action);
+}
+
+/**
+ * Refuse, loudly, any intent aimed at the control-plane row that is not allowed there.
+ *
+ * CALLED FROM enqueueIntent — the ONE place every intent passes, whichever route or
+ * helper queued it. That placement is the point: the core-upgrade route checks the
+ * same rule earlier so the owner reads a sentence instead of a 500, but every OTHER
+ * action reaches the queue through a route that has never heard of this shape. A
+ * guard that must hold for all of them cannot live in each of them.
+ *
+ * IT THROWS RATHER THAN RETURNING A CONFLICT, because the two are different
+ * statements. A conflict means "not now", and a caller may reasonably retry it; this
+ * means "never, and if you got here something upstream is already wrong". A retry
+ * loop spinning on a refusal that cannot change is the worse failure.
+ *
+ * AN ABSENT ROW IS NOT REFUSED. The insert that follows carries a NOT NULL FK, so a
+ * missing instance fails there with the error that actually describes it; answering
+ * "control plane protected" for a row that does not exist would be a lie that sends
+ * the reader to the wrong file.
+ *
+ * One extra SELECT, on a path that runs a handful of times a day.
+ *
+ * @param {{query: Function}} db
+ * @param {number|string} instanceId
+ * @param {string} action  an INTENT_ACTIONS member
+ * @throws {Error} code 'control_plane_protected'
+ */
+async function assertIntentAllowed(db, instanceId, action) {
+  const { rows } = await db.query(
+    'SELECT hosting_shape FROM provisioning_instances WHERE id = $1', [instanceId]);
+  const shape = rows[0] && rows[0].hosting_shape;
+  if (!shape || intentAllowedForShape(action, shape)) return;
+  // It carries the { code, status, message } shape credential-preflight.js established,
+  // so a route that wants to answer 409 with the sentence can, without re-deriving it.
+  // NO ROUTE MAPS IT TODAY, and that is the honest state rather than an oversight: every
+  // action that can reach this throw has its own earlier refusal, so arriving here means
+  // a route forgot one — a bug in us, not a thing the caller did. A 500 plus a logged
+  // stack is the right loudness for that, and the fields are here so the day a route
+  // legitimately needs to say it to a person, the wording is already written.
+  const err = new Error(`'${action}' cannot be aimed at the control plane — only ${CONTROL_PLANE_ACTIONS.join(' and ')} may run against the box the platform itself runs on`);
+  err.code = 'control_plane_protected';
+  err.status = 409;
+  err.publicMessage = `That action cannot be aimed at the machine the platform itself runs on. Only ${CONTROL_PLANE_ACTIONS.join(' and ')} are allowed there.`;
+  throw err;
+}
+
+module.exports = { CONTROL_PLANE_ACTIONS, intentAllowedForShape, assertIntentAllowed };

package/modules/provisioning/core-upgrade.js

@@ -0,0 +1,289 @@
+'use strict';
+
+// modules/provisioning/core-upgrade.js — the owner's deploy door, web-tier half
+// (task 1003159, ADR 0293).
+//
+// Moving an instance's core pin is gate 3 of the release pipeline and the only act
+// that makes shipped work visible to users. It was reachable from exactly one
+// place — a shell on the control-plane box with an ssh key — so the owner could not
+// take it, and neither could an agent (the permission classifier blocks a mutating
+// `sudo -u lars` over ssh by design).
+//
+// THIS FILE ONLY ASKS. It validates and queues an intent; the control-plane runner
+// drains it and drives the proven `bongos upgrade` path with its health gate and
+// auto-rollback intact. The web process gains no sudo and no ssh key — that split
+// is ADR 0111 §2's rule and ADR 0293 D1's decision, and it is why a stolen builder
+// token can request a deploy but never perform one.
+//
+// WHY THE REGISTRY CHECK IS NOT HERE, though ADR 0293 D3 demands one. The only
+// tool that can answer "is this version published" is update-channel.js's
+// `listAvailableVersions`, which shells out via spawnSync — it would block the
+// entire event loop for the seconds npm takes, stalling every other request on a
+// single-process server. It also lives in scripts/gds/, which a module may not
+// require (ADR 0083). So publication and channel policy are enforced by the RUNNER,
+// which is a CLI process where both are free. What is enforced here is everything
+// that can be decided without the network: shape, state, format, and the guard.
+//
+// Lives in its own file for the mechanical reason paid-shape-gate.js and
+// credential-preflight.js do: provisioning.js and routes/provisioning.js both sit
+// AT the 1500-line fitness ratchet, and at that ceiling a new function costs more
+// than the build will give back.
+
+
+// Exactly the states in which there is a running instance whose pin can move.
+// Narrower than RESTART_FROM on purpose: an instance mid-standup has no settled pin
+// to move, and one that is tearing down is on its way out.
+const CORE_UPGRADE_FROM = Object.freeze(new Set(['active']));
+
+// The shapes whose box the runner can actually reach to perform an upgrade.
+// Mirrors RESTART_SHAPES and adds the control plane (which the runner IS on).
+//
+// A 'dedicated' droplet is stood up by cloud-init and the runner has no post-hoc
+// exec path to it — the same fact the restart route refuses on. Queueing an
+// upgrade for one would be the F16 lie: a request that is accepted and never
+// lands. This is a SEPARATE question from the control-plane guard, which asks
+// what may be aimed at the platform itself; a first cut conflated the two and
+// silently accepted upgrades for dedicated droplets.
+const UPGRADE_SHAPES = Object.freeze(new Set(['co-tenant', 'standalone', 'control-plane']));
+
+// The shape of a core version as the pin records it. Deliberately strict and
+// three-part: the column's own CHECK carries the same pattern, so a value that
+// slips past one still cannot reach the table. This says the string is WELL-FORMED,
+// never that the version exists — see the header.
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+const isCoreVersion = (v) => typeof v === 'string' && VERSION_RE.test(v);
+
+/**
+ * Why this core-upgrade request must be refused, or null to admit it. PURE.
+ *
+ * Returns the shape credential-preflight.js established — `{ code, status, message }`
+ * for the route to `res.fail` with — so the refusal text lives beside the rule that
+ * produced it rather than being re-derived at the call site. Every message names
+ * what the caller can actually DO instead, which is the ADR 0190 §7 convention, and
+ * none of them promises a duration: how long a deploy takes is exactly what this
+ * layer cannot know.
+ *
+ * @param {object}  inst  the provisioning_instances row
+ * @param {string}  to    the requested target core version
+ * @param {string?} live  the version the instance currently serves, when known
+ */
+function coreUpgradeFault(inst, to, live = null) {
+  // UPGRADE_SHAPES IS THE WHOLE SHAPE CHECK, and the self-row guard is deliberately
+  // NOT consulted here. `intentAllowedForShape('core-upgrade', …)` returns true for
+  // every shape there is — for a tenant shape unconditionally, and for the control
+  // plane because 'core-upgrade' is permanently a member of CONTROL_PLANE_ACTIONS.
+  // A first cut called it anyway, which read as a second gate and could not refuse
+  // anything: the same "present but unreachable" failure this file's own header
+  // records about `inst.core_version ||`. The guard's real job is refusing the OTHER
+  // actions on the self row, and it does that at enqueueIntent, where every intent
+  // passes. Naming it a third time here would only make the dead branch look alive.
+  if (!UPGRADE_SHAPES.has(inst.hosting_shape)) {
+    return {
+      code: 'core_upgrade_unavailable',
+      status: 409,
+      message: `This project runs on a machine the platform doesn’t manage, so its core can’t be moved from here — whoever runs that machine has to upgrade it there.`,
+    };
+  }
+  if (!CORE_UPGRADE_FROM.has(inst.status)) {
+    const offline = inst.status === 'torn_down' || inst.status === 'tearing_down';
+    return {
+      code: 'not_upgradable',
+      status: 409,
+      message: offline
+        ? 'This project is offline, so there is no running core to move — stand it up again first.'
+        : 'This project hasn’t finished standing up yet, so it has no settled core version to move.',
+    };
+  }
+  if (!isCoreVersion(to)) {
+    return {
+      code: 'bad_target_version',
+      status: 400,
+      message: 'Name the exact core version to move to, as three numbers — for example 1.19.757.',
+    };
+  }
+  // Asking for the version already running is not an error worth a 4xx on its own,
+  // but queueing it would restart the service to change nothing. Say so instead.
+  if (live && String(live) === String(to)) {
+    return {
+      code: 'already_on_version',
+      status: 409,
+      message: `This project already runs core ${to}, so there is nothing to move — it would restart and land exactly where it is.`,
+    };
+  }
+  return null;
+}
+
+/**
+ * Queue the upgrade. Mirrors enqueueRestart's arbitration of the single open slot.
+ *
+ * A core-upgrade already open is NOT reported as success the way a duplicate
+ * restart is: a restart carries no payload, so "already under way" is the truth,
+ * but this one names a TARGET and the open intent may name a different one.
+ * Reporting that as done would tell the owner their version is coming when another
+ * is. So a second request is a conflict the route names, including when the open
+ * intent is itself a core-upgrade.
+ */
+async function enqueueCoreUpgrade(provisioning, db, instanceId, to, requestedBy) {
+  const { intent, created } = await provisioning.enqueueIntent(db, instanceId, 'core-upgrade', requestedBy, to);
+  if (created) return { intent, created: true };
+  return { intent, created: false, conflict: 'open_intent' };
+}
+
+/**
+ * The POST handler, as a factory over its dependencies.
+ *
+ * It lives here rather than inline in routes/provisioning.js because that file is
+ * AT the 1500-line fitness ratchet — the same reason callback-page.js and
+ * body-validators.js were carved out of it (see the module's CLAUDE.md). The
+ * router keeps the declaration and its gate, which is the part a reader scanning
+ * the route table needs to see; the body is one require away.
+ *
+ * THE SECOND STEP IS THE BODY. The owner previews, then confirms by naming the
+ * version they saw. Requiring an explicit `to` IS the confirmation (ADR 0293 D4):
+ * a request that cannot fire without naming its target cannot fire from a stray
+ * click, and "move to whatever is newest", resolved at drain time, would be a
+ * different act from the one that was previewed — main moves between the two.
+ */
+function makeCoreUpgradeHandler({ provisioning, pool, parseId, validateOrRespond, log }) {
+  return async function coreUpgradeHandler(req, res) {
+    const id = parseId(req, res);
+    if (!id) return;
+    if (validateOrRespond(req, res, { to: { type: 'string', maxLength: 32 } }, { strict: true })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      const to = req.body && typeof req.body.to === 'string' ? req.body.to.trim() : '';
+      // THE LIVE VERSION IS NOT KNOWN HERE, and saying so beats pretending.
+      // provisioning_instances carries no core_version column, so the first cut's
+      // `inst.core_version || null` was always undefined and the already-on-version
+      // refusal could never fire from this route — a guard that reads as present
+      // and is unreachable, which is worse than no guard at all.
+      //
+      // What actually refuses a same-version move is `bongos upgrade`'s own
+      // same-version guard, in the runner, which is also what makes re-running a
+      // settled-but-unconfirmed intent a no-op (ADR 0293 Consequences). The
+      // parameter stays because the PREVIEW does know the live version — it reads
+      // the box's own /version (ADR 0293 D6) — and passes it.
+      const fault = coreUpgradeFault(inst, to, null);
+      if (fault) return res.fail(fault.code, { status: fault.status, message: fault.message });
+
+      // The actor rides the intent, and the runner carries it through to the
+      // core_upgrades ledger (ADR 0293 D5): a privileged action with an
+      // unattributed row is not acceptable here.
+      const actor = `api:archon:${req.builder.id}`;
+      const r = await enqueueCoreUpgrade(provisioning, pool, id, to, actor);
+      if (r.conflict) {
+        return res.fail('intent_conflict', {
+          status: 409,
+          message: `A '${r.intent.action}' run is currently ${r.intent.state} for this project — the core move could not be queued; try again once that settles.`,
+          details: { action: r.intent.action, state: r.intent.state, target_version: r.intent.target_version || null },
+        });
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'core-upgrade',
+        detail: `core pin move to ${to} requested`, actor,
+      }).catch(() => {});
+      // No duration is promised and no success is claimed: this says the request
+      // was RECORDED, which is the only thing true at this moment (ADR 0190 §7).
+      return res.json({
+        ok: true, queued: true, action: 'core-upgrade', target_version: to,
+        message: `Queued a move to core ${to}. The project will restart; this page reports the version it actually serves afterwards, and rolls back on its own if the new one does not answer.`,
+      });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/core-upgrade', err);
+      return res.fail('core_upgrade_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+/**
+ * What the control shows BEFORE anything is pressed — step one of the two-step (D4).
+ *
+ * Reads the snapshot the control-plane runner writes (migration core_242), because
+ * neither fact is reachable from here: the served version lives on the box's loopback
+ * and the available versions need a blocking `npm view`. The web tier asks; it does not
+ * go and look.
+ *
+ * EVERY FIELD THAT COULD BE STALE CARRIES ITS AGE. `observed_at` is returned, not hidden,
+ * and a missing snapshot returns `observed_at: null` rather than a confident-looking
+ * empty one — a control that renders a cache as though it were live is how someone is
+ * told their box is on a version it left an hour ago.
+ */
+function previewFromSnapshot(inst, snap, openIntent) {
+  const served = (snap && snap.served_version) || null;
+  const available = (snap && Array.isArray(snap.available) ? snap.available : []);
+  const recommended = (snap && snap.recommended) || null;
+  // Only what a move could actually go TO: newer than what is running, and admitted by
+  // the channel the runner will apply. Listing anything else would offer the owner a
+  // button whose press the runner then refuses.
+  const behind = served && recommended && recommended !== served;
+  return {
+    instance_id: inst.id,
+    slug: inst.slug,
+    hosting_shape: inst.hosting_shape,
+    served_version: served,
+    recommended_version: recommended,
+    available_count: available.length,
+    behind: !!behind,
+    // Named so the UI cannot accidentally render "up to date" over a missing reading.
+    reading: served ? 'ok' : 'no_answer',
+    observed_at: (snap && snap.observed_at) || null,
+    open_intent: openIntent ? { action: openIntent.action, state: openIntent.state, target_version: openIntent.target_version || null } : null,
+  };
+}
+
+async function loadPreview(pool, provisioning, inst) {
+  const { rows } = await pool.query('SELECT * FROM core_version_snapshot WHERE instance_id = $1', [inst.id]);
+  const openIntent = provisioning.getOpenIntent ? await provisioning.getOpenIntent(pool, inst.id) : null;
+  return previewFromSnapshot(inst, rows[0], openIntent);
+}
+
+function makeCoreUpgradePreviewHandler({ provisioning, pool, parseId, log }) {
+  return async function coreUpgradePreviewHandler(req, res) {
+    const id = parseId(req, res);
+    if (!id) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      return res.json({ ok: true, preview: await loadPreview(pool, provisioning, inst) });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/instances/:id/core-upgrade', err);
+      return res.fail('core_upgrade_preview_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+/**
+ * Where the deploy page starts: "which row is this platform?"
+ *
+ * THE PAGE CANNOT BE EXPECTED TO KNOW THE ID. The self row is created once, by hand, at
+ * install time (scripts/gds/enroll-control-plane.js) — so its id differs per install and
+ * is nobody's to memorise. The alternative was to have the page list the fleet and filter
+ * it client-side, which would make a page about ONE box read every project row to find it,
+ * and would answer nothing at all for an Archon who does not own the control-plane row.
+ *
+ * A MISSING SELF ROW IS A 404 WITH AN INSTRUCTION, not an error. It is the expected state
+ * of an install that has not run the enrolment yet, and the only useful thing to say is
+ * which command creates it.
+ */
+function makeControlPlaneHandler({ provisioning, pool, log }) {
+  return async function controlPlaneHandler(req, res) {
+    try {
+      const { rows } = await pool.query("SELECT * FROM provisioning_instances WHERE hosting_shape = 'control-plane' LIMIT 1");
+      if (!rows[0]) {
+        return res.fail('control_plane_not_enrolled', {
+          status: 404,
+          message: 'This platform has no deploy door yet. Whoever administers the box runs `node scripts/gds/enroll-control-plane.js --owner <builderId> --apply` once, and it appears here.',
+        });
+      }
+      return res.json({ ok: true, preview: await loadPreview(pool, provisioning, rows[0]) });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/control-plane', err);
+      return res.fail('control_plane_read_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = { CORE_UPGRADE_FROM, UPGRADE_SHAPES, VERSION_RE, isCoreVersion, coreUpgradeFault, enqueueCoreUpgrade, makeCoreUpgradeHandler, previewFromSnapshot, makeCoreUpgradePreviewHandler, makeControlPlaneHandler };
+