@bongos/core 1.19.789 → 1.19.790

package/modules/government/migrations/government_014_core_pin_move.sql

@@ -0,0 +1,46 @@
+-- government_014_core_pin_move.sql — grant `core.pin.move` to the Archon
+-- rank-role (task 1003159, ADR 0293).
+--
+-- The atom gates the owner's deploy door: POST /provisioning/instances/:id/
+-- core-upgrade, which queues an intent the control-plane runner drains to move an
+-- instance's core pin. That is gate 3 of the release pipeline (ADR 0137) and the
+-- only act that makes shipped work visible to users.
+--
+-- ARCHON ONLY, AND system:true. Two separate statements about the same key:
+--
+--   • the FLOOR is archon because deploy is one of the hard gates the owner holds.
+--     Cloud Bongos is AI-first — agents write the code, the human holds the gates —
+--     and this task exists because that gate had no instrument, not because it
+--     should be widely held.
+--
+--   • `system: true` is what makes the floor un-delegatable. The catalog's own
+--     invariant (tests/government_catalog.mjs) forbids granting a system key to
+--     metic, so no custom rank can be handed this without clearing the flag first —
+--     a deliberate, visible edit. It sits beside `version.close` and
+--     `task.confirm.grade_bypass` for exactly the reason ADR 0157 gives about the
+--     escalation keys: a power that can be delegated downward by someone holding it
+--     is not really a gate.
+--
+-- ONLY archon is granted, so unlike government_007 this adds exactly one row.
+-- There is no metic grant to write, which is the point.
+--
+-- The compat seed (governance_002) is RUN-ONCE, so a new atom cannot be added by
+-- editing it — every already-migrated database would never see the grant. This is
+-- the follow-on grant migration that header calls for.
+--
+-- tests/governance_seed.mjs reads the UNION of the seed and every later government_*
+-- grant migration and asserts it equals catalog.js's floor-derived RANK_ROLE_SEED,
+-- so this file is what keeps the SQL snapshot equal to the catalog entry.
+--
+-- Additive, idempotent (ON CONFLICT DO NOTHING), forward-safe: INSERT only, nothing
+-- dropped or retyped, no down-migration.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'core.pin.move'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;

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

@@ -0,0 +1,64 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Deploy — {{worldName}}</title>
+  <meta name="description" content="Move this instance onto a newer core and read back the version the box actually serves — the deploy gate, without a shell or an ssh key.">
+  <link rel="icon" href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><text x='16' y='24' font-size='24' text-anchor='middle' font-family='sans-serif'>⌂</text></svg>">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
+  <link rel="stylesheet" href="/builders/oversight.css">
+  <link rel="stylesheet" href="/builders/project-settings.css">
+</head>
+<body data-page="deploy" data-page-title="Deploy">
+
+<div class="app">
+  <aside class="app-sidebar" id="app-sidebar" aria-label="Primary"></aside>
+  <div class="app-scrim" id="app-scrim" hidden></div>
+  <div class="app-body">
+    <header class="app-topbar" id="app-topbar"></header>
+    <div class="app-content">
+      <div class="page-head page-head--board">
+        <h1 class="page-head__h">Deploy</h1>
+        <p class="page-head__sub" id="dp-sub">Loading…</p>
+      </div>
+
+      <main id="hall-main">
+        <section class="scroll" id="dp-sealed" aria-labelledby="dp-sealed-h" hidden>
+          <h2 class="scroll__h" id="dp-sealed-h">Restricted</h2>
+          <p class="scroll__lede" id="dp-sealed-body">This page opens at a higher rank.</p>
+        </section>
+
+        <section class="scroll" id="dp-body" aria-labelledby="dp-body-h" hidden>
+          <h2 class="scroll__h" id="dp-body-h">What users can see</h2>
+          <!-- The honest framing, and the one thing a reader must not misread:
+               shipping work and deploying it are different acts. "Merged" does not
+               mean visible (ADR 0137's three gates); this page is the third one. -->
+          <p class="scroll__lede">
+            Merging work does not put it in front of anyone. This is the step that does:
+            it moves this instance onto a newer core, waits for the box to answer, and
+            puts itself back if it does not.
+          </p>
+          <!-- One mount, written by deploy.js. Nothing here is authored as markup with
+               a version in it: every number on this page is a reading the control plane
+               took, carrying the time it took it. -->
+          <div id="dp-panel"><span class="kit-skel"></span></div>
+        </section>
+      </main>
+
+      <footer class="app-foot" id="app-foot"></footer>
+    </div>
+  </div>
+</div>
+
+<div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
+
+<script src="/builders/shell.js?v=2026-07-02-shell1"></script>
+<script src="/builders/palette.js" defer></script>
+<script src="/builders/dom-utils.js?v=2026-06-16-gate"></script>
+<script src="/builders/hall-kit.js"></script>
+<script src="/builders/deploy.js?v=2026-09-16-deploy1"></script>
+</body>
+</html>

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

@@ -0,0 +1,188 @@
+// deploy.js — the owner's deploy door (task 1003159, ADR 0293).
+//
+// WHAT THIS PAGE IS FOR. The owner, twice in a month: "I don't think I can make anything
+// live", then "this is above my paygrade." Moving this instance's core pin is gate 3 of
+// the release pipeline and the ONLY act that makes shipped work visible to users — and it
+// was reachable from exactly one place, a shell on the control-plane box holding an ssh
+// key. An agent could not close the loop either: the permission classifier blocks a
+// mutating `sudo -u lars` over ssh by design. So the one gate that is the owner's to hold
+// was the one gate with no instrument. This page is the instrument.
+//
+// THE RULE THAT SHAPES EVERY LINE HERE: this page KNOWS NOTHING. Every version on it is a
+// reading the control-plane runner took on the box, carried through the server with the
+// time it was taken. Nothing is computed here, no version is compared here, and "up to
+// date" is never inferred from an absence — the server says `behind` or it does not, and
+// a missing reading renders as a missing reading. A deploy control that guesses is worse
+// than none, because it is trusted.
+//
+// TWO STEPS, NEVER ONE (ADR 0293 D4). The owner asked for the confirmation. Auto-rollback
+// already guards the bad release; this guards the wrong button. Step one shows what would
+// move; step two names the version it saw and sends that. The confirm button is built
+// FROM the previewed version, so a release that lands between the two steps cannot
+// silently change what the press does.
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const { escapeHtml } = window.OTB;
+  const toast = (msg) => window.OTB.toast(msg);
+  const $ = (id) => document.getElementById(id);
+
+  // The preview the server last handed us. The confirm step reads its version from HERE
+  // rather than from the DOM, so what is sent is what was previewed even if a poll
+  // repaints between the two clicks.
+  let previewed = null;
+
+  async function fetchJson(path) {
+    const res = await api.request('GET', `${API}${path}`);
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw { kind: '401' }; }
+    if (res.status === 403) { throw { kind: '403' }; }
+    if (!res.ok) {
+      const err = (res.data && res.data.error) || {};
+      throw new Error(err.message && err.message !== err.code ? err.message : (err.code || `${path} → ${res.status}`));
+    }
+    return res.data;
+  }
+
+  async function sendJson(method, path, body) {
+    const res = await api.request(method, `${API}${path}`, { body: body || {} });
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw { kind: '401' }; }
+    const data = res.data || {};
+    if (!res.ok) {
+      const err = data.error || {};
+      // The server's sentence when it wrote one — its refusals name what to do instead,
+      // and re-wording them here would lose that. Never a message invented on this page.
+      throw new Error(err.message && err.message !== err.code ? err.message : (err.code || `${path} → ${res.status}`));
+    }
+    return data;
+  }
+
+  // "3 minutes ago" for a reading's age. The age is part of the answer, not decoration:
+  // every number on this page came from a cache, and a cache rendered as though it were
+  // live is how someone is told their box is on a version it left an hour ago.
+  function ago(iso) {
+    if (!iso) return 'never';
+    const secs = Math.max(0, Math.round((Date.now() - new Date(iso).getTime()) / 1000));
+    if (secs < 90) return `${secs}s ago`;
+    const mins = Math.round(secs / 60);
+    if (mins < 90) return `${mins} min ago`;
+    return `${Math.round(mins / 60)}h ago`;
+  }
+
+  function versionHtml(v) {
+    return v ? `<span class="ov-mono">${escapeHtml(String(v))}</span>` : '<span class="ps-pill ps-pill--absent">no reading</span>';
+  }
+
+  // ---- the three states this page can be in --------------------------------
+
+  // Something is already running. The press is not offered at all — offering a button
+  // that the server will refuse with 'intent_conflict' is a worse experience than saying
+  // plainly that the box is busy.
+  function busyHtml(p) {
+    const i = p.open_intent;
+    return `
+      <p class="ov-row__sub">A <strong>${escapeHtml(i.action)}</strong> is ${escapeHtml(i.state)} for this box${
+        i.target_version ? ` (to core ${escapeHtml(i.target_version)})` : ''}.
+        Nothing else can be queued until it settles; this page will notice when it does.</p>`;
+  }
+
+  function stepOneHtml(p) {
+    return `
+      <p class="ov-row__sub">Core <strong>${escapeHtml(String(p.recommended_version))}</strong> is published and
+        this box is not on it yet.</p>
+      <div class="ps-controls">
+        <button type="button" class="btn" id="dp-preview">See what would change</button>
+      </div>`;
+  }
+
+  // Step two. The version is written into the button's own label and into `previewed`,
+  // so the owner confirms the thing they were shown rather than "the newest", which is a
+  // different act by the time it is resolved.
+  function stepTwoHtml(p) {
+    return `
+      <div class="ps-controls" id="dp-confirm-wrap">
+        <p class="ov-row__sub">This restarts the platform onto core
+          <strong>${escapeHtml(String(p.recommended_version))}</strong>. It waits for the box to answer and
+          puts itself back on ${escapeHtml(String(p.served_version))} if it does not.</p>
+        <button type="button" class="btn btn--primary" id="dp-confirm">Move to ${escapeHtml(String(p.recommended_version))}</button>
+        <button type="button" class="btn" id="dp-cancel">Cancel</button>
+      </div>`;
+  }
+
+  function panelHtml(p, step) {
+    const rows = [
+      `<li class="ov-row"><div class="ov-row__main">
+         <span class="ov-row__title">Serving now</span>
+         <p class="ov-row__sub">${versionHtml(p.served_version)} — read from the box itself, ${escapeHtml(ago(p.observed_at))}.</p>
+         ${p.reading === 'no_answer'
+           ? `<p class="ps-invalid">The box did not answer when the control plane last looked, so this version is unknown rather than unchanged. A move is not offered while that is true.</p>`
+           : ''}
+       </div></li>`,
+    ];
+    let action = '';
+    if (p.open_intent) action = busyHtml(p);
+    else if (p.reading === 'no_answer') action = '';
+    else if (!p.behind) action = `<p class="ov-row__sub">Nothing newer is published that this box can take. There is nothing to deploy.</p>`;
+    else action = step === 'confirm' ? stepTwoHtml(p) : stepOneHtml(p);
+    rows.push(`<li class="ov-row"><div class="ov-row__main">
+        <span class="ov-row__title">Make it live</span>
+        ${action}
+      </div></li>`);
+    return `<ul class="ov-lines">${rows.join('')}</ul>
+      <p class="ps-prov">reads the control plane's own observation · ADR 0293 · every move is recorded with who asked</p>`;
+  }
+
+  // ---- wiring --------------------------------------------------------------
+
+  function render(p, step) {
+    previewed = p;
+    $('dp-panel').innerHTML = panelHtml(p, step);
+    const preview = $('dp-preview');
+    if (preview) preview.addEventListener('click', () => render(p, 'confirm'));
+    const cancel = $('dp-cancel');
+    if (cancel) cancel.addEventListener('click', () => render(p, 'preview'));
+    const confirm = $('dp-confirm');
+    if (confirm) confirm.addEventListener('click', () => move(p));
+  }
+
+  async function move(p) {
+    const btn = $('dp-confirm');
+    if (btn) { btn.disabled = true; btn.textContent = 'Queueing…'; }
+    try {
+      // `p.recommended_version` — the version this owner was SHOWN, not whatever is
+      // newest at the moment of the click.
+      const r = await sendJson('POST', `/provisioning/instances/${p.instance_id}/core-upgrade`, { to: p.recommended_version });
+      toast(r.message || 'Queued.');
+      await load();
+    } catch (e) {
+      if (e && e.kind === '401') return;
+      toast(e.message || 'Could not queue the move.');
+      if (btn) { btn.disabled = false; btn.textContent = `Move to ${p.recommended_version}`; }
+    }
+  }
+
+  async function load() {
+    try {
+      const d = await fetchJson('/provisioning/control-plane');
+      $('dp-sub').textContent = `${d.preview.slug} — the box this platform runs on`;
+      $('dp-body').hidden = false;
+      render(d.preview, 'preview');
+    } catch (e) {
+      if (e && e.kind === '401') return;
+      if (e && e.kind === '403') {
+        $('dp-sealed').hidden = false;
+        $('dp-sub').textContent = 'Restricted';
+        return;
+      }
+      // Including 'control_plane_not_enrolled', whose message names the one command
+      // that fixes it — which is why the server's sentence is shown rather than a
+      // generic failure line.
+      $('dp-body').hidden = false;
+      $('dp-sub').textContent = 'Unavailable';
+      $('dp-panel').innerHTML = `<p class="ps-invalid">${escapeHtml(e.message || 'Could not read the deploy state.')}</p>`;
+    }
+  }
+
+  document.addEventListener('DOMContentLoaded', load);
+})();

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