@ultimat3/cli 28.0.0 → 29.0.0

package/src/runtime-jobs.ts

@@ -1,10 +1,16 @@
-// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency` and
-// `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
+// The queues a `worker` serves and the slots each gets: `jobs.queues`, `jobs.concurrency`,
+// `jobs.maxInFlight` and `jobs.visibilityTimeoutMs` off the app's own `app.config.ts`, and `WORKER_QUEUES` off the
 // Deployment's env — the one per-Deployment answer, since every Deployment runs the same image and
 // the same config (issues #673, #676).
 
 import type { AppConfig, JobsConcurrency } from '@ultimat3/core';
-import { ConfigInvalidError, logger, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
+import {
+  ConfigInvalidError,
+  logger,
+  renderCauseValue,
+  renderFixShellArg,
+  UltimateError,
+} from '@ultimat3/core';
 import { registeredJobs, type WorkerOptions } from '@ultimat3/jobs';
 import type { Env } from './runtime-bindings';
 
@@ -19,7 +25,14 @@ export interface WorkerConfig {
    * queues registered jobs are enqueued on. `false` is the union `workerQueuesFor` explains.
    */
   readonly exact: boolean;
+  /**
+   * `jobs.queues` as the app configured them, kept when `WORKER_QUEUES` replaced `queues`: with
+   * the registered jobs' queues, the set an exact entry must belong to (`refuseUnknownQueues`).
+   */
+  readonly configured: readonly string[];
   readonly concurrency: JobsConcurrency | undefined;
+  /** `jobs.maxInFlight`: runs across every queue this process serves. Unset: no process cap. */
+  readonly maxInFlight?: number | undefined;
   readonly visibilityTimeoutMs: number | undefined;
 }
 
@@ -27,7 +40,9 @@ export interface WorkerConfig {
 const NO_WORKER_CONFIG: WorkerConfig = Object.freeze({
   queues: [],
   exact: false,
+  configured: [],
   concurrency: undefined,
+  maxInFlight: undefined,
   visibilityTimeoutMs: undefined,
 });
 
@@ -45,7 +60,7 @@ export function workerQueuesFromEnv(env: Env): readonly string[] | undefined {
   if (!names.includes('')) return named;
   throw new ConfigInvalidError({
     cause: `${WORKER_QUEUES_ENV} ${renderCauseValue(raw)} contains an empty queue name — every comma-separated entry must name a queue`,
-    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')} on this Deployment — or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
+    fix: `WORKER_QUEUES=${renderFixShellArg(named.join(','), '<queue>,<queue>')}   # on this Deployment; or unset WORKER_QUEUES to serve jobs.queues and every registered job's queue`,
     meta: { key: WORKER_QUEUES_ENV },
   });
 }
@@ -58,7 +73,9 @@ export function workerConfigOf(config: AppConfig | undefined, env: Env = {}): Wo
       : {
           queues: config.jobs.queues,
           exact: false,
+          configured: config.jobs.queues,
           concurrency: config.jobs.concurrency,
+          maxInFlight: config.jobs.maxInFlight,
           visibilityTimeoutMs: config.jobs.visibilityTimeoutMs,
         };
   return fromEnv === undefined ? base : { ...base, queues: fromEnv, exact: true };
@@ -97,16 +114,74 @@ function reportUnserved(served: readonly string[], registered: readonly string[]
   });
 }
 
-type WorkerConfigOptions = Pick<WorkerOptions, 'queues' | 'concurrency' | 'visibilityTimeoutMs'>;
+/**
+ * A `WORKER_QUEUES` entry no registered job and no `jobs.queues` entry names. The worker would
+ * claim a queue nothing is enqueued on and leave the real ones waiting while its pod stays Ready —
+ * a 15-minute outage behind a healthy roll (`banks-*`, never expanded, 2026-10-27). Refused at
+ * boot instead, so the new pods crash and a rolling update stalls on the old ones.
+ */
+export class WorkerQueueUnknownError extends UltimateError {
+  constructor(input: {
+    unknown: readonly string[];
+    known: readonly string[];
+    named: readonly string[];
+  }) {
+    const patterns = input.unknown.filter((queue) => /[*?[\]{}]/.test(queue));
+    // A pattern's fix is its expansion over the known queues: the list the author meant to write.
+    const meant = input.named.flatMap((queue) =>
+      patterns.includes(queue)
+        ? input.known.filter((name) => new Bun.Glob(queue).match(name))
+        : input.unknown.includes(queue)
+          ? []
+          : [queue],
+    );
+    const list = [...new Set(meant)].join(',');
+    // Every name through `renderCauseValue`: an env value can carry a newline, and a cause is one line.
+    const names = (queues: readonly string[]) => queues.map((q) => renderCauseValue(q)).join(', ');
+    const pattern =
+      patterns.length === 0
+        ? ''
+        : ` — WORKER_QUEUES is never expanded, so ${names(patterns)} is a literal queue name`;
+    super({
+      code: 'X_WORKER_QUEUE_UNKNOWN',
+      cause: `${WORKER_QUEUES_ENV} names ${names(input.unknown)}, which no registered job is enqueued on and jobs.queues does not list${pattern}; the queues this app knows are ${input.known.length === 0 ? 'none' : names(input.known)}`,
+      // The prose after `#`, so the line pasted into a shell sets the variable and runs nothing.
+      fix: `WORKER_QUEUES=${renderFixShellArg(list === '' ? undefined : list, '<queue>,<queue>')}   # on this Deployment; or add the queue to jobs.queues in app.config.ts when jobs reach it by enqueue({ queue }) alone`,
+      meta: { key: WORKER_QUEUES_ENV, unknown: input.unknown, known: input.known },
+    });
+  }
+}
+
+/**
+ * An exact worker's entries, held to what the app knows: `jobs.queues` plus every registered
+ * job's queue — the union an unset `WORKER_QUEUES` would serve. Thrown, never logged: an info line
+ * is what let the worker run claiming nothing (2026-10-27).
+ */
+function refuseUnknownQueues(
+  named: readonly string[],
+  configured: readonly string[],
+  registered: readonly string[],
+): void {
+  const known = [...new Set([...configured, ...registered])].sort();
+  const unknown = named.filter((queue) => !known.includes(queue));
+  if (unknown.length > 0) throw new WorkerQueueUnknownError({ unknown, known, named });
+}
+
+type WorkerConfigOptions = Pick<
+  WorkerOptions,
+  'queues' | 'concurrency' | 'maxInFlight' | 'visibilityTimeoutMs'
+>;
 
 /**
  * The `jobWorker` 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`).
+ * on import is counted — and an exact entry the app does not know is refused there. 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 registered = registeredJobs().map((handle) => handle.queue);
   const exact = config?.exact === true;
+  if (exact) refuseUnknownQueues(config?.queues ?? [], config?.configured ?? [], registered);
   const queues = workerQueuesFor(config?.queues ?? [], registered, exact);
   if (exact) reportUnserved(queues ?? [], registered);
   // Passed as written: `jobWorker` reads a table by own key and runs a queue it does not name at
@@ -115,6 +190,7 @@ export function workerOptionsFor(config: WorkerConfig | undefined): WorkerConfig
   return {
     ...(queues === undefined ? {} : { queues }),
     ...(concurrency === undefined ? {} : { concurrency }),
+    ...(config?.maxInFlight === undefined ? {} : { maxInFlight: config.maxInFlight }),
     ...(config?.visibilityTimeoutMs === undefined
       ? {}
       : { visibilityTimeoutMs: config.visibilityTimeoutMs }),

package/src/runtime-render.ts

@@ -6,7 +6,7 @@
 import { actionPathStyle } from '@ultimat3/action';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Actor, Ctx } from '@ultimat3/core';
-import { CLIENT_SCOPE_HEADER, singleFlight } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER, escapeHtml, singleFlight } from '@ultimat3/core';
 import type {
   RouteMeta as HttpRouteMeta,
   RedirectIntent,
@@ -44,6 +44,7 @@ import {
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import { loadAppConfig } from './app-config-load';
 import type { DocumentOptions } from './document-options';
 import { routeQuery } from './isr-query-guard';
 import {
@@ -56,13 +57,28 @@ import { bootScript, collectorFor } from './route-islands';
 import { addressedUrl } from './runtime-address';
 import { attachedIsr } from './runtime-isr';
 import { isrOutcome } from './runtime-isr-outcome';
+import { siteAssetTable } from './site-assets';
 import type { StaticResult } from './static-document';
 import { createStaticMemo, staticMemoKey, staticResponse } from './static-document';
 import { styleBundle } from './style-bundle';
 
 export type { DocumentOptions, IslandResolver } from './document-options';
 
-export interface DevRenderOptions extends DocumentOptions {
+/**
+ * The app-wide favicon head, from `site.favicon`: the content-hashed URL `asset('assets/….svg')`
+ * returns and `/assets/*` serves, never the raw path. Per render, never frozen at boot.
+ */
+export async function appFaviconHead(root: string): Promise<string | undefined> {
+  const favicon = (await loadAppConfig(root))?.site.favicon;
+  if (favicon === undefined) return undefined;
+  const url = siteAssetTable(root).resolve(favicon).url;
+  return `<link rel="icon" type="image/svg+xml" href="${escapeHtml(url)}">`;
+}
+
+/** `DocumentOptions`, plus the app root the app's own favicon is resolved against per render. */
+export type RenderOptions = DocumentOptions & { readonly root?: string };
+
+export interface DevRenderOptions extends RenderOptions {
   readonly buildId: string;
   /**
    * The boot's own controller, attached and released by it (`runtime-isr.ts`). Omitted, one is
@@ -76,33 +92,30 @@ export interface DevRenderOptions extends DocumentOptions {
    */
   readonly memoStatic?: boolean;
 }
-
 /** What a route's `meta(data)` is given. `url` is a string because that is what `ld.*` embeds. */
 export interface DevRouteData extends Record<string, unknown> {
   readonly url: string;
   readonly params: RouteParams;
 }
-
 /**
  * `<html lang>` is the request's own locale, never a constant: the `locale` stage negotiated it
  * one stage before this handler and published it on the context, so a hardcoded `'en'` shipped
- * every document mislabelled — wrong for a screen reader, wrong for `hreflang`, wrong for a CDN
- * keying on `content-language`. Outside a request (`x build`'s prerender) it is the app's own
- * configured fallback, which is the only defensible answer there.
+ * every document mislabelled — wrong for a screen reader, wrong for `hreflang`. Outside a request
+ * (`x build`'s prerender) it is the app's own configured fallback.
  */
 const lang = (): string => currentLocale();
 
 /**
  * `scope` is present only on a PRIVATE document (a gated `ssr` page, every `stream`): the page's
  * client scope (`@ultimat3/auth`'s `clientScopeOf`), which core's `pageClient()` reads to fence its
- * one store per principal. A shareable document (`static`, `isr`, ungated `ssr`) carries NO scope
- * tag — absent means "not rendered for anyone", a different answer from `''`, the anonymous page.
+ * one store per principal. A shareable document carries NO scope tag — absent means "not rendered
+ * for anyone", a different answer from `''`, the anonymous page.
  */
 const headFor = async (
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
-  options: DocumentOptions,
+  options: RenderOptions,
   scope?: string,
 ): Promise<string> => {
   const meta = metaContextFor(ctx, data);
@@ -132,7 +145,7 @@ const headFor = async (
           ...router,
           // The page boot rides the scope tag: its whole job — restoring a principal's persisted
           // records and replaying its queued writes — is per principal, and a shareable document
-          // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
+          // (no scope tag) has neither.
           ...(scope === undefined
             ? []
             : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
@@ -142,6 +155,9 @@ const headFor = async (
     (options.themeHead ?? '') +
     // One mechanism per document: the router prefetches for itself, the browser for the rest.
     (router.length === 0 ? (options.speculationHead ?? '') : '') +
+    // The app's own favicon: one link, every document, the URL the table resolves NOW.
+    ((options.root === undefined ? options.faviconHead : await appFaviconHead(options.root)) ??
+      '') +
     // Per locale: each links its own locale's manifest (`PwaArtifacts.headFor`).
     (typeof options.pwaHead === 'function' ? options.pwaHead(meta.locale) : (options.pwaHead ?? ''))
   );
@@ -149,19 +165,17 @@ const headFor = async (
 
 /**
  * `<link rel="stylesheet">` for the surface's own stylesheets, or nothing at all when the surface
- * imports none. Inlined until 2026-09-06: every `app/` document of ai-maxxing then carried the same
- * 156,738-byte `<style>` (92% of it) under `no-store`, re-paid on every navigation.
+ * imports none.
  *
  * In `<head>`, which is what keeps this a swap and not a regression: a `<link rel="stylesheet">`
- * there is render-blocking in every browser, exactly as the inline block was, so there is no
- * window in which the document paints unstyled. Moving it to the body, or deferring it, is what
- * would introduce a flash — never do that here.
+ * there is render-blocking in every browser, exactly as the inline block was, so there is no window
+ * in which the document paints unstyled. Moving it to the body, or deferring it, would introduce a
+ * flash — never do that here.
  *
  * Read through `styleBundle()` rather than passed in through `DocumentOptions`: the registry it
  * derives from is process-global (importing the app IS what fills it), so a caller that forgot to
- * thread a resolver would serve a document with no CSS at all — and `appRoutes` is on this
- * package's public surface, called as `appRoutes({ buildId })` by both tracked apps' contract
- * tests. One reader, and it is the same one `styleRoutes` serves from.
+ * thread a resolver would serve a document with no CSS at all. One reader, and it is the same one
+ * `styleRoutes` serves from.
  */
 const styleTag = (entry: RouteEntry): string => {
   const href = styleBundle().hrefFor(entry.surface);
@@ -175,8 +189,7 @@ const stylesFor = (entry: RouteEntry, options: DocumentOptions): string =>
 /**
  * The route's rendered body, inside the hydration root. Every mode goes through here — an empty
  * root is what a module exporting no component renders, and nothing else: `spa` was the one mode
- * that never reached this function, which is why every `spa` route ever declared served
- * `<div id="x-root"></div>` and painted nothing.
+ * that never reached this function, so every `spa` route ever declared served an empty root.
  */
 export async function routeBody(
   entry: RouteEntry,
@@ -204,28 +217,27 @@ export async function routeBody(
 }
 
 /**
- * Head + body for one route render. Exported because the build's prerenderer must emit the same
- * document `x dev` serves — two document builders is how a page that works in dev ships broken.
+ * Head + body for one route render — the document `x dev` serves, which the build's prerenderer
+ * must emit too.
  */
 export async function routeDocument(
   entry: RouteEntry,
   ctx: DevRouteData,
-  options: DocumentOptions = {},
+  options: RenderOptions = {},
 ): Promise<string> {
   return documentFrom(entry, ctx, await routeDataFor(entry.config, ctx), options);
 }
 
 /**
  * The document a request by `actor` is SERVED: `routeDocument` plus the scope the response would
- * carry, which is what earns the page boot. The build weighs an app/ page through this, because a
- * budget is a promise about what that page's browser downloads — and an unscoped render of a
- * scoped page weighed a runtime chunk it never fetches and no boot it always does (#505).
+ * carry, which is what earns the page boot. The build weighs an app/ page through this — a budget
+ * is a promise about what that page's browser downloads (#505).
  */
 export async function servedDocument(
   entry: RouteEntry,
   ctx: DevRouteData,
   actor: Actor,
-  options: DocumentOptions & { readonly buildId: string },
+  options: RenderOptions & { readonly buildId: string },
 ): Promise<string> {
   const data = await routeDataFor(entry.config, ctx);
   return documentFrom(entry, ctx, data, options, documentScope(entry, options.buildId, actor));
@@ -233,9 +245,8 @@ export async function servedDocument(
 
 /**
  * Whether, and as whom, a mode's response is scoped — ONE decision for the request path and for
- * `servedDocument`. A stream is always `private, no-store`; an ssr page carries the scope exactly
- * when the headers `renderSsr` sends are private (an ungated page is `public, s-maxage`, and a CDN
- * may hand it to anyone); a static or isr document is shareable by construction.
+ * `servedDocument`. A stream is always `private, no-store`; an ssr page carries the scope when the
+ * headers `renderSsr` sends are private; a static or isr document is shareable.
  */
 function documentScope(entry: RouteEntry, buildId: string, actor: Actor): string | undefined {
   switch (entry.config.render) {
@@ -257,14 +268,14 @@ function documentScope(entry: RouteEntry, buildId: string, actor: Actor): string
  * a `<title>` describe content the body does not contain.
  *
  * The hydration runtime is appended after the body and only after it: what strategies a page needs
- * is a fact about the islands the walk just recorded, so emitting it earlier would either guess or
- * ship the whole runtime to a page with no island — the 0kb baseline, spent on nothing.
+ * is a fact about the islands the walk just recorded, so emitting it earlier would guess or ship
+ * the whole runtime to a page with no island.
  */
 async function documentFrom(
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
-  options: DocumentOptions,
+  options: RenderOptions,
   scope?: string,
 ): Promise<string> {
   const islands = collectorFor(entry, options, scope);
@@ -298,11 +309,10 @@ async function resultFor(
       return { status, headers: staticHeaders(contentHash(body), options.buildId), body };
     }
     case 'stream': {
-      // The shell IS the component: nothing can yet mark a subtree as a hole. Solid's `Suspense`
-      // is not the missing piece and never will be here — it calls `getContextId()`, which throws
-      // outside a Solid renderer, and this package's JSX factory is inert by design. A hole marker
-      // has to be the framework's own. Until it exists the first flush carries the whole body —
-      // correct output, no streaming benefit.
+      // The shell IS the component: nothing can yet mark a subtree as a hole, and Solid's
+      // `Suspense` cannot be the missing piece — it calls `getContextId()`, which throws outside a
+      // Solid renderer. Until a hole marker of the framework's own exists, the first flush carries
+      // the whole body — correct output, no streaming benefit.
       // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
       const scope = documentScope(entry, options.buildId, ctx.actor);
       const islands = collectorFor(entry, options, scope);
@@ -316,7 +326,7 @@ async function resultFor(
             head: `<!doctype html><html lang="${lang()}"><head>${head}${stylesFor(entry, options)}</head><body>`,
             // The runtime rides the first flush, with the shell it boots. A later chunk would leave
             // the window between flush one and the close with inert islands and no listeners on
-            // them — which is exactly the first-click-lost failure `interaction` replay exists for.
+            // them — the first-click-lost failure `interaction` replay exists for.
             shell: `${shell}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}`,
             holes: [],
           },
@@ -345,8 +355,7 @@ async function resultFor(
 
 /**
  * A private document's scope, as a RESPONSE header too: the service worker partitions its offline
- * pages by principal and never parses HTML, so the meta alone cannot reach it. Exactly the
- * documents that carry the scope tag carry this — a shareable one carries neither.
+ * pages by principal and never parses HTML, so the meta alone cannot reach it.
  */
 const withScope = (result: RenderResult, scope: string | undefined): RenderResult =>
   scope === undefined
@@ -355,16 +364,14 @@ const withScope = (result: RenderResult, scope: string | undefined): RenderResul
 
 /**
  * A loader's redirect. No declared `cache` means `private, no-store`: the loader decided it for
- * THIS request (it recorded an open, it checked a token), and the mode's default would offer that
- * decision to a CDN, which would then answer every later request without running the loader. A
- * declared one is the pipeline's to apply, off `meta.cache`, exactly as for any handler.
+ * THIS request, and the mode's default would offer that decision to a CDN, which would then answer
+ * every later request without running the loader.
  */
 function loadRedirect(entry: RouteEntry, to: RedirectIntent): Response {
   const response = redirect(to.location, to.status);
   if (entry.config.cache === undefined) response.headers.set('cache-control', 'private, no-store');
   return response;
 }
-
 const responseOf = (result: RenderResult): Response =>
   typeof result.body === 'string'
     ? html(result.body, { status: result.status, headers: result.headers })
@@ -381,8 +388,7 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
   localeSource: entry.surface === 'site' ? 'path' : 'request',
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
   // Projected so the router screens its ages at mount (`assertRouteCache`) and the `cache-headers`
-  // stage applies it to a response that wrote none — a loader's redirect. The rendered document
-  // carries its own header, from `ssrHeaders`, which the stage reviews rather than replaces.
+  // stage applies it to a response that wrote none — a loader's redirect.
   ...(entry.config.cache === undefined
     ? {}
     : { cache: entry.config.cache === 'no-store' ? NO_STORE : entry.config.cache }),
@@ -397,13 +403,9 @@ const metaOf = (entry: RouteEntry, head?: NavigationDocumentHead): HttpRouteMeta
  * handler renders AND the `meta` the pipeline enforces — is read back from the table on every
  * request. `x dev` re-registers a route module when its source changes (`app-load.ts`), and a
  * handler closing over the entry it was built from kept serving the first component after every
- * save — the table had moved and this closure had not. `meta` was the same defect one stage
- * earlier: a snapshot taken here, so a `policy` added in a save was not enforced until a restart
- * while the page behind it was already the new one — the pipeline's `auth` and `authz` stages read
- * `route.meta` per request, and this getter is what makes that read the table's. The path cannot
- * move under a reload (the table derives it from the file, and the file is the reload's key), so
- * the entry captured here is only the fallback for a table cleared under a running server, which
- * only a test does — and then guard and page fall back together.
+ * save. `meta` was the same defect one stage earlier, and this getter is what makes that read the
+ * table's: the pipeline's `auth` and `authz` stages read `route.meta` per request. The path cannot
+ * move under a reload, so the captured entry is only the fallback for a cleared table.
  */
 export function appRoutes(options: DevRenderOptions): readonly Route[] {
   const isr = options.isr ?? attachedIsr({ buildId: options.buildId }).isr;

package/src/serve-web.ts

@@ -69,6 +69,9 @@ export async function webSurface(
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(options.root);
   const origin = publicOrigin(options.env, site);
+  // The app's own favicon is NOT resolved here: the document resolves it, per render, from the app
+  // root below — the same link `x dev` serves, so the tab icon does not change between a laptop
+  // and the image.
   // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
   // Before the service worker, which precaches those scripts.
   const sync = await pageSync(options.root, options.env, buildId, runtime.realtime);
@@ -150,6 +153,8 @@ export async function webSurface(
     }),
     ...appRoutes({
       buildId,
+      // The app root: the document resolves the app's own favicon from it, per render.
+      root: options.root,
       resolveIsland: (file) => islands.resolverFor(file),
       realtimeIslands: () => islands.realtime,
       ...(sync.head === undefined ? {} : { sync: sync.head }),

package/src/site-config.ts

@@ -1,9 +1,9 @@
-// The public origin and the crawler rules out of `app.config.ts` — `site.origin`,
-// `seo.robots.disallow` and `seo.robots.groups` — and the one resolution of "which origin is this site served on" every
+// The public origin, the app's favicon and the crawler rules out of `app.config.ts` — `site.origin`,
+// `site.favicon`, `seo.robots.disallow` and `seo.robots.groups` — and the one resolution of "which origin is this site served on" every
 // absolute URL a document, a sitemap or a robots file carries is built against. Read off the one
 // loader (`app-config-load.ts`).
 
-import type { Environment, SeoRobotsGroup, SeoSitemapConfig } from '@ultimat3/core';
+import type { Environment, SeoRobotsGroup, SeoSitemapConfig, SiteFavicon } from '@ultimat3/core';
 import { loadAppConfig } from './app-config-load';
 
 export interface SiteSettings {
@@ -18,6 +18,14 @@ export interface SiteSettings {
   readonly robotsGroups?: readonly SeoRobotsGroup[] | undefined;
   /** `seo.sitemap` — public `app/` pages to list, where `<lastmod>` comes from, sections, page size. */
   readonly sitemap: SeoSitemapConfig;
+  /**
+   * `site.favicon` — the app's SVG favicon, named as a site asset path (`assets/brand/icon.svg`).
+   * `undefined` when the app declares none. The boot resolves it ONCE, through the site asset
+   * table (`siteAssetTable(root).resolve(path).url` — the table `/assets/*` serves and `asset()`
+   * answers from), into the content-hashed URL every document carries. Optional so a
+   * `SiteSettings` literal written before it existed still compiles.
+   */
+  readonly favicon?: SiteFavicon | undefined;
 }
 
 export const NO_SITE_SETTINGS: SiteSettings = {
@@ -25,6 +33,7 @@ export const NO_SITE_SETTINGS: SiteSettings = {
   disallow: [],
   robotsGroups: [],
   sitemap: { extra: [], lastmod: 'none', sections: [], pageSize: 50_000 },
+  favicon: undefined,
 };
 
 const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
@@ -32,12 +41,13 @@ const trimSlash = (origin: string): string => origin.replace(/\/+$/, '');
 export async function loadSiteSettings(root: string): Promise<SiteSettings> {
   const config = await loadAppConfig(root);
   if (config === undefined) return NO_SITE_SETTINGS;
-  const { origin } = config.site;
+  const { origin, favicon } = config.site;
   return {
     origin: origin === null ? null : trimSlash(origin),
     disallow: [...config.seo.robots.disallow],
     robotsGroups: [...(config.seo.robots.groups ?? [])],
     sitemap: config.seo.sitemap,
+    favicon,
   };
 }
 

package/src/templates/scaffold-container.ts

@@ -32,16 +32,16 @@ const dockerfile = (
 # from the file itself, and without it the frozen install cannot find what the lockfile names.
 # The tag names the series for the reader; the digest is what builds — a tag is a pointer its
 # publisher can move. Dependabot's docker ecosystem moves the digest together with the tag.
-# The digest is \`oven/bun:1.4.3-alpine\`'s, the patch the framework that wrote this file was
+# The digest is \`oven/bun:1.4.4-alpine\`'s, the patch the framework that wrote this file was
 # tested on — the same patch as \`engines.bun\` in package.json.
-FROM oven/bun:1.4-alpine@sha256:629e17411f1f129dbec3af78d5af9c9f2a937435c80349437206c6b0b7422373 AS manifests
+FROM oven/bun:1.4-alpine@sha256:4cf82f5686b196504fe119db3fcd9185b191f82ece82c40680e597228ec6070a AS manifests
 WORKDIR /app
 COPY . .
 RUN find . ! -type d ! -name package.json ! -name bunfig.toml ! -name '*.tgz' -delete \\
  && find . -type d -empty -delete
 
 # ---------- deps: runtime dependencies only, cached on the lockfile and the manifests ----------
-FROM oven/bun:1.4-alpine@sha256:629e17411f1f129dbec3af78d5af9c9f2a937435c80349437206c6b0b7422373 AS deps
+FROM oven/bun:1.4-alpine@sha256:4cf82f5686b196504fe119db3fcd9185b191f82ece82c40680e597228ec6070a AS deps
 WORKDIR /app
 COPY --from=manifests /app ./
 COPY bun.lock ./

package/src/templates/scaffold-repo.ts

@@ -45,11 +45,11 @@ const TYPESCRIPT_VERSION = '^7.0.2';
 
 /**
  * The Solid runtime every island and `@ultimat3/ui` component renders with, exact for the reason
- * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.15`, and a scaffold
+ * `BIOME_VERSION` is: the CLI compiles islands with `babel-preset-solid ^1.9.16`, and a scaffold
  * that installed an older runtime than the compiler targets drifted as a buried literal (1.9.14
  * beside the repository's 1.9.15). `scaffold-repo.test.ts` holds it equal to the root manifest's.
  */
-const SOLID_VERSION = '1.9.15';
+const SOLID_VERSION = '1.9.17';
 
 // `engines.bun` is `REQUIRED_BUN`, the floor the SHIPPED `x` enforces
 // (`packages/cli/src/app-root.ts`), and not a second literal. It was one: `>=1.3.0`, a whole minor

package/src/workspace-graph.ts

@@ -1,13 +1,16 @@
 // The workspace dependency graph, in the two forms that must agree: the edges every manifest
 // DECLARES, the edges every shipped source file actually IMPORTS, and the gate rule that the
-// second is a subset of the first. An edge that lives only in a tsconfig `paths` entry resolves
-// for `tsc` and is invisible to bun, to `--filter` ordering and to any change-detection tool.
+// second is covered by the first, with no unused framework sibling declarations. A tsconfig-only
+// edge resolves for `tsc` but is invisible to bun, `--filter` ordering and change-detection tools.
 
 import { join } from 'node:path';
 import { ERROR_DOCS_URL, maskLiterals } from '@ultimat3/core';
+import { CATALOG_PACKAGES } from './error-catalog';
 import { scanAllImports } from './import-scan';
 import type { Finding } from './output';
-import { eachSourceFile, isGenerated, isTest, isVendored } from './source-files';
+import { FIXTURE_SUFFIX } from './publish-closure';
+import { quoteArg } from './shell-quote';
+import { eachSourceFile, isGenerated, isTest, isVendored, SOURCE_GLOBS } from './source-files';
 
 export interface WorkspaceNode {
   /** package.json "name". */
@@ -176,7 +179,7 @@ export const undeclaredWorkspaceDepFinding = (
   cause: `${at} imports ${to.name}, which ${from.dir}/package.json does not declare`,
   // The exact line to paste, at the version the target really carries: a `workspace:*` range would
   // resolve and then fail `checkLockstep`, which compares a sibling pin against the version.
-  fix: `add "${to.name}": "${to.version ?? '0.0.0'}" to "dependencies" in ${from.dir}/package.json`,
+  fix: `add "${to.name}": "${to.version ?? '0.0.0'}" to "${at.endsWith(FIXTURE_SUFFIX) ? 'devDependencies' : 'dependencies'}" in ${from.dir}/package.json`,
   docs: ERROR_DOCS_URL,
   at: `${from.dir}/package.json`,
 });
@@ -186,10 +189,9 @@ export const undeclaredWorkspaceDepFinding = (
  * declared none of it — the imports resolved through the root tsconfig's `paths`, so the edges
  * existed only inside `tsc` and every tool that asks what a change affects answered short.
  *
- * Shipped source only. A test file is excluded from the tarball by every package here
- * (`TEST_EXCLUSION`) and resolves its imports through the ROOT manifest's hoisted devDependencies,
- * which is why no `packages/*` in this repo carries a `devDependencies` block of its own —
- * judging test imports would demand 29 of them to describe a resolution that already works.
+ * Tests resolve through the root's hoisted devDependencies and are excluded here. Fixtures still
+ * need forward declarations, but their imports justify only development dependencies: they are
+ * excluded from tarballs and must not keep unused shipped dependency fields alive.
  *
  * One finding per (workspace, dependency) pair, never one per import site: the fix is one line in
  * one manifest, and repeating it per file is noise an author has to deduplicate by hand.
@@ -202,6 +204,8 @@ export async function checkWorkspaceDependencies(root: string): Promise<readonly
   // Deepest directory first: a nested workspace's files are its own, never its parent's.
   const owners = [...graph].sort((left, right) => right.dir.length - left.dir.length);
   const reported = new Set<string>();
+  const used = new Set<string>();
+  const fixtureUsed = new Set<string>();
   for await (const path of eachSourceFile(root)) {
     if (isTest(path) || isGenerated(path)) continue;
     const owner = owners.find((node) => path.startsWith(`${node.dir}/`));
@@ -209,12 +213,55 @@ export async function checkWorkspaceDependencies(root: string): Promise<readonly
     for (const name of importedPackages(await Bun.file(join(root, path)).text(), path)) {
       const target = byName.get(name);
       if (target === undefined || target.name === owner.name) continue;
-      if (owner.dependencies.includes(target.name)) continue;
       const pair = `${owner.dir} ${target.name}`;
+      // Fixtures still owe forward declarations, but never justify a shipped dependency.
+      (path.endsWith(FIXTURE_SUFFIX) ? fixtureUsed : used).add(pair);
+      if (owner.dependencies.includes(target.name)) continue;
       if (reported.has(pair)) continue;
       reported.add(pair);
       findings.push(undeclaredWorkspaceDepFinding(owner, target, path));
     }
   }
+  for (const owner of graph) {
+    // Only infer absence where the source contract scans. Match directory prefixes rather than
+    // observed files so a covered workspace with no source still owes removal of unused siblings.
+    const covered = SOURCE_GLOBS.some((pattern) => {
+      const directories = pattern.split('/').slice(0, -1);
+      return directories.some((_, index) =>
+        new Bun.Glob(directories.slice(0, index + 1).join('/')).match(owner.dir),
+      );
+    });
+    if (!covered || isVendored(owner.dir)) continue;
+    const unused = owner.dependencies.filter(
+      (name) =>
+        name.startsWith('@ultimat3/') &&
+        !used.has(`${owner.dir} ${name}`) &&
+        !(owner.name === '@ultimat3/cli' && CATALOG_PACKAGES.some((root) => root === name)),
+    );
+    if (unused.length === 0) continue;
+    const path = `${owner.dir}/package.json`;
+    const manifest = await readManifest(join(root, path));
+    for (const name of unused) {
+      const fields = DEPENDENCY_FIELDS.filter(
+        (field) =>
+          Object.hasOwn(asRecord(manifest?.[field]) ?? {}, name) &&
+          !(field === 'devDependencies' && fixtureUsed.has(`${owner.dir} ${name}`)),
+      );
+      if (fields.length === 0) continue;
+      // A package-wide remove would also delete a valid fixture-only development declaration.
+      const script =
+        'const [path, name, fields] = Bun.argv.slice(-3); ' +
+        'const manifest = await Bun.file(path).json(); ' +
+        'for (const field of JSON.parse(fields)) delete manifest[field]?.[name]; ' +
+        'await Bun.write(path, JSON.stringify(manifest, null, 2) + "\\n");';
+      findings.push({
+        code: 'X_PACKAGE_SHAPE',
+        cause: `${path} declares ${name} in ${fields.join(', ')}, but no eligible source in ${owner.dir} imports it`,
+        fix: `bun -e ${quoteArg(script)} -- ${quoteArg(path)} ${quoteArg(name)} ${quoteArg(JSON.stringify(fields))}`,
+        docs: ERROR_DOCS_URL,
+        at: path,
+      });
+    }
+  }
   return findings;
 }