@ultimat3/cli 23.0.0 → 25.0.0

package/src/site-config.ts

@@ -1,14 +1,10 @@
 // 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.
+// absolute URL a document, a sitemap or a robots file carries is built against. Read off the one
+// loader (`app-config-load.ts`).
 
-// why: Bun exposes no path-join primitive, and the config path is app-root-relative.
-import { join } from 'node:path';
-import type { AppConfig, Environment, SeoSitemapConfig, SitemapLastmod } from '@ultimat3/core';
-import { SITEMAP_LASTMOD_SOURCES } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { Environment, SeoSitemapConfig } from '@ultimat3/core';
+import { loadAppConfig } from './app-config-load';
 
 export interface SiteSettings {
   /** `site.origin`, trailing slash removed; `null` when the app declares none. */
@@ -25,51 +21,16 @@ export const NO_SITE_SETTINGS: SiteSettings = {
   sitemap: { extra: [], lastmod: 'none' },
 };
 
-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;
+  const config = await loadAppConfig(root);
+  if (config === undefined) return NO_SITE_SETTINGS;
+  const { origin } = config.site;
   return {
-    origin: typeof origin === 'string' && origin !== '' ? trimSlash(origin) : null,
+    origin: origin === null ? null : trimSlash(origin),
     disallow: [...config.seo.robots.disallow],
-    sitemap: sitemapOf(config.seo),
-  };
-}
-
-/**
- * Structural for `hasSiteSections`' reason: a config resolved through a core older than
- * `seo.sitemap` has no such key, and that is the default, not a crash.
- */
-function sitemapOf(seo: unknown): SeoSitemapConfig {
-  const declared = isRecord(seo) ? seo['sitemap'] : undefined;
-  if (!isRecord(declared)) return NO_SITE_SETTINGS.sitemap;
-  const extra = declared['extra'];
-  const lastmod = declared['lastmod'];
-  return {
-    extra: Array.isArray(extra)
-      ? extra.filter((path): path is string => typeof path === 'string')
-      : [],
-    lastmod: SITEMAP_LASTMOD_SOURCES.includes(lastmod as SitemapLastmod)
-      ? (lastmod as SitemapLastmod)
-      : 'none',
+    sitemap: config.seo.sitemap,
   };
 }
 

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 };
@@ -173,7 +175,7 @@ export async function siteSeo(options: SiteSeoOptions): Promise<SiteSeo> {
             localizedPath(path, locale, defaultLocale),
         }),
   });
-  // Past 50,000 URLs `files` are `/sitemap-N.xml` and the index is `/sitemap.xml`; below it,
+  // Past 50,000 URLs `files` are `/sitemaps/<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({

package/src/sitemap-lastmod.ts

@@ -14,6 +14,9 @@ let builtAt: string | undefined;
 
 const cache = new Map<string, string | undefined>();
 
+/** One `git log -1` over one path; a synchronous wait past this blocks the request serving it. */
+const GIT_DATE_TIMEOUT_MS = 5_000;
+
 /**
  * The `<lastmod>` for one route file, W3C Datetime (ISO 8601, UTC), or `undefined` when the source
  * yields none — a sitemap entry without `<lastmod>` is valid, a wrong one misleads a crawler.
@@ -46,6 +49,8 @@ function gitDate(file: string, root: string): string | undefined {
       cwd: root,
       stdout: 'pipe',
       stderr: 'ignore',
+      // A wedged `git` (a lock, a credential prompt) answers no date: the mtime fallback below.
+      timeout: GIT_DATE_TIMEOUT_MS,
     });
     if (run.exitCode !== 0) return undefined;
     return isoOf(run.stdout.toString().trim());

package/src/solid-loader.ts

@@ -73,6 +73,10 @@ interface CacheEntry {
  */
 const cache = new Map<string, CacheEntry>();
 
+/** Transforms running now, and the `prepareStackTrace` the first of them found (see below). */
+let inFlight = 0;
+let foundStackTrace: typeof Error.prepareStackTrace;
+
 /** Test seam: the cache is process-global because the dev server it serves is too. */
 export function clearIslandTransformCache(): void {
   cache.clear();
@@ -92,8 +96,12 @@ export async function transformIslandTsx(source: string, path: string): Promise<
 
   // Babel installs its own `prepareStackTrace` on the first TRANSFORM — not on import, which is
   // where this guard was first put — and leaving it installed makes `Error.captureStackTrace`
-  // strict for every unrelated module loaded later in the same process.
-  const saved = Error.prepareStackTrace;
+  // strict for every unrelated module loaded later in the same process, and names every error in
+  // it `Error` (a `TypeError`'s stack then opens `Error: …`). Saved by the FIRST transform in
+  // flight and restored by the LAST: `Bun.build` loads a second `.tsx` while the first compiles,
+  // and a per-call save taken inside that window saved Babel's own rewriter and restored it last.
+  if (inFlight === 0) foundStackTrace = Error.prepareStackTrace;
+  inFlight += 1;
   let code: string | null | undefined;
   try {
     // `transformAsync` and never `transformFileAsync`: the latter is gated behind `@babel/core`'s
@@ -111,7 +119,8 @@ export async function transformIslandTsx(source: string, path: string): Promise<
     });
     code = result?.code;
   } finally {
-    Error.prepareStackTrace = saved;
+    inFlight -= 1;
+    if (inFlight === 0) Error.prepareStackTrace = foundStackTrace;
   }
   // A parse error is NOT caught here: Babel's own message already names the file, the line and the
   // column ("a.island.tsx: Unexpected token (2:23)"), and `buildOne` wraps whatever escapes in

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}',
@@ -16,6 +17,12 @@ export const SOURCE_GLOBS = [
   'api/**/*.{ts,tsx}',
   'shared/**/*.{ts,tsx}',
   'apps/*/{app,site,api,shared}/**/*.{ts,tsx}',
+  // An app's own entry files: authored, shipped, and outside every surface glob above — a 900-line
+  // `server.ts` or an unrunnable `fix:` in it was invisible to `filesize` and `errors`.
+  // And its guards: run on the gate, held to the error contract, and invisible to `filesize`.
+  'guards/*.ts',
+  'apps/*/server.ts',
+  'apps/*/prerender.ts',
 ] as const;
 
 /**
@@ -32,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
@@ -46,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/stored-object-headers.ts

@@ -0,0 +1,43 @@
+// How a stored object may be presented when the app's own origin serves it (plan 101, s1-sec L6):
+// inline only for a type a browser renders without running anything, a sandboxed download otherwise. Read by
+// both surfaces that serve stored bytes — `/_storage` (`runtime-storage.ts`) and `/media`.
+
+/**
+ * Raster images, audio and video: what an `<img>`, `<audio>` or `<video>` presents and nothing
+ * executes. NOT `image/svg+xml` (it carries `<script>`), `text/html`, `application/xml` or PDF —
+ * any of them opened from the app's origin runs with the app's cookies and its `'self'` sources.
+ */
+const INLINE_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+  'audio/mpeg',
+  'audio/ogg',
+  'audio/wav',
+  'audio/webm',
+  'video/mp4',
+  'video/webm',
+  'video/ogg',
+]);
+
+/** `image/PNG; charset=…` is `image/png`: parameters and case never widen the list. */
+const essenceOf = (contentType: string): string =>
+  (contentType.split(';')[0] ?? '').trim().toLowerCase();
+
+export const isInlineSafe = (contentType: string): boolean =>
+  INLINE_TYPES.has(essenceOf(contentType));
+
+/**
+ * The headers a stored object is served with beyond its type. `attachment` makes a navigation to an
+ * uploaded `text/html` a download instead of a page on the app's origin; an embedding element
+ * (`<img>`, `<video>`) ignores it, so nothing that displays an object inline stops working. The
+ * `sandbox` policy is for the browser that renders it anyway: an opaque origin, no script, no
+ * cookies. `@ultimat3/http`'s security stage keeps it and adds the app's policy beside it.
+ */
+export function storedObjectHeaders(contentType: string): Readonly<Record<string, string>> {
+  return isInlineSafe(contentType)
+    ? {}
+    : { 'content-disposition': 'attachment', 'content-security-policy': 'sandbox' };
+}

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.
  */
@@ -43,8 +43,8 @@ export function syncConnectSources(env: Readonly<Record<string, string | undefin
 }
 
 /**
- * The page origins a sync node admits besides its own host name: `APP_URL`'s, when set. Only a
- * deployment that serves the page on another host than the node needs it; an unparsable value is
+ * The page origins a sync node admits besides its own origin: `APP_URL`'s, when set. A deployment
+ * that serves the page on another port or host than the node sees needs it; an unparsable value is
  * refused rather than read as "no page origin", which would refuse every socket in silence.
  */
 export function syncOriginsFrom(env: Readonly<Record<string, string | undefined>>): string[] {

package/src/tasks-facts.ts

@@ -5,38 +5,12 @@
 import type { TaskDescriptor, TaskHandle } from '@ultimat3/jobs';
 import { getTask, registeredTasks } from '@ultimat3/jobs';
 import type { CronPhrases } from '@ultimat3/time';
-import {
-  describeCron,
-  fromEpochMs,
-  nextCronOccurrenceMs,
-  offsetLabel,
-  toZoned,
-} from '@ultimat3/time';
+import { describeCron, fromEpochMs, isoInZone, nextCronOccurrenceMs } from '@ultimat3/time';
 import { BadFlagError } from './errors';
 
 const DEFAULT_COUNT = 5;
 const MAX_COUNT = 50;
 
-const pad2 = (value: number): string => String(value).padStart(2, '0');
-
-/**
- * ISO-8601 rendered with the ZONE's OWN offset (`2026-03-08T03:00:00-04:00`), never collapsed to
- * UTC `Z` — an ambient zone is exactly the bug a task's `tz` exists to prevent. No single
- * "instant in a zone, as ISO" export exists in `@ultimat3/time` to call instead: `toIso` is
- * UTC-`Z` only, `isoDateInZone` is date-only, and `formatWithOffset` renders locale prose, not
- * ISO. So this composes the package's own instant→zoned-wall-clock conversion (`toZoned`) and
- * zone-label helper (`offsetLabel`) rather than a fresh `Intl.DateTimeFormat` call here.
- *
- * Exported for `cmd-tasks.ts`'s `last` column: the occurrence a task last fired and the one it
- * fires next are one clock, so they are one function.
- */
-export function isoInZone(ms: number, zone: string): string {
-  const zoned = toZoned(fromEpochMs(ms), zone);
-  const date = `${String(zoned.year).padStart(4, '0')}-${pad2(zoned.month)}-${pad2(zoned.day)}`;
-  const time = `${pad2(zoned.hour)}:${pad2(zoned.minute)}:${pad2(zoned.second)}`;
-  return `${date}T${time}${offsetLabel(zoned.offsetMinutes)}`;
-}
-
 /** `x tasks list` row: the descriptor plus the next occurrence, ms and rendered alike. */
 export interface TaskFact extends TaskDescriptor {
   readonly nextMs: number;
@@ -46,7 +20,7 @@ export interface TaskFact extends TaskDescriptor {
 function toFact(handle: TaskHandle, nowMs: number): TaskFact {
   const descriptor = handle.describe();
   const nextMs = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, nowMs);
-  return { ...descriptor, nextMs, next: isoInZone(nextMs, descriptor.tz) };
+  return { ...descriptor, nextMs, next: isoInZone(fromEpochMs(nextMs), descriptor.tz) };
 }
 
 export function listTaskFacts(nowMs: number): readonly TaskFact[] {
@@ -110,7 +84,7 @@ export function taskShowFacts(
   let cursor = nowMs;
   for (let i = 0; i < count; i += 1) {
     cursor = nextCronOccurrenceMs(descriptor.cron, descriptor.tz, cursor);
-    upcoming.push({ ms: cursor, at: isoInZone(cursor, descriptor.tz) });
+    upcoming.push({ ms: cursor, at: isoInZone(fromEpochMs(cursor), descriptor.tz) });
   }
   return { descriptor, describe: describeCron(descriptor.cron, 'en-US', phrases), upcoming };
 }

package/src/templates/action.ts

@@ -82,6 +82,9 @@ export const ${name.camel} = mutator({
   input: t.object({ id: t.uuid, orgId: t.uuid, title: t.string }),
   output: t.object({ id: t.uuid, title: t.string }),
   policy: can${feature.pascal}Write,
+  // Required on a mutator (X_MUTATOR_NOT_IDEMPOTENT): the client replays this write under one
+  // Idempotency-Key after a dropped response, and the replay answers the first result.
+  idempotent: true,
   // No \`mcp\` until a real description is written: see \`x g action\`.
   // tx.table(name) rather than tx.${feature.plural}: the typed accessor exists only once the app
   // augments LocalTables, and generated code cannot assume that has happened yet. The name is the
@@ -151,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
@@ -231,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});
 });
@@ -260,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}';`] : []),
@@ -273,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' } });