@ultimat3/cli 24.0.0 → 25.0.0

package/src/shot-settle.ts

@@ -32,9 +32,9 @@ export interface SettleOptions {
 /**
  * Read the probe until every booted island has settled, or the window runs out.
  *
- * `DEFAULT_SETTLE_MS` is the deadline at which the hydration runtime CALLS `import()` — `mounted`
- * and `failed` land after it — so a single read at that instant reports `mounted: 0` for a page
- * that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
+ * The default window, `IDLE_HYDRATE_TIMEOUT_MS`, is the deadline at which the hydration runtime
+ * CALLS `import()` — `mounted` and `failed` land after it — so a single read at that instant
+ * reports `mounted: 0` for a page that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
  * is the only shape that ends EARLY on a fast page and still bounds a slow one.
  *
  * A `null` answer never overwrites a real count: `null` means "not counted", and a probe that

package/src/shot-theme.ts

@@ -5,7 +5,7 @@
 // (issue #489). A requested theme is therefore stored as the visitor's CHOICE, on the page's origin,
 // before the boot reads it: the picture is then what a visitor who chose that theme sees.
 
-import { THEME_STORAGE_KEY } from '@ultimat3/render';
+import { THEME_STORAGE_KEY } from '@ultimat3/core';
 import type { ShotColorScheme } from './browser-launcher-port';
 import { BadFlagError } from './errors';
 

package/src/shot-viewport.ts

@@ -0,0 +1,152 @@
+// `x shot --viewport 390x844,1440x900`: the flag read into sizes, and one route photographed once
+// per size into `<out>/<w>x<h>/` over ONE dev server. Every responsive picture used to need a
+// hand-written browser script beside the tool that exists to make that unnecessary (#444).
+
+// why: no Bun native joins a path.
+import { join } from 'node:path';
+import { renderCauseValue } from '@ultimat3/core';
+import type { ShotRun } from './cmd-shot';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import type { ShotServer } from './shot-server';
+import type { ShotArtifacts } from './shot-verdict';
+import { shotLines, shotSummary, verdictJson } from './shot-verdict';
+
+/** CSS pixels a page is laid out in. */
+export interface ShotViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The largest side a size may have: Chrome's maximum texture dimension, past which a capture is
+ * tiles the compositor never painted. One bound for both sides, so the refusal states one number.
+ */
+export const VIEWPORT_MAX = 16_384;
+
+/** Digits only: `0x10`, `1e3` and `390.5` are not a size anybody typed meaning a size. */
+const SIZE = /^(\d+)x(\d+)$/i;
+
+const FIX = 'x shot / --viewport 390x844,1440x900 --json';
+
+const refuse = (reason: string): never => {
+  throw new BadFlagError({ flag: 'viewport', command: 'shot', reason, fix: FIX });
+};
+
+/**
+ * An island state declares its own `viewport` in its `*.island.states.ts`, and the harness opens one
+ * browser per declared size — so a size asked for beside `--island`/`--all-islands` is a second
+ * answer to a question the states already answer.
+ */
+export function refuseViewportWithComponent(): never {
+  throw new BadFlagError({
+    flag: 'viewport',
+    command: 'shot',
+    reason: 'sizes a route capture; an island is photographed at the viewport each state declares',
+    fix: FIX,
+  });
+}
+
+/** A size is its own directory name, so two sizes can never write one picture. */
+export const viewportDir = (viewport: ShotViewport): string =>
+  `${String(viewport.width)}x${String(viewport.height)}`;
+
+function readSize(entry: string): ShotViewport {
+  const match = SIZE.exec(entry);
+  if (match === null) {
+    return refuse(`${renderCauseValue(entry)} is not <width>x<height>, e.g. 390x844`);
+  }
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (width < 1 || height < 1 || width > VIEWPORT_MAX || height > VIEWPORT_MAX) {
+    return refuse(`${renderCauseValue(entry)} is outside 1..${String(VIEWPORT_MAX)} on a side`);
+  }
+  return { width, height };
+}
+
+/**
+ * The flag, every entry judged before any is returned — a run that photographed the good half and
+ * refused afterwards would leave a reader with half a set and a failure. Absent is `undefined`:
+ * no override, the capture's own default size. Refused, never skipped: an empty entry and the same
+ * size twice are both a list the reader did not mean, and the second would overwrite the first.
+ */
+export function parseViewports(raw: string | undefined): readonly ShotViewport[] | undefined {
+  if (raw === undefined) return undefined;
+  const sizes = raw.split(',').map((entry) => readSize(entry.trim()));
+  const seen = new Set<string>();
+  for (const size of sizes) {
+    const dir = viewportDir(size);
+    if (seen.has(dir)) return refuse(`${dir} is listed twice`);
+    seen.add(dir);
+  }
+  return sizes;
+}
+
+export interface ViewportRun {
+  readonly viewports: readonly ShotViewport[];
+  /** Absolute; each size lands in `<outDir>/<w>x<h>/`. */
+  readonly outDir: string;
+  readonly boot: () => Promise<ShotServer>;
+  /** `runShot`, handed in so this module never imports the command that imports it. */
+  readonly shoot: (run: ShotRun) => Promise<ShotArtifacts>;
+  /** Everything a size shares: the route, the driver, the waits, the locale, the theme. */
+  readonly base: Omit<ShotRun, 'outDir' | 'boot' | 'viewport'>;
+}
+
+/**
+ * One server for every size, `runShotMatrix`'s rule: each capture gets a boot that never stops it,
+ * and the run stops it once after the last picture. Each size is an ordinary `runShot`, so its
+ * `verdict.json` means exactly what a single shot's does; `ok` only when every one is.
+ */
+export async function runShotViewports(run: ViewportRun): Promise<CommandResult> {
+  // `parseViewports` never answers an empty list; a hand-built one is refused before the boot.
+  if (run.viewports.length === 0) refuse('lists no size');
+  const server = await run.boot();
+  const shared: ShotServer = { ...server, stop: () => Promise.resolve() };
+  const shots: { readonly viewport: ShotViewport; readonly artifacts: ShotArtifacts }[] = [];
+  try {
+    for (const viewport of run.viewports) {
+      const artifacts = await run.shoot({
+        ...run.base,
+        viewport,
+        outDir: join(run.outDir, viewportDir(viewport)),
+        boot: () => Promise.resolve(shared),
+      });
+      shots.push({ viewport, artifacts });
+    }
+  } finally {
+    await server.stop().catch(() => undefined);
+  }
+  // The summary is the first failure's, else the first picture's — labelled by its size, so a
+  // reader of one line knows which of the sizes it speaks for.
+  const worst = shots.find((shot) => !shot.artifacts.verdict.ok) ?? shots[0];
+  return {
+    ok: shots.every((shot) => shot.artifacts.verdict.ok),
+    command: 'shot',
+    summary:
+      worst === undefined
+        ? refuse('lists no size')
+        : msg('cli.shot.viewport.summary', {
+            size: viewportDir(worst.viewport),
+            summary: shotSummary(worst.artifacts.verdict),
+          }),
+    lines: shots.flatMap((shot) => [
+      msg('cli.shot.viewport.line', {
+        size: viewportDir(shot.viewport),
+        summary: shotSummary(shot.artifacts.verdict),
+      }),
+      ...shotLines(shot.artifacts).map((line) => `  ${line}`),
+    ]),
+    data: {
+      outDir: run.outDir,
+      shots: shots.map((shot) => ({
+        width: shot.viewport.width,
+        height: shot.viewport.height,
+        image: shot.artifacts.image,
+        verdictFile: shot.artifacts.verdictFile,
+        verdict: verdictJson(shot.artifacts.verdict),
+      })),
+    },
+  };
+}

package/src/signal-shred.ts

@@ -4,24 +4,38 @@
 
 export type Reraise = (signal: NodeJS.Signals) => void;
 
+/** Ctrl-C, a supervisor's stop, and a terminal closing under the editor. */
+const SHRED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const;
+
 const reraiseDefault: Reraise = (signal) => {
   process.kill(process.pid, signal);
 };
 
 /**
- * Shred on SIGINT/SIGTERM, then re-raise the same signal: `once` has already removed this
- * listener, so the re-raised signal meets the default action and terminates. Returns the undo for
- * the normal path, which shreds in its own `finally`.
+ * Shred on SIGINT/SIGTERM/SIGHUP, then re-raise the same signal with the listeners gone, so it
+ * meets the default action and terminates. Returns the undo for the normal path, which shreds in
+ * its own `finally`.
+ *
+ * The listeners stay installed UNTIL the shred is done, and a repeat meanwhile is ignored. With
+ * `once` the listener was gone the moment the first signal was dispatched, so a second one — a
+ * Ctrl-C the terminal delivers to the whole group and a wrapper forwards again — met the default
+ * action: a kernel-level kill mid-`rmSync`, the plaintext left in $TMPDIR (30 of 40 runs).
  */
 export function shredOnSignal(shred: () => void, reraise: Reraise = reraiseDefault): () => void {
-  const handler = (signal: NodeJS.Signals): void => {
-    shred();
-    reraise(signal);
-  };
-  process.once('SIGINT', handler);
-  process.once('SIGTERM', handler);
-  return () => {
-    process.off('SIGINT', handler);
-    process.off('SIGTERM', handler);
+  let shredding = false;
+  const undo = (): void => {
+    for (const signal of SHRED_SIGNALS) process.off(signal, handler);
   };
+  function handler(signal: NodeJS.Signals): void {
+    if (shredding) return;
+    shredding = true;
+    try {
+      shred();
+    } finally {
+      undo();
+      reraise(signal);
+    }
+  }
+  for (const signal of SHRED_SIGNALS) process.on(signal, handler);
+  return undo;
 }

package/src/site-asset-routes.ts

@@ -5,7 +5,7 @@
 
 import { isUltimateError } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
 import type { SiteAsset, SiteAssetTable } from './site-assets';
 import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
 
@@ -13,7 +13,7 @@ import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
 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 });
+  jsonResponse({ 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(

package/src/site-seo.ts

@@ -4,7 +4,8 @@
 
 import type { Environment, SeoSitemapConfig } from '@ultimat3/core';
 import { UltimateError } from '@ultimat3/core';
-import { localeConfig, localizedPath, routedLocales, unlocalizedPath } from '@ultimat3/i18n';
+import { localizedPath, unlocalizedPath } from '@ultimat3/i18n';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteEntry } from '@ultimat3/render';
 import { routeEntries } from '@ultimat3/render';
 import { enumeratePrerender, fillPath } from '@ultimat3/render/server';
@@ -150,10 +151,11 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
   // 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 settings = options.sitemap ?? NO_SITEMAP_SETTINGS;
+  // The app's declared set — the one the manifest, the worker and the prerender read — never the
+  // ambient locale config, which a build process has not configured.
   const root = options.root ?? process.cwd();
+  const { locales, defaultLocale } = await appLocaleSet(root);
+  const settings = options.sitemap ?? NO_SITEMAP_SETTINGS;
   const stamp: Stamp = (file) => {
     const lastmod = lastmodOf(file, settings.lastmod, root);
     return lastmod === undefined ? {} : { lastmod };

package/src/source-files.ts

@@ -3,6 +3,7 @@
 // means a finding one of them can never see.
 
 import { hasPathSegment } from './path-segments';
+import { toPosix } from './posix-path';
 
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
@@ -38,7 +39,17 @@ export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');
 export const isTest = (path: string): boolean => /\.test\.tsx?$/.test(path);
 
 /**
- * Every source file under `root`, repo-relative and deduplicated across the globs — in a SORTED
+ * Glob answers as the POSIX paths every consumer keys by, in code-unit order of that spelling.
+ * The glob answers in the host's separator: on Windows `guards\untranslated-string.ts` missed
+ * `i18n`'s `startsWith('guards/')`, so the example `t('…')` in its fix line became a key every
+ * fresh scaffold was missing — and `^packages\/` rules matched nothing at all.
+ */
+export function sortedPosix(paths: readonly string[]): string[] {
+  return paths.map(toPosix).sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+
+/**
+ * Every source file under `root`, repo-relative, POSIX and deduplicated across the globs — in a SORTED
  * order per pattern, `As of 2026-09-05`. `Bun.Glob.scan` yields in the filesystem's `readdir`
  * order, which ext4 hashes: the first offender a scan names was `index.ts` on one machine and
  * `tools.ts` on a GitHub runner, so a finding's `cause` depended on which disk held the checkout
@@ -52,8 +63,7 @@ export async function* eachSourceFile(root: string): AsyncGenerator<string> {
     for await (const path of new Bun.Glob(pattern).scan({ cwd: root, absolute: false })) {
       if (!isVendored(path)) matches.push(path);
     }
-    matches.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
-    for (const path of matches) {
+    for (const path of sortedPosix(matches)) {
       if (seen.has(path)) continue;
       seen.add(path);
       yield path;

package/src/static-report.ts

@@ -71,6 +71,11 @@ export type UnmeasuredRoute = {
   readonly code?: string;
   readonly cause?: string;
   readonly fix?: string;
+  /**
+   * Who the measurement render ran as, labelled (`measure-scope.ts`'s `measurementActorLabel`) —
+   * so a refusal OF that actor names it, and the edit that changes it (#675). Never its facts.
+   */
+  readonly actor?: string;
   /**
    * `false` when no build can weigh the route by construction — a `render: 'ssr'` page with params,
    * which may not declare `prerender()`, so the build holds no value to render it at. Not a defect

package/src/style-routes.ts

@@ -4,7 +4,7 @@
 // image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
 import type { StyleBundle } from './style-bundle';
 import { STYLE_BASE_PATH } from './style-bundle';
 
@@ -32,7 +32,7 @@ export function styleRoutes(source: StyleSource): readonly Route[] {
       handler: (request: UltimateRequest): Response => {
         const chunk = source().chunkAt(request.pathname);
         if (chunk === undefined) {
-          const missing = json(
+          const missing = jsonResponse(
             {
               ok: false,
               error: {

package/src/sw-artifacts.ts

@@ -3,7 +3,6 @@
 // until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
 // file, this one needs a booted app and a finished build.
 
-import { localeConfig, routedLocales } from '@ultimat3/i18n';
 import type { PrecacheManifest } from '@ultimat3/pwa';
 import { generateServiceWorker } from '@ultimat3/pwa';
 import type { RouteDescriptor } from '@ultimat3/render';
@@ -12,7 +11,7 @@ import { ISLAND_BASE_PATH } from './island-bundle';
 import { msg } from './messages';
 import type { PwaArtifacts } from './pwa-artifacts';
 import type { StyleBundle } from './style-bundle';
-import type { RenderedDocument, RoutedLocales } from './sw-precache-plan';
+import type { RenderedDocument } from './sw-precache-plan';
 import { localePrefixes, precacheAssets, pwaRoutes } from './sw-precache-plan';
 
 export type { RenderedDocument, RoutedLocales } from './sw-precache-plan';
@@ -73,11 +72,6 @@ export interface ServiceWorkerInput {
    * offline reload that cannot load the boot restores no record and shows the old count.
    */
   readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
-  /**
-   * The routed locales, default first. Absent, `@ultimat3/i18n`'s own — the answer the server routes
-   * with, set once the app's catalogs are loaded, which every caller has done by now.
-   */
-  readonly locales?: RoutedLocales;
 }
 
 /**
@@ -157,7 +151,9 @@ export function serviceWorkerArtifacts(
   // 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 locales = input.locales ?? { routed: routedLocales(), fallback: localeConfig().fallback };
+  // The set the manifests were built from (`PwaArtifacts.locales`), never the ambient locale
+  // config: one answer, so a locale an installed manifest names is always one the worker prefixes.
+  const locales = pwa.locales;
   const output = generateServiceWorker(
     pwaRoutes(input.routes, documents, locales),
     {
@@ -187,6 +183,10 @@ export function serviceWorkerArtifacts(
         styles: input.styles,
         scripts: input.scripts ?? [],
         fallback,
+        placeholders: {
+          urls: [pwa.offline.image, pwa.offline.font].filter((url): url is string => url !== null),
+          buildId: input.buildId,
+        },
       }),
     },
     input.buildId,

package/src/sw-precache-plan.ts

@@ -7,6 +7,7 @@ import type { PrecacheAsset, PwaRoute } from '@ultimat3/pwa';
 import { strategyFor } from '@ultimat3/pwa';
 import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
+import { parseHashedAssetUrl } from './site-assets';
 import type { StyleBundle } from './style-bundle';
 
 /**
@@ -94,6 +95,12 @@ export interface PrecacheAssetInput {
   readonly scripts: readonly { readonly url: string; readonly bytes: number }[];
   /** The offline document's path: its islands ride the precache whatever its own route says. */
   readonly fallback: string;
+  /**
+   * `pwa.offline.image` / `pwa.offline.font`: the worker answers a failed image or font request
+   * from the PRECACHE only, so a placeholder nothing precached is a branch that matches nothing.
+   * `buildId` is the revision of one whose bytes this build cannot hash — the offline document's.
+   */
+  readonly placeholders?: { readonly urls: readonly string[]; readonly buildId: string };
 }
 
 /**
@@ -140,12 +147,35 @@ export function precacheAssets(input: PrecacheAssetInput): readonly PrecacheAsse
   for (const chunk of input.islands.chunks) {
     if (wanted.has(chunk.url)) for (const url of chunk.imports) wanted.add(url);
   }
-  return [
+  const chunks: PrecacheAsset[] = [
     ...input.islands.chunks.filter((chunk) => wanted.has(chunk.url)),
     ...input.islands.shared.filter((chunk) => wanted.has(chunk.url)),
     ...input.styles.chunks,
     ...input.scripts,
-  ]
-    .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
-    .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+  ].map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }));
+  return [...chunks, ...placeholderAssets(input, new Set(chunks.map((chunk) => chunk.url)))].sort(
+    (a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0),
+  );
+}
+
+/**
+ * The placeholders on the offline document's terms (`buildPrecacheManifest`'s `fallback` entry):
+ * never refused here — this pass cannot see the site assets, and the worker installs entry by
+ * entry, so a URL that 404s costs that entry and the branch falls through to the 503 — and
+ * stamped with the build id unless the URL is content-addressed, which is its own revision. Bytes
+ * unknown count 0, as the offline document's do. A chunk already listed keeps its own entry.
+ */
+function placeholderAssets(
+  input: PrecacheAssetInput,
+  listed: ReadonlySet<string>,
+): PrecacheAsset[] {
+  const out = new Map<string, PrecacheAsset>();
+  const placeholders = input.placeholders;
+  if (placeholders === undefined) return [];
+  for (const url of placeholders.urls) {
+    if (listed.has(url) || out.has(url)) continue;
+    const hashed = parseHashedAssetUrl(url) !== undefined;
+    out.set(url, { url, revision: hashed ? url : placeholders.buildId, bytes: 0 });
+  }
+  return [...out.values()];
 }

package/src/sync-authenticator.ts

@@ -9,8 +9,8 @@ import { finiteCount, systemClock } from '@ultimat3/core';
 import type { HttpConfig } from '@ultimat3/http';
 import {
   configuredAuthenticator,
-  createRequestContext,
   defineHttpConfig,
+  requestContext,
   UltimateRequest,
 } from '@ultimat3/http';
 import type { SyncAuthenticator, SyncGrant } from '@ultimat3/realtime/server';
@@ -84,7 +84,7 @@ export interface SyncAuthenticatorOptions {
 /**
  * What the sync node is given when the app configured an authenticator, and `undefined` when it
  * did not — which keeps `x dev` anonymous and makes the node log that it is, exactly as
- * `createSyncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
+ * `syncNode` documents. A stub that answered `{ actor: anonymous }` would look configured.
  *
  * The grant carries an `expiresAt` and a `refresh`, and both are the app's own resolver asked
  * again: `configureAuthenticator` says who is dialling, and the only honest way to learn that it
@@ -115,7 +115,7 @@ export function syncAuthenticator(
       method: credential.method,
       headers: credential.headers,
     });
-    const ctx = createRequestContext({
+    const ctx = requestContext({
       url: new URL(credential.url),
       method: credential.method,
       role: 'sync',

package/src/sync-url.ts

@@ -5,7 +5,7 @@
 import { ConfigInvalidError } from '@ultimat3/core';
 
 /**
- * The sync node's own path (`createSyncNode`'s default in `@ultimat3/realtime`). Same origin by
+ * The sync node's own path (`syncNode`'s default in `@ultimat3/realtime`). Same origin by
  * default because every rung already serves it there: `x dev` and a combined-role container mount
  * the node on the web port, and `docker/helm`'s ingress routes `/_x/sync` to the `sync` service.
  */

package/src/templates/action.ts

@@ -154,7 +154,7 @@ const input = { id, orgId${isMutator ? ", title: 'a title'" : ''} };
 
 // Named here because every projection needs a stable name and this file does not boot the app.
 // At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
-// object, so \`${name.camel}.tool()\` works there with nothing to remember.
+// object, so each projection of it works there with nothing to remember.
 const target = ${name.camel}.named('${name.camel}');
 ${
   outsider
@@ -234,7 +234,7 @@ ${
     ? `
 unitTest('the handler answers the row it found', async () => {
   const draft = { orgId, title: 'kept', price: { minor: 0, currency: 'USD' } };
-  const row = await runWithContext(createContext({ actor: writer }), () => repo.insert(draft));
+  const row = await runWithContext(ctxOf({ actor: writer }), () => repo.insert(draft));
   const answer = await target.as(writer, ${call});
   expect(answer).toEqual(${found});
 });
@@ -263,7 +263,7 @@ const actionUnitTest = (name: NameSet, feature: NameSet, shape: HandlerShape): s
   return `// ${name.camel}: its declared shape, the input it refuses, and what its handler answers — in
 // process, so all three belong to the \`unit\` step. The contract projections are next door.
 ${sortedImports([
-  ...(stores ? ["import { createContext, runWithContext } from '@ultimat3/core';"] : []),
+  ...(stores ? ["import { ctxOf, runWithContext } from '@ultimat3/core';"] : []),
   "import { testActor } from '@ultimat3/policy';",
   `import { ${testing} } from '@ultimat3/testing';`,
   ...(stores ? [`import { driver } from '${shape.dbModule}';`] : []),
@@ -276,7 +276,7 @@ const input = { id, orgId${shape.isMutator ? ", title: 'a title'" : ''} };
 ${shape.isMutator ? `\n// The client store's table: the entity's own, so the twin and the server row share one key.\nconst TABLE = '${feature.table}';\n` : ''}
 // Named here because every projection needs a stable name and this file does not boot the app.
 // At boot \`registerActions(await import('./actions'))\` stamps the same name onto the same
-// object, so \`${name.camel}.tool()\` works there with nothing to remember.
+// object, so each projection of it works there with nothing to remember.
 const target = ${name.camel}.named('${name.camel}');
 
 // Holds the grant in the org the input names: past the policy, so what answers is the handler.

package/src/templates/backfill.ts

@@ -107,14 +107,14 @@ const backfillTest = (
 ): string => `// ${name.camel}'s durable identity: one live run per name, retried under the same key. The work
 // itself — the pass over real rows and the projection it applies — is the unit suite's, next door.
 
-import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+import { memoryJobDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
 // The driver is process-global, so it is installed and released around this file rather than
 // left behind for whichever test happens to run next.
 beforeAll(() => {
-  setJobDriver(createMemoryDriver());
+  setJobDriver(memoryJobDriver());
 });
 afterAll(resetJobDriver);
 
@@ -162,7 +162,7 @@ const backfillUnitTest = (
 // driver. A sweep rewrites rows no user asked it to, so what is worth failing on is that it reaches
 // every tenant's rows, writes the projection and nothing else, and that a replay changes nothing.
 ${sortedImports([
-  "import { createContext, runWithContext } from '@ultimat3/core';",
+  "import { ctxOf, runWithContext } from '@ultimat3/core';",
   "import { testActor } from '@ultimat3/policy';",
   "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
   `import { db, driver } from '${dbModule}';`,
@@ -175,7 +175,7 @@ const orgB = '00000000-0000-4000-8000-000000000009';
 
 /** What a request is to the handle: an actor, whose org every read and write runs under. */
 const inOrg = <T>(orgId: string, run: () => Promise<T>): Promise<T> =>
-  runWithContext(createContext({ actor: testActor('member', { orgId }).actor }), run);
+  runWithContext(ctxOf({ actor: testActor('member', { orgId }).actor }), run);
 
 const store = (orgId: string, title: string): Promise<${feature.pascal}> => {
   const draft = { orgId, title, price: { minor: 1000, currency: 'USD' } };

package/src/templates/entity.ts

@@ -156,7 +156,7 @@ const repoTest = (
 ): string => `// The ${name.kebab} repo against the in-memory driver: the contract Postgres serves, with no
 // database. What it pins is what the repo cannot show by being read — whose rows a call reaches.
 ${sortedImports([
-  "import { createContext, frozenClock, runWithContext } from '@ultimat3/core';",
+  "import { ctxOf, frozenClock, runWithContext } from '@ultimat3/core';",
   "import { testActor } from '@ultimat3/policy';",
   "import { afterEach, expect, unitTest } from '@ultimat3/testing';",
   `import { driver } from '${dbModule}';`,
@@ -171,7 +171,7 @@ const clock = frozenClock('2026-01-01T00:00:00.000Z');
 
 /** What a request is to the handle: an actor, whose org every read and write runs under. */
 const inOrg = <T>(org: string, run: () => Promise<T>): Promise<T> =>
-  runWithContext(createContext({ actor: testActor('member', { orgId: org }).actor, clock }), run);
+  runWithContext(ctxOf({ actor: testActor('member', { orgId: org }).actor, clock }), run);
 
 const draft = (title: string) => ({ orgId, title, price: { minor: 1200, currency: 'USD' } });