@bongos/core 1.19.788 → 1.19.790

package/scripts/gds/provision-core-upgrade.js

@@ -0,0 +1,311 @@
+'use strict';
+
+// scripts/gds/provision-core-upgrade.js — the owner's deploy door, CONTROL-PLANE half
+// (task 1003159, ADR 0293).
+//
+// The web tier queues a 'core-upgrade' intent naming a target version and gains no new
+// capability doing so (modules/provisioning/core-upgrade.js). THIS is the half that acts:
+// the runner drains that intent and drives the proven `bongos upgrade` path, with its
+// health gate, its served-version check and its auto-rollback (task 2149) intact.
+//
+// It is a DOOR ONTO THE PROVEN PATH, NOT A SECOND UPGRADE MECHANISM. Every step that
+// could get an upgrade wrong — install, migrate, pin, restart, verify, revert — already
+// lives in upgrade.js and is exercised by every hand-run bump. Re-implementing any of it
+// here would mean two paths that must stay in step, and the one used less often would be
+// the one that rots. So this file does exactly three things upgrade.js cannot do for
+// itself: decide whether the request is ALLOWED, decide whether the target is REAL, and
+// report what the box actually serves afterwards.
+//
+// WHY THE REGISTRY CHECK LIVES HERE AND NOT ON THE ROUTE (ADR 0293 D3). Answering "is
+// this version published" means `npm view`, which update-channel.js runs via spawnSync —
+// on the single-process web server that blocks every other request for the seconds npm
+// takes. Here it is a CLI process with nothing else to serve, and blocking is free. The
+// check is not optional tidiness: the release lane mints a git tag BEFORE the npm publish
+// completes (8–13 minutes, measured 2026-09-16 — learnings 1000263/1000266), so a door
+// that trusted the request would routinely queue a version that does not exist yet and
+// fail deep inside npm with `notarget`.
+//
+// Its own file because scripts/gds/provision.js sits at the 1500-line oversized-file
+// ratchet, the same reason provision-net.js and provision-units.js were carved out.
+
+const path = require('path');
+const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
+const { standaloneRoot } = require('./provision-repo.js');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+
+// The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
+// web-tier half, and deliberately EXCLUDES 'dedicated': a dedicated droplet is stood up
+// by cloud-init and the runner has no post-hoc exec path to it, so queueing an upgrade
+// for one would be a request that is accepted and never lands. The route refuses the
+// same shape; this is the second gate, and it is the one that holds if a row's shape
+// changes between the request and the drain.
+const UPGRADE_SHAPES = Object.freeze(new Set(['co-tenant', 'standalone', 'control-plane']));
+
+// The box's own answer to "what core am I running?" — loopback, on the instance's port.
+//
+// THE APEX CANNOT BE ASKED (ADR 0293 D6). It sits behind pre-launch basic_auth and its
+// HTML rides a CDN, so a public read can report a stale or gated answer with complete
+// confidence. 127.0.0.1 is the only address that is answering FROM the process whose
+// version is in question. This is the same reasoning healthzCmd already encodes, and the
+// DONE-WHEN task 1003156 established in so many words.
+function versionCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/version`;
+}
+
+// Pull coreVersion out of whatever /version answers with.
+//
+// TOLERANT BY DESIGN, and the tolerance is load-bearing rather than lazy. This reads a
+// process that may be running a core OLDER than the one that wrote this parser — that is
+// the entire point of an upgrade — so the shape of its response is not something this
+// side gets to assume. A body it cannot read returns null, which the caller reports as
+// "could not confirm", never as a mismatch: claiming the upgrade failed because the
+// reply was unfamiliar would roll back a perfectly good deploy.
+function parseServedVersion(stdout) {
+  if (!stdout || typeof stdout !== 'string') return null;
+  try {
+    const j = JSON.parse(stdout);
+    for (const k of ['coreVersion', 'core_version', 'version']) {
+      if (typeof j[k] === 'string' && j[k].trim()) return j[k].trim();
+    }
+  } catch { /* not JSON — fall through to the text probe */ }
+  const m = stdout.match(/\b\d+\.\d+\.\d+\b/);
+  return m ? m[0] : null;
+}
+
+/**
+ * Is this target a version the instance may actually be moved to? PURE.
+ *
+ * Two separate questions, and conflating them is how a door starts lying:
+ *   • does it EXIST — is it published to the registry at all;
+ *   • is it ALLOWED — does this instance's channel policy admit it (ADR 0136).
+ *
+ * A version that exists but the channel forbids is a refusal the owner can act on
+ * ("your channel is stable and that is a prerelease"); one that does not exist yet is a
+ * refusal they can only wait out. Saying which is which is the difference between a
+ * useful message and "upgrade failed".
+ *
+ * @param {string}   to         the requested version
+ * @param {string[]} available  versions the registry reports
+ * @param {string}   installed  the version running now
+ * @param {string}   channel    this instance's update channel
+ */
+function targetFault(to, available, installed, channel, channelAllows) {
+  if (!Array.isArray(available) || available.length === 0) {
+    return `could not read the published core versions from the registry — nothing was changed; the release may still be publishing (a tag is minted before the publish completes)`;
+  }
+  if (!available.includes(to)) {
+    return `core ${to} is not published yet — nothing was changed. A release tag appears several minutes before the package itself does; try again once it lands.`;
+  }
+  if (installed && channelAllows && !channelAllows(installed, to, channel)) {
+    return `core ${to} is outside this project's '${channel}' update channel — nothing was changed. Change the channel first if this is deliberate.`;
+  }
+  return null;
+}
+
+/**
+ * Perform a queued core-pin move. Returns { ok } — NEVER throws for an expected refusal.
+ *
+ * The drain loop's catch flips the instance to 'error', which is the wrong outcome for
+ * every refusal here: a request that was never valid, or a version that is not published
+ * yet, says nothing at all about the health of a running instance. So each of those
+ * returns { ok:false, error } and the loop retries or retires the INTENT, leaving the
+ * instance exactly as it found it (ADR 0190 §2, the shape restartInstance established).
+ *
+ * @param {object} inst    the provisioning_instances row
+ * @param {object} deps    the runner's dependency bag
+ * @param {object} intent  the claimed provisioning_intents row (carries target_version)
+ */
+async function coreUpgradeInstance(inst, deps, intent) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  // A standalone's box IS the control plane's box, the same routing restartInstance and
+  // settingsApplyInstance use; a co-tenant shares this checkout.
+  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+  const to = intent && intent.target_version;
+  log(`core-upgrade ${inst.slug} → ${to || '(no target)'} (shape=${inst.hosting_shape}, status=${inst.status})`);
+
+  // ---- 1. is this request allowed at all ------------------------------------------
+  // UPGRADE_SHAPES IS THE WHOLE SHAPE CHECK. The self-row guard is deliberately not
+  // consulted: `intentAllowedForShape('core-upgrade', …)` is true for every shape
+  // there is, because 'core-upgrade' is permanently on CONTROL_PLANE_ACTIONS — so
+  // calling it here would read as a second gate while being unable to refuse
+  // anything. The guard's real job is the OTHER actions on the self row, enforced at
+  // enqueueIntent where every intent passes.
+  if (!UPGRADE_SHAPES.has(inst.hosting_shape)) {
+    return { ok: false, error: `core-upgrade is not automated for a '${inst.hosting_shape}' instance — whoever runs that machine has to upgrade it there` };
+  }
+  if (inst.status !== 'active') {
+    // Not an error: a teardown or a stand-up that raced the request must not burn the
+    // intent's retry budget, and there is no settled pin to move either way.
+    log(`  instance is '${inst.status}' — no running core whose pin can move`);
+    return { ok: true, noop: true };
+  }
+  if (!to) {
+    return { ok: false, error: 'core-upgrade intent carries no target_version — refusing to guess which version was meant' };
+  }
+  // THE SLUG IS INTERPOLATED INTO A SHELL COMMAND BELOW, so it is re-checked HERE
+  // rather than trusted. `isValidSlug` is enforced on the create route, but the
+  // control-plane self row is inserted by an operator script (enroll-control-plane.js)
+  // and any later write path is one more place that would have to remember. The value
+  // reaching a shell is this function's problem, and a format check at the point of use
+  // is the only one that cannot be bypassed by a path nobody has written yet. The other
+  // two interpolated values are already constrained — the version by the column's own
+  // CHECK and by VERSION_RE, the actor by the digits-only extraction below.
+  if (!isValidSlug(inst.slug)) {
+    return { ok: false, error: `instance slug '${inst.slug}' is not a valid slug — refusing to build a command from it` };
+  }
+
+  // ---- 2. is the target real, and permitted -----------------------------------------
+  const channelMod = deps.updateChannel || require('./update-channel.js');
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  const readInstalled = deps.readInstalledCoreVersion || require('./upgrade.js').readInstalledCoreVersion;
+  const installed = readInstalled(instanceDir);
+  // THE PLATFORM DEFAULT, NOT A PER-INSTANCE CHANNEL — and saying so beats implying
+  // otherwise. provisioning_instances carries no channel column; the subscription
+  // roster update-channel.js reads is a control-plane file, not a per-row setting. So
+  // this bounds every instance by the same policy (DEFAULT_CHANNEL: patch-only), which
+  // is a real bound — it refuses a prerelease or a major jump — and is the honest one
+  // available today. When a per-instance channel lands, this line is where it is read;
+  // writing `inst.update_channel ||` now would only have created a guard that reads as
+  // present and can never fire, which is the trap the web-tier half already documents.
+  const channel = channelMod.normalizeChannel(channelMod.DEFAULT_CHANNEL);
+  const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
+  const available = (listed && listed.versions) || [];
+  const fault = targetFault(to, available, installed, channel, channelMod.channelAllows);
+  if (fault) return { ok: false, error: fault };
+  if (installed && installed === to) {
+    // `bongos upgrade` would no-op on this too, but saying so here keeps a re-drained
+    // intent from restarting a healthy service to land exactly where it already is.
+    log(`  already serving core ${to} — nothing to move`);
+    return { ok: true, noop: true };
+  }
+
+  // ---- 3. drive the proven path -----------------------------------------------------
+  // Exactly the invocation docs/recipes/core-release-pipeline.md gate 3 documents, plus
+  // the two attribution flags (ADR 0293 D5). --commit-pin is NOT optional here: without
+  // it the pin lives only in the working tree, and the next pull-deploy resets it away —
+  // the silent thirteen-release revert upgrade.js's own header records.
+  const healthUrl = `http://127.0.0.1:${inst.port}/healthz`;
+  const versionUrl = `http://127.0.0.1:${inst.port}/version`;
+  const sudoP = privileged ? 'sudo ' : '';
+  const cli = path.posix.join('scripts', 'gds', 'upgrade.js');
+  const requestedBy = intent.requested_by && /^api:archon:(\d+)$/.test(intent.requested_by)
+    ? intent.requested_by.replace(/^api:archon:/, '')
+    : '';
+  const cmd = [
+    `${sudoP}node ${cli}`,
+    '--registry',
+    `--to ${to}`,
+    `--service ${inst.slug}`,
+    `--health-url ${healthUrl}`,
+    `--version-url ${versionUrl}`,
+    '--commit-pin',
+    requestedBy ? `--requested-by ${requestedBy}` : '',
+    requestedBy ? '--upgrade-source owner-control' : '',
+  ].filter(Boolean).join(' ');
+
+  if (!apply) {
+    log(`  ✓ would run: ${cmd} (dry-run — nothing ran)`);
+    log(`  ✓ would then read ${versionUrl} on the box and require it to say ${to}`);
+    return { ok: true, served: null };
+  }
+  try {
+    log(`  [upgrade] ${cmd}`);
+    boxExec(cmd, { cwd: instanceDir });
+  } catch (e) {
+    // upgrade.js rolls itself back on a failed health check or an unchanged served
+    // version, so by the time this throws the instance is back on the core it had.
+    // ok:false, never a throw: the instance is healthy and must not be marked broken.
+    return { ok: false, error: `core upgrade to ${to} failed and was rolled back: ${(e && e.message) || e}` };
+  }
+
+  // ---- 4. read back what the BOX serves (ADR 0293 D6) --------------------------------
+  // With the same patience the manifest probe uses: the service has just restarted and a
+  // single immediate read races it binding its port. A false "did not take" here is
+  // never cosmetic — it is what the owner is shown after the one act they were told they
+  // could finally perform.
+  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let served = null;
+  for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
+    const res = boxExec(versionCmd(inst), { allowFail: true });
+    served = parseServedVersion(res && !res.softFailed ? (res.stdout || '') : null);
+    if (served) break;
+    if (i < MANIFEST_VERIFY_TRIES - 1) await sleep(MANIFEST_VERIFY_INTERVAL_MS);
+  }
+  if (served && served !== to) {
+    // upgrade.js's own --version-url gate should have caught and reverted this, so
+    // reaching here means the two disagree. Report what was SEEN rather than a verdict.
+    return { ok: false, error: `the box is serving core ${served}, not the requested ${to} — the move did not take` };
+  }
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'core-upgraded',
+    detail: served ? `core pin moved to ${served}` : `core pin moved to ${to}; the box did not answer /version, so this is unconfirmed`,
+    actor: intent.requested_by || 'runner',
+  }).catch(() => {});
+  if (provisioning.clearErrorNote) await provisioning.clearErrorNote(db, inst.id).catch(() => {});
+  log(served ? `  ✓ ${inst.slug} serves core ${served}` : `  ⚠ ${inst.slug} upgraded to ${to}, but did not answer /version — unconfirmed`);
+  return { ok: true, served, confirmed: served === to };
+}
+
+/**
+ * Observe one instance and cache what the deploy control needs, without acting.
+ *
+ * Runs on every drain tick for each upgradable instance. Both facts it records are ones
+ * the web tier cannot reach for itself — the served version lives on loopback, the
+ * available versions need a blocking `npm view` (migration core_242 says why at length)
+ * — so this is the runner reporting on behalf of a process that may only ask.
+ *
+ * BEST-EFFORT, ALWAYS. A registry hiccup or a box that will not answer must never fail a
+ * tick that has real work in it: the snapshot simply keeps its previous value and its
+ * previous, now-visibly-older, observed_at. That staleness is the honest signal, and it
+ * is why observed_at is stored rather than assumed.
+ */
+async function snapshotCoreVersions(inst, deps) {
+  const { db, exec, log } = deps;
+  if (!UPGRADE_SHAPES.has(inst.hosting_shape) || inst.status !== 'active') return { ok: true, skipped: true };
+  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+  const channelMod = deps.updateChannel || require('./update-channel.js');
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  try {
+    const probe = boxExec(versionCmd(inst), { allowFail: true });
+    const served = parseServedVersion(probe && !probe.softFailed ? (probe.stdout || '') : null);
+    const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
+    const available = (listed && listed.versions) || [];
+    // What the channel would take FROM the version the box is actually on. Resolving it
+    // here rather than in the browser is what keeps the button's promise and the
+    // runner's behaviour the same sentence.
+    // resolveChannelTarget returns the bare version string, or null when the channel
+    // admits nothing newer — "already current" and "nothing to take" are the same
+    // answer here, and both correctly leave `recommended` NULL.
+    const recommended = served
+      ? channelMod.resolveChannelTarget({ installed: served, channel: channelMod.DEFAULT_CHANNEL, available })
+      : null;
+    await db.query(
+      `INSERT INTO core_version_snapshot (instance_id, served_version, available, recommended, observed_at)
+       VALUES ($1, $2, $3::jsonb, $4, now())
+       ON CONFLICT (instance_id) DO UPDATE
+         SET served_version = EXCLUDED.served_version, available = EXCLUDED.available,
+             recommended = EXCLUDED.recommended, observed_at = now()`,
+      [inst.id, served, JSON.stringify(available), recommended || null]);
+    return { ok: true, served, available: available.length };
+  } catch (e) {
+    log(`  ~ core-version snapshot for ${inst.slug} skipped (${(e && e.message) || e})`);
+    return { ok: true, skipped: true };
+  }
+}
+
+/** Snapshot every instance whose box the runner can reach. Never throws. */
+async function snapshotAllCoreVersions(deps) {
+  const { db, log } = deps;
+  const shapes = [...UPGRADE_SHAPES];
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_instances WHERE status = 'active' AND hosting_shape = ANY($1)`, [shapes]);
+  let seen = 0;
+  for (const inst of rows) {
+    const r = await snapshotCoreVersions(inst, deps);
+    if (r && !r.skipped) seen++;
+  }
+  if (seen) log(`core-version snapshot: refreshed ${seen} instance(s)`);
+  return { seen };
+}
+
+module.exports = { UPGRADE_SHAPES, versionCmd, parseServedVersion, targetFault, coreUpgradeInstance, snapshotCoreVersions, snapshotAllCoreVersions };

package/scripts/gds/provision.js

@@ -56,6 +56,7 @@ const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dns
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
+const { coreUpgradeInstance, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
 
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   // `shown` (task 1003140): what to LOG in place of the command text — for a command
@@ -1238,6 +1239,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'settings-apply') result = await settingsApplyInstance(inst, deps);
       else if (intent.action === 'restart') result = await restartInstance(inst, deps);
       else if (intent.action === 'disconnect') result = await disconnectInstance(inst, deps);
+      else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
       else result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
@@ -1260,8 +1262,8 @@ async function cmdRunIntents(deps) {
       errors++; log(`  ✖ intent #${intent.id}: ${e.message}`);
     }
   }
-  // Same tick: convert + place any GitHub-App-Manifest creds awaiting the control plane.
-  const m = await drainOAuthManifests(deps);
+  await snapshotAllCoreVersions(deps); // refresh what the deploy control reads, AFTER the drain (ADR 0293 D3/D6)
+  const m = await drainOAuthManifests(deps); // same tick: convert + place any GitHub-App-Manifest creds awaiting the control plane
   log(`done — ran=${ran} ok=${ok} errors=${errors}; oauth-manifest converted=${m.converted} errors=${m.errors}`);
   return { ran, ok, errors, manifests: m };
 }

package/scripts/gds/upgrade.js

@@ -746,7 +746,33 @@ function restartService({ service, restartCmd }, run = spawnSync, deps = {}) {
   return { ok: null, skipped: true };
 }
 
-const LEDGER_INSERT_COLS = 'INSERT INTO core_upgrades (from_version, to_version, source_commit, note)';
+// The two attribution columns migration core_241 adds (task 1003159, ADR 0293 D5).
+//
+// APPENDED ONLY WHEN THE CALLER SUPPLIES THEM, and that conditionality is the whole
+// design rather than laziness. An upgrade run the old way — a human at a shell — has
+// no builder to attribute, and this file also runs ON instances whose DB may not have
+// core_241 yet (the core upgrades itself; the migration lands during the very run that
+// would be writing this row). Naming a column that does not exist turns a best-effort
+// ledger append into a hard `column "source" does not exist`, so the bump would report
+// a failure over bookkeeping. Absent → the original four-column INSERT, byte for byte.
+//
+// The DB is still the backstop: core_upgrades_door_needs_actor_chk refuses a row that
+// claims source='owner-control' without an actor, so a caller that passes one and not
+// the other is rejected there rather than landing an unattributable privileged row.
+const LEDGER_ACTOR_COLS = Object.freeze(['requested_by_builder_id', 'source']);
+
+// Build the INSERT for the columns this call actually has. Returns the statement plus
+// the ordered values, so the two connection paths below cannot drift apart.
+function ledgerInsert({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source }) {
+  const cols = ['from_version', 'to_version', 'source_commit', 'note'];
+  const vals = [fromVersion || null, toVersion, sourceCommit || null, note || null];
+  if (requestedByBuilderId != null || source) {
+    cols.push(...LEDGER_ACTOR_COLS);
+    vals.push(requestedByBuilderId != null ? String(requestedByBuilderId) : null, source || null);
+  }
+  const holders = cols.map((_, i) => `$${i + 1}`).join(',');
+  return { sql: `INSERT INTO core_upgrades (${cols.join(', ')}) VALUES (${holders})`, cols, vals };
+}
 
 // Best-effort append to the core_upgrades ledger (migration core_189). Resolves the DB the same two
 // ways a consumer might connect:
@@ -759,10 +785,11 @@ const LEDGER_INSERT_COLS = 'INSERT INTO core_upgrades (from_version, to_version,
 // Skips silently only when NEITHER is present (a local rehearsal with no DB pointed at) — the bump's
 // verification never depends on the ledger. An attempted-but-failed insert returns skipped:false so
 // the caller can surface it (the manual-INSERT footgun from 1976), never lose it.
-async function recordLedger({ fromVersion, toVersion, sourceCommit, note }, deps = {}) {
+async function recordLedger({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source }, deps = {}) {
   const url = deps.databaseUrl !== undefined ? deps.databaseUrl : process.env.DATABASE_URL;
   const database = deps.pgDatabase !== undefined ? deps.pgDatabase : process.env.PGDATABASE;
   if (!url && !database) return { ok: false, skipped: true, reason: 'no DATABASE_URL or PGDATABASE' };
+  const stmt = ledgerInsert({ fromVersion, toVersion, sourceCommit, note, requestedByBuilderId, source });
 
   // DATABASE_URL path: the pg driver with a bound-parameter query (no psql client needed).
   if (url) {
@@ -770,10 +797,7 @@ async function recordLedger({ fromVersion, toVersion, sourceCommit, note }, deps
     try { ({ Pool } = deps.pg || require('pg')); } catch { return { ok: false, skipped: true, reason: 'pg not resolvable' }; }
     const pool = new Pool({ connectionString: url });
     try {
-      await pool.query(
-        `${LEDGER_INSERT_COLS} VALUES ($1,$2,$3,$4)`,
-        [fromVersion || null, toVersion, sourceCommit || null, note || null]
-      );
+      await pool.query(stmt.sql, stmt.vals);
       return { ok: true };
     } catch (e) {
       return { ok: false, skipped: false, reason: e.message };
@@ -790,15 +814,23 @@ async function recordLedger({ fromVersion, toVersion, sourceCommit, note }, deps
   // literal `:'from_version'` and syntax-error — psql only interpolates variables in script/stdin
   // mode. ON_ERROR_STOP=1 guarantees a non-zero exit on any SQL error.
   const run = deps.run || spawnSync;
-  const sql = `${LEDGER_INSERT_COLS}\n  VALUES (NULLIF(:'from_version',''), :'to_version', NULLIF(:'source_commit',''), NULLIF(:'note',''));\n`;
+  // Built from the SAME column list the pg path uses, so the two cannot drift.
+  // to_version is the one NOT NULL column, hence the one without a NULLIF; the
+  // builder id is text on the wire (a psql :'var' is always a quoted literal) and
+  // casts at the DB, which also rejects anything non-numeric rather than coercing.
+  const psqlValue = (col) => {
+    if (col === 'to_version') return `:'${col}'`;
+    if (col === 'requested_by_builder_id') return `NULLIF(:'${col}','')::bigint`;
+    return `NULLIF(:'${col}','')`;
+  };
+  const sql = `${stmt.sql.slice(0, stmt.sql.indexOf(' VALUES '))}\n  VALUES (${stmt.cols.map(psqlValue).join(', ')});\n`;
+  const sets = [];
+  for (let i = 0; i < stmt.cols.length; i++) sets.push('--set', `${stmt.cols[i]}=${stmt.vals[i] == null ? '' : stmt.vals[i]}`);
   const r = run('psql', [
     '-d', database,
     '-v', 'ON_ERROR_STOP=1',
     '-q', '--no-psqlrc',
-    '--set', `from_version=${fromVersion || ''}`,
-    '--set', `to_version=${toVersion || ''}`,
-    '--set', `source_commit=${sourceCommit || ''}`,
-    '--set', `note=${note || ''}`,
+    ...sets,
   ], { encoding: 'utf8', input: sql });
   if (!r || r.error) {
     const enoent = !!(r && r.error && r.error.code === 'ENOENT');
@@ -1031,7 +1063,7 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   // 5. record the reversal in the ledger via the always-present `note` column (no schema
   //    dependency — so it records even when a FAILED migrate means a newer column wouldn't exist).
   const note = `rolled_back: ${reason} (attempted ${fromVersion || '(none)'} → ${toVersion}, restored ${snapshot.prevVersion || 'previous'})`;
-  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note }, deps);
+  const ledger = await recordLedger({ fromVersion, toVersion, sourceCommit: opts.sourceCommit, note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
   if (ledger.ok) log('  ✓ recorded rollback in core_upgrades ledger');
   else if (ledger.skipped) log(`  • rollback ledger skipped (${ledger.reason})`);
   else err(`  ! rollback ledger insert failed (${ledger.reason}) — record it manually`);
@@ -1310,7 +1342,7 @@ async function runUpgrade(opts, deps = {}) {
     return { ok: false, error: `${why} — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, rolledBack: true, rollback: rb };
   }
 
-  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note }, deps);
+  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
   if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
   else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
   else err(`  ! ledger insert failed (${ledger.reason}) — record it manually`);
@@ -1354,6 +1386,13 @@ function parseArgs(argv) {
     versionUrl: arg('--version-url', argv), // task 1002884: read the LIVE process's coreVersion back; defaults to /version on the health URL's origin
     sourceCommit: arg('--source-commit', argv),
     note: arg('--note', argv),
+    // Who asked, and through which door (task 1003159, ADR 0293 D5). Both reach the
+    // core_upgrades row so a privileged act that an HTTP request could start is never
+    // unattributable. Omitted on a hand-run bump, where there is no builder to name —
+    // and omitting them keeps the INSERT on its pre-core_241 four columns, which is
+    // what lets this script keep working against an instance DB that has not migrated.
+    requestedBy: arg('--requested-by', argv),
+    upgradeSource: arg('--upgrade-source', argv),
     pinPath: arg('--pin-path', argv),
     registry: hasFlag('--registry', argv), // ADR 0134: pull @bongos/core@<--to> from the npm registry instead of vendoring
     commitPin: hasFlag('--commit-pin', argv), // task 1002712: commit + push package.json/-lock so a pull-deploy reset cannot revert the bump
@@ -1419,7 +1458,7 @@ module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
   vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, API_ARTIFACT_FILES, preflightDbIdentity,
-  resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
+  resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, ledgerInsert, LEDGER_ACTOR_COLS, pollHealth, deriveVersionUrl, pollServedVersion,
   resolvePinPushAuth, remoteGithubRepo, pinnedDeployKey, // task 1003081 — the pin push prefers the owner's GitHub token (ADR 0176 follow-up)
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT, vendorRelFor,

package/src/bongos/auth.js

@@ -451,6 +451,17 @@ const PAGE_GATES = Object.freeze({
   // members who can cast a vote through the API and cannot load the page they
   // would cast it on. That is the code-path change ADR 0175 §6 exists to remove.
   requireBoardVotePage: Object.freeze({ permission: 'board.vote.cast', deniedTo: '/builders' }),
+  // The /deploy page (task 1003159, ADR 0293) — gated on `core.pin.move`, the SAME
+  // atom both its routes check, so the shell can never drift wider or narrower than
+  // the action it fronts. That atom is archon-floor AND system:true, making this the
+  // narrowest gate in the table, which is correct for the one page whose button
+  // restarts the live service and changes what code the platform runs.
+  //
+  // The page's READ is gated identically to its write, and that is deliberate: the
+  // preview discloses the exact core version the box serves and how far behind it is
+  // — a vulnerability window, and exactly the kind of topology ADR 0043 keeps off
+  // unauthenticated surfaces.
+  requireCorePinPage: Object.freeze({ permission: 'core.pin.move', deniedTo: '/builders' }),
 });
 
 // The `alsoAdmits` door — "is this visitor the page's OTHER audience?", asked of
@@ -620,6 +631,13 @@ async function requireBoardVotePage(req, res, next) {
   return runPageGate('requireBoardVotePage', req, res, next);
 }
 
+// The /deploy page (ADR 0293) — the owner's deploy door. Gated on `core.pin.move`,
+// the same atom the preview and the move both check, so this layer decides only who
+// receives the shell and never becomes the authority (ADR 0016).
+async function requireCorePinPage(req, res, next) {
+  return runPageGate('requireCorePinPage', req, res, next);
+}
+
 // ---------------------------------------------------------------------------
 // Route-gate inventory (V3.R06 #231) — the canonical "who can call what" list.
 // Derived from ADR 0016's fail-closed rule: privileged routes that mutate
@@ -909,6 +927,7 @@ module.exports = {
   requireGovernmentPage,
   requireProjectCuratePage,
   requireBoardVotePage,
+  requireCorePinPage,
   requireRank,
   rankMeetsThreshold,
   requirePermission,

package/src/bongos/serve-internal.js

@@ -973,6 +973,23 @@ function mountInternalSurfaces(app) {
   // exact permission its data route (GET /scouting) checks — same posture as the
   // /government tab above (the page can never drift wider than the API it fronts).
   const PEOPLE_PAGE_RE = /^\/builders\/people(?:\.html)?\/?$/;
+  // /deploy — the owner's deploy door (task 1003159, ADR 0293). Gated on the
+  // `core.pin.move` atom, the same key its preview and its move both check, so the
+  // shell's reach equals the right to press the button. Archon-floor and system:true,
+  // which makes this the narrowest page gate here — correct for the one surface whose
+  // button restarts the live service and changes what code the platform runs.
+  //
+  // DECLARED HERE, WITH THE OTHER GATES, AND NOT BELOW: the SCOUTING_LEGACY_RE block
+  // that follows is a matcher immediately followed by the redirect it feeds, and
+  // tests/hall_roster_world.mjs reads them as one span. Wedging a declaration between
+  // the two separates a matcher from its handler for a reader as well as for that test.
+  //
+  // NB as at PROJECT_SETTINGS_PAGE_RE: this assignment must stay
+  // `const NAME_RE = /…/;` with nothing between the `=` and the literal —
+  // tests/hall_page_gate_map.mjs rebuilds the URL→gate map by parsing this file
+  // statically, and a comment in that gap makes the page test as UNGATED while
+  // looking gated here. Prose goes above the const, as here.
+  const DEPLOY_PAGE_RE = /^\/builders\/deploy(?:\.html)?\/?$/;
   // /scouting WAS the legacy twin of /people — the same /api/gds/scouting
   // directory, left behind when task 1002577 graduated it into the hall. Task
   // 1003470 had already made the two one page (scouting.html rendered people's
@@ -1019,6 +1036,10 @@ function mountInternalSurfaces(app) {
     if (PEOPLE_PAGE_RE.test(norm)) {
       return gdsAuth.requireProjectCuratePage(req, res, next);
     }
+    // ADR 0293: the deploy door, on the same atom its two routes check.
+    if (DEPLOY_PAGE_RE.test(norm)) {
+      return gdsAuth.requireCorePinPage(req, res, next);
+    }
     next();
   });
 

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.788'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.790'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/auth_resolve_failure.mjs

@@ -96,16 +96,18 @@ test('AUDIT: every async middleware mounted directly on a router owns its reject
   //   requireGovernmentPage      \ all FOUR delegate to runPageGate, guarded by
   //   requireProjectCuratePage   /  BV1.R107 (the /people curate gate; the
   //   requireBoardVotePage      /   ADR 0266 /board-room vote gate)
+  //   requireCorePinPage        /   ADR 0293's /deploy door — the narrowest of them,
+  //                                 on the archon-floor `core.pin.move` atom.
   // Task 1003450 removed two more — requireNonXenosPage and the R113
   // requireGovernmentManagePage — which had both ended up dispatched from no
   // route at all; tests/hall_page_gate_map.mjs now fails if that recurs.
   // Anything else async and router-mounted must be added with its own try/catch.
   const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'auth.js'), 'utf8');
   const asyncMw = [...src.matchAll(/^async function (require\w+|allow\w+)\s*\(req, res, next\)/gm)].map((m) => m[1]);
-  assert.deepEqual(asyncMw.sort(), ['requireBoardVotePage', 'requireBuilder', 'requireBuilderPage', 'requireGovernmentPage', 'requireProjectCuratePage'],
+  assert.deepEqual(asyncMw.sort(), ['requireBoardVotePage', 'requireBuilder', 'requireBuilderPage', 'requireCorePinPage', 'requireGovernmentPage', 'requireProjectCuratePage'],
     'a new async router middleware appeared — give it a try/catch and add it here');
   // The page gates must actually delegate (that is WHY they are safe).
-  for (const name of ['requireBuilderPage', 'requireGovernmentPage', 'requireProjectCuratePage', 'requireBoardVotePage']) {
+  for (const name of ['requireBuilderPage', 'requireGovernmentPage', 'requireProjectCuratePage', 'requireBoardVotePage', 'requireCorePinPage']) {
     const fn = src.slice(src.indexOf(`async function ${name}`));
     assert.match(sliceFn(fn), /runPageGate\(/, `${name} must delegate to the guarded runPageGate`);
   }