@bongos/core 1.19.850 → 1.19.852

package/tests/curve_kind_overlay.mjs

@@ -0,0 +1,298 @@
+// tests/curve_kind_overlay.mjs — the dev curve's kind filter + ecosystem overlay
+// (task 1004005, split from task 1004004 part D).
+//
+// Three things are pinned here, and each one is a claim that can be made FALSELY
+// while every chart still renders:
+//
+//   1. THE OVERLAY SHARES A SCALE. Two lines each fitted to their own min/max
+//      are not a comparison — they are two unrelated shapes that look like one.
+//      A chart that does this is worse than no benchmark, because the reader
+//      believes they are reading one.
+//   2. THE SINGLE-SERIES PATH IS UNTOUCHED. modules/hall-ui/CLAUDE.md records
+//      one-series-per-chart as a deliberate decision, and every other chart in
+//      the hall shares this kit. The overlay is an addition, so a caller that
+//      passes no overlay must get back exactly the bytes it got before.
+//   3. BOTH SIDES OF A COMPARISON ARE NARROWED THE SAME WAY. A kind-filtered
+//      line against an unfiltered benchmark is the same lie as (1), one layer
+//      up — so the ecosystem query takes the same `kind`, and cost, which
+//      CANNOT be narrowed by kind, is withheld rather than faked.
+//
+// The kit is a browser IIFE on `window`, so it is evaluated in a vm with a
+// window stub — the hall_kit / hall_landing_boot pattern.
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function loadKit() {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-kit.js'), 'utf8');
+  const win = {};
+  const ctx = vm.createContext({ window: win, document: { createElement: () => ({}) }, console });
+  vm.runInContext(src, ctx);
+  assert.ok(win.OTBKit, 'hall-kit.js did not publish window.OTBKit');
+  return win.OTBKit;
+}
+
+const KIT = loadKit();
+
+// Pull the y of each point out of a `points="x,y x,y"` polyline.
+function ysOf(svg, cls) {
+  const m = new RegExp(`class="${cls}" points="([^"]+)"`).exec(svg);
+  if (!m) return null;
+  return m[1].trim().split(/\s+/).map((p) => Number(p.split(',')[1]));
+}
+
+// ── 1. The shared scale ──────────────────────────────────────────────────────
+
+test('an overlaid chart fits BOTH series to one scale', () => {
+  // Own series 0..10, benchmark 0..100. On a shared scale the own line must sit
+  // in the BOTTOM tenth of the box; on two independent scales it would fill the
+  // box exactly as if the benchmark were not there, and the reader would see
+  // "level with everyone" where the truth is "a tenth of everyone".
+  const own = [0, 5, 10];
+  const eco = [0, 50, 100];
+  const solo = KIT.sparklineHtml(own, { color: 'var(--accent)' });
+  const both = KIT.sparklineHtml(own, { color: 'var(--accent)', overlay: eco });
+
+  const soloY = ysOf(solo, 'kit-spark__line');
+  const bothY = ysOf(both, 'kit-spark__line');
+  const ecoY = ysOf(both, 'kit-spark__overlay');
+
+  assert.ok(soloY && bothY && ecoY, 'expected an own line and an overlay line');
+  assert.notDeepEqual(bothY, soloY,
+    'the own series was drawn identically with and without the benchmark — the two series are NOT sharing a scale');
+
+  // SVG y grows downward, so a bigger y is a lower value. The own series' top
+  // must sit BELOW the benchmark's top by most of the box.
+  const ownTop = Math.min(...bothY);
+  const ecoTop = Math.min(...ecoY);
+  const ownBottom = Math.max(...bothY);
+  assert.ok(ownTop > ecoTop, 'the smaller series must not reach as high as the larger one');
+  // Own spans 10 of a 0..100 range, so its drawn height is ~1/10 of the overlay's.
+  const ownHeight = ownBottom - ownTop;
+  const ecoHeight = Math.max(...ecoY) - ecoTop;
+  assert.ok(ownHeight < ecoHeight * 0.25,
+    `own series drew ${ownHeight.toFixed(1)}px against the benchmark's ${ecoHeight.toFixed(1)}px — expected roughly a tenth`);
+});
+
+test('the scale is shared SYMMETRICALLY — an own series larger than the benchmark still fits', () => {
+  // The mirror of the case above. If only the overlay were folded into the
+  // scale, a builder shipping more than the average would run off the top of
+  // the box and be silently clipped at exactly the moment the chart has good
+  // news to deliver.
+  const svg = KIT.sparklineHtml([0, 50, 100], { overlay: [0, 5, 10] });
+  const ys = ysOf(svg, 'kit-spark__line');
+  const H = 46; // CHART_H
+  assert.ok(Math.min(...ys) >= 0 && Math.max(...ys) <= H,
+    `own series left the viewBox: ${JSON.stringify(ys)}`);
+});
+
+test('two series of DIFFERENT length each span the full width', () => {
+  // The builder's window and the ecosystem's need not have the same number of
+  // days with data. Each series gets its own x spread over the same box, so a
+  // sparser one is stretched rather than crammed into a corner.
+  const svg = KIT.sparklineHtml([1, 2, 3, 4], { overlay: [1, 4] });
+  const over = /class="kit-spark__overlay" points="([^"]+)"/.exec(svg)[1].trim().split(/\s+/);
+  assert.equal(over.length, 2);
+  const xs = over.map((p) => Number(p.split(',')[0]));
+  assert.ok(xs[0] < 10 && xs[1] > 250, `overlay did not span the box: ${JSON.stringify(xs)}`);
+});
+
+// ── 2. The single-series path is untouched ───────────────────────────────────
+
+test('no overlay means byte-identical output — the one-series rule still holds', () => {
+  for (const values of [[1, 2, 3], [7], [], [0, 0, 0], [5, -3, 9]]) {
+    const a = KIT.sparklineHtml(values, { color: 'var(--sea)' });
+    const b = KIT.sparklineHtml(values, { color: 'var(--sea)', overlay: undefined });
+    assert.equal(a, b, `overlay:undefined changed the output for ${JSON.stringify(values)}`);
+    assert.ok(!a.includes('kit-spark__overlay'), 'a single-series chart drew an overlay element');
+  }
+});
+
+test('an EMPTY overlay is not an overlay', () => {
+  // A builder whose ecosystem feed failed, or a kind nobody else has shipped,
+  // must get the ordinary one-line chart — not a chart claiming a benchmark it
+  // has no data for.
+  const plain = KIT.sparklineHtml([1, 2, 3]);
+  assert.equal(KIT.sparklineHtml([1, 2, 3], { overlay: [] }), plain);
+  assert.equal(KIT.sparklineHtml([1, 2, 3], { overlay: null }), plain);
+});
+
+test('linePoints without scaleWith is unchanged', () => {
+  const a = KIT.linePoints([3, 1, 4, 1, 5]);
+  const b = KIT.linePoints([3, 1, 4, 1, 5], { scaleWith: undefined });
+  assert.equal(a.points, b.points);
+});
+
+test('the benchmark is drawn UNDER the subject, and carries no area fill', () => {
+  // Paint order is the encoding: the subject's own line must win where they
+  // cross. And a second filled area would muddy both until neither reads as the
+  // figure.
+  const svg = KIT.sparklineHtml([1, 5, 2], { overlay: [2, 3, 4] });
+  const iOverlay = svg.indexOf('kit-spark__overlay');
+  const iArea = svg.indexOf('kit-spark__area');
+  const iLine = svg.indexOf('kit-spark__line');
+  assert.ok(iOverlay !== -1 && iOverlay < iArea && iOverlay < iLine,
+    'the benchmark must be emitted before the subject so it renders beneath it');
+  assert.equal((svg.match(/kit-spark__area/g) || []).length, 1, 'only the subject may have an area fill');
+  assert.match(svg, /class="kit-spark__overlay"[^>]*fill="none"/);
+});
+
+test('an overlaid chart says so in its accessible label', () => {
+  // A screen-reader user gets the aria-label and nothing else; without the
+  // benchmark named there, the second line simply does not exist for them.
+  const svg = KIT.sparklineHtml([1, 2, 3], { overlay: [4, 5, 6], overlayLabel: 'all builders' });
+  const label = /aria-label="([^"]+)"/.exec(svg)[1];
+  assert.match(label, /all builders/);
+  assert.match(label, /latest 3/);
+});
+
+// ── The legend ───────────────────────────────────────────────────────────────
+
+test('a legend is drawn for two series and withheld for fewer', () => {
+  assert.equal(KIT.chartLegendHtml([{ label: 'You', color: 'var(--accent)' }]), '',
+    'one series needs no key — that is why the hall had no legend before the overlay');
+  assert.equal(KIT.chartLegendHtml([]), '');
+  const two = KIT.chartLegendHtml([
+    { label: 'You', color: 'var(--accent)' },
+    { label: 'All builders', color: 'var(--ink-soft)' },
+  ]);
+  assert.match(two, /You/);
+  assert.match(two, /All builders/);
+});
+
+test('the legend swatch survives a var() colour', () => {
+  // The regression this shape exists to prevent: CSS_LEN in the kit REFUSES
+  // `var(`, so routing a chart colour through a style attribute would blank
+  // every swatch and leave a legend of unlabelled colours. An SVG fill attribute
+  // is the path the kit already uses for exactly these values.
+  const html = KIT.chartLegendHtml([
+    { label: 'You', color: 'var(--accent-deep)' },
+    { label: 'All builders', color: 'var(--ink-soft)' },
+  ]);
+  assert.match(html, /fill="var\(--accent-deep\)"/, 'the swatch colour was dropped');
+  assert.match(html, /fill="var\(--ink-soft\)"/);
+  assert.ok(!html.includes('style="background:"'), 'an emptied style attribute means the colour was refused');
+});
+
+test('a legend label is escaped, not interpolated raw', () => {
+  const html = KIT.chartLegendHtml([
+    { label: '<img src=x onerror=alert(1)>', color: 'var(--accent)' },
+    { label: 'All builders', color: 'var(--ink-soft)' },
+  ]);
+  assert.ok(!html.includes('<img'), 'a legend label reached the DOM as markup');
+});
+
+// ── 3. Both sides narrowed the same way (the server contract) ────────────────
+
+const ANALYTICS = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/db-analytics.js'), 'utf8');
+const ROUTES = fs.readFileSync(path.join(ROOT, 'modules/lifecycle/routes/analytics.js'), 'utf8');
+
+function fnBody(src, name) {
+  const start = src.indexOf(`async function ${name}(`);
+  assert.notEqual(start, -1, `${name} not found`);
+  const end = src.indexOf('\n}', src.indexOf('  return {', start));
+  return src.slice(start, end);
+}
+
+test('BOTH analytics functions take a kind — a one-sided filter is the lie this prevents', () => {
+  assert.match(ANALYTICS, /async function builderAnalytics\(builderId, days = 90, kind = null\)/);
+  assert.match(ANALYTICS, /async function ecosystemAnalytics\(days = 90, kind = null\)/);
+});
+
+test('both routes pass the caller\'s kind through', () => {
+  assert.match(ROUTES, /db\.builderAnalytics\(targetId, days, parseKind\(req\.query\.kind\)\)/);
+  assert.match(ROUTES, /db\.ecosystemAnalytics\(days, parseKind\(req\.query\.kind\)\)/);
+});
+
+test('the kind is a BOUND parameter everywhere, never interpolated into SQL', () => {
+  // The filter reaches a GROUP BY on two hot tables; a template-literal kind
+  // would be an injection point on a route that is, on the ecosystem side,
+  // unauthenticated.
+  for (const [name, body] of [['builderAnalytics', fnBody(ANALYTICS, 'builderAnalytics')],
+    ['ecosystemAnalytics', fnBody(ANALYTICS, 'ecosystemAnalytics')]]) {
+    assert.ok(!/COALESCE\(kind, 'unspecified'\) = \$\{/.test(body),
+      `${name} interpolates the kind into SQL`);
+    assert.match(body, /\$\d::text IS NULL OR COALESCE\(kind, 'unspecified'\) = \$\d/,
+      `${name} has no bound kind predicate`);
+  }
+});
+
+test('top_kinds is NEVER narrowed — it is the picker\'s own source', () => {
+  // Narrowing it would leave the reader one bar and no way back to the others:
+  // the control that caused the filter would lose the options to undo it.
+  for (const name of ['builderAnalytics', 'ecosystemAnalytics']) {
+    const body = fnBody(ANALYTICS, name);
+    const q = body.indexOf("COALESCE(kind, 'unspecified') AS kind, COUNT(*)::int AS n");
+    assert.notEqual(q, -1, `${name} has no top_kinds query`);
+    // The params array immediately after that query must not carry the kind.
+    const tail = body.slice(q, q + 700);
+    const params = /\n\s*\[([^\]]*)\]/.exec(tail);
+    assert.ok(params, `could not read top_kinds params in ${name}`);
+    assert.ok(!/\bk\b/.test(params[1]),
+      `${name}'s top_kinds is filtered by kind (params: [${params[1]}]) — the picker would lose its options`);
+  }
+});
+
+test('cost is WITHHELD under a kind filter, not faked', () => {
+  // cost_log has no kind and reaches tasks only through a nullable task_id that
+  // is NULL for most rows, so a kind-filtered cost line would drop nearly every
+  // cost row and plot a near-zero trend that reads like genuinely cheap work.
+  const body = fnBody(ANALYTICS, 'builderAnalytics');
+  assert.match(body, /k !== null \? \{ rows: \[\] \} : pool\.query\(/,
+    'the cost query must be skipped under a kind filter, not run and discarded');
+  assert.match(body, /unavailable: k === null \? \[\] : \['cost_trend', 'cost_per_task', 'total_cost_usd'\]/,
+    'the payload must NAME what it cannot answer');
+  assert.match(body, /total_cost_usd: k === null \?[^\n]*: null/,
+    'cost must be null under a filter — 0 is a measurement, this is the absence of one');
+});
+
+test('the client hides the cost chart and stat rather than printing $0.00', () => {
+  const render = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-render.js'), 'utf8');
+  assert.match(render, /costUnavailable = Array\.isArray\(data\.unavailable\) && data\.unavailable\.includes\('cost_trend'\)/);
+  assert.match(render, /costUnavailable\s*\?\s*statCard\('Cost \/ work', '—'/,
+    'a withheld cost must render as —, never as a price');
+});
+
+test('the controls are written BEFORE every early return', () => {
+  // A kind with nothing shipped in the window takes the totalShipped === 0
+  // branch, which blanks the body. If the filter were drawn after that, the
+  // reader would be stranded at "no data" with no control to undo it.
+  const render = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-render.js'), 'utf8');
+  const fn = render.slice(render.indexOf('function renderCurveBody()'));
+  const controls = fn.indexOf('kindFilterHtml()');
+  const firstReturn = fn.indexOf('if (!data) {');
+  const emptyReturn = fn.indexOf('if (totalShipped === 0)');
+  assert.ok(controls !== -1 && firstReturn !== -1 && emptyReturn !== -1);
+  assert.ok(controls < firstReturn && controls < emptyReturn,
+    'the kind filter is rendered after an early return — an empty result would strand the reader behind it');
+});
+
+test('the scope toggle is no longer rank-gated', () => {
+  const render = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-render.js'), 'utf8');
+  const builders = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/builders.js'), 'utf8');
+  assert.ok(!/analyticsState\.isArchon\s*&&/.test(render),
+    'the scope toggle is still gated on rank');
+  // The field is REMOVED, not merely unread — a write-only state flag is how a
+  // deleted gate quietly grows back.
+  assert.ok(!/analyticsState\.isArchon\s*=/.test(builders),
+    'analyticsState.isArchon is still assigned; remove the field, not just its reader');
+  assert.ok(!/if \(analyticsState\.isArchon\) \{/.test(builders),
+    'the ecosystem fetch is still behind the Archon gate');
+});
+
+test('a kind change re-fetches BOTH series, and the newest answer wins', () => {
+  const builders = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/builders.js'), 'utf8');
+  const fn = builders.slice(builders.indexOf('async function reloadCurveForKind'));
+  const body = fn.slice(0, fn.indexOf('\n  }') + 4);
+  assert.match(body, /analytics\/builder\/\$\{id\}\?days=90\$\{q\}/);
+  assert.match(body, /public\/analytics\/ecosystem\?days=90\$\{q\}/);
+  // Out-of-order responses: a dropdown changes faster than a round trip.
+  assert.match(body, /seq !== curveKindSeq/, 'a stale response can overwrite a newer one');
+  assert.match(body, /encodeURIComponent\(kind\)/, 'the kind must be encoded into the query string');
+});

package/tests/markdown_line_endings.mjs

@@ -0,0 +1,78 @@
+// tests/markdown_line_endings.mjs — *.md is pinned to LF in .gitattributes (task 1003981).
+//
+// WHAT THIS GUARDS. At least six tools in this repo read a .md file AS TEXT and make a
+// decision from what they parse: skill-preflight.js (SKILL.md frontmatter), fitness.js
+// G03, linkify-refs.js, docs-entropy.js, the role-pack guard and the doc-CLI guard.
+// Before this pin, *.md fell through `* text=auto`, so a Windows clone with the common
+// core.autocrlf=true got CRLF in the worktree for 834 of 835 tracked .md files while the
+// index stayed LF. A CRLF-blind reader does not fail loudly — it parses nothing, and a
+// guard with nothing to compare cannot fail. Measured on task 1003754: skill-preflight's
+// /^---\n/ frontmatter regex matched ZERO of 53 skills, and G03 duly reported
+// "53 skill(s) scanned; 0 declare a machine contract" while staying green.
+//
+// Asserted through GIT ITSELF (`git check-attr`), not by pattern-matching .gitattributes:
+// the pattern semantics are git's, and the failure mode this replaces was precisely a
+// rule that read correctly but did not match what it was believed to match (the
+// root-anchored /CLAUDE.md lesson in tests/git_merge_regen.mjs). Reading the file back
+// would re-assert our own spelling rather than git's resolution of it.
+//
+// Run:  node --test tests/markdown_line_endings.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repo = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const git = (args) => spawnSync('git', args, { cwd: repo, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+
+const eolOf = (p) => {
+  const r = git(['check-attr', 'eol', '--', p]);
+  return (r.stdout || '').trim().split(': ').pop();
+};
+
+// Representative paths, chosen for DEPTH rather than count: a gitattributes pattern
+// with no leading slash matches at any depth, and the bug being pinned bit a .md
+// four directories down, not one at the root.
+test('every tracked .md resolves to eol=lf, at any depth', () => {
+  for (const p of [
+    'README.md',
+    'CLAUDE.md',
+    'docs/architecture.md',
+    'docs/packs/engineer.md',
+    'docs/adr/README.md',
+    '.claude/skills/merge-mode/SKILL.md',
+    'modules/hall-ui/CLAUDE.md',
+  ]) {
+    assert.equal(eolOf(p), 'lf', `${p} must be pinned to LF — a CRLF copy silently voids every reader that parses it`);
+  }
+});
+
+// The invariant that actually matters, over the REAL tracked set rather than a sample.
+// `git ls-files --eol` reports the index ("i/") and worktree ("w/") encodings side by
+// side; the index is what every clone receives, so an index CRLF is the state that
+// would ship the bug to someone else's checkout.
+test('no tracked .md carries CRLF in the index', () => {
+  const r = git(['ls-files', '--eol', '-z', '*.md']);
+  assert.equal(r.status, 0, 'git ls-files --eol must succeed');
+  const rows = (r.stdout || '').split('\0').filter(Boolean);
+  assert.ok(rows.length > 500, `expected the full markdown set, got ${rows.length} rows`);
+
+  const crlf = rows.filter((row) => /^i\/crlf/.test(row.trim())).map((row) => row.trim());
+  assert.deepEqual(crlf, [], `these .md files are CRLF in the index: ${crlf.join(', ')}`);
+});
+
+// The complementary half, and the reason this is not just `*` pinned to LF: the repo
+// deliberately ships CRLF for the Windows-shell wrappers, where cmd.exe and PowerShell
+// expect it. A future over-broad edit that pinned everything to LF would silently break
+// those, and the markdown assertions above would keep passing while it did.
+test('the Windows-shell classes stay pinned to CRLF', () => {
+  // scripts/gds/api.ps1 is the one such file that exists today; the .cmd/.bat spellings
+  // are the declared-up-front rules for the wrappers .gitattributes says do not exist yet.
+  // check-attr resolves a PATTERN, so it answers for those too — which is the point here.
+  for (const p of ['scripts/gds/api.ps1', 'scripts/setup-builder.cmd', 'scripts/setup-builder.bat']) {
+    assert.equal(eolOf(p), 'crlf', `${p} must stay CRLF — cmd.exe/PowerShell expect it`);
+  }
+});

package/tests/provision.mjs

@@ -28,6 +28,12 @@ const NEUTRAL_PREFIX =
   JSON.parse(readFileSync(new URL('../config/branding.neutral.json', import.meta.url), 'utf8')).envPrefix || 'CLOUDBONGOS';
 const reEsc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
+// The scaffold-composition assertions below pin the remote as `git@github-deploy:…`.
+// Since task 1003996 that alias is the default only where it actually RESOLVES, so pin
+// it here rather than inheriting whatever ~/.ssh/config the test machine happens to have
+// (the resolution rule itself is covered directly, with an injected probe).
+process.env.PROVISION_GIT_SSH_ALIAS = 'github-deploy';
+
 let passed = 0, failed = 0;
 function t(name, fn) {
   try { fn(); passed++; console.log(`  PASS  ${name}`); }
@@ -528,9 +534,46 @@ t('parseTargetRef: owner/repo, SSH + HTTPS URLs, .git suffix; garbage → null',
   assert.equal(P.parseTargetRef(null), null);
 });
 
-t('instanceRepoRemote: reuses the SSH deploy alias (no secret in the URL); alias overridable', () => {
-  assert.equal(P.instanceRepoRemote({ owner: 'example-owner', name: 'demo' }), 'git@github-deploy:example-owner/demo.git');
-  assert.equal(P.instanceRepoRemote({ owner: 'o', name: 'r' }, { sshAlias: 'gh-alt' }), 'git@gh-alt:o/r.git');
+t('instanceRepoRemote: the deploy alias only where it RESOLVES, else github.com directly', () => {
+  // `ssh -G <name>` prints the effective config: a real `Host` block rewrites `hostname`,
+  // an absent one echoes the name straight back. That difference is the whole probe.
+  const wired = () => 'user git\nhostname github.com\nport 22\n';
+  const absent = (a) => `user x\nhostname ${a}\nport 22\n`;
+  const saved = process.env.PROVISION_GIT_SSH_ALIAS;
+  delete process.env.PROVISION_GIT_SSH_ALIAS;
+  try {
+    assert.equal(
+      P.instanceRepoRemote({ owner: 'example-owner', name: 'demo' }, { runSsh: wired }),
+      'git@github-deploy:example-owner/demo.git', 'founder box: alias resolves, transport unchanged');
+    assert.equal(
+      P.instanceRepoRemote({ owner: 'example-owner', name: 'demo' }, { runSsh: absent }),
+      'git@github.com:example-owner/demo.git', 'any other plane: no alias, so address GitHub directly');
+    assert.equal(
+      P.instanceRepoRemote({ owner: 'o', name: 'r' }, { runSsh: () => { throw new Error('ssh: not found'); } }),
+      'git@github.com:o/r.git', 'no ssh client at all is not an alias either');
+    process.env.PROVISION_GIT_SSH_ALIAS = 'gh-env';
+    assert.equal(P.instanceRepoRemote({ owner: 'o', name: 'r' }, { runSsh: absent }),
+      'git@gh-env:o/r.git', 'PROVISION_GIT_SSH_ALIAS wins over the probe');
+    assert.equal(P.instanceRepoRemote({ owner: 'o', name: 'r' }, { sshAlias: 'gh-alt', runSsh: absent }),
+      'git@gh-alt:o/r.git', 'an explicit alias wins over both');
+  } finally {
+    if (saved === undefined) delete process.env.PROVISION_GIT_SSH_ALIAS;
+    else process.env.PROVISION_GIT_SSH_ALIAS = saved;
+  }
+});
+
+t('instanceRepoRemotes: the accept-set a stored remote is validated against, probe-free', () => {
+  const { instanceRepoRemotes } = createRequire(import.meta.url)('../scripts/gds/provision-repo-auth.js');
+  const urls = instanceRepoRemotes({ owner: 'o', name: 'r' });
+  // github-deploy is in the set even here, where it does NOT resolve: upgrade.js must keep
+  // recognising a remote an alias-carrying box wrote.
+  assert.ok(urls.includes('git@github-deploy:o/r.git'), 'the deploy-alias form stays ours');
+  assert.ok(urls.includes('git@github.com:o/r.git'), 'so does the direct form');
+  const saved = process.env.PROVISION_GIT_SSH_ALIAS;
+  process.env.PROVISION_GIT_SSH_ALIAS = 'gh-env';
+  try {
+    assert.ok(instanceRepoRemotes({ owner: 'o', name: 'r' }).includes('git@gh-env:o/r.git'), 'and the configured one');
+  } finally { process.env.PROVISION_GIT_SSH_ALIAS = saved; }
 });
 
 t('instanceInitSpec: builds a VALID greenfield init spec from the row + owner login', () => {

package/tests/update_channel.mjs

@@ -48,6 +48,24 @@ t('compareSemver: numeric precedence + prerelease below stable', () => {
   assert.equal(uc.compareSemver('bogus', '1.0.0'), -1);        // unparseable sorts lowest
 });
 
+// task 1004009: `bongos upgrade` now asks "is --to OLDER than what is installed?", so two
+// orderings this module never needed for auto-targeting have a caller that depends on them.
+t('compareSemver: two prereleases of one x.y.z are ordered by semver precedence', () => {
+  assert.equal(uc.compareSemver('1.20.0-rc.1', '1.20.0-rc.2'), -1);
+  assert.equal(uc.compareSemver('1.20.0-rc.10', '1.20.0-rc.2'), 1, 'numeric identifiers compare as numbers, not text');
+  assert.equal(uc.compareSemver('1.20.0-rc.1', '1.20.0-rc'), 1, 'the longer identifier list wins a tie');
+  assert.equal(uc.compareSemver('1.20.0-1', '1.20.0-alpha'), -1, 'a numeric identifier sorts below a text one');
+  assert.equal(uc.compareSemver('1.20.0-beta', '1.20.0-alpha'), 1);
+  assert.equal(uc.compareSemver('1.20.0-rc.1', '1.20.0-rc.1'), 0);
+});
+
+t('parseSemver: build metadata parses and never changes precedence', () => {
+  assert.deepEqual(uc.parseSemver('1.19.840+hotfix'), { major: 1, minor: 19, patch: 840, pre: '' });
+  assert.deepEqual(uc.parseSemver('1.19.840-rc.1+b7'), { major: 1, minor: 19, patch: 840, pre: 'rc.1' });
+  assert.equal(uc.compareSemver('1.19.840+hotfix', '1.19.840'), 0);
+  assert.equal(uc.compareSemver('1.19.840+hotfix', '1.19.841'), -1);
+});
+
 t('normalizeChannel: valid pass through, unknown/blank → patch default', () => {
   assert.equal(uc.normalizeChannel('pinned'), 'pinned');
   assert.equal(uc.normalizeChannel('MINOR'), 'minor');
@@ -133,6 +151,19 @@ t('listAvailableVersions: ok path parses stdout; non-zero exit is fail-soft', ()
   assert.match(threw.error, /ENOENT/);
 });
 
+t('listAvailableVersions: the registry read carries a timeout, so a hung npm cannot stall a sweep or a refusal', () => {
+  const seen = [];
+  const run = (cmd, args, o) => { seen.push(o.timeout); return { status: 0, stdout: '[]' }; };
+  uc.listAvailableVersions({ run });
+  uc.listAvailableVersions({ run, timeoutMs: 1234 });
+  assert.ok(seen[0] > 0, 'a default, not an opt-in — every existing caller gets it');
+  assert.equal(seen[1], 1234);
+  // spawnSync reports a timeout as { error, status: null } — the fail-soft path, not a throw.
+  const hung = uc.listAvailableVersions({ run: () => ({ status: null, error: new Error('spawnSync npm ETIMEDOUT') }) });
+  assert.equal(hung.ok, false);
+  assert.match(hung.error, /ETIMEDOUT/);
+});
+
 // ---- loadSubscriptions -----------------------------------------------------
 
 function scratchWith(obj) {

package/tests/upgrade.mjs

@@ -1557,7 +1557,9 @@ t('pinnedDeployKey / remoteGithubRepo: read the ADR 0176 wiring off the checkout
   assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://github.com/acme/widgets')), acme);
   assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://x-access-token@github.com/acme/widgets.git')), acme);
   const P = require('../scripts/gds/provision.js');
-  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at(P.instanceRepoRemote(acme))), acme, 'the shared SSH alias the public scaffold wires is GitHub too');
+  // Pin the alias: since task 1003996 it is the scaffold's default only on a box where it
+  // resolves, and this assertion is about the ALIAS branch being recognised as GitHub.
+  assert.deepEqual(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at(P.instanceRepoRemote(acme, { sshAlias: 'github-deploy' }))), acme, 'the shared SSH alias the public scaffold wires is GitHub too');
   assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('https://gitlab.com/acme/widgets.git')), null, 'another host is never pointed at github.com');
   assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', at('git@bitbucket.org:acme/widgets.git')), null);
   assert.equal(u.remoteGithubRepo('/srv/bongos/acme', 'origin', pinRun()), null, 'no such remote');
@@ -1714,6 +1716,145 @@ t('runUpgrade --commit-pin --pin-no-push: a generator that did not run contribut
   assert.ok(!calls.some((c) => c.startsWith('git push')), '--pin-no-push');
 });
 
+// ---- 11. a --to OLDER than the installed core is refused (task 1004009) ------
+
+// A registry that answers `npm view … versions --json`, on top of the pin-aware shim.
+function registryRun(calls, { dir, published = null, registryDown = false } = {}) {
+  const base = pinAwareRun(calls, { dir });
+  return (cmd, args, o) => {
+    if (cmd === 'npm' && args[0] === 'view') {
+      calls.push(`npm ${args.join(' ')}`);
+      assert.ok(o.timeout > 0, 'the registry read only words a refusal — it must not be able to hang one');
+      return registryDown ? { status: 1, stderr: 'npm error code E404' } : { status: 0, stdout: JSON.stringify(published || []) };
+    }
+    return base(cmd, args, o);
+  };
+}
+
+t('downgrade guard: an older --to refuses BEFORE the pin moves, in one line naming both versions + the newest published', async () => {
+  const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+  const before = readFileSync(join(dir, 'package.json'), 'utf8');
+  const calls = [];
+  const res = await u.runUpgrade(
+    { to: '1.19.840', registry: true, instance: dir, commitPin: true, restartCmd: 'true', healthUrl: 'http://x/healthz' },
+    { log: () => {}, err: () => {}, run: registryRun(calls, { dir, published: ['1.19.840', '1.19.841', '1.19.842', '1.20.0-rc.1'] }) },
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.downgrade, true);
+  assert.match(res.error, /1\.19\.840/, 'names the target');
+  assert.match(res.error, /1\.19\.841/, 'names what is installed');
+  assert.match(res.error, /newest published: 1\.19\.842\b/, 'names the newest STABLE release — a prerelease is never the answer');
+  assert.match(res.error, /--allow-downgrade/, 'names the way through');
+  assert.ok(!res.error.includes('\n'), 'one line — a refusal that scrolls is a refusal nobody reads');
+  assert.equal(readFileSync(join(dir, 'package.json'), 'utf8'), before, 'the pin never moved');
+  assert.deepEqual(calls.filter((c) => !c.startsWith('npm view')), [], 'nothing ran but the registry read — no install, no restart, no commit');
+});
+
+t('downgrade guard: an unreadable registry still refuses — the newest version just reads unknown', async () => {
+  const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+  const res = await u.runUpgrade({ to: '1.19.840', registry: true, instance: dir },
+    { log: () => {}, err: () => {}, run: registryRun([], { dir, registryDown: true }) });
+  assert.equal(res.downgrade, true, 'the refusal must not depend on the network');
+  assert.match(res.error, /newest published: unknown/);
+});
+
+t('downgrade guard: --force does NOT waive it, and --dry-run reports the refusal a real run would give', async () => {
+  for (const extra of [{ force: true }, { dryRun: true }]) {
+    const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+    const res = await u.runUpgrade({ to: '1.19.840', registry: true, instance: dir, ...extra },
+      { log: () => {}, err: () => {}, run: registryRun([], { dir }) });
+    assert.equal(res.downgrade, true, `${JSON.stringify(extra)} must not get past the guard`);
+  }
+});
+
+t('downgrade guard: the baseline is the NEWER of installed and pinned — a half-applied bump cannot hide the pin', async () => {
+  // pin moved to 841 by a pull-deploy whose install never ran: node_modules still says 838
+  const pinAhead = scratchConsumer({ pinned: '1.19.841', installed: '1.19.838' });
+  const a = await u.runUpgrade({ to: '1.19.840', registry: true, instance: pinAhead },
+    { log: () => {}, err: () => {}, run: registryRun([], { dir: pinAhead }) });
+  assert.equal(a.downgrade, true, '840 is newer than what is installed but OLDER than the pin it would overwrite');
+  assert.match(a.error, /1\.19\.841/);
+  assert.match(a.error, /pinned/, 'says which of the two it measured against');
+  // the reverse: a rollback whose reinstall failed leaves 842 on disk behind an 841 pin
+  const diskAhead = scratchConsumer({ pinned: '1.19.841', installed: '1.19.842' });
+  const b = await u.runUpgrade({ to: '1.19.841', registry: true, instance: diskAhead, force: true },
+    { log: () => {}, err: () => {}, run: registryRun([], { dir: diskAhead }) });
+  assert.equal(b.downgrade, true, 'taking running code backwards needs the flag, even to match the pin');
+  assert.match(b.error, /installed/);
+});
+
+t('downgrade guard: an older prerelease, and an older version carrying build metadata, are both caught', async () => {
+  for (const [installed, to] of [['1.20.0-rc.2', '1.20.0-rc.1'], ['1.19.841', '1.19.840+hotfix']]) {
+    const dir = scratchConsumer({ pinned: installed, installed });
+    const res = await u.runUpgrade({ to, registry: true, instance: dir },
+      { log: () => {}, err: () => {}, run: registryRun([], { dir }) });
+    assert.equal(res.downgrade, true, `${installed} → ${to}`);
+  }
+});
+
+t('downgrade guard: an upgrade, and a --to it cannot parse, are not called downgrades', async () => {
+  for (const to of ['1.19.842', 'not-a-version']) {
+    const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+    const calls = [];
+    const res = await u.runUpgrade({ to, registry: true, instance: dir, dryRun: true },
+      { log: () => {}, err: () => {}, run: registryRun(calls, { dir }) });
+    assert.equal(res.downgrade, undefined, `--to ${to}`);
+    assert.ok(!calls.some((c) => c.startsWith('npm view')), 'the registry is only read to word a refusal');
+  }
+});
+
+t('--allow-downgrade: goes backwards on purpose, and says so in the first line, the last line AND the ledger', async () => {
+  const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+  const out = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.19.840', registry: true, instance: dir, allowDowngrade: true, skipPinVerify: true, note: 'owner asked' },
+    {
+      log: (l) => out.push(l), err: (l) => out.push(l), run: registryRun([], { dir }),
+      materialize: () => ({}), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    },
+  );
+  assert.equal(res.ok, true, `an explicit downgrade should run: ${res.error}`);
+  assert.equal(u.readInstalledCoreVersion(dir), '1.19.840');
+  assert.match(out[0], /DOWNGRADE/, 'the first line says which way this is going');
+  assert.match(out[out.length - 1], /downgrade complete/);
+  assert.ok(!out.some((l) => /upgrade (complete|finished)/.test(l)), 'no line calls it an upgrade');
+  // the ledger outlives the console: an auditor must not read this row as a normal bump
+  assert.equal(queries[0].params[3], 'downgrade (--allow-downgrade): owner asked');
+});
+
+t('--allow-downgrade: a downgrade that ends with warnings is still called a downgrade', async () => {
+  const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+  const out = [];
+  const res = await u.runUpgrade(
+    { to: '1.19.840', registry: true, instance: dir, allowDowngrade: true, skipPinVerify: true },
+    {
+      log: (l) => out.push(l), err: (l) => out.push(l),
+      run: fakeRun([], { dir, installTo: '1.19.839' }), // the install lands something other than the target
+      materialize: () => ({}), regenerateApiArtifacts: () => ({ ok: true, ran: [] }), databaseUrl: '', pgDatabase: '',
+    },
+  );
+  assert.equal(res.ok, false);
+  assert.match(out[out.length - 1], /downgrade finished with warnings/);
+});
+
+// Same scenario as "rollback on migrate failure" in section 9, on the versions this guard
+// cares about: a rollback routed through runUpgrade would be refused and stay on 842.
+t('auto-rollback still goes backwards with no flag — it restores its own pin and never meets the guard', async () => {
+  const dir = scratchConsumer({ pinned: '1.19.841', installed: '1.19.841' });
+  const calls = [];
+  const res = await u.runUpgrade({ to: '1.19.842', registry: true, instance: dir, healthCheck: false },
+    { log: () => {}, err: () => {}, run: pinAwareRun(calls, { dir, failMigrate: true }), materialize: () => ({}), databaseUrl: '', pgDatabase: '' });
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readInstalledCoreVersion(dir), '1.19.841', 'back on the previous core, 842 → 841, unprompted');
+  assert.ok(!calls.some((c) => c.startsWith('npm view')), 'it never asked the registry, because it never met the guard');
+});
+
+t('parseArgs: --allow-downgrade is read, and is OFF unless asked for', () => {
+  assert.equal(u.parseArgs(['--to', '1.0.0']).allowDowngrade, false);
+  assert.equal(u.parseArgs(['--to', '1.0.0', '--allow-downgrade']).allowDowngrade, true);
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);