@bongos/core 1.19.1039 → 1.19.1040

package/modules/npm-release/public/work.js

@@ -0,0 +1,261 @@
+// modules/npm-release/public/work.js — the deploy page's "where is the work?" and version
+// history sections (task 1002622). Loaded by /deploy only when the npm-release module is on
+// (hall-ui/public/deploy.js), and rendered into #nr-work / #nr-versions.
+//
+// WHY IT LEADS THE PAGE. The owner, 2026-09-26: "I did so many tasks and changes yesterday
+// and it's not showing anything that's been done." The page answered with two version
+// numbers and a button. So the work comes first, by name, with no click needed — each task
+// in the stage it has actually reached — and the version numbers come after it, as the list
+// of what each version carried.
+//
+// THE PAGE KNOWS NOTHING (deploy.js's rule, kept here). Every stage, version and date is the
+// server's reading; nothing is compared or inferred in the browser, and a reading the server
+// could not take is shown as that, never as an empty list.
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const client = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const { escapeHtml } = window.OTB;
+  const $ = (id) => document.getElementById(id);
+
+  // Rows shown per stage before "Show all" — the released pile is most of a fortnight's
+  // work and would push every other stage off the screen.
+  const ROWS_SHOWN = 8;
+  // Tasks shown per version in the history: a busy release carries seventeen.
+  const ENTRIES_SHOWN = 3;
+  // Versions on first paint, and per "Show older versions": 20–30 publish a day, so the
+  // first screen is today's and the rest is one press away.
+  const VERSIONS_FIRST = 6;
+  const VERSIONS_MORE = 10;
+  // Stage keys and `v:<version>` keys the reader has opened with "Show all".
+  const expanded = new Set();
+
+  // The stages in the order work travels, each with the sentence that says what it means.
+  // `live` is the version this hall runs; it is null for a package this hall does not run.
+  // `fig` is the short form the count strip uses: its cells truncate past ~12 capitals.
+  function stageList(live) {
+    return [
+      { key: 'not_merged', fig: 'Not merged', name: 'Done, not merged', note: 'Marked done in the ledger; the code is not on main yet. A task that sits here for hours is a stranded ship.' },
+      { key: 'unversioned', fig: 'Unversioned', name: 'Merged, waiting for a version', note: 'On main, and not yet inside a published version.' },
+      live
+        ? { key: 'not_live', fig: 'Not running', name: 'Published, not running here', note: `Inside a published version newer than ${live}, the one this hall runs.` }
+        : null,
+      live
+        ? { key: 'live_unreleased', fig: 'Unreleased', name: 'Running here, not released', note: 'Other projects are not offered these yet.' }
+        : { key: 'live_unreleased', fig: 'Unreleased', name: 'Published, not released', note: 'Other projects are not offered these yet.' },
+      { key: 'released', fig: 'Released', name: 'Released', note: live ? 'Running here and offered to other projects.' : 'Offered to other projects.' },
+      { key: 'no_version', fig: 'No version', name: 'Shipped, in no version', note: 'No published version names these: ledger-only ships such as scope edits and checks, or a merge whose note did not name its task.' },
+    ].filter(Boolean);
+  }
+
+  function when(iso) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t)) return '';
+    const d = new Date(t);
+    const mins = Math.round((Date.now() - t) / 60000);
+    let label;
+    if (mins < 1) label = 'just now';
+    else if (mins < 60) label = `${mins}m ago`;
+    else if (mins < 48 * 60) label = `${Math.round(mins / 60)}h ago`;
+    else label = d.toLocaleDateString(undefined, { day: 'numeric', month: 'short' });
+    return `<span class="ov-row__when" title="${escapeHtml(d.toLocaleString())}">${escapeHtml(label)}</span>`;
+  }
+
+  // The title IS the link, the hall's own row idiom (oversight.css `a.ov-row__title`),
+  // which is what buys it the 24px floor and the row's ink rather than link colour.
+  function taskTitle(id, title) {
+    return `<a class="ov-row__title" href="/task/${encodeURIComponent(id)}">${escapeHtml(title || `Task ${id}`)}</a>`;
+  }
+
+  function taskRow(t, { offeredInNote = false } = {}) {
+    const facts = [];
+    if (t.builder) facts.push(`<span class="ov-fact">${escapeHtml(t.builder)}</span>`);
+    if (t.version) facts.push(`<span class="ov-fact">in <b>${escapeHtml(t.version)}</b></span>`);
+    if (t.status && t.status !== 'shipped') facts.push(`<span class="ov-fact">${escapeHtml(t.status)}</span>`);
+    if (t.offered && !offeredInNote) facts.push('<span class="ov-fact"><b>already offered to other projects</b></span>');
+    return `<li class="ov-row ov-row--dense" data-task="${escapeHtml(t.id)}">
+        <div class="ov-row__main">
+          ${taskTitle(t.id, t.title)}
+          <div class="ov-row__facts">${facts.join('')}</div>
+        </div>
+        <div class="ov-row__right">${when(t.at)}</div>
+      </li>`;
+  }
+
+  function moreButton(key, total, shown) {
+    return total > shown ? `<button type="button" class="ov-toggle" data-expand="${escapeHtml(key)}">Show all ${total}</button>` : '';
+  }
+
+  function stageHtml(stage, rows) {
+    if (!rows.length) return '';
+    const shown = expanded.has(stage.key) ? rows : rows.slice(0, ROWS_SHOWN);
+    // Published before this hall ran it is the order Release exists to prevent. When it
+    // is true of the whole group (every merge is released today) it is said once, in the
+    // group's note, rather than on every row.
+    const allOffered = rows.every((t) => t.offered);
+    const note = allOffered ? `${stage.note} Already offered to other projects.` : stage.note;
+    // The sentence sits UNDER the head, not in `.ov-group__note`: that slot is sized for a
+    // few words, and a sentence there squeezes the stage name to one word a line on a phone.
+    return `<div class="ov-group" data-stage="${stage.key}">
+        <div class="ov-group__head">
+          <span class="ov-group__name">${escapeHtml(stage.name)}</span>
+          <span class="ov-group__n">${rows.length}</span>
+        </div>
+        <p class="ov-row__sub">${escapeHtml(note)}</p>
+        <ul class="ov-rows">${shown.map((t) => taskRow(t, { offeredInNote: allOffered })).join('')}</ul>
+        ${moreButton(stage.key, rows.length, shown.length)}
+      </div>`;
+  }
+
+  function figsHtml(stages, d) {
+    return `<div class="ov-figs">${stages.map((s) => `
+        <div class="ov-fig">
+          <span class="ov-fig__l" title="${escapeHtml(s.name)}">${escapeHtml(s.fig)}</span>
+          <span class="ov-fig__v">${(d.stages[s.key] || []).length}</span>
+        </div>`).join('')}</div>`;
+  }
+
+  // What the page could NOT read, said plainly above what it could.
+  function problemsHtml(d) {
+    const out = [];
+    if (d.registry && !d.registry.ok) out.push(`The npm registry could not be read (${d.registry.error}), so which version is newest and which is released is unknown.`);
+    if (d.notes && d.notes.error) {
+      out.push(d.notes.covers_to
+        ? `The release notes of the newest version could not be read (${d.notes.error}). Versions after ${d.notes.covers_to} show no work below, and work inside them may be listed as waiting.`
+        : `No release notes could be read (${d.notes.error}), so no task can be placed in a version.`);
+    }
+    if (!out.length) return '';
+    return `<div class="ov-note ov-note--warn">${out.map((p, i) => `<p>${i === 0 ? '<strong>Partial reading.</strong> ' : ''}${escapeHtml(p)}</p>`).join('')}</div>`;
+  }
+
+  function ledeHtml(d) {
+    const parts = [`Every task finished in the last ${d.window_days} days, in the stage it has actually reached.`];
+    if (d.live) parts.push(`This hall runs ${d.live}.`);
+    if (d.newest) parts.push(`The newest published version is ${d.newest}.`);
+    if (d.released) parts.push(`Other projects are offered ${d.released}.`);
+    return `<p class="scroll__lede">${escapeHtml(parts.join(' '))}</p>`;
+  }
+
+  function versionHtml(v) {
+    const marks = [];
+    if (v.live) marks.push('running here');
+    if (v.released) marks.push('released');
+    const date = v.published_at ? new Date(v.published_at).toLocaleString(undefined, { day: 'numeric', month: 'short', hour: '2-digit', minute: '2-digit' }) : '';
+    const note = [date, ...marks].filter(Boolean).join(' · ');
+    let body;
+    if (v.entries === null) body = '<p class="ov-row__sub">This version\'s notes could not be read.</p>';
+    else if (!v.entries.length) body = '<p class="ov-row__sub">No task work — housekeeping merges only.</p>';
+    else {
+      const key = `v:${v.version}`;
+      const shown = expanded.has(key) ? v.entries : v.entries.slice(0, ENTRIES_SHOWN);
+      body = `<ul class="ov-rows">${shown.map((e) => `<li class="ov-row ov-row--dense">
+          <div class="ov-row__main">
+            ${e.id ? taskTitle(e.id, e.title) : `<span class="ov-row__title">${escapeHtml(e.text)}</span>`}
+            ${e.id ? `<p class="ov-row__sub">${escapeHtml(e.text)}</p>` : ''}
+          </div>
+        </li>`).join('')}</ul>${moreButton(key, v.entries.length, shown.length)}`;
+    }
+    return `<div class="ov-group" data-version="${escapeHtml(v.version)}">
+        <div class="ov-group__head">
+          <span class="ov-group__name ov-key">${escapeHtml(v.version)}</span>
+          <span class="ov-group__n">${v.entries ? v.entries.length : '?'}</span>
+          <span class="ov-group__note">${escapeHtml(note)}</span>
+        </div>
+        ${body}
+      </div>`;
+  }
+
+  let data = null;
+  let history = [];
+  let hasMore = false;
+  let loadingMore = false;
+
+  function paint() {
+    const work = $('nr-work');
+    const vers = $('nr-versions');
+    if (!work || !data) return;
+    const stages = stageList(data.live);
+    const groups = stages.map((s) => stageHtml(s, data.stages[s.key] || [])).join('');
+    work.innerHTML = `
+      <h2 class="scroll__h" id="nr-work-h">Where the work is</h2>
+      ${ledeHtml(data)}
+      ${problemsHtml(data)}
+      ${figsHtml(stages, data)}
+      ${groups || '<p class="ov-row__sub">Nothing was finished in this window.</p>'}
+      <p class="ov-foot">read ${escapeHtml(new Date(data.checked_at).toLocaleTimeString())} · ${escapeHtml(data.package)} · release notes from ${escapeHtml(data.notes.source ? `${data.notes.source.from === 'package' ? 'the published' : 'this hall\'s'} ${data.notes.source.version} package` : 'nowhere')}</p>`;
+    work.hidden = false;
+    if (vers) {
+      vers.innerHTML = `
+        <h2 class="scroll__h" id="nr-versions-h">Versions</h2>
+        <p class="scroll__lede">What each version carried, newest first — the task each merge named, in the words its ship wrote.</p>
+        ${history.map(versionHtml).join('')}
+        ${hasMore ? `<button type="button" class="ov-toggle" id="nr-older"${loadingMore ? ' disabled' : ''}>${loadingMore ? 'Loading…' : 'Show older versions'}</button>` : ''}`;
+      vers.hidden = false;
+    }
+  }
+
+  async function fetchWork(query) {
+    const res = await client.request('GET', `${API}/npm-release/work${query ? `?${query}` : ''}`);
+    if (res.status === 401 || res.status === 403 || res.status === 404) return null;   // not this reader's, or module off
+    if (!res.ok) {
+      const err = (res.data && res.data.error) || {};
+      throw new Error(err.message || `work → ${res.status}`);
+    }
+    return res.data;
+  }
+
+  // The module's own sheet, beside this script — fetched only where the module is on.
+  function loadSheet() {
+    if (document.getElementById('nr-work-css') || !document.createElement) return;
+    const l = document.createElement('link');
+    l.id = 'nr-work-css';
+    l.rel = 'stylesheet';
+    l.href = '/modules/npm-release/public/work.css';
+    document.head.appendChild(l);
+  }
+
+  async function load() {
+    const work = $('nr-work');
+    if (!work) return;
+    loadSheet();
+    try {
+      const d = await fetchWork(`limit=${VERSIONS_FIRST}`);
+      if (!d) return;
+      data = d;
+      history = d.history.versions;
+      hasMore = d.history.more;
+      paint();
+    } catch (e) {
+      work.innerHTML = `<h2 class="scroll__h">Where the work is</h2>
+        <div class="ov-note ov-note--warn"><p><strong>Could not read where the work is.</strong> ${escapeHtml(e.message || String(e))}</p></div>`;
+      work.hidden = false;
+    }
+  }
+
+  async function loadOlder() {
+    if (loadingMore || !history.length) return;
+    loadingMore = true;
+    paint();
+    try {
+      const last = history[history.length - 1].version;
+      const d = await fetchWork(`before=${encodeURIComponent(last)}&limit=${VERSIONS_MORE}`);
+      if (d) { history = history.concat(d.history.versions); hasMore = d.history.more; }
+    } catch (e) {
+      if (window.OTB.toast) window.OTB.toast(`Could not load older versions: ${e.message || e}`);
+    } finally {
+      loadingMore = false;
+      paint();
+    }
+  }
+
+  document.addEventListener('click', (ev) => {
+    const t = ev.target;
+    if (!(t instanceof Element)) return;
+    const ex = t.closest('[data-expand]');
+    if (ex) { expanded.add(ex.getAttribute('data-expand')); paint(); return; }
+    if (t.closest('#nr-older')) loadOlder();
+  });
+
+  load();
+})();

package/modules/npm-release/registry.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// modules/npm-release/registry.js — what the npm registry says about the package: which
+// versions exist, when each was published, which one carries the `latest` label, and the
+// release notes the newest version was packed with (task 1002622).
+//
+// WHY THE NEWEST PACKAGE'S NOTES. package-core writes release-notes.json from the WHOLE
+// history at pack time (scripts/gds/release-notes.js, task 1004218), so the newest version
+// alone lists every version before it. One file answers the whole page. The copy the
+// running core carries stops at its own version, which is exactly the range the deploy
+// page is asked about least: the work that is published but not running yet.
+//
+// NEVER A CHILD PROCESS, NEVER A SYNC CALL. This runs inside the web process, so the
+// upgrade runner's `npm pack` + `tar -xzOf` (provision-core-upgrade.js readPackagedNotes)
+// is the wrong tool here: spawnSync would stall every other request for the length of a
+// 24 MB download. The tarball is streamed through gunzip and a small tar reader that keeps
+// only the one file it wants, and the download is dropped the moment that file is read.
+//
+// FAIL-SOFT, AND SAYS SO. Every read resolves `{ ok: false, error }` rather than throwing,
+// and the page renders the error. "Could not read" and "nothing there" are different
+// answers and neither is ever allowed to look like the other.
+
+const https = require('node:https');
+const zlib = require('node:zlib');
+
+const REGISTRY_ORIGIN = 'https://registry.npmjs.org';
+const RELEASE_NOTES_PATH = 'package/release-notes.json';
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+
+// The full packument, not the abbreviated one core-update.js asks for: only the full
+// document carries `time`, and a version history without dates is not reviewable. It is
+// ~2 MB for ~1,000 releases (measured 2026-09-26), so it is read at most every few minutes.
+const PACKUMENT_TTL_MS = 5 * 60 * 1000;
+const PACKUMENT_TIMEOUT_MS = 15000;
+// One tarball download. ~24 MB for @bongos/core 1.19.1039, well under a second from a
+// droplet; the bound is for a registry that stops answering mid-stream.
+const TARBALL_TIMEOUT_MS = 90000;
+// release-notes.json is bounded at 1 MB by its generator; anything past 4 MB is not it.
+const NOTES_MAX_BYTES = 4 * 1024 * 1024;
+// A failed read is retried after this, not on every page load.
+const RETRY_AFTER_MS = 2 * 60 * 1000;
+
+function compareVersions(a, b) {
+  const x = String(a).split('.').map(Number);
+  const y = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+/** GET a URL, resolving `{ res }` or `{ error }` — never a throw. */
+function open(get, url, { accept, timeoutMs }) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    let req;
+    try {
+      req = get(url, { headers: accept ? { accept } : {}, timeout: timeoutMs }, (res) => {
+        if (res.statusCode !== 200) { res.resume(); return done({ error: `the registry answered ${res.statusCode}` }); }
+        done({ res, req });
+      });
+    } catch (e) { return done({ error: e.message }); }
+    if (req && req.on) {
+      req.on('error', (e) => done({ error: e.message }));
+      req.on('timeout', () => { try { req.destroy(); } catch { /* gone */ } done({ error: 'the registry did not answer in time' }); });
+    }
+  });
+}
+
+/**
+ * The facts the page needs out of one packument. PURE.
+ * Returns `{ versions, published, latest, newest, tarballs }` — stable x.y.z versions only,
+ * because a prerelease is never a release and never a candidate.
+ */
+function summarizePackument(doc) {
+  const all = Object.keys((doc && doc.versions) || {}).filter((v) => VERSION_RE.test(v)).sort(compareVersions);
+  const time = (doc && doc.time) || {};
+  const published = {};
+  const tarballs = {};
+  for (const v of all) {
+    if (typeof time[v] === 'string') published[v] = time[v];
+    const dist = doc.versions[v] && doc.versions[v].dist;
+    if (dist && typeof dist.tarball === 'string') tarballs[v] = dist.tarball;
+  }
+  const tag = doc && doc['dist-tags'] && doc['dist-tags'].latest;
+  return {
+    versions: all,
+    published,
+    latest: VERSION_RE.test(String(tag || '')) ? tag : null,
+    newest: all.length ? all[all.length - 1] : null,
+    tarballs,
+  };
+}
+
+function fetchPackument({ pkg, get, origin }) {
+  return open(get, `${origin}/${pkg.replace('/', '%2f')}`, { accept: 'application/json', timeoutMs: PACKUMENT_TIMEOUT_MS })
+    .then(({ res, error }) => {
+      if (error) return { ok: false, error };
+      return new Promise((resolve) => {
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('error', (e) => resolve({ ok: false, error: e.message }));
+        res.on('end', () => {
+          try {
+            const facts = summarizePackument(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            resolve(facts.newest ? { ok: true, ...facts } : { ok: false, error: 'the registry lists no versions of this package' });
+          } catch (e) { resolve({ ok: false, error: `the registry's answer could not be read (${e.message})` }); }
+        });
+      });
+    });
+}
+
+/**
+ * One file out of a gzipped tar stream, as a Buffer — or null when the archive ends
+ * without it. Understands the three header kinds npm's tarballs use: plain ustar entries,
+ * pax extended headers ('x', whose `path` renames the next entry) and GNU long names ('L').
+ * Skipped entries are counted past, never buffered, so a 24 MB tarball costs one file.
+ */
+function extractTarEntry(stream, wanted, { maxBytes = NOTES_MAX_BYTES } = {}) {
+  return new Promise((resolve, reject) => {
+    let buf = Buffer.alloc(0);
+    let skip = 0;          // bytes of the current entry (plus padding) still to pass over
+    let take = null;       // { size, pad, parts, got } while reading the wanted entry
+    let meta = null;       // { size, pad, kind, parts, got } while reading an 'x' / 'L' header
+    let nextName = null;   // a name a pax/GNU header gave the entry that follows it
+    let finished = false;
+    const finish = (v, err) => {
+      if (finished) return;
+      finished = true;
+      try { stream.destroy(); } catch { /* already closed */ }
+      if (err) reject(err); else resolve(v);
+    };
+    const cstr = (b, from, len) => {
+      const s = b.subarray(from, from + len);
+      const z = s.indexOf(0);
+      return (z < 0 ? s : s.subarray(0, z)).toString('utf8');
+    };
+    const padOf = (size) => (512 - (size % 512)) % 512;
+    const onBytes = () => {
+      while (!finished) {
+        if (skip > 0) {
+          const n = Math.min(skip, buf.length);
+          buf = buf.subarray(n);
+          skip -= n;
+          if (skip > 0) return;
+          continue;
+        }
+        const body = take || meta;
+        if (body) {
+          const need = body.size - body.got;
+          const n = Math.min(need, buf.length);
+          body.parts.push(buf.subarray(0, n));
+          body.got += n;
+          buf = buf.subarray(n);
+          if (body.got < body.size) return;
+          const data = Buffer.concat(body.parts);
+          if (take) return finish(data);
+          if (meta.kind === 'L') nextName = cstr(data, 0, data.length);
+          else {
+            const m = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(data.toString('utf8'));
+            if (m) nextName = m[1];
+          }
+          skip = meta.pad;
+          meta = null;
+          continue;
+        }
+        if (buf.length < 512) return;
+        const h = buf.subarray(0, 512);
+        buf = buf.subarray(512);
+        if (h.every((x) => x === 0)) return finish(null);
+        const size = parseInt(cstr(h, 124, 12).trim() || '0', 8);
+        if (!Number.isFinite(size) || size < 0) return finish(null, new Error('the package archive is damaged'));
+        const type = String.fromCharCode(h[156] || 48);
+        if (type === 'x' || type === 'L') {
+          if (size > maxBytes) return finish(null, new Error('the package archive is damaged'));
+          meta = { size, pad: padOf(size), kind: type, parts: [], got: 0 };
+          continue;
+        }
+        const prefix = cstr(h, 345, 155);
+        const name = nextName || (prefix ? `${prefix}/${cstr(h, 0, 100)}` : cstr(h, 0, 100));
+        nextName = null;
+        if (name === wanted && (type === '0' || type === '\0')) {
+          if (size > maxBytes) return finish(null, new Error(`${wanted} is larger than any release notes file`));
+          take = { size, pad: 0, parts: [], got: 0 };
+          if (size === 0) return finish(Buffer.alloc(0));
+          continue;
+        }
+        skip = size + padOf(size);
+      }
+    };
+    stream.on('data', (c) => { if (finished) return; buf = buf.length ? Buffer.concat([buf, c]) : c; onBytes(); });
+    stream.on('end', () => finish(null));
+    stream.on('error', (e) => finish(null, e));
+  });
+}
+
+function fetchPackagedNotes({ version, tarball, get, origin }) {
+  // The URL came off the registry, but it is still only followed on the registry's own
+  // origin: a packument pointing somewhere else is not something this page will fetch.
+  if (typeof tarball !== 'string' || !tarball.startsWith(`${origin}/`)) {
+    return Promise.resolve({ ok: false, error: `the registry gave no download for ${version}` });
+  }
+  return open(get, tarball, { timeoutMs: TARBALL_TIMEOUT_MS }).then(async ({ res, req, error }) => {
+    if (error) return { ok: false, error: `could not download ${version} (${error})` };
+    const gunzip = zlib.createGunzip();
+    res.on('error', (e) => gunzip.destroy(e));
+    res.pipe(gunzip);
+    try {
+      const data = await extractTarEntry(gunzip, RELEASE_NOTES_PATH);
+      if (!data) return { ok: false, missing: true, error: `${version} was published without release notes` };
+      const notes = JSON.parse(data.toString('utf8'));
+      if (!notes || typeof notes !== 'object' || Array.isArray(notes)) return { ok: false, error: `the release notes in ${version} are not a list of versions` };
+      return { ok: true, notes };
+    } catch (e) {
+      return { ok: false, error: `could not read the release notes in ${version} (${e.message})` };
+    } finally {
+      try { res.destroy(); } catch { /* gone */ }
+      try { if (req && req.destroy) req.destroy(); } catch { /* gone */ }
+    }
+  });
+}
+
+// Process-local, like core-update.js's: derived facts with a short life, and a restart
+// re-deriving them costs one request. Notes are immutable per version, so only the newest
+// one is ever worth keeping.
+function makeStore() {
+  return { packument: { at: 0, value: null, inflight: null }, notes: { version: null, at: 0, value: null, inflight: null } };
+}
+const defaultStore = makeStore();
+
+async function cached(slot, fresh, load, t) {
+  if (slot.value && fresh(slot)) return slot.value;
+  if (slot.inflight) return slot.inflight;
+  slot.inflight = (async () => {
+    try {
+      const v = await load();
+      slot.value = v;
+      slot.at = t;
+      return v;
+    } finally { slot.inflight = null; }
+  })();
+  return slot.inflight;
+}
+
+/**
+ * Everything the registry can tell the deploy page about `pkg`, in one call.
+ *
+ * Returns `{ registry, notes }`:
+ *   registry — `{ ok, versions, published, latest, newest }` or `{ ok:false, error }`
+ *   notes    — the newest version's release notes, `{ ok, version, notes }` or
+ *              `{ ok:false, version, error }`; `{ ok:false, skipped }` when the caller
+ *              already holds notes that reach the newest version (`haveNotesFor`).
+ *
+ * `get` swaps the HTTPS transport and `store`/`now` the cache, so tests drive the real
+ * parsing and failure paths rather than a stub standing in front of them.
+ */
+async function readRegistry({ pkg, haveNotesFor = () => false, get = https.get, origin = REGISTRY_ORIGIN, now = Date.now, store = defaultStore } = {}) {
+  const t = now();
+  const pk = store.packument;
+  const registry = await cached(pk, (s) => t - s.at < (s.value.ok ? PACKUMENT_TTL_MS : RETRY_AFTER_MS),
+    () => fetchPackument({ pkg, get, origin }), t);
+  if (!registry.ok) return { registry, notes: { ok: false, error: 'the registry could not be read' } };
+  const version = registry.newest;
+  if (haveNotesFor(version)) return { registry, notes: { ok: false, skipped: true, version } };
+  const ns = store.notes;
+  if (ns.version !== version) { ns.version = version; ns.value = null; ns.at = 0; }
+  const notes = await cached(ns, (s) => s.value.ok || t - s.at < RETRY_AFTER_MS,
+    () => fetchPackagedNotes({ version, tarball: registry.tarballs[version], get, origin }), t);
+  return { registry, notes: { ...notes, version } };
+}
+
+module.exports = { readRegistry, compareVersions };

package/modules/npm-release/routes/work.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// modules/npm-release/routes/work.js — GET /npm-release/work, the deploy page's
+// "where is my work?" reading (task 1002622). See ../work.js for what it answers.
+//
+// GATED LIKE THE PAGE IT FEEDS. /deploy is served only to holders of `core.pin.move`
+// (serve-internal.js DEPLOY_PAGE_RE), and this answer carries the same disclosure the
+// door's own preview does — the exact core this hall runs and how far behind the
+// newest it is (ADR 0043's reason for gating that preview). A read no wider than the
+// page is also what keeps the page from ever offering more than its API will answer.
+// An atom, not requireRank: tests/government_require_permission.mjs fails the build on
+// a new requireRank in a modules/*/routes gate (BV1.R105 / ADR 0151).
+//
+// READ-ONLY. Nothing here writes, queues or moves anything; the Release button is a
+// separate route with its own gate.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { readWork } = require('../work');
+
+const log = api.logger('npm-release');
+
+module.exports = function buildNpmReleaseWorkRouter({ read = readWork } = {}) {
+  const router = express.Router();
+
+  // Query: days (ledger window, default 14, max 60), before + limit (history paging).
+  // Read by hand rather than through validateOrRespond: every field is optional and
+  // clamped, so there is nothing to refuse.
+  router.get(
+    '/npm-release/work',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    async (req, res) => {
+      try {
+        const q = req.query || {};
+        const before = typeof q.before === 'string' ? q.before : undefined;
+        res.json(await read({ pool: api.pool, days: q.days, before, limit: q.limit }));
+      } catch (e) {
+        log.error(`npm-release work read failed: ${e && e.message}`);
+        res.status(500).json({ error: { code: 'work_read_failed', message: 'Could not read where the work is right now.' } });
+      }
+    },
+  );
+
+  return router;
+};