@bongos/core 1.19.789 → 1.19.791

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.789",
+  "version": "1.19.791",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.789",
+      "version": "1.19.791",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.789",
+  "version": "1.19.791",
   "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/accessibility-replay.js

@@ -0,0 +1,195 @@
+// scripts/gds/accessibility-replay.js — the two-profile replay regression for the
+// accessibility dimension (task 1002517; clauses 5 and 8 of criterion
+// `accessibility-fluency-profile`, which named this run as its OWN proof).
+//
+// WHAT IT PROVES, and why it is not already covered.
+// tests/session_accessibility.mjs pins the scorer's contracts against synthetic
+// fixtures it builds itself — a test of the arithmetic. It cannot answer the
+// criterion's actual question, which is about PROSE: does the dimension reward a
+// reply a newcomer can use, and does it leave an expert's reply alone? So this
+// harness takes a FIXED set of eight questions a newcomer really asks, each the
+// documented trigger of a surface that exists, answered twice — once in each
+// register — and scores both runs.
+//
+// Four legs. Each one fails a different way of being wrong:
+//
+//   1. FLOOR          the non-technical run, under the non-technical profile,
+//                     clears FLOOR. The dimension recognises accessible prose.
+//   2. NO PENALTY     the engineer run, under the engineer profile, is not
+//                     scored at all — every signal waived, score null.
+//   3. DISCRIMINATION the SAME engineer prose under the NON-TECHNICAL profile
+//                     falls BELOW FLOOR, with every detector registering hits.
+//                     Without this leg 1 proves nothing — a scorer that returned
+//                     10 for everything, or three detectors that had gone blind,
+//                     would pass leg 1 and look identical to a working one.
+//   4. LENGTH         `doubleRun` says the same prose twice. Chars double, hits
+//                     double, the rate is unchanged, so the score must be
+//                     IDENTICAL. That is the metric reading density rather than
+//                     volume, asserted against real prose.
+//
+// WHERE TERSENESS PROTECTION ACTUALLY COMES FROM, since the task's "watch out"
+// is a metric that punishes an expert's brevity. It is leg 2 — the WAIVER — not
+// the per-1000-character rates. The rates make the score independent of how long
+// an answer is at a fixed density (leg 4); they do NOT make it independent of
+// density, and they should not: three undefined terms in three hundred
+// characters really is denser than three in three thousand. What protects the
+// expert is that their profile removes those two signals from the scoring set
+// entirely. `terseVariant` — every turn cut to its first sentence, a genuinely
+// shorter and thinner answer — is checked too, asserting only that answering
+// more briefly never COSTS points; it is a guard, not the mechanism.
+//
+// One honest asymmetry this surfaced and the corpus now records: under
+// `technical_level: engineer` with `toolchain_familiarity: new`, the engineer
+// run still scores, because terminal-where-a-click-path-exists is waived by the
+// TOOLCHAIN setting, not the technical one. "I think in code" and "I live in a
+// terminal" are two different answers, and the scorer is right to keep them
+// apart. tests/accessibility_replay.mjs pins that pairing so a future widening
+// of the engineer waiver has to be a deliberate edit.
+//
+// The corpus is data — tests/fixtures/accessibility-replay.json — so adding a
+// prompt is an edit to JSON, not to code.
+//
+// Run:  node scripts/gds/accessibility-replay.js
+//       node scripts/gds/accessibility-replay.js --json
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { scoreAccessibility, bandFor } = require('../../modules/sessions/accessibility.js');
+
+const CORPUS_PATH = path.join(__dirname, '..', '..', 'tests', 'fixtures', 'accessibility-replay.json');
+
+// FLOOR — the score a non-technical run has to clear. It is bandFor()'s
+// 'workable' boundary and deliberately not a second independent number: the
+// scorer already draws the line between prose a newcomer can work with and prose
+// that is merely dense, and inventing a different one here would let the two
+// drift. tests/accessibility_replay.mjs asserts they stay tied.
+const FLOOR = 6.0;
+
+function loadCorpus(file = CORPUS_PATH) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+// terseVariant — each turn cut to its first sentence: a shorter, thinner answer.
+// Mechanical on purpose. A hand-written "terse version" in the corpus would be a
+// version tuned until it passed; taking the first sentence of prose written for
+// another purpose is a variant nobody got to tune.
+function terseVariant(turns) {
+  return turns.map((t) => {
+    const m = /^[^.!?]*[.!?]/.exec(t);
+    return m ? m[0] : t;
+  });
+}
+
+// doubleRun — the same prose said twice. Every count doubles and so does the
+// character total, so every rate is unchanged and the score must come back
+// EXACTLY equal. This is the length-independence property at prose altitude: a
+// scorer that had drifted to absolute counts would double its penalties here.
+function doubleRun(turns) {
+  return [...turns, ...turns];
+}
+
+// asDetail — a run's replies as the per-turn digest shape scoreAccessibility
+// reads. The user turns are included because a real digest has them and
+// assistantProse must keep ignoring them; if it ever stopped, the prompts would
+// start scoring the builder's own words and every number here would move.
+function asDetail(corpus, replies, { transform } = {}) {
+  const detail = [];
+  let i = 0;
+  for (const { id, prompt } of corpus.prompts) {
+    detail.push({ i: i++, role: 'user', snippet: prompt });
+    const turns = replies[id] || [];
+    for (const snippet of transform ? transform(turns) : turns) {
+      detail.push({ i: i++, role: 'assistant', snippet });
+    }
+  }
+  return detail;
+}
+
+const TRANSFORMS = { terse: terseVariant, doubled: doubleRun };
+
+// replay — score one named run under one profile. `profile` defaults to the
+// run's own declared profile, which is the pairing the criterion asks about;
+// passing another is how leg 3 reads engineer prose as a newcomer would.
+function replay(corpus, runName, { profile, variant } = {}) {
+  const run = corpus.runs[runName];
+  if (!run) throw new Error(`no such run in the corpus: ${runName}`);
+  const transform = variant ? TRANSFORMS[variant] : undefined;
+  if (variant && !transform) throw new Error(`no such variant: ${variant}`);
+  const effective = profile || run.profile;
+  const result = scoreAccessibility(asDetail(corpus, run.replies, { transform }), { profile: effective });
+  return { run: runName, variant: variant || 'full', profile: effective, result };
+}
+
+// The partial engineer profile — thinks in code, new to the toolchain. Named
+// here because it is the pairing that shows the two waivers are independent.
+const ENGINEER_NEW_TO_TOOLCHAIN = Object.freeze({ technical_level: 'engineer', toolchain_familiarity: 'new' });
+
+function rows(corpus) {
+  const newcomer = corpus.runs.non_technical.profile;
+  return [
+    ['non-technical prose, non-technical profile', replay(corpus, 'non_technical')],
+    ['engineer prose, engineer profile', replay(corpus, 'engineer')],
+    ['engineer prose, NON-TECHNICAL profile', replay(corpus, 'engineer', { profile: newcomer })],
+    ['engineer prose, engineer but new to the terminal', replay(corpus, 'engineer', { profile: ENGINEER_NEW_TO_TOOLCHAIN })],
+    ['non-technical prose, said twice', replay(corpus, 'non_technical', { variant: 'doubled' })],
+    ['non-technical prose, first sentences only', replay(corpus, 'non_technical', { variant: 'terse' })],
+  ];
+}
+
+function fmt(n) {
+  return n == null ? '—' : n.toFixed(1);
+}
+
+function formatReport(corpus) {
+  const lines = [`accessibility replay — ${corpus.prompts.length} fixed beginner prompts, floor ${FLOOR.toFixed(1)}`, ''];
+  for (const [label, r] of rows(corpus)) {
+    const { score, band, sampled_chars: chars, sampled_turns: turns } = r.result;
+    const waived = r.result.signals.filter((s) => s.waived).length;
+    lines.push(
+      `  ${label.padEnd(48)} ${fmt(score).padStart(5)}  ${band.padEnd(9)} ` +
+        `${String(turns).padStart(3)} turns  ${String(chars).padStart(5)} chars  ${waived}/3 waived`
+    );
+    for (const s of r.result.signals) {
+      if (s.waived) continue;
+      if (!s.count) continue;
+      lines.push(
+        `      ${s.type.padEnd(28)} ${String(s.count).padStart(2)} hits  rate ${s.rate.toFixed(2)}/1k  −${s.penalty.toFixed(2)}`
+      );
+    }
+  }
+  return lines.join('\n');
+}
+
+// main — the CLI. `write` is injectable so the test can exercise both output
+// paths without printing a screenful of JSON into the test log.
+function main(argv = process.argv.slice(2), write = (s) => process.stdout.write(s)) {
+  const corpus = loadCorpus();
+  if (argv.includes('--json')) {
+    const out = { floor: FLOOR };
+    for (const [label, r] of rows(corpus)) out[label] = r.result;
+    write(`${JSON.stringify(out, null, 2)}\n`);
+    return 0;
+  }
+  write(`${formatReport(corpus)}\n`);
+  return 0;
+}
+
+module.exports = {
+  FLOOR,
+  CORPUS_PATH,
+  ENGINEER_NEW_TO_TOOLCHAIN,
+  loadCorpus,
+  terseVariant,
+  doubleRun,
+  asDetail,
+  replay,
+  rows,
+  formatReport,
+  bandFor,
+  main,
+};
+
+if (require.main === module) process.exit(main());

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