@ultimat3/cli 22.2.2 → 22.3.0

package/src/site-asset-routes.ts

@@ -0,0 +1,106 @@
+// Serving `apps/web/site/assets/**` at the hashed URLs `asset()` mints. Mounted by `assetRoutes`,
+// which both `x dev` and the container compose, so a picture that paints on a laptop paints in the
+// image. Byte ranges are answered because Safari will not play an `<video>` from a server that
+// ignores `Range`, and a film that plays everywhere but an iPhone is not a film that ships.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders, json } from '@ultimat3/http';
+import type { SiteAsset, SiteAssetTable } from './site-assets';
+import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
+
+/** The URL is the content, so the answer is `public, max-age=31536000, immutable`. */
+export const SITE_ASSET_CACHE: CacheHint = { mode: 'immutable' };
+
+const notFound = (code: string, cause: string, fix: string): Response =>
+  json({ ok: false, error: { code, cause, fix } }, { status: 404 });
+
+/** One `bytes=` range, resolved against the file's size; `null` when it cannot be satisfied. */
+export function byteRange(
+  header: string | null,
+  size: number,
+): { readonly start: number; readonly end: number } | null | undefined {
+  if (header === null) return undefined;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  // A multi-range or a unit we do not speak: RFC 9110 lets a server ignore Range and send it all.
+  if (match === null) return undefined;
+  const [, from = '', to = ''] = match;
+  if (from === '' && to === '') return null;
+  if (from === '') {
+    const suffix = Number(to);
+    if (suffix === 0) return null;
+    return { start: Math.max(0, size - suffix), end: size - 1 };
+  }
+  const start = Number(from);
+  const end = to === '' ? size - 1 : Math.min(Number(to), size - 1);
+  if (start >= size || end < start) return null;
+  return { start, end };
+}
+
+function assetResponse(asset: SiteAsset, range: string | null): Response {
+  const file = Bun.file(asset.file);
+  const headers: Record<string, string> = {
+    'content-type': asset.contentType,
+    'accept-ranges': 'bytes',
+  };
+  const wanted = byteRange(range, asset.bytes);
+  if (wanted === null) {
+    return new Response(null, {
+      status: 416,
+      headers: { ...headers, 'content-range': `bytes */${String(asset.bytes)}` },
+    });
+  }
+  if (wanted === undefined) {
+    return applyCacheHeaders(new Response(file, { headers }), SITE_ASSET_CACHE);
+  }
+  return applyCacheHeaders(
+    new Response(file.slice(wanted.start, wanted.end + 1), {
+      status: 206,
+      headers: {
+        ...headers,
+        'content-range': `bytes ${String(wanted.start)}-${String(wanted.end)}/${String(asset.bytes)}`,
+      },
+    }),
+    SITE_ASSET_CACHE,
+  );
+}
+
+/**
+ * Only the HASHED name is served, and only while the bytes still hash to it: an immutable answer
+ * under a URL whose bytes changed would be cached for a year by every CDN that saw it. A stale
+ * hash is a document from an earlier build, and says so.
+ */
+export function siteAssetRoutes(table: SiteAssetTable): readonly Route[] {
+  return [
+    {
+      method: 'GET',
+      path: `${SITE_ASSET_BASE_PATH}/*file`,
+      meta: { name: 'assets.site', auth: 'public', tags: ['assets'] },
+      handler: (request: UltimateRequest): Response => {
+        const named = parseHashedAssetUrl(request.pathname);
+        if (named === undefined) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${request.pathname} is not a hashed site asset URL`,
+            "name the file with asset('assets/…') in the page, which returns the URL this route serves",
+          );
+        }
+        let asset: SiteAsset;
+        try {
+          asset = table.resolve(named.path);
+        } catch (error) {
+          if (!isUltimateError(error)) throw error;
+          return notFound(error.code, error.cause, error.fix);
+        }
+        if (asset.hash !== named.hash) {
+          return notFound(
+            'X_ROUTE_NOT_FOUND',
+            `${named.path} is at ${asset.url} now — the document asking for ${request.pathname} was rendered against earlier bytes`,
+            'reload the page; it names the current URL',
+          );
+        }
+        return assetResponse(asset, request.headers.get('range'));
+      },
+    },
+  ];
+}

package/src/site-assets.ts

@@ -0,0 +1,177 @@
+// The site asset table: every file under `apps/web/site/assets/`, named by a content-hashed URL.
+// One table per app root answers all three questions — the URL `asset()` returns while a page
+// renders, the file `/assets/*` serves, and the copy `x build --target static` writes — so the
+// page, the container and the CDN can never name one file three ways.
+
+// why: `asset()` is called from a synchronous render, so the table answers synchronously — and Bun
+// ships no sync stat or sync read; `join`/`relative` because Bun ships no path API either.
+import { copyFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path'; // why: Bun ships no path API.
+import type { AssetExtension, AssetPath } from '@ultimat3/render';
+import { ASSET_DIR, AssetMissingError, assetPathProblem } from '@ultimat3/render';
+
+/** App-root-relative, beside `favicon.ico`: `apps/web/site/` is where an app's public files live. */
+export const SITE_ASSETS_SOURCE = `apps/web/site/${ASSET_DIR}`;
+
+/** The URL prefix every hashed asset is served under, and the export directory it is copied to. */
+export const SITE_ASSET_BASE_PATH = `/${ASSET_DIR}`;
+
+/** What each served extension IS. `vtt` carries a charset: captions are text a player decodes. */
+export const ASSET_CONTENT_TYPES: Readonly<Record<AssetExtension, string>> = {
+  avif: 'image/avif',
+  webp: 'image/webp',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  ico: 'image/x-icon',
+  woff2: 'font/woff2',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  vtt: 'text/vtt; charset=utf-8',
+};
+
+export interface SiteAsset {
+  /** As `asset()` names it: `assets/brand/logo.svg`. */
+  readonly path: AssetPath;
+  /** Absolute path on disk. */
+  readonly file: string;
+  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  readonly hash: string;
+  /** `/assets/brand/logo.<hash>.svg`. */
+  readonly url: string;
+  readonly contentType: string;
+  readonly bytes: number;
+}
+
+const splitExtension = (path: string): { readonly stem: string; readonly extension: string } => {
+  const dot = path.lastIndexOf('.');
+  return { stem: path.slice(0, dot), extension: path.slice(dot + 1) };
+};
+
+/** The hash goes before the extension, so a static host still infers the type from the name. */
+export function hashedAssetUrl(path: AssetPath, hash: string): string {
+  const { stem, extension } = splitExtension(path);
+  return `/${stem}.${hash}.${extension}`;
+}
+
+const HASHED = /^\/(assets\/.+)\.([0-9a-f]{8})\.([a-z0-9]+)$/i;
+
+/** The inverse of `hashedAssetUrl`: which asset a request names, and at which content. */
+export function parseHashedAssetUrl(
+  pathname: string,
+): { readonly path: AssetPath; readonly hash: string } | undefined {
+  const match = HASHED.exec(pathname);
+  if (match === null) return undefined;
+  const path = `${match[1] ?? ''}.${match[3] ?? ''}`;
+  if (assetPathProblem(path) !== undefined) return undefined;
+  return { path: path as AssetPath, hash: match[2] ?? '' };
+}
+
+const hashBytes = (bytes: Uint8Array): string =>
+  Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0');
+
+export interface SiteAssetTable {
+  /** The asset `asset()` named, hashed as the bytes are NOW. Throws `X_ASSET_MISSING`. */
+  resolve(path: AssetPath): SiteAsset;
+  /** Every servable file under the source directory, sorted by path. */
+  all(): readonly SiteAsset[];
+}
+
+const missing = (path: string, cause: string): AssetMissingError =>
+  new AssetMissingError(
+    `asset(${JSON.stringify(path)}): ${cause}`,
+    `add the file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}, or correct the path passed to asset(), then x build --target static --json`,
+  );
+
+/**
+ * A stat per call, a read only when the file changed: `x dev` sees an edited image under a new URL
+ * on the next render with no watcher, and the container — whose files never change — pays one
+ * `stat` per `asset()` call and nothing else. One behaviour in both, never a dev-only rescan.
+ */
+export function createSiteAssetTable(root: string): SiteAssetTable {
+  const source = join(root, SITE_ASSETS_SOURCE);
+  const cache = new Map<string, { readonly stamp: string; readonly asset: SiteAsset }>();
+
+  const resolve = (path: AssetPath): SiteAsset => {
+    const problem = assetPathProblem(path);
+    if (problem !== undefined) throw missing(path, problem);
+    const file = join(source, path.slice(ASSET_DIR.length + 1));
+    let stamp: string;
+    try {
+      const stat = statSync(file);
+      if (!stat.isFile()) throw missing(path, `${file} is not a file`);
+      stamp = `${String(stat.mtimeMs)}:${String(stat.size)}`;
+    } catch (error) {
+      if (error instanceof AssetMissingError) throw error;
+      throw missing(path, `no file at ${SITE_ASSETS_SOURCE}/${path.slice(ASSET_DIR.length + 1)}`);
+    }
+    const cached = cache.get(path);
+    if (cached !== undefined && cached.stamp === stamp) return cached.asset;
+    const bytes = readFileSync(file);
+    const hash = hashBytes(bytes);
+    // `assetPathProblem` already refused an unknown extension; the guard keeps `constructor` from
+    // ever answering an `Object` member if that check is loosened.
+    const extension = splitExtension(path).extension.toLowerCase();
+    const asset: SiteAsset = {
+      path,
+      file,
+      hash,
+      url: hashedAssetUrl(path, hash),
+      contentType: Object.hasOwn(ASSET_CONTENT_TYPES, extension)
+        ? ASSET_CONTENT_TYPES[extension as AssetExtension]
+        : 'application/octet-stream',
+      bytes: bytes.byteLength,
+    };
+    cache.set(path, { stamp, asset });
+    return asset;
+  };
+
+  const all = (): readonly SiteAsset[] => {
+    const found: SiteAsset[] = [];
+    let files: string[];
+    try {
+      files = [...new Bun.Glob('**/*').scanSync({ cwd: source, onlyFiles: true })];
+    } catch {
+      // No `assets/` directory is an app with no assets, not an error.
+      return [];
+    }
+    for (const relativePath of files.sort()) {
+      const path = `${ASSET_DIR}/${relativePath.split('\\').join('/')}`;
+      // A source file beside its renditions (a `.psd`, a `README.md`) is not a served asset.
+      if (assetPathProblem(path) !== undefined) continue;
+      found.push(resolve(path as AssetPath));
+    }
+    return found;
+  };
+
+  return { resolve, all };
+}
+
+/** One table per root, so the renderer and the route read the same cache. */
+const tables = new Map<string, SiteAssetTable>();
+
+export function siteAssetTable(root: string): SiteAssetTable {
+  let table = tables.get(root);
+  if (table === undefined) {
+    table = createSiteAssetTable(root);
+    tables.set(root, table);
+  }
+  return table;
+}
+
+/**
+ * Every asset, copied into the static export under its hashed URL — a static host serves with no
+ * process behind it, so the artifact carries every byte a document names. Returns the URLs written.
+ */
+export function writeSiteAssets(root: string, out: string): readonly string[] {
+  const written: string[] = [];
+  for (const asset of siteAssetTable(root).all()) {
+    const target = join(out, asset.url.slice(1));
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(asset.file, target);
+    written.push(asset.url);
+  }
+  return written;
+}

package/src/site-config.ts

@@ -0,0 +1,79 @@
+// The public origin and the crawler rules out of `app.config.ts` — `site.origin` and
+// `seo.robots.disallow` — and the one resolution of "which origin is this site served on" every
+// absolute URL a document, a sitemap or a robots file carries is built against. Sibling of
+// `app-auth.ts`'s `loadSignInPath`, and it imports the config for the same reason.
+
+// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
+import { join } from 'node:path';
+import type { AppConfig, Environment } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+export interface SiteSettings {
+  /** `site.origin`, trailing slash removed; `null` when the app declares none. */
+  readonly origin: string | null;
+  /** `seo.robots.disallow` — the paths a production `robots.txt` keeps crawlers out of. */
+  readonly disallow: readonly string[];
+}
+
+export const NO_SITE_SETTINGS: SiteSettings = { origin: null, disallow: [] };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Structural, never `instanceof`, for `loadSignInPath`'s reason: a config that resolved through an
+ * older core simply has no `site` section, and that is the "not declared" answer, not a crash.
+ */
+const hasSiteSections = (value: unknown): value is Pick<AppConfig, 'site' | 'seo'> =>
+  isRecord(value) &&
+  isRecord(value['site']) &&
+  isRecord(value['seo']) &&
+  isRecord(value['seo']['robots']);
+
+const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
+
+export async function loadSiteSettings(root: string): Promise<SiteSettings> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(configPath).exists())) return NO_SITE_SETTINGS;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!hasSiteSections(config)) return NO_SITE_SETTINGS;
+  const origin = config.site.origin;
+  return {
+    origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
+    disallow: [...config.seo.robots.disallow],
+  };
+}
+
+/**
+ * The declared public origin: `APP_URL` (what the runtime already names it — OAuth's redirect, the
+ * sync node's admitted origin), then `SITE_ORIGIN` (the static build's), then `site.origin`.
+ * The environment first because one image is deployed to staging and production under two
+ * origins; the config line is what a deploy that sets neither falls back to. `undefined` when
+ * nothing names one — the caller decides whether the request's own origin will do.
+ */
+export function publicOrigin(
+  env: Readonly<Record<string, string | undefined>>,
+  site: SiteSettings,
+): string | undefined {
+  for (const key of ['APP_URL', 'SITE_ORIGIN']) {
+    const declared = env[key]?.trim() ?? '';
+    if (declared !== '') return trimSlash(declared);
+  }
+  return site.origin ?? undefined;
+}
+
+/**
+ * The sentence a production build prints when no origin was declared. Every canonical, `og:url`,
+ * hreflang and sitemap `<loc>` is then built against a placeholder, and a search engine indexes a
+ * page whose canonical names a host the site is not on. A warning, not a refusal: a production
+ * build on a laptop is how a deploy is rehearsed.
+ */
+export function originWarning(environment: Environment, declared: string | undefined): string[] {
+  if (environment !== 'production' || declared !== undefined) return [];
+  return [
+    'no public origin: set APP_URL (or SITE_ORIGIN) or `site: { origin }` in app.config.ts — ' +
+      'canonical, og:url, hreflang and the sitemap are absolute against a placeholder',
+  ];
+}

package/src/site-seo.ts

@@ -3,6 +3,7 @@
 // serves it), so a crawler reads the same two files from a CDN and from a container.
 
 import type { Environment } from '@ultimat3/core';
+import { localeConfig, localizedPath, routedLocales, unlocalizedPath } from '@ultimat3/i18n';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
@@ -24,6 +25,11 @@ export interface SiteSeoOptions {
    * the same list, enumerated by the same function the prerenderer calls.
    */
   readonly pagesFor?: ((routePath: string) => readonly string[]) | undefined;
+  /**
+   * `seo.robots.disallow` from `app.config.ts` (`loadSiteSettings`). Added to the production
+   * `User-agent: *` group; a non-production `robots.txt` still disallows everything.
+   */
+  readonly disallow?: readonly string[] | undefined;
 }
 
 export interface SiteSeo {
@@ -36,8 +42,15 @@ export interface SiteSeo {
 const isPublicSite = (entry: RouteEntry): boolean =>
   entry.surface === 'site' && entry.config.policy === undefined;
 
+/**
+ * A dynamic route's pages, UNPREFIXED and once each. A static export's report lists every locale's
+ * copy (`/blog/a` and `/en/blog/a`), and the sitemap localizes each page itself — reading the
+ * prefixed copies back as pages of their own listed `/en/en/blog/a`.
+ */
 const pagesOf = async (entry: RouteEntry, options: SiteSeoOptions): Promise<readonly string[]> => {
-  if (options.pagesFor !== undefined) return options.pagesFor(entry.path);
+  if (options.pagesFor !== undefined) {
+    return [...new Set(options.pagesFor(entry.path).map((path) => unlocalizedPath(path)))];
+  }
   const params = await enumeratePrerender(entry);
   return params.map((set) => fillPath(entry.pattern.source, set));
 };
@@ -65,13 +78,29 @@ async function publicSiteRoutes(options: SiteSeoOptions): Promise<readonly Route
 }
 
 export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
-  const sitemap = await buildSitemap(await publicSiteRoutes(options), { baseUrl: options.baseUrl });
+  // Every routed locale, with `xhtml:link` alternates: one `<url>` per page per locale, each
+  // naming the whole cluster and `x-default`. A single-locale app passes none and gets the plain
+  // urlset it always had — an alternates cluster of one is noise.
+  const locales = routedLocales();
+  const defaultLocale = localeConfig().fallback;
+  const sitemap = await buildSitemap(await publicSiteRoutes(options), {
+    baseUrl: options.baseUrl,
+    ...(locales.length < 2
+      ? {}
+      : {
+          locales,
+          defaultLocale,
+          localizePath: (path: string, locale: string) =>
+            localizedPath(path, locale, defaultLocale),
+        }),
+  });
   // Past 50,000 URLs `files` are `/sitemap-N.xml` and the index is `/sitemap.xml`; below it,
   // `files` is that one file and there is no index.
   const sitemaps = sitemap.index === undefined ? sitemap.files : [sitemap.index, ...sitemap.files];
   const robots = buildRobots({
     baseUrl: options.baseUrl,
     sitemaps: [SITEMAP_PATH],
+    ...(options.disallow === undefined ? {} : { disallow: options.disallow }),
     ...(options.environment === undefined ? {} : { environment: options.environment }),
   });
   return { robots, sitemaps };

package/src/templates/scaffold-entries.ts

@@ -65,7 +65,7 @@ const prerender =
 // landed on disk — which is what \`x build --target static --json\` reads back.
 
 import { join } from 'node:path';
-import { DEFAULT_ORIGIN, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
+import { loadSiteSettings, type PrerenderReport, prerenderSite, siteSeo } from '@ultimat3/cli';
 
 const root = join(import.meta.dir, '..', '..');
 const flag = Bun.argv.indexOf('--out');
@@ -90,9 +90,11 @@ const origin = Bun.env.SITE_ORIGIN;
  * \`robots.txt\` fails closed — anything that is not \`ULTIMATE_ENV=production\` emits
  * \`Disallow: /\` and advertises no sitemap — so a preview build cannot outrank the real site.
  */
-async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<readonly string[]> {
+async function writeSeoFiles(report: PrerenderReport): Promise<readonly string[]> {
   const seo = await siteSeo({
-    baseUrl,
+    // The origin the pages were built against, so the sitemap and every canonical agree.
+    baseUrl: report.origin,
+    disallow: (await loadSiteSettings(root)).disallow,
     pagesFor: (route) =>
       report.pages.filter((page) => page.route === route).map((page) => page.path),
   });
@@ -103,7 +105,7 @@ async function writeSeoFiles(report: PrerenderReport, baseUrl: string): Promise<
 
 if (import.meta.main) {
   const report = await prerenderSite({ root, out, ...(origin === undefined ? {} : { origin }) });
-  const seo = await writeSeoFiles(report, origin ?? DEFAULT_ORIGIN);
+  const seo = await writeSeoFiles(report);
   await Bun.stdout.write(
     \`\${JSON.stringify({ ok: true, out: report.out, emitted: report.pages, skipped: report.skipped, unmeasured: report.unmeasured, report: report.report, seo })}\\n\`,
   );

package/src/test-select.ts

@@ -5,7 +5,7 @@
 import { join } from 'node:path';
 // Bun ships no equivalent: `join` builds the host-separator path from the scan root to a hit.
 // Sizing is Bun's own (`Bun.file().size`), so nothing here reaches for `node:fs`.
-import { nearestName } from '@ultimat3/core';
+import { nearestName, renderFixShellArg } from '@ultimat3/core';
 import { BadFlagError } from './errors';
 import type { ParsedArgs } from './parse';
 import { flagString } from './parse';
@@ -45,17 +45,21 @@ const IGNORED = ['/dist/', '/build/', '/node_modules/', '/examples/', '/dummy/']
  * File size stands in for duration: cheap to read, and it correlates far better than file count.
  * `type`, when given, narrows to exactly the files verify-tests.ts would run for that suite — one
  * owner per path, decided by `ownerOf` there and never a second time here.
+ *
+ * `filter` is one substring or several: a path is kept when it contains ANY of them, so an app's
+ * scoped runner hands `x test` every affected slice at once instead of one process per slice.
  */
 export async function discoverTests(
   root: string,
-  filter?: string,
+  filter?: string | readonly string[],
   type?: TestType,
 ): Promise<readonly TestFile[]> {
+  const filters = filter === undefined ? undefined : typeof filter === 'string' ? [filter] : filter;
   const files: TestFile[] = [];
   for await (const found of new Bun.Glob(TEST_GLOB).scan({ cwd: root, absolute: false })) {
     const path = found.split('\\').join('/');
     if (IGNORED.some((part) => `/${path}`.includes(part))) continue;
-    if (filter !== undefined && !path.includes(filter)) continue;
+    if (filters !== undefined && !filters.some((part) => path.includes(part))) continue;
     if (type !== undefined && !belongsToType(path, type)) continue;
     files.push({ path, bytes: Bun.file(join(root, path)).size });
   }
@@ -134,6 +138,29 @@ export function readSample(args: ParsedArgs): number | undefined {
   return value;
 }
 
+/**
+ * `--filter`'s value as the list `discoverTests` matches: comma-separated, each item trimmed. An
+ * empty item is refused rather than dropped — `''` is a substring of every path, so `a,,b` would
+ * quietly widen a narrowed run back to the whole suite.
+ */
+export function readFilters(raw: string | undefined): readonly string[] | undefined {
+  if (raw === undefined) return undefined;
+  const items = raw.split(',').map((item) => item.trim());
+  if (items.some((item) => item === '')) {
+    const kept = items.filter((item) => item !== '');
+    throw new BadFlagError({
+      flag: 'filter',
+      command: 'test',
+      reason: `"${raw}" holds an empty path, and an empty substring matches every test file`,
+      fix:
+        kept.length === 0
+          ? 'x test --json'
+          : `x test --filter ${renderFixShellArg(kept.join(','), '<path,path>')}`,
+    });
+  }
+  return items;
+}
+
 /** The selection, as `NoTestFilesError` wants it: only the parts the caller actually asked for. */
 export function missingSelection(
   type: TestType | undefined,

package/src/test-workers.ts

@@ -3,8 +3,9 @@
 // suite two different ways, and the `--worker N` reproduction a shard failure prints would then
 // name a shard the gate never ran.
 
-// Bun ships no CPU-count primitive; `cpus()` is the fallback when navigator cannot answer.
-import { cpus } from 'node:os';
+// Bun ships no CPU-count or free-memory primitive: `cpus()` is the fallback when navigator cannot
+// answer, and `freemem()` is the only reader of available memory.
+import { cpus, freemem } from 'node:os';
 import type { TestType } from '@ultimat3/testing';
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
@@ -14,7 +15,7 @@ export function availableCpus(): number {
 }
 
 /**
- * Deliberately MORE workers than cores, with a ceiling.
+ * Deliberately MORE workers than cores, bounded by memory rather than by a fixed count.
  *
  * `cpus - 1` is the intuitive default and it was measured to be worthless exactly where it has to
  * pay off. On a 4-core `ubuntu-latest` — the runner this repo commits to — the `unit` step:
@@ -32,23 +33,62 @@ export function availableCpus(): number {
  * resolution, on `--isolate` rebuilding a registry per file, and on waiting for its database.
  * Oversubscribing fills those stalls.
  *
- * The ceiling is memory, not cores. A worker is a whole Bun process with the framework's module
- * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite, so
- * width costs hundreds of MB per step. It binds on a developer's 12- or 32-core machine, which is
- * exactly where an unbounded count would swap.
+ * The bound is memory, not cores. A worker is a whole Bun process with the framework's module
+ * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite. Until
+ * 22.3 that was a FIXED ceiling of 8, which held a 12-core box to 8 workers with 30 GB free: the
+ * notificado.co `unit` step (381 files) sat at 51s on 8 workers against a 90s gate budget. The
+ * ceiling is now what the machine can actually hold — `os.freemem()` (MemAvailable on Linux, so
+ * reclaimable page cache counts as free) divided by `WORKER_BYTES` — which still binds on a small
+ * CI runner and on a loaded laptop, the two places an unbounded count would swap.
  *
  * The floor of 2 keeps a 1-core box sharding rather than silently reverting to serial.
  */
-export const WORKER_CEILING = 8;
-
-/** Oversubscription factor. See the table above — it is measured, not chosen for roundness. */
 export const WORKER_OVERSUBSCRIBE = 1.5;
 
 /** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
 export const WORKER_FLOOR = 2;
 
-export const defaultWorkers = (available: number = availableCpus()): number =>
-  Math.max(WORKER_FLOOR, Math.min(WORKER_CEILING, Math.round(available * WORKER_OVERSUBSCRIBE)));
+/**
+ * What one test worker is budgeted at, for the memory bound above. MEASURED — peak RSS of the whole
+ * `x test unit` process tree on the notificado.co corpus (381 files, PGlite per worker), 12-core
+ * box, `As of 2026-09-25`:
+ *
+ *   | workers | peak tree RSS |
+ *   |---------|---------------|
+ *   | 8       | 20.7 GB       |
+ *   | 12      | 22.5 GB       |
+ *   | 16      | 24.3 GB       |
+ *
+ * The MARGINAL worker costs ~0.45 GB (the slope); the ~17 GB intercept is the corpus itself —
+ * every file's module graph and database, retained per worker — and does not shrink with fewer
+ * workers, so it is not this bound's to budget. The constant is the slope doubled and rounded to a
+ * power of two, because free memory is read once, before a single worker has started.
+ */
+export const WORKER_BYTES = 1024 * 1024 * 1024;
+
+/**
+ * The most `--workers` accepts, on either command. Not a default and not a memory rule — a sanity
+ * bound: without one `--workers 5000` parsed, the run clamped only to the file count, and it
+ * started one Bun process per test FILE. An explicit width below it is the caller's call.
+ */
+export const WORKER_CEILING = 64;
+
+/** Bun ships no memory primitive; `freemem()` is libuv's MemAvailable on Linux. */
+export const availableMemory = (): number => freemem();
+
+/**
+ * `ceil(cpus x 1.5)`, held to what free memory can carry and never below the floor. The file-count
+ * clamp is `test-passes.ts`'s (every pass is clamped to its own file list), because only the
+ * caller knows the selection.
+ */
+export const defaultWorkers = (
+  available: number = availableCpus(),
+  freeBytes: number = availableMemory(),
+): number => {
+  const byCpu = Math.ceil(available * WORKER_OVERSUBSCRIBE);
+  const byMemory = Math.floor(freeBytes / WORKER_BYTES);
+  return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
+};
 
 /**
  * Which types run across worker processes, and why the other two cannot.