@ultimat3/cli 17.0.0 → 18.0.0

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) };
+}

package/src/dev-purge.ts

@@ -1,5 +1,10 @@
-// The retention sweep this boot owns: the three framework tables that grow with traffic, the
-// `purge()` job that empties them and the `task` that fires it hourly.
+// The retention sweep this boot owns: the framework tables that grow with traffic, the `purge()`
+// job that empties them and the `task` that fires it hourly.
+//
+// FIVE TARGETS over six tables, `As of 2026-08-27` — `x_idempotency`, `x_rate_limit`, the two
+// `x_auth` tables under one target, `x_notify_deliveries` and `x_notify_inbox`. Counted nowhere in
+// prose but here: this header said "three" for two releases after the notify tables joined the
+// boot's DDL, which is how `x_notify_inbox` became the one framework table nothing swept.
 //
 // WHY here and not in the packages that own the tables: `postgresIdempotencyStore` (tier 3),
 // `postgresRateLimitStore` (tier 2) and `postgresAuthLimiter` (tier 2) cannot see each other and
@@ -17,6 +22,9 @@ import { purgeAuthLimits } from '@ultimat3/auth';
 import type { PostgresRateLimitStore } from '@ultimat3/http';
 import type { JobHandle, PurgeInput, PurgeTarget } from '@ultimat3/jobs';
 import { DEFAULT_PURGE_CRON, getJob, getTask, purge, task } from '@ultimat3/jobs';
+import { purgeNotifyDeliveries, purgeNotifyInbox } from '@ultimat3/notify';
+import type { InboxRetention } from './dev-notify-retention';
+import { NO_INBOX_RETENTION } from './dev-notify-retention';
 
 /** The durable queue key. Pinned, like every framework-owned job name — rows carry it. */
 export const PURGE_JOB_NAME = 'x.purge';
@@ -36,6 +44,42 @@ export const PURGE_TASK_NAME = 'x.purge.hourly';
 export interface RetentionStores {
   readonly idempotency: PostgresIdempotencyStore;
   readonly rateLimit: PostgresRateLimitStore;
+  /**
+   * The app's own answer to "how long is an unread message kept", loaded from `app.config.ts` by
+   * `loadInboxRetention`. Absent windows mean the inbox is never swept, which is the default and a
+   * decision rather than an oversight — see `NotifyConfig` in `@ultimat3/core`.
+   */
+  readonly inboxRetention?: InboxRetention | undefined;
+}
+
+/**
+ * The two notify tables, and neither store is in `RetentionStores` — deliberately, and for the
+ * reason `authTarget` is not either. `setNotifyStores` is an APP's boot line and runs when the
+ * app's modules import, which is AFTER this install; `framework-schema.ts` says so where it
+ * applies the DDL "whether or not this boot calls `setNotifyStores`". So the sweep can only ask,
+ * per attempt, what is installed now — `purgeNotifyInbox`/`purgeNotifyDeliveries` answer 0 for a
+ * memory store or none at all, which is a boot that made a decision, not a failure.
+ */
+function notifyTargets(retention: InboxRetention): readonly PurgeTarget[] {
+  return [
+    {
+      name: 'x_notify_deliveries',
+      // The job's clock, exactly as `x_rate_limit` below: `at` is written by whichever process took
+      // the delivery, so a cutoff computed inside Postgres measures the offset between two clocks
+      // rather than the age of the row. The WINDOW is the ledger's own, never named here — one
+      // number, beside the statement that reads it.
+      purgeExpired: (nowMs: number): Promise<number> => purgeNotifyDeliveries(nowMs),
+    },
+    {
+      name: 'x_notify_inbox',
+      purgeExpired: (nowMs: number): Promise<number> =>
+        purgeNotifyInbox({
+          read: retention.readMs === undefined ? undefined : new Date(nowMs - retention.readMs),
+          unread:
+            retention.unreadMs === undefined ? undefined : new Date(nowMs - retention.unreadMs),
+        }),
+    },
+  ];
 }
 
 /**
@@ -76,6 +120,7 @@ function retentionTargets(stores: RetentionStores): readonly PurgeTarget[] {
       purgeExpired: (nowMs: number): Promise<number> => stores.rateLimit.purgeExpired(nowMs),
     },
     authTarget,
+    ...notifyTargets(stores.inboxRetention ?? NO_INBOX_RETENTION),
   ];
 }
 

package/src/dev-render.ts

@@ -45,6 +45,17 @@ export type IslandResolver = (routeFile: string) => (src: string) => string;
 
 export interface DocumentOptions {
   readonly resolveIsland?: IslandResolver;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas and the apple-touch links — `PwaArtifacts.head`
+   * from `pwa-artifacts.ts`, or absent when the app is not installable.
+   *
+   * A document-level string rather than something a route's `meta()` returns: it is the same three
+   * elements on every page of the app, an installable app is one whose EVERY page carries them
+   * (a browser offers the install on whichever page the visitor landed on), and `headFromMeta`
+   * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
+   * boot knows it, the renderer cannot ask.
+   */
+  readonly pwaHead?: string;
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -68,13 +79,18 @@ export interface DevRouteData extends Record<string, unknown> {
  */
 const lang = (): string => currentLocale();
 
-const headFor = async (entry: RouteEntry, ctx: DevRouteData, data: RouteData): Promise<string> =>
+const headFor = async (
+  entry: RouteEntry,
+  ctx: DevRouteData,
+  data: RouteData,
+  options: DocumentOptions,
+): Promise<string> =>
   renderHead(
     headFromMeta(
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
     ),
-  );
+  ) + (options.pwaHead ?? '');
 
 /** `<style>` for the surface's own stylesheets, or nothing at all when the surface imports none. */
 const styleTag = (entry: RouteEntry): string => {
@@ -155,7 +171,7 @@ async function documentFrom(
 ): Promise<string> {
   const islands = collectorFor(entry, options);
   const [head, body] = await Promise.all([
-    headFor(entry, ctx, data),
+    headFor(entry, ctx, data, options),
     routeBody(entry, ctx, data, islands),
   ]);
   return (
@@ -203,7 +219,7 @@ async function resultFor(
       // correct output, no streaming benefit.
       const islands = collectorFor(entry, options);
       const [head, shell] = await Promise.all([
-        headFor(entry, request, data),
+        headFor(entry, request, data, options),
         routeBody(entry, request, data, islands),
       ]);
       return streamResult(

package/src/dev-replicator.ts

@@ -41,6 +41,24 @@ const embeddedRefusal = (): BadFlagError =>
     fix: 'DATABASE_URL=postgres://user:password@localhost:5432/app x dev --role replicator',
   });
 
+/**
+ * The relations the feed decodes: every registered entity's PHYSICAL TABLE, never its name.
+ *
+ * Both readers of this list are catalog readers. `PgReplicationStream` keeps a change only when
+ * `#entities.has(relation.name)`, and a pgoutput Relation message names the table; `warnPartialIdentity`
+ * matches the same list against `pg_class.relname`. An entity NAME is the framework's own registry
+ * key — what a cache tag, a policy and `x entities describe` are keyed by — and `entity('user',
+ * { table: 'users' })` makes the two different strings. Passing the name meant a renamed table
+ * matched nothing on either side: every change SKIPPED, and a replica-identity warning that could
+ * never fire. Latent wherever the two agree, which is every entity in `examples/dummy`.
+ *
+ * Deduplicated and sorted: two entities may share one table, and the same registry must hand the
+ * feed the same list whatever order it was registered in.
+ */
+export function replicatedRelations(): readonly string[] {
+  return [...new Set(describeEntities().map((entity) => entity.table))].sort();
+}
+
 /**
  * An entity list is the feed's filter, so an empty one is a replicator that decodes every change
  * and forwards none. Refused here rather than inside the feed: this is the layer that knows the
@@ -61,7 +79,7 @@ const noEntitiesRefusal = (): BadFlagError =>
  */
 export async function startReplicator(options: StartReplicatorOptions): Promise<RunningReplicator> {
   if (options.services.db.mode === 'embedded') throw embeddedRefusal();
-  const entities = describeEntities().map((entity) => entity.name);
+  const entities = replicatedRelations();
   if (entities.length === 0) throw noEntitiesRefusal();
 
   const selection = selectChangeFeed(options.env, { entities });

package/src/dev-runtime.ts

@@ -31,6 +31,7 @@ import { selectTransport } from '@ultimat3/realtime/server';
 import type { Storage } from '@ultimat3/storage';
 import { defineStorage, localDriver, s3Driver, usesDevStorageSecret } from '@ultimat3/storage';
 import { loadCacheTiers, startCacheTiers } from './dev-cache';
+import { loadInboxRetention } from './dev-notify-retention';
 import { installRetentionSweep } from './dev-purge';
 import type { DevDbClient } from './dev-queue';
 import { pgExecutorFor, startQueue } from './dev-queue';
@@ -327,11 +328,19 @@ export async function startServices(
       postgresAuthLimiter({ executor, clock: systemClock, policy }),
     );
     started.push(() => resetAuthLimiters());
-    // The hourly sweep over the three framework tables this boot is responsible for. Every one of
-    // them ships a `purgeExpired()` that nothing called, so every row written was a row kept —
+    // The hourly sweep over the framework tables this boot is responsible for. Every one of them
+    // ships a `purgeExpired()` that nothing called, so every row written was a row kept —
     // `x_rate_limit` takes one upsert per request the web role serves, assets included.
+    //
+    // `inboxRetention` is READ HERE and not defaulted in `dev-purge.ts`: the two windows are the
+    // app's, `startServices` holds no `AppConfig`, and a loader that silently answered "never
+    // sweep" from inside the sweep would be indistinguishable from an app that chose it.
     started.push(
-      installRetentionSweep({ idempotency: queue.idempotency, rateLimit: rateLimitStore }),
+      installRetentionSweep({
+        idempotency: queue.idempotency,
+        rateLimit: rateLimitStore,
+        inboxRetention: await loadInboxRetention(services.root),
+      }),
     );
     // One readiness check per resource this boot OWNS, released with it. Nothing in the tree
     // registered one, so `/readyz` was `markReady()` alone — "this process bound a socket" — and

package/src/dev-services.ts

@@ -21,6 +21,13 @@ export interface DevServices {
   readonly events: ServiceBinding;
   readonly storage: ServiceBinding;
   readonly stateDir: string;
+  /**
+   * The app directory itself, carried rather than re-derived from `stateDir`. A boot that needs to
+   * read the app's own `app.config.ts` — `loadInboxRetention` does — otherwise has to undo the
+   * `join(root, '.x')` above, and a `dirname` that silently disagrees with this file's join is a
+   * path bug nothing would catch.
+   */
+  readonly root: string;
 }
 
 export type Env = Readonly<Record<string, string | undefined>>;
@@ -44,6 +51,7 @@ export function resolveServices(root: string, env: Env): DevServices {
     mkdirSync(stateDir, { recursive: true });
   }
   return {
+    root,
     stateDir,
     db:
       databaseUrl === undefined

package/src/error-codes.ts

@@ -108,6 +108,14 @@ export const CLI_OWNED_ERROR_CODES = [
   // code, because the only remedy available for all of them is a line in the migration file, and
   // where that file lives is this package's fact.
   'X_MIGRATION_UNGENERATABLE',
+  // The third `subscribes:` condition, and the only one neither @ultimat3/query nor
+  // @ultimat3/db can ask. Query owns X_QUERY_SUBSCRIBES_INVALID (a declaration that cannot
+  // be acted on) and X_QUERY_SUBSCRIBES_DRIFT (it disagrees with the resolved shape); db
+  // keeps only the declared names an entity's table matches and DROPS the rest, because it
+  // has no way to tell a typo from a table another migration owns. Neither package holds
+  // both registries, so a name matching nothing was granted REPLICA IDENTITY FULL on
+  // nothing while its author read the declaration as granted (#357).
+  'X_QUERY_SUBSCRIBES_UNKNOWN',
   'X_DB_MIGRATE_FAILED',
   'X_DB_BRANCH_FAILED',
   'X_DB_STUDIO_FAILED',
@@ -258,6 +266,7 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_DB_SCHEMA_UNMIGRATED: 'an entity declaration no migration recorded',
   X_DB_SCHEMA_UNDECLARED: 'a migration records schema no entity declares',
   X_MIGRATION_UNGENERATABLE: 'this migration holds SQL no declaration carries and does not say so',
+  X_QUERY_SUBSCRIBES_UNKNOWN: 'a live query subscribes to a table no entity declares',
   X_DB_MIGRATE_FAILED: 'x db migrate failed',
   X_DB_BRANCH_FAILED: 'an x db branch step failed',
   X_DB_STUDIO_FAILED: 'x db studio failed',

package/src/icon-assets.ts

@@ -0,0 +1,74 @@
+// Single responsibility: the one source image every generated icon derives from, where the matrix
+// is served, and the renderer that turns one into the other. Its own module so the two things that
+// need it — `dev-assets.ts`, which SERVES the matrix, and `pwa-artifacts.ts`, which NAMES it in the
+// web manifest — can share it without importing each other.
+
+// why: 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 type { IconPlan } from '@ultimat3/pwa';
+import { BuiltinImagePipeline, PwaIconMissingError, planIcons } from '@ultimat3/pwa';
+
+/**
+ * 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 matrix's whole plan, off one constant pair. One call, so the icons `/icons/*` serves and the
+ * icons `manifest.webmanifest` names can never be two different lists.
+ */
+export const iconPlan = (): IconPlan =>
+  planIcons({ sourceIcon: ICON_SOURCE, outDir: ICON_BASE_PATH });
+
+/**
+ * Whether the app committed the one file the whole matrix derives from. Read where the answer
+ * changes what is EMITTED — a manifest naming twelve icons an app has no source for is twelve 404s
+ * in an install prompt, which is the promise-nothing-keeps shape this module's callers exist to
+ * close. `x doctor` owns the diagnostic and reports the same condition with `X_PWA_ICON_MISSING`.
+ */
+export const hasSourceIcon = (root: string): Promise<boolean> =>
+  Bun.file(join(root, ICON_SOURCE)).exists();
+
+/**
+ * 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.
+ */
+export 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;
+  };
+}