@bongos/core 1.19.674 → 1.19.676

package/scripts/gds/discord-channels.js

@@ -10,8 +10,9 @@
 // directly — it asks the deployed bot (via the API) to do the work.
 //
 // Usage:
-//   node scripts/gds/discord-channels.js plan     # dry run: what WOULD change
+//   node scripts/gds/discord-channels.js plan      # dry run: what WOULD change
 //   node scripts/gds/discord-channels.js apply     # apply docs/discord/channels.json to Discord
+//   node scripts/gds/discord-channels.js snapshot  # print the guild AS channels.json (seed the file)
 //
 // The channel layout itself is edited in docs/discord/channels.json and merged
 // (rank-gated) — this command just triggers the reconcile.
@@ -20,8 +21,8 @@ const { cliClient } = require('./cli-lib');
 
 async function main() {
   const cmd = (process.argv[2] || '').toLowerCase();
-  if (cmd !== 'plan' && cmd !== 'apply') {
-    console.error('usage: node scripts/gds/discord-channels.js <plan|apply>');
+  if (cmd !== 'plan' && cmd !== 'apply' && cmd !== 'snapshot') {
+    console.error('usage: node scripts/gds/discord-channels.js <plan|apply|snapshot>');
     process.exit(2);
   }
 
@@ -29,6 +30,8 @@ async function main() {
   let res;
   if (cmd === 'plan') {
     res = await api.discord.getDiscordChannelsPlan();
+  } else if (cmd === 'snapshot') {
+    res = await api.discord.getDiscordChannelsSnapshot();
   } else {
     res = await api.discord.postDiscordChannelsReconcile({ body: {} });
   }
@@ -47,7 +50,15 @@ async function main() {
     process.exit(1);
   }
 
+  // Warnings go to STDERR so `snapshot > channels.json` writes clean JSON.
   for (const w of body.warnings || []) console.warn(`warning: ${w}`);
+  if (cmd === 'snapshot') {
+    // STDOUT is the file body and nothing else — this command exists to be
+    // redirected. Review the diff before committing: it is the guild's real
+    // state, which is not necessarily the state anyone intended.
+    console.log(JSON.stringify(body.config, null, 2));
+    return;
+  }
   if (cmd === 'plan') {
     const ops = body.ops || [];
     if (!ops.length) { console.log('In sync — no channel changes needed.'); return; }

package/scripts/gds/go-live.js

@@ -77,8 +77,32 @@ function isSafeToken(v) {
 // rather than ignored: a typo'd `healthURL` that silently disables the health gate
 // is precisely the class of quiet failure this pipeline keeps being bitten by.
 // `ssh` is NOT required: a target with no ssh host is LOCAL (the box driving itself).
-const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer'];
-const OPTIONAL_FIELDS = ['ssh', 'local', 'deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage'];
+//
+// `deployTimer` is NOT required either — that is CO-TENANT MODE (task 1003521). A
+// provisioned instance under /srv/<host>/<slug> has no pull-deploy timer at all (only
+// its <slug>-db-backup.timer), so requiring the field forced an operator to invent a
+// unit name that the script would then try to `systemctl stop`. Absent, the stop and
+// the restart are simply skipped: there is no `reset --hard` to race.
+const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl'];
+const OPTIONAL_FIELDS = ['ssh', 'local', 'deployTimer', 'deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage', 'pinMode'];
+
+// How the bump is made durable — the other half of co-tenant mode (task 1003521).
+//
+// On the PLATFORM instance the repo of record is ours, and a pull-deploy
+// `git reset --hard origin/main` reverts any pin that was not PUSHED (task 1002712 —
+// thirteen releases were lost exactly that way). So the default is `push`.
+//
+// On a provisioned co-tenant the repo of record is the CUSTOMER's own GitHub repo, so
+// that push is both wrong and, in practice, uncredentialed. With no pull-deploy timer
+// nothing will revert the pin, so a local commit is enough to leave the tree clean:
+//   local-commit — commit the pin, do not push it
+//   leave-dirty  — do not commit at all; the bump lives in the working tree by design
+const PIN_MODES = ['push', 'local-commit', 'leave-dirty'];
+const DEFAULT_PIN_MODE = 'push';
+
+function pinModeOf(target) {
+  return (target && target.pinMode) || DEFAULT_PIN_MODE;
+}
 
 function validateTarget(name, t) {
   const errors = [];
@@ -105,6 +129,10 @@ function validateTarget(name, t) {
       if (typeof v !== 'boolean') errors.push(`target "${name}".local must be true or false`);
       continue;
     }
+    if (k === 'pinMode') { // an enum, never interpolated into a command
+      if (!PIN_MODES.includes(v)) errors.push(`target "${name}".pinMode must be one of ${PIN_MODES.join(', ')} (got ${JSON.stringify(v)})`);
+      continue;
+    }
     if (!isSafeToken(v)) errors.push(`target "${name}".${k} contains characters that are unsafe in a shell (got ${JSON.stringify(v)})`);
   }
   return errors;
@@ -123,14 +151,27 @@ const CONFIG_TEMPLATE = `{
       "service": "my-instance.service",                 // systemd unit to restart
       "healthUrl": "http://127.0.0.1:3002/healthz",     // box-side, NOT the apex
       "versionUrl": "http://127.0.0.1:3002/version",    // box-side truth read back after
-      "deployTimer": "my-deploy.timer",                 // pull-deploy timer (its reset --hard is the hazard)
+      "deployTimer": "my-deploy.timer",                 // optional: pull-deploy timer (its reset --hard is the hazard)
       "deployService": "my-deploy.service",             // optional: forced tick proves the pin stuck
       "npmEnvFile": "/etc/my/npm.env",                  // optional: root-only NPM_TOKEN for a PRIVATE package
       "runAs": "me",                                    // optional: unprivileged owner of the instance
       "backupDb": "mydb",                               // optional: pg_dump before the bump
       "backupDir": "~/backups",
       "env": { "PGDATABASE": "mydb" },                  // optional: load-bearing for migrate
-      "registryPackage": "@bongos/core"
+      "registryPackage": "@bongos/core",
+      "pinMode": "push"                                 // optional: push (default) | local-commit | leave-dirty
+    },
+    "a-co-tenant": {
+      // A PROVISIONED instance: no pull-deploy timer to stop, and the repo of record
+      // is the customer's own GitHub repo — so the pin is committed, never pushed.
+      "ssh": "my-box",
+      "instanceDir": "/srv/my-host/their-slug",
+      "service": "their-slug.service",
+      "healthUrl": "http://127.0.0.1:3101/healthz",
+      "versionUrl": "http://127.0.0.1:3101/version",
+      "runAs": "their-slug",
+      "env": { "PGDATABASE": "their_slug" },
+      "pinMode": "local-commit"
     }
   }
 }`;
@@ -455,7 +496,10 @@ function renderReport(r) {
 
   L.push('');
   L.push(`  live reads back   ${r.liveVersion || '(unread)'}`);
-  L.push(`  pin committed     ${r.pinCommitted ? 'yes' : 'NO — the next pull-deploy reset will revert this bump'}`);
+  const mode = r.pinMode || DEFAULT_PIN_MODE;
+  if (mode === 'leave-dirty') L.push('  pin               left in the working tree (pinMode leave-dirty)');
+  else if (r.pinCommitted) L.push(`  pin committed     yes${mode === 'local-commit' ? ' (local commit — this target\'s remote is not ours to push)' : ''}`);
+  else L.push('  pin committed     NO — the next pull-deploy reset will revert this bump');
   L.push('');
   return L.join('\n');
 }
@@ -506,36 +550,78 @@ echo "##END##"
   };
 }
 
+// The `bongos upgrade` invocation, as its own function so the pin-mode wiring is
+// assertable without a box.
+//
+// Both non-default modes pass --pin-no-push, which is what tells upgrade.js the repo of
+// record is not ours: `local-commit` pairs it with --commit-pin (commit, no push), and
+// `leave-dirty` sends it alone, which downgrades upgrade.js's "PIN NOT COMMITTED" alarm
+// to a note. That alarm is correct on a pull-deploy instance and misleading here, and an
+// alarm an operator learns to ignore is worse than no alarm.
+function upgradeCommand(target, targetVersion) {
+  const mode = pinModeOf(target);
+  return [
+    `./node_modules/.bin/bongos upgrade`,
+    `--to ${targetVersion}`, '--registry',
+    `--instance ${target.instanceDir}`,
+    `--service ${target.service}`,
+    `--health-url ${target.healthUrl}`,
+    ...(mode === 'leave-dirty' ? [] : ['--commit-pin']),
+    ...(mode === 'push' ? [] : ['--pin-no-push']),
+    '--force',
+  ].join(' ');
+}
+
+// Whether the post-bump pin state is what this target ASKED for. Under `leave-dirty` a
+// modified working tree is the configured outcome, so reporting it as the durability
+// failure it is on a pull-deploy instance would make a correct co-tenant run read as
+// broken — the one place the three modes must not share a verdict.
+function pinStep(mode, pinDirty, head) {
+  if (mode === 'leave-dirty') {
+    return {
+      name: 'pin left in the working tree (pinMode leave-dirty)',
+      ok: true,
+      detail: pinDirty ? 'package.json/-lock MODIFIED by design — this target has no pull-deploy to revert it' : (head || null),
+    };
+  }
+  return {
+    name: mode === 'local-commit' ? 'pin committed locally (not pushed)' : 'pin committed + pushed',
+    ok: !pinDirty,
+    detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (head || null),
+  };
+}
+
 function applyGoLive(target, targetName, targetVersion, from, opts = {}) {
   const pkg = target.registryPackage || '@bongos/core';
+  const pinMode = pinModeOf(target);
   const steps = [];
   const src = target.npmEnvFile ? `set -a; . ${target.npmEnvFile}; set +a` : 'true';
 
   // Phase A — stop the pull-deploy timer, then back up. The timer's `reset --hard`
-  // is the hazard: it would revert an uncommitted pin mid-flight.
+  // is the hazard: it would revert an uncommitted pin mid-flight. A co-tenant has no
+  // such timer (see REQUIRED_FIELDS), so there is nothing to stop and no hazard.
   const backup = target.backupDb
     ? asOwner(target, `bash -c "mkdir -p ${target.backupDir || '~/backups'} && pg_dump ${target.backupDb} | gzip > ${target.backupDir || '~/backups'}/pre-${targetVersion}-$(date -u +%Y%m%dT%H%M%SZ).sql.gz"`)
     : 'echo "(no backupDb configured — skipping)"';
   const phaseA = remote(target, `
 set -euo pipefail
 ${SUDO_PREAMBLE}
-echo "##TIMER##"; $SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true
+echo "##TIMER##"; ${target.deployTimer
+    ? `$SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true`
+    : 'echo "(no deployTimer configured — no pull-deploy to stop)"'}
 echo "##BACKUP##"; ${backup}
 echo "##END##"
 `, opts);
-  steps.push({ name: `stop ${target.deployTimer} + backup`, ok: phaseA.ok, detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop() });
-  if (!phaseA.ok) return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'PREPARE', raw: phaseA };
+  steps.push({
+    name: target.deployTimer ? `stop ${target.deployTimer} + backup` : 'backup (no pull-deploy timer)',
+    ok: phaseA.ok,
+    detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop(),
+  });
+  if (!phaseA.ok) return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'PREPARE', raw: phaseA };
 
   // Phase B — the upgrade itself. --commit-pin makes the bump durable against the
   // pull-deploy reset; auto-rollback stays ON (do NOT pass --no-rollback-on-failure).
-  const upgrade = [
-    `./node_modules/.bin/bongos upgrade`,
-    `--to ${targetVersion}`, '--registry',
-    `--instance ${target.instanceDir}`,
-    `--service ${target.service}`,
-    `--health-url ${target.healthUrl}`,
-    '--commit-pin', '--force',
-  ].join(' ');
+  const upgrade = upgradeCommand(target, targetVersion);
   const phaseB = remote(target, `
 set -uo pipefail
 ${src}
@@ -549,9 +635,10 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { needsNpm
   });
   if (!phaseB.ok || rolledBack) {
     // Restart the timer even on failure — leaving it stopped silently disables
-    // the instance's pull-deploy until someone notices.
-    remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
-    return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
+    // the instance's pull-deploy until someone notices. Nothing was stopped on a
+    // co-tenant, so there is nothing to put back.
+    if (target.deployTimer) remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
+    return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
   }
 
   // Phase C — restart the timer, force one tick, and read back the BOX-SIDE truth.
@@ -560,7 +647,7 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { needsNpm
   const phaseC = remote(target, `
 set -uo pipefail
 ${SUDO_PREAMBLE}
-echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}
+${target.deployTimer ? `echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}` : ''}
 echo "##PIN##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain -- package.json package-lock.json )
 echo "##HEAD##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git log -1 --format='%h %s' )
 ${target.deployService ? `echo "##TICK##"; $SUDO systemctl start ${target.deployService} || true; $SUDO journalctl -u ${target.deployService} -n 20 --no-pager | tail -8` : ''}
@@ -578,13 +665,13 @@ echo "##END##"
   let liveVersion = null;
   try { liveVersion = JSON.parse(section('VERSION') || '{}').coreVersion || null; } catch { liveVersion = null; }
 
-  steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
-  steps.push({ name: 'pin committed + pushed', ok: !pinDirty, detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (section('HEAD') || null) });
+  if (target.deployTimer) steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
+  steps.push(pinStep(pinMode, pinDirty, section('HEAD')));
   steps.push({ name: 'installed package version', ok: installed === targetVersion, detail: installed === targetVersion ? installed : `reports ${installed}, expected ${targetVersion}` });
   steps.push({ name: 'live reads back (box-side)', ok: liveVersion === targetVersion, detail: liveVersion === targetVersion ? liveVersion : `reports ${liveVersion}, expected ${targetVersion}` });
 
   const ok = steps.every((s) => s.ok);
-  return { ok, steps, from, to: targetVersion, targetName, liveVersion, installed, pinCommitted: !pinDirty, raw: phaseC };
+  return { ok, steps, from, to: targetVersion, targetName, pinMode, liveVersion, installed, pinCommitted: !pinDirty, raw: phaseC };
 }
 
 // ---------------------------------------------------------------------------
@@ -608,6 +695,11 @@ go-live — move an enrolled instance's core pin, as one command.
   node scripts/gds/go-live.js --no-divergence     skip the git-derived checks (needs --to)
   node scripts/gds/go-live.js --json              machine-readable
 
+CO-TENANT TARGETS. A provisioned instance has no pull-deploy timer and its repo of
+record is the customer's own, so omit "deployTimer" (the stop/restart is skipped) and
+set "pinMode": "local-commit" (the pin is committed, never pushed). "leave-dirty"
+leaves the bump in the working tree; "push" (the default) is the platform instance.
+
 Host topology is NOT baked into the core. ${DEFAULT_CONFIG} (host-owned, not published):
 
 ${CONFIG_TEMPLATE}
@@ -770,5 +862,6 @@ if (require.main === module) {
 module.exports = {
   loadConfig, selectTarget, validateTarget, planGoLive, parseMarker, parseMarkerHits,
   renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, NPM_AUTH_PREAMBLE, refreshMain, isLocalTarget, gitRefExists, SUDO_PREAMBLE,
-  CONFIG_TEMPLATE, HALTS, SEMVER_RE,
+  applyGoLive, upgradeCommand, pinStep, pinModeOf,
+  CONFIG_TEMPLATE, HALTS, SEMVER_RE, PIN_MODES, DEFAULT_PIN_MODE,
 };

package/scripts/gds/upgrade.js

@@ -160,7 +160,12 @@ function dirtyPinFiles(instanceDir, run = spawnSync) {
   return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
 }
 
-function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = 'origin', dryRun = false },
+// `push: false` is CO-TENANT MODE (task 1003521). The reasoning above assumes the repo
+// of record is OURS; on a provisioned instance it is the customer's own GitHub repo, so
+// pushing there is both wrong and uncredentialed. Such an instance also has no
+// pull-deploy timer, so nothing will `reset --hard` the pin away — the commit alone
+// makes it durable, and leaves the tree clean for the customer's own pulls.
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false },
   run = spawnSync, log = console.log, err = console.error) {
   const dirty = dirtyPinFiles(instanceDir, run);
   if (dirty === null) return { applicable: false, reason: 'not a git repo' };
@@ -169,6 +174,15 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   const branch = gitCurrentBranch(instanceDir, run);
 
   if (!commitPin) {
+    if (!push) {
+      // No pull-deploy of ours reaches this instance, so an uncommitted pin is untidy
+      // rather than doomed. Crying wolf here would teach an operator to ignore the
+      // warning that DOES matter on the platform instance.
+      err(`  ! pin not committed — ${dirty.join(', ')} changed in the working tree only.`);
+      err('    This target pulls from a repo that is not ours, so nothing here will revert it —');
+      err('    but the tree stays dirty until it is committed. Re-run with --commit-pin to commit it.');
+      return { applicable: true, committed: false, pushed: false, dirty, warned: true };
+    }
     // LOUD — this is the whole point. A silent uncommitted pin is the bug.
     err(`  ! PIN NOT COMMITTED — ${dirty.join(', ')} changed in the working tree only.`);
     err('    On a pull-deploy instance the next push to the repo of record makes deploy.sh');
@@ -184,7 +198,9 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   }
 
   if (dryRun) {
-    log(`  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`);
+    log(push
+      ? `  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`
+      : `  [dry-run] would commit ${dirty.join(', ')} locally (no push — this remote is not ours)`);
     return { applicable: true, committed: false, pushed: false, dirty, dryRun: true };
   }
 
@@ -201,8 +217,13 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   }
   log(`  ✓ committed the pin (${dirty.join(', ')})`);
 
-  const push = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
-  if (!push || push.error || push.status !== 0) {
+  if (!push) {
+    log('  ✓ not pushed, by request — this instance\'s repo of record is not ours, and no pull-deploy of ours can revert the commit');
+    return { applicable: true, committed: true, pushed: false, dirty, pushSkipped: true };
+  }
+
+  const pushed = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
+  if (!pushed || pushed.error || pushed.status !== 0) {
     // Committed but not pushed is still doomed: deploy.sh resets to the REMOTE.
     err(`  ! commit landed locally but the push to ${remote} FAILED — this bump is still not durable.`);
     err(`    Push it: git -C ${instanceDir} push ${remote} HEAD:${branch || 'main'}`);
@@ -984,6 +1005,7 @@ async function runUpgrade(opts, deps = {}) {
     fromVersion,
     toVersion: targetVersion,
     commitPin: opts.commitPin,
+    push: !opts.pinNoPush,
     remote: opts.gitRemote || 'origin',
     dryRun: opts.dryRun,
   }, run, log, err);
@@ -1006,6 +1028,7 @@ function parseArgs(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
+    pinNoPush: hasFlag('--pin-no-push', argv), // task 1003521 co-tenant mode: commit the pin but leave the customer's own remote alone
     gitRemote: arg('--git-remote', argv),
     dryRun: hasFlag('--dry-run', argv),
     force: hasFlag('--force', argv),
@@ -1042,6 +1065,7 @@ async function main(argv = process.argv.slice(2)) {
       '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
       '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
       '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
+      '  --pin-no-push        with --commit-pin: commit the pin but do NOT push it — for an instance whose repo of record is not ours (a provisioned co-tenant), where the push is wrong and no pull-deploy can revert the commit',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',

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.674'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.676'; // 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/discord_channels_snapshot.mjs

@@ -0,0 +1,198 @@
+// tests/discord_channels_snapshot.mjs
+//
+// Seeding docs/discord/channels.json from the LIVE guild (task 1003510).
+//
+// WHY THIS EXISTS. ADR 0037 §1 calls channels.json "the single source of truth"
+// and rests its security argument on it — changing channels means editing a repo
+// file and merging it, and merging is rank-gated, so the layout is Archon-gated
+// by construction. That property only holds for channels the file actually
+// describes. It described one (board-room, task 1003033); the rest of the guild
+// was configured somewhere untracked. Reconstructing them by hand from the ADR's
+// access table was rejected on purpose: the table lists `view` but no names and
+// no topics, so guessing would make the bot EDIT live channels to match an
+// invention. `configFromSnapshot` reads the real values instead.
+//
+// THE PROPERTY THAT MAKES IT TRUSTWORTHY — and the whole point of this file:
+//
+//     planChannelReconcile(snapshot, configFromSnapshot(snapshot).config) === no ops
+//
+// Feeding the derived config straight back at the guild it came from must ask for
+// NOTHING. Any field inverted wrongly — a view, a name, a topic, a parent — makes
+// the planner emit an op, so this one assertion tests the whole function instead
+// of restating it field by field. A config that round-trips is one an operator can
+// commit without the next reconcile rewriting the guild.
+//
+// Pure: no Discord, no network, no DB.
+//
+// Run:  node tests/discord_channels_snapshot.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ch = require('../modules/discord/discord-channels.js');
+const { configFromSnapshot, viewFromOverwrites, planChannelReconcile, mergeViewOverwrites, resolveViewRoles } = ch;
+
+const EVERYONE = '100';
+const ROLES = { xenos: '201', thetes: '202', metic: '203', archon: '204' };
+const BOT = '999';
+const ctx = { everyoneId: EVERYONE, roleMap: ROLES, botId: BOT };
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (e) { console.error(`  FAIL ${name}\n     ${e.message}`); failed++; }
+}
+
+// Build the overwrites a REAL reconciled channel carries for a given view, using
+// the production forward path — so the fixtures are what the bot actually writes,
+// not a hand-rolled guess at it.
+const owFor = (view) => mergeViewOverwrites([], resolveViewRoles(view, ROLES), ctx);
+
+// ---- the inverse, on its own ----------------------------------------------
+
+test('everyone-visible reads back as "everyone"', () => {
+  assert.equal(viewFromOverwrites(owFor('everyone'), ctx), 'everyone');
+});
+
+test('each rank round-trips through the overwrites the bot writes', () => {
+  for (const rank of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(viewFromOverwrites(owFor(rank), ctx), rank, `view=${rank}`);
+  }
+});
+
+test('the LOWEST allowed rank wins — view grants that rank and every rank above', () => {
+  // thetes' overwrites allow thetes+metic+archon. The answer must be the floor,
+  // not whichever happens to be first in the array.
+  const ow = owFor('thetes');
+  assert.ok(ow.some((o) => o.id === ROLES.archon), 'fixture really does allow archon too');
+  assert.equal(viewFromOverwrites(ow, ctx), 'thetes');
+});
+
+test('no managed overwrite at all reads back as null, never "everyone"', () => {
+  // A channel the bot has never touched. Claiming "everyone" here would write a
+  // claim the guild never made, and the next reconcile would act on it.
+  assert.equal(viewFromOverwrites([], ctx), null);
+  assert.equal(viewFromOverwrites([{ id: '777', type: 0, allow: '0', deny: '0' }], ctx), null);
+});
+
+test('@everyone denied with no rank allowed fails safe to archon', () => {
+  const ow = [{ id: EVERYONE, type: 0, allow: '0', deny: '1024' }];
+  assert.equal(viewFromOverwrites(ow, ctx), 'archon', 'mirrors resolveViewRoles fail-safe');
+});
+
+// ---- the round trip --------------------------------------------------------
+
+// A guild shaped like the real one: a public category, a restricted one, emoji in
+// the names, and a channel whose view is TIGHTER than its category's.
+function guild() {
+  return {
+    categories: [
+      { id: '1', name: 'COMMONS', overwrites: owFor('everyone') },
+      { id: '2', name: 'BUILDERS', overwrites: owFor('xenos') },
+    ],
+    channels: [
+      { id: '10', name: '👋-welcome', type: 0, parentId: '1', topic: 'Start here.', overwrites: owFor('everyone') },
+      { id: '11', name: '📯-ship-news', type: 0, parentId: '1', topic: 'What shipped.', overwrites: owFor('everyone') },
+      { id: '12', name: '🏛️-board-room', type: 0, parentId: '2', topic: 'Ratification votes.', overwrites: owFor('xenos') },
+      { id: '13', name: '🔒-archon-only', type: 0, parentId: '2', topic: 'Archon business.', overwrites: owFor('archon') },
+    ],
+  };
+}
+
+test('ROUND TRIP: the derived config asks the planner for nothing', () => {
+  const snapshot = guild();
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.deepEqual(warnings, [], 'a fully-reconciled guild produces no warnings');
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], `expected zero ops, got: ${JSON.stringify(ops.map((o) => [o.op, o.name]))}`);
+});
+
+test('the real names survive, emoji and all — they are what slug matching needs', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const names = config.categories.flatMap((c) => c.channels.map((x) => x.name));
+  assert.deepEqual(names, ['👋-welcome', '📯-ship-news', '🏛️-board-room', '🔒-archon-only']);
+  const keys = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.deepEqual(keys, ['welcome', 'ship-news', 'board-room', 'archon-only'], 'key is the slug');
+});
+
+test('topics are carried verbatim — the ADR table has none, which is why guessing was refused', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const commons = config.categories.find((c) => c.name === 'COMMONS');
+  assert.equal(commons.channels.find((c) => c.key === 'ship-news').topic, 'What shipped.');
+});
+
+test('a channel view EQUAL to its category is omitted; a tighter one is stated', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  assert.equal(builders.view, 'xenos');
+  // board-room matches its category → inherits, so no `view` key to drift later.
+  assert.equal('view' in builders.channels.find((c) => c.key === 'board-room'), false);
+  // archon-only is tighter → must be stated or the config would widen it.
+  assert.equal(builders.channels.find((c) => c.key === 'archon-only').view, 'archon');
+});
+
+test('a tighter channel view is not merely recorded — it survives the round trip', () => {
+  // Guard against "stated but wrong": drop the view and the planner must object.
+  const snapshot = guild();
+  const { config } = configFromSnapshot(snapshot, ctx);
+  const builders = config.categories.find((c) => c.name === 'BUILDERS');
+  delete builders.channels.find((c) => c.key === 'archon-only').view;
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.ok(ops.length > 0, 'removing the tighter view must make the planner want to widen it');
+});
+
+// ---- the honest edges ------------------------------------------------------
+
+test('an uncategorised channel is REPORTED and omitted, never invented into a category', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '14', name: 'stray', type: 0, parentId: null, topic: '', overwrites: owFor('everyone') });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const all = config.categories.flatMap((c) => c.channels.map((x) => x.key));
+  assert.ok(!all.includes('stray'), 'omitted — channels.json cannot express it');
+  assert.ok(warnings.some((w) => /stray/.test(w) && /no category/.test(w)), 'and said so');
+  // Omitted means UNTOUCHED, which is the file header's own rule.
+  const { ops } = planChannelReconcile(snapshot, config, ctx);
+  assert.deepEqual(ops, [], 'an omitted channel still produces no op');
+});
+
+test('a never-reconciled channel warns instead of silently claiming a view', () => {
+  const snapshot = guild();
+  snapshot.channels.push({ id: '15', name: 'untouched', type: 0, parentId: '1', topic: '', overwrites: [] });
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  const entry = config.categories.find((c) => c.name === 'COMMONS').channels.find((c) => c.key === 'untouched');
+  assert.equal('view' in entry, false, 'inherits the category, as it does in the guild');
+  assert.ok(warnings.some((w) => /untouched/.test(w)), 'the operator is told before they apply');
+});
+
+test('a CATEGORY with no managed overwrite is recorded as everyone, and warns', () => {
+  // The category-side twin of the channel null path above. A guild can carry a
+  // category the bot has never restricted; channels.json has no way to say
+  // "inherits" for a category (it is the top of the tree), so 'everyone' is the
+  // only expressible answer — and it is a WIDER claim than the guild made, which
+  // is exactly why it has to warn rather than pass silently.
+  const snapshot = {
+    categories: [{ id: '1', name: 'UNMANAGED', overwrites: [] }],
+    channels: [{ id: '10', name: 'chat', type: 0, parentId: '1', topic: '', overwrites: owFor('everyone') }],
+  };
+  const { config, warnings } = configFromSnapshot(snapshot, ctx);
+  assert.equal(config.categories[0].view, 'everyone');
+  assert.ok(
+    warnings.some((w) => /UNMANAGED/.test(w) && /confirm/i.test(w)),
+    'the operator is told the category view was assumed, not read'
+  );
+});
+
+test('the output is the shape channels.json actually declares', () => {
+  const { config } = configFromSnapshot(guild(), ctx);
+  assert.deepEqual(Object.keys(config), ['categories']);
+  for (const c of config.categories) {
+    assert.deepEqual(Object.keys(c).sort(), ['channels', 'name', 'view']);
+    for (const x of c.channels) {
+      for (const k of Object.keys(x)) assert.ok(['key', 'name', 'topic', 'view'].includes(k), `unexpected key ${k}`);
+    }
+  }
+});
+
+console.log(`\ndiscord_channels_snapshot: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);