@ultimat3/cli 23.0.0 → 24.0.0

package/src/serve-boot.ts

@@ -5,13 +5,15 @@
 // (`serve-web.ts`) and the manifest projection are behind `await import()` in turn, so a worker's
 // module graph holds neither.
 
-import type { Role } from '@ultimat3/core';
+import type { DrainConfig, LifecycleOptions, Role } from '@ultimat3/core';
 import { configureLifecycle, logger } from '@ultimat3/core';
 import type { MetricsEndpoint } from './metrics-endpoint';
 import { startOtlpExport } from './otlp-export';
 import { loadAppForRole, roleLoadFor } from './role-load';
 import { startRoles } from './role-start';
 import { resolveServices } from './runtime-bindings';
+import { warnIfIdempotencyProcessScoped } from './runtime-idempotency-scope';
+import { warnUnsealedMfaSecrets } from './runtime-mfa-warning';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
 import { startServices } from './runtime-services';
@@ -42,6 +44,23 @@ async function buildIdFor(options: ServeOptions, role: Role): Promise<string> {
   return (await appManifest(options.root)).manifest.buildId;
 }
 
+/** The roles that open an HTTP listener something routes to — the only ones a readiness grace serves. */
+const LISTENING_ROLES: readonly Role[] = ['web', 'sync'];
+
+/**
+ * `app.config.ts`'s `drain`, applied to the WHOLE process rather than only to the web server that
+ * `createServer` hands it to. A role nothing routes to gets no readiness grace at all: the grace
+ * holds `/readyz` at 503 with the listener open so the endpoints catch up, and a worker has neither
+ * — it only went on claiming jobs for those seconds, then aborted them at the drain (s1-con #7).
+ */
+export function lifecycleForRole(
+  role: Role,
+  drain: Partial<DrainConfig> | undefined,
+): LifecycleOptions {
+  if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0 };
+  return drain?.readinessGraceMs === undefined ? {} : { readinessGraceMs: drain.readinessGraceMs };
+}
+
 /**
  * Everything `serveApp` does after the scrape listener is open: the services, then the roles over
  * them. One export, so `serve.ts` reaches the whole serving graph through ONE `await import()`.
@@ -53,11 +72,12 @@ export async function bootServing(boot: {
   readonly metrics: MetricsEndpoint;
 }): Promise<ServedApp> {
   const { options } = boot;
-  const runtime = await startServices(
-    resolveServices(options.root, options.env),
-    options.env,
-    options.runtime,
-  );
+  const services = resolveServices(options.root, options.env);
+  // A serving role on a real database runs no DDL: `ROLE=migrate` applied this build's framework
+  // tables first, and this boot only verifies the stamp it left (`framework-schema-apply.ts`).
+  // The embedded database has no migrate step to have run, so it applies its own.
+  const schema = services.db.mode === 'external' ? 'verify' : 'apply';
+  const runtime = await startServices(services, options.env, options.runtime, schema);
   boot.acquired.push(() => runtime.stop());
   return bootRoles({ ...boot, runtime });
 }
@@ -84,6 +104,8 @@ async function bootRoles(boot: {
   for (const finding of loaded.findings) {
     logger.error('ultimate app module failed to load', { role, ...finding });
   }
+  // After the app's modules: an app swaps the store at import time, after `startServices`.
+  warnIfIdempotencyProcessScoped();
   const buildId = await buildIdFor(options, role);
   // Before the first socket opens: everything above this line fails loudly into the container's
   // own logs, everything below it is a served request, a claimed job or a routed frame.
@@ -102,6 +124,9 @@ async function bootRoles(boot: {
     role === 'web'
       ? await (await import('./serve-web')).webSurface(options, runtime, buildId)
       : undefined;
+  if (web !== undefined) acquired.push(web.release);
+  // The web role alone — it is where a second factor is asked for — and once per pod boot.
+  if (role === 'web') await warnUnsealedMfaSecrets(runtime.db);
   // Islands and stylesheets are the image build's to make (`x build --target prebuilt`). A role
   // that made either here served correctly and paid for it — seconds of CPU and a compiler's
   // memory, on every start of every replica — so it says so once, with the Dockerfile line.
@@ -112,6 +137,7 @@ async function bootRoles(boot: {
   // still wins — that is the deploy talking.
   const metricsPort = metricsPortFor(options.env, port, options.metricsPort);
   const drain = await loadDrainConfig(options.root);
+  configureLifecycle(lifecycleForRole(role, drain));
   // Process-wide, so every role's `/readyz` — web, sync, worker — answers in the declared mode.
   const health = await loadHealthConfig(options.root);
   if (health?.readiness !== undefined) configureLifecycle({ readiness: health.readiness });
@@ -156,6 +182,8 @@ async function bootRoles(boot: {
     runtime,
     async stop() {
       await running.stop();
+      // After the server drained: a bust landing mid-drain still marks the pages it is serving.
+      web?.release();
       await runtime.stop();
       // Last: the exporters outlive the roles they were recording, so the drain's own spans and
       // the final counter snapshot still have somewhere to go.

package/src/serve-drain.ts

@@ -1,41 +1,17 @@
-// `app.config.ts`'s `drain` and `health` sections, read for the production boot — the same import
-// every other config reader here makes (`theme-boot.ts`, `app-auth.ts`), because the config is a
-// module. Both shape what `/readyz` tells the load balancer.
+// `app.config.ts`'s `drain` and `health` sections for the production boot, off the one loader
+// (`app-config-load.ts`). Both shape what `/readyz` tells the load balancer.
 
 import type { DrainConfig, HealthConfig } from '@ultimat3/core';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/**
- * The declared section, or `undefined` when the app has none (a config not built by
- * `defineConfig`, or no config file): `@ultimat3/http` then keeps core's own default. A value that
- * is not a number is left for core to refuse, where the rule lives, rather than dropped here.
- */
+/** The declared section, or `undefined` for a root with no config file — core keeps its default. */
 export async function loadDrainConfig(root: string): Promise<Partial<DrainConfig> | undefined> {
-  const path = `${root}/${APP_CONFIG_FILE}`;
-  if (!(await Bun.file(path).exists())) return undefined;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const drain = isRecord(config) ? config['drain'] : undefined;
-  if (!isRecord(drain) || !Object.hasOwn(drain, 'readinessGraceMs')) return undefined;
-  return { readinessGraceMs: drain['readinessGraceMs'] as number };
+  const drain = (await loadAppConfig(root))?.drain;
+  return drain === undefined ? undefined : { readinessGraceMs: drain.readinessGraceMs };
 }
 
-/**
- * `health.readiness`, or `undefined` when the app declares none (core keeps `'dependencies'`). The
- * value is handed to `configureLifecycle` as written, so a bad one is refused by core's own rule.
- */
+/** `health.readiness`, or `undefined` for a root with no config file (core keeps its default). */
 export async function loadHealthConfig(root: string): Promise<Partial<HealthConfig> | undefined> {
-  const path = `${root}/${APP_CONFIG_FILE}`;
-  if (!(await Bun.file(path).exists())) return undefined;
-  const module = (await import(path)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  const health = isRecord(config)
-    ? (config['health'] as Partial<HealthConfig> | undefined)
-    : undefined;
-  if (!isRecord(health) || health.readiness === undefined) return undefined;
-  return { readiness: health.readiness };
+  const health = (await loadAppConfig(root))?.health;
+  return health === undefined ? undefined : { readiness: health.readiness };
 }

package/src/serve-env.ts

@@ -42,22 +42,25 @@ export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
 /**
  * `ROLE` is the one knob one image exposes. Validated rather than defaulted: a typo that fell back
  * to `web` would start a process that serves nothing the operator asked for and reports healthy.
+ * Empty or blank is unset, read the way `PORT` and `HOST` are — not a role name nobody typed.
  */
 export function roleFromEnv(env: Env): Role {
-  const raw = env['ROLE'] ?? 'web';
-  if (!isRole(raw)) throw new RoleUnknownError({ role: raw, known: ROLES });
-  return raw;
+  const raw = env['ROLE']?.trim();
+  const role = raw === undefined || raw.length === 0 ? 'web' : raw;
+  if (!isRole(role)) throw new RoleUnknownError({ role, known: ROLES });
+  return role;
 }
 
 /**
- * `Number.parseInt` would read `80abc` as 80, so the whole string has to be a port — a
- * partially-parsed port is a deploy that binds somewhere nobody asked for.
+ * `Number.parseInt` would read `80abc` as 80, and `Number` reads `0x1F90` as 8080 and `8e3` as
+ * 8000, so the whole string has to be decimal digits — a port spelled any other way is a deploy
+ * that binds somewhere nobody wrote down.
  */
 function portValue(env: Env, name: string, fallback: number): number {
   const raw = env[name];
   if (raw === undefined || raw.trim().length === 0) return fallback;
   const port = Number(raw.trim());
-  if (!Number.isInteger(port) || port < 0 || port > 65_535)
+  if (!/^\d+$/.test(raw.trim()) || !Number.isInteger(port) || port < 0 || port > 65_535)
     throw new PortInvalidError({ value: raw, name });
   return port;
 }

package/src/serve-web.ts

@@ -5,7 +5,6 @@
 
 import type { Route } from '@ultimat3/http';
 import { describeRoutes } from '@ultimat3/render';
-import { createIsrController } from '@ultimat3/render/server';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { mountAppMcp } from './app-mcp';
@@ -19,6 +18,7 @@ import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { adminMountRoutes } from './runtime-admin';
 import { assetRoutes } from './runtime-assets';
+import { attachedIsr } from './runtime-isr';
 import { appRoutes } from './runtime-render';
 import type { RunningServices } from './runtime-services';
 import { servedStorage, storageRoutes } from './runtime-storage';
@@ -42,6 +42,8 @@ export interface WebSurface {
   readonly signInPath: string | null;
   /** Present when this boot built the islands itself: how many chunks, and why not the store. */
   readonly islandsBuilt?: LoadedIslands['built'];
+  /** Detaches the ISR controller from `invalidateTags` — on the boot's stop list. */
+  readonly release: () => void;
 }
 
 export async function webSurface(
@@ -93,6 +95,13 @@ export async function webSurface(
   const mcpMount = await mountAppMcp(options.root);
   // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
   const served = servedStorage(runtime.storage);
+  // Attached, so a tag bust marks this process's ISR pages stale. The store is the deployment's
+  // when it supplied one: the default is per process, so twelve replicas hold twelve of them and a
+  // purge regenerates one twelfth of the fleet while the other eleven keep the invalidated page.
+  const isr = attachedIsr({
+    buildId,
+    ...(options.runtime?.isrStore === undefined ? {} : { store: options.runtime.isrStore }),
+  });
   const routes: readonly Route[] = [
     ...apiRoutes(),
     // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
@@ -142,12 +151,7 @@ export async function webSurface(
       ...(pwa === undefined
         ? {}
         : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
-      // Only when a store was supplied. `createIsrController` defaults to a per-process memory
-      // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
-      // the fleet while the other eleven keep serving the page it just invalidated.
-      ...(options.runtime?.isrStore === undefined
-        ? {}
-        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+      isr: isr.isr,
     }),
   ];
   return {
@@ -160,5 +164,6 @@ export async function webSurface(
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
     ...(islandsBuilt === undefined ? {} : { islandsBuilt }),
+    release: isr.release,
   };
 }

package/src/shot-locale.ts

@@ -3,9 +3,7 @@
 // on the language of the machine's Chrome. A non-default locale is also a URL prefix (`/en/…`),
 // because on a `site/` route the unprefixed path is always the default locale whatever the header.
 
-import { join } from 'node:path'; // why: Bun ships no path join.
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { BadFlagError } from './errors';
 
 export interface ShotLocales {
@@ -16,27 +14,11 @@ export interface ShotLocales {
 /** An app that declares nothing is `en` only — the framework's own default. */
 export const FALLBACK_SHOT_LOCALES: ShotLocales = { locales: ['en'], defaultLocale: 'en' };
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/** `app.config.ts`'s `locales` and `defaultLocale`, read the way `loadThemeMode` reads `theme`. */
+/** `app.config.ts`'s `locales` and `defaultLocale`, off the one loader (`app-config-load.ts`). */
 export async function loadShotLocales(root: string): Promise<ShotLocales> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return FALLBACK_SHOT_LOCALES;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return FALLBACK_SHOT_LOCALES;
-  const declared = config['locales'];
-  const locales = Array.isArray(declared)
-    ? declared.filter((locale): locale is string => typeof locale === 'string')
-    : [];
-  const fallback = config['defaultLocale'];
-  const defaultLocale =
-    typeof fallback === 'string' && fallback !== '' ? fallback : (locales[0] ?? 'en');
-  return {
-    locales: locales.length === 0 ? [defaultLocale] : locales,
-    defaultLocale,
-  };
+  const config = await loadAppConfig(root);
+  if (config === undefined) return FALLBACK_SHOT_LOCALES;
+  return { locales: config.locales, defaultLocale: config.defaultLocale };
 }
 
 /** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */

package/src/site-assets.ts

@@ -9,6 +9,7 @@ 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';
+import { contentHash } from '@ultimat3/render/server';
 
 /** 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}`;
@@ -37,7 +38,7 @@ export interface SiteAsset {
   readonly path: AssetPath;
   /** Absolute path on disk. */
   readonly file: string;
-  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  /** `@ultimat3/render`'s `contentHash` of the bytes, 8 hex characters — the one CSS and HTML get. */
   readonly hash: string;
   /** `/assets/brand/logo.<hash>.svg`. */
   readonly url: string;
@@ -69,9 +70,6 @@ export function parseHashedAssetUrl(
   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;
@@ -110,7 +108,7 @@ export function createSiteAssetTable(root: string): SiteAssetTable {
     const cached = cache.get(path);
     if (cached !== undefined && cached.stamp === stamp) return cached.asset;
     const bytes = readFileSync(file);
-    const hash = hashBytes(bytes);
+    const hash = contentHash(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();

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

@@ -173,7 +173,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

@@ -16,6 +16,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;
 
 /**

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/sync-url.ts

@@ -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

package/src/templates/naming.ts

@@ -77,6 +77,34 @@ export const plural = (input: string): string => {
   return `${input}s`;
 };
 
+/** Singular words `plural()` already handles, though they end in a lone `s`. */
+const SINGULAR_IN_S: ReadonlySet<string> = new Set([
+  'alias',
+  'atlas',
+  'bias',
+  'canvas',
+  'gas',
+  'lens',
+]);
+
+/**
+ * The singular a plural name was made from, kebab-case — `undefined` when the name is not one
+ * `plural()` would have produced. Read off the last word only, `plural()`'s inverse: a name that
+ * is already plural is pluralised AGAIN by every generator that names a table (`posts` →
+ * `postses`), so it is refused with this spelling. `ss`, `us`, `is` endings are singular.
+ */
+export const singularOf = (input: string): string | undefined => {
+  const parts = words(input);
+  const last = parts.at(-1);
+  if (last === undefined || !last.endsWith('s') || /(ss|us|is)$/.test(last)) return undefined;
+  if (SINGULAR_IN_S.has(last)) return undefined;
+  const candidates = last.endsWith('ies')
+    ? [`${last.slice(0, -3)}y`]
+    : [last.slice(0, -2), last.slice(0, -1)];
+  const found = candidates.find((candidate) => candidate.length > 0 && plural(candidate) === last);
+  return found === undefined ? undefined : [...parts.slice(0, -1), found].join('-');
+};
+
 export const titleKey = (input: string): string => `app.${kebab(input)}.title`;
 
 /**