@ultimat3/cli 19.2.0 → 19.3.2

package/src/sw-artifacts.ts

@@ -50,15 +50,41 @@ export interface ServiceWorkerInput {
    * the offline fallback with no CSS is a page the visitor cannot read.
    */
   readonly styles: StyleBundle;
+  /**
+   * What the build RENDERED, keyed by the route path it was rendered for. Optional because only a
+   * static export has documents to hash: `x dev` and the container emit the worker at boot, where
+   * no page has been built yet, and `buildPrecacheManifest` falls back to the build id for a route
+   * this map does not name.
+   */
+  readonly documents?: ReadonlyMap<string, RenderedDocument>;
+}
+
+/**
+ * One rendered document, as the precache manifest needs it.
+ *
+ * `revision` is `contentHash(html)` — `@ultimat3/render`'s own, the function that already stamps
+ * an ETag — and never the build id. `precache.ts`' header states the rule and nothing kept it:
+ * `pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+ * `{"url":"/","revision":"build-aaa","bytes":0}` and two deploys of a byte-identical site
+ * re-fetched every precached document. The zero was the second half — `DEFAULT_PRECACHE_WARN_BYTES`
+ * is a 5 MB budget over a total that could not count one byte of HTML.
+ */
+export interface RenderedDocument {
+  readonly revision: string;
+  readonly bytes: number;
 }
 
 /**
  * The route table, as the service worker sees it. `api/` is dropped: an API response is a JSON
  * document whose freshness is the app's business, and precaching one serves a stale answer to a
- * client that had a network. Only the four fields `PwaRoute` reads cross — a descriptor carries
- * budgets and policy flags that a browser has no use for.
+ * client that had a network. Only the fields a browser can act on cross — a descriptor carries
+ * budgets and policy flags it has no use for — plus, for a route this build rendered, the content
+ * hash and the byte count of the document it produced.
  */
-const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
+const pwaRoutes = (
+  routes: readonly RouteDescriptor[],
+  documents: ReadonlyMap<string, RenderedDocument>,
+): readonly PwaRoute[] =>
   // `flatMap` rather than `filter().map()`: the filter's predicate does not narrow `surface` for
   // the map that follows it, and `PwaRoute` declares the two navigable surfaces only. A cast would
   // hide the day a fifth surface arrives.
@@ -66,6 +92,8 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
     // `shared/` is dropped with `api/`, and for a stronger reason: it is not a URL at all — the
     // surface exists so two routes can import one module, and a browser can never navigate to it.
     if (route.surface !== 'site' && route.surface !== 'app') return [];
+    // A `Map`, so a route path that happens to spell a prototype member cannot answer with one.
+    const document = documents.get(route.path);
     return [
       {
         path: route.path,
@@ -73,6 +101,10 @@ const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
         mode: route.mode,
         offline: route.offline,
         dynamic: route.dynamic,
+        // Absent rather than invented for a route no build rendered — an `ssr` page, or one this
+        // pass could not produce. `buildPrecacheManifest` then falls back to the build id, which
+        // is the honest answer when there are no bytes to hash.
+        ...(document === undefined ? {} : { revision: document.revision, bytes: document.bytes }),
       },
     ];
   });
@@ -128,14 +160,34 @@ export function serviceWorkerArtifacts(
   input: ServiceWorkerInput,
 ): ServiceWorkerArtifacts | undefined {
   const pwa = input.pwa;
-  if (pwa.offline.fallback === null) return undefined;
+  const head = serviceWorkerHead(pwa);
+  const fallback = pwa.offline.fallback;
+  // One predicate DECIDES — `serviceWorkerHead`, so a document can never name a script this
+  // function then declines to emit — and the `null` check is what NARROWS `fallback` below:
+  // TypeScript cannot learn a `string` from the other's answer, and a cast would hide the day the
+  // two stop agreeing.
+  if (head === undefined || fallback === null) return undefined;
+  const documents = input.documents ?? new Map<string, RenderedDocument>();
+  // The offline document is the one entry `buildPrecacheManifest` adds ITSELF, as
+  // `reason: 'fallback'`, ahead of every route — and `add()` keeps the first entry per url, so its
+  // revision is the one that decides. Without this pair it was the build id whatever the build
+  // knew, which re-downloaded the single page an offline navigation depends on on every deploy.
+  // Absent when this pass did not render the fallback (no route serves it — `x doctor` reports
+  // that as `X_PWA_NO_OFFLINE_FALLBACK`), and then `@ultimat3/pwa` falls back to the build id.
+  const fallbackDocument = documents.get(fallback);
   const output = generateServiceWorker(
-    pwaRoutes(input.routes),
+    pwaRoutes(input.routes, documents),
     {
       scope: SW_SCOPE,
       swPath: SERVICE_WORKER_PATH,
+      ...(fallbackDocument === undefined
+        ? {}
+        : {
+            offlineFallbackRevision: fallbackDocument.revision,
+            offlineFallbackBytes: fallbackDocument.bytes,
+          }),
       offline: {
-        fallback: pwa.offline.fallback,
+        fallback,
         ...(pwa.offline.image === null ? {} : { image: pwa.offline.image }),
         ...(pwa.offline.font === null ? {} : { font: pwa.offline.font }),
         neverCache: pwa.offline.neverCache,
@@ -148,7 +200,7 @@ export function serviceWorkerArtifacts(
   return {
     source: output.source,
     register: registerSource(),
-    head: `<script src="${SW_REGISTER_PATH}" defer></script>`,
+    head,
     precache: output.precache,
     // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
     // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
@@ -160,6 +212,18 @@ export function serviceWorkerArtifacts(
   };
 }
 
+/**
+ * The one `<script src>` a document needs, or `undefined` for an app that gets no worker.
+ *
+ * Separate from `serviceWorkerArtifacts` because the two are wanted at different moments: a static
+ * export has to put this tag in every document it renders, and the WORKER cannot be emitted until
+ * those documents exist — its precache manifest is built from their content hashes. One predicate
+ * for both (`offline.fallback === null` is `generateServiceWorker`'s refusal, spent early), so a
+ * document can never name a script the export does not carry.
+ */
+export const serviceWorkerHead = (pwa: PwaArtifacts): string | undefined =>
+  pwa.offline.fallback === null ? undefined : `<script src="${SW_REGISTER_PATH}" defer></script>`;
+
 /**
  * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
  * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently

package/src/templates/action.ts

@@ -5,12 +5,25 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
-import { sliceFoundation } from './slice-foundation';
+import { sliceExports, sliceFoundation } from './slice-foundation';
 import { wrapImport } from './wrap';
 
+/**
+ * The handler's lookup-by-id, or the comment that says what a slice needs before it can have one.
+ * `x g resource` writes a slice whose `errors.ts` declares `<Feature>NotFoundError`, and so does
+ * the foundation this generator lays under an empty directory; a slice an author wrote by hand
+ * (ai-maxxing's `fleet`, with `HostNotFoundError` and `SessionNotFoundError`) declares the errors
+ * it has and not this one. Importing it anyway is a file that fails at import.
+ */
+const missingLookup = (feature: NameSet): string =>
+  `    // No lookup by id: ../errors declares no ${feature.pascal}NotFoundError, and a row that is not
+    // there needs one to be thrown for it. Declare it there — the shape \`x g resource\` writes —
+    // then read the row through ../repo and throw it when the read answers nothing.`;
+
 const actionSource = (
   name: NameSet,
   feature: NameSet,
+  lookup: boolean,
 ): string => `// ${name.camel}: one mutation, server-authoritative. Input is validated before the handler runs
 // and the policy is the same object the MCP tool and the HTTP route evaluate.
 // \`t\` comes from @ultimat3/action, not @ultimat3/schema: an action file imports one package.
@@ -18,23 +31,25 @@ const actionSource = (
 import { action, t } from '@ultimat3/action';
 // One directory up: actions live in \`actions/\`, the feature's errors, policy and repo are the
 // slice's own files and are shared by every action in it.
-
-import { ${feature.pascal}NotFoundError } from '../errors';
-${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
-import * as repo from '../repo';
-
+${lookup ? `\nimport { ${feature.pascal}NotFoundError } from '../errors';\n` : ''}${wrapImport([`can${feature.pascal}Write`, `${feature.camel}Tag`], '../policy')}
+${lookup ? "import * as repo from '../repo';\n" : ''}
 export const ${name.camel} = action({
   // orgId is part of the input because the policy decides on it — authz reads the declaration,
   // never the database.
   input: t.object({ id: t.uuid, orgId: t.uuid }),
-  output: t.object({ id: t.uuid, title: t.string }),
+  output: t.object({ id: t.uuid${lookup ? ', title: t.string' : ''} }),
   policy: can${feature.pascal}Write,
   cache: { invalidates: [${feature.camel}Tag] },
   mcp: { expose: true, description: '${name.raw} — edit this description' },
   async handle({ input }) {
-    const row = await repo.byId(input.id);
+${
+  lookup
+    ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
-    return { id: row.id, title: row.title };
+    return { id: row.id, title: row.title };`
+    : `${missingLookup(feature)}
+    return { id: input.id };`
+}
   },
 });
 `;
@@ -42,14 +57,13 @@ export const ${name.camel} = action({
 const mutatorSource = (
   name: NameSet,
   feature: NameSet,
+  lookup: boolean,
 ): string => `// ${name.camel}: an action with an optimistic local twin. The local half runs against the client
 // store immediately; the server half is authoritative and reconciles on conflict.
 
 import { mutator, t } from '@ultimat3/action';
-import { ${feature.pascal}NotFoundError } from '../errors';
-import { can${feature.pascal}Write } from '../policy';
-import * as repo from '../repo';
-
+${lookup ? `import { ${feature.pascal}NotFoundError } from '../errors';\n` : ''}import { can${feature.pascal}Write } from '../policy';
+${lookup ? "import * as repo from '../repo';\n" : ''}
 interface Local${feature.pascal} {
   readonly id: string;
   readonly title: string;
@@ -71,9 +85,14 @@ export const ${name.camel} = mutator({
     });
   },
   async server(_ctx, input) {
-    const row = await repo.byId(input.id);
+${
+  lookup
+    ? `    const row = await repo.byId(input.id);
     if (row === undefined) throw new ${feature.pascal}NotFoundError({ id: input.id });
-    return { id: row.id, title: input.title };
+    return { id: row.id, title: input.title };`
+    : `${missingLookup(feature)}
+    return { id: input.id, title: input.title };`
+}
   },
   conflict: 'server-wins',
 });
@@ -181,6 +200,13 @@ contractTest('${name.camel} projects one tool and one operation', () => {
 
 export interface ActionOptions extends FeatureTarget {
   readonly mutator?: boolean;
+  /**
+   * The slice's `errors.ts` as it stands on disk, or absent when the slice has none yet. Absent,
+   * the foundation writes one declaring `<Feature>NotFoundError` and the action may throw it;
+   * present, the file is the author's and is never rewritten, so the action throws it only when
+   * `sliceExports` finds it there.
+   */
+  readonly sliceErrors?: string;
 }
 
 export function actionFiles(rawName: string, target: ActionOptions): readonly GeneratedFile[] {
@@ -188,6 +214,9 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
   const feature = names(target.feature);
   const dir = `${target.surfaceDir}/${target.feature}/actions`;
   const isMutator = target.mutator === true;
+  const lookup =
+    target.sliceErrors === undefined ||
+    sliceExports(target.sliceErrors, `${feature.pascal}NotFoundError`);
   return [
     // The three slice modules this action's source imports — `../errors`, `../policy`, `../repo`
     // (which comes with `../entity`, its row type). Composed rather than assumed: `x g action`
@@ -195,7 +224,9 @@ export function actionFiles(rawName: string, target: ActionOptions): readonly Ge
     ...sliceFoundation(target, ['entity', 'policy', 'errors']),
     {
       path: `${dir}/${name.kebab}.ts`,
-      contents: isMutator ? mutatorSource(name, feature) : actionSource(name, feature),
+      contents: isMutator
+        ? mutatorSource(name, feature, lookup)
+        : actionSource(name, feature, lookup),
     },
     // TWO test files, because the gate types a test by its FILENAME and this declaration owes two
     // suites: the input parse is a `unit` assertion and the three projections are `contract` ones.

package/src/templates/admin-page.ts

@@ -9,6 +9,7 @@ import { sortedImports } from './imports';
 import { catalogPath, resolveLocales } from './locales';
 import type { GeneratedFile } from './naming';
 import { camel, kebab, pascal } from './naming';
+import { LINE_WIDTH } from './wrap';
 
 /** Where an admin lives when the caller does not say. `x new` scaffolds this layout. */
 export const DEFAULT_ADMIN_PAGE_DIR = 'apps/admin/src/pages';
@@ -58,9 +59,45 @@ const catalogImport = (module: string | undefined): string =>
 const pageImports = (module: string | undefined): string =>
   sortedImports([
     `import type { AdminCustomPage, AdminPageProps } from '@ultimat3/admin';`,
+    `import { definePermissions } from '@ultimat3/policy';`,
     catalogImport(module),
   ]);
 
+/**
+ * The page DECLARES the permission it requires, in both registries that decide about it.
+ *
+ * `x g admin:page ops` emitted `permissions: ['ops:read']` and nothing anywhere declared
+ * `ops:read`, so `assertPermission` threw X_PERMISSION_UNKNOWN on the first request that reached
+ * the page: a screen the generator built and no actor can open. Nothing catches it either — the
+ * gate's `policy` step reads `roleDefinitions()` and `routeEntries()`, and an admin page is
+ * neither a role nor a route, so `x verify` is green over it.
+ *
+ * Here rather than in a `policy.ts` beside it, because registration is a side effect of IMPORT and
+ * `pages:` already imports this module: a declaration in a file the admin does not import is a
+ * declaration that never runs. `declare module` is the type half — `can()`'s key type reads the
+ * registry, not the `definePermissions` call — and merging an identical member is what lets an app
+ * that already declares this permission keep its own declaration.
+ */
+const declarePermissions = (name: string, permission: string): string => {
+  const line = `export const ${camel(name)}PagePermissions = definePermissions(['${permission}']);`;
+  // Emitted PRE-formatted, because a template cannot run one: past 100 columns biome rewrites this
+  // call across four lines, and `x new zebra`-class names reach it (`emitted-contract.test.ts`
+  // varies both the length and the first letter for exactly this reason).
+  return line.length <= LINE_WIDTH
+    ? line
+    : `export const ${camel(name)}PagePermissions = definePermissions([\n  '${permission}',\n]);`;
+};
+
+const permissionDeclaration = (name: string, permission: string): string => `
+declare module '@ultimat3/policy' {
+  interface PermissionRegistry {
+    '${permission}': true;
+  }
+}
+
+${declarePermissions(name, permission)}
+`;
+
 /** `useT()` is per render, so the component binds it in its own body. */
 const translatorBinding = (module: string | undefined): string =>
   module === undefined ? '' : '\n  const t = useT();\n';
@@ -81,9 +118,12 @@ const pageSource = (
 // so the specifier is relative to wherever \`defineAdmin\` lives:
 //   import { ${declaration}Page } from './${name}';
 //   defineAdmin({ …, pages: […, ${declaration}Page] })
+//
+// The permission below is declared here AND has to be decided: an authz map built from a fixed
+// list must name '${permission}' too, or a declared permission is still denied for everyone.
 
 ${pageImports(module)}
-
+${permissionDeclaration(name, permission)}
 export function ${Name}Page(props: AdminPageProps) {${translatorBinding(module)}
   return (
     <section>
@@ -108,6 +148,7 @@ const pageTest = (name: string, permission: string): string => {
   const declaration = camel(name);
   return `// The ${name} admin page is guarded and owns no route of its own — the two facts that separate an
 // admin screen from a page, and the two an edit here is most likely to break.
+import { knownPermissions } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { ${declaration}Page } from './${name}';
 
@@ -119,6 +160,13 @@ unitTest('the ${name} admin page is rooted and guarded', () => {
   expect(${declaration}Page.permissions).toContain('${permission}');
 });
 
+// A \`permissions:\` entry no \`definePermissions()\` declares is X_PERMISSION_UNKNOWN on the first
+// request that reaches the page — a screen this generator built and nobody can open. Importing the
+// page above is what registers it, which is why the declaration lives in that file and not beside it.
+unitTest('the ${name} admin page declares its permission', () => {
+  expect(knownPermissions()).toContain('${permission}');
+});
+
 unitTest('the ${name} admin page declares no route of its own', () => {
   // \`pages:\` is the only way in. A \`config\` export here would be a route the frame never guards.
   expect('config' in ${declaration}Page).toBe(false);

package/src/templates/island.ts

@@ -71,9 +71,11 @@ function ${Name}(props: ${Name}Props): JSX.Element {
  * container already has children, so without it the server's markup stays on screen above a
  * second, live copy of the same thing.
  */
-export function mount(el: HTMLElement, props: ${Name}Props): void {
+export function mount(el: HTMLElement, props: ${Name}Props): () => void {
   el.textContent = '';
-  render(() => <${Name} {...props} />, el);
+  // Solid's \`render\` answers its disposer; returning it is what lets \`mountIsland\` in
+  // \`@ultimat3/testing\` stop this island — its timers included — when a test is done with it.
+  return render(() => <${Name} {...props} />, el);
 }
 `;
 };

package/src/templates/scaffold-container.ts

@@ -6,6 +6,7 @@
 // run-to-completion migrate step are conventions every container platform shares — a Heroku
 // buildpack, a Render blueprint or a fly.toml would be the primitive that never ships.
 
+import { SECRETS_KEY_FILE } from '@ultimat3/core';
 import type { GeneratedFile, NameSet } from './naming';
 import { helmFiles } from './scaffold-helm';
 
@@ -81,6 +82,12 @@ ENTRYPOINT ["bun", "apps/web/server.ts"]
  * tells the operator to create, in its own `env_file:` — nor `.env.development`, and both landed in
  * an image layer that `cache-to=mode=max` then pushes to a shared cache. Same four lines the
  * framework's own `docker/Dockerfile.dockerignore` carries, and for the same reason.
+ *
+ * The key file is interpolated from `SECRETS_KEY_FILE` rather than written out, because the
+ * constant is what `findMasterKey` reads: a rename would otherwise leave every app this generator
+ * has ever produced ignoring a filename nothing writes, which reads as a rule still in force.
+ * `scripts/image-contract.ts` holds every ignore file IN THIS TREE to the same line; a generated
+ * app's copy is this template's, and `scaffold-container.test.ts` is where it is judged.
  */
 const dockerignore = (): string => `**/.env
 **/.env.*
@@ -88,6 +95,11 @@ const dockerignore = (): string => `**/.env
 # Same shape, different file: an .npmrc carries a registry auth token, so any that exists in a
 # build context is somebody's local credential and has no business in a layer.
 **/.npmrc
+# Same shape, and this one is the key itself: ${SECRETS_KEY_FILE} decrypts the committed
+# secrets.enc.json beside it, and findMasterKey falls back to the file whenever
+# ULTIMATE_SECRETS_KEY is unset — so a baked copy boots the image on it and the platform's key is
+# never exercised.
+**/${SECRETS_KEY_FILE}
 
 node_modules
 **/node_modules

package/src/templates/scaffold-docs.ts

@@ -4,6 +4,7 @@
 // ignore file, the production topology and the deploy page are `scaffold-container.ts`; the
 // `.claude/` harness that reads AGENTS.md is `scaffold-claude.ts`.
 
+import { LINE_CEILING } from '../workspace-checks';
 import type { GeneratedFile, NameSet } from './naming';
 import { claudeFiles } from './scaffold-claude';
 import { containerFiles } from './scaffold-container';
@@ -27,10 +28,16 @@ not exist — five of these had an empty column and were each measured green on
 | Time | store UTC, format with an explicit IANA time zone | \`guards/unzoned-date.ts\` |
 | Strings | every user-facing string goes through \`t()\` | \`guards/untranslated-string.ts\` |
 | Colour | semantic tokens only, never a raw hex | \`guards/raw-colour.ts\` |
+| Size | one file, one job — ${LINE_CEILING} lines of reviewable logic, and split past it | \`X_FILE_TOO_LONG\` |
 
 \`guards/\` is yours: each file is one rule, discovered by \`x verify\` and run inside its
 \`boundaries\` step. Delete one to drop the rule, and \`x g guard <name>\` writes the next.
 
+Size is a hard line and not a style note: past ${LINE_CEILING} lines a file has stopped being the
+unit of review, and \`x verify\` refuses it. The one exemption is a file that is nothing but re-exports —
+it has one job by construction, and its length tracks the API's size rather than its complexity;
+one statement of logic in such a file re-arms the ceiling on the same save.
+
 Money is the one row with no guard, deliberately: a float has no static signature a text rule can
 see, and the type already fires — measured, \`price: 19.99\` in a seed is
 \`TS2322: Type 'number' is not assignable to type 'MoneyInput'\`. A guard that pretended to check

package/src/templates/scaffold-entries.ts

@@ -9,8 +9,10 @@ import type { GeneratedFile } from './naming';
 const server =
   (): string => `// The production entry. \`docker/Dockerfile\` starts this, and \`x build --target binary\` compiles it.
 // ROLE selects what this process is — web, sync, worker, scheduler, replicator, or migrate, which
-// applies the migrations and exits. PORT is bound on every interface, because a container bound to
-// localhost is unreachable through its own port mapping.
+// applies the migrations and exits. PORT is bound on HOST, and HOST defaults to every interface,
+// because a container bound to loopback is unreachable through its own port mapping. HOST=127.0.0.1
+// is for a process that must never answer a public interface: reachable only where the container
+// shares the host's network namespace (\`--network host\`), or through a sidecar and \`ssh -L\`.
 
 import { join } from 'node:path';
 import { runRole } from '@ultimat3/cli';

package/src/templates/scaffold-repo.ts

@@ -333,13 +333,18 @@ declare module '*.scss' {
 }
 `;
 
+// Build output is ROOT-ANCHORED, and that is not cosmetic: an unanchored `dist/` or `coverage/`
+// matches a directory of that name at ANY depth, so `apps/web/site/dist/page.tsx` — an app's own
+// `/dist` route, the directory IS the URL — was a file git refused to commit and `x dev` refused to
+// reload. `packages/*/dist/` keeps a workspace's build output ignored without reaching a surface.
 const gitignore = (): string => `node_modules/
 .x/
-dist/
+/dist/
+packages/*/dist/
 *.tsbuildinfo
 .env
 .env.*.local
-coverage/
+/coverage/
 playwright-report/
 test-results/
 `;

package/src/templates/slice-foundation.ts

@@ -3,6 +3,7 @@
 // `policyFiles`; the five generators that write *into* a slice imported the same files and wrote
 // none of them, so each emitted TS2307 in any slice a resource had not been run in first.
 
+import { stripComments } from '../ts-scan';
 import type { FeatureTarget } from './entity';
 import { entityFiles } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
@@ -84,3 +85,38 @@ export function sliceFoundation(
       : []),
   ]);
 }
+
+/** The exported names an `export { a, b as c }` list declares — `c`, never `b`. */
+const listedExports = (code: string): readonly string[] =>
+  [...code.matchAll(/\bexport\s*\{([^}]*)\}/g)].flatMap((match) =>
+    (match[1] ?? '')
+      .split(',')
+      .map(
+        (entry) =>
+          entry
+            .trim()
+            .split(/\s+as\s+/)
+            .at(-1)
+            ?.trim() ?? '',
+      )
+      .filter((entry) => entry !== ''),
+  );
+
+/**
+ * Whether `source` — a slice module as it stands on the app's disk — exports the VALUE `name`.
+ * Read at generation time because assuming it was measured: `x g action` into ai-maxxing's
+ * `fleet` slice wrote `import { FleetNotFoundError } from '../errors'` into a slice whose
+ * `errors.ts` declared `HostNotFoundError` and `SessionNotFoundError` and no `FleetNotFoundError`.
+ * The file failed at import — and because `x db gen` and `x manifest` load every module, one
+ * generated-and-not-yet-edited action made both refuse to run.
+ *
+ * Comments are masked first: `// TODO: add FleetNotFoundError` is not an export. A `type` or an
+ * `interface` of that name is not one either — the generated code constructs it.
+ */
+export function sliceExports(source: string, name: string): boolean {
+  const code = stripComments(source);
+  const declared = new RegExp(
+    `\\bexport\\s+(?:abstract\\s+)?(?:class|const|let|var|function|enum)\\s+${name}\\b`,
+  );
+  return declared.test(code) || listedExports(code).includes(name);
+}

package/src/test-passes.ts

@@ -0,0 +1,79 @@
+// Which of a selection's files may share a worker pool, and which may not. `--parallel=N` is the
+// width of the WHOLE run, so a selection holding a `live` or an `e2e` file is more than one run —
+// this file decides how many, and `test-shards.ts` spends them.
+
+import type { TestFile } from './test-select';
+import type { TestType } from './verify-tests';
+import { ownerOf, SERIAL_TYPES } from './verify-tests';
+
+/** One `bun test` invocation: which files, how wide, and the type its reproduce line names. */
+export interface TestPass {
+  readonly files: readonly TestFile[];
+  readonly workers: number;
+  /**
+   * The type this pass is exactly the selection of, when it is one — so a failure's `fix:` names
+   * `x test live --workers 1` and reruns THESE files, not the whole corpus at this width.
+   */
+  readonly type?: TestType;
+}
+
+export interface PassInput {
+  readonly files: readonly TestFile[];
+  /** What the caller asked for, already bounded by `--workers`' own reader. */
+  readonly workers: number;
+  /** The positional, when there was one. A pass over one type keeps it; the split never adds one. */
+  readonly type?: TestType;
+  /** Set for a `--worker I` rerun, which is one process by construction. */
+  readonly shard?: number;
+}
+
+const widthFor = (files: readonly TestFile[], workers: number): number =>
+  Math.max(1, Math.min(Math.trunc(workers), files.length || 1));
+
+/**
+ * The passes one invocation becomes. One, for every selection that holds no serial file — which
+ * is every `x test unit`, every `--filter` over a feature's contract tests, and the whole corpus
+ * of an app that has neither.
+ *
+ * `live` and `e2e` are the exception, and `verify-tests.ts` owns both the list and the reasons: a
+ * logical replication slot is named at the Postgres CLUSTER level so a per-worker database does
+ * not isolate it, and `e2e` shares one `dist/` and one browser profile. `x verify` has routed them
+ * through `runSerial` since 2026-08 while `x test` clamped on the POSITIONAL alone — so a bare
+ * `x test --workers 8` ran the very files the gate runs one at a time, eight at a time, and only
+ * a real `TEST_DATABASE_URL` makes that visible.
+ *
+ * Each serial type is its own pass rather than one pass over both, because the pass's `type` is
+ * what its failure reproduces with: `x test live --workers 1` selects exactly the files that ran.
+ *
+ * A `--worker I` rerun is left whole: it is a single `bun test --isolate --shard=i/N` process, so
+ * nothing inside it runs beside anything else, and splitting it would make shard i of the rerun a
+ * different set of files from shard i of the run it reproduces.
+ */
+export function testPasses(input: PassInput): readonly TestPass[] {
+  const serialTypes = new Set<TestType>(SERIAL_TYPES);
+  if (input.shard !== undefined) {
+    return [
+      {
+        files: input.files,
+        workers: widthFor(input.files, input.workers),
+        ...(input.type === undefined ? {} : { type: input.type }),
+      },
+    ];
+  }
+  const shared = input.files.filter((file) => !serialTypes.has(ownerOf(file.path)));
+  const passes: TestPass[] = [];
+  // Cheapest first, and the widest first: the pool run is most of the corpus and most of the
+  // signal, and a serial suite that needs a database is the one a laptop is least likely to have.
+  if (shared.length > 0) {
+    passes.push({
+      files: shared,
+      workers: widthFor(shared, input.workers),
+      ...(input.type === undefined ? {} : { type: input.type }),
+    });
+  }
+  for (const type of SERIAL_TYPES) {
+    const files = input.files.filter((file) => ownerOf(file.path) === type);
+    if (files.length > 0) passes.push({ files, workers: 1, type });
+  }
+  return passes;
+}