@ultimat3/cli 23.0.0 → 25.0.0

package/src/runtime-storage.ts

@@ -7,12 +7,12 @@
 // `localDriver` SIGNS `/_storage/<disk>/<key>`, so a local `'/_storage'` here is a second statement
 // of one constant — and a signer and a reader that disagree serve 404 for every signed URL.
 
-import { actorOf } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
+import { actorOf } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { asCtx, unauthenticated } from '@ultimat3/http';
 import type { KnownPermission } from '@ultimat3/policy';
-import { can, codeOf, evaluate, forbidden, reasonOf } from '@ultimat3/policy';
+import { can, codeOf, evaluate, policyForbidden, reasonOf } from '@ultimat3/policy';
 import type { Storage, StorageRead } from '@ultimat3/storage';
 import {
   assertSafeKey,
@@ -24,6 +24,7 @@ import {
   orgMismatch,
 } from '@ultimat3/storage';
 import { storageUploadRoute } from './runtime-storage-upload';
+import { storedObjectHeaders } from './stored-object-headers';
 
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
@@ -87,7 +88,7 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
   const reason = reasonOf(evaluation.decision) ?? 'denied';
   throw codeOf(evaluation.decision) === 'X_UNAUTHENTICATED'
     ? unauthenticated(ctx.url.pathname)
-    : forbidden(policy.label, reason);
+    : policyForbidden(policy.label, reason);
 }
 
 /**
@@ -103,11 +104,10 @@ export function authorizeStorageRead(input: StorageReadInput, ctx: RequestContex
  */
 export function assertReadableKey(key: string, actor: Actor): string {
   const safe = assertSafeKey(key);
-  // An actor with no org is inside no org, so every tenant-scoped key is somebody else's. Checked
-  // before `isWithinOrg`, which reads an empty org as a malformed key and would blame the caller's
-  // URL for the actor's missing claim.
+  // An actor with no org is inside no org, so every tenant-scoped key is somebody else's —
+  // `isWithinOrg` answers exactly that for an empty org, without throwing.
   const orgId = actor.orgId ?? '';
-  if (isTenantScoped(safe) && (orgId === '' || !isWithinOrg(safe, orgId))) {
+  if (isTenantScoped(safe) && !isWithinOrg(safe, orgId)) {
     throw orgMismatch(safe, orgId);
   }
   return safe;
@@ -185,9 +185,14 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
   const headers = new Headers({
     'content-type': read.object.contentType,
     etag,
-    'last-modified': read.object.lastModified.toUTCString(),
     'accept-ranges': 'bytes',
+    // A type a browser would RUN (html, svg, xml) is a download, never a page on this origin.
+    ...storedObjectHeaders(read.object.contentType),
   });
+  // Omitted, never invented: a disk whose provider reported no date has none, and a `Last-Modified`
+  // made up for it is a validator a cache would go on to trust.
+  const modified = read.object.lastModified;
+  if (modified !== undefined) headers.set('last-modified', modified.toUTCString());
   // Revalidation costs a request and no bytes, which is the trade an authorized response wants:
   // the bytes never change under a key, but the actor's permission to read them can be revoked.
   if (etagMatches(request.header('if-none-match'), etag)) {

package/src/schema-diff.ts

@@ -40,6 +40,11 @@ export interface SchemaDifference {
 
 const DECLARED_ONLY = 'is declared by the entities and no migration recorded it';
 const RECORDED_ONLY = 'was recorded by the newest migration and no entity declares it';
+/** The difference's name — what `x db gen "record …"` is told to write down. */
+const REPLICA_IDENTITY_FULL = 'replica identity full';
+const REPLICA_IDENTITY_UNRECORDED =
+  'needs REPLICA IDENTITY FULL — a channel with params routes deletes by its old row — and no ' +
+  'migration recorded it';
 
 const columns = (names: readonly string[]): string => names.join(', ');
 
@@ -187,6 +192,17 @@ function compareTable(declared: TableDescription, recorded: TableDescription): S
       detail: `declares primary key (${columns(declared.primaryKey)}) and the migration recorded (${columns(recorded.primaryKey)})`,
     });
   }
+  // One direction: `replica-identity.ts` never reverts the identity, so a recorded FULL nothing
+  // needs any more is what `x db gen` leaves behind on purpose, not a difference.
+  if (declared.replicaIdentityFull === true && recorded.replicaIdentityFull !== true) {
+    out.push({
+      direction: 'unmigrated',
+      part: 'table',
+      table,
+      name: REPLICA_IDENTITY_FULL,
+      detail: REPLICA_IDENTITY_UNRECORDED,
+    });
+  }
   out.push(
     ...compareList({
       part: 'column',

package/src/schema-drift.ts

@@ -15,10 +15,15 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { EntityDescriptionLike, UnrenderedDeclaration } from '@ultimat3/db';
-import { declaredSchema, snapshotOf, unrenderedOf } from '@ultimat3/db';
+import { declaredSchema, shellInertIdentifier, snapshotOf, unrenderedOf } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
 import { loadApp } from './app-load';
 import { checkSourceDrift, DB_PACKAGE } from './drift';
+import {
+  appReplicaIdentity,
+  type ReplicaIdentityWanted,
+  wantedReplicaIdentity,
+} from './drift-replica-identity';
 import { MIGRATIONS_DIR, readMigrations } from './migrations';
 import type { Finding } from './output';
 import { diffDeclaredSchema, type SchemaDifference } from './schema-diff';
@@ -50,10 +55,17 @@ const appEntities: DeclaredEntities = async (root) => {
  * silently and the result is green. In that state the unrendered entry's own `fix:` is the
  * instruction: `@ultimat3/db` owns that wording, and a second one here would drift from it.
  */
+interface Repair {
+  /** One runnable command or one edit — never a second option behind a shell comment. */
+  readonly fix: string;
+  /** Why this fix and not the obvious one, appended to the cause where the reader sees it. */
+  readonly why?: string;
+}
+
 function repairFix(
   unrendered: readonly UnrenderedDeclaration[],
   difference: SchemaDifference,
-): string {
+): Repair {
   // The entry ABOUT this difference first, then any entry at all. Reading `unrendered[0]`
   // unconditionally meant that in any app carrying an unrendered DEFAULT, every difference —
   // a dropped CHECK included — was answered with the default's edit, which is an instruction for
@@ -62,7 +74,7 @@ function repairFix(
     (entry) => entry.table === difference.table && entry.name === difference.name,
   );
   // The entry ABOUT this difference carries the edit that repairs it, so it is the whole answer.
-  if (named !== undefined) return named.fix;
+  if (named !== undefined) return { fix: named.fix };
   // Otherwise `x db gen` is still unsafe — it would drop what the other entries name — but the
   // reader must NOT be handed a different declaration's edit as the instruction for this one.
   // Reading `unrendered[0]` did exactly that: a column default and an index each got
@@ -72,16 +84,26 @@ function repairFix(
   // app — not only for the one the entry names.
   const blocker = unrendered[0];
   if (blocker !== undefined) {
-    return `${blocker.fix}   # ${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it; repair that before recording ${difference.name}`;
+    return {
+      fix: blocker.fix,
+      why: `${blocker.table}.${blocker.name} reaches no SQL, so regenerating would drop it — repair that before recording ${difference.name}`,
+    };
   }
   // "record", not "add": one finding covers a declaration the migrations never carried AND one they
-  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` gets
-  // both branches, in the order they are safe — regenerating emits the DROP, and the declaration
-  // may have been LOST rather than removed, which is the whole reason this direction is its own
-  // finding.
-  return difference.direction === 'unmigrated'
-    ? `x db gen "record ${difference.name}"`
-    : `x db gen "drop ${difference.name}"   # or re-declare ${difference.name} on the entity`;
+  // carry differently, so `add` would be a wrong migration name for half of them. `undeclared` runs
+  // the DROP, and the other branch — the declaration may have been LOST rather than removed, which
+  // is the whole reason this direction is its own finding — rides in the cause: a `fix:` is one
+  // command, and a `# or …` after it was a shell comment nobody's paste would run.
+  if (difference.direction === 'unmigrated') return { fix: `x db gen "record ${difference.name}"` };
+  // The name was read off a sidecar on disk and lands inside double quotes, where `$(…)` and a
+  // backtick still run: one the shell would act on is named in the cause only, never the command.
+  const inert = shellInertIdentifier(difference.name) !== null;
+  return {
+    fix: inert
+      ? `x db gen "drop ${difference.name}"`
+      : 'x db gen "drop what the entities no longer declare"',
+    why: `if ${difference.name} was lost rather than removed, re-declare it on the entity instead — this command drops it`,
+  };
 }
 
 /**
@@ -95,8 +117,10 @@ export const schemaDifferenceCause = (difference: SchemaDifference): string =>
     ? `table "${difference.table}" ${difference.detail}`
     : `${difference.part} "${difference.name}" on table "${difference.table}" ${difference.detail}`;
 
-function findingFor(difference: SchemaDifference, fix: string): Finding {
-  const cause = schemaDifferenceCause(difference);
+function findingFor(difference: SchemaDifference, repair: Repair): Finding {
+  const { fix } = repair;
+  const stated = schemaDifferenceCause(difference);
+  const cause = repair.why === undefined ? stated : `${stated} — ${repair.why}`;
   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 };
@@ -114,6 +138,7 @@ function findingFor(difference: SchemaDifference, fix: string): Finding {
 export async function checkSnapshotDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
   if (!existsSync(join(root, DB_PACKAGE))) return [];
   const entities = await declared(root);
@@ -122,7 +147,11 @@ export async function checkSnapshotDrift(
   if (migrations.length === 0) return [];
   const recorded = declaredSchema(migrations);
   if (recorded === undefined) return [];
-  const differences = diffDeclaredSchema(snapshotOf(entities), recorded);
+  // Read only over a WHOLE registry (`entities` is `undefined` otherwise), the rule `x db gen`
+  // states for the same call: a short one makes every subscribed name in the missing module a typo.
+  const wanted = wantedReplicaIdentity(identity, new Set(entities.map((entity) => entity.table)));
+  if ('finding' in wanted) return [wanted.finding];
+  const differences = diffDeclaredSchema(snapshotOf(entities, wanted.tables), recorded);
   if (differences.length === 0) return [];
   // `recorded` and not the entities alone: whether an `assert` is a LOSS depends on whether a
   // migration recorded a CHECK for it, which only the sidecar knows.
@@ -145,8 +174,9 @@ export async function checkMigrationDrift(
   root: string,
   declared: DeclaredEntities = appEntities,
   hashDrift: (root: string) => Promise<readonly Finding[]> = checkSourceDrift,
+  identity: ReplicaIdentityWanted = appReplicaIdentity,
 ): Promise<readonly Finding[]> {
-  const snapshot = await checkSnapshotDrift(root, declared);
+  const snapshot = await checkSnapshotDrift(root, declared, identity);
   if (snapshot.length > 0) return snapshot;
   return hashDrift(root);
 }

package/src/secrets-rotation.ts

@@ -1,18 +1,19 @@
 // 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
+// `<key>.next` (owner-only: 0600, and an ACL on Windows) 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 { existsSync, readFileSync, rmSync } from 'node:fs'; // why: Bun has no sync exists/remove; the key is WRITTEN and RENAMED only by core's owner-only writers.
 import type { MasterKeyRef, SecretValues } from '@ultimat3/core';
 import {
   generateMasterKey,
   isUltimateError,
   masterKeyPath,
+  promoteStagedMasterKey,
   readSecretsFile,
-  SECRETS_KEY_MODE,
   stagedMasterKeyPath,
+  stageMasterKeyFile,
   writeSecretsFile,
 } from '@ultimat3/core';
 
@@ -24,14 +25,12 @@ const fileKey = (root: string, hex: string): MasterKeyRef => ({
 
 /** 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' });
+  // A fresh temp file renamed over any leftover: a staged key left 0644 is replaced, never reused.
+  stageMasterKeyFile(root, hex);
   const next = fileKey(root, hex);
   await writeSecretsFile(root, values, next);
-  renameSync(staged, masterKeyPath(root));
+  promoteStagedMasterKey(root);
   return next;
 }
 
@@ -53,7 +52,7 @@ export async function recoverRotation(root: string, key: MasterKeyRef): Promise<
     // 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));
+    promoteStagedMasterKey(root);
     return candidate;
   }
 }

package/src/seo-routes.ts

@@ -1,11 +1,14 @@
-// `GET /robots.txt` and `GET /sitemap.xml` from a running web role — the files the static export
-// writes, answered by the process for a deploy that serves its pages from a container. Mounted by
-// `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
+// `GET /robots.txt`, `GET /sitemap.xml` and its parts (`/sitemaps/<n>.xml`) from a running web
+// role — the files the static export writes, for a deploy that serves its pages from a container.
+// Mounted by `x dev` and `runRole` alike, before the app's pages, for `style-routes.ts`' reason.
 
 import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse, NO_STORE } from '@ultimat3/http';
+import { SITEMAP_PARTS_DIR } from '@ultimat3/seo';
+import { quoteArg } from './shell-quote';
 import { NO_SITE_SETTINGS, publicOrigin, type SiteSettings } from './site-config';
+import type { SiteSeo } from './site-seo';
 import { ROBOTS_PATH, SITEMAP_PATH, siteSeo } from './site-seo';
 
 export interface SeoRoutesOptions {
@@ -26,22 +29,57 @@ function originOf(options: SeoRoutesOptions, request: UltimateRequest): string {
 }
 
 /**
- * Per request, never cached across one: `prerender()` may enumerate rows that change, and a
- * crawler asks for these a handful of times a day. An hour of shared cache is what a CDN keeps.
+ * An hour of shared cache is what a CDN keeps of either file, and what this process keeps of the
+ * answer behind both. `prerender()` may enumerate rows that change, so the memo is never longer
+ * than the response's own `max-age` — a crawler that bypasses the CDN sees what one behind it
+ * would. Before it, every `/robots.txt` hit recomputed the whole sitemap, each dynamic route's
+ * `prerender()` included.
  */
 const SEO_CACHE = { mode: 'public', maxAgeSeconds: 3600 } as const;
 
+/**
+ * Origins remembered at once. With no declared origin the request's own is the key, and a `Host`
+ * header is the caller's to choose — so the memo is bounded, oldest out first.
+ */
+const SEO_MEMO_ORIGINS = 8;
+
+interface Memo {
+  readonly at: number;
+  readonly answer: Promise<SiteSeo>;
+}
+
 export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
   const environment: Environment =
     tryResolveEnvironment({ env: options.env }) ?? DEFAULT_ENVIRONMENT;
-  const answer = async (request: UltimateRequest) =>
-    await siteSeo({
-      baseUrl: originOf(options, request),
+  const compute = (baseUrl: string): Promise<SiteSeo> =>
+    siteSeo({
+      baseUrl,
       environment,
       disallow: options.site?.disallow ?? [],
       ...(options.site === undefined ? {} : { sitemap: options.site.sitemap }),
       ...(options.root === undefined ? {} : { root: options.root }),
     });
+  // Single-flight per origin: concurrent requests share the one computation in progress. A failed
+  // one is dropped, so the next request asks again rather than serving the failure for an hour.
+  const memo = new Map<string, Memo>();
+  const answer = (request: UltimateRequest): Promise<SiteSeo> => {
+    const origin = originOf(options, request);
+    const now = Date.now();
+    const kept = memo.get(origin);
+    if (kept !== undefined && now - kept.at < SEO_CACHE.maxAgeSeconds * 1000) return kept.answer;
+    memo.delete(origin);
+    if (memo.size >= SEO_MEMO_ORIGINS) {
+      const oldest = memo.keys().next().value;
+      if (oldest !== undefined) memo.delete(oldest);
+    }
+    const computed = compute(origin);
+    memo.set(origin, { at: now, answer: computed });
+    // Voided: the request awaits `computed` itself and reports its failure; this branch only forgets it.
+    void computed.catch(() => {
+      if (memo.get(origin)?.answer === computed) memo.delete(origin);
+    });
+    return computed;
+  };
 
   return [
     {
@@ -69,5 +107,38 @@ export function seoRoutes(options: SeoRoutesOptions): readonly Route[] {
           SEO_CACHE,
         ),
     },
+    {
+      method: 'GET',
+      path: `${SITEMAP_PARTS_DIR}/:file`,
+      meta: { name: 'seo.sitemapPart', auth: 'public', tags: ['seo'] },
+      // A part of a split sitemap, from the same answer the index came from — so a part the index
+      // names always exists here, and the static export writes the same paths.
+      handler: async (request: UltimateRequest): Promise<Response> => {
+        const seo = await answer(request);
+        const part = seo.sitemaps.find((file) => file.path === request.pathname);
+        if (part !== undefined && part.path !== SITEMAP_PATH) {
+          return applyCacheHeaders(
+            new Response(part.xml, {
+              headers: { 'content-type': 'application/xml; charset=utf-8' },
+            }),
+            SEO_CACHE,
+          );
+        }
+        const index = new URL(SITEMAP_PATH, originOf(options, request)).href;
+        const missing = jsonResponse(
+          {
+            ok: false,
+            error: {
+              code: 'X_ROUTE_NOT_FOUND',
+              cause: `${request.pathname} is no part of this site's sitemap: the index names ${String(Math.max(seo.sitemaps.length - 1, 0))} part(s)`,
+              fix: `curl -sS ${quoteArg(index)}`,
+            },
+          },
+          { status: 404 },
+        );
+        // `no-store`: the part may exist once the site grows, and a cached miss would hide it.
+        return applyCacheHeaders(missing, NO_STORE);
+      },
+    },
   ];
 }

package/src/serve-boot.ts

@@ -5,16 +5,18 @@
 // (`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';
+import { releaseOrThrow, startServices } from './runtime-services';
 import { loadDrainConfig, loadHealthConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import { adoptPrebuiltStyles, reportBootBuilds, watchBootBuilds } from './serve-prebuilt';
@@ -42,6 +44,29 @@ 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
+ * `httpServer` 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).
+ *
+ * The budget (`deadlineMs`) is every role's: it is the time a worker's running job has to finish
+ * on a deploy, so it is the one key here a non-listening role needs MOST.
+ */
+export function lifecycleForRole(
+  role: Role,
+  drain: Partial<DrainConfig> | undefined,
+): LifecycleOptions {
+  const budget = drain?.deadlineMs === undefined ? {} : { deadlineMs: drain.deadlineMs };
+  if (!LISTENING_ROLES.includes(role)) return { readinessGraceMs: 0, ...budget };
+  return drain?.readinessGraceMs === undefined
+    ? budget
+    : { readinessGraceMs: drain.readinessGraceMs, ...budget };
+}
+
 /**
  * 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 +78,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 +110,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 +130,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 +143,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 });
@@ -155,11 +187,18 @@ async function bootRoles(boot: {
     running,
     runtime,
     async stop() {
-      await running.stop();
-      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.
-      stopOtlp();
+      // Every step runs and the first failure is rethrown (`releaseOrThrow`): a refused role stop
+      // used to leave the services, the PGlite lock and the exporter behind it. Listed in boot
+      // order, released newest first — the roles; then the web surface, after the server drained
+      // (a bust landing mid-drain still marks the pages it is serving); then the services; LAST
+      // the exporter, so the drain's own spans and the final counter snapshot still have
+      // somewhere to go.
+      await releaseOrThrow([
+        stopOtlp,
+        () => runtime.stop(),
+        () => web?.release(),
+        () => running.stop(),
+      ]);
     },
   };
 }

package/src/serve-drain.ts

@@ -1,41 +1,19 @@
-// `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, deadlineMs: drain.deadlineMs };
 }
 
-/**
- * `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;
 }