@ultimat3/cli 22.15.0 → 24.0.0

package/src/import-closure.ts

@@ -0,0 +1,165 @@
+// The modules a set of entry files can EXECUTE, followed name by name through barrels. A package
+// barrel re-exports its whole surface by name (the house forbids `export *`), so a closure taken
+// module by module reaches every server file of every package an island touches — `@ultimat3/action`'s
+// barrel reaches `http.ts` — while a bundler with honest `sideEffects` keeps only the modules the
+// imported NAMES live in. This follows the names, which is what makes "browser-reachable" a
+// question with a useful answer instead of "everything".
+//
+// Pure over an injected reader, so a test's fixture tree is a Map rather than files on disk.
+
+import { stripComments } from '@ultimat3/core';
+
+/** What a module asks of another: named bindings, or the whole module (`*`). */
+export type Wanted = '*' | ReadonlySet<string>;
+
+export interface ModuleShape {
+  /** `import … from`, `import('x')` — followed only when this module's body runs. */
+  readonly imports: readonly { readonly spec: string; readonly names: Wanted }[];
+  /** `export { local as exported } from 'x'` — followed only for the names somebody wants. */
+  readonly reexports: readonly {
+    readonly spec: string;
+    readonly map: ReadonlyMap<string, string>;
+  }[];
+  /** `export * from 'x'` — searched for a wanted name this module does not name itself. */
+  readonly stars: readonly string[];
+  /** `import 'x'` — runs whenever this module is touched at all, which is what a barrel's is for. */
+  readonly effects: readonly string[];
+}
+
+export interface ClosureHost {
+  /** The file's text, or `undefined` when there is no such file. Paths are root-relative POSIX. */
+  read(path: string): string | undefined;
+  /**
+   * A bare specifier's file (`@ultimat3/core` → `packages/core/src/index.ts`), or `undefined` —
+   * which ENDS the walk there: an installed package is past the boundary this closure reads.
+   */
+  alias(spec: string, from: string): string | undefined;
+}
+
+const IMPORT_FROM = /\bimport\s+(?!type\s)([^;'"]*?)\s*from\s*(['"])([^'"]+)\2/g;
+const IMPORT_BARE = /\bimport\s*(['"])([^'"]+)\1/g;
+const IMPORT_DYNAMIC = /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g;
+const EXPORT_FROM = /\bexport\s+(?!type\s)\{([^}]*)\}\s*from\s*(['"])([^'"]+)\2/g;
+const EXPORT_STAR = /\bexport\s+\*\s*(?:as\s+[\w$]+\s*)?from\s*(['"])([^'"]+)\1/g;
+
+/** `a, type b, c as d` → the value names, `type` members dropped. */
+const members = (list: string): readonly (readonly [string, string])[] =>
+  list
+    .split(',')
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith('type '))
+    .map((part) => {
+      const [local = part, exported = local] = part.split(/\s+as\s+/);
+      return [local.trim(), exported.trim()] as const;
+    });
+
+/** The names an import clause binds: `default`, the braced members, or `*` for a namespace. */
+function clauseNames(clause: string): Wanted {
+  if (/\*\s*as\s/.test(clause)) return '*';
+  const names = new Set<string>();
+  const braced = /\{([^}]*)\}/.exec(clause);
+  for (const [local] of members(braced?.[1] ?? '')) names.add(local);
+  const head = clause
+    .replace(/\{[^}]*\}/, '')
+    .replace(/,/g, ' ')
+    .trim();
+  if (head.length > 0) names.add('default');
+  return names;
+}
+
+export function parseModule(source: string): ModuleShape {
+  const code = stripComments(source);
+  const imports: { spec: string; names: Wanted }[] = [];
+  for (const found of code.matchAll(IMPORT_FROM)) {
+    const names = clauseNames(found[1] ?? '');
+    // `import type { A }` is caught above; `import { type A }` alone binds nothing at runtime.
+    if (names !== '*' && names.size === 0) continue;
+    imports.push({ spec: found[3] ?? '', names });
+  }
+  const effects = [...code.matchAll(IMPORT_BARE)].map((found) => found[2] ?? '');
+  for (const found of code.matchAll(IMPORT_DYNAMIC)) {
+    imports.push({ spec: found[2] ?? '', names: '*' });
+  }
+  const reexports = [...code.matchAll(EXPORT_FROM)].map((found) => ({
+    spec: found[3] ?? '',
+    map: new Map(members(found[1] ?? '').map(([local, exported]) => [exported, local])),
+  }));
+  const stars = [...code.matchAll(EXPORT_STAR)].map((found) => found[2] ?? '');
+  return { imports, reexports, stars, effects };
+}
+
+const CANDIDATES = ['', '.ts', '.tsx', '/index.ts', '/index.tsx'];
+
+/** A relative specifier against the importing file, extension-less as TypeScript writes it. */
+function resolveRelative(host: ClosureHost, from: string, spec: string): string | undefined {
+  const base = from.split('/').slice(0, -1);
+  for (const part of spec.split('/')) {
+    if (part === '.' || part === '') continue;
+    if (part === '..') base.pop();
+    else base.push(part);
+  }
+  const joined = base.join('/').replace(/\.js$/, '');
+  for (const suffix of CANDIDATES) {
+    const path = `${joined}${suffix}`;
+    if (/\.tsx?$/.test(path) && host.read(path) !== undefined) return path;
+  }
+  return undefined;
+}
+
+export function resolveSpec(host: ClosureHost, from: string, spec: string): string | undefined {
+  return spec.startsWith('.') ? resolveRelative(host, from, spec) : host.alias(spec, from);
+}
+
+/**
+ * Every module whose BODY an entry set can run. A module reached only for names it re-exports is
+ * passed through, not included: its own statements are the re-export lines and nothing else.
+ */
+export function importClosure(host: ClosureHost, entries: readonly string[]): readonly string[] {
+  const shapes = new Map<string, ModuleShape>();
+  const bodies = new Set<string>();
+  const asked = new Map<string, Set<string>>();
+  const queue: { path: string; names: Wanted }[] = entries.map((path) => ({ path, names: '*' }));
+
+  const shapeOf = (path: string): ModuleShape | undefined => {
+    const known = shapes.get(path);
+    if (known !== undefined) return known;
+    const source = host.read(path);
+    if (source === undefined) return undefined;
+    const shape = parseModule(source);
+    shapes.set(path, shape);
+    return shape;
+  };
+  const follow = (from: string, spec: string, names: Wanted): void => {
+    const path = resolveSpec(host, from, spec);
+    if (path !== undefined) queue.push({ path, names });
+  };
+
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    const { path, names } = next;
+    const shape = shapeOf(path);
+    if (shape === undefined) continue;
+    let needsBody = names === '*';
+    const seen = asked.get(path) ?? new Set<string>();
+    if (!asked.has(path)) for (const effect of shape.effects) follow(path, effect, '*');
+    asked.set(path, seen);
+    for (const name of names === '*' ? [] : names) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      const source = shape.reexports.find((entry) => entry.map.has(name));
+      if (source !== undefined) {
+        follow(path, source.spec, new Set([source.map.get(name) ?? name]));
+        continue;
+      }
+      needsBody = true;
+      for (const star of shape.stars) follow(path, star, new Set([name]));
+    }
+    if (names === '*') {
+      for (const entry of shape.reexports) follow(path, entry.spec, new Set(entry.map.values()));
+      for (const star of shape.stars) follow(path, star, '*');
+    }
+    if (!needsBody || bodies.has(path)) continue;
+    bodies.add(path);
+    for (const entry of shape.imports) follow(path, entry.spec, entry.names);
+  }
+  return [...bodies].sort();
+}

package/src/index.ts

@@ -8,11 +8,10 @@
 import './error-codes';
 
 /** The app's own API over HTTP — the one table `x dev` and a container both mount. */
-export { apiRoutes } from './api-routes';
+export { apiMountRoutes, apiRoutes } from './api-routes';
 export type { SourceFile } from './app-boundaries';
 export {
   appImportGraph,
-  checkAppBoundaries,
   readAppSources,
   resolveSpecifier,
   scanRuntimeImports,
@@ -22,7 +21,7 @@ export { appManifest, writeAppManifest } from './app-manifest';
 export { requireAppRoot } from './app-root';
 export type { RouteStats } from './budgets';
 export { checkBudgets, FRAMEWORK_INLINE_SCRIPTS, FRAMEWORK_SCRIPTS } from './budgets';
-export { BUILD_ENTRY, BUILD_TARGETS, readTarget } from './cmd-build';
+export { BUILD_ENTRY, BUILD_TARGETS, BuildEntryMissingError, readTarget } from './cmd-build';
 export { dbCommand } from './cmd-db';
 export { planDeploy } from './cmd-deploy';
 export { startDev } from './cmd-dev';
@@ -46,6 +45,11 @@ export type { BranchRow } from './db-branch';
 export { BRANCH_SUBCOMMANDS, branchDatabaseName, branchNameOf } from './db-branch';
 export type { GeneratedFiles } from './db-generate';
 export { generateAppMigration } from './db-generate';
+// The schema dump's two verbs for a caller that holds an app root and no command context —
+// `scripts/schema-dumps.ts` regenerates and checks every tracked app's through them.
+export { SCHEMA_DUMP_DIR } from './db-schema-dump';
+export type { SchemaDumpRefresh } from './db-schema-refresh';
+export { refreshSchemaDump } from './db-schema-refresh';
 export { QuerySubscribesUnknownError, replicaIdentityTables } from './db-subscribes';
 export { dispatch } from './dispatch';
 export { checkSourceDrift, reconcileSchemaHash, writeSchemaHash } from './drift';
@@ -65,10 +69,8 @@ export {
 export { checkErrorCodesThrown } from './error-unthrown';
 export {
   BadFlagError,
-  BuildEntryMissingError,
   BunVersionError,
   CatalogExistsError,
-  CliNotImplementedError,
   DeclarationUnknownError,
   ErrorCodeUnknownError,
   FixTargetUnknownError,
@@ -99,6 +101,10 @@ export { checkFlagReads } from './flag-reads';
 // The framework's own tables, as data. Exported so `scripts/` can read the applier's list without
 // re-deriving it — the shape a ratchet over declared-but-never-applied DDL needs.
 export { FRAMEWORK_SCHEMA } from './framework-schema';
+// What a guard's `check(root, sources)` is handed: the run's one read of the app. Types an app's
+// `guards/*.ts` names, and the constructor a test of one needs.
+export type { GuardFile, GuardSources, GuardStylesheet } from './guard-sources';
+export { guardSources } from './guard-sources';
 export type { Guard } from './guards';
 export { findingProblem, guardFindings, guardPaths } from './guards';
 export { ICON_BASE_PATH, ICON_SOURCE } from './icon-assets';
@@ -134,6 +140,7 @@ export type { RunningServices } from './runtime-services';
 export { startServices } from './runtime-services';
 // The drift a hash cannot see, and the composition both the gate step and `x doctor` read.
 export { checkMigrationDrift, checkSnapshotDrift } from './schema-drift';
+export { checkSchemaDump } from './schema-dump-drift';
 export { FrameworkSchemaFailedError } from './schema-errors';
 export type { MigratedApp, ServeOptions } from './serve';
 export {

package/src/island-bundle.ts

@@ -22,8 +22,7 @@
 // POSIX by construction), `join`/`basename` the filesystem side.
 import { basename, join, posix, relative, sep } from 'node:path';
 import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/render';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { IslandBuildFailedError } from './errors';
 import { describeBuildError, sourcesContentOf, stableChunk, stripDebugId } from './island-identity';
 import type { BuiltOutput, LinkedFile } from './island-link';
@@ -357,20 +356,9 @@ export interface BuildIslandsOptions {
   readonly sharedChunks?: boolean;
 }
 
-/**
- * `islands.sharedChunks` as `defineConfig` validated it — `false` for an app with no config file or
- * none of it. Structural, never `instanceof`, for `loadNavigation`'s reason.
- */
+/** `islands.sharedChunks` off the one loader (`app-config-load.ts`) — `false` with no config file. */
 export async function loadSharedChunks(root: string): Promise<boolean> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return false;
-  const config: unknown = ((await import(configPath)) as Record<string, unknown>)[
-    APP_CONFIG_EXPORT
-  ];
-  if (typeof config !== 'object' || config === null) return false;
-  const islands: unknown = (config as Record<string, unknown>)['islands'];
-  if (typeof islands !== 'object' || islands === null) return false;
-  return (islands as Record<string, unknown>)['sharedChunks'] === true;
+  return (await loadAppConfig(root))?.islands.sharedChunks ?? false;
 }
 
 /** Build every island in the app. An app with none returns an empty bundle and costs one glob. */

package/src/island-store.ts

@@ -1,21 +1,22 @@
-// The island chunks a container serves, built ONCE by `x build --target docker` into
-// `.x/islands/` and read back at boot. Without it every role's boot ran `Bun.build` — Babel, the
-// JSX transform, a minifier — for every island, in the image, on every start, and a chunk whose
-// URL is a hash of its sources was rebuilt from sources that could not have changed.
+// The island chunks a container serves, built ONCE inside the image build by
+// `x build --target prebuilt` and read back at boot. Without it every web pod's boot ran
+// `Bun.build` — Babel, the JSX transform, a minifier — for every island, on every start, and a
+// chunk whose URL is a hash of its sources was rebuilt from sources that could not have changed.
 //
 // Load-and-VERIFY, never load-and-trust: a store written by another framework or Bun version, one
 // that names a different set of islands than the app has, or a chunk whose bytes do not hash to
-// what the index recorded is refused, and the boot builds instead — with the reason logged.
+// what the index recorded is refused, and the boot builds instead — and says so.
 
 import { join, relative, sep } from 'node:path'; // why: Bun ships no path-join primitive.
-import { frameworkVersion, logger } from '@ultimat3/core';
+import { frameworkVersion } from '@ultimat3/core';
 import { contentHash, loadStylesheet } from '@ultimat3/render/server';
 import type { IslandBundle, IslandChunk, SharedChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
 import { islandStylesheets } from './island-styles';
+import { PREBUILT_ISLANDS_DIR } from './serve-prebuilt-paths';
 
-/** App-root-relative: `COPY . .` carries it into the image with the rest of `.x/`. */
-export const ISLAND_STORE_DIR = '.x/islands';
+/** App-root-relative, inside the image's prebuilt store (`serve-prebuilt-paths.ts` says why there). */
+export const ISLAND_STORE_DIR = PREBUILT_ISLANDS_DIR;
 const INDEX = 'index.json';
 
 interface StoredChunk {
@@ -200,16 +201,23 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
   return { bundle: islandBundle(chunks, shared) };
 }
 
+/** The container's islands, and — when this boot had to build them — why and how many. */
+export interface LoadedIslands {
+  readonly bundle: IslandBundle;
+  readonly built?: { readonly chunks: number; readonly reason: string };
+}
+
 /**
  * The container's islands: the verified store, or a build when there is none to trust. A build is
- * correct and only slower, so a stale store is a warning with its reason, never a refusal.
+ * correct and only slower, so a stale store is never a refusal — the caller is handed the reason,
+ * and `serve-boot.ts` logs it once with everything else the boot built (`X_IMAGE_NOT_PREBUILT`).
  */
-export async function loadOrBuildIslands(root: string): Promise<IslandBundle> {
+export async function loadOrBuildIslands(root: string): Promise<LoadedIslands> {
   const read = await readIslandStore(root);
-  if (read.bundle !== undefined) return read.bundle;
-  logger.warn('islands built at boot', {
-    reason: read.stale,
-    fix: 'x build --target docker',
-  });
-  return buildIslands(root);
+  if (read.bundle !== undefined) return { bundle: read.bundle };
+  const bundle = await buildIslands(root);
+  return {
+    bundle,
+    built: { chunks: bundle.chunks.length + bundle.shared.length, reason: read.stale },
+  };
 }

package/src/jobs-drain.ts

@@ -2,9 +2,9 @@
 // it is the only command here that WRITES to two drivers at once, and the ordering rule that makes
 // that safe — lease, copy steps, enqueue, then ack — has to be readable in one screen.
 
-import { uuid } from '@ultimat3/core';
-import type { JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
-import { inspectJobList } from '@ultimat3/jobs';
+import { logger, uuid } from '@ultimat3/core';
+import type { ClaimedJob, JobDriver, JobRecord, JobState } from '@ultimat3/jobs';
+import { claimOf, inspectJobList, jobCursor, MAX_JOB_PAGE } from '@ultimat3/jobs';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 
@@ -12,10 +12,10 @@ import { findingFrom } from './output';
 const PENDING_STATES: readonly JobState[] = ['ready', 'delayed', 'suspended'];
 
 /**
- * The lease has to outlive the WHOLE transfer loop, not one record: the batch is claimed up
- * front, and a lease expiring mid-drain would hand a half-transferred job back to a source
- * worker. The snapshot is bounded by the drivers' own 100-row-per-state list cap, so this is a
- * ceiling over a few hundred sequential enqueues rather than a guess about one.
+ * The lease has to outlive the transfer of the whole BATCH it covers: a batch is claimed up front,
+ * and a lease expiring mid-batch would hand a half-transferred job back to a source worker. A
+ * batch is at most `MAX_JOB_PAGE` rows, so this is a ceiling over a couple of hundred sequential
+ * enqueues rather than a guess about however many the queue holds.
  */
 const DRAIN_LEASE_MS = 300_000;
 
@@ -54,19 +54,56 @@ export interface DrainOutcome {
  * left alone. `queues` is always explicit because the pg driver reads an empty list as
  * `['default']` rather than as "every queue".
  */
-function leaseCandidates(
+function leaseBatch(
   source: JobDriver,
   candidates: readonly JobRecord[],
-): Promise<readonly JobRecord[]> {
-  if (candidates.length === 0) return Promise.resolve([]);
+  limit: number,
+): Promise<readonly ClaimedJob[]> {
+  if (candidates.length === 0 || limit <= 0) return Promise.resolve([]);
   return source.claim({
     queues: [...new Set(candidates.map((record) => record.queue))],
-    limit: candidates.length,
+    limit,
     visibilityTimeoutMs: DRAIN_LEASE_MS,
     workerId: `x-jobs-drain:${uuid()}`,
+    // A claim BURIES a row whose lease lapsed on its final attempt, whoever makes it — this one
+    // too. The drain is an operator's tool with no worker context, so it runs no `onSettled`
+    // (at most once across a crash, as documented) and names no `dropExhausted`: said out loud
+    // here, because an unlistened burial is a row that went `dead` with nothing anywhere saying so.
+    onExhausted: (dead) => {
+      for (const row of dead) {
+        logger.error('jobs.claim.exhausted', {
+          workerId: 'x-jobs-drain',
+          job: row.name,
+          jobId: row.id,
+          attempt: row.attempt,
+          maxAttempts: row.maxAttempts,
+          error: row.lastError ?? '',
+        });
+      }
+    },
   });
 }
 
+/**
+ * Every row in `state`, page by page on the keyset cursor until a short page: one page was the
+ * drivers' default 100, so a drain of 350 ready jobs moved 100 and left 250 on the source.
+ */
+async function everyRow(source: JobDriver, state: JobState): Promise<readonly JobRecord[]> {
+  const rows: JobRecord[] = [];
+  let after: string | undefined;
+  for (;;) {
+    const page = await inspectJobList(source, {
+      state,
+      limit: MAX_JOB_PAGE,
+      ...(after === undefined ? {} : { after }),
+    });
+    rows.push(...page);
+    const last = page.at(-1);
+    if (page.length < MAX_JOB_PAGE || last === undefined) return rows;
+    after = jobCursor(last);
+  }
+}
+
 /** Steps carry their own `runId`, so a copy lands under the same key the target job resumes on. */
 async function copySteps(source: JobDriver, target: JobDriver, runId: string): Promise<void> {
   for (const record of await source.steps.list(runId)) await target.steps.put(record);
@@ -82,9 +119,14 @@ async function copySteps(source: JobDriver, target: JobDriver, runId: string): P
  * `countsAsAttempt: false` was the only bit the drivers had and `step.sleep` had claimed it;
  * `NackOptions.park` now carries the suspension, so the two callers no longer share one meaning.
  */
-async function releaseLease(source: JobDriver, id: string): Promise<void> {
+async function releaseLease(source: JobDriver, leased: ClaimedJob): Promise<void> {
   try {
-    await source.nack(id, { delayMs: 0, countsAsAttempt: false });
+    // Fenced on the drain's own claim, like every settle: a lease that lapsed is not handed back.
+    await source.nack(leased.id, {
+      ...claimOf(leased),
+      delayMs: 0,
+      countsAsAttempt: false,
+    });
   } catch {
     // The lease expires on its own. Masking the transfer's real error with this one helps nobody.
   }
@@ -109,18 +151,49 @@ export async function drainJobs(
   target: JobDriver,
   dryRun: boolean,
 ): Promise<DrainOutcome> {
-  const lists = await Promise.all(PENDING_STATES.map((state) => inspectJobList(source, { state })));
+  const lists = await Promise.all(PENDING_STATES.map((state) => everyRow(source, state)));
   const candidates = lists.flat();
   const base = { from: source.name, to: target.name, candidates };
   if (dryRun) return { ...base, dryRun: true, moved: [], skipped: [], failures: [] };
 
-  const leased = await leaseCandidates(source, candidates);
-  const held = new Set(leased.map((record) => record.id));
   const found = new Map(candidates.map((record) => [record.id, record]));
-  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
-
+  const held = new Set<string>();
   const moved: JobRecord[] = [];
   const failures: DrainFailure[] = [];
+  // Batch by batch, each under its own lease, until the claims stop or the snapshot's count is
+  // spent — a claim may lease a row enqueued after the snapshot, and that row spends the budget
+  // too, so a queue that keeps filling cannot keep the drain running.
+  let budget = candidates.length;
+  while (budget > 0) {
+    const leased = await leaseBatch(source, candidates, Math.min(budget, MAX_JOB_PAGE));
+    if (leased.length === 0) break;
+    // A row the target already refused is tried once per drain: handed straight back, spending
+    // no budget and adding no second failure for the same id.
+    const refused = new Set(failures.map((failure) => failure.id));
+    const fresh = leased.filter((record) => !refused.has(record.id));
+    for (const record of leased) if (refused.has(record.id)) await releaseLease(source, record);
+    if (fresh.length === 0) break;
+    budget -= fresh.length;
+    for (const record of fresh) held.add(record.id);
+    const before = moved.length;
+    await transfer(source, target, fresh, found, moved, failures);
+    // A batch that moved nothing handed its leases back, and the next claim would take the same
+    // rows to the same refusing target: stop, and let the failures already counted say why.
+    if (moved.length === before) break;
+  }
+  const skipped = candidates.filter((record) => !held.has(record.id)).map(toSkip);
+  return { ...base, dryRun: false, moved, skipped, failures };
+}
+
+/** One leased batch onto the target: steps, then the job, then the ack — per record. */
+async function transfer(
+  source: JobDriver,
+  target: JobDriver,
+  leased: readonly ClaimedJob[],
+  found: ReadonlyMap<string, JobRecord>,
+  moved: JobRecord[],
+  failures: DrainFailure[],
+): Promise<void> {
   for (const record of leased) {
     let enqueued = false;
     try {
@@ -141,16 +214,17 @@ export async function drainJobs(
       // Only now is the ack the drain's to make: the lease proves no source worker holds this
       // job, and the target already has both the row and its steps. A crash between the two
       // leaves the job live on both drivers, where `idempotencyKey` dedupes it.
-      await source.ack(record.id);
+      // `counted: false`: the row is finished HERE because it left, and a job that was moved is
+      // not a job that completed — it must add nothing to the source's `done` history.
+      await source.ack(record.id, { ...claimOf(record), counted: false });
       // Report the row as the drain FOUND it: `claim()` returns it mid-lease (`running`, one
       // attempt higher), a state nothing on either driver is in once this returns.
       moved.push(found.get(record.id) ?? record);
     } catch (error) {
       // A failed enqueue left nothing on the target, so the lease goes back. A failed ack did
       // not: the job is already live there, and releasing it would race the target's worker.
-      if (!enqueued) await releaseLease(source, record.id);
+      if (!enqueued) await releaseLease(source, record);
       failures.push({ id: record.id, name: record.name, finding: findingFrom(error) });
     }
   }
-  return { ...base, dryRun: false, moved, skipped, failures };
 }

package/src/jobs-json.ts

@@ -7,9 +7,11 @@ import type {
   DeadLetterEntry,
   JobRecord,
   JobTrace,
+  PausedName,
   QueueDepthReport,
   QueueStats,
   StepTrace,
+  WorkerRecord,
 } from '@ultimat3/jobs';
 import type { DrainFailure, DrainSkip } from './jobs-drain';
 import type { JsonValue } from './output';
@@ -59,15 +61,61 @@ export function jobTraceToJson(trace: JobTrace): JsonValue {
     runId: trace.runId,
     runAt: trace.runAt,
     lastError: trace.lastError,
+    // The failure's stack, bounded by the queue. `null` when the thrown value carried none.
+    stack: trace.stack,
+    // The payload with every key the app declared secret already replaced (`redactInput`), so it
+    // is the queue's promise that this is safe to print — never this file's.
+    input: toJson(trace.input),
+    progress:
+      trace.progress === null
+        ? null
+        : {
+            done: trace.progress.done,
+            total: trace.progress.total,
+            note: trace.progress.note ?? null,
+            at: trace.progress.at,
+          },
     tenantId: trace.tenantId,
     steps: trace.steps.map(stepTraceToJson),
     retryDelaysMs: trace.retryDelaysMs.map((ms) => ms),
+    // `concurrency.key(input)` for a keyed job, `null` for every other: which lease this run waits on.
+    concurrencyKey: trace.concurrencyKey,
     // `null` for every job that is not a `backfill()` pass. Dropped, `x jobs show <id> --json`
     // would answer "how far has it got" with silence for the one job kind that can say.
     backfill: trace.backfill === null ? null : backfillToJson(trace.backfill),
   };
 }
 
+/**
+ * An app payload as plain JSON. A round trip through the serialiser is the proof: whatever a
+ * payload held that JSON cannot carry — a bigint, a function, a cycle — degrades to `null` rather
+ * than failing the command that was asked to show it.
+ */
+function toJson(value: unknown): JsonValue {
+  try {
+    const text: string | undefined = JSON.stringify(value);
+    return text === undefined ? null : (JSON.parse(text) as JsonValue);
+  } catch {
+    return null;
+  }
+}
+
+export function pausedToJson(paused: PausedName): JsonValue {
+  return { name: paused.name, pausedAt: paused.pausedAt };
+}
+
+export function workerToJson(worker: WorkerRecord): JsonValue {
+  return {
+    id: worker.id,
+    host: worker.host,
+    startedAt: worker.startedAt,
+    heartbeatAt: worker.heartbeatAt,
+    queues: [...worker.queues],
+    concurrency: worker.concurrency,
+    inFlight: [...worker.inFlight],
+  };
+}
+
 /**
  * `input` is deliberately excluded: it is `unknown` at the driver boundary (an app-defined
  * payload, not something this package can prove is JSON-safe), and `JobTrace` already sets the
@@ -100,6 +148,7 @@ function queueStatsToJson(stats: QueueStats): JsonValue {
     delayed: stats.delayed,
     running: stats.running,
     suspended: stats.suspended,
+    failed: stats.failed,
     dead: stats.dead,
     oldestReadyMs: stats.oldestReadyMs,
   };
@@ -114,6 +163,7 @@ export function depthToJson(depth: QueueDepthReport): JsonValue {
       delayed: depth.totals.delayed,
       running: depth.totals.running,
       suspended: depth.totals.suspended,
+      failed: depth.totals.failed,
       dead: depth.totals.dead,
     },
     oldestReadyMs: depth.oldestReadyMs,

package/src/jobs-report.ts

@@ -72,6 +72,8 @@ export interface JobsListFilter {
   readonly state?: string | undefined;
   readonly name?: string | undefined;
   readonly limit?: string | undefined;
+  /** `jobCursor(lastRow)` of the page before — the keyset the next page seeks from. */
+  readonly after?: string | undefined;
 }
 
 export interface JobsListResult {
@@ -103,6 +105,7 @@ export async function listJobs(
     ...(filter.name === undefined ? {} : { name: filter.name }),
     ...(state === undefined ? {} : { state }),
     ...(limit === undefined ? {} : { limit }),
+    ...(filter.after === undefined ? {} : { after: filter.after }),
   };
   const [depth, rows, deadLetters, backfills] = await Promise.all([
     inspectQueues(driver),
@@ -124,10 +127,10 @@ export async function showJob(driver: JobDriver, id: string): Promise<JobTrace>
 // ── retry ─────────────────────────────────────────────────────────────────
 
 /**
- * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: the
- * concrete drivers (pg, memory) throw their own error from inside `requeue()` for a missing
- * row, and that error is not this command's contract — `retryFromStep`'s documented `undefined`
- * return is, and the driver never reaches it once the row is already known absent.
+ * Existence is checked up front so an unknown id always surfaces as `X_JOB_UNKNOWN`: both
+ * drivers answer `X_JOB_NOT_FOUND` from inside `requeue()` for a missing row, and that code is
+ * the driver's contract, not this command's — `retryFromStep`'s documented `undefined` return
+ * is, and the driver never reaches it once the row is already known absent.
  */
 export async function retryJob(
   driver: JobDriver,