@ultimat3/cli 19.2.0 → 19.3.2

package/src/hold.ts

@@ -33,12 +33,15 @@ export interface HoldOptions {
  * handler opened them against. It is the resources core never learned about: the embedded
  * Postgres, the worker, the file watcher.
  *
- * It runs INSIDE the drain's own deadline, and that is not a detail. `drain()` ABANDONS a hook
- * that overruns `ShutdownReason.deadlineAt` — the process is meant to exit without it — and
- * `release` here re-enters the very same teardown one call later: `app.stop()` ->
- * `startRoles().stop()` -> `worker.stop()`, memoised in the package that owns it, so awaiting it
- * is awaiting the promise the drain just walked away from. Unbounded, that hangs forever and the
- * deadline buys nothing.
+ * It is BOUNDED, and that is not a detail. `drain()` ABANDONS a hook that overruns
+ * `ShutdownReason.deadlineAt` — the process is meant to exit without it — and `release` here
+ * re-enters the very same teardown one call later: `app.stop()` -> `startRoles().stop()` ->
+ * `worker.stop()`, memoised in the package that owns it, so awaiting it is awaiting the promise
+ * the drain just walked away from. Unbounded, that hangs forever and the deadline buys nothing.
+ *
+ * The bound is what is LEFT of the drain's budget, under a floor of `MIN_RELEASE_MS` — see there
+ * for why the remainder alone answered `0` on every busy pod and abandoned the teardown before it
+ * closed anything.
  */
 export function holdUntilShutdown(
   name: string,
@@ -48,8 +51,8 @@ export function holdUntilShutdown(
   const uninstall = installSignalHandlers({ exit: false });
   let unregister = (): void => {};
   // The hook's own `reason`, not a stopwatch of ours: `deadlineAt` is the instant core computed
-  // when the drain began, on the same real monotonic clock, so this budget IS the drain's budget
-  // rather than a second one that happens to be the same length.
+  // when the drain began, on the same real monotonic clock, so what is left of the drain's budget
+  // is read off the drain's own number and never off a second one of the same length.
   const shuttingDown = new Promise<number>((resolve) => {
     unregister = onShutdown(
       `cli:${name}:hold`,
@@ -71,7 +74,7 @@ export function holdUntilShutdown(
       await drain();
       unregister();
       uninstall();
-      await releaseWithin(name, release, deadlineAt - systemClock.monotonic());
+      await releaseWithin(name, release, releaseBudgetMs(deadlineAt - systemClock.monotonic()));
       options.exit?.(0);
     })();
     return held;
@@ -79,33 +82,63 @@ export function holdUntilShutdown(
 }
 
 /**
- * `release()` raced against what is left of the drain's budget.
+ * The floor under `release`'s budget, and the reason the drain's REMAINDER alone is the wrong one.
+ *
+ * The remainder is what is left of a budget that was spent on something else. A drain that used
+ * all of it — one request over budget is enough, and that is the ordinary shutdown on a busy pod —
+ * hands `release` a NEGATIVE number, `Math.max(0, …)` reads it as `0`, and `setTimeout(resolve, 0)`
+ * wins against any teardown whose first await is real work. Measured at `deadlineMs: 60` with one
+ * `beginWork()` outstanding: the release STARTED and was abandoned 0ms later, so `app.stop()` never
+ * reached the pool close, the NATS close, the cache tiers or the mail driver, and the outbox relay
+ * was abandoned somewhere between `driver.enqueue` and `markPublished` — a duplicate job on the
+ * next boot. The abandonment is not the harmless "exit slightly early" it was written as: it is
+ * every resource the process holds, left to the kernel.
+ *
+ * So `release` gets a budget of its own, floored, never a leftover. 5s, and the arithmetic is
+ * what makes it defensible rather than a feel: `DEFAULT_DEADLINE_MS` is 25s
+ * (`packages/core/src/lifecycle.ts`) and `docker/helm/templates/deployments.yaml` sets
+ * `terminationGracePeriodSeconds: 45`, so a drain that spends everything PLUS a release that
+ * spends everything is 30s — still inside the grace period, so the kubelet never SIGKILLs a
+ * process this floor kept alive. It stays a floor and not a clamp: an app that raised
+ * `deadlineMs` for a slow teardown keeps the bigger number.
+ */
+export const MIN_RELEASE_MS = 5_000;
+
+/**
+ * What `release` really gets. Non-finite is the floor rather than the input, for the reason
+ * `packages/core/src/lifecycle-bounds.test.ts` exists: `Math.max(n, NaN)` is `NaN` and
+ * `setTimeout(fn, NaN)` fires on the next tick, which is this whole defect a second time.
+ */
+export const releaseBudgetMs = (remainingMs: number): number =>
+  Number.isFinite(remainingMs) ? Math.max(MIN_RELEASE_MS, remainingMs) : MIN_RELEASE_MS;
+
+/**
+ * `release()` raced against its own budget.
  *
  * A local race and not core's `settleWithin`, which is internal to `lifecycle-deadline.ts` and not
  * on core's barrel. The semantics are deliberately the same, including the one that matters: a
  * REJECTION still rejects — `dispatch` awaits the hold inside its own `try`, and an embedded
  * database that would not close is a finding on the way out, never a clean exit over it.
- *
- * A budget already spent is `0`, and that abandons immediately by design: past `deadlineAt` the
- * orchestrator is already counting down to SIGKILL, so the honest move is to say so and exit
- * rather than to start a second grace period nobody granted.
  */
 async function releaseWithin(
   name: string,
   release: () => Promise<void>,
   budgetMs: number,
 ): Promise<void> {
-  const budget = Math.max(0, budgetMs);
+  // Screened by `releaseBudgetMs`, which is the one answer to "how long does a teardown get" —
+  // a second `Math.max` here would be a second, quieter one.
   let timer: ReturnType<typeof setTimeout> | undefined;
   const abandoned = new Promise<'abandoned'>((resolve) => {
-    timer = setTimeout(() => resolve('abandoned'), budget);
+    timer = setTimeout(() => resolve('abandoned'), budgetMs);
   });
   try {
     const outcome = await Promise.race([release().then(() => 'released' as const), abandoned]);
     if (outcome === 'released') return;
     logger.warn('X_SHUTDOWN_TIMEOUT', {
       code: 'X_SHUTDOWN_TIMEOUT',
-      cause: `the "${name}" release was still running ${budget}ms after the drain finished and has been ABANDONED — the process exits without it, so anything it held may not be closed`,
+      // Rounded: `deadlineAt - monotonic()` is a float, and `4923.185900000001ms` in a shutdown
+      // log reads as a bug in the number rather than as the budget it is.
+      cause: `the "${name}" release was still running ${Math.round(budgetMs)}ms after the drain finished and has been ABANDONED — the process exits without it, so anything it held may not be closed`,
       fix: 'raise the budget past the slowest teardown — configureLifecycle({ deadlineMs: 600_000 }) for a 10-minute one — and set terminationGracePeriodSeconds to at least as many seconds',
     });
   } finally {

package/src/index.ts

@@ -68,7 +68,7 @@ export { deployCommand, planDeploy } from './cmd-deploy';
 export type { DevServer, StartDevOptions } from './cmd-dev';
 export { devCommand, startDev } from './cmd-dev';
 export type { DoctorProbe } from './cmd-doctor';
-export { doctorCommand, OFFLINE_FALLBACK, probeFor, runDoctor } from './cmd-doctor';
+export { doctorCommand, ENV_DEVELOPMENT, probeFor, runDoctor } from './cmd-doctor';
 export { ERRORS_SUBCOMMANDS, errorsCommand } from './cmd-errors';
 export { FIX_SUBCOMMANDS, fixCommand } from './cmd-fix';
 export type { GenerateOptions, Generator } from './cmd-generate';

package/src/island-bundle.ts

@@ -12,6 +12,7 @@ import { ISLAND_EXTENSION, IslandInvalidError, islandModuleId } from '@ultimat3/
 import { contentHash } from '@ultimat3/render/server';
 import { IslandBuildFailedError } from './errors';
 import { islandStylesPlugin } from './island-styles';
+import { hasPathSegment } from './path-segments';
 import { solidJsxPlugin } from './solid-loader';
 
 /**
@@ -59,7 +60,7 @@ export interface IslandBundle {
 export async function discoverIslands(root: string): Promise<readonly string[]> {
   const files: string[] = [];
   for await (const absolute of new Bun.Glob(ISLAND_GLOB).scan({ cwd: root, absolute: true })) {
-    if (absolute.includes('node_modules')) continue;
+    if (hasPathSegment(absolute, 'node_modules')) continue;
     files.push(relative(root, absolute).split(sep).join('/'));
   }
   return files.sort();

package/src/island-states-load.ts

@@ -16,6 +16,7 @@ import {
 } from '@ultimat3/testing';
 import { ISLAND_GLOB } from './island-bundle';
 import { IslandStatesFileEmptyError } from './island-shot-errors';
+import { hasPathSegment } from './path-segments';
 
 /**
  * `.island.states.ts`, built from the two constants that own its halves and restated as neither:
@@ -37,7 +38,7 @@ export async function discoverIslandStates(root: string): Promise<readonly strin
   const files: string[] = [];
   const scan = new Bun.Glob(ISLAND_STATES_GLOB).scan({ cwd: root, absolute: true });
   for await (const absolute of scan) {
-    if (absolute.includes('node_modules')) continue;
+    if (hasPathSegment(absolute, 'node_modules')) continue;
     files.push(relative(root, absolute).split(sep).join('/'));
   }
   return files.sort();

package/src/jobs-driver.ts

@@ -24,7 +24,10 @@ export async function withJobDriver(
   const ambient = jobDriver();
   if (ambient !== undefined) return fn(ambient);
   const services = resolveServices(root, ctx.env);
-  const queue = await startQueue(services);
+  // The command's own environment on both halves: `resolveServices` reads DATABASE_URL off it, so
+  // a queue that resolved its standby from `process.env` would talk to a pair the same call had
+  // just decided against.
+  const queue = await startQueue(services, undefined, ctx.env);
   try {
     return await fn(queue.jobs);
   } finally {

package/src/mcp-host.ts

@@ -45,6 +45,7 @@ import { databaseTarget } from './mcp-db-target';
 import { explainErrorCode } from './mcp-errors';
 import { parseBunTest } from './mcp-test-output';
 import { readMigrations } from './migrations';
+import { retryMemo } from './retry-memo';
 
 export interface DevHostInput {
   readonly root: string;
@@ -91,7 +92,11 @@ export interface LazyServices {
  */
 export function lazyServices(input: DevHostInput): LazyServices {
   const services = resolveServices(input.root, input.env);
-  let started: Promise<RunningServices> | undefined;
+  // `retryMemo`, not `??=`: a boot that REJECTED is not an answer to keep. A Postgres that refused
+  // one connection wedged every later tool call in the session with that first error, and the only
+  // way out was restarting the host — `startServices` unwinds everything it started before it
+  // rejects, so there is nothing left over for a second attempt to collide with.
+  const boot = retryMemo(() => startServices(services, input.env));
   let closed = false;
   return {
     services,
@@ -104,14 +109,14 @@ export function lazyServices(input: DevHostInput): LazyServices {
           fix: 'x mcp serve --transport stdio   # keep the host open for the whole session',
         });
       }
-      started ??= startServices(services, input.env);
-      return started;
+      return boot.get();
     },
     async close(): Promise<void> {
       if (closed) return;
       closed = true;
-      // A boot that rejected has nothing to stop, and close() must not throw on the way out.
-      await (await started?.catch(() => undefined))?.stop();
+      // `started()` and never `get()`: closing must not BOOT a database in order to stop one. A
+      // boot that rejected has nothing to stop, and close() must not throw on the way out.
+      await (await boot.started()?.catch(() => undefined))?.stop();
     },
   };
 }
@@ -175,8 +180,13 @@ export async function readOnlyRows(
 function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities {
   const { root, runner } = input;
   // Layer 1 is seven idempotent DDL statements, and `db.query` is a tool an agent calls in a
-  // loop — resolve the role once per process and reuse the answer, `null` included.
-  let readOnlyRole: Promise<string | null> | undefined;
+  // loop — resolve the role once per process and reuse the answer, `null` included. A FAILED
+  // resolution is not an answer: `??=` kept the rejection, so a statement timeout on the DDL
+  // meant every later `db.query` in the session refused with it instead of trying again.
+  //
+  // It asks `lazy.running()` for the client rather than closing over one: this runs before any
+  // boot has happened, and the boot is memoised, so it is the same connection `runQuery` uses.
+  const readOnlyRole = retryMemo(async () => ensureReadOnlyRole((await lazy.running()).db));
 
   return {
     database: databaseTarget(lazy.services, input.env),
@@ -185,8 +195,7 @@ function capabilities(input: DevHostInput, lazy: LazyServices): DevCapabilities
       const { db } = await lazy.running();
       // A managed Postgres may refuse CREATE ROLE; `ensureReadOnlyRole` answers null and the
       // layer is reported absent in `guards` rather than quietly assumed present.
-      readOnlyRole ??= ensureReadOnlyRole(db);
-      return readOnlyRows(db, sql, limits, await readOnlyRole);
+      return readOnlyRows(db, sql, limits, await readOnlyRole.get());
     },
 
     async runMigrations(branch: string, dryRun: boolean) {

package/src/parse.ts

@@ -88,6 +88,15 @@ export interface CommandSpec {
    * that declared it and forgot the call ran outside an app with no refusal.
    */
   readonly requiresApp?: boolean;
+  /**
+   * The command hands everything after a bare `--` to another tool, so `ParsedArgs.passthrough`
+   * has a READER. Declared, because it did not until 2026-09 and nothing read it anywhere:
+   * `x test unit -- --coverage --bail` parsed both flags, carried them the whole way and dropped
+   * them, and every other command did the same in the same silence. A command that declares this
+   * forwards them; one that does not refuses the `--` (`X_CLI_BAD_FLAG`), which is the only way an
+   * argument that changes nothing becomes visible to the caller who typed it.
+   */
+  readonly passthrough?: true;
 }
 
 export interface ParsedArgs {
@@ -170,6 +179,14 @@ export function parseArgs(argv: readonly string[], specs: readonly CommandSpec[]
   }
 
   const spec = resolveCommand(first, specs);
+  if (passthrough.length > 0 && spec.passthrough !== true) {
+    throw new BadFlagError({
+      flag: '',
+      command: spec.name,
+      reason: `hands nothing to another tool, so ${passthrough.join(' ')} would be dropped in silence`,
+      fix: `x ${spec.name} --help`,
+    });
+  }
   const flags = defaults(spec);
   const positionals: string[] = [];
   // What argv actually SET, as against what `defaults()` seeded: a default is nobody's request,

package/src/path-segments.ts

@@ -0,0 +1,14 @@
+// One answer to "does this path pass through a directory called X". Six modules asked it with
+// `path.includes('node_modules')`, which is a SUBSTRING match: an app checked out under
+// `~/dev/node_modules-experiments/myapp` answered true for every file it holds, so `loadApp`
+// imported none of them and the app registered nothing at all.
+
+/** Split on either separator: a rule that reads `a/b` and not `a\b` does not exist on Windows. */
+export function pathSegments(path: string): readonly string[] {
+  return path.replaceAll('\\', '/').split('/');
+}
+
+/** Whether any whole segment of `path` is `segment` — never a substring of one. */
+export function hasPathSegment(path: string, segment: string): boolean {
+  return pathSegments(path).includes(segment);
+}

package/src/prerender.ts

@@ -22,7 +22,13 @@ import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifa
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
 import { styleBundle, writeStyles } from './style-bundle';
-import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
+import type { RenderedDocument } from './sw-artifacts';
+import {
+  SERVICE_WORKER_PATH,
+  SW_REGISTER_PATH,
+  serviceWorkerArtifacts,
+  serviceWorkerHead,
+} from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -141,6 +147,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
   const unmeasured: UnmeasuredRoute[] = [];
+  // What the loop below rendered, by the path it rendered — the service worker's precache
+  // revisions. A `Map` and not a record, so a route path spelling a prototype member cannot answer
+  // with one; insertion order is never read, because `pwaRoutes` walks the route table and
+  // `buildPrecacheManifest` sorts its own entries by code unit.
+  const documents = new Map<string, RenderedDocument>();
 
   // Before the first document: a page's `data-x-entry` is a built chunk's URL, so the chunks have
   // to exist to be named. Written into `out` too — a static export is served with no process
@@ -174,24 +185,15 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
-  // The worker and its registration script, written as FILES. A static host runs no route table,
-  // so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the
-  // artifact — the same promise `favicon.ico` and the icons above keep, for the asset that decides
-  // whether the export works offline at all.
-  const serviceWorker =
-    pwa === undefined
-      ? undefined
-      : serviceWorkerArtifacts({
-          pwa,
-          buildId,
-          routes: describeRoutes(),
-          islands,
-          styles,
-        });
-  if (serviceWorker !== undefined) {
-    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
-    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
-  }
+  // The registration TAG now, the worker itself after the render loop — the two halves are wanted
+  // at different moments and used to be taken at the same one. Every document below has to name
+  // `/x-sw-register.js`, and the worker's precache manifest is built from the content hash of
+  // those same documents, which do not exist yet: emitted here, every route's revision was the
+  // BUILD ID and every route's byte count was 0, so a deploy of a byte-identical site re-fetched
+  // everything and the precache budget could not count one byte of HTML (`precache.ts`' own
+  // header). `serviceWorkerHead` is the one predicate behind both, so a page can never name a
+  // script the export does not carry.
+  const swHead = pwa === undefined ? undefined : serviceWorkerHead(pwa);
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -224,7 +226,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(as, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
       }),
     );
   const document = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
@@ -299,6 +301,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         hash: artifact.hash,
         bytes,
       });
+      // `artifact.hash` is `contentHash(html)` — the same identity that becomes this page's ETag,
+      // so the precache revision and the HTTP validator can never disagree about one document.
+      // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
+      // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
+      documents.set(artifact.path, { revision: artifact.hash, bytes });
       // Measured from the document that was just written, so the `budgets` step compares a
       // declared budget against bytes that exist on disk rather than against a graph's estimate.
       const measured = await measureDocumentJs(artifact.html, options.out);
@@ -312,6 +319,25 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     }
     if (heaviest !== undefined) routes.push(heaviest);
   }
+  // The worker, LAST: every document it precaches has now been rendered, hashed and weighed. A
+  // static host runs no route table, so both files go into the artifact — a
+  // `<script src="/x-sw-register.js">` in every document is a 404 otherwise, which is the same
+  // promise `favicon.ico` and the icons above keep.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId,
+          routes: describeRoutes(),
+          islands,
+          styles,
+          documents,
+        });
+  if (serviceWorker !== undefined) {
+    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
+  }
   const stats = await writeBuildStats(options.root, { routes });
   // Written LAST and by the same call that writes the stats, so an app whose `prerender.ts` does
   // not reach `prerenderSite` produces neither — and `x verify`'s `budgets` step already reds that

package/src/retry-memo.ts

@@ -0,0 +1,37 @@
+// One in-flight attempt, shared — and a FAILED one not kept. `started ??= boot()` caches the
+// rejection with the value, so a Postgres that refused a connection once answered every later
+// call in the session with that same error and no retry was possible short of restarting the host.
+
+/**
+ * A lazily made attempt that may be made again.
+ *
+ * `started()` is the half `??=` has no spelling for: it answers the attempt already in flight or
+ * already made, and `undefined` when nobody has asked yet — so a `close()` can stop what was
+ * booted without BOOTING one in order to stop it.
+ */
+export interface RetryMemo<T> {
+  get(): Promise<T>;
+  started(): Promise<T> | undefined;
+}
+
+/**
+ * `start` runs at most once per SUCCESS. `@ultimat3/db`'s `createPgliteClient` states the rule this
+ * generalises — "a failed boot must not be cached" — and the clearing handler is attached at
+ * creation for the reason that matters: it therefore runs ahead of every caller's own `await`
+ * continuation, so by the time anyone sees the rejection the slot is already empty and the next
+ * call really does start a new attempt. Cleared inside the caller's `catch` instead, there is a
+ * window in which a second call is handed the dead promise.
+ */
+export function retryMemo<T>(start: () => Promise<T>): RetryMemo<T> {
+  let attempt: Promise<T> | undefined;
+  return {
+    get(): Promise<T> {
+      attempt ??= start().catch((error: unknown) => {
+        attempt = undefined;
+        throw error;
+      });
+      return attempt;
+    },
+    started: (): Promise<T> | undefined => attempt,
+  };
+}

package/src/scaffold-fixture.ts

@@ -10,6 +10,17 @@ import type { GeneratedFile } from './templates';
 /** The app the fixture scaffolds. Kebab, multi-word: single-word names hide casing bugs. */
 export const FIXTURE_APP = 'ledger-demo';
 
+/**
+ * An `errors.ts` an author wrote: it declares what the slice throws, and not the generated name.
+ * The generator's INPUT only — the sandbox's own `errors.ts` is the one the resource wrote — so it
+ * carries no `X_*` code: a literal here would be one shipped source hands a reader, and the
+ * registry rule would ask where it was registered.
+ */
+export const HANDWRITTEN_ERRORS = `import { UltimateError } from '@ultimat3/core';
+
+export class LedgerClosedError extends UltimateError {}
+`;
+
 /**
  * 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
@@ -25,6 +36,12 @@ export const FIXTURE_GENERATORS: readonly GenerateOptions[] = [
   { kind: 'policy', name: 'credit-note', feature: 'credit-note' },
   { kind: 'action', name: 'send-invoice', feature: 'invoice' },
   { kind: 'mutator', name: 'rename-invoice', feature: 'invoice' },
+  // 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: 'query', name: 'invoice-search', feature: 'invoice' },
   { kind: 'query', name: 'invoice-feed', feature: 'invoice', live: true },
   { kind: 'job', name: 'sweep-invoices', feature: 'invoice' },

package/src/serve.ts

@@ -1,8 +1,8 @@
 // What a container starts. `apps/web/server.ts` is three lines that call `runRole`, so the boot a
 // production process performs is framework code with tests rather than app code the author has to
 // get right — and it is the SAME code `x dev` runs, minus the watcher, minus `/_x`, minus
-// `dev: true`. The only production-shaped decisions live here: which role, which port, and the
-// fact that a container must bind every interface.
+// `dev: true`. The only production-shaped decisions live here: which role, which port, and which
+// interface — every one by default, because a container is reached through a port mapping.
 
 import type { Role } from '@ultimat3/core';
 import {
@@ -56,9 +56,35 @@ import { serviceWorkerRoutes } from './sw-routes';
 
 export const DEFAULT_PORT = 3000;
 
-/** Every interface. A container bound to loopback is unreachable through its own port mapping. */
+/**
+ * Every interface, which is what a role binds when nothing says otherwise: a container bound to
+ * loopback is unreachable through its own port mapping. `HOST` and `ServeOptions.hostname` are the
+ * two ways of saying otherwise — see `hostnameFromEnv`.
+ */
 export const CONTAINER_BINDING: WebBinding = { dev: false, hostname: '0.0.0.0' };
 
+/**
+ * The interface the `web` and `sync` roles bind, and the metrics endpoint with them (`WebBinding`
+ * is one decision). Read the way `PORT` is: empty or whitespace is the default.
+ *
+ * Exists because a container had exactly one binding, `0.0.0.0`, and an app whose auth mode is
+ * "nobody logs in, one implicit actor" must refuse a public interface — so it could not run in a
+ * container at all. `HOST=127.0.0.1` is unreachable through `docker run -p` (the proxy connects to
+ * the container's bridge address, never its loopback); it is reachable where the container shares
+ * the host's network namespace (`--network host`), or through a sidecar and `ssh -L` inside it —
+ * which is the exposure such an app wants. Not `HOSTNAME`: Docker sets that to the container id.
+ */
+export function hostnameFromEnv(env: Env): string {
+  const raw = env['HOST']?.trim();
+  return raw === undefined || raw.length === 0 ? CONTAINER_BINDING.hostname : raw;
+}
+
+/** What `serveApp` hands `startRoles`: the caller's hostname, else `HOST`, else every interface. */
+export const containerBinding = (env: Env, hostname?: string): WebBinding => ({
+  dev: false,
+  hostname: hostname ?? hostnameFromEnv(env),
+});
+
 /**
  * `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.
@@ -144,6 +170,11 @@ export interface ServeOptions {
   readonly port?: number;
   /** Overrides `METRICS_PORT`, on the same terms. */
   readonly metricsPort?: number;
+  /**
+   * Overrides `HOST`: the interface the HTTP roles bind. An app that must never answer on a public
+   * interface passes `'127.0.0.1'` here rather than trusting the deployment to set the variable.
+   */
+  readonly hostname?: string;
   /**
    * The drivers this deployment supplies instead of the ones the environment would select.
    *
@@ -195,7 +226,11 @@ export type StartedApp = ServedApp | MigratedApp;
  * is what fails on it.
  */
 export async function runMigrations(options: ServeOptions): Promise<MigratedApp> {
-  const queue = await startQueue(resolveServices(options.root, options.env), options.runtime);
+  const queue = await startQueue(
+    resolveServices(options.root, options.env),
+    options.runtime,
+    options.env,
+  );
   try {
     const migrations = await readMigrations(options.root);
     const report = await migrate({
@@ -387,7 +422,7 @@ async function bootRoles(boot: {
     // The app's own `apps/web/site/errors/<status>.html`, resolved inside `startWeb` so this
     // process and `x dev` cannot answer a browser differently.
     root: options.root,
-    http: CONTAINER_BINDING,
+    http: containerBinding(options.env, options.hostname),
     // The read-replica scope rides in FRONT of whatever the host supplied, or the host's own value
     // passes through untouched. `DATABASE_REPLICA_URL` was read by no booted process before this:
     // `defaultClient()` is the one composer of a replicated pair and it runs only when an app

package/src/source-files.ts

@@ -2,6 +2,8 @@
 // and an app. One list for every step that walks source, because two steps scanning different sets
 // means a finding one of them can never see.
 
+import { hasPathSegment } from './path-segments';
+
 export const SOURCE_GLOBS = [
   'packages/*/src/**/*.{ts,tsx}',
   // Three packages carry an `e2e` directory beside `src`. It is shipped source by every rule that
@@ -21,7 +23,7 @@ export const SOURCE_GLOBS = [
  * root. `dist/` is build output: the sources that produced it are already in the set.
  */
 export const isVendored = (path: string): boolean =>
-  path.includes('node_modules') || path.includes('/dist/') || path.startsWith('dist/');
+  hasPathSegment(path, 'node_modules') || hasPathSegment(path, 'dist');
 
 /** Emitted declarations, not authored source — a rule about authored code cannot apply to them. */
 export const isGenerated = (path: string): boolean => path.endsWith('.d.ts');