@bongos/core 1.19.788 → 1.19.790

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 };
+

package/modules/provisioning/migrations/provisioning_018_core_upgrade_intent.sql

@@ -0,0 +1,98 @@
+-- provisioning_018_core_upgrade_intent.sql — the owner's deploy door (task
+-- 1003159, ADR 0293).
+--
+-- NUMBERED 018, NOT 016: this shipped as 016 on a branch while 016_disconnect and
+-- 017_domain_lookup_index landed on main. Two files claiming one number is not a
+-- merge artefact to tidy after the fact — migrations run in name order, and the
+-- action CHECK below REPLACES the one 016_disconnect writes, so running them in
+-- the wrong order would drop 'disconnect' from the vocabulary. It goes last, and
+-- it carries the whole set.
+--
+-- Moving an instance's core pin is gate 3 of the release pipeline and the only act
+-- that makes shipped work visible to users. Until now it was reachable from exactly
+-- one place: a shell on the control-plane box holding an ssh key. The owner said so
+-- twice in a month — "I don't think I can make anything live", then "this is above
+-- my paygrade" — and an agent could not close the loop either, because the
+-- permission classifier blocks a mutating `sudo -u lars` over ssh by design.
+--
+-- Two widenings, and they are two halves of one door:
+--
+--   1. 'core-upgrade' joins the intent vocabulary. The web tier QUEUES it; 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 — it gains the ability to ASK (ADR 0293 D1).
+--
+--   2. 'control-plane' joins the hosting shapes. `provisioning_intents.instance_id`
+--      is NOT NULL REFERENCES provisioning_instances(id), so an intent must name a
+--      row, and the box this software runs on has never had one — the table holds
+--      only tenant projects. Enrolling it is what gives the door something to point
+--      at (ADR 0293 D2).
+--
+-- THE SELF ROW IS THE DANGEROUS HALF, AND THE GUARD IS IN CODE, NOT HERE.
+-- 'teardown' aimed at the control-plane row would destroy the platform from inside
+-- the platform's own UI. `intentAllowedForShape()` in modules/provisioning/
+-- provisioning.js is the single place that decides, as an ALLOW-list
+-- (CONTROL_PLANE_ACTIONS = core-upgrade, restart) rather than a deny-list of the
+-- destructive ones — so an action added to INTENT_ACTIONS later is refused on the
+-- self row until someone states it is safe there. That is the direction which
+-- cannot destroy the platform by omission.
+--
+-- A CHECK constraint cannot express that rule (it would have to see both tables at
+-- once), which is exactly why the shape is a distinct VALUE: it makes the rule
+-- expressible in the one place that can enforce it.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, every object
+-- provisioning_-prefixed, idempotent — safe to re-run.
+
+BEGIN;
+
+-- 1. the intent vocabulary
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest', 'domain-attach',
+                    'settings-apply', 'restart', 'disconnect', 'core-upgrade'));
+
+-- 2. the hosting shapes
+ALTER TABLE provisioning_instances DROP CONSTRAINT IF EXISTS provisioning_instances_hosting_shape_check;
+ALTER TABLE provisioning_instances ADD CONSTRAINT provisioning_instances_hosting_shape_check
+  CHECK (hosting_shape IN ('co-tenant', 'dedicated', 'standalone', 'control-plane'));
+
+-- 3. the target a core-upgrade names.
+--
+-- No existing action carries a payload: settings-apply re-reads the instance row,
+-- restart carries nothing. A core-upgrade MUST name a version, because "upgrade to
+-- whatever is newest" resolved at drain time is a DIFFERENT act from the one the
+-- owner previewed and confirmed (ADR 0293 D4) — main can move between the two.
+--
+-- The invariant is an EQUIVALENCE, and both directions are load-bearing: a
+-- core-upgrade with no target is an intent the runner cannot execute, and a target
+-- on any other action is a value nothing reads — which is how a payload column
+-- quietly becomes a junk drawer. Valid immediately rather than NOT VALID: every
+-- pre-existing row has a non-core-upgrade action and a NULL target, so it holds.
+--
+-- The format CHECK keeps free text out at the DB layer as well as the route's. The
+-- REGISTRY is still the authority on whether the version exists; that check lives
+-- in the runner, which can reach npm without blocking a web request.
+ALTER TABLE provisioning_intents ADD COLUMN IF NOT EXISTS target_version text;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'provisioning_intents_target_version_chk') THEN
+    ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_target_version_chk
+      CHECK ((action = 'core-upgrade') = (target_version IS NOT NULL));
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'provisioning_intents_target_version_fmt_chk') THEN
+    ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_target_version_fmt_chk
+      CHECK (target_version IS NULL OR target_version ~ '^[0-9]+\.[0-9]+\.[0-9]+$');
+  END IF;
+END $$;
+
+-- AT MOST ONE control-plane row, ever. The self row means "the box this process is
+-- running on"; two of them would make "which one is me?" a question with no answer,
+-- and the deploy door would point at whichever the query happened to return first.
+-- A partial unique index over a constant is the standard way to say "at most one".
+CREATE UNIQUE INDEX IF NOT EXISTS provisioning_instances_one_control_plane_idx
+  ON provisioning_instances ((hosting_shape))
+  WHERE hosting_shape = 'control-plane';
+
+COMMIT;

package/modules/provisioning/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Off the Boats maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["provisioning", "disconnect"],
+    "routes": ["provisioning", "disconnect", "core-upgrade"],
     "migrations": true,
     "pollers": ["liveness-sweep", "catalog-backfill"]
   },

package/modules/provisioning/provisioning.js

@@ -28,7 +28,7 @@ const INSTANCE_STATES = ['requested', 'provisioning', 'active', 'tearing_down',
 // dedicated  — its own DigitalOcean droplet (priced by tier)
 // standalone — its OWN repo checkout + pinned @cloudbongos/core npm dep, co-located on
 //              the box (ADR 0108 destination model; owner-hosted, $0). See provision.js.
-const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
+const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone', 'control-plane'];
 // How the instance's repo was onboarded (migration provisioning_004, ADR 0121):
 //   greenfield — a fresh EMPTY repo; the runner scaffolds it and pushes the first commit
 //   adopt      — a repo the owner ALREADY has; the runner must LAYER onto it, preserving
@@ -59,7 +59,9 @@ const PROJECT_TYPES = ['game', 'research', 'business', 'non-profit', 'not-sure']
 // env patch. Its own action because no existing one fits: provision refuses
 // 'active' and settings-apply requires a value that actually changed.
 // 'disconnect' (task 1003249, migration provisioning_016): the owner's true delete — ./disconnect.js.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect'];
+// 'core-upgrade' (task 1003159, ADR 0293): move this instance's core pin — the owner's
+// deploy door. The web tier only QUEUES it; the control-plane runner performs it.
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach', 'settings-apply', 'restart', 'disconnect', 'core-upgrade'];
 // Every state a teardown can be asked for — i.e. everything except the one
 // state where there is provably nothing left to release. DERIVED from
 // INSTANCE_STATES on purpose (task 1003042, walk finding N5): the old hand-kept
@@ -1134,13 +1136,11 @@ async function setInstanceStatus(db, id, status, patch = {}) {
 // Enqueue a provision/teardown intent. Idempotent: the partial unique index
 // ux_provisioning_intents_open makes a second open enqueue collide (23505); we
 // then return the already-open intent with created:false (mirrors boxes.enqueueIntent).
-async function enqueueIntent(db, instanceId, action, requestedBy) {
+async function enqueueIntent(db, instanceId, action, requestedBy, targetVersion = null) {
+  await require('./control-plane-guard').assertIntentAllowed(db, instanceId, action); // ADR 0293 D2; required HERE because this file is at the size ratchet
   try {
-    const { rows } = await db.query(
-      `INSERT INTO provisioning_intents (instance_id, action, requested_by, state)
-       VALUES ($1, $2, $3, 'pending') RETURNING *`,
-      [instanceId, action, requestedBy ?? null]
-    );
+    const { rows } = await db.query(`INSERT INTO provisioning_intents (instance_id, action, requested_by, state, target_version)
+       VALUES ($1, $2, $3, 'pending', $4) RETURNING *`, [instanceId, action, requestedBy ?? null, targetVersion ?? null]);
     return { intent: rows[0], created: true };
   } catch (e) {
     if (e && e.code === '23505') {

package/modules/provisioning/routes/core-upgrade.js

@@ -0,0 +1,95 @@
+'use strict';
+
+// modules/provisioning/routes/core-upgrade.js — the owner's deploy door
+// (task 1003159, ADR 0293).
+//
+// Moving an instance's core pin is gate 3 of the release pipeline (ADR 0137) and
+// the ONLY act that makes shipped work visible to users. Until this route it was
+// reachable from exactly one place — a shell on the control-plane box holding an
+// ssh key — which is why the owner said "I don't think I can make anything live",
+// and why an agent could not close the loop for them either: the permission
+// classifier blocks a mutating `sudo -u lars` over ssh by design.
+//
+// THE WEB TIER ONLY ASKS. This queues an intent; the control-plane runner drains it
+// and drives the proven `bongos upgrade` path with its health gate and auto-rollback
+// intact. This process gains no sudo, no ssh key, no new capability — ADR 0111 §2's
+// rule and ADR 0293 D1's decision, and what keeps a stolen builder token able to
+// REQUEST a deploy and never to perform one.
+//
+// ITS OWN ROUTER, not a block inside routes/provisioning.js, for the mechanical
+// reason that file's own CLAUDE.md records: it sits AT the 1500-line fitness
+// ratchet, and at that ceiling a route costs more lines than the build will give
+// back. Multi-router modules are the norm here (lifecycle contributes eighteen), so
+// this is the cheap, conventional shape rather than a workaround.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const provisioning = require('../provisioning');
+const { makeCoreUpgradeHandler, makeCoreUpgradePreviewHandler, makeControlPlaneHandler } = require('../core-upgrade');
+
+const log = api.logger('provisioning');
+
+module.exports = function buildCoreUpgradeRouter() {
+  const router = express.Router();
+
+  // POST /provisioning/instances/:id/core-upgrade — move the core pin.
+  //
+  // rank: `core.pin.move` — archon floor AND system:true, so the catalog's own
+  // invariant forbids granting it to metic and no custom rank can be handed it
+  // without a deliberate, visible edit. BV1.R105 / ADR 0151 is why this is an atom
+  // and not `requireRank`: tests/government_require_permission.mjs fails the build
+  // on a new requireRank in a modules/*/routes gate.
+  //
+  // Body: { to: "1.19.757" } — and requiring it IS the second step of the two-step
+  // the owner asked for (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 previewed: main
+  // moves between the preview and the confirm.
+  //
+  // What this does NOT check: whether the version is PUBLISHED, and whether the
+  // channel policy admits it. Both need the registry, and the only tool that reads
+  // it (update-channel.js `listAvailableVersions`) shells out synchronously — it
+  // would block the event loop for every other request on this process. It also
+  // lives in scripts/gds/, which a module may not require (ADR 0083). The runner
+  // enforces both, where it is a CLI and both are free. See ../core-upgrade.js.
+  router.post(
+    '/provisioning/instances/:id/core-upgrade',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    makeCoreUpgradeHandler({
+      provisioning,
+      pool: api.pool,
+      parseId: api.parseId,
+      validateOrRespond: api.validateOrRespond,
+      log,
+    }),
+  );
+
+  // GET the same path — step ONE of the two-step (ADR 0293 D4): what a move would do.
+  //
+  // GATED THE SAME AS THE POST, deliberately. Reading it discloses the instance's exact
+  // core version and how far behind it is, which is a vulnerability-window disclosure —
+  // precisely the sort of thing ADR 0043 keeps off unauthenticated surfaces. A preview
+  // anyone could read would also let an attacker time a request against a known-stale
+  // window. The read being no cheaper than the write costs the owner nothing: they hold
+  // the atom by construction, because they are the only one who can press the button.
+  router.get(
+    '/provisioning/instances/:id/core-upgrade',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    makeCoreUpgradePreviewHandler({ provisioning, pool: api.pool, parseId: api.parseId, log }),
+  );
+
+  // GET /provisioning/control-plane — "which row is this platform, and where does it
+  // stand?" The deploy page's first call: the self row is created once by hand at
+  // install time, so its id is per-install and nobody's to memorise. Same atom again,
+  // so the entrance is no wider than the door it leads to.
+  router.get(
+    '/provisioning/control-plane',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    makeControlPlaneHandler({ provisioning, pool: api.pool, log }),
+  );
+
+  return router;
+};

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.788",
+  "version": "1.19.790",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.788",
+      "version": "1.19.790",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.788",
+  "version": "1.19.790",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/enroll-control-plane.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/enroll-control-plane.js — give the platform a row so its own pin can move
+// (task 1003159, ADR 0293 D2).
+//
+// WHY THIS EXISTS AT ALL. `provisioning_intents.instance_id` is NOT NULL REFERENCES
+// provisioning_instances(id), so every intent must name a row. That table has only ever
+// held tenant projects — the box this software runs on has no row — which is the
+// mechanical reason the owner had no deploy door: there was nothing to point the door at.
+//
+// IDEMPOTENT, AND ONLY EVER ONE. provisioning_instances_one_control_plane_idx makes a
+// second control-plane row impossible at the database, because "which row is me?" must
+// have exactly one answer; this script resolves the existing row and reports it rather
+// than racing that index.
+//
+// RUN ONCE PER INSTALL, by whoever already has the box — the same person who runs
+// migrations. This is deliberately NOT something the web tier does for itself: a process
+// that could mint its own control-plane row could mint a second one, and the whole value
+// of the self row is that it is a thing someone decided to create. See
+// docs/recipes/core-release-pipeline.md.
+//
+//   node scripts/gds/enroll-control-plane.js --owner <builderId> [--slug cloudbongos]
+//                                            [--port 3002] [--domain cloudbongos.com] [--apply]
+//
+// Without --apply it prints what it would do and changes nothing, matching provision.js.
+
+const { Pool } = require('pg');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+
+function arg(flag, argv, fallback = null) {
+  const i = argv.indexOf(flag);
+  return i >= 0 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : fallback;
+}
+const hasFlag = (flag, argv) => argv.includes(flag);
+
+async function enrollControlPlane(db, { ownerBuilderId, slug, port, domain, apply }) {
+  // The slug ends up as a systemd unit name and inside the runner's shell commands,
+  // so it is validated at the door rather than left to whoever runs this. The runner
+  // re-checks it at the point of use too — this one is so the operator hears about a
+  // typo now, instead of as a refused upgrade weeks later.
+  if (!isValidSlug(slug)) {
+    return { ok: false, created: false, error: `'${slug}' is not a valid slug — lowercase letters, digits and single hyphens, 2-40 characters` };
+  }
+  const { rows: existing } = await db.query(
+    "SELECT * FROM provisioning_instances WHERE hosting_shape = 'control-plane'");
+  if (existing[0]) {
+    return { ok: true, created: false, instance: existing[0], reason: 'already enrolled' };
+  }
+  if (!apply) return { ok: true, created: false, wouldCreate: { slug, port, domain, ownerBuilderId } };
+  // status 'active' because it IS active — this process is the proof. A row parked at
+  // 'requested' would be refused by the upgrade leg's own status gate, so enrolling it
+  // any other way would produce a door that is visible and permanently refuses.
+  const { rows } = await db.query(
+    `INSERT INTO provisioning_instances
+       (owner_builder_id, slug, hosting_shape, domain, port, status, onboard_mode, description)
+     VALUES ($1, $2, 'control-plane', $3, $4, 'active', 'adopt', $5)
+     RETURNING *`,
+    [ownerBuilderId, slug, domain || null, port,
+     'The control plane itself — the box this platform runs on. Enrolled so its core pin can be moved from the hall (ADR 0293); it is not a tenant project and cannot be torn down.']);
+  return { ok: true, created: true, instance: rows[0] };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (hasFlag('--help', argv)) {
+    console.log('usage: node scripts/gds/enroll-control-plane.js --owner <builderId> [--slug <slug>] [--port <port>] [--domain <domain>] [--apply]');
+    return 0;
+  }
+  const ownerBuilderId = arg('--owner', argv);
+  if (!ownerBuilderId) {
+    console.error('enroll-control-plane: --owner <builderId> is required — the self row needs an owner like any other, and an unattributed one is exactly what ADR 0293 D5 refuses.');
+    return 2;
+  }
+  const url = process.env.DATABASE_URL;
+  if (!url) { console.error('enroll-control-plane: DATABASE_URL is not set.'); return 2; }
+  const apply = hasFlag('--apply', argv);
+  const pool = new Pool({ connectionString: url });
+  try {
+    const r = await enrollControlPlane(pool, {
+      ownerBuilderId,
+      slug: arg('--slug', argv, 'cloudbongos'),
+      port: Number(arg('--port', argv, '3002')),
+      domain: arg('--domain', argv),
+      apply,
+    });
+    if (r.error) { console.error(`enroll-control-plane: ${r.error}`); return 2; }
+    if (r.created) console.log(`enrolled the control plane as instance #${r.instance.id} (${r.instance.slug}, port ${r.instance.port})`);
+    else if (r.instance) console.log(`already enrolled: instance #${r.instance.id} (${r.instance.slug}, port ${r.instance.port})`);
+    else console.log(`would enroll the control plane as ${JSON.stringify(r.wouldCreate)} — re-run with --apply`);
+    return 0;
+  } finally {
+    try { await pool.end(); } catch { /* ignore */ }
+  }
+}
+
+if (require.main === module) {
+  main().then((c) => process.exit(c)).catch((e) => { console.error(e.message); process.exit(1); });
+}
+
+module.exports = { enrollControlPlane };