@ultimat3/cli 21.0.0 → 22.1.0

package/src/runtime-jobs.ts

@@ -0,0 +1,87 @@
+// `jobs.queues`, `jobs.concurrency` and `jobs.visibilityTimeoutMs`, read out of the app's own
+// `app.config.ts` for the `worker` role — the sibling of `runtime-realtime.ts`, and structural
+// for its reason. Until 22.0.0 `createWorker` was called with none of them: every worker served
+// `default` at its own concurrency whatever the config said, so a `mail` queue ran nothing.
+
+// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
+// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
+import { join } from 'node:path';
+import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** What the worker takes from the config. An absent number keeps the worker's own default. */
+export interface WorkerConfig {
+  readonly queues: readonly string[];
+  readonly concurrency: number | undefined;
+  readonly visibilityTimeoutMs: number | undefined;
+}
+
+const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
+  queues: [],
+  concurrency: undefined,
+  visibilityTimeoutMs: undefined,
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * A number is handed on AS WRITTEN, never screened here: `createWorker`'s `resolveWorkerTimings`
+ * is the one refusal for a non-finite knob, and core's `defineConfig` screens both counts first.
+ */
+const numberOf = (value: unknown): number | undefined =>
+  typeof value === 'number' ? value : undefined;
+
+export async function loadWorkerConfig(root: string): Promise<WorkerConfig> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return NO_WORKER_CONFIG;
+  const module = (await import(path)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const jobs = isRecord(config) ? config['jobs'] : undefined;
+  if (!isRecord(jobs)) return NO_WORKER_CONFIG;
+  const queues = Array.isArray(jobs['queues'])
+    ? jobs['queues'].filter((queue): queue is string => typeof queue === 'string' && queue !== '')
+    : [];
+  return {
+    queues,
+    concurrency: numberOf(jobs['concurrency']),
+    visibilityTimeoutMs: numberOf(jobs['visibilityTimeoutMs']),
+  };
+}
+
+/**
+ * The queues a worker serves: the configured ones, then every queue a registered job is enqueued
+ * on. The union and not the list, decided 2026-09-23: `x new` and the deployed demo configure
+ * `['<app>-default']` while a `job()` naming no queue lands on `default`, so obeying the list alone
+ * would leave every such job queued for ever — the silent direction. `undefined` when both are
+ * empty, which is `createWorker`'s own `['default']`.
+ */
+export function workerQueuesFor(
+  configured: readonly string[],
+  registered: readonly string[],
+): readonly string[] | undefined {
+  const served = [...new Set([...configured, ...registered])];
+  return served.length === 0 ? undefined : served;
+}
+
+type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
+
+/**
+ * The `createWorker` options the config supplies, read at START so every job the app registered
+ * on import is counted. A key the config leaves unset is omitted, never passed as `undefined`, so
+ * the worker's own default applies (`exactOptionalPropertyTypes`).
+ */
+export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfigOptions {
+  const queues = workerQueuesFor(
+    config?.queues ?? [],
+    registeredJobs().map((handle) => handle.queue),
+  );
+  return {
+    ...(queues === undefined ? {} : { queues }),
+    ...(config?.concurrency === undefined ? {} : { concurrency: config.concurrency }),
+    ...(config?.visibilityTimeoutMs === undefined
+      ? {}
+      : { visibilityTimeoutMs: config.visibilityTimeoutMs }),
+  };
+}

package/src/{dev-live-feed.ts → runtime-live-feed.ts}

@@ -4,17 +4,22 @@
 // subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
 // every scaffolded app was dead in development — which is where an author first tries one.
 //
-// The bridge is `@ultimat3/testing`'s `startLiveReplicator`, the same in-process row observer the
+// The bridge is `@ultimat3/realtime/server`'s `startLiveReplicator`, the same in-process row observer the
 // framework's own live tests run on: a repository write in THIS process becomes a `ChangeEvent`
 // shaped exactly as the WAL decoder shapes one, fanned into the node's registry. Its honest bound
 // is stated there and repeated here — a write another process makes is invisible — and `x dev` is
 // the one boot where that bound holds by construction: every role runs in this one process.
 
 import { logger, renderThrowable } from '@ultimat3/core';
-import type { LiveReplicator } from '@ultimat3/testing';
-import { startLiveReplicator } from '@ultimat3/testing';
-import type { ServiceMode } from './dev-services';
-import type { RunningSync } from './dev-sync';
+// `@ultimat3/realtime/server`, never `@ultimat3/testing`: this module is on the production boot
+// path (`serve.ts` → `role-start.ts` → here), and the test harness was 38 modules of every image.
+import {
+  type LiveReplicator,
+  RealtimeTopologyError,
+  startLiveReplicator,
+} from '@ultimat3/realtime/server';
+import type { RunningSync } from './role-sync';
+import type { ServiceMode } from './runtime-bindings';
 
 /** What feeds the sync node, said out loud on the boot line and in `--json`. */
 export type LiveFeed = 'in-process' | 'replication' | 'none';
@@ -31,6 +36,10 @@ export interface LiveFeedInput {
   readonly sync: RunningSync | null;
   /** The database's binding: `embedded` is PGlite, which has no log to decode. */
   readonly dbMode: ServiceMode;
+  /** The bus this process fans out on (`Transport.name`): `in-process` reaches no other process. */
+  readonly transport: string;
+  /** Whether the `replicator` role runs in THIS process. */
+  readonly replicatorHere: boolean;
 }
 
 /** The label the `x dev` boot line carries beside `db=`, `events=` and `storage=`. */
@@ -45,6 +54,10 @@ export const liveFeedLabel = (feed: LiveFeed): string => `live=${feed}`;
 export async function startLiveFeed(input: LiveFeedInput): Promise<RunningLiveFeed> {
   if (input.sync === null) return { feed: 'none', bridge: null, stop: () => undefined };
   if (input.dbMode !== 'embedded') {
+    // A decoder this node can hear: in this process, or on a bus other processes share. Neither
+    // is a sync node that reported `replication` while nothing could ever reach it.
+    if (input.transport === 'in-process' && !input.replicatorHere)
+      throw new RealtimeTopologyError();
     return { feed: 'replication', bridge: null, stop: () => undefined };
   }
   const bridge = await startLiveReplicator({

package/src/{dev-notify-retention.ts → runtime-notify-retention.ts}

@@ -1,5 +1,5 @@
 // `notify.inboxReadRetentionMs` and `notify.inboxUnreadRetentionMs`, read out of the app's own
-// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `dev-cache.ts`'s
+// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `runtime-cache.ts`'s
 // `loadCacheTiers`, and structural for the same reason: `defineConfig` returns a plain object, so
 // a config that resolved through an older core simply has no `notify` section.
 //

package/src/{dev-purge.ts → runtime-purge.ts}

@@ -23,8 +23,8 @@ import type { PostgresRateLimitStore } from '@ultimat3/http';
 import type { JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
 import { DEFAULT_PURGE_CRON, getJob, getTask, purge, task } from '@ultimat3/jobs';
 import { purgeNotifyDeliveries, purgeNotifyInbox } from '@ultimat3/notify';
-import type { InboxRetention } from './dev-notify-retention';
-import { NO_INBOX_RETENTION } from './dev-notify-retention';
+import type { InboxRetention } from './runtime-notify-retention';
+import { NO_INBOX_RETENTION } from './runtime-notify-retention';
 
 /** The durable queue key. Pinned, like every framework-owned job name — rows carry it. */
 export const PURGE_JOB_NAME = 'x.purge';

package/src/{dev-queue.ts → runtime-queue.ts}

@@ -1,5 +1,5 @@
 // The database and the job queue, started together and released together. Split from
-// `dev-runtime.ts` because `x jobs` needs exactly this pair and nothing else — and because a
+// `runtime-services.ts` because `x jobs` needs exactly this pair and nothing else — and because a
 // process that installs ambient accessors (`db()`, `jobDriver()`, the jobs facade, the event bus)
 // must have one place that takes them all back, or the next command in the same process inherits
 // a driver over a closed socket.
@@ -32,10 +32,10 @@ import {
   setJobDriver,
   setJobsFacade,
 } from '@ultimat3/jobs';
-import { attachReplica, type ReplicaEnv, replicaUrlFor } from './dev-replica';
-import type { DevServices } from './dev-services';
 import { applyFrameworkSchema } from './framework-schema';
+import type { DevServices } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { attachReplica, type ReplicaEnv, replicaUrlFor } from './runtime-replica';
 
 /** Both embedded and external clients boot lazily and close explicitly. */
 export type DevDbClient = PgliteClient | PostgresClient;
@@ -51,7 +51,7 @@ export interface RunningQueue {
   readonly jobs: JobDriver;
   /**
    * The `x_outbox` store this boot installed behind `handle.enqueue()`. Returned because the
-   * relay that drains it is a ROLE's decision, not the queue's — `dev-roles.ts` starts one.
+   * relay that drains it is a ROLE's decision, not the queue's — `role-start.ts` starts one.
    */
   readonly outbox: OutboxStore;
   /** The `x_job_events` bus a `step.waitForEvent` resumes from. Durable, not per-process. */

package/src/runtime-realtime.ts

@@ -0,0 +1,55 @@
+// `realtime.enabled`, `realtime.transport` and `realtime.urlEnv`, read out of the app's own
+// `app.config.ts` for the boot. The sibling of `runtime-notify-retention.ts` and `runtime-cache.ts`, and
+// structural for their reason: `startServices` holds no `AppConfig`, and `defineConfig` returns a
+// plain object. Until 22.0.0 no boot read any of the three and `NATS_URL` alone decided the bus.
+
+// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
+// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
+import { join } from 'node:path';
+import { ConfigInvalidError, type RealtimeConfig, type RealtimeTransport } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/** Core's `defaults()` for the section, restated as the answer for a config that names none. */
+export const REALTIME_DEFAULTS: RealtimeConfig = Object.freeze({
+  enabled: true,
+  transport: 'memory',
+  urlEnv: undefined,
+});
+
+const TRANSPORTS: readonly RealtimeTransport[] = ['memory', 'nats'];
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/** A transport this boot can build, or a refusal — never a guess at a bus. */
+function transportOf(section: Record<string, unknown>): RealtimeTransport {
+  const value = section['transport'];
+  if (value === undefined) return REALTIME_DEFAULTS.transport;
+  const known = TRANSPORTS.find((transport) => transport === value);
+  if (known !== undefined) return known;
+  throw new ConfigInvalidError({
+    cause: `realtime.transport in ${APP_CONFIG_FILE} is not one of ${TRANSPORTS.join(', ')}`,
+    fix: `set realtime: { transport: 'memory' } in ${APP_CONFIG_FILE}, or { transport: 'nats', urlEnv: 'NATS_URL' } for more than one node`,
+    meta: { key: 'realtime.transport' },
+  });
+}
+
+/**
+ * The section as the boot obeys it. A key the file does not name keeps core's default, the same
+ * per-key merge `defineConfig` performs, so the boot and the app's own config object agree.
+ */
+export async function loadRealtimeConfig(root: string): Promise<RealtimeConfig> {
+  const path = join(root, APP_CONFIG_FILE);
+  if (!(await Bun.file(path).exists())) return REALTIME_DEFAULTS;
+  const module = (await import(path)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  const section = isRecord(config) ? config['realtime'] : undefined;
+  if (!isRecord(section)) return REALTIME_DEFAULTS;
+  const { enabled, urlEnv } = section;
+  return {
+    enabled: typeof enabled === 'boolean' ? enabled : REALTIME_DEFAULTS.enabled,
+    transport: transportOf(section),
+    urlEnv: typeof urlEnv === 'string' && urlEnv.trim() !== '' ? urlEnv.trim() : undefined,
+  };
+}

package/src/{dev-replica.ts → runtime-replica.ts}

@@ -6,7 +6,7 @@
 //
 // 1. `defaultClient()` is the one place db composes `replicatedClient(primary, replica)` from
 //    `DATABASE_REPLICA_URL`, and it runs only from `baseClient()` — "the client an app installed
-//    none for". Every process the framework boots installs one: `dev-queue.ts` calls
+//    none for". Every process the framework boots installs one: `runtime-queue.ts` calls
 //    `setDbClient(createPgliteClient(…) | createPostgresClient({ url }))`, so `defaultClient()` was
 //    unreachable from `x dev`, from `apps/web/server.ts` and from every container role.
 // 2. Routing needs an OPEN scope as well as a configured replica, and nothing opened one.
@@ -24,7 +24,7 @@ import {
   withReplicaReads,
 } from '@ultimat3/db';
 import type { Middleware } from '@ultimat3/http';
-import type { ServiceBinding } from './dev-services';
+import type { ServiceBinding } from './runtime-bindings';
 import type { RuntimeOverrides } from './runtime-overrides';
 
 export type ReplicaEnv = Readonly<Record<string, string | undefined>>;

package/src/{dev-runtime.ts → runtime-services.ts}

@@ -1,4 +1,4 @@
-// Starting the services `dev-services.ts` resolved. Resolution answers "which database"; this
+// Starting the services `runtime-bindings.ts` resolved. Resolution answers "which database"; this
 // answers "it is running, and every ambient accessor in the framework now points at it" — so
 // `db()`, `jobDriver()`, `mailDriver()` and the realtime transport are the objects a production
 // boot installs, only backed by embedded drivers.
@@ -10,6 +10,7 @@ import type { PurgeDriver } from '@ultimat3/cache';
 import { isNoopPurgeDriver, selectPurgeDriver } from '@ultimat3/cache';
 import {
   isLocal,
+  type RealtimeConfig,
   registerReadinessCheck,
   renderThrowable,
   resolveEnvironment,
@@ -30,15 +31,17 @@ import type { Transport, TransportSelection } from '@ultimat3/realtime/server';
 import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
-import { loadCacheTiers, startCacheTiers } from './dev-cache';
-import { loadInboxRetention } from './dev-notify-retention';
-import { installRetentionSweep } from './dev-purge';
-import type { DevDbClient } from './dev-queue';
-import { pgExecutorFor, startQueue } from './dev-queue';
-import type { DevServices, Env } from './dev-services';
 import { LocalDiskUnsafeError, StorageUnwritableError } from './errors';
 import { msg } from './messages';
+import type { DevServices, Env } from './runtime-bindings';
+import { loadCacheTiers, startCacheTiers } from './runtime-cache';
+import { loadWorkerConfig, type WorkerConfig } from './runtime-jobs';
+import { loadInboxRetention } from './runtime-notify-retention';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { installRetentionSweep } from './runtime-purge';
+import type { DevDbClient } from './runtime-queue';
+import { pgExecutorFor, startQueue } from './runtime-queue';
+import { loadRealtimeConfig } from './runtime-realtime';
 
 export interface RunningServices {
   readonly services: DevServices;
@@ -48,6 +51,17 @@ export interface RunningServices {
   readonly outbox: OutboxStore;
   readonly events: EventBus;
   readonly transport: Transport;
+  /**
+   * `app.config.ts`'s `realtime` section as this boot obeyed it. `transport` and `urlEnv` chose
+   * `transport` above; `enabled` is what `startRoles` reads before it starts `sync` or a replicator.
+   */
+  readonly realtime: RealtimeConfig;
+  /**
+   * `app.config.ts`'s `jobs.queues` / `concurrency` / `visibilityTimeoutMs`, for the `worker` role.
+   * Optional because a `RunningServices` can be hand-built, and a test runtime with none keeps the
+   * worker's own defaults — the answer it always got. `startServices` always sets it.
+   */
+  readonly workerConfig?: WorkerConfig;
   readonly storage: Storage;
   readonly mail: MailDriver;
   /**
@@ -193,8 +207,13 @@ export function startStorage(services: DevServices, env: Env, override?: Storage
   // `usesDevStorageSecret({ env })` left bare, refuse a boot whose own env carries a real
   // `STORAGE_SIGNING_SECRET` because the PROCESS does not. Which environment, whether a secret
   // exists, and the name the message prints are one question about one table.
-  if (!isLocal({ env }) && usesDevStorageSecret({ env })) {
-    throw new LocalDiskUnsafeError({ environment: resolveEnvironment({ env }), root });
+  // `fallback: 'production'` on both, the reading `localDriver` itself takes: a boot that names no
+  // environment is not a development one, and this message beats the driver's to it.
+  if (!isLocal({ env, fallback: 'production' }) && usesDevStorageSecret({ env })) {
+    throw new LocalDiskUnsafeError({
+      environment: resolveEnvironment({ env, fallback: 'production' }),
+      root,
+    });
   }
   try {
     mkdirSync(root, { recursive: true });
@@ -293,12 +312,15 @@ export async function startServices(
   // Same reason, same place: building a purge driver reads env and dials nothing, so a half-set
   // `FASTLY_API_TOKEN` without its service id fails here rather than on the first stale page.
   const cdn = selectPurgeDriver(env);
-  // Third of the same kind. `NATS_URL` selects the bus rather than quietly keeping the in-process
-  // one — dev pointed at compose is a parity check, and a parity check that silently ran the
-  // embedded driver is worse than none. Which transport, which KV bucket and which presence TTL is
-  // `@ultimat3/realtime`'s decision, and it is the same call a `ROLE=sync` container makes, so this
-  // process cannot resolve the bus differently from the container it stands in for.
-  const bus: TransportSelection = selectTransport(env);
+  // Third of the same kind. `realtime.transport` selects the bus and `realtime.urlEnv` names the
+  // variable holding its url; a config and an environment that disagree refuse here, before any
+  // service starts, rather than quietly keeping the in-process bus. Which transport, which KV
+  // bucket and which presence TTL is `@ultimat3/realtime`'s decision, and it is the same call a
+  // `ROLE=sync` container makes, so this process cannot resolve the bus differently from the
+  // container it stands in for. The root is `dirname(stateDir)`, as `loadCacheTiers` reads it.
+  const realtime = await loadRealtimeConfig(dirname(services.stateDir));
+  const workerConfig = await loadWorkerConfig(dirname(services.stateDir));
+  const bus: TransportSelection = selectTransport(env, realtime);
   // `env`, not the ambient one: this function is HANDED the boot's environment and every other
   // reader here already uses it, so a queue that asked `process.env` would decide the standby from
   // a different answer than the middleware that routes to it.
@@ -335,7 +357,7 @@ export async function startServices(
     // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
     //
-    // `inboxRetention` is READ HERE and not defaulted in `dev-purge.ts`: the two windows are the
+    // `inboxRetention` is READ HERE and not defaulted in `runtime-purge.ts`: the two windows are the
     // app's, `startServices` holds no `AppConfig`, and a loader that silently answered "never
     // sweep" from inside the sweep would be indistinguishable from an app that chose it.
     started.push(
@@ -347,7 +369,7 @@ export async function startServices(
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
     // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and
-    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `dev-roles.ts` calls it
+    // `packages/http/src/server.ts` calls that BEFORE `Bun.serve`, while `role-start.ts` calls it
     // before `sync`, `worker` and `scheduler` start. The chart's `readinessProbe` and the container
     // healthcheck both route on it, so a replica whose pool was gone kept taking traffic.
     started.push(probedReadinessCheck('database', () => db.ping()));
@@ -399,6 +421,8 @@ export async function startServices(
       outbox,
       events,
       transport,
+      realtime,
+      workerConfig,
       storage,
       mail,
       mailDetail: selection.detail,

package/src/{dev-storage.ts → runtime-storage.ts}

@@ -1,6 +1,6 @@
 // Single responsibility: the one HTTP surface that SERVES a stored object. `@ultimat3/storage`
 // owns keys, bytes and the tenant boundary and owns no `Response`; `@ultimat3/policy` owns the
-// one authz decision; this file is where those two meet a `Route` — the same shape `dev-assets.ts`
+// one authz decision; this file is where those two meet a `Route` — the same shape `runtime-assets.ts`
 // uses for `/icons` and `/media`, so `x dev` and `apps/web/server.ts` mount one read path, not two.
 //
 // The base path is `@ultimat3/storage`'s `DEFAULT_SIGNED_URL_BASE`, imported and never restated:
@@ -37,7 +37,7 @@ export const STORAGE_READ_PERMISSION = 'storage:read';
  * augments `PermissionRegistry` — and this package compiles against no app, so the bare literal is
  * a type error inside a generated project (`scaffold-typecheck` is what proves it). The check that
  * decides is the runtime one anyway: `can()` calls `assertPermission`, which throws
- * `X_PERMISSION_UNKNOWN` naming the `definePermissions` edit. `dev-hooks.ts` narrows a route's
+ * `X_PERMISSION_UNKNOWN` naming the `definePermissions` edit. `runtime-hooks.ts` narrows a route's
  * structurally-typed permission for the same reason.
  */
 const READ_PERMISSION = STORAGE_READ_PERMISSION as unknown as KnownPermission;
@@ -94,7 +94,7 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
  * (never 403 — `error-map.ts` maps `X_STORAGE_ORG_MISMATCH` there so a refusal cannot confirm that
  * a key exists).
  *
- * Split out of `readStorageObject` because `/media/*key` (`dev-assets.ts`) has to make the same
+ * Split out of `readStorageObject` because `/media/*key` (`runtime-assets.ts`) has to make the same
  * decision and made none at all: it passed a client-supplied key straight to `disk().get`, so every
  * object on the app's only disk was one unauthenticated URL away. A second copy of this test is how
  * one of the two surfaces would drift back — `storage-surfaces.test.ts` is what holds them level.
@@ -198,7 +198,7 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
     headers.set('content-range', `bytes */${size}`);
     return new Response(null, { status: 416, headers });
   }
-  // Copied at each call, not through a helper, for `dev-assets.ts`'s reason: a
+  // Copied at each call, not through a helper, for `runtime-assets.ts`'s reason: a
   // `Uint8Array<ArrayBufferLike>` may be backed by a `SharedArrayBuffer`, which `Response` does
   // not accept — and a helper's declared return type widens the copy back to the type it refuses.
   if (range === undefined) {

package/src/scaffold-fixture.ts

@@ -46,6 +46,16 @@ export async function list(limit = 50): Promise<readonly ShortLink[]> {
 }
 `;
 
+/**
+ * The `invoice` resource's own `entity.ts`, as `x g` would read it off disk after the resource
+ * below ran — the generators writing INTO that slice are handed it, because a slice with no entity
+ * now gets the neutral body and no invented table.
+ */
+export const INVOICE_ENTITY = String(
+  generate({ kind: 'entity', name: 'invoice' }).find((file) => file.path.endsWith('/entity.ts'))
+    ?.contents,
+);
+
 /**
  * One realistic invocation of every generator, on top of `x new --example`. Names differ from
  * their feature on purpose: `x g query invoice --feature invoice` would collide with the entity
@@ -59,19 +69,31 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'resource', name: 'invoice', admin: true },
   { kind: 'entity', name: 'credit-note', feature: 'credit-note' },
   { kind: 'policy', name: 'credit-note', feature: 'credit-note' },
-  { kind: 'action', name: 'send-invoice', feature: 'invoice' },
-  { kind: 'mutator', name: 'rename-invoice', feature: 'invoice' },
+  { kind: 'action', name: 'send-invoice', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
+  { kind: 'mutator', name: 'rename-invoice', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   // The other shape both templates have: a slice whose `errors.ts` is the author's and declares
   // no `InvoiceNotFoundError`. The resource's own `errors.ts` still lands in the sandbox (it does
   // declare one), which is the point — this compiles the file `x g action` writes when it must
   // not import that class, beside the one it writes when it may.
-  { kind: 'action', name: 'ping-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
-  { kind: 'mutator', name: 'touch-invoice', feature: 'invoice', sliceErrors: HANDWRITTEN_ERRORS },
+  {
+    kind: 'action',
+    name: 'ping-invoice',
+    feature: 'invoice',
+    sliceErrors: HANDWRITTEN_ERRORS,
+    sliceEntity: INVOICE_ENTITY,
+  },
+  {
+    kind: 'mutator',
+    name: 'touch-invoice',
+    feature: 'invoice',
+    sliceErrors: HANDWRITTEN_ERRORS,
+    sliceEntity: INVOICE_ENTITY,
+  },
   { kind: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
-  { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },
+  { kind: 'job', name: 'sweep-invoices', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   { kind: 'backfill', name: 'reindex-invoices', feature: 'invoice' },
-  { kind: 'task', name: 'nightly-sweep', feature: 'invoice' },
+  { kind: 'task', name: 'nightly-sweep', feature: 'invoice', sliceEntity: INVOICE_ENTITY },
   // The other shape both templates have: a feature whose entity names no tenant column, so the
   // job/task must not assume one — compiled here beside the tenant-scoped pair above, exactly as
   // `ping-invoice`/`touch-invoice` compile the action's other shape beside `send-invoice`.

package/src/scaffold-typecheck.ts

@@ -146,11 +146,14 @@ const overlay = (root: string, app: string): string =>
       compilerOptions: {
         noEmit: true,
         paths: {
-          // The two subpath exports a generated app reaches for, spelled the way the packages'
-          // own `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a
-          // package name. Longest prefix wins, so these are consulted first.
+          // The subpath exports a generated app reaches for, spelled the way the packages' own
+          // `exports` maps spell them — the wildcard below would read `ui/icons/zap` as a package
+          // name, and `cli/serve` as `packages/cli/serve`. Longest prefix wins, so these are
+          // consulted first. `@ultimat3/cli/serve` is what `x new`'s `apps/web/server.ts` imports.
           '@ultimat3/ui/icons/*': [`${root}/packages/ui/src/icons/glyphs/*`],
           '@ultimat3/render/server': [`${root}/packages/render/src/server`],
+          '@ultimat3/cli/serve': [`${root}/packages/cli/src/serve-entry`],
+          '@ultimat3/testing/test-types': [`${root}/packages/testing/src/test-types`],
           '@ultimat3/*': [`${root}/packages/*/src`],
           [`@${app}/web/*`]: ['./apps/web/*'],
           [`@${app}/admin/*`]: ['./apps/admin/*'],

package/src/schema-drift.ts

@@ -89,8 +89,14 @@ function repairFix(
  * never get what the app declares; `undeclared` means the database holds what nothing declares.
  * One "drift" verdict over both teaches a reader neither.
  */
+/** A table difference names the table once: `table "customers" on table "customers"` did not. */
+export const schemaDifferenceCause = (difference: SchemaDifference): string =>
+  difference.part === 'table'
+    ? `table "${difference.table}" ${difference.detail}`
+    : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
+
 function findingFor(difference: SchemaDifference, fix: string): Finding {
-  const cause = `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
+  const cause = schemaDifferenceCause(difference);
   return difference.direction === 'unmigrated'
     ? { code: 'X_DB_SCHEMA_UNMIGRATED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR }
     : { code: 'X_DB_SCHEMA_UNDECLARED', cause, fix, docs: ERROR_DOCS_URL, at: MIGRATIONS_DIR };

package/src/script-csp.ts

@@ -5,7 +5,7 @@
 // invisible in `x dev`, where the policy is report-only.
 
 import { cspHashSource } from '@ultimat3/http';
-import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
+import { HYDRATE_RUNTIME_BODIES, STREAM_REVEAL_BODIES } from '@ultimat3/render';
 
 /**
  * Hashes, never a nonce: a `render: 'static'` page is a file on disk, so no per-response value can
@@ -16,5 +16,8 @@ import { HYDRATE_RUNTIME_BODIES } from '@ultimat3/render';
  * which `theme-boot.ts` derives from the same string it inlines.
  */
 export function inlineScriptSources(extra: readonly string[] = []): readonly string[] {
-  return [...new Set([...HYDRATE_RUNTIME_BODIES.map(cspHashSource), ...extra])].sort();
+  // The stream reveal too: a `render: 'stream'` page swaps each Suspense boundary in with a
+  // constant inline `$X()` call, and unhashed it is blocked under the enforced policy.
+  const bodies = [...HYDRATE_RUNTIME_BODIES, ...STREAM_REVEAL_BODIES];
+  return [...new Set([...bodies.map(cspHashSource), ...extra])].sort();
 }

package/src/secrets-rotation.ts

@@ -0,0 +1,59 @@
+// A master-key rotation in an order a crash cannot turn into data loss. The new key is STAGED at
+// `<key>.next` (0600) before anything is sealed with it, the committed file is sealed second, and
+// the rename that makes the new key live is last. Interrupted anywhere, some key on disk opens the
+// committed file — and `recoverRotation`, which every `x secrets` command runs first, finishes or
+// abandons the move by asking the file which key it answers to.
+
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'; // why: the staged key is written and renamed synchronously at 0600, and Bun has no mode-setting write or rename.
+import type { MasterKeyRef, SecretValues } from '@ultimat3/core';
+import {
+  generateMasterKey,
+  isUltimateError,
+  masterKeyPath,
+  readSecretsFile,
+  SECRETS_KEY_MODE,
+  stagedMasterKeyPath,
+  writeSecretsFile,
+} from '@ultimat3/core';
+
+const fileKey = (root: string, hex: string): MasterKeyRef => ({
+  hex,
+  source: 'file',
+  at: masterKeyPath(root),
+});
+
+/** Stage, seal, then make live. Returns the key now in force. */
+export async function rotateMasterKey(root: string, values: SecretValues): Promise<MasterKeyRef> {
+  const staged = stagedMasterKeyPath(root);
+  const hex = generateMasterKey();
+  rmSync(staged, { force: true });
+  // `wx`: the mode applies only when a write CREATES the file, and a leftover could be 0644.
+  writeFileSync(staged, `${hex}\n`, { encoding: 'utf-8', mode: SECRETS_KEY_MODE, flag: 'wx' });
+  const next = fileKey(root, hex);
+  await writeSecretsFile(root, values, next);
+  renameSync(staged, masterKeyPath(root));
+  return next;
+}
+
+/**
+ * A staged key left by an interrupted rotation: whichever of the two keys opens the committed file
+ * is the live one. The staged key wins only by opening it, and is then moved into place; otherwise
+ * it never sealed anything and is dropped. With no staged key this is `key`, unchanged.
+ */
+export async function recoverRotation(root: string, key: MasterKeyRef): Promise<MasterKeyRef> {
+  const staged = stagedMasterKeyPath(root);
+  if (!existsSync(staged)) return key;
+  try {
+    await readSecretsFile(root, key);
+    rmSync(staged, { force: true });
+    return key;
+  } catch (error) {
+    if (!isUltimateError(error) || error.code !== 'X_SECRETS_KEY_MISMATCH') throw error;
+    const candidate = fileKey(root, readFileSync(staged, 'utf-8').trim());
+    // Throws the staged key's own mismatch when neither opens it — the committed file's problem,
+    // which `X_SECRETS_KEY_MISMATCH`'s fix (restore it from git) answers.
+    await readSecretsFile(root, candidate);
+    renameSync(staged, masterKeyPath(root));
+    return candidate;
+  }
+}