@ultimat3/cli 17.0.0 → 19.0.0

package/src/cmd-doctor.ts

@@ -10,8 +10,8 @@ import { STORAGE_SIGNING_SECRET_KEY, usesDevStorageSecret } from '@ultimat3/stor
 import { findAppRoot, REQUIRED_BUN, versionAtLeast } from './app-root';
 import type { CliCommand, CommandContext } from './command';
 import { checkMigrationSnapshots } from './db-snapshot';
-import { ICON_SOURCE } from './dev-assets';
 import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
+import { ICON_SOURCE } from './icon-assets';
 import { msg } from './messages';
 import type { CommandResult, Finding } from './output';
 import type { ParsedArgs } from './parse';

package/src/cmd-test.ts

@@ -20,7 +20,7 @@ import { discoverTests, missingSelection, readSample, readType, sampleFiles } fr
 import { runShards } from './test-shards';
 import { defaultWorkers, WORKER_CEILING, WORKER_FLOOR, WORKER_OVERSUBSCRIBE } from './test-workers';
 import type { TestType } from './verify-tests';
-import { TEST_TYPES } from './verify-tests';
+import { SERIAL_TYPES, TEST_TYPES } from './verify-tests';
 
 /**
  * `--workers` and `--shard`. `Number.parseInt` alone accepted `4abc` and `4.9` as four, while
@@ -33,10 +33,10 @@ const readIndex = (args: ParsedArgs, name: string, min: number): number | undefi
     command: 'test',
     min,
     // The ceiling the summary already claimed and the reader never enforced: `--workers 5000` was
-    // accepted, `planShards` clamps only to the file count, and `runParallel` `Promise.all`s them —
-    // one Bun process per test FILE, each with the framework module graph and a cloned database.
-    // `--worker` is an index into that split, so the same bound holds it (the exact upper index is
-    // `workers - 1`, refused a line below by the check that knows the real width).
+    // accepted and the run clamps only to the file count, which is one Bun worker per test FILE,
+    // each with the framework module graph and a cloned database. `--worker` is an index into an
+    // N-way split, so the same bound holds it (the exact upper index is `workers - 1`, refused a
+    // line below by the check that knows the real width).
     max: WORKER_CEILING,
     example: `x test --${name} ${Math.max(min, 1)}`,
   });
@@ -103,19 +103,20 @@ export const testCommand: CliCommand = {
   spec: {
     name: 'test',
     summary:
-      'run one test type — or the whole suite — across N processes, one isolated database per worker',
+      'run one test type — or the whole suite — across N workers, one isolated database per worker',
     usage: `x test [${TEST_TYPES.join('|')}] [--filter text] [--sample N] [--affected [--base ref] [--dirty]] [--workers N] [--worker I] [--json]`,
     positionalChoices: TEST_TYPES,
     flags: [
       {
         name: 'workers',
         type: 'string',
-        summary: `process count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING})`,
+        summary: `bun worker count (default: ${WORKER_OVERSUBSCRIBE}x CPUs, min ${WORKER_FLOOR}, max ${WORKER_CEILING}); clamped to the file count, and to 1 for ${SERIAL_TYPES.join(' and ')}`,
       },
       {
         name: 'worker',
         type: 'string',
-        summary: 'rerun only shard I of the same split — reproduces a CI worker failure locally',
+        summary:
+          'run only shard I of an N-way split of the selection, serially — one CI job\u2019s share',
       },
       { name: 'filter', type: 'string', summary: 'only files whose path contains this substring' },
       {
@@ -172,7 +173,17 @@ export const testCommand: CliCommand = {
     }
     const files = sample === undefined ? selected : sampleFiles(selected, sample);
     const requested = readIndex(ctx.args, 'workers', 1) ?? defaultWorkers();
-    const workers = Math.max(1, Math.min(requested, files.length));
+    // A serial type is serial HERE TOO, `As of 2026-08-27`. `verify-tests.ts` routes `live` and
+    // `e2e` through `runSerial` and this command never read the same list, so `x verify` ran one
+    // process over the very files `x test live --workers 8` ran eight over — two answers to one
+    // question, which is axiom 1, and the dangerous one is the command a human types while
+    // debugging. What makes them serial is not a preference: a logical replication slot is named
+    // at the Postgres CLUSTER level, so a per-worker database does not isolate it and two workers
+    // race `pg_create_logical_replication_slot`; `e2e` shares one built `dist/` and one browser
+    // profile. Neither is visible without a real `TEST_DATABASE_URL`, which is why the split
+    // measured green for as long as it did.
+    const ceiling = type !== undefined && SERIAL_TYPES.includes(type) ? 1 : files.length;
+    const workers = Math.max(1, Math.min(requested, ceiling));
     const only = readIndex(ctx.args, 'worker', 0);
     if (only !== undefined && only >= workers) {
       throw new BadFlagError({

package/src/compile-externals.ts

@@ -11,10 +11,17 @@
  * anyway, and that is the whole failure: Bun 1.3 refuses the build with
  * `Could not resolve: "@babel/preset-typescript/package.json"`, while Bun 1.4 bundles the
  * unresolvable `require` as a runtime throw — so one tree compiled on a laptop and did not in CI.
- * That skew is closed `As of 2026-08-20`: CI pins `1.4.x` (`.github/actions/setup/action.yml`),
- * `docker/Dockerfile` builds on `oven/bun:1.4-slim` and `scripts/setup.ts` holds contributors to
- * 1.4.0, so every builder now takes the second branch. The external stays regardless — it is the
- * `--compile` graph that must not reach an unresolvable `require`, on either Bun.
+ *
+ * **This list is what closed that, and the version pin never was.** The paragraph here said the
+ * skew was closed `As of 2026-08-20` by CI moving to `1.4.x`, "so every builder now takes the
+ * second branch", and added that the external stays regardless. Read together those are two fixes
+ * for one bug, and only the second is a fix: pinning the whole repository to the Bun that TOLERATES
+ * an unresolvable `require` leaves the `--compile` graph still reaching one, so the next Bun that
+ * tightens resolution breaks the build again. Marking the specifier external means the graph never
+ * reaches it, on either Bun — measured on 2026-08-27, when the 1.4 pin was trialled in reverse:
+ * `docker build -f docker/Dockerfile` is green on `oven/bun:1.3-slim` and the image answers
+ * `--version`. So this file does not depend on the series above it, and a future move of that pin
+ * costs it nothing.
  *
  * Marking the dead specifier external rather than the two live ones: `serve.ts` calls
  * `buildIslands` on every boot, unconditionally, so a binary with `@babel/core` external is a

package/src/db-accept-created.ts

@@ -0,0 +1,207 @@
+// Single responsibility: accept a table an applied migration's own SQL created. A snapshot records
+// only what ENTITIES declare, so a hand-written `create table` is `unexpected-table` on every
+// deploy forever (issue #345) — and the migration list `x db migrate` has just applied is the one
+// piece of evidence that the app owns the relation. Named in `@ultimat3/db`'s `unexpectedTable`.
+
+import type { DriftReport, Migration } from '@ultimat3/db';
+import { statementsOf } from '@ultimat3/db';
+
+/**
+ * `create table`, `create unlogged table`, either with `if not exists`. Anchored, so only the verb
+ * phrase a statement OPENS with counts.
+ *
+ * `temp`/`temporary` is deliberately absent: a temporary table lives in `pg_temp` and can never be
+ * the relation `checkDrift` introspected, so reading one as evidence would accept a `drafts`
+ * somebody created by hand on the strength of SQL that never touched it.
+ */
+const CREATE_TABLE = /^create\s+(?:unlogged\s+)?table\s+(?:if\s+not\s+exists\s+)?/i;
+
+/**
+ * `drop table`, with `if exists`. A migration that creates a relation and later drops it OWNS
+ * neither: re-creating `legacy_audit` by hand afterwards is drift, and a set that only ever grew
+ * accepted it forever. `cascade`/`restrict` and a comma list are handled by the caller.
+ */
+const DROP_TABLE = /^drop\s+table\s+(?:if\s+exists\s+)?/i;
+
+/** `alter table … rename to …` — the old name stops existing and the new one starts. */
+const ALTER_TABLE = /^alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?/i;
+const RENAME_TO = /^\s*rename\s+to\s+/i;
+
+/**
+ * One identifier: quoted (with `""` for a literal quote) or bare. The bare form is Postgres' own
+ * charset — a letter or `_` to open, then letters, digits, `_` and `$` — with everything above
+ * ASCII admitted, since the server accepts any multibyte letter and a name it accepts must be
+ * readable here or the relation behind it is drift nobody can clear.
+ */
+const NAME = /^(?:("(?:[^"]|"")+")|([A-Za-z_\u0080-\uFFFF][A-Za-z0-9_$\u0080-\uFFFF]*))/;
+
+/** A qualifier's dot, with the whitespace Postgres allows on either side of it. */
+const DOT = /^\s*\.\s*/;
+
+/** The schema `checkDrift` compares — `introspect()`'s default, and what `runMigrations` asks for. */
+const COMPARED_SCHEMA = 'public';
+
+/**
+ * Postgres folds an unquoted identifier to lower case and stores a quoted one verbatim, so
+ * `CREATE TABLE LegacyAudit` and `create table legacyaudit` are the same relation and
+ * `"LegacyAudit"` is a different one. The catalog name is what a drift difference carries, so the
+ * fold has to happen here or the comparison misses on every unquoted name that was not typed flat.
+ */
+function unquote(match: RegExpExecArray): string {
+  const quoted = match[1];
+  if (quoted === undefined) return (match[2] ?? '').toLowerCase();
+  return quoted.slice(1, -1).replaceAll('""', '"');
+}
+
+/**
+ * The relation one statement creates, or `null`.
+ *
+ * **The anchor is the whole protection**, and it is read off the raw text. A statement can only
+ * open with `create table` by BEING one: `values ('create table ghost')` opens with `insert`, and
+ * a chunk that is nothing but a comment is not a statement at all (`statementsOf` drops it). A
+ * `stripSqlNoise` pass was written here first and then deleted — it could not change one answer,
+ * because position 0 is the one position no literal, comment or dollar body can cover, and a
+ * defence that cannot fail is a defence nobody can test.
+ *
+ * Anything the anchor admits but the name grammar does not — a comment between the keywords,
+ * `create table (` — contributes nothing. Fail-closed: drift that could have been accepted is
+ * reported, never the reverse.
+ */
+function createdBy(statement: string): string | null {
+  const text = statement.trimStart();
+  const head = CREATE_TABLE.exec(text);
+  if (head === null) return null;
+  const rest = text.slice(head[0].length);
+  const first = NAME.exec(rest);
+  if (first === null) return null;
+
+  const tail = rest.slice(first[0].length);
+  const dot = DOT.exec(tail);
+  if (dot === null) return unquote(first);
+  const second = NAME.exec(tail.slice(dot[0].length));
+  if (second === null) return null;
+  // A qualifier naming another schema is evidence about a relation this report never mentions:
+  // `checkDrift` introspects one schema, and `audit.drafts` is not the `drafts` it compared.
+  return unquote(first) === COMPARED_SCHEMA ? unquote(second) : null;
+}
+
+/**
+ * Every relation a migration script creates, in statement order.
+ *
+ * `statementsOf` is `@ultimat3/db`'s own splitter — the one `x db migrate` sends by — so a `;`
+ * inside a literal, an identifier or a dollar-quoted body is not a statement boundary here either.
+ */
+export function createdTables(up: string): readonly string[] {
+  const owned = new Set<string>();
+  applyOwnership(up, owned);
+  return [...owned];
+}
+
+/**
+ * Fold one migration's statements over the owned set, IN ORDER.
+ *
+ * A set that only ever grew was the defect: `create table legacy_audit` followed by
+ * `drop table legacy_audit` left the name accepted, so a `legacy_audit` somebody re-created by
+ * hand afterwards lost its `unexpected-table` finding — real drift, silenced, which is the one
+ * thing this module may not do.
+ *
+ * Fail-closed on anything the grammar cannot read: a `drop`/`rename` this cannot parse REMOVES
+ * nothing it is unsure about only when it could not name a relation at all; when it can name one,
+ * dropping it from the set is always the safe direction, because the cost of being wrong is a
+ * difference reported that could have been accepted.
+ */
+function applyOwnership(up: string, owned: Set<string>): void {
+  for (const statement of statementsOf(up)) {
+    const created = createdBy(statement);
+    if (created !== null) {
+      owned.add(created);
+      continue;
+    }
+    for (const dropped of droppedBy(statement)) owned.delete(dropped);
+    const renamed = renamedBy(statement);
+    if (renamed === null) continue;
+    // Only inherit ownership when the OLD name was owned: renaming a hand-made table into a name
+    // a migration once created must not launder it into an accepted one.
+    owned.delete(renamed.from);
+    if (renamed.owned) owned.add(renamed.to);
+  }
+}
+
+/** Every relation one `drop table` names — the form takes a comma list. */
+function droppedBy(statement: string): readonly string[] {
+  const text = statement.trimStart();
+  const head = DROP_TABLE.exec(text);
+  if (head === null) return [];
+  const dropped: string[] = [];
+  let rest = text.slice(head[0].length);
+  for (;;) {
+    const name = qualifiedName(rest);
+    if (name === null) break;
+    if (name.table !== null) dropped.push(name.table);
+    if (!/^\s*,/.test(name.rest)) break;
+    rest = name.rest.replace(/^\s*,\s*/, '');
+  }
+  return dropped;
+}
+
+/** `alter table <old> rename to <new>`, or `null`. `owned` is filled in by the caller's set. */
+function renamedBy(statement: string): { from: string; to: string; owned: boolean } | null {
+  const text = statement.trimStart();
+  const head = ALTER_TABLE.exec(text);
+  if (head === null) return null;
+  const source = qualifiedName(text.slice(head[0].length));
+  if (source === null || source.table === null) return null;
+  const verb = RENAME_TO.exec(source.rest);
+  if (verb === null) return null;
+  const target = qualifiedName(source.rest.slice(verb[0].length));
+  if (target === null || target.table === null) return null;
+  return { from: source.table, to: target.table, owned: true };
+}
+
+/**
+ * One optionally schema-qualified relation name and what follows it. `table` is `null` when the
+ * qualifier names a schema `checkDrift` never introspected — the same rule `createdBy` applies.
+ */
+function qualifiedName(input: string): { table: string | null; rest: string } | null {
+  const first = NAME.exec(input);
+  if (first === null) return null;
+  const tail = input.slice(first[0].length);
+  const dot = DOT.exec(tail);
+  if (dot === null) return { table: unquote(first), rest: tail };
+  const second = NAME.exec(tail.slice(dot[0].length));
+  if (second === null) return null;
+  const rest = tail.slice(dot[0].length + second[0].length);
+  return { table: unquote(first) === COMPARED_SCHEMA ? unquote(second) : null, rest };
+}
+
+/**
+ * The drift report minus the tables these migrations demonstrably create.
+ *
+ * **Only `unexpected-table`, and only for a name a migration's SQL creates.** That is what makes
+ * this an acceptance and not the check switched off: a table absent from the snapshot produces
+ * exactly ONE difference (`diffSchema` reports it and never compares its columns), so nothing else
+ * about the relation was being said, and every difference about a table that IS declared — a
+ * missing column, a changed index, a dropped constraint — passes through untouched.
+ *
+ * The migrations are the list `x db migrate` applied immediately before the check, which is why
+ * "created" is provable rather than assumed: `runMigrations` applies every pending file and then
+ * asks, so a `create table` still on disk and unapplied is not one this path can be handed.
+ *
+ * Identity in, identity out when nothing matched — a report this has nothing to say about is not
+ * its to rebuild.
+ */
+export function acceptCreatedTables(
+  report: DriftReport,
+  migrations: readonly Migration[],
+): DriftReport {
+  // In migration ORDER, across the whole list: ownership is a running state, not a union. A
+  // relation created by 0003 and dropped by 0007 is owned by neither.
+  const created = new Set<string>();
+  for (const migration of migrations) applyOwnership(migration.up, created);
+  if (created.size === 0) return report;
+  const differences = report.differences.filter(
+    (difference) => !(difference.kind === 'unexpected-table' && created.has(difference.table)),
+  );
+  if (differences.length === report.differences.length) return report;
+  return { ok: differences.length === 0, differences };
+}

package/src/db-generate.ts

@@ -13,7 +13,9 @@ import {
   snapshotJson,
 } from '@ultimat3/db';
 import { describeEntities } from '@ultimat3/entity';
+import { describeQueries } from '@ultimat3/query';
 import { loadApp } from './app-load';
+import { replicaIdentityTables } from './db-subscribes';
 import { reconcileSchemaHash, writeSchemaHash } from './drift';
 import { hashFileName, MIGRATIONS_DIR, readMigrations, snapshotFileName } from './migrations';
 import type { Finding } from './output';
@@ -103,10 +105,25 @@ export async function generateAppMigration(
     throw migrationSnapshotMissing(id, join(MIGRATIONS_DIR, snapshotFileName(id)));
   }
 
+  const entities = describeEntities();
+  // Read AFTER the findings check above, never before: a module that would not import leaves the
+  // registry short, and every `subscribes:` name whose entity lives in that module would then look
+  // like a typo. The refusal below is only sound over a whole registry.
+  //
+  // `describeQueries()` is the manifest's own source — `frameworkSources` copies this exact field
+  // onto `QueryFact.subscribes` and changes nothing — so this is the manifest fact one hop earlier.
+  // Building the manifest here would re-load the app and demand a `package.json`, which `x db gen`
+  // has never needed: generation reads declarations and writes files.
+  const replicaIdentityFull = replicaIdentityTables(
+    describeQueries(),
+    new Set(entities.map((entity) => entity.table)),
+  );
+
   const migration = generateMigration({
-    entities: describeEntities(),
+    entities,
     current,
     name: options.name,
+    replicaIdentityFull,
     ...(options.allowDestructive === true ? { allowDestructive: true } : {}),
   });
   // An empty diff writes no MIGRATION — one with no statement still takes a ledger row, a checksum

package/src/db-subscribes.ts

@@ -0,0 +1,81 @@
+// Single responsibility: which tables `x db gen` must grant `REPLICA IDENTITY FULL`, read off the
+// live queries' DECLARED `subscribes:` — and the refusal for a declared name no entity's table
+// matches. This tier is the only one holding both registries, so it is the only one that can ask.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * The two fields this reads, and nothing else. Structurally satisfied by `QueryDescriptor` (whose
+ * `subscribes` is `null` when the read declared none) and by `@ultimat3/manifest`'s `QueryFact`
+ * (where it is absent instead) — one function over both spellings of one fact, rather than a
+ * projection per caller that could disagree about which reads are subscribed.
+ */
+export interface SubscribingQuery {
+  readonly name: string;
+  readonly subscribes?: readonly string[] | null | undefined;
+}
+
+/** Enough of the app's own tables to act on, without printing a hundred of them into one line. */
+const NAMED_IN_FIX = 10;
+
+function offer(tables: ReadonlySet<string>): string {
+  const known = [...tables].sort();
+  if (known.length === 0) return 'this app declares no entity at all — x g entity Note body:text';
+  const shown = known.slice(0, NAMED_IN_FIX).join(', ');
+  return known.length > NAMED_IN_FIX ? `${shown} and ${known.length - NAMED_IN_FIX} more` : shown;
+}
+
+/**
+ * A live read declares a relation this app has no entity for.
+ *
+ * Refused rather than dropped, and that is the whole point of the check: `@ultimat3/db` keeps only
+ * the declared names an entity's table matches (`replica-identity.ts`), so an EXTRA name is
+ * discarded in silence — and `@ultimat3/query` has no table catalog, so its own `subscribes:`
+ * assertions cannot see one either. A typo therefore granted `REPLICA IDENTITY FULL` to nothing
+ * while its author read the declaration as granted, which is the failure #357 exists to end.
+ *
+ * The name goes in the `cause` and never into a command: it is a string from the app's own source,
+ * and the remedy is an edit to a field rather than anything to paste at a shell.
+ */
+export class QuerySubscribesUnknownError extends UltimateError {
+  constructor(input: { query: string; table: string; tables: ReadonlySet<string> }) {
+    super({
+      code: 'X_QUERY_SUBSCRIBES_UNKNOWN',
+      cause:
+        `the query "${input.query}" declares subscribes: ["${input.table}"] and no entity ` +
+        'declares a table with that name',
+      fix:
+        `edit subscribes: on the query "${input.query}" to name a table this app declares ` +
+        `(${offer(input.tables)}), or drop the name — x db gen grants REPLICA IDENTITY FULL to ` +
+        'exactly the tables it lists, and would have granted it to nothing',
+      meta: { query: input.query, table: input.table },
+    });
+  }
+}
+
+/**
+ * The tables to hand `GenerateOptions.replicaIdentityFull`, deduped and sorted.
+ *
+ * Sorted so the same app generates the same bytes whatever order its modules registered in — the
+ * rule `@ultimat3/db`'s own `pending()` states one layer down, kept here too because a caller that
+ * ordered by registration would put a diff in a file for nothing.
+ *
+ * Every name is checked against `tables` BEFORE any of them is returned: a run that emitted the
+ * good half and refused afterwards would leave an author with a migration that is right for one
+ * table and silently absent for the other.
+ */
+export function replicaIdentityTables(
+  queries: readonly SubscribingQuery[],
+  tables: ReadonlySet<string>,
+): readonly string[] {
+  const wanted = new Set<string>();
+  for (const query of queries) {
+    for (const table of query.subscribes ?? []) {
+      if (!tables.has(table)) {
+        throw new QuerySubscribesUnknownError({ query: query.name, table, tables });
+      }
+      wanted.add(table);
+    }
+  }
+  return [...wanted].sort();
+}

package/src/db-ungeneratable.ts

@@ -58,8 +58,20 @@ export function declaredUngeneratable(up: string): number {
  * the statement stays, and the next author to squash these migrations is told by the file itself
  * that regenerating it loses something. Re-declaring is available only for the statements an
  * entity can express — an enum is a text column plus a check invariant, which `x db gen` writes —
- * and never for `REPLICA IDENTITY FULL`, which nothing in the framework emits, so a `fix:` naming
- * only the second branch would be an instruction half its readers cannot carry out.
+ * so a `fix:` naming only the second branch would be an instruction some of its readers cannot
+ * carry out.
+ *
+ * `REPLICA IDENTITY FULL` used to be the example of a statement with no second branch at all, and
+ * it stopped being one on 2026-08-26 (#357): a live query DECLARES the relations it is patched
+ * from (`subscribes:`), `db-subscribes.ts` reads them off the registry the manifest is built from,
+ * and `x db gen` emits the ALTER and records it on the snapshot. So the re-declare branch now
+ * covers it too: declare `subscribes:` on the live query and regenerate.
+ *
+ * A committed `replica identity full`/`default` ALTER is NOT counted, `As of 2026-08-26`:
+ * `GENERATABLE_FORMS` carries the verb phrase, so a squash no longer loses it and no marker is
+ * owed for one. Measured on `examples/dummy/packages/db/migrations/0001_init.sql`: 7 found and 7
+ * declared before that entry, 5 and 5 after. `using index` and `nothing` are NOT on the list —
+ * the generator emits neither, so those stay hand-written and stay counted.
  */
 export class MigrationUngeneratableError extends UltimateError {
   constructor(input: { file: string; declared: number; statements: readonly string[] }) {

package/src/dev-assets.ts

@@ -5,14 +5,9 @@
 // thing it does NOT decide is who may read a stored object: `/media` borrows that whole answer
 // from `dev-storage.ts`, because the same bytes are reachable through both.
 
-// `join` is `node:`-only by necessity: Bun exposes no path-join primitive, and `ICON_SOURCE` is
-// app-root-relative, so resolving it against the root is string work no `Bun.file` overload does.
-import { join } from 'node:path';
 import { probeImage } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
-import type { IconPlan } from '@ultimat3/pwa';
-import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
 import type { ImageQuery, ImageTransformDriver } from '@ultimat3/seo';
 import { builtinImageDriver, DEFAULT_WIDTHS, parseImageQuery } from '@ultimat3/seo';
 import type { ImageTransform, Storage, VariantFormat } from '@ultimat3/storage';
@@ -24,16 +19,13 @@ import {
   STORAGE_READ_PERMISSION,
 } from './dev-storage';
 import { faviconRoute } from './favicon';
-
-/**
- * The one source image every generated icon derives from. `x new` scaffolds it, `x doctor` checks
- * it and this file reads it — one constant, because a second spelling is an app that passes the
- * diagnostic and still serves no icons. PNG, not SVG: core's pipeline decodes PNG and JPEG only.
- */
-export const ICON_SOURCE = 'apps/web/site/icon.png';
-
-/** Where `planIcons` writes, and therefore the paths the generated web manifest names. */
-export const ICON_BASE_PATH = '/icons';
+// The icon matrix's source, its base path and its renderer live in their own module so that
+// `pwa-artifacts.ts` — which this file imports for the manifest route — can reach them without
+// importing this one back. A cycle between the two would be the manifest and the icons it names
+// resolving through each other.
+import { iconPlan, iconRenderer } from './icon-assets';
+import type { PwaArtifacts } from './pwa-artifacts';
+import { pwaManifestRoute } from './pwa-artifacts';
 
 /**
  * Storage-backed images. `responsiveImage({ src: '/media/<key>' })` mints its variants under it.
@@ -171,50 +163,18 @@ async function mediaResponse(
   return imageResponse(read.bytes, read.object.contentType, mediaCache(key));
 }
 
-/**
- * Rendered once per process, not per request: the fourteen matrix entries are pure functions of
- * one source file, and re-encoding a 512px PNG on every hit would be work no caller can observe.
- */
-function iconRenderer(root: string): (plan: IconPlan, path: string) => Promise<Uint8Array> {
-  const pipeline = new BuiltinImagePipeline();
-  const rendered = new Map<string, Promise<Uint8Array>>();
-  const sourceBytes = async (): Promise<Uint8Array> => {
-    const file = Bun.file(join(root, ICON_SOURCE));
-    if (!(await file.exists())) {
-      throw new PwaIconMissingError(
-        `${ICON_SOURCE} does not exist, so every icon the web manifest declares is unbacked and ` +
-          'the app is not installable',
-        // The same edit `x doctor` reports for the same condition, in `@ultimat3/pwa`'s own words.
-        // `x new` was here and takes an app name, so it could never run inside the broken app.
-        `add a 1024x1024 square PNG at ${ICON_SOURCE}`,
-      );
-    }
-    return file.bytes();
-  };
-  return async (plan, path) => {
-    const entry = plan.entries.find((candidate) => candidate.outputPath === path);
-    if (entry === undefined) {
-      throw new PwaIconMissingError(
-        `${path} is not in the icon matrix, so no transform describes it`,
-        `request one of ${plan.entries.map((one) => one.outputPath).join(', ')}`,
-      );
-    }
-    const existing = rendered.get(path);
-    if (existing !== undefined) return existing;
-    const bytes = sourceBytes().then((source) => pipeline.resize(source, entry.transform));
-    rendered.set(path, bytes);
-    // A failed render must not be remembered — the next request comes after the source was added.
-    bytes.catch(() => rendered.delete(path));
-    return bytes;
-  };
-}
-
 export interface AssetRoutesOptions {
   /** App root. The source icon is resolved against it; storage keys never are. */
   readonly root: string;
   readonly storage: Storage;
   /** Replaces `builtinImageDriver` for `/media/*`. Omitted, core's PNG/JPEG pipeline. */
   readonly images?: ImageTransformDriver;
+  /**
+   * `manifest.webmanifest`, resolved at boot by `pwa-artifacts.ts`. Absent when the app declares
+   * `pwa.enabled: false` — and then no route is mounted at all, rather than one answering an empty
+   * document: a manifest a browser can fetch is a promise the app is installable.
+   */
+  readonly pwa?: PwaArtifacts;
 }
 
 /**
@@ -225,7 +185,9 @@ export interface AssetRoutesOptions {
  * this package's own rule forbids. `x dev` owns the runtime half, the diagnostic owns the other.
  */
 export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
-  const plan = planIcons({ sourceIcon: ICON_SOURCE, outDir: ICON_BASE_PATH });
+  // `iconPlan()`, never a second `planIcons` call: the icons this mounts and the icons
+  // `manifest.webmanifest` names are one list, or the manifest promises a size nothing mints.
+  const plan = iconPlan();
   const render = iconRenderer(options.root);
 
   const routes: Route[] = plan.entries.map((entry) => ({
@@ -260,6 +222,9 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
   // container is the dev/prod difference this package's own rule forbids. `favicon.ts` owns what
   // the answer IS — this file only says the app's asset surface is where it hangs.
   routes.push(faviconRoute(options.root));
+  // Same rule one asset further along: the icons above are the ones this manifest NAMES, so the
+  // two belong to one surface and cannot be mounted from two places without drifting apart.
+  if (options.pwa !== undefined) routes.push(pwaManifestRoute(options.pwa));
 
   return routes;
 }

package/src/dev-notify-retention.ts

@@ -0,0 +1,69 @@
+// `notify.inboxReadRetentionMs` and `notify.inboxUnreadRetentionMs`, read out of the app's own
+// `app.config.ts`. The sibling of `app-auth.ts`'s `loadSignInPath` and `dev-cache.ts`'s
+// `loadCacheTiers`, and structural for the same reason: `defineConfig` returns a plain object, so
+// a config that resolved through an older core simply has no `notify` section.
+//
+// WHY A LOADER AND NOT A BOOT ARGUMENT: `startServices` has no `AppConfig` — the app's modules
+// import after it, which is the same reason `configureAuthLimiters` takes a factory. A key read
+// here is a key read from the file the operator edited, per boot.
+
+// why: Bun ships no path-joining API — `Object.keys(Bun)` has `file`, `write`, `Glob`,
+// `pathToFileURL` and `fileURLToPath`, and nothing that joins a path.
+import { join } from 'node:path';
+import { INBOX_RETENTION_KEYS } from '@ultimat3/core';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+
+/**
+ * The two windows in milliseconds, each `undefined` where the app named none.
+ *
+ * ABSENT IS A DECISION, not a missing default, and it is the only safe one: an inbox row is a
+ * message a person has not read yet, so when it disappears is the app's call (axiom 8). The
+ * framework picking a number silently is the failure this whole key exists to avoid.
+ */
+export interface InboxRetention {
+  readonly readMs: number | undefined;
+  readonly unreadMs: number | undefined;
+}
+
+/** Nothing swept — what a boot with no config file, no `notify` section or no keys resolves to. */
+export const NO_INBOX_RETENTION: InboxRetention = Object.freeze({
+  readMs: undefined,
+  unreadMs: undefined,
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+/**
+ * Re-screened here rather than trusted from `defineConfig`. That validator runs when the app
+ * IMPORTS its config, and this loader imports the module for its export — so a config object
+ * assembled by hand, or one that resolved through a core too old to validate the section, reaches
+ * this line unchecked. A window that is not a positive finite number reads as absent: refusing
+ * would take the sweep over the other four framework tables down with it, and the whole point of
+ * the key is that not sweeping is a legal state.
+ */
+const windowOf = (section: Record<string, unknown>, key: string): number | undefined => {
+  const value = section[key];
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined;
+  return value;
+};
+
+export async function loadInboxRetention(root: string): Promise<InboxRetention> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  // `Bun.file(p).exists()` rather than `existsSync`: this function is already async, so the
+  // `node:fs` import buys nothing here — and an import with nothing to say for itself is what
+  // `bun run node-imports` refuses.
+  if (!(await Bun.file(configPath).exists())) return NO_INBOX_RETENTION;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return NO_INBOX_RETENTION;
+  const notify = config['notify'];
+  if (!isRecord(notify)) return NO_INBOX_RETENTION;
+  // Keyed off core's own list rather than two string literals here, so the two names exist in one
+  // place. What actually stops a third window being declared-and-never-read is
+  // `bun run scripts/config-readers.ts` — every leaf key of `AppConfig` needs a reader or a pinned
+  // reason, and it is the guard whose own header calls that "the framework's most repeated defect".
+  const [readKey, unreadKey] = INBOX_RETENTION_KEYS;
+  return { readMs: windowOf(notify, readKey), unreadMs: windowOf(notify, unreadKey) };
+}