@bongos/core 1.19.773 → 1.19.774

package/scripts/gds/provision-config.js

@@ -177,16 +177,16 @@ function loadDeps() {
   // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
   // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
   // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
-  let platformIdentity = null, hubKeys = null;
+  let platformIdentity = null, hubKeys = null, projectCatalog = null;
   const PI_KEY = 'platform-identity';
   let piEnabled = false;
   try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
   if (piEnabled) {
     const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
-    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
-    catch { platformIdentity = null; hubKeys = null; }
+    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); projectCatalog = require(path.join(piBase, 'project-catalog')); }
+    catch { platformIdentity = null; hubKeys = null; projectCatalog = null; }
   }
-  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
+  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog };
   return _deps;
 }
 

package/scripts/gds/provision-disconnect.js

@@ -0,0 +1,90 @@
+'use strict';
+// provision-disconnect.js — "Disconnect from Bongos entirely": the runner leg (task 1003249,
+// ADR 0290).
+//
+// WHY. A teardown deliberately KEEPS a project's database, dumps and address (ADR 0181), so
+// taking a project offline is always reversible. The owner asked for a separate, truer delete.
+// This is it, and it is the exception ADR 0181 names: owner-initiated only, behind a typed-name
+// confirm the route checks server-side (modules/provisioning/routes/disconnect.js).
+//
+// ORDER IS THE SAFETY PROPERTY. The teardown runs first (units stopped, Caddy block gone, DNS
+// parked, deploy key revoked). Then the erase. Then the catalog, membership and client rows
+// leave the map. The provisioning row is deleted LAST, and only when everything before it
+// succeeded: the row is what lets the runner retry, so a failure anywhere leaves the row intact
+// (an erase or forget failure returns a retryable { ok:false }; a teardown throw propagates).
+// Deleting the row is what releases the name (slug UNIQUE), the port (allocatePort reads every
+// row) and the address (the next standup UPSERTs it).
+//
+// The GitHub repository is never touched, and neither is the GitHub App the owner registered for
+// sign-in — GitHub offers no API to delete an App; the manage page tells the owner where it is.
+
+const path = require('node:path');
+const { CONFIG } = require('./provision-config.js');
+const { dbName, instanceDbRole, instanceStateDir, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const { webEnvPath } = require('./provision-units.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+const { catalogOriginForInstance, ownerGithubIdForInstance } = require('../../modules/provisioning/catalog-bridge.js');
+const { deleteInstance } = require('../../modules/provisioning/disconnect.js');
+
+// The dump filename db-backup-nightly.sh writes — <db>-YYYY-MM-DDTHHMMSSZ.sql.gz — matched
+// EXACTLY. The nightly prune's own `<db>-*.sql.gz` would let a project named `test` erase
+// `test-nk`'s dumps, which is harmless for a 30-day prune and unacceptable for an erase. PURE.
+function dumpGlob(inst) {
+  const d = '[0-9]';
+  return `${dbName(inst)}-${d.repeat(4)}-${d.repeat(2)}-${d.repeat(2)}T${d.repeat(6)}Z.sql.gz`;
+}
+
+// The erase, in order: the database before the role that owns it; the dumps; the env dir and
+// state dir; the per-project checkout (standalone only — a co-tenant runs from the shared one);
+// the unix account last, idempotently. Every path derives from a slug the caller has already
+// validated. PURE.
+function eraseCommands(inst, { privileged = false } = {}) {
+  const sudo = privileged ? 'sudo ' : '';
+  const asPg = (cmd) => (privileged ? `sudo -u postgres ${cmd}` : cmd);
+  const user = instanceUser(inst);
+  const cmds = [
+    asPg(`dropdb --if-exists --force ${dbName(inst)}`),
+    asPg(`psql -v ON_ERROR_STOP=1 -d postgres -c 'DROP ROLE IF EXISTS "${instanceDbRole(inst)}"'`),
+    `${sudo}find ${CONFIG.backupDir} -maxdepth 1 -type f -name '${dumpGlob(inst)}' -delete`,
+    `${sudo}rm -rf ${path.posix.dirname(webEnvPath(inst))} ${instanceStateDir(inst)}`,
+  ];
+  if (inst.hosting_shape === 'standalone') cmds.push(`${sudo}rm -rf ${standaloneRoot(inst)}`);
+  cmds.push(`if id -u ${user} >/dev/null 2>&1; then ${sudo}userdel ${user}; fi`);
+  return cmds;
+}
+
+async function disconnectInstance(inst, deps) {
+  const { db, exec, log, apply, privileged } = deps;
+  // Every rm -rf below is built from the slug, so it is re-validated here rather than trusted.
+  if (!inst || !isValidSlug(inst.slug)) return { ok: false, error: `refusing to disconnect: invalid slug ${JSON.stringify(inst && inst.slug)}` };
+  log(`disconnect ${inst.slug} (status=${inst.status})`);
+  // A teardown returns ok or throws; a throw ends the run here, before anything is erased.
+  await teardownInstance(inst, deps);
+
+  if (inst.hosting_shape !== 'dedicated') {
+    const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+    for (const cmd of eraseCommands(inst, { privileged })) {
+      try { boxExec(cmd); }
+      catch (e) { return { ok: false, error: `erase step failed (${cmd.split(' ').slice(0, 3).join(' ')}): ${(e && e.message) || e}` }; }
+    }
+  }
+
+  const origin = catalogOriginForInstance(inst);
+  if (origin && deps.projectCatalog) {
+    if (apply) {
+      try {
+        const ownerGithubId = await ownerGithubIdForInstance(db, inst);
+        const gone = await deps.projectCatalog.forgetOwnedProject({ clientId: inst.slug, origin, ownerGithubId }, { pool: db });
+        log(`  catalog: removed ${gone.project} project row, ${gone.client} client, ${gone.memberships} membership(s)`);
+      } catch (e) { return { ok: false, error: `catalog forget failed: ${(e && e.message) || e}` }; }
+    } else log(`  would remove ${origin} from the catalog`);
+  }
+
+  if (!apply) { log(`  would delete the provisioning row for ${inst.slug}`); return { ok: true }; }
+  await deleteInstance(db, inst.id);
+  log(`  ✓ ${inst.slug} disconnected — row deleted; name, port and address released`);
+  return { ok: true };
+}
+
+module.exports = { disconnectInstance, eraseCommands, dumpGlob };

package/scripts/gds/provision-teardown.js

@@ -0,0 +1,108 @@
+'use strict';
+// provision-teardown.js — reverse the provisioning runbook for one instance
+// (idempotent). Split out of provision.js (task 1002897), which sat at the size
+// ratchet; provision.js re-exports teardownInstance, so its callers are unchanged.
+//
+// What a teardown takes down: the service + backup units, the per-instance Caddy
+// snippet, the DNS record (parked at the blackhole), and the deploy key. What it
+// deliberately LEAVES (ADR 0181): the database, its dumps and the checkout (data is
+// precious), and the row's `domain` + `port` — a revive re-uses exactly that address,
+// and step 5 of the next standup UPSERTs it straight back.
+
+const path = require('node:path');
+const { CONFIG, REPO_ROOT } = require('./provision-config.js');
+const { dbName, deployKeyPath, deployKeyTitle, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo.js');
+const { backupServicePath, backupTimerPath, backupUnitName, serviceUnitPath } = require('./provision-units.js');
+const { caddySnippetPath, dnsReleaseEnv } = require('./provision-net.js');
+const apexMod = require('./instance-apex.js');
+const { isReservedHostname } = require('../../modules/provisioning/provisioning.js');
+
+async function teardownInstance(inst, deps) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  const controlExec = deps.controlExec || exec;
+  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
+  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
+  // box, where it was never installed (that would allowFail-noop and leave the real
+  // control-plane unit running). Co-tenant + dedicated are unchanged.
+  const boxExec = inst.hosting_shape === 'standalone' ? controlExec : exec;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
+  log(`teardown ${inst.slug} (status=${inst.status})`);
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
+  if (inst.hosting_shape !== 'dedicated') {
+    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
+    // Stop + remove the nightly backup units too (task 2213; the dir + dumps stay — precious data, like the DB below), then reset-failed (task 1003940): a removed unit's FAILED state outlives its file, so `systemctl --failed` listed torn-down ghosts for weeks.
+    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
+    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
+    boxExec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
+    // The site snippet standup step 6 wrote: while it stays, Caddy proxies the hostname to
+    // a port nothing listens on and every visitor gets a 502 (task 1002897). Not precious.
+    boxExec(`${sudoP}rm -f ${caddySnippetPath(inst)}`, { allowFail: true });
+    boxExec(`${sudoP}systemctl reload caddy`, { allowFail: true });
+    // Left for an operator (data is precious), naming ONLY what this row created —
+    // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
+    if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
+  } else if (apply && deps.doApi && inst.droplet_id) {
+    await deps.doApi.deleteDroplet(inst.droplet_id);
+  }
+  parkAddress(inst, { controlExec, log, apply });
+  // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
+  // checkout itself is deliberately left in place (data is precious), so the key
+  // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project
+  // silently keeping durable read access to the owner's private repo is the exact
+  // shape a teardown exists to end. A missing token / API hiccup never blocks it.
+  if (inst.hosting_shape === 'standalone' && inst.target_ref) {
+    const repo = parseTargetRef(inst.target_ref);
+    if (repo) {
+      try {
+        const token = await resolveOwnerGithubToken(inst, deps, { tag: '[teardown]' });
+        if (token) {
+          const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
+          if (apply) {
+            const keys = await ghRepos.listDeployKeys(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+            const ours = keys.find((k) => k.title === deployKeyTitle(inst));
+            if (ours) {
+              await ghRepos.deleteDeployKey(token, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
+              log(`  revoked the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name}`);
+            }
+          } else log(`  would revoke the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name} if present`);
+        } else {
+          log(`  (deploy-key revoke skipped: no usable owner credential — if ${repo.owner}/${repo.name} carries a "${deployKeyTitle(inst)}" deploy key, remove it in the repo's settings)`);
+        }
+      } catch (e) { log(`  (deploy-key revoke skipped: ${e && e.message})`); }
+      boxExec(`rm -f ${deployKeyPath(inst)} ${deployKeyPath(inst)}.pub`, { allowFail: true });
+    }
+  }
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
+  }
+  log(`  ✓ ${inst.slug} torn down`);
+  return { ok: true };
+}
+
+// Park the row's hostname at the RFC 5737 blackhole — the release a re-point already
+// uses (ADR 0200 §2: parked, not deleted, so no NXDOMAIN window gets negative-cached).
+// Runs on the CONTROL PLANE for every shape: the hook needs the Cloudflare token, which
+// never leaves it. BEST-EFFORT: a failure is logged and never strands the row. A
+// platform-reserved hostname is refused outright — standup would never have been given
+// one, and blackholing it would take the platform's own record down.
+function parkAddress(inst, { controlExec, log, apply }) {
+  if (!inst.domain) return;
+  if (isReservedHostname(inst.domain, apexMod.instanceApex())) {
+    log(`  [dns] NOT parking ${inst.domain}: a platform-reserved hostname is never blackholed by a teardown`);
+    return;
+  }
+  if (!CONFIG.dnsHook) {
+    log(`  [dns] cannot park ${inst.domain} (BOX_DNS_HOOK unset) — point its A record at 192.0.2.1 by hand`);
+    return;
+  }
+  const env = dnsReleaseEnv(inst.domain);
+  log(`  [dns] park ${inst.domain} -> ${env.BOX_IP} (blackhole, zone ${env.CLOUDFLARE_ZONE}) via ${CONFIG.dnsHook}`);
+  if (!apply) return;
+  try { controlExec(CONFIG.dnsHook, { env }); }
+  catch (e) { log(`  ⚠ could not park ${inst.domain}: ${(e && e.message) || e} — its A record still points at the platform`); }
+}
+
+module.exports = { teardownInstance };

package/scripts/gds/provision.js

@@ -54,6 +54,8 @@ const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbN
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { disconnectInstance } = require('./provision-disconnect.js');
 
 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
@@ -1017,69 +1019,6 @@ async function restartInstance(inst, deps) {
   return { ok: true, healthy };
 }
 
-// ---------------------------------------------------------------------------
-// Teardown one instance (reverse the runbook; idempotent).
-// ---------------------------------------------------------------------------
-async function teardownInstance(inst, deps) {
-  const { db, provisioning, exec, log, apply, privileged } = deps;
-  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
-  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
-  // box, where it was never installed (that would allowFail-noop and leave the real
-  // control-plane unit running). Co-tenant + dedicated are unchanged.
-  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
-  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
-  log(`teardown ${inst.slug} (status=${inst.status})`);
-  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
-  if (inst.hosting_shape !== 'dedicated') {
-    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
-    // Stop + remove the nightly backup units too (task 2213; the dir + dumps stay — precious data, like the DB below), then reset-failed (task 1003940): a removed unit's FAILED state outlives its file, so `systemctl --failed` listed torn-down ghosts for weeks.
-    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
-    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
-    boxExec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
-    // Left for an operator (data is precious), naming ONLY what this row created —
-    // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
-    const dumps = inst.db_name ? [`dropdb ${dbName(inst)}`, `prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz`] : [];
-    log(`  (left for the operator: ${dumps.concat([`remove the Caddy block for ${inst.slug} if one was written`]).join(', ')})`);
-  } else if (apply && deps.doApi && inst.droplet_id) {
-    await deps.doApi.deleteDroplet(inst.droplet_id);
-  }
-  // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
-  // checkout itself is deliberately left in place (data is precious), so the key
-  // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project
-  // silently keeping durable read access to the owner's private repo is the exact
-  // shape a teardown exists to end. A missing token / API hiccup never blocks it.
-  if (inst.hosting_shape === 'standalone' && inst.target_ref) {
-    const repo = parseTargetRef(inst.target_ref);
-    if (repo) {
-      try {
-        const token = await resolveOwnerGithubToken(inst, deps, { tag: '[teardown]' });
-        if (token) {
-          const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
-          if (apply) {
-            const keys = await ghRepos.listDeployKeys(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
-            const ours = keys.find((k) => k.title === deployKeyTitle(inst));
-            if (ours) {
-              await ghRepos.deleteDeployKey(token, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
-              log(`  revoked the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name}`);
-            }
-          } else log(`  would revoke the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name} if present`);
-        } else {
-          log(`  (deploy-key revoke skipped: no usable owner credential — if ${repo.owner}/${repo.name} carries a "${deployKeyTitle(inst)}" deploy key, remove it in the repo's settings)`);
-        }
-      } catch (e) { log(`  (deploy-key revoke skipped: ${e && e.message})`); }
-      boxExec(`rm -f ${deployKeyPath(inst)} ${deployKeyPath(inst)}.pub`, { allowFail: true });
-    }
-  }
-  if (apply) {
-    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
-    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
-  }
-  log(`  ✓ ${inst.slug} torn down`);
-  return { ok: true };
-}
-
 // ---------------------------------------------------------------------------
 // GitHub App Manifest conversion + cred placement (task 2080, ADR 0133).
 // The web tier stored GitHub's temporary `code` on a provisioning_oauth_manifests
@@ -1298,6 +1237,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, 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 result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
@@ -1425,8 +1365,8 @@ async function main() {
   const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
   if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
 
-  let pool, provisioning, DoApi, platformIdentity, hubKeys;
-  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys } = loadDeps()); }
+  let pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog;
+  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog } = loadDeps()); }
   catch (e) { console.error(`cannot load DB layer (run this on the control plane): ${e.message}`); process.exit(1); }
 
   // Box-target executor (remote over SSH when PROVISION_REMOTE_HOST is set, else
@@ -1446,6 +1386,7 @@ async function main() {
     // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
     // dormant; shouldFederate() then skips and the instance owns its auth (as today).
     platformIdentity, hubKeys,
+    projectCatalog,   // the disconnect leg's catalog forget (task 1003249); null off the hub
   };
 
   let result;

package/scripts/gds/seam-wiring-guard.js

@@ -0,0 +1,273 @@
+// scripts/gds/seam-wiring-guard.js — Check 33: a declared contributes.<seam> that
+// nothing consumes (task 1003819; successor to abandoned task 1002464).
+//
+// THE GAP THIS CLOSES. A module declares what it contributes in module.json.
+// src/module-seams.js `verifyPortsSatisfied` checks the OPPOSITE direction — every
+// `consumes` port has exactly one provider among the enabled modules — and
+// src/module-loader/manifest-schema.js `validateManifest` checks the SHAPE of
+// `contributes` (a closed key set, so a typo'd KEY errors). Neither asks whether a
+// declared entry is actually WIRED. So a module can declare `contributes.pollers:
+// ["ghost"]` with no modules/<key>/pollers/ghost.js and boot stays silent: the
+// loader's startModulePollers treats a missing poller file as declarative-only and
+// skips it, hallWidgetScripts skips a uiSection with no hall-widget.js, and
+// moduleWebSurfaces skips a surface whose dir was never shipped. Every one of those
+// skips is correct behaviour for a REAL declarative-only entry, and indistinguishable
+// from a typo or a rename that left the manifest behind.
+//
+// WHAT "CONSUMED" MEANS. Each seam has one consumer in the tree, and each consumer
+// looks for one artifact at a fixed path. SEAM_CONSUMERS below records that pairing —
+// seam → the artifact its consumer resolves — so this guard asks the same question
+// the consumer asks rather than inventing a second convention that could drift from
+// it. A seam with NO consumer anywhere carries `consumer: null`, and every
+// declaration of it is reported: that is the strongest form of the defect.
+//
+// WHY A CI GATE AND NOT A BOOT REFUSAL (ADR 0289). `verifyEnabledPorts` throws at
+// boot because an unprovided port otherwise becomes a runtime throw on a request
+// path, in a process that reported healthy — refusing early is strictly safer. For
+// every seam BUT `routes`, an unconsumed contribution is not that shape: the consumer
+// skips it gracefully, nothing crashes later, and the instance runs correctly minus
+// one feature. Adding a production start-up failure for a manifest-hygiene defect
+// would trade a real outage risk for a cosmetic one.
+//
+// `routes` is the exception and it argues the SAME way: mountModuleRoutes `require`s
+// the factory with no try/catch, so a missing route file already takes the boot down
+// today. There the guard is not a new gate at all — it moves an existing crash from
+// production start-up to the build, which is strictly earlier and strictly cheaper.
+// So CI covers both cases: the seams that fail silently get a voice, and the one that
+// fails loudly gets to fail before it reaches a server.
+//
+// Exported for scripts/gds/fitness.js (checkSeamWiring) and for the unit suite, which
+// drives scanSeamWiring() over synthetic manifests with an injected `exists` so every
+// case is hermetic — the scanScopeMapSource / scanDeterministicBody precedent, where
+// the pure scanner is the tested surface.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+// The SAME enumerator + labeller validateManifest uses for the exemption cross-check,
+// imported rather than re-declared: two copies would drift, and the drift would land
+// on whether an exemption is honoured (task 1003819).
+const { declaredEntries, entryLabel } = require('../../src/module-loader/manifest-schema.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// Is `child` inside `parent`? Both are repo-relative-or-absolute; normalised before
+// comparing so a '..' segment cannot pass by spelling.
+function within(parent, child) {
+  const a = path.resolve(REPO_ROOT, parent);
+  const b = path.resolve(REPO_ROOT, child);
+  const r = path.relative(a, b);
+  return r !== '' && !r.startsWith('..') && !path.isAbsolute(r);
+}
+
+// A repo-relative, forward-slashed path for an error message.
+function rel(p) {
+  if (!p) return '(no artifact path)';
+  const r = path.relative(REPO_ROOT, path.isAbsolute(p) ? p : path.join(REPO_ROOT, p));
+  return r.split(path.sep).join('/');
+}
+
+// seam → how its consumer resolves a declared entry to an on-disk artifact.
+//   consumer   the function that actually reads it, named so a reader can go check
+//   kind       'file' | 'dir' | 'registry' — what must exist
+//   artifact   (moduleDir, entry) → path, or null when the seam is per-MODULE rather
+//              than per-entry (uiSections ships ONE widget however many it names)
+//   alternates optional extra paths that also count as wired
+const SEAM_CONSUMERS = {
+  routes: {
+    consumer: 'src/module-loader/loader.js mountModuleRoutes',
+    kind: 'file',
+    artifact: (dir, entry) => path.join(dir, 'routes', `${entry}.js`),
+  },
+  pollers: {
+    consumer: 'src/module-loader/loader.js startModulePollers',
+    kind: 'file',
+    artifact: (dir, entry) => path.join(dir, 'pollers', `${entry}.js`),
+  },
+  rooms: {
+    // Allowed by the manifest schema since the doorway, but nothing in core reads
+    // contributes.rooms — the realtime seam was never wired to the loader. No module
+    // declares it today; if one ever does, this guard says so rather than letting the
+    // declaration read as though it did something.
+    consumer: null,
+    kind: 'file',
+    artifact: (dir, entry) => path.join(dir, 'rooms', `${entry}.js`),
+  },
+  uiSections: {
+    // Per-MODULE, not per-entry: hallWidgetScripts looks for one hall-widget.js
+    // however many sections the module names.
+    consumer: 'src/module-loader/loader.js hallWidgetScripts',
+    kind: 'file',
+    artifact: (dir) => path.join(dir, 'public', 'hall-widget.js'),
+  },
+  skills: {
+    // moduleSkillSources resolves a declared name against the module's OWN tree or
+    // its vendor/ subdir. A name that exists only in the core .claude/skills/ is
+    // skipped by it (`if (!src) continue`), so it is unconsumed BY THE MANIFEST —
+    // a legitimate declarative-only case, and what ui-design's exemption records.
+    //
+    // The artifact is the SKILL.md, not the directory: moduleSkillSources tests
+    // `fs.existsSync(path.join(p, 'SKILL.md'))`, so a skills/<name>/ dir without one
+    // is NOT a skill to it. Probing the bare directory would call such an entry wired
+    // while the real consumer skipped it — this guard's own defect, on the seam with
+    // the most declared entries.
+    consumer: 'scripts/gds/claude-materialize.js moduleSkillSources',
+    kind: 'file',
+    artifact: (dir, entry) => path.join(dir, 'skills', entry, 'SKILL.md'),
+    alternates: (dir, entry) => [path.join(dir, 'skills', 'vendor', entry, 'SKILL.md')],
+  },
+  disciplines: {
+    consumer: 'scripts/gds/discipline-modes.json (read by src/modules.js + claim.js)',
+    kind: 'registry',
+    artifact: () => null,
+  },
+  webSurfaces: {
+    consumer: 'src/module-loader/loader.js moduleWebSurfaces',
+    kind: 'dir',
+    // `entry` is the surface OBJECT here, not a string.
+    artifact: (dir, entry) => (entry && typeof entry.dir === 'string' ? path.join(dir, entry.dir) : null),
+  },
+  migrations: {
+    consumer: 'scripts/migrate.sh (the module-migration runner)',
+    kind: 'dir',
+    artifact: (dir) => path.join(dir, 'migrations'),
+  },
+};
+
+// Default existence probe — `kind` decides file-vs-directory. A relative path is
+// resolved against the repo root so a manifest's `dir` may be either.
+function fsExists(p, kind) {
+  try {
+    const st = fs.statSync(path.isAbsolute(p) ? p : path.join(REPO_ROOT, p));
+    return kind === 'dir' ? st.isDirectory() : st.isFile();
+  } catch {
+    return false;
+  }
+}
+
+// THE SCANNER. Pure over its inputs (the only I/O is the injected `exists`), so the
+// unit suite drives every case with synthetic manifests and no tmp dirs.
+//
+//   modules       [{ key, dir, manifest }] — the loader's `discovered().loaded` shape
+//   exists        (path, kind) => boolean — defaults to the real filesystem
+//   registryKeys  Set of valid `disciplines` entries, or null to skip that seam
+//
+// Returns { ok, findings[], wired[], declarative[] }. `wired` and `declarative` are
+// populated on the SUCCESS path too, deliberately: a guard that reports nothing when
+// it passes leaves no evidence it ran, so the caller prints the counts either way.
+function scanSeamWiring(modules = [], { exists = fsExists, registryKeys = null } = {}) {
+  const findings = [];
+  const wired = [];
+  const declarative = [];
+
+  for (const { key, dir, manifest } of modules) {
+    const contributes = (manifest && manifest.contributes) || {};
+    const exempt = (manifest && manifest.declarativeSeams) || {};
+    const isExempt = (seam, label) => Array.isArray(exempt[seam]) && exempt[seam].includes(label);
+
+    for (const [seam, value] of Object.entries(contributes)) {
+      const spec = SEAM_CONSUMERS[seam];
+      if (!spec) continue; // an unknown seam key is validateManifest's error, not ours
+
+      for (const entry of declaredEntries(seam, value)) {
+        const label = entryLabel(seam, entry);
+
+        if (spec.consumer === null) {
+          findings.push(`module "${key}" declares contributes.${seam}: "${label}", but NOTHING in the tree consumes the ${seam} seam at all — the declaration does nothing`);
+          continue;
+        }
+
+        // A 'registry' seam is satisfied by membership in a roster, not by a file.
+        if (spec.kind === 'registry') {
+          if (registryKeys && !registryKeys.has(label)) {
+            findings.push(`module "${key}" declares contributes.${seam}: "${label}", but ${spec.consumer} has no such entry`);
+          } else {
+            wired.push({ key, seam, entry: label, via: spec.consumer });
+          }
+          continue;
+        }
+
+        const primary = spec.artifact(dir, entry);
+        const candidates = [primary, ...(spec.alternates ? spec.alternates(dir, entry) : [])].filter(Boolean);
+        // An entry carrying path separators or '..' would aim the probe outside
+        // modules/<key>/. It is only an existence test over repo-committed content, so
+        // the blast radius is an on/off answer — but a declaration that reaches out of
+        // its own module is a finding in its own right, not something to resolve.
+        const escapes = candidates.find((p) => !within(dir, p));
+        if (escapes) {
+          findings.push(`module "${key}" declares contributes.${seam}: "${label}", which resolves to ${rel(escapes)} — outside the module's own directory. A contributes entry names something the module ships, so it may not contain a path separator or ".."`);
+          continue;
+        }
+        const found = candidates.some((p) => exists(p, spec.kind));
+
+        if (found) {
+          // A STALE exemption is the same rot in the other direction: the artifact
+          // exists now, so the entry IS wired and the exemption reads as though a
+          // real gap were sanctioned. Fail it rather than let the list quietly lie.
+          if (isExempt(seam, label)) {
+            findings.push(`module "${key}" exempts ${seam} "${label}" as declarative-only, but ${rel(primary)} exists and ${spec.consumer} wires it — drop the stale declarativeSeams.${seam} entry`);
+          } else {
+            wired.push({ key, seam, entry: label, via: spec.consumer });
+          }
+          continue;
+        }
+
+        if (isExempt(seam, label)) {
+          declarative.push({ key, seam, entry: label });
+          continue;
+        }
+
+        findings.push(`module "${key}" declares contributes.${seam}: "${label}", but ${rel(primary)} does not exist — ${spec.consumer} silently skips it. Ship the artifact, drop the declaration, or record it in declarativeSeams.${seam} if it is declarative-only on purpose`);
+      }
+    }
+  }
+
+  return { ok: findings.length === 0, findings, wired, declarative };
+}
+
+// The roster `contributes.disciplines` is checked against. Returns null when the file
+// is unreadable, which makes the disciplines seam UNCHECKED rather than failed — a
+// missing registry is its own check's problem (fitness.js role packs), not this one's.
+function disciplineKeys() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', 'discipline-modes.json'), 'utf8'));
+    return new Set(Object.keys(raw.modes || {}));
+  } catch {
+    return null;
+  }
+}
+
+// The fitness-check wrapper. Discovers every module.json through the loader — the same
+// discovery the running server uses, so the guard cannot check a different module set
+// than the one that boots.
+function checkSeamWiring() {
+  const name = 'declared module seams are consumed (task 1003819)';
+  let modules = [];
+  try {
+    modules = require('../../src/module-loader/loader.js').discoverModules().loaded;
+  } catch (e) {
+    return {
+      name,
+      ok: true,
+      hardFail: false,
+      violations: [],
+      warnings: [`module discovery failed: ${e && e.message ? e.message : e}`],
+      note: 'module discovery unavailable — skipped.',
+    };
+  }
+
+  const { ok, findings, wired, declarative } = scanSeamWiring(modules, { registryKeys: disciplineKeys() });
+  const seams = [...new Set(wired.map((w) => w.seam))].sort();
+  return {
+    name,
+    ok,
+    hardFail: !ok,
+    violations: findings,
+    warnings: [],
+    // Printed on the PASS path too — the wired set is the evidence the guard ran.
+    note: `${modules.length} module(s): ${wired.length} declared seam entr(ies) WIRED across ${seams.length} seam(s) (${seams.join(', ') || 'none'}), ${declarative.length} recorded declarative-only. A declared contributes.<seam> whose consumer's artifact is absent is a silent no-op (ADR 0289).`,
+  };
+}
+
+module.exports = { checkSeamWiring, scanSeamWiring, SEAM_CONSUMERS, declaredEntries, entryLabel, disciplineKeys };