@ultimat3/cli 23.0.0 → 25.0.0

package/src/island-runtime.ts

@@ -0,0 +1,241 @@
+// The page runtime as ONE chunk beside the islands (#505): realtime's `page-runtime.ts` — the store,
+// the socket stack, the query client, core's transport — built once per build, addressed by its
+// source graph like any island, and loaded by a realtime island only on a document the page boot
+// is absent from. Islands carry thin hooks over it; none carries a copy of it.
+
+// why: Bun ships no path API; the runtime is resolved beside the realtime the islands bundle.
+import { dirname, join } from 'node:path';
+import type { BunPlugin } from 'bun';
+import { IslandBuildFailedError } from './errors';
+import type { IslandChunk, SharedChunk } from './island-bundle';
+import { realSpelling } from './island-duplicates';
+import { describeBuildError, graphHash, stableChunk, stripDebugId } from './island-identity';
+import { frameworkDedupePlugins } from './island-package-dedupe';
+import type { SourcePaths } from './island-sources';
+import { sourcesOnDisk } from './island-sources';
+
+/** The runtime, as realtime exports it — resolved from the copy every realtime island bundles. */
+const RUNTIME_SPECIFIER = '@ultimat3/realtime/page-runtime';
+
+/** What an island awaits before its first hook: realtime's own, from the same copy. */
+const WAIT_SPECIFIER = '@ultimat3/realtime/page-runtime-wait';
+
+/** The virtual entry the runtime is built from, and the module it installs from. */
+const ENTRY = 'ultimate:realtime-runtime';
+const MODULE = 'ultimate:realtime-runtime-module';
+const NAMESPACE = 'ultimate-realtime-runtime';
+
+/**
+ * `page-runtime.<identity>.js`. The dot is the point: an island entry is `<moduleId>-<identity>.js`
+ * and a module id is `[a-z0-9-]` only (`islandModuleId`), so no island — not even one named
+ * `realtime.island.tsx` — can be served at a URL this name could be.
+ */
+const RUNTIME_CHUNK_FILE = /^page-runtime\.[0-9a-z]+\.js$/;
+
+/** The relative specifier a realtime island's bootstrap `import()`s the runtime chunk by. */
+export const RUNTIME_CHUNK_SPECIFIER = /^\.\/page-runtime\.[0-9a-z]+\.js$/;
+
+/** Whether `url` (any base path) is the page runtime's chunk — the one predicate, never a prefix. */
+export function isRuntimeChunk(url: string): boolean {
+  const slash = url.lastIndexOf('/');
+  return slash !== -1 && RUNTIME_CHUNK_FILE.test(url.slice(slash + 1));
+}
+
+/** The page runtime a realtime island loads — built once per `buildIslands` call. */
+export type Runtimes = (island: string) => Promise<RuntimeChunk>;
+
+/** One runtime chunk: served beside the islands, never a `data-x-entry` of its own. */
+export interface RuntimeChunk {
+  /**
+   * The realtime barrel it was built against — the ONE copy every realtime island of the build
+   * bundles its hooks from, or the page object the runtime installs is not the shape they read.
+   */
+  readonly realtime: string;
+  /** What an island's bootstrap awaits the runtime with: `page-runtime-wait.ts`, of that copy. */
+  readonly wait: string;
+  readonly url: string;
+  readonly code: string;
+  readonly bytes: number;
+  readonly sources: SourcePaths;
+}
+
+/**
+ * Builds the runtime at most once per build: every realtime island of one `buildIslands` call loads
+ * the SAME chunk, whether the islands are built together or one by one. The first island's realtime
+ * copy is the build's; another copy at the SAME version is the same code and folds onto it (a
+ * Windows `file:` install copies a package where a symlink would fold it). Another VERSION is
+ * refused: the first runtime to install wins the page, so that copy's islands would call services
+ * of a shape they were not built against.
+ */
+export function runtimeBuilder(root: string, basePath: string): Runtimes {
+  let first: { readonly copy: RealtimeCopy; readonly chunk: Promise<RuntimeChunk> } | undefined;
+  return async (island: string): Promise<RuntimeChunk> => {
+    // From the island's own directory: the resolution the island itself gets — by its REAL path,
+    // the spelling the framework dedupe gives every other `@ultimat3/*` file. Windows' resolver
+    // answers a junction's spelling, and Bun keys a module by its path string, so the barrel's own
+    // relative imports would ship again beside the realpath ones (`island-duplicates.ts`).
+    const copy = await realtimeCopy(
+      island,
+      realSpelling(Bun.resolveSync('@ultimat3/realtime', dirname(join(root, island)))),
+    );
+    if (first === undefined) {
+      first = { copy, chunk: buildRuntime(root, island, copy.barrel, basePath) };
+    } else if (first.copy.version !== copy.version) {
+      throw new IslandBuildFailedError({
+        file: island,
+        logs: `it resolves @ultimat3/realtime ${copy.version} (${copy.dir}) while another island of this build resolves ${first.copy.version} (${first.copy.dir}): one page runs ONE runtime, and @ultimat3/realtime is released in lockstep, so install one version of it across the apps`,
+      });
+    }
+    return first.chunk;
+  };
+}
+
+interface RealtimeCopy {
+  /** The barrel the island resolved. */
+  readonly barrel: string;
+  /** The package's directory, for the refusal. */
+  readonly dir: string;
+  readonly version: string;
+}
+
+/** The installed package the barrel belongs to: the nearest `package.json` above it. */
+async function realtimeCopy(island: string, barrel: string): Promise<RealtimeCopy> {
+  for (let dir = dirname(barrel); dir !== dirname(dir); dir = dirname(dir)) {
+    const manifest = Bun.file(join(dir, 'package.json'));
+    if (!(await manifest.exists())) continue;
+    const parsed: unknown = await manifest.json();
+    const version =
+      typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'version') : undefined;
+    return { barrel, dir, version: typeof version === 'string' ? version : 'an unversioned copy' };
+  }
+  throw new IslandBuildFailedError({
+    file: island,
+    logs: `the @ultimat3/realtime it resolves (${barrel}) has no package.json above it, so its version cannot be checked against the build's`,
+  });
+}
+
+/** A subpath of the realtime at `realtime`, through its `exports` — never a path into its source. */
+function exported(island: string, realtime: string, specifier: string): string {
+  try {
+    return realSpelling(Bun.resolveSync(specifier, dirname(realtime)));
+  } catch {
+    throw new IslandBuildFailedError({
+      file: island,
+      logs: `the realtime it resolves (${realtime}) exports no ${specifier}: @ultimat3/realtime and @ultimat3/cli are released in lockstep, so install the same version of both`,
+    });
+  }
+}
+
+async function buildRuntime(
+  root: string,
+  island: string,
+  realtime: string,
+  basePath: string,
+): Promise<RuntimeChunk> {
+  const file = exported(island, realtime, RUNTIME_SPECIFIER);
+  const wait = exported(island, realtime, WAIT_SPECIFIER);
+  let built: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    built = await Bun.build({
+      entrypoints: [ENTRY],
+      root,
+      target: 'browser',
+      format: 'esm',
+      minify: true,
+      plugins: [runtimeEntryPlugin(file), ...frameworkDedupePlugins(root)],
+      // `island-bundle.ts`'s reasons, verbatim: only ever built to be shipped, and the map's
+      // `sourcesContent` is the one stable identity a minified bundle has.
+      define: { 'process.env.NODE_ENV': '"production"' },
+      sourcemap: 'external',
+    });
+  } catch (error) {
+    throw new IslandBuildFailedError({ file: island, logs: describeBuildError(error) });
+  }
+  const output = built.outputs.find((artifact) => artifact.kind === 'entry-point');
+  const map = built.outputs.find((artifact) => artifact.kind === 'sourcemap');
+  if (!built.success || output === undefined || map === undefined) {
+    throw new IslandBuildFailedError({
+      file: island,
+      logs: built.logs.map((log) => String(log)).join('; '),
+    });
+  }
+  const text = await map.text();
+  const identity = graphHash(ENTRY, text);
+  const url = `${basePath}/page-runtime.${identity}.js`;
+  return {
+    realtime,
+    wait,
+    url,
+    ...stableChunk(url, identity, stripDebugId(await output.text())),
+    sources: await sourcesOnDisk(root, JSON.parse(text)),
+  };
+}
+
+/**
+ * The entry installs the runtime as its whole body; the module is named BARE in that source and
+ * resolved here, because the source is part of `sourcesContent` and a machine path in it would give
+ * one runtime a different URL in every checkout (the reason `island-realtime.ts` names realtime).
+ */
+function runtimeEntryPlugin(file: string): BunPlugin {
+  return {
+    name: 'ultimate-realtime-runtime',
+    setup(build) {
+      build.onResolve({ filter: /^ultimate:realtime-runtime$/ }, () => ({
+        path: 'entry',
+        namespace: NAMESPACE,
+      }));
+      build.onResolve({ filter: /^ultimate:realtime-runtime-module$/ }, () => ({ path: file }));
+      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, () => ({
+        contents: `import { installPageRuntime } from '${MODULE}';\ninstallPageRuntime();\n`,
+        loader: 'js',
+      }));
+    },
+  };
+}
+
+/** Every realtime entry names the runtime among what it loads: a precache and a budget count it. */
+export function loadingRuntime(
+  chunks: readonly IslandChunk[],
+  live: readonly string[],
+  runtime: RuntimeChunk | undefined,
+): readonly IslandChunk[] {
+  if (runtime === undefined) return chunks;
+  return chunks.map((chunk) =>
+    live.includes(chunk.file)
+      ? { ...chunk, imports: [...new Set([...chunk.imports, runtime.url])].sort() }
+      : chunk,
+  );
+}
+
+/** The runtime as the bundle's shared asset — served, written and precached beside the entries. */
+export function runtimeShared(
+  runtime: RuntimeChunk | undefined,
+  live: readonly string[],
+): readonly SharedChunk[] {
+  if (runtime === undefined) return [];
+  const { url, code, bytes, sources } = runtime;
+  return [{ url, code, bytes, importers: [...live].sort(), sources }];
+}
+
+/**
+ * One-island builds as one bundle's two tables: every entry, and each shared asset once by URL with
+ * its importers the union — each solo build names the runtime for itself.
+ */
+export function mergeBuilds(
+  builds: readonly {
+    readonly chunks: readonly IslandChunk[];
+    readonly shared: readonly SharedChunk[];
+  }[],
+): [readonly IslandChunk[], readonly SharedChunk[]] {
+  const byUrl = new Map<string, SharedChunk>();
+  for (const one of builds.flatMap((build) => build.shared)) {
+    const seen = byUrl.get(one.url);
+    byUrl.set(
+      one.url,
+      seen === undefined
+        ? one
+        : { ...seen, importers: [...new Set([...seen.importers, ...one.importers])].sort() },
+    );
+  }
+  return [builds.flatMap((build) => build.chunks), [...byUrl.values()]];
+}

package/src/island-sources.ts

@@ -0,0 +1,105 @@
+// The files on disk an island chunk was built from, and whether they still hold those bytes. The
+// prebuilt store (`island-store.ts`) verified only its own chunk bytes, so a source edited after
+// `x build --target prebuilt` still verified and a boot served the chunk built from the old one.
+
+// why: Bun ships no path join/resolve/relative primitive.
+import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { contentHash } from '@ultimat3/render/server';
+import { hasPathSegment } from './path-segments';
+
+/**
+ * App-root-relative POSIX paths of the files an output was built from — its source map's
+ * `sources`, outside `node_modules` and inside the app root.
+ */
+export type SourcePaths = readonly string[];
+
+/**
+ * A path the store may record and a boot may read: app-root-relative, normalized, inside the
+ * root, outside `node_modules`. The writer filters on it and the reader REFUSES on it — the index is
+ * a file on disk, and a path read at every boot must never be `../../etc/hostname` or `/dev/zero`.
+ */
+export function isRecordableSource(path: string): boolean {
+  return (
+    path !== '' &&
+    posix.normalize(path) === path &&
+    !path.startsWith('..') &&
+    !isAbsolute(path) &&
+    !path.includes('\\') &&
+    !hasPathSegment(path, 'node_modules')
+  );
+}
+
+/** One recorded source: its path and the content digest of its bytes when the store was written. */
+export interface SourceStamp {
+  readonly path: string;
+  readonly digest: string;
+}
+
+/**
+ * A source map's `sources` that are files in the app. A virtual module (the realtime wrapper) has
+ * no file; `node_modules` changes only with an install, and hashing it would make every pod boot
+ * pay for the dependency tree.
+ */
+export async function sourcesOnDisk(root: string, map: unknown): Promise<SourcePaths> {
+  const listed: unknown =
+    typeof map === 'object' && map !== null ? (map as Record<string, unknown>)['sources'] : [];
+  // Bun 1.4.2 writes each source relative to the BUILDING process's cwd, not to the map or to the
+  // build's `root` (measured: a build run from the repo root over a /tmp app names
+  // `../../tmp/…/plain.island.tsx`), so that is what they are resolved against.
+  const cwd = process.cwd();
+  const paths = (Array.isArray(listed) ? listed : [])
+    .filter((one): one is string => typeof one === 'string')
+    .map((one) => relative(root, resolve(cwd, one)).split(sep).join('/'))
+    .filter(isRecordableSource);
+  const present = await Promise.all(paths.map((one) => Bun.file(join(root, one)).exists()));
+  return [...new Set(paths.filter((_, index) => present[index]))].sort();
+}
+
+/** Each path with the content digest of its bytes now — `undefined` for a file that is gone. */
+export type SourceDigester = (path: string) => Promise<string | undefined>;
+
+/**
+ * A digester that reads each file once, however many chunks name it: a module shared by every
+ * island is one read per boot, not one per island.
+ */
+export function sourceDigester(root: string): SourceDigester {
+  const seen = new Map<string, Promise<string | undefined>>();
+  return (path) => {
+    let digested = seen.get(path);
+    if (digested === undefined) {
+      const file = Bun.file(join(root, path));
+      digested = file
+        .exists()
+        .then(async (exists) => (exists ? contentHash(await file.text()) : undefined));
+      seen.set(path, digested);
+    }
+    return digested;
+  };
+}
+
+/** What the store records for one chunk's sources. */
+export async function stampSources(
+  paths: SourcePaths,
+  digestOf: SourceDigester,
+): Promise<readonly SourceStamp[]> {
+  const stamps: SourceStamp[] = [];
+  for (const path of paths) {
+    const now = await digestOf(path);
+    if (now !== undefined) stamps.push({ path, digest: now });
+  }
+  return stamps;
+}
+
+/**
+ * The first recorded source that is gone or whose content digest moved, else `undefined`. A plain
+ * comparison: a digest of a source file the app commits is no secret, and nothing here is timed.
+ */
+export async function changedSource(
+  stamps: readonly SourceStamp[],
+  digestOf: SourceDigester,
+): Promise<string | undefined> {
+  for (const stamp of stamps) {
+    if ((await digestOf(stamp.path)) !== stamp.digest) return stamp.path;
+  }
+  return undefined;
+}

package/src/island-states-load.ts

@@ -53,6 +53,12 @@ export async function discoverIslandStates(root: string): Promise<readonly strin
 async function manifestsIn(root: string, file: string): Promise<readonly IslandStatesManifest[]> {
   const absolute = join(root, file);
   assertIslandStatesPure(file, await Bun.file(absolute).text());
+  // Evicted first: Bun caches `import()` by path, and `x dev` loads the states on every shot
+  // request in one process — so an edited states file was never read again until a restart, and
+  // `app-load.ts`'s reload skips this file by name. The check above read the NEW text; this makes
+  // the import evaluate that same text. A states file imports no relative module (the purity rule
+  // refuses one), so the file itself is the whole of what can be stale.
+  delete require.cache[absolute];
   const module: unknown = await import(absolute);
   const exported = typeof module === 'object' && module !== null ? Object.values(module) : [];
   const found = exported.filter(isIslandStatesManifest);

package/src/island-store.ts

@@ -10,8 +10,11 @@
 import { join, relative, sep } from 'node:path'; // why: Bun ships no path-join primitive.
 import { frameworkVersion } from '@ultimat3/core';
 import { contentHash, loadStylesheet } from '@ultimat3/render/server';
+import { IslandBuildFailedError } from './errors';
 import type { IslandBundle, IslandChunk, SharedChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
+import type { SourceDigester, SourceStamp } from './island-sources';
+import { changedSource, isRecordableSource, sourceDigester, stampSources } from './island-sources';
 import { islandStylesheets } from './island-styles';
 import { PREBUILT_ISLANDS_DIR } from './serve-prebuilt-paths';
 
@@ -26,6 +29,8 @@ interface StoredChunk {
   readonly identity: string;
   /** The shared chunk URLs the entry loads, transitively (`IslandChunk.imports`). */
   readonly imports: readonly string[];
+  /** The files it was built from, hashed at write — rehashed at read (`island-sources.ts`). */
+  readonly sources: readonly SourceStamp[];
 }
 
 /** A shared chunk: no island of its own, verified by the same hash. */
@@ -33,6 +38,7 @@ interface StoredShared {
   readonly url: string;
   readonly identity: string;
   readonly importers: readonly string[];
+  readonly sources: readonly SourceStamp[];
 }
 
 interface StoreIndex {
@@ -52,12 +58,32 @@ interface StoreIndex {
 
 const chunkFile = (url: string): string => url.slice(url.lastIndexOf('/') + 1);
 
+/**
+ * Refuses a bundle in which an island's own file is a source of nothing it loads. Its file is
+ * always one — in its entry chunk, or in a shared chunk when another island imports it — so its
+ * absence means the map's paths stopped resolving into the root (`sourcesOnDisk`), and the store
+ * would record nothing to rehash: a boot would serve that chunk after any edit, the K8 bug again.
+ */
+function refuseUntracked(bundle: IslandBundle): void {
+  const shared = new Map(bundle.shared.map((one) => [one.url, one.sources ?? []]));
+  for (const chunk of bundle.chunks) {
+    const loaded = [chunk.sources ?? [], ...chunk.imports.map((url) => shared.get(url) ?? [])];
+    if (loaded.some((sources) => sources.includes(chunk.file))) continue;
+    throw new IslandBuildFailedError({
+      file: chunk.file,
+      logs: `neither its chunk nor a shared chunk it loads records ${chunk.file} as a source — the source map's paths, resolved against the build's cwd ${process.cwd()}, no longer land in the app root, so a prebuilt store would serve this chunk after the file is edited`,
+    });
+  }
+}
+
 /** Writes every chunk and the index that verifies them. Answers the files written, app-relative. */
 export async function writeIslandStore(
   root: string,
   bundle: IslandBundle,
 ): Promise<readonly string[]> {
+  refuseUntracked(bundle);
   const dir = join(root, ISLAND_STORE_DIR);
+  const digestOf = sourceDigester(root);
   const chunks: StoredChunk[] = [];
   const written: string[] = [];
   for (const chunk of bundle.chunks) {
@@ -69,13 +95,19 @@ export async function writeIslandStore(
       url: chunk.url,
       identity: contentHash(chunk.code),
       imports: chunk.imports,
+      sources: await stampSources(chunk.sources ?? [], digestOf),
     });
   }
   const shared: StoredShared[] = [];
   for (const chunk of bundle.shared) {
     await Bun.write(join(dir, chunkFile(chunk.url)), chunk.code);
     written.push(`${ISLAND_STORE_DIR}/${chunkFile(chunk.url)}`);
-    shared.push({ url: chunk.url, identity: contentHash(chunk.code), importers: chunk.importers });
+    shared.push({
+      url: chunk.url,
+      identity: contentHash(chunk.code),
+      importers: chunk.importers,
+      sources: await stampSources(chunk.sources ?? [], digestOf),
+    });
   }
   const stylesheets = islandStylesheets()
     .map((path) => relative(root, path).split(sep).join('/'))
@@ -97,8 +129,29 @@ const isString = (value: unknown): value is string => typeof value === 'string';
 const stringsOf = (value: unknown): readonly string[] =>
   Array.isArray(value) ? value.filter(isString) : [];
 
-/** The index, narrowed field by field — a file on disk is input, never a trusted shape. */
-function parseIndex(value: unknown): StoreIndex | undefined {
+/**
+ * `undefined` when the field is absent or any entry is malformed or names a path outside the app:
+ * a store that cannot say what it was built from cannot be checked, which is stale — never
+ * "nothing to check".
+ */
+function stampsOf(value: unknown): readonly SourceStamp[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const stamps: SourceStamp[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    const { path, digest } = entry as Record<string, unknown>;
+    // A path the writer could not have recorded is refused before anything reads it.
+    if (!isString(path) || !isString(digest) || !isRecordableSource(path)) return undefined;
+    stamps.push({ path, digest });
+  }
+  return stamps;
+}
+
+/**
+ * The index, narrowed field by field — a file on disk is input, never a trusted shape. `unchecked`
+ * names an output that records no sources: a store written before they were recorded.
+ */
+function parseIndex(value: unknown): StoreIndex | { readonly unchecked: string } | undefined {
   if (typeof value !== 'object' || value === null) return undefined;
   const record = value as Record<string, unknown>;
   const chunks = record['chunks'];
@@ -112,14 +165,18 @@ function parseIndex(value: unknown): StoreIndex | undefined {
     const { file, moduleId, url, identity, imports } = chunk;
     if (!isString(file) || !isString(moduleId) || !isString(url) || !isString(identity))
       return undefined;
-    parsed.push({ file, moduleId, url, identity, imports: stringsOf(imports) });
+    const sources = stampsOf(chunk['sources']);
+    if (sources === undefined) return { unchecked: url };
+    parsed.push({ file, moduleId, url, identity, imports: stringsOf(imports), sources });
   }
   const shared: StoredShared[] = [];
   for (const entry of Array.isArray(record['shared']) ? record['shared'] : []) {
     if (typeof entry !== 'object' || entry === null) return undefined;
-    const { url, identity, importers } = entry as Record<string, unknown>;
+    const { url, identity, importers, sources: listed } = entry as Record<string, unknown>;
     if (!isString(url) || !isString(identity)) return undefined;
-    shared.push({ url, identity, importers: stringsOf(importers) });
+    const sources = stampsOf(listed);
+    if (sources === undefined) return { unchecked: url };
+    shared.push({ url, identity, importers: stringsOf(importers), sources });
   }
   const sheets = record['stylesheets'];
   // Absent in a 22.3.2 store: read as none, and the boot builds when it matters (see below).
@@ -133,6 +190,18 @@ function parseIndex(value: unknown): StoreIndex | undefined {
   };
 }
 
+/** The first output with a recorded source that is gone or no longer hashes the same. */
+async function firstEdited(
+  outputs: readonly { readonly url: string; readonly sources: readonly SourceStamp[] }[],
+  digestOf: SourceDigester,
+): Promise<{ readonly url: string; readonly path: string } | undefined> {
+  for (const output of outputs) {
+    const path = await changedSource(output.sources, digestOf);
+    if (path !== undefined) return { url: output.url, path };
+  }
+  return undefined;
+}
+
 /** A verified store, or the one sentence saying why it cannot be served. */
 export type StoreRead =
   | { readonly bundle: IslandBundle; readonly stale?: undefined }
@@ -144,6 +213,11 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
   if (!(await file.exists())) return { stale: `no ${ISLAND_STORE_DIR}/${INDEX}` };
   const index = parseIndex(await file.json().catch(() => undefined));
   if (index === undefined) return { stale: `${ISLAND_STORE_DIR}/${INDEX} does not parse` };
+  if ('unchecked' in index) {
+    return {
+      stale: `${index.unchecked} records no checkable sources, so an edit since it was built would be unseen`,
+    };
+  }
   if (index.framework !== frameworkVersion() || index.bun !== Bun.version) {
     return {
       stale: `built by framework ${index.framework} on Bun ${index.bun}, serving ${frameworkVersion()} on Bun ${Bun.version}`,
@@ -154,6 +228,16 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
   if (stored.join('\n') !== present.join('\n')) {
     return { stale: 'the stored islands are not the islands this app has' };
   }
+  // Every recorded source first: a chunk whose bytes verify was still built from whatever the files
+  // said THEN. Only the recorded paths are read, each once, so a boot pays for the app's own island
+  // sources and nothing else.
+  const digestOf = sourceDigester(root);
+  const edited = await firstEdited([...index.chunks, ...index.shared], digestOf);
+  if (edited !== undefined) {
+    return {
+      stale: `${edited.path}, a source of ${edited.url}, changed since the store was built`,
+    };
+  }
   const verified = async (entry: { readonly url: string; readonly identity: string }) => {
     const bytes = Bun.file(join(dir, chunkFile(entry.url)));
     const code = (await bytes.exists()) ? await bytes.text() : undefined;

package/src/jobs-json.ts

@@ -13,7 +13,6 @@ import type {
   StepTrace,
   WorkerRecord,
 } from '@ultimat3/jobs';
-import type { DrainFailure, DrainSkip } from './jobs-drain';
 import type { JsonValue } from './output';
 
 function stepTraceToJson(step: StepTrace): JsonValue {
@@ -181,28 +180,3 @@ export function deadLetterToJson(entry: DeadLetterEntry): JsonValue {
     retryCommand: entry.retryCommand,
   };
 }
-
-export function drainFailureToJson(failure: DrainFailure): JsonValue {
-  return {
-    id: failure.id,
-    name: failure.name,
-    finding: {
-      code: failure.finding.code,
-      cause: failure.finding.cause,
-      fix: failure.finding.fix,
-      docs: failure.finding.docs ?? null,
-      at: failure.finding.at ?? null,
-    },
-  };
-}
-
-/** A candidate the drain refused to touch, and why — the half of the outcome `moved` cannot show. */
-export function drainSkipToJson(skip: DrainSkip): JsonValue {
-  return {
-    id: skip.id,
-    name: skip.name,
-    queue: skip.queue,
-    state: skip.state,
-    reason: skip.reason,
-  };
-}