@bongos/core 1.17.0 → 1.17.2

package/tests/publish_manifest.mjs

@@ -44,13 +44,13 @@ const PUBLISH = [
   'scripts/gds/ship.js',                   // the ship/grade pipeline publishes (sans secrets)
   'scripts/gds/publish-manifest.js',
   'scripts/migrate.sh',
-  'server.js',
   'migrations/182_some_change.sql',
   'tests/publish_manifest.mjs',
   'modules/lifecycle/db.js',
   'modules/grading/grader.js',
   'modules/hall-ui/public/work.js',
   'modules/dev-box/boxes.js',
+  'modules/provisioning/provisioning.js',  // instance-hosting control plane — CORE like its sibling dev-box (task 2135)
   // served-at-runtime surfaces a standalone must carry (task 2078) — their absence
   // from the packaged core 404'd the hall UI + /docs on demo.cloudbongos.com
   'clients/bongos-client/bongos-client.global.js', // /lib/bongos-client.js (window.BongosClient)
@@ -91,8 +91,19 @@ const EXCLUDE = [
   'src/world/terrain.js',
   'src/rooms/WorldRoom.js',
   'src/preview-server.js',
+  'server.js',                             // repo-root game+platform entry (top-level require('colyseus')); the core boots via src/platform-server.js (task 2134)
   'scripts/art/orchestrate.js',            // art-feature tooling under scripts/ (legacy location)
+  'scripts/gds/art-stage.js',              // art sandbox-staging CLI (requires modules/art-pipeline); excluded with the art feature (task 2135)
   'scripts/tile-add.js',
+  // host-feature tests that statically import an excluded module's source: shipped in the
+  // core package they'd MODULE_NOT_FOUND; excluded with the feature they cover (task 2147)
+  'tests/walkability.mjs',
+  'tests/terrain_picker.mjs',
+  'tests/snapshot_picker.mjs',
+  'tests/sprite_facing.mjs',
+  'tests/turn_in_place.mjs',
+  'tests/day_cycle.mjs',
+  'tests/art_key.mjs',
   // instance identity + history
   'config/branding.json',
   'config/modules.json',
@@ -106,6 +117,7 @@ const EXCLUDE = [
   'blockers/blockers.md',
   'limitations/v1-shipped.md',
   'generative-ideas.md',
+  'migrations/instance/018_pms_v3_planning_seed.sql',   // instance seed migrations = host scope-truth (ADR 0105, task 2140)
   '.env.local',
   // topology / deploy / CI / local gate hooks / secrets — read-sensitive docs
   'infra/Caddyfile',
@@ -180,5 +192,44 @@ t('allowlist + denylist are non-empty arrays of strings', () => {
   for (const g of [...PUBLISH_ALLOWLIST, ...PUBLISH_DENYLIST]) assert.equal(typeof g, 'string');
 });
 
+// ── R89 split guard: no PUBLISHABLE test may statically import an EXCLUDED module ─────
+// tests/ is allowlisted, but a test that imports host-module source (game / art-pipeline)
+// would ship inside the @bongos/core package WITHOUT that module → MODULE_NOT_FOUND when a
+// core CI/consumer runs it, and the cutover would delete OTB's own host tests. Every such
+// test must be host-excluded (see CONTENT_EXCLUDE). This DERIVES the set from disk so a NEW
+// host-module test can't slip in unlisted (the enumerated assertions above would miss it).
+// Static relative-literal imports only — temp-dir fixtures (modules/alpha, …) use path.join,
+// so they never match; a module name appearing only as string DATA (this file's own arrays)
+// isn't in a require()/import statement, so it never matches either. (task 2147)
+t('no publishable test statically imports an excluded module (R89 boundary)', () => {
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const { fileURLToPath } = require('node:url');
+  const testsDir = path.dirname(fileURLToPath(import.meta.url));
+  const IMPORT_RE = /(?:require|import)\s*\(\s*["'](\.\.?\/[^"']*?)modules\/([a-z0-9][a-z0-9-]*)\/[^"']*["']|from\s+["'](\.\.?\/[^"']*?)modules\/([a-z0-9][a-z0-9-]*)\/[^"']*["']/g;
+  const detected = [];   // test files that import ANY excluded module (non-vacuous check)
+  const offenders = [];  // …and are still publishable (the actual failure)
+  for (const name of fs.readdirSync(testsDir)) {
+    if (!/\.(mjs|js|cjs)$/.test(name)) continue;
+    const rel = `tests/${name}`;
+    const bad = new Set();
+    let m; IMPORT_RE.lastIndex = 0;
+    const src = fs.readFileSync(path.join(testsDir, name), 'utf8');
+    while ((m = IMPORT_RE.exec(src))) {
+      const key = m[2] || m[4];
+      if (key && !isPublishable(`modules/${key}/module.json`)) bad.add(key);
+    }
+    if (bad.size === 0) continue;
+    detected.push(rel);
+    if (isPublishable(rel)) {
+      offenders.push(`${rel} imports excluded module(s) [${[...bad].sort().join(', ')}] but is still PUBLISHABLE — add it to CONTENT_EXCLUDE (task 2147)`);
+    }
+  }
+  // non-vacuous: the scan must actually SEE the known host tests (a broken regex that
+  // matched nothing would otherwise pass silently). The 7 game/art tests are the floor.
+  assert.ok(detected.length >= 7, `expected ≥7 host-module tests detected, saw ${detected.length} — the import scan may be broken`);
+  assert.equal(offenders.length, 0, '\n        ' + offenders.join('\n        '));
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/run_routine.mjs

@@ -4,8 +4,9 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 const require = createRequire(import.meta.url);
-const { parseRoutineFrontmatter, tokenize } = require('../scripts/gds/run-routine.js');
+const { parseRoutineFrontmatter, tokenize, resolveStepArgv } = require('../scripts/gds/run-routine.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -65,5 +66,29 @@ test('tokenize splits argv and honors quotes', () => {
   assert.deepEqual(tokenize(''), []);
 });
 
+// resolveStepArgv — two-root step resolution (ADR 0108; task 2138). Explicit roots (pure).
+const ROOTS = { coreRoot: '/core', instanceRoot: '/inst' };
+
+test('resolveStepArgv: `bongos exec <rel>` resolves under the CORE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['bongos', 'exec', 'scripts/gds/box.js', 'sweep-idle', '--apply'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/box.js'), 'sweep-idle', '--apply']);
+});
+
+test('resolveStepArgv: `node scripts/...` → CORE root; `node .claude/...` companion → INSTANCE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['node', 'scripts/gds/x.js', '--flag'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/x.js'), '--flag']);
+  assert.deepEqual(
+    resolveStepArgv(['node', '.claude/scheduled-tasks/demo/run.js'], ROOTS),
+    [process.execPath, path.join('/inst', '.claude/scheduled-tasks/demo/run.js')]);
+});
+
+test('resolveStepArgv: absolute paths + non-node commands + empty pass through untouched', () => {
+  assert.deepEqual(resolveStepArgv(['node', '/abs/x.js'], ROOTS), ['node', '/abs/x.js']);
+  assert.deepEqual(resolveStepArgv(['bash', 'x.sh'], ROOTS), ['bash', 'x.sh']);
+  assert.deepEqual(resolveStepArgv([], ROOTS), []);
+});
+
 console.log(`\nrun_routine: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/run_routine_two_root.mjs

@@ -0,0 +1,77 @@
+// tests/run_routine_two_root.mjs — task 2138 (ADR 0108 configurable-root).
+//
+// Proves the deterministic cron dispatcher works in a real CONSUMER layout: it FINDS a routine
+// under resolveInstanceRoot() (the host repo — NOT the core root) and RUNS its companion step,
+// whose core require() resolves into node_modules/@bongos/core via the materialized
+// _core-resolve.js sibling. This is task 2138's "a consumer-layout dispatch finds + runs the
+// routines" done-when, exercised in a synthetic two-root tree.
+//
+// Counterfactual built in: the routine exists ONLY under the synthetic instance root, so against
+// the pre-2138 dispatcher (TASKS_DIR hardcoded to __dirname/../..) run-routine would look in THIS
+// repo, not find `demo`, and exit 2 — reddening this test. And the companion asserts its core lib
+// resolved from node_modules/@bongos/core (not the instance root), so a single-root resolve fails it.
+//
+// DB-free, no model. Run: node tests/run_routine_two_root.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(__dirname, '..'); // the core root (this repo), fixed by resolveCoreRoot()
+const RUN_ROUTINE = path.join(REPO, 'scripts', 'gds', 'run-routine.js');
+const CORE_RESOLVE = path.join(REPO, '.claude', 'hooks', '_core-resolve.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// Build a synthetic CONSUMER tree: instance content (.claude/) at its OWN root; the core installed
+// under node_modules/@bongos/core carrying just the one lib the companion needs.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rr-two-root-'));
+const inst = path.join(tmp, 'instance');
+try {
+  const coreLibDir = path.join(inst, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+  fs.mkdirSync(coreLibDir, { recursive: true });
+  fs.writeFileSync(path.join(coreLibDir, 'fake-core-lib.js'), 'module.exports = { ping: () => "CORE_OK" };\n');
+
+  // the materialized _core-resolve.js sibling (the real one — its resolution is what we exercise)
+  const hooksDir = path.join(inst, '.claude', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.copyFileSync(CORE_RESOLVE, path.join(hooksDir, '_core-resolve.js'));
+
+  // a materialized deterministic routine + its instance-path companion
+  const rtDir = path.join(inst, '.claude', 'scheduled-tasks', 'demo');
+  fs.mkdirSync(rtDir, { recursive: true });
+  fs.writeFileSync(path.join(rtDir, 'SKILL.md'),
+    ['---', 'name: demo', 'mode: deterministic', 'steps:',
+      '  - command: node .claude/scheduled-tasks/demo/run.js', '    sink: none', '---', 'body', ''].join('\n'));
+  fs.writeFileSync(path.join(rtDir, 'run.js'),
+    "const { requireCore, coreModulePath } = require('../../hooks/_core-resolve.js');\n" +
+    "const { ping } = requireCore('scripts/gds/fake-core-lib.js');\n" +
+    "console.log('RESOLVED=' + coreModulePath('scripts/gds/fake-core-lib.js'));\n" +
+    "console.log(ping());\n");
+
+  test('dispatch finds the routine under resolveInstanceRoot() and runs it; companion resolves core from node_modules', () => {
+    const out = execFileSync(process.execPath, [RUN_ROUTINE, 'demo'], {
+      encoding: 'utf8',
+      // Diverge the roots: OTB_INSTANCE_ROOT points resolveInstanceRoot() at the synthetic tree
+      // (OTB_ is an accepted legacy prefix; ADR 0108 §1); resolveCoreRoot() stays this repo.
+      // CLAUDE_PROJECT_DIR pins _core-resolve's own instance root to the synthetic tree too.
+      env: { ...process.env, OTB_INSTANCE_ROOT: inst, CLAUDE_PROJECT_DIR: inst },
+    });
+    assert.match(out, /CORE_OK/, 'companion step should have run and printed its core lib output');
+    assert.match(out, /RESOLVED=.*node_modules[/\\]@bongos[/\\]core[/\\]scripts[/\\]gds[/\\]fake-core-lib\.js/,
+      'the core lib must resolve from node_modules/@bongos/core, proving two-root (not single-root) resolution');
+  });
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\nrun_routine_two_root: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/scrubber_corpus.mjs

@@ -242,6 +242,23 @@ test('collectEnvSecrets: gathers secret-shaped env VALUES, skips benign & short'
   assert.ok(!out.includes(env.MAC_INSTALLER_CERT_P12) && !out.includes(env.APPLE_API_ISSUER_ID), 'env literals scrubbed');
 });
 
+test('collectEnvSecrets: benign shell PWD/OLDPWD are skipped, real *_PWD password vars still collected (task 2130)', () => {
+  // Regression: PWD/OLDPWD contain "pwd" (the password alternative in ENV_SECRET_KEY_RE)
+  // and hold a directory PATH ≥ 8 chars, so pre-fix they were collected as "secrets" — then
+  // the package-core no-leak gate aborted a legit publish whenever that path appeared verbatim
+  // in a functional file (a /Users/<name> anti-pattern comment), passing or failing purely on
+  // the operator's last `cd`. Exact-match exclusion, so genuine password vars still match.
+  const env = {
+    PWD: '/Users/larskristensen/dev/Claude-OTB',
+    OLDPWD: '/Users/larskristensen',
+    MYSQL_PWD: randStr(20, 40, B64URL), // a real password var — MUST still be collected
+  };
+  const got = collectEnvSecrets(env);
+  assert.ok(!got.includes(env.PWD), 'PWD (a directory path) must not be collected');
+  assert.ok(!got.includes(env.OLDPWD), 'OLDPWD (a directory path) must not be collected');
+  assert.ok(got.includes(env.MYSQL_PWD), 'MYSQL_PWD (a real password var) must still be collected');
+});
+
 test('self-reference `key = key` (SQL SET col = col) survives — zero recall loss', () => {
   // task 1688: the core packager redacts live SQL, so a `_token` COLUMN self-increment
   // must NOT be corrupted — while a real `key = <secret>` assignment is STILL redacted.

package/tests/served_paths_shipped.mjs

@@ -3,7 +3,7 @@
 // GUARD (task 2078): every static asset serve-internal.js reads at runtime from the
 // core tree MUST be included in the packaged core — i.e. isPublishable() per
 // scripts/gds/publish-manifest.js. A standalone instance runs the PACKAGED core
-// (@cloudbongos/core, ADR 0108), so a served path the publish boundary EXCLUDES is
+// (@bongos/core, ADR 0108), so a served path the publish boundary EXCLUDES is
 // simply absent on the box and 404s.
 //
 // This is exactly how demo.cloudbongos.com rendered a blank page: the browser client
@@ -101,7 +101,7 @@ test('every ROOT-served asset ships in the core package (isPublishable)', () =>
     offenders,
     [],
     `serve-internal.js reads these from ROOT but the publish boundary EXCLUDES them, so the ` +
-      `packaged core (@cloudbongos/core) omits them and a standalone 404s (task 2078): ${offenders.join(', ')}. ` +
+      `packaged core (@bongos/core) omits them and a standalone 404s (task 2078): ${offenders.join(', ')}. ` +
       `Fix: add each to PUBLISH_ALLOWLIST in scripts/gds/publish-manifest.js (or, if truly host-only, ` +
       `document it in INTENTIONALLY_UNSHIPPED in this test).`
   );

package/tests/task_cli.mjs

@@ -0,0 +1,99 @@
+// tests/task_cli.mjs
+//
+// task 2123 (demo-audit fix C1) — locks the PURE argv→body mapping of the new
+// `bongos task new` command (scripts/gds/task.js). Hermetic: no session/DB/network
+// (buildTaskBody never touches the API), so the pr-unit-tests gate auto-includes it.
+//
+// Run:  node tests/task_cli.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildTaskBody, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink } = require('../scripts/gds/task.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+t('requires --title and --description', () => {
+  const { errors } = buildTaskBody([]);
+  assert.ok(errors.some((e) => /--title/.test(e)));
+  assert.ok(errors.some((e) => /--description/.test(e)));
+});
+
+t('minimal valid: defaults kind=feature, discipline=engineer, status=backlog', () => {
+  const { body, errors } = buildTaskBody(['--title', 'T', '--description', 'D']);
+  assert.equal(errors.length, 0);
+  assert.equal(body.title, 'T');
+  assert.equal(body.description, 'D');
+  assert.equal(body.kind, 'feature');
+  assert.equal(body.discipline, 'engineer');
+  assert.equal(body.status, 'backlog');
+  assert.equal(body.source, 'bongos-task-cli');
+  // optional fields absent unless provided
+  assert.equal('priority' in body, false);
+  assert.equal('version_id' in body, false);
+  assert.equal('goal_id' in body, false);
+});
+
+t('--ready flips status to ready', () => {
+  const { body } = buildTaskBody(['--title', 'T', '--description', 'D', '--ready']);
+  assert.equal(body.status, 'ready');
+});
+
+t('maps all optional flags → body', () => {
+  const { body, criteria, errors } = buildTaskBody([
+    '--title', 'Add X', '--description', 'Because Y',
+    '--kind', 'bug', '--discipline', 'ui', '--priority', '2',
+    '--version', 'BONGOS-V1', '--goal', '26', '--criteria', 'C1,gcarry-prod-vanilla',
+    '--touches', 'src/a.js,tests/', '--est-minutes', '45', '--manual-degree', '3', '--credits', '15',
+  ]);
+  assert.equal(errors.length, 0);
+  assert.equal(body.kind, 'bug');
+  assert.equal(body.discipline, 'ui');
+  assert.equal(body.priority, 2);
+  assert.equal(body.version_id, 'BONGOS-V1');
+  assert.equal(body.goal_id, 26);
+  assert.deepEqual(body.touches, ['src/a.js', 'tests/']);
+  assert.deepEqual(body.criterion_ids, ['C1', 'gcarry-prod-vanilla']);
+  assert.deepEqual(criteria, ['C1', 'gcarry-prod-vanilla']);
+  assert.equal(body.est_minutes, 45);
+  assert.equal(body.manual_degree, 3);
+  assert.equal(body.credits_reward, 15);
+});
+
+t('rejects an invalid kind', () => {
+  const { errors } = buildTaskBody(['--title', 'T', '--description', 'D', '--kind', 'nonsense']);
+  assert.ok(errors.some((e) => /--kind/.test(e)));
+});
+
+t('rejects a priority out of 1–5', () => {
+  const { errors } = buildTaskBody(['--title', 'T', '--description', 'D', '--priority', '9']);
+  assert.ok(errors.some((e) => /--priority/.test(e)));
+});
+
+t('rejects a non-positive --goal', () => {
+  const { errors } = buildTaskBody(['--title', 'T', '--description', 'D', '--goal', '0']);
+  assert.ok(errors.some((e) => /--goal/.test(e)));
+});
+
+t('csv trims + drops blanks', () => {
+  assert.deepEqual(csv(' a , b ,,c '), ['a', 'b', 'c']);
+  assert.deepEqual(csv(''), []);
+});
+
+t('hallLink builds a hall URL from the API base origin, falls back cleanly', () => {
+  assert.equal(hallLink('https://demo.cloudbongos.com/api/bongos', 7), 'https://demo.cloudbongos.com/builders#/task/7');
+  assert.equal(hallLink('not-a-url', 7), 'task #7');
+});
+
+t('enum vocab is the expected shape', () => {
+  assert.ok(VALID_KINDS.includes('feature') && VALID_KINDS.includes('bug'));
+  assert.deepEqual(VALID_DISCIPLINES, ['engineer', 'artist', 'ideator', 'ui']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/update_channel.mjs

@@ -0,0 +1,186 @@
+// tests/update_channel.mjs
+//
+// task 2150 / ADR 0136 — the update-subscription policy core (scripts/gds/update-channel.js).
+// Pins the channel math + manifest loading the `core-update-subscription` routine relies on:
+//   1. semver — parse (incl. prerelease), compare precedence.
+//   2. channelAllows — the pinned/patch/minor blast-radius matrix; majors + prereleases never auto.
+//   3. resolveChannelTarget — highest permitted target, or null (pinned / nothing newer / unknown).
+//   4. parseNpmViewVersions — the array / bare-string / empty shapes npm view emits.
+//   5. listAvailableVersions — ok + fail-soft with an injected runner.
+//   6. loadSubscriptions — missing/malformed → empty; channel default + validate; env kept; dropless.
+//
+// DB-free + network-free (every external is injected). Run:  node tests/update_channel.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const uc = require('../scripts/gds/update-channel.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- semver ----------------------------------------------------------------
+
+t('parseSemver: plain, v-prefixed, prerelease, junk', () => {
+  assert.deepEqual(uc.parseSemver('1.17.2'), { major: 1, minor: 17, patch: 2, pre: '' });
+  assert.deepEqual(uc.parseSemver('v2.0.0'), { major: 2, minor: 0, patch: 0, pre: '' });
+  assert.deepEqual(uc.parseSemver('1.17.2-rc.1'), { major: 1, minor: 17, patch: 2, pre: 'rc.1' });
+  assert.equal(uc.parseSemver('1.17'), null);
+  assert.equal(uc.parseSemver('latest'), null);
+  assert.equal(uc.parseSemver(''), null);
+});
+
+t('compareSemver: numeric precedence + prerelease below stable', () => {
+  assert.equal(uc.compareSemver('1.17.2', '1.17.1'), 1);
+  assert.equal(uc.compareSemver('1.17.1', '1.18.0'), -1);
+  assert.equal(uc.compareSemver('1.17.1', '2.0.0'), -1);
+  assert.equal(uc.compareSemver('1.17.2', '1.17.2'), 0);
+  assert.equal(uc.compareSemver('1.17.2-rc.1', '1.17.2'), -1); // prerelease < stable
+  assert.equal(uc.compareSemver('bogus', '1.0.0'), -1);        // unparseable sorts lowest
+});
+
+t('normalizeChannel: valid pass through, unknown/blank → patch default', () => {
+  assert.equal(uc.normalizeChannel('pinned'), 'pinned');
+  assert.equal(uc.normalizeChannel('MINOR'), 'minor');
+  assert.equal(uc.normalizeChannel('major'), 'patch'); // major is not a valid auto-channel
+  assert.equal(uc.normalizeChannel(''), 'patch');
+  assert.equal(uc.normalizeChannel(undefined), 'patch');
+});
+
+// ---- channelAllows ---------------------------------------------------------
+
+t('channelAllows: patch stays within x.y', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.10', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'patch'), false); // minor bump not allowed on patch
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'patch'), false);
+});
+
+t('channelAllows: minor allows higher minor within the major, not a major', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.5', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'minor'), false); // major never automatic
+});
+
+t('channelAllows: pinned never; not-newer never; prerelease never; unknown installed never', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.99.99', 'pinned'), false);
+  assert.equal(uc.channelAllows('1.17.2', '1.17.1', 'patch'), false); // older
+  assert.equal(uc.channelAllows('1.17.1', '1.17.1', 'patch'), false); // same
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2-rc.1', 'patch'), false); // prerelease target
+  assert.equal(uc.channelAllows(null, '1.17.2', 'patch'), false);     // unknown installed
+  assert.equal(uc.channelAllows('1.17.1', 'garbage', 'patch'), false);
+});
+
+// ---- resolveChannelTarget --------------------------------------------------
+
+const AVAIL = ['1.16.9', '1.17.0', '1.17.1', '1.17.2', '1.17.3', '1.18.0', '1.18.1', '2.0.0', '1.17.4-rc.1'];
+
+t('resolveChannelTarget: patch → highest patch on the same minor', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: AVAIL }), '1.17.3');
+});
+
+t('resolveChannelTarget: minor → highest minor within the major (not 2.0.0)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'minor', available: AVAIL }), '1.18.1');
+});
+
+t('resolveChannelTarget: pinned → null', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'pinned', available: AVAIL }), null);
+});
+
+t('resolveChannelTarget: already newest → null; prerelease never chosen', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'patch', available: AVAIL }), null);
+  // A prerelease ahead (1.17.4-rc.1) is NOT a target even though it's numerically newer.
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'minor', available: ['1.17.4-rc.1'] }), null);
+});
+
+t('resolveChannelTarget: unknown installed / empty list → null (never guesses)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: null, channel: 'patch', available: AVAIL }), null);
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: [] }), null);
+  assert.equal(uc.resolveChannelTarget({}), null);
+});
+
+// ---- parseNpmViewVersions --------------------------------------------------
+
+t('parseNpmViewVersions: array, bare string, empty, malformed', () => {
+  assert.deepEqual(uc.parseNpmViewVersions('["1.0.0","1.1.0"]'), { ok: true, versions: ['1.0.0', '1.1.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('"1.0.0"'), { ok: true, versions: ['1.0.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('   '), { ok: true, versions: [] });
+  const bad = uc.parseNpmViewVersions('not json');
+  assert.equal(bad.ok, false);
+});
+
+// ---- listAvailableVersions (injected runner) -------------------------------
+
+t('listAvailableVersions: ok path parses stdout; non-zero exit is fail-soft', () => {
+  const ok = uc.listAvailableVersions({ run: () => ({ status: 0, stdout: '["1.17.1","1.17.2"]' }) });
+  assert.deepEqual(ok, { ok: true, versions: ['1.17.1', '1.17.2'] });
+
+  const fail = uc.listAvailableVersions({ run: () => ({ status: 1, stderr: 'E404 Not Found' }) });
+  assert.equal(fail.ok, false);
+  assert.match(fail.error, /E404/);
+
+  const threw = uc.listAvailableVersions({ run: () => { throw new Error('spawn ENOENT'); } });
+  assert.equal(threw.ok, false);
+  assert.match(threw.error, /ENOENT/);
+});
+
+// ---- loadSubscriptions -----------------------------------------------------
+
+function scratchWith(obj) {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-'));
+  const cfgDir = join(dir, 'config');
+  require('node:fs').mkdirSync(cfgDir, { recursive: true });
+  writeFileSync(join(cfgDir, 'update-subscriptions.json'), typeof obj === 'string' ? obj : JSON.stringify(obj));
+  return dir;
+}
+
+t('loadSubscriptions: missing file → empty roster, present:false, no throw', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-none-'));
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.equal(r.present, false);
+  assert.equal(r.defaultChannel, 'patch');
+});
+
+t('loadSubscriptions: malformed JSON → empty + error, no throw', () => {
+  const dir = scratchWith('{ not valid');
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.match(r.error, /malformed JSON/);
+});
+
+t('loadSubscriptions: normalizes channel, keeps env, defaults from defaultChannel', () => {
+  const dir = scratchWith({
+    defaultChannel: 'minor',
+    instances: [
+      { slug: 'demo', dir: '/srv/demo', service: 'demo.service', healthUrl: 'https://demo/healthz', env: { PGDATABASE: 'demo', BAD: 5 } },
+      { slug: 'pinnedone', dir: '/srv/p', channel: 'PINNED' },
+      { slug: 'nochan', dir: '/srv/n' },
+    ],
+  });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.defaultChannel, 'minor');
+  assert.equal(r.instances.length, 3);
+  const demo = r.instances.find((i) => i.slug === 'demo');
+  assert.equal(demo.channel, 'minor');            // inherited from defaultChannel
+  assert.deepEqual(demo.env, { PGDATABASE: 'demo' }); // non-string env value dropped
+  assert.equal(r.instances.find((i) => i.slug === 'pinnedone').channel, 'pinned');
+  assert.equal(r.instances.find((i) => i.slug === 'nochan').channel, 'minor');
+});
+
+t('loadSubscriptions: an entry without a dir is dropped (cannot be upgraded)', () => {
+  const dir = scratchWith({ instances: [{ slug: 'ghost' }, { slug: 'real', dir: '/srv/real' }] });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.instances.length, 1);
+  assert.equal(r.instances[0].slug, 'real');
+});
+
+console.log(`\nupdate_channel: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);