@celilo/e2e 0.19.0 → 0.19.2

package/registry-server/src/sweep.test.ts

@@ -0,0 +1,326 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { RegistryStorage } from './storage';
+import { DEFAULT_KEEP_BUILD_REVISIONS, parseRevision, planModuleSweep, sweep } from './sweep';
+
+let dataDir: string;
+let storage: RegistryStorage;
+
+beforeEach(() => {
+  dataDir = mkdtempSync(join(tmpdir(), 'celilo-registry-sweep-'));
+  storage = new RegistryStorage(dataDir);
+});
+
+afterEach(() => {
+  rmSync(dataDir, { recursive: true, force: true });
+});
+
+/** Publish a version through the same two calls the real publish path uses. */
+function publish(name: string, vers: string, sizeBytes = 32): void {
+  storage.storePackage(name, vers, Buffer.alloc(sizeBytes, 7));
+  storage.appendIndex({ name, vers, deps: [], cksum: `sha256:${vers}`, yanked: false });
+}
+
+/**
+ * THE invariant. A sweep that trims payloads without trimming index lines
+ * leaves the index advertising a version whose file is gone — search lists it
+ * and the download 404s. The reverse leaves unreachable bytes on the disk the
+ * sweep exists to reclaim. Both directions have to hold.
+ */
+function expectIndexAndPayloadsAgree(name: string): void {
+  const indexed = storage.readIndex(name).map((e) => e.vers);
+  const stored = storage.storedVersions(name).sort();
+  for (const vers of indexed) {
+    expect(storage.readPackage(name, vers)).not.toBeNull();
+  }
+  expect(stored).toEqual([...indexed].sort());
+}
+
+describe('parseRevision', () => {
+  test('splits a release from its build revision', () => {
+    expect(parseRevision('1.0.3+7')).toEqual({ release: '1.0.3', revision: 7 });
+  });
+
+  test('keeps a Debian epoch with the release', () => {
+    expect(parseRevision('2:1.0.0+1')).toEqual({ release: '2:1.0.0', revision: 1 });
+  });
+
+  test('returns null for a version with no build revision', () => {
+    expect(parseRevision('1.0.0')).toBeNull();
+  });
+});
+
+describe('planModuleSweep', () => {
+  const entry = (vers: string, yanked = false) => ({
+    name: 'm',
+    vers,
+    deps: [],
+    cksum: 'sha256:x',
+    yanked,
+  });
+
+  /**
+   * Plan against a store where every indexed version HAS its payload — the
+   * ordinary case. Passing an empty stored set instead would trip the
+   * unreadable guard, which is a different scenario with its own tests below.
+   */
+  const planWithPayloads = (entries: ReturnType<typeof entry>[], keepBuildRevisions: number) =>
+    planModuleSweep(
+      'm',
+      entries,
+      entries.map((e) => e.vers),
+      { keepBuildRevisions },
+    );
+
+  test('keeps the newest build revision of every release', () => {
+    const entries = [
+      entry('1.0.0+1'),
+      entry('1.0.0+2'),
+      entry('1.0.2+8'),
+      entry('1.0.2+9'),
+      entry('1.0.3+5'),
+      entry('1.0.3+6'),
+      entry('1.0.3+7'),
+    ];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.0+2', '1.0.2+9', '1.0.3+7']);
+    expect(plan.remove).toEqual(['1.0.0+1', '1.0.2+8', '1.0.3+5', '1.0.3+6']);
+  });
+
+  test('never removes the only revision of a release', () => {
+    const entries = [entry('0.9.0+2'), entry('1.0.0+1')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.remove).toEqual([]);
+  });
+
+  test('a module can never be swept out of existence', () => {
+    const entries = [entry('1.0.0+1')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep).toHaveLength(1);
+  });
+
+  test('keeps more revisions per release when asked', () => {
+    const entries = [entry('1.0.3+5'), entry('1.0.3+6'), entry('1.0.3+7')];
+    const plan = planWithPayloads(entries, 2);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.3+6', '1.0.3+7']);
+  });
+
+  test('keepBuildRevisions below 1 is clamped — no policy deletes a whole release', () => {
+    // Needs MORE THAN ONE release to be a real check. With a single release
+    // the latest-line retention below masks a missing clamp; with two, an
+    // unclamped 0 wipes out every release except the last.
+    const entries = [entry('1.0.0+1'), entry('1.0.0+2'), entry('1.0.3+5'), entry('1.0.3+6')];
+    const plan = planWithPayloads(entries, 0);
+    expect(plan.keep.map((e) => e.vers)).toEqual(['1.0.0+2', '1.0.3+6']);
+  });
+
+  test('retains what latestVersion resolves to even when the index is out of order', () => {
+    // Last line wins for RegistryClient.latestVersion regardless of ordering,
+    // so a disordered index must not lose the version clients actually fetch.
+    const entries = [entry('1.0.3+7'), entry('1.0.3+6'), entry('1.0.3+5')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+5');
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+7');
+  });
+
+  test('retains the last NON-yanked line, which is what clients resolve to', () => {
+    const entries = [entry('1.0.3+5'), entry('1.0.3+6'), entry('1.0.3+7', true)];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.keep.map((e) => e.vers)).toContain('1.0.3+6');
+  });
+
+  test('keeps a version it cannot parse rather than deleting it', () => {
+    const entries = [entry('nonsense'), entry('1.0.0+1'), entry('1.0.0+2')];
+    const plan = planWithPayloads(entries, 1);
+    expect(plan.remove).toEqual(['1.0.0+1']);
+  });
+
+  test('reports a payload with no index line as an orphan', () => {
+    const plan = planModuleSweep('m', [entry('1.0.0+2')], ['1.0.0+1', '1.0.0+2'], {
+      keepBuildRevisions: 1,
+    });
+    expect(plan.orphans).toEqual(['1.0.0+1']);
+  });
+});
+
+describe('sweep over a fixture store', () => {
+  test('index and payloads agree afterwards, and every release survives', () => {
+    for (const rev of [1, 2, 3, 4, 5]) publish('celilo-registry', `1.0.3+${rev}`);
+    for (const rev of [1, 2]) publish('celilo-registry', `1.0.2+${rev}`);
+    publish('forgejo', '2.1.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: DEFAULT_KEEP_BUILD_REVISIONS });
+
+    expect(report.removedCount).toBe(5);
+    expectIndexAndPayloadsAgree('celilo-registry');
+    expectIndexAndPayloadsAgree('forgejo');
+    // Original index order is preserved: the fixture published 1.0.3 before
+    // 1.0.2, and the sweep filters lines rather than re-sorting them.
+    expect(storage.readIndex('celilo-registry').map((e) => e.vers)).toEqual(['1.0.3+5', '1.0.2+2']);
+    expect(storage.readIndex('forgejo').map((e) => e.vers)).toEqual(['2.1.0+1']);
+  });
+
+  test('reclaims the bytes it says it reclaims', () => {
+    publish('m', '1.0.0+1', 4096);
+    publish('m', '1.0.0+2', 4096);
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+    expect(report.reclaimedBytes).toBe(4096);
+  });
+
+  test('a dry run changes nothing', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    const report = sweep(storage, { keepBuildRevisions: 1 }, true);
+
+    expect(report.removedCount).toBe(2);
+    expect(storage.readIndex('m')).toHaveLength(3);
+    expect(storage.storedVersions('m').sort()).toEqual(['1.0.0+1', '1.0.0+2', '1.0.0+3']);
+  });
+
+  test('is idempotent — a second sweep finds nothing to do', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    sweep(storage, { keepBuildRevisions: 1 });
+    const second = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(second.removedCount).toBe(0);
+    expect(second.orphanCount).toBe(0);
+    expect(second.reclaimedBytes).toBe(0);
+    expectIndexAndPayloadsAgree('m');
+  });
+
+  test('a sweep interrupted after the index rewrite self-heals on the next run', () => {
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    // The crash window: index trimmed, payloads not yet unlinked. The version
+    // is unlisted but still on disk — wasted bytes, not a broken registry.
+    storage.updateIndex('m', storage.readIndex('m').slice(-1));
+    expect(storage.storedVersions('m')).toHaveLength(3);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.orphanCount).toBe(2);
+    expectIndexAndPayloadsAgree('m');
+  });
+
+  test('a version left unlisted stays downloadable until its payload goes', () => {
+    // Why index-first is the safe order: the download route reads the payload
+    // directly and never consults the index, so the window an interrupted
+    // sweep opens serves stale-but-valid bytes rather than 404ing.
+    publish('m', '1.0.0+1');
+    storage.updateIndex('m', []);
+    expect(storage.readPackage('m', '1.0.0+1')).not.toBeNull();
+  });
+
+  test('reclaims a half-written publish, which is what makes the version publishable again', () => {
+    // Both states below exist on the production registry, created 2026-08-22 by
+    // real failures: an ENOSPC that killed a run after storePackage, and an
+    // EACCES on appendIndex. handlePublish has no rollback between the two.
+    //
+    // The consequence is worse than wasted bytes: `packageExists` reads the
+    // FILESYSTEM, so the orphan makes its own version permanently
+    // unpublishable — "versions are immutable". Removing the orphan is the
+    // repair, and nothing else in the product performs it.
+    storage.storePackage('celilo-mgmt', '0.6.2+2', Buffer.alloc(2048, 1));
+    publish('celilo-mgmt', '0.6.1+1');
+    expect(storage.packageExists('celilo-mgmt', '0.6.2+2')).toBe(true);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.orphanCount).toBe(1);
+    expect(storage.packageExists('celilo-mgmt', '0.6.2+2')).toBe(false);
+    expectIndexAndPayloadsAgree('celilo-mgmt');
+  });
+
+  test('REPORTS an index line with no payload and does not remove it', () => {
+    // The dangerous direction. Removing the line would actually repair the
+    // module — a dangling entry already 404s — but a missing payload is
+    // indistinguishable from an unreadable store, so it is reported only.
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    storage.removePackage('m', '1.0.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.danglingCount).toBe(1);
+    expect(report.modules[0]?.dangling).toEqual(['1.0.0+1']);
+    // Still listed: the sweep reported it rather than acting on it.
+    expect(storage.readIndex('m').map((e) => e.vers)).toContain('1.0.0+1');
+  });
+
+  test('touches nothing when a module has index lines and no payloads at all', () => {
+    // An unmounted volume or a wrong DATA_DIR looks exactly like this. Acting
+    // on it would trim the index of a module whose files are merely
+    // unreachable.
+    for (const rev of [1, 2, 3]) publish('m', `1.0.0+${rev}`);
+    for (const rev of [1, 2, 3]) storage.removePackage('m', `1.0.0+${rev}`);
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.unreadable).toEqual(['m']);
+    expect(report.removedCount).toBe(0);
+    expect(storage.readIndex('m')).toHaveLength(3);
+  });
+
+  test('a dangling entry does not stop the rest of the sweep', () => {
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    publish('m', '1.0.0+3');
+    storage.removePackage('m', '1.0.0+1');
+
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+
+    expect(report.danglingCount).toBe(1);
+    // 1.0.0+2 is superseded and still had its payload, so it is swept normally.
+    expect(report.removedCount).toBe(1);
+    expect(storage.readIndex('m').map((e) => e.vers)).toEqual(['1.0.0+1', '1.0.0+3']);
+  });
+
+  test('never sweeps the last SERVABLE version because a newer line is dangling', () => {
+    // The failure this guards: retention computed over every index line lets a
+    // dangling NEWEST entry satisfy both the per-release rule and the
+    // latest-line rule, so every servable older version reads as superseded.
+    // The module ends up listed, with one index line, and undownloadable.
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    publish('m', '1.0.0+3');
+    storage.removePackage('m', '1.0.0+3'); // the newest line is now dangling
+
+    sweep(storage, { keepBuildRevisions: 1 });
+
+    // Something is still downloadable, which is the whole point.
+    const servable = storage
+      .readIndex('m')
+      .map((e) => e.vers)
+      .filter((v) => storage.packageExists('m', v));
+    expect(servable.length).toBeGreaterThan(0);
+    expect(servable).toContain('1.0.0+2');
+  });
+
+  test('an empty store sweeps cleanly', () => {
+    const report = sweep(storage, { keepBuildRevisions: 1 });
+    expect(report.removedCount).toBe(0);
+    expect(report.modules).toEqual([]);
+  });
+});
+
+describe('updateIndex atomicity', () => {
+  test('leaves no temp file behind', () => {
+    publish('m', '1.0.0+1');
+    storage.updateIndex('m', storage.readIndex('m'));
+    expect(existsSync(`${storage.indexPath('m')}.tmp`)).toBe(false);
+  });
+
+  test('a write that cannot land leaves the original index intact', () => {
+    publish('m', '1.0.0+1');
+    publish('m', '1.0.0+2');
+    const before = storage.readIndex('m');
+    // Block the temp path so the new content cannot be written. A truncating
+    // in-place write ignores the obstruction and replaces the index anyway;
+    // the rename path fails with the original still on disk. This stands in
+    // for the failure that actually matters — ENOSPC on the full disk this
+    // sweep exists to relieve — which needs an fs seam to reproduce directly.
+    mkdirSync(`${storage.indexPath('m')}.tmp`, { recursive: true });
+    expect(() => storage.updateIndex('m', before.slice(0, 1))).toThrow();
+    expect(storage.readIndex('m')).toEqual(before);
+  });
+});

package/registry-server/src/sweep.ts

@@ -0,0 +1,289 @@
+/**
+ * Reclaiming disk from superseded build revisions.
+ *
+ * The registry had no delete path at all: `yank` sets a boolean in the index
+ * and frees nothing, so every revision ever published was retained forever.
+ * A `+N` build revision is auto-assigned on every publish, so the store grew
+ * with every release until the disk filled and the release pipeline stopped.
+ *
+ * ── What the policy keeps, and why it cannot break a fetch ──
+ *
+ * A version is `X.Y.Z+N`: a released semver plus a build revision. The bloat
+ * is the rebuilds, not the releases — a module embedding compiled binaries
+ * republished twenty times carries twenty ~73 MB payloads of one release.
+ *
+ * So the sweep keeps the newest `keepBuildRevisions` of EVERY release and
+ * drops the rest. No release ever disappears, which is what makes the safety
+ * argument checkable rather than a judgement call:
+ *
+ *   - The only version a celilo client can ask for is the one
+ *     `RegistryClient.latestVersion` picks — the last non-yanked line in the
+ *     index. There is no `--version` flag, no lockfile, and `IndexEntry.deps`
+ *     is always `[]`, so nothing pins a specific revision.
+ *   - {@link planModuleSweep} retains that line explicitly, on top of the
+ *     per-release rule, so the property holds even for an index whose lines
+ *     are out of publish order.
+ *   - Every release keeps a downloadable payload, so an operator rolling back
+ *     to an older release still can.
+ *
+ * ── Ordering, and why it is index-first ──
+ *
+ * The download route reads the payload file directly and never consults the
+ * index. That asymmetry decides the order:
+ *
+ *   - index line first, then payload — the window is "unlisted but still
+ *     served". Nothing 404s. A crash here leaves an orphan payload, which
+ *     wastes the disk we are reclaiming but is otherwise correct.
+ *   - payload first, then index — the window is "listed but 404s", an
+ *     actively wrong registry. A crash here leaves it that way.
+ *
+ * So: index first. The orphan a crash leaves behind is then reclaimed by the
+ * NEXT run, which is what makes the sweep idempotent and safe to interrupt.
+ * The orphan pass runs FIRST for a second reason: it is pure unlink and needs
+ * no free space, so it can still make progress on a disk with nothing left to
+ * write with — the state that produced this code.
+ */
+
+import type { IndexEntry, RegistryStorage } from './storage';
+
+export interface SweepPolicy {
+  /**
+   * Build revisions to keep per released semver. Must be >= 1 — keeping zero
+   * would delete a whole release, which this policy never does.
+   */
+  keepBuildRevisions: number;
+}
+
+export const DEFAULT_KEEP_BUILD_REVISIONS = 1;
+
+export interface ModuleSweepPlan {
+  name: string;
+  /** Index entries to retain, in their original order. */
+  keep: IndexEntry[];
+  /** Versions whose index line and payload both go. */
+  remove: string[];
+  /**
+   * Payloads on disk with no index line. Unreachable by search, and the
+   * publisher's immutability check still sees them — `packageExists` reads the
+   * FILESYSTEM, so an orphan makes its version unpublishable forever with no
+   * repair path anywhere else in the product. Safe to delete, and deleting it
+   * IS the repair.
+   */
+  orphans: string[];
+  /**
+   * Index lines whose payload is missing. REPORTED, NEVER REMOVED.
+   *
+   * This is the direction the sweep must never create, and the reason it takes
+   * the index line before the payload. Removing the line would in fact repair
+   * the module — a dangling entry already 404s on download, and dropping it
+   * makes `latestVersion` resolve to a version that can actually be served.
+   * It is left alone anyway, because a missing payload and an unreadable store
+   * are indistinguishable from here: an unmounted volume or a wrong DATA_DIR
+   * makes every payload look absent, and an auto-remove would then delete the
+   * whole index. Reporting costs nothing and cannot destroy anything.
+   */
+  dangling: string[];
+  /**
+   * The module's index lists versions and NOT ONE has a payload on disk. That
+   * is a broken or unmounted store rather than N independent losses, so the
+   * sweep does nothing at all to this module — see {@link ModuleSweepPlan.dangling}.
+   */
+  unreadable: boolean;
+}
+
+export interface SweepReport {
+  modules: Array<{
+    name: string;
+    removed: string[];
+    orphans: string[];
+    dangling: string[];
+    bytes: number;
+  }>;
+  removedCount: number;
+  orphanCount: number;
+  /** Index lines with no payload. Reported for a human; never acted on. */
+  danglingCount: number;
+  /** Modules skipped entirely because their whole payload set is missing. */
+  unreadable: string[];
+  reclaimedBytes: number;
+  dryRun: boolean;
+}
+
+/**
+ * Split `X.Y.Z+N` (or `E:X.Y.Z+N`) into the release it belongs to and its
+ * build revision. Returns null for anything that does not parse — the caller
+ * treats that as "keep", because a version the sweep cannot reason about is
+ * not one it should delete.
+ */
+export function parseRevision(vers: string): { release: string; revision: number } | null {
+  const plus = vers.lastIndexOf('+');
+  if (plus <= 0) return null;
+  const release = vers.slice(0, plus);
+  const revision = Number(vers.slice(plus + 1));
+  if (!Number.isInteger(revision) || revision < 0) return null;
+  return { release, revision };
+}
+
+/**
+ * Decide what one module keeps. Pure — no filesystem, no storage.
+ *
+ * `storedVersions` is what is on DISK, which is deliberately not the same set
+ * as `entries`: a previous interrupted run can leave a payload whose index
+ * line is already gone, and reclaiming it is the whole reason this takes both.
+ */
+export function planModuleSweep(
+  name: string,
+  entries: IndexEntry[],
+  storedVersions: string[],
+  policy: SweepPolicy,
+): ModuleSweepPlan {
+  const keepBuildRevisions = Math.max(1, Math.trunc(policy.keepBuildRevisions));
+
+  const stored = new Set(storedVersions);
+  const dangling = entries.filter((e) => !stored.has(e.vers)).map((e) => e.vers);
+
+  // Every listed version missing its payload is one broken store, not N
+  // independent losses. Touch nothing.
+  if (entries.length > 0 && dangling.length === entries.length) {
+    return { name, keep: entries, remove: [], orphans: [], dangling, unreadable: true };
+  }
+
+  /**
+   * Retention is computed over the SERVABLE entries only — the ones whose
+   * payload is actually there.
+   *
+   * Doing it over every index line is subtly wrong in a way that bites exactly
+   * when the store is already damaged. If a module's NEWEST line is dangling,
+   * that line satisfies both the per-release rule and the latest-line rule, so
+   * every older version — the servable ones — becomes "superseded" and is
+   * swept. The module is then listed, has one index line, and cannot be
+   * downloaded at all. The sweep would not have created the dangling entry,
+   * but it would have removed the last thing that still worked.
+   */
+  const servable = entries.filter((e) => stored.has(e.vers));
+
+  const retained = new Set<string>();
+
+  // The newest `keepBuildRevisions` of each release.
+  const byRelease = new Map<string, Array<{ vers: string; revision: number }>>();
+  for (const entry of servable) {
+    const parsed = parseRevision(entry.vers);
+    if (!parsed) {
+      // Unparseable — never a publish this server accepted, so it is hand-
+      // written state. Keep it and move on.
+      retained.add(entry.vers);
+      continue;
+    }
+    const group = byRelease.get(parsed.release) ?? [];
+    group.push({ vers: entry.vers, revision: parsed.revision });
+    byRelease.set(parsed.release, group);
+  }
+  for (const group of byRelease.values()) {
+    group.sort((a, b) => b.revision - a.revision);
+    for (const { vers } of group.slice(0, keepBuildRevisions)) retained.add(vers);
+  }
+
+  // What every client actually resolves to, retained explicitly rather than
+  // inferred from the rule above. The rule already covers it for an index in
+  // publish order; stating it means a disordered or hand-edited index cannot
+  // turn into an unfetchable module.
+  const lastServable = servable.at(-1);
+  if (lastServable) retained.add(lastServable.vers);
+  const lastUnyanked = [...servable].reverse().find((e) => !e.yanked);
+  if (lastUnyanked) retained.add(lastUnyanked.vers);
+
+  // Only ever removes something it can see. A dangling line is left in the
+  // index untouched and reported instead.
+  const remove = servable.filter((e) => !retained.has(e.vers)).map((e) => e.vers);
+  const removing = new Set(remove);
+  const indexed = new Set(entries.map((e) => e.vers));
+
+  return {
+    name,
+    keep: entries.filter((e) => !removing.has(e.vers)),
+    remove,
+    orphans: storedVersions.filter((v) => !indexed.has(v)),
+    dangling,
+    unreadable: false,
+  };
+}
+
+/**
+ * Apply one module's plan. Orphans first (needs no free space), then the
+ * index rewrite, then the payloads the rewrite just unlisted.
+ */
+function applyModuleSweep(
+  storage: RegistryStorage,
+  plan: ModuleSweepPlan,
+  dryRun: boolean,
+): number {
+  let bytes = 0;
+
+  for (const version of plan.orphans) {
+    bytes += storage.packageSize(plan.name, version);
+    if (!dryRun) storage.removePackage(plan.name, version);
+  }
+
+  for (const version of plan.remove) {
+    bytes += storage.packageSize(plan.name, version);
+  }
+
+  if (plan.remove.length > 0 && !dryRun) {
+    storage.updateIndex(plan.name, plan.keep);
+    for (const version of plan.remove) storage.removePackage(plan.name, version);
+  }
+
+  return bytes;
+}
+
+/** Sweep every module in the store. */
+export function sweep(storage: RegistryStorage, policy: SweepPolicy, dryRun = false): SweepReport {
+  const modules: SweepReport['modules'] = [];
+  let removedCount = 0;
+  let orphanCount = 0;
+  let reclaimedBytes = 0;
+
+  const unreadable: string[] = [];
+  let danglingCount = 0;
+
+  for (const name of storage.storedNames()) {
+    const plan = planModuleSweep(
+      name,
+      storage.readIndex(name),
+      storage.storedVersions(name),
+      policy,
+    );
+
+    if (plan.unreadable) {
+      unreadable.push(name);
+      continue;
+    }
+
+    danglingCount += plan.dangling.length;
+    if (plan.remove.length === 0 && plan.orphans.length === 0 && plan.dangling.length === 0) {
+      continue;
+    }
+
+    const bytes = applyModuleSweep(storage, plan, dryRun);
+    modules.push({
+      name,
+      removed: plan.remove,
+      orphans: plan.orphans,
+      dangling: plan.dangling,
+      bytes,
+    });
+    removedCount += plan.remove.length;
+    orphanCount += plan.orphans.length;
+    reclaimedBytes += bytes;
+  }
+
+  return {
+    modules,
+    removedCount,
+    orphanCount,
+    danglingCount,
+    unreadable,
+    reclaimedBytes,
+    dryRun,
+  };
+}

package/scripts/consumer-paths-changed.ts

@@ -22,6 +22,9 @@
 export const CONSUMER_PATHS = [
   'packages/e2e/**',
   'packages/registry-server/**',
+  // The smoke test IS this gate's body — the only place publishModule and
+  // friends run in the consumer install shape (celilo#1142).
+  'e2e/tests/smoke.test.ts',
   // The publish driver (moved from the dead apps/celilo/scripts/publish.ts).
   'apps/celilo/src/cli/commands/publish/**',
   'scripts/publish.ts',

package/src/address-plan.test.ts

@@ -50,6 +50,25 @@ const SCANNED_PATHS = ['packages/e2e', 'e2e/tests', 'modules/*/e2e'];
  */
 const EXCLUDED = [/^packages\/e2e\/CHANGELOG\.md$/, /address-plan\.test\.ts$/];
 
+/**
+ * A single LINE may exempt itself with `#539-ok: <reason>`.
+ *
+ * There is one legitimate reason to write a banned prefix: enumerating an
+ * RFC 1918 block as a CLASS, which any correct private-address predicate must
+ * do. `192.168.` is both the operator's LAN (banned) and 192.168.0.0/16
+ * (unavoidable), and RETIRED_PREFIXES cannot tell them apart. The tell that
+ * this is the prefix list's blind spot rather than a real judgement: `10.` sits
+ * beside `192.168.` in exactly such a predicate and escapes only because `10.`
+ * was never added to the list.
+ *
+ * Deliberately per-line and not per-file. Excluding a file would blind the gate
+ * to every OTHER address in it, which is how a suppression becomes the next
+ * leak. The reason is required — a marker with nothing after the colon does not
+ * match, because an exemption that names only a line number is the next
+ * reader's mystery.
+ */
+const INLINE_EXEMPTION = /#539-ok:\s*\S/;
+
 function grepRetired(): string[] {
   const pattern = RETIRED_PREFIXES.map(toPattern).join('|');
   let out = '';
@@ -66,7 +85,8 @@ function grepRetired(): string[] {
   return out
     .split('\n')
     .filter(Boolean)
-    .filter((line) => !EXCLUDED.some((re) => re.test(line.split(':')[0])));
+    .filter((line) => !EXCLUDED.some((re) => re.test(line.split(':')[0] as string)))
+    .filter((line) => !INLINE_EXEMPTION.test(line));
 }
 
 describe('simulated address plan (#539)', () => {