@cosmicdrift/kumiko-server-runtime 0.413.1 → 0.415.0

package/dist/boot/apply-boot-seeds.js

@@ -6,7 +6,6 @@ import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/
 // missing call site (e.g. someone deletes the line from runDevApp)
 // surfaces as a missing-helper-use in code review rather than silently
 // shipping a server that never seeds.
-// @wrapper-known semantic-alias
 export async function applyBootSeeds(deps) {
     return runInSystemRowLevelSecurityScope("boot seeds write rows for arbitrary tenants", async () => {
         await seedAllConfigValues(deps.registry, deps.db, deps.cipher);

package/dist/boot/search-reindex-on-boot.d.ts

@@ -12,7 +12,7 @@ export type SearchReindexOutcome = {
     readonly reindexedEntities: readonly string[];
     readonly failedEntities: readonly string[];
 };
-/** Changes when the search fields of the entity or the document format change. */
+/** Changes when the search fields, the payload extension code or the document format change. */
 export declare function searchReindexFingerprint(registry: Registry, entityName: string): string;
 export declare function runSearchReindexOnBoot(opts: {
     readonly db: DbConnection;

package/dist/boot/search-reindex-on-boot.js

@@ -16,12 +16,15 @@ function searchedEntityNames(registry) {
     return [...registry.getAllEntities().keys()].filter((name) => registry.getSearchableFields(name).length > 0 ||
         registry.getSearchPayloadExtensions(name).length > 0);
 }
-/** Changes when the search fields of the entity or the document format change. */
+/** Changes when the search fields, the payload extension code or the document format change. */
 export function searchReindexFingerprint(registry, entityName) {
     const fields = [...registry.getSearchableFields(entityName)].sort();
-    const extensionCount = registry.getSearchPayloadExtensions(entityName).length;
+    // Contributors have no name or version; their source is what decides what they add to a document.
+    const extensions = registry
+        .getSearchPayloadExtensions(entityName)
+        .map((contribute) => createHash("sha256").update(contribute.toString()).digest("hex"));
     return createHash("sha256")
-        .update(`${SEARCH_DOCUMENT_FORMAT_VERSION}|${fields.join(",")}|${extensionCount}`)
+        .update(`${SEARCH_DOCUMENT_FORMAT_VERSION}|${fields.join(",")}|${extensions.join(",")}`)
         .digest("hex")
         .slice(0, 16);
 }

package/dist/boot/shared-boot-steps.d.ts

@@ -13,6 +13,7 @@ import { type DatabaseWaitClock } from "./wait-for-database.ts";
 /** Returns `envSource` itself (it may be `process.env`) when there is nothing to layer under it. */
 export declare function withEnvDefaults(envDefaults: Readonly<Record<string, string | undefined>>, envSource: Record<string, string | undefined>): Record<string, string | undefined>;
 export declare function composeAppFeatures(appFeatures: readonly FeatureDefinition[], bootFeatures: readonly FeatureDefinition[], effectiveAuth: AuthOptionsCarrier | undefined, bundledLists?: BundledListsOptions): readonly FeatureDefinition[];
+export declare function validateBootAndWarnTz(features: readonly FeatureDefinition[], bootOptions: ValidateBootOptions): void;
 export declare function validateComposedFeatures(features: readonly FeatureDefinition[], bootOptions: ValidateBootOptions): void;
 export declare function assertMfaSwitchTenantGate(registry: Registry, processName: string): void;
 export declare function buildEffectiveFeaturesResolver(deps: {

package/dist/boot/shared-boot-steps.js

@@ -23,9 +23,12 @@ export function composeAppFeatures(appFeatures, bootFeatures, effectiveAuth, bun
         ...(bundledLists && { bundledLists }),
     });
 }
-export function validateComposedFeatures(features, bootOptions) {
+export function validateBootAndWarnTz(features, bootOptions) {
     validateBoot(features, bootOptions);
     warnIfNonUtcServerTimeZone();
+}
+export function validateComposedFeatures(features, bootOptions) {
+    validateBootAndWarnTz(features, bootOptions);
     validateAppCustomScreenWriteQns(process.cwd(), collectWriteHandlerQns(features));
 }
 export function assertMfaSwitchTenantGate(registry, processName) {

package/dist/boot/stream-tenant-backfill-on-boot.js

@@ -19,6 +19,7 @@ import { deleteMany, fetchOne, insertOne, listEventTenantIds, withSessionAdvisor
 import { createEsOperationsTable, esOperationsTable } from "@cosmicdrift/kumiko-framework/es-ops";
 import { runInSystemRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { isEntitySearchable } from "@cosmicdrift/kumiko-framework/search";
 import { waitUntilDatabaseReachable } from "./wait-for-database.js";
 export const STREAM_TENANT_BACKFILL_LOCK_KEY = 0x73_74_62_66; // 'stbf'
 export function streamBackfillPendingId(part) {
@@ -70,8 +71,7 @@ function isDeferredWithoutSearchAdapter(searchable, deps) {
 async function runPart(part, deps) {
     const { db, registry, log } = deps;
     const entity = part === "user" ? "user" : "tenant";
-    const searchable = registry.getSearchableFields(entity).length > 0 ||
-        registry.getSearchPayloadExtensions(entity).length > 0;
+    const searchable = isEntitySearchable(registry, entity);
     const blockedWithoutAdapter = isDeferredWithoutSearchAdapter(searchable, deps);
     const warnBlocked = () => log.warn(`stream tenant backfill (${part}) has work but "${entity}" is searchable and this process has no search adapter; a process with one runs it`);
     const pendingId = streamBackfillPendingId(part);

package/dist/boot/wait-for-database.js

@@ -1,4 +1,4 @@
-import { extractPgError, tableExists } from "@cosmicdrift/kumiko-framework/db";
+import { BUN_SQL_CONNECTION_ERROR_CODES, extractPgError, tableExists, } from "@cosmicdrift/kumiko-framework/db";
 const TRANSIENT_CODES = new Set([
     "53300", // too_many_connections
     "57P03", // cannot_connect_now (startup / recovery)
@@ -7,10 +7,7 @@ const TRANSIENT_CODES = new Set([
     "ETIMEDOUT",
     "ENOTFOUND",
     "EAI_AGAIN",
-    "ERR_POSTGRES_CONNECTION_CLOSED",
-    "ERR_POSTGRES_CONNECTION_REFUSED",
-    "ERR_POSTGRES_CONNECTION_TIMEOUT",
-    "ERR_POSTGRES_CONNECTION_FAILED",
+    ...BUN_SQL_CONNECTION_ERROR_CODES,
 ]);
 const CONNECTION_EXCEPTION_CLASS = "08";
 export function isTransientConnectionError(error) {

package/dist/boot/worker-boot-core.js

@@ -6,7 +6,7 @@
 import { createDefaultSseBroker, loadJwtSecretOrKeyring } from "@cosmicdrift/kumiko-framework/api";
 import { configureBlindIndexKey, configurePiiSubjectKms, resolvePlatformKeks, } from "@cosmicdrift/kumiko-framework/crypto";
 import { assertRowLevelSecurityBootState, configureEntityFieldEncryption, knownTablesOf, } from "@cosmicdrift/kumiko-framework/db";
-import { createRegistry, validateBoot, } from "@cosmicdrift/kumiko-framework/engine";
+import { createRegistry, } from "@cosmicdrift/kumiko-framework/engine";
 import { createWorkerEntrypoint, } from "@cosmicdrift/kumiko-framework/entrypoint";
 import { DEFAULT_ROW_LEVEL_SECURITY_MODE } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
 import { maintenanceWindowFromEnv } from "@cosmicdrift/kumiko-framework/jobs";
@@ -14,18 +14,18 @@ import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { assertKumikoSchemaCurrent, SchemaDriftError, } from "@cosmicdrift/kumiko-framework/migrations";
 import { createEntityCache, createEventDedup, createIdempotencyGuard, } from "@cosmicdrift/kumiko-framework/pipeline";
 import { createRedisCacheSyncBus, redisClientOptionsFromEnv, redisNamespaceFromEnv, } from "@cosmicdrift/kumiko-framework/redis";
-import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { Redis } from "ioredis";
 import { readShutdownDrainTimeoutMs } from "../boot-options/process-signals.js";
 import { composeFeatures } from "../compose-features.js";
 import { assertPiiBootInvariants } from "../pii-boot-gate.js";
 import { readEnv, requireEnv } from "../require-env.js";
+import { resolveUnsubscribeWiring } from "../resolve-unsubscribe-wiring.js";
 import { addConfigAccessorFactory, buildBootExtraContext, loggerFromExtraContext, } from "../run-prod-app-boot-context.js";
 import { resolveBootCrypto } from "./boot-crypto.js";
 import { jobRunLoggerCallbacks } from "./job-run-logger.js";
 import { INSTANCE_ID_ENV } from "./record-app-started-on-boot.js";
-import { buildEffectiveFeaturesResolver, openDatabasePools, waitForKmsHealthy, } from "./shared-boot-steps.js";
+import { buildEffectiveFeaturesResolver, openDatabasePools, validateBootAndWarnTz, waitForKmsHealthy, } from "./shared-boot-steps.js";
 import { WAIT_FOR_DATABASE_DEADLINE_MS, waitForDatabase } from "./wait-for-database.js";
 import { warnIfRowLevelSecurityOff } from "./warn-row-level-security-off.js";
 import { assertWorkerMetricsOptions } from "./worker-metrics-server.js";
@@ -43,12 +43,12 @@ export async function resolveWorkerEnvSource(options, processName) {
         })
         : rawEnvSource;
 }
-async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
+async function assertWorkerSchemaCurrent(db, migrationsDir, processName, bootedFeatures) {
     const dir = migrationsDir ?? "./kumiko/migrations";
     // biome-ignore lint/suspicious/noConsole: boot-time progress hint
     console.log(`[${processName}] checking schema drift (${dir})…`);
     try {
-        await assertKumikoSchemaCurrent(db, dir);
+        await assertKumikoSchemaCurrent(db, dir, bootedFeatures);
     }
     catch (err) {
         if (err instanceof SchemaDriftError) {
@@ -58,6 +58,16 @@ async function assertWorkerSchemaCurrent(db, migrationsDir, processName) {
         throw err;
     }
 }
+// The broker is opened before the entrypoint; a throwing entrypoint would otherwise leak its connection.
+async function createWorkerEntrypointOrCloseBroker(ownedBroker, args) {
+    try {
+        return createWorkerEntrypoint(args);
+    }
+    catch (error) {
+        await ownedBroker?.close();
+        throw error;
+    }
+}
 export async function bootWorkerProcess(options, envSource, profile) {
     const { processName } = profile;
     // Polyfill before anything else: without it every job fails with
@@ -79,12 +89,11 @@ export async function bootWorkerProcess(options, envSource, profile) {
         ...(options.bundledLists && { bundledLists: options.bundledLists }),
     });
     const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
-    validateBoot(features, {
+    validateBootAndWarnTz(features, {
         env: envSource,
         ...(bootCrypto.entityFieldCipher && { entityFieldCipher: bootCrypto.entityFieldCipher }),
         ...options.validateBootOptions,
     });
-    warnIfNonUtcServerTimeZone();
     assertWorkerMetricsOptions(options.metrics, options.observability, processName);
     assertPiiBootInvariants(features, {
         kms: options.kms,
@@ -142,7 +151,7 @@ export async function bootWorkerProcess(options, envSource, profile) {
     });
     if (options.migrations !== false) {
         try {
-            await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName);
+            await assertWorkerSchemaCurrent(db, options.migrations?.dir, processName, features);
         }
         catch (err) {
             await closeDb();
@@ -176,6 +185,13 @@ export async function bootWorkerProcess(options, envSource, profile) {
     configureBlindIndexKey(options.blindIndexKey);
     const bootLogger = loggerFromExtraContext(resolvedExtraContext);
     warnIfRowLevelSecurityOff(rowLevelSecurity, bootLogger ?? createFallbackLogger(processName));
+    const { unsubscribeLinks } = resolveUnsubscribeWiring({
+        unsubscribe: options.unsubscribe,
+        publicOrigin: undefined,
+        mailBaseUrl: undefined,
+        envSource,
+        warn: (message) => (bootLogger ?? createFallbackLogger(processName)).warn(message),
+    });
     const autoExtraContext = buildBootExtraContext({
         db,
         features,
@@ -188,11 +204,12 @@ export async function bootWorkerProcess(options, envSource, profile) {
         ...(options.kms && { kms: options.kms }),
         ...(profile.deliverQueuedInline === true && { deliverQueuedInline: true }),
         ...(bootLogger && { log: bootLogger }),
+        ...(unsubscribeLinks && { unsubscribeLinks }),
     });
     const extraContext = addConfigAccessorFactory({ ...autoExtraContext, ...resolvedExtraContext }, registry);
     const jobLogger = jobRunLoggerCallbacks(registry, db);
     const { sseBroker, ownedRedisSseBroker } = createDefaultSseBroker(envSource);
-    const entrypoint = createWorkerEntrypoint({
+    const entrypoint = await createWorkerEntrypointOrCloseBroker(ownedRedisSseBroker, {
         sseBroker,
         registry,
         rowLevelSecurity,

package/dist/boot-options/billing-option.d.ts

@@ -8,7 +8,7 @@ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
  *  (`tier-engine`). Needs `billing-foundation`, `tier-engine`, `config` and
  *  `secrets` in `features`. The env keys (`STRIPE_API_KEY` /
  *  `STRIPE_WEBHOOK_SECRET`, `PADDLE_API_KEY` / `PADDLE_WEBHOOK_SECRET` /
- *  `PADDLE_TENANT_BINDING_KEY` / `PADDLE_CLIENT_TOKEN`) are only the bridge fallback; the keys
+ *  `PADDLE_CLIENT_TOKEN`) are only the bridge fallback; the keys
  *  normally live in the secrets store.
  *
  *  @example
@@ -22,15 +22,18 @@ export type BillingBootOption = {
     /** At least one of `stripe` and `paddle` is required. */
     readonly stripe?: {
         readonly priceToTier: Readonly<Record<string, string>>;
-        /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. Applies to every provider. */
+        /** @deprecated Use `billing.webhookPath`; still read as a fallback. */
         readonly webhookPath?: string;
         readonly oneOffPriceIds?: SubscriptionStripeOptions["oneOffPriceIds"];
         readonly paymentInvoiceCreation?: boolean;
+        readonly clientConfig?: SubscriptionStripeOptions["clientConfig"];
     };
     readonly paddle?: {
         readonly priceToTier: Readonly<Record<string, string>>;
         readonly oneOffPriceIds?: SubscriptionPaddleOptions["oneOffPriceIds"];
     };
+    /** Default `SUBSCRIPTION_WEBHOOK_PATH`; must contain `:providerName`. Applies to every provider. */
+    readonly webhookPath?: string;
     /** Tier a tenant falls back to without an active subscription. */
     readonly defaultTier: string;
     /** Valid tier names beyond `defaultTier` and the `priceToTier` targets. */

package/dist/boot-options/billing-option.js

@@ -23,18 +23,17 @@ function providerFeatures({ stripe, paddle }, envSource) {
             ...(stripe.paymentInvoiceCreation !== undefined && {
                 paymentInvoiceCreation: stripe.paymentInvoiceCreation,
             }),
+            ...(stripe.clientConfig && { clientConfig: stripe.clientConfig }),
             ...bridgeCredentials(envSource, "STRIPE_API_KEY", "STRIPE_WEBHOOK_SECRET"),
         }));
     }
     if (paddle) {
-        const tenantBindingKey = envSource["PADDLE_TENANT_BINDING_KEY"];
         const clientToken = envSource["PADDLE_CLIENT_TOKEN"];
         warnOnEmptyPriceMap("paddle", paddle.priceToTier);
         features.push(createSubscriptionPaddleFeature({
             priceToTier: paddle.priceToTier,
             ...(paddle.oneOffPriceIds && { oneOffPriceIds: paddle.oneOffPriceIds }),
             ...bridgeCredentials(envSource, "PADDLE_API_KEY", "PADDLE_WEBHOOK_SECRET"),
-            ...(tenantBindingKey && { tenantBindingKey }),
             ...(clientToken && { clientToken }),
         }));
     }
@@ -45,9 +44,9 @@ export function resolveBillingOption(billing, envSource) {
     if (!stripe && !paddle) {
         throw new Error("[runProdApp] billing needs at least one provider: set billing.stripe or billing.paddle.");
     }
-    const webhookPath = stripe?.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
+    const webhookPath = billing.webhookPath ?? stripe?.webhookPath ?? SUBSCRIPTION_WEBHOOK_PATH;
     if (!webhookPath.includes(PROVIDER_NAME_PARAM)) {
-        throw new Error(`[runProdApp] billing.stripe.webhookPath "${webhookPath}" must contain ${PROVIDER_NAME_PARAM}.`);
+        throw new Error(`[runProdApp] billing.webhookPath "${webhookPath}" must contain ${PROVIDER_NAME_PARAM}.`);
     }
     const features = providerFeatures(billing, envSource);
     const tierNames = new Set([

package/dist/boot-options/file-storage-option.js

@@ -1,5 +1,5 @@
 import { createFileProviderInMemoryFeature } from "@cosmicdrift/kumiko-bundled-features/file-provider-inmemory";
-import { createFileProviderS3Feature, createFileProviderS3NamedEnvFeature, } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
+import { createFileProviderS3Feature, createFileProviderS3NamedEnvFeature, isAcceptableS3Endpoint, } from "@cosmicdrift/kumiko-bundled-features/file-provider-s3";
 import { FILE_STORAGE_PROVIDER_ENV, } from "@cosmicdrift/kumiko-framework/engine";
 export function isNamedS3FileProvider(provider) {
     return typeof provider === "object";
@@ -32,6 +32,15 @@ function assertNamedProviderNames(named) {
         seen.add(name);
     }
 }
+function assertEndpointsAcceptable(envSource, isProduction, providers) {
+    for (const { label, envPrefix } of providers) {
+        const key = `${envPrefix}ENDPOINT`;
+        const endpoint = envSource[key];
+        if (endpoint && !isAcceptableS3Endpoint(endpoint, isProduction)) {
+            throw new Error(`[runProdApp] fileStorage ${label}: ${key} must use https unless the host is loopback (NODE_ENV=production).`);
+        }
+    }
+}
 function buildProviderFeature(provider) {
     return provider === "s3-env"
         ? createFileProviderS3Feature({ fromEnv: true })
@@ -67,6 +76,10 @@ export function resolveFileStorageOption(fileStorage, deps) {
     }
     const named = additional.filter(isNamedS3FileProvider);
     assertNamedProviderNames(named);
+    assertEndpointsAcceptable(deps.envSource, deps.isProduction, [
+        ...(wanted.has("s3-env") ? [{ label: '"s3-env"', envPrefix: "S3_" }] : []),
+        ...named.map((entry) => ({ label: `provider "${entry.name}"`, envPrefix: entry.envPrefix })),
+    ]);
     for (const entry of named) {
         const missing = entry.lazy ? [] : missingEnvKeys(deps.envSource, s3KeysOf(entry.envPrefix));
         if (missing.length > 0) {

package/dist/boot-options/process-signals.d.ts

@@ -11,6 +11,8 @@ export declare const SHUTDOWN_DRAIN_TIMEOUT_ENV = "KUMIKO_SHUTDOWN_DRAIN_TIMEOUT
 export declare function readShutdownDrainTimeoutMs(env: Readonly<Record<string, string | undefined>>): number | undefined;
 /** Explicit `signals.drainTimeoutMs` wins over the env variable, which wins over the default. */
 export declare function resolveDrainTimeoutMs(explicit: number | undefined, fromEnv: number | undefined): number;
+export declare const SHUTDOWN_TAIL_RESERVE_MS = 5000;
+export declare function jobDrainBudgetMs(totalBudgetMs: number): number;
 export type SignalProcess = {
     on(signal: ShutdownSignal, listener: () => void): unknown;
     off(signal: ShutdownSignal, listener: () => void): unknown;

package/dist/boot-options/process-signals.js

@@ -18,6 +18,13 @@ export function readShutdownDrainTimeoutMs(env) {
 export function resolveDrainTimeoutMs(explicit, fromEnv) {
     return explicit ?? fromEnv ?? DEFAULT_DRAIN_TIMEOUT_MS;
 }
+// HTTP shutdown, escape-hatch audit flush and DB/Redis close run after the job drain and must fit
+// into the same signal budget, so the job drain gets the budget minus this reserve.
+export const SHUTDOWN_TAIL_RESERVE_MS = 5_000;
+const MIN_JOB_DRAIN_MS = 1_000;
+export function jobDrainBudgetMs(totalBudgetMs) {
+    return Math.max(MIN_JOB_DRAIN_MS, totalBudgetMs - SHUTDOWN_TAIL_RESERVE_MS);
+}
 /** Registers SIGTERM/SIGINT: the first signal drains via `stop()` and exits
  *  0, a drain that fails or outlives the timeout exits 1. Returns the
  *  uninstall function so `stop()` can drop the listeners again. */

package/dist/pwa-service-worker-script.d.ts

@@ -0,0 +1,10 @@
+import { PWA_CACHE_NAME_PREFIX } from "@cosmicdrift/kumiko-renderer/headless";
+export { PWA_CACHE_NAME_PREFIX };
+export type PwaServiceWorkerScriptInput = {
+    readonly cacheName: string;
+    readonly cacheScopePrefix: string;
+    readonly precacheUrls: readonly string[];
+    readonly shellUrl: string;
+    readonly serviceWorkerPath: string;
+};
+export declare function buildPwaServiceWorkerScript(input: PwaServiceWorkerScriptInput): string;

package/dist/pwa-service-worker-script.js

@@ -0,0 +1,127 @@
+// The worker is plain JS in a string because the server hands it out as is: no bundler step,
+// no workbox, nothing loaded from outside the app's own origin.
+import { PWA_CACHE_NAME_PREFIX } from "@cosmicdrift/kumiko-renderer/headless";
+export { PWA_CACHE_NAME_PREFIX };
+// Cache names before scoping were `kumiko-pwa-<16hex>`; kept only so an update drops those precaches once.
+// The pattern also matches the precache of another app on the same origin that still runs an old
+// framework version; accepted, because that app only has to precache again.
+const UNSCOPED_CACHE_NAME_PATTERN = /^kumiko-pwa-[0-9a-f]{16}$/;
+const SERVICE_WORKER_BODY = `
+const PASS_THROUGH_PATHS = ["/api", "/sse", "/auth", "/health", "/build-info.json", SERVICE_WORKER_PATH, "/_reload"];
+const PASS_THROUGH_PREFIXES = ["/api/", "/sse/", "/auth/"];
+
+function isPassThrough(request, url) {
+  if (request.method !== "GET") return true;
+  if (url.origin !== self.location.origin) return true;
+  if ((request.headers.get("accept") || "").includes("text/event-stream")) return true;
+  if (PASS_THROUGH_PATHS.includes(url.pathname)) return true;
+  return PASS_THROUGH_PREFIXES.some((prefix) => url.pathname.startsWith(prefix));
+}
+
+// A redirected response served to a navigation request makes the browser reject it.
+function isCacheable(response) {
+  return (
+    response.ok &&
+    response.type === "basic" &&
+    !response.redirected &&
+    !(response.headers.get("cache-control") || "").includes("no-store")
+  );
+}
+
+async function storeInCache(request, response) {
+  if (!isCacheable(response)) return;
+  const cache = await caches.open(CACHE_NAME);
+  await cache.put(request, response);
+}
+
+async function precache() {
+  const cache = await caches.open(CACHE_NAME);
+  await Promise.all(
+    PRECACHE_URLS.map(async (url) => {
+      try {
+        const response = await fetch(new Request(url, { cache: "reload" }));
+        if (isCacheable(response)) await cache.put(url, response);
+      } catch {
+        // One missing file must not block the install; it is cached on first use instead.
+      }
+    }),
+  );
+}
+
+async function deleteOldCaches() {
+  const names = await caches.keys();
+  await Promise.all(
+    names
+      .filter(
+        (name) =>
+          (name.startsWith(CACHE_SCOPE_PREFIX) || UNSCOPED_CACHE_NAME_PATTERN.test(name)) &&
+          name !== CACHE_NAME,
+      )
+      .map((name) => caches.delete(name)),
+  );
+}
+
+async function networkFirstNavigation(request) {
+  try {
+    return await fetch(request);
+  } catch {
+    const cache = await caches.open(CACHE_NAME);
+    return (await cache.match(SHELL_URL, { ignoreVary: true })) || Response.error();
+  }
+}
+
+async function networkFirst(request) {
+  try {
+    const response = await fetch(request);
+    await storeInCache(request, response.clone());
+    return response;
+  } catch {
+    const cache = await caches.open(CACHE_NAME);
+    return (await cache.match(request, { ignoreVary: true })) || Response.error();
+  }
+}
+
+async function cacheFirst(request) {
+  const cache = await caches.open(CACHE_NAME);
+  const cached = await cache.match(request, { ignoreVary: true });
+  if (cached) return cached;
+  const response = await fetch(request);
+  await storeInCache(request, response.clone());
+  return response;
+}
+
+self.addEventListener("install", (event) => {
+  event.waitUntil(precache().then(() => self.skipWaiting()));
+});
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(deleteOldCaches().then(() => self.clients.claim()));
+});
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request;
+  const url = new URL(request.url);
+  if (isPassThrough(request, url)) return;
+  if (request.mode === "navigate") {
+    event.respondWith(networkFirstNavigation(request));
+    return;
+  }
+  // Hashed build output never changes under one URL; everything else must not go stale.
+  if (url.pathname.startsWith("/assets/")) {
+    event.respondWith(cacheFirst(request));
+    return;
+  }
+  if (PRECACHE_URLS.includes(url.pathname)) event.respondWith(networkFirst(request));
+});
+`;
+export function buildPwaServiceWorkerScript(input) {
+    return [
+        `const CACHE_SCOPE_PREFIX = ${JSON.stringify(input.cacheScopePrefix)};`,
+        `const CACHE_NAME = ${JSON.stringify(input.cacheName)};`,
+        `const UNSCOPED_CACHE_NAME_PATTERN = ${UNSCOPED_CACHE_NAME_PATTERN.toString()};`,
+        `const SHELL_URL = ${JSON.stringify(input.shellUrl)};`,
+        `const SERVICE_WORKER_PATH = ${JSON.stringify(input.serviceWorkerPath)};`,
+        `const PRECACHE_URLS = ${JSON.stringify(input.precacheUrls)};`,
+        SERVICE_WORKER_BODY,
+    ].join("\n");
+}

package/dist/pwa.d.ts

@@ -0,0 +1,32 @@
+export type PwaIconPurpose = "any" | "maskable" | "monochrome";
+export type PwaIcon = {
+    /** Same-origin path, e.g. `/icons/app-192.png`; the app serves the file itself (usually from `public/`). */
+    readonly src: string;
+    /** `"192x192"`, several sizes separated by spaces, or `"any"` for SVG. */
+    readonly sizes: string;
+    readonly type?: string;
+    readonly purpose?: PwaIconPurpose;
+};
+export type PwaOptions = {
+    readonly name: string;
+    readonly shortName: string;
+    readonly themeColor: string;
+    readonly backgroundColor: string;
+    readonly icons: readonly PwaIcon[];
+    /** Directory the app is served under, e.g. `/a/`; starts and ends with `/`. Default `/`. */
+    readonly basePath?: string;
+};
+export type PwaShellBuild = {
+    /** Same-origin URLs of the client bundles and stylesheet the shell loads. */
+    readonly appShellUrls: readonly string[];
+    /** Changes whenever the served bundles change, so a new build gets a new cache. */
+    readonly buildToken: string;
+};
+export type PwaShell = {
+    readonly cacheName: string;
+    readonly injectHeadTags: (html: string) => string;
+    /** undefined: not a PWA file, the request goes on to the normal routes. */
+    readonly respond: (req: Request, pathname: string) => Response | undefined;
+};
+export declare function buildWebManifest(options: PwaOptions): Readonly<Record<string, unknown>>;
+export declare function createPwaShell(options: PwaOptions, build: PwaShellBuild): PwaShell;

package/dist/pwa.js

@@ -0,0 +1,134 @@
+import { createHash } from "node:crypto";
+import { escapeHtmlAttr, PWA_CACHE_SCOPE_HASH_LENGTH, PWA_SERVICE_WORKER_META_NAME, } from "@cosmicdrift/kumiko-renderer/headless";
+import { buildPwaServiceWorkerScript, PWA_CACHE_NAME_PREFIX } from "./pwa-service-worker-script.js";
+const DEFAULT_PWA_BASE_PATH = "/";
+const MANIFEST_FILE = "manifest.webmanifest";
+const SERVICE_WORKER_FILE = "sw.js";
+function pwaPathsOf(options) {
+    const basePath = options.basePath ?? DEFAULT_PWA_BASE_PATH;
+    return {
+        shellUrl: basePath,
+        manifestPath: `${basePath}${MANIFEST_FILE}`,
+        serviceWorkerPath: `${basePath}${SERVICE_WORKER_FILE}`,
+    };
+}
+// "/x" only: "//host/x" and "/\host" are protocol-relative to browsers (which also strip tab and
+// newline before parsing), and the worker precaches every icon, so a foreign URL would be fetched
+// from the user's browser.
+function isSameOriginPath(src) {
+    return /^\/(?![/\\])/.test(src) && !src.includes("\\") && !/[\s\p{Cc}]/u.test(src);
+}
+function isValidBasePath(basePath) {
+    if (!isSameOriginPath(basePath) || !basePath.endsWith("/"))
+        return false;
+    if (basePath.includes("?") || basePath.includes("#"))
+        return false;
+    const segments = basePath.slice(1, -1).split("/");
+    if (basePath === "/")
+        return true;
+    return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+function assertValidPwaOptions(options) {
+    const basePath = options.basePath;
+    if (basePath !== undefined && !isValidBasePath(basePath)) {
+        throw new Error(`[pwa] basePath "${basePath}" must be a same-origin path that starts and ends with "/", has no empty, "." or ".." segment and no "?" or "#".`);
+    }
+    for (const icon of options.icons) {
+        if (!isSameOriginPath(icon.src)) {
+            throw new Error(`[pwa] icon src "${icon.src}" must be a same-origin path starting with a single "/".`);
+        }
+    }
+}
+export function buildWebManifest(options) {
+    const { shellUrl } = pwaPathsOf(options);
+    return {
+        id: shellUrl,
+        name: options.name,
+        short_name: options.shortName,
+        start_url: shellUrl,
+        scope: shellUrl,
+        display: "standalone",
+        theme_color: options.themeColor,
+        background_color: options.backgroundColor,
+        icons: options.icons.map((icon) => ({
+            src: icon.src,
+            sizes: icon.sizes,
+            ...(icon.type !== undefined && { type: icon.type }),
+            ...(icon.purpose !== undefined && { purpose: icon.purpose }),
+        })),
+    };
+}
+function largestEdge(sizes) {
+    return Math.max(0, ...sizes.split(/\s+/).map((size) => Number.parseInt(size, 10) || 0));
+}
+// iOS ignores the manifest icons and crops maskable artwork badly, so it gets the
+// largest plain icon.
+function pickAppleTouchIcon(icons) {
+    const plain = icons.filter((icon) => icon.purpose === undefined || icon.purpose === "any");
+    return [...plain].sort((a, b) => largestEdge(b.sizes) - largestEdge(a.sizes))[0];
+}
+function buildHeadTags(options) {
+    const appleIcon = pickAppleTouchIcon(options.icons);
+    const { manifestPath, serviceWorkerPath } = pwaPathsOf(options);
+    return [
+        `<link rel="manifest" href="${escapeHtmlAttr(manifestPath)}" />`,
+        `<meta name="theme-color" content="${escapeHtmlAttr(options.themeColor)}" />`,
+        `<meta name="mobile-web-app-capable" content="yes" />`,
+        `<meta name="apple-mobile-web-app-capable" content="yes" />`,
+        `<meta name="apple-mobile-web-app-title" content="${escapeHtmlAttr(options.shortName)}" />`,
+        ...(appleIcon
+            ? [`<link rel="apple-touch-icon" href="${escapeHtmlAttr(appleIcon.src)}" />`]
+            : []),
+        `<meta name="${PWA_SERVICE_WORKER_META_NAME}" content="${escapeHtmlAttr(serviceWorkerPath)}" />`,
+    ].join("\n    ");
+}
+function computeCacheVersion(options, build) {
+    return createHash("sha256").update(JSON.stringify({ options, build })).digest("hex").slice(0, 16);
+}
+function fileResponse(req, body, contentType) {
+    return new Response(req.method === "HEAD" ? null : body, {
+        headers: { "content-type": contentType, "cache-control": "no-cache" },
+    });
+}
+export function createPwaShell(options, build) {
+    assertValidPwaOptions(options);
+    const paths = pwaPathsOf(options);
+    const cacheScopePrefix = `${PWA_CACHE_NAME_PREFIX}${createHash("sha256").update(paths.shellUrl).digest("hex").slice(0, PWA_CACHE_SCOPE_HASH_LENGTH)}-`;
+    const cacheName = `${cacheScopePrefix}${computeCacheVersion(options, build)}`;
+    const precacheUrls = [
+        ...new Set([
+            paths.shellUrl,
+            paths.manifestPath,
+            ...options.icons.map((icon) => icon.src),
+            ...build.appShellUrls,
+        ]),
+    ];
+    const manifestBody = JSON.stringify(buildWebManifest(options));
+    const serviceWorkerBody = buildPwaServiceWorkerScript({
+        cacheName,
+        cacheScopePrefix,
+        precacheUrls,
+        shellUrl: paths.shellUrl,
+        serviceWorkerPath: paths.serviceWorkerPath,
+    });
+    const headTagsHtml = buildHeadTags(options);
+    return {
+        cacheName,
+        injectHeadTags: (html) => 
+        // A replacer function, so a "$&" in an app name is not read as a replacement pattern.
+        html.includes("</head>")
+            ? html.replace("</head>", () => `  ${headTagsHtml}\n  </head>`)
+            : html,
+        respond: (req, pathname) => {
+            if (req.method !== "GET" && req.method !== "HEAD")
+                return undefined;
+            if (pathname === paths.manifestPath) {
+                return fileResponse(req, manifestBody, "application/manifest+json");
+            }
+            if (pathname === paths.serviceWorkerPath) {
+                return fileResponse(req, serviceWorkerBody, "text/javascript; charset=utf-8");
+            }
+            return undefined;
+        },
+    };
+}

package/dist/run-prod-app-boot-context.js

@@ -4,7 +4,7 @@ import { resolveSessionStore } from "@cosmicdrift/kumiko-bundled-features/auth-f
 import { bindMfaRevokeAllOtherSessionsFromFeature, bindRevokeAllPatTokensFromFeature, } from "@cosmicdrift/kumiko-bundled-features/auth-mfa";
 import { createSmtpTransportFromEnv } from "@cosmicdrift/kumiko-bundled-features/channel-email";
 import { buildEnvConfigOverrides, createConfigAccessorFactory, createConfigResolver, validateAppOverrides, } from "@cosmicdrift/kumiko-bundled-features/config";
-import { collectChannels, createDeliveryNotifyFactory, createDeliveryService, DELIVERY_FEATURE, } from "@cosmicdrift/kumiko-bundled-features/delivery";
+import { collectChannels, createDeliveryAttemptLogFactory, createDeliveryNotifyFactory, createDeliveryService, DELIVERY_FEATURE, } from "@cosmicdrift/kumiko-bundled-features/delivery";
 import { bindPatAutoRevokeOnPasswordChangeFromFeature, revokeAllPatTokensForUser, } from "@cosmicdrift/kumiko-bundled-features/personal-access-tokens";
 import { createSecretsContext, SECRETS_FEATURE_NAME, } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import { bindAutoRevokeFromFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
@@ -50,7 +50,9 @@ export function addConfigAccessorFactory(resolved, registry) {
 // the calling context's job runner (3rd factory arg); without one they send
 // inline, with `secrets` for chat-channel credentials. `to: { tenant }` resolves
 // through tenantUserIdsQuery, which the caller sets when the tenant feature is mounted.
-function buildDeliveryNotifyFactory(opts) {
+// The attempt log factory shares the service, so a handler sending through a channel itself
+// logs exactly like ctx.notify does.
+function buildDeliveryContextFactories(opts) {
     if (!opts.addressCipher && opts.deliverQueuedInline !== true) {
         createFallbackLogger("delivery", opts.log).warn("No master key configured: queued delivery jobs carry recipient addresses in plaintext " +
             "(Redis, job runs). Set KUMIKO_SECRETS_MASTER_KEY_V1 (and KUMIKO_SECRETS_MASTER_KEY_CURRENT_VERSION) " +
@@ -80,9 +82,12 @@ function buildDeliveryNotifyFactory(opts) {
             },
         }),
     });
-    return createDeliveryNotifyFactory(deliveryService, {
-        deliverQueuedInline: opts.deliverQueuedInline === true,
-    });
+    return {
+        _notifyFactory: createDeliveryNotifyFactory(deliveryService, {
+            deliverQueuedInline: opts.deliverQueuedInline === true,
+        }),
+        _deliveryAttemptLogFactory: createDeliveryAttemptLogFactory(deliveryService),
+    };
 }
 function isLogger(value) {
     if (typeof value !== "object" || value === null)
@@ -149,7 +154,7 @@ function bootDeliveryContext(opts, parts) {
     const hasTenantFeature = opts.features.some((f) => f.name === TENANT_FEATURE);
     const { crypto, secrets, escapeHatchAuditSink } = parts;
     return {
-        _notifyFactory: buildDeliveryNotifyFactory({
+        ...buildDeliveryContextFactories({
             db: opts.db,
             registry: opts.registry,
             ...(secrets && { secrets }),

package/dist/run-prod-app-connections.d.ts

@@ -1,4 +1,5 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { Logger } from "@cosmicdrift/kumiko-framework/logging";
 import { createRedisCacheSyncBus, type RedisNamespace } from "@cosmicdrift/kumiko-framework/redis";
 import { Redis } from "ioredis";
@@ -15,4 +16,4 @@ export type ProdConnections = {
     readonly cacheSync: ReturnType<typeof createRedisCacheSyncBus>;
 };
 export declare function connectProdDependencies(config: ProdBootConfig, log: Logger, registerAbortCleanup: RegisterBootAbortCleanup, databaseWait?: DatabaseWaitClock): Promise<ProdConnections>;
-export declare function assertProdSchemaCurrent(db: DbConnection, migrations: RunProdAppOptions["migrations"], log: Logger): Promise<void>;
+export declare function assertProdSchemaCurrent(db: DbConnection, migrations: RunProdAppOptions["migrations"], log: Logger, bootedFeatures: readonly FeatureDefinition[]): Promise<void>;

package/dist/run-prod-app-connections.js

@@ -49,12 +49,12 @@ export async function connectProdDependencies(config, log, registerAbortCleanup,
 // kumiko/migrations/.snapshot.json exists. Drift aborts boot rather than being auto-healed, avoiding
 // races between container replicas. `migrations: false` opts out for custom
 // schema setups.
-export async function assertProdSchemaCurrent(db, migrations, log) {
+export async function assertProdSchemaCurrent(db, migrations, log, bootedFeatures) {
     if (migrations !== false) {
         const migrationsDir = migrations?.dir ?? "./kumiko/migrations";
         log.info(`checking schema drift (${migrationsDir})`);
         try {
-            await assertKumikoSchemaCurrent(db, migrationsDir);
+            await assertKumikoSchemaCurrent(db, migrationsDir, bootedFeatures);
         }
         catch (err) {
             if (err instanceof SchemaDriftError) {

package/dist/run-prod-app-handle.js

@@ -1,9 +1,10 @@
 import { assertNoActiveRowLevelSecurityScope } from "@cosmicdrift/kumiko-framework/db";
 import { flushEscapeHatchAudits } from "@cosmicdrift/kumiko-framework/pipeline";
-import { installShutdownSignals, resolveDrainTimeoutMs } from "./boot-options/process-signals.js";
+import { installShutdownSignals, jobDrainBudgetMs, resolveDrainTimeoutMs, } from "./boot-options/process-signals.js";
 import { buildBunServeOptions, resolveDerivedMaxRequestBodySize } from "./bun-serve-options.js";
 import { installFatalErrorHandlers } from "./fatal-error-handlers.js";
 import { uninstallProcessLogger } from "./process-logger.js";
+import { loadProdPwaShell } from "./run-prod-app-pwa.js";
 import { buildStaticFallback, resolveCspScriptHashes, resolveHostDispatchScriptHashes, } from "./run-prod-app-static-files.js";
 import { withSecurityHeaders } from "./security-headers.js";
 import { stripNoRouteMatchHeader } from "./try-hono-first.js";
@@ -30,10 +31,11 @@ export async function buildProdFetchHandler(options, config, entrypoint) {
     const hostDispatchScriptHashes = options.hostDispatch !== undefined && options.staticDir !== undefined
         ? await resolveHostDispatchScriptHashes(options.staticDir, options.securityHeaders, cspScriptHashes)
         : [];
+    const pwaShell = await loadProdPwaShell(options.pwa, options.staticDir);
     const fetchHandler = withSecurityHeaders(config.bootOptionWiring.wrapFetch(options.staticDir
         ? buildStaticFallback(entrypoint.app.fetch.bind(entrypoint.app), options.staticDir, options.hostDispatch, options.resolvePageHead
             ? { resolvePageHead: options.resolvePageHead, dispatcher: entrypoint.dispatcher }
-            : undefined, entrypoint.dispatcher, config.trustedProxyHops ?? 0, hostDispatchScriptHashes)
+            : undefined, entrypoint.dispatcher, config.trustedProxyHops ?? 0, hostDispatchScriptHashes, pwaShell)
         : // No staticDir (split-deploy / API-only container) → app.fetch's
             // response goes straight to the client, bypassing buildStaticFallback
             // (and with it tryHonoFirst) entirely. Must strip the router-miss
@@ -51,8 +53,12 @@ export function createProdAppHandle(input) {
     const webSocketUpgradeFetch = async (req, env) => securedUpgradeFetch(req, env);
     const explicitDrainTimeoutMs = options.signals === false ? undefined : options.signals?.drainTimeoutMs;
     const drainTimeoutMs = resolveDrainTimeoutMs(explicitDrainTimeoutMs, config.shutdownDrainTimeoutMs);
-    // Without a configured budget the lifecycle keeps its own default for programmatic stop().
-    const jobDrainTimeoutMs = explicitDrainTimeoutMs ?? config.shutdownDrainTimeoutMs;
+    // With signals off and no configured budget nothing bounds stop(), so the lifecycle keeps its own default.
+    const jobDrainTimeoutMs = options.signals === false &&
+        explicitDrainTimeoutMs === undefined &&
+        config.shutdownDrainTimeoutMs === undefined
+        ? undefined
+        : jobDrainBudgetMs(drainTimeoutMs);
     let uninstallShutdownSignals;
     let uninstallFatalHandlers;
     const handle = {

package/dist/run-prod-app-pwa.d.ts

@@ -0,0 +1,2 @@
+import { type PwaOptions, type PwaShell } from "./pwa.ts";
+export declare function loadProdPwaShell(pwa: PwaOptions | undefined, staticDir: string | undefined): Promise<PwaShell | undefined>;

package/dist/run-prod-app-pwa.js

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { createPwaShell } from "./pwa.js";
+import { readStaticFile } from "./run-prod-app-static-files.js";
+// Both files are written by kumiko build next to index.html: manifest.json maps logical
+// names to the hashed asset URLs, build-info.json carries the build id.
+const BUILD_ASSET_MANIFEST_FILE = "manifest.json";
+const BUILD_INFO_FILE = "build-info.json";
+async function readJsonFile(path) {
+    const file = await readStaticFile(path);
+    if (!file)
+        return undefined;
+    try {
+        return JSON.parse(new TextDecoder().decode(file.bytes));
+    }
+    catch {
+        return undefined;
+    }
+}
+function hashedAssetUrls(manifest) {
+    if (!isPlainObject(manifest))
+        return [];
+    return Object.values(manifest).filter((url) => typeof url === "string" && url.startsWith("/"));
+}
+function buildIdOf(buildInfo) {
+    return isPlainObject(buildInfo) && typeof buildInfo["id"] === "string" ? buildInfo["id"] : "";
+}
+export async function loadProdPwaShell(pwa, staticDir) {
+    if (pwa === undefined)
+        return undefined;
+    if (staticDir === undefined) {
+        throw new Error("[runProdApp] `pwa` needs `staticDir`: the HTML shell is served from there.");
+    }
+    const [assetManifest, buildInfo] = await Promise.all([
+        readJsonFile(join(staticDir, BUILD_ASSET_MANIFEST_FILE)),
+        readJsonFile(join(staticDir, BUILD_INFO_FILE)),
+    ]);
+    const appShellUrls = hashedAssetUrls(assetManifest);
+    // Without build-info.json the hashed URLs still change with every build.
+    return createPwaShell(pwa, { appShellUrls, buildToken: buildIdOf(buildInfo) });
+}

package/dist/run-prod-app-seeds.js

@@ -50,7 +50,6 @@ async function runSeedMigrations(run, seedsDir, seedDispatcher) {
         seedsDir,
         appliedBy: "boot",
         registry: run.composed.registry, // The dry-run validator catches handler QN typos before writing.
-        // @wrapper-known semantic-alias
         createContext: (dbRunner) => createSeedMigrationContext({ dispatcher: seedDispatcher, dbRunner }),
     });
 }

package/dist/run-prod-app-static-files.d.ts

@@ -1,4 +1,5 @@
 import { type CachePolicy } from "@cosmicdrift/kumiko-framework/api";
+import type { PwaShell } from "./pwa.ts";
 import { type QueryDispatcher } from "./request-bound-system-query.ts";
 import type { HostDispatchFn, PageHeadResolver } from "./run-prod-app.ts";
 import type { SecurityHeadersOption } from "./security-headers.ts";
@@ -34,5 +35,5 @@ hostDispatchDispatcher?: QueryDispatcher,
  *  1:1 with runProdApp's effective value. */
 trustedProxyHops?: number, 
 /** Build inline-script hashes, passed through to hostDispatch's deps. */
-hostDispatchScriptHashes?: readonly string[]): (req: Request, socketAddress?: string) => Promise<Response>;
+hostDispatchScriptHashes?: readonly string[], pwa?: PwaShell): (req: Request, socketAddress?: string) => Promise<Response>;
 export declare function staticCachePolicy(pathname: string): CachePolicy;

package/dist/run-prod-app-static-files.js

@@ -154,7 +154,7 @@ hostDispatchDispatcher,
  *  1:1 with runProdApp's effective value. */
 trustedProxyHops = 0, 
 /** Build inline-script hashes, passed through to hostDispatch's deps. */
-hostDispatchScriptHashes = []) {
+hostDispatchScriptHashes = [], pwa) {
     const indexHtml = `${staticDir}/index.html`;
     const clientIpResolver = createClientIpResolver(trustedProxyHops, "buildStaticFallback");
     // Reads an HTML file from disk. No schema injection — createKumikoApp
@@ -164,6 +164,11 @@ hostDispatchScriptHashes = []) {
         const file = await readStaticFile(path);
         if (!file)
             return null;
+        if (pwa) {
+            // No mtime: the injected tags come from the boot options, not from the file.
+            const encoded = new TextEncoder().encode(pwa.injectHeadTags(new TextDecoder().decode(file.bytes)));
+            return { bytes: encoded.buffer, mime: file.mime, etag: computeStrongEtag(encoded) };
+        }
         return {
             bytes: new Uint8Array(file.bytes).buffer,
             mime: file.mime,
@@ -289,6 +294,9 @@ hostDispatchScriptHashes = []) {
         if (url.pathname.startsWith("/api/") || url.pathname === "/health") {
             return stripNoRouteMatchHeader(await apiHandler(req, socketAddress));
         }
+        const pwaFile = pwa?.respond(req, url.pathname);
+        if (pwaFile)
+            return pwaFile;
         // Try Hono before disk lookup so extraRoutes (for example /feed.xml and
         // /sitemap.xml) and r.httpRoute features (for example /legal/*) are handled
         // before unknown paths fall through to index.html. Keep this consistent with

package/dist/run-prod-app.d.ts

@@ -23,6 +23,7 @@ import type { MailBootOption } from "./boot-options/mail-option.ts";
 import type { SignalsOption } from "./boot-options/process-signals.ts";
 import type { ProdSeedsConfig } from "./boot-options/seed-shortcuts.ts";
 import type { SystemWireDeps } from "./extra-routes-deps.ts";
+import type { PwaOptions } from "./pwa.ts";
 import type { RateLimitOption } from "./rate-limit-defaults.ts";
 import type { UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
 import type { ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
@@ -331,6 +332,11 @@ export type RunProdAppOptions = {
      *  anonymous role (not system) — the resolver is reachable by any
      *  public visitor, same access gate as a real anonymous request. */
     readonly resolvePageHead?: PageHeadResolver;
+    /** Installable web app: serves `/manifest.webmanifest` and `/sw.js`, adds the manifest,
+     *  theme-color and apple-touch tags to every HTML shell of `staticDir`, and the web client
+     *  then registers the service worker and offers a one-time install hint. Requires
+     *  `staticDir`. Pass the same value to `runDevApp`. Unset: none of this happens. */
+    readonly pwa?: PwaOptions;
     /** Path to kumiko/migrations for the boot gate. Default "./kumiko/migrations"
      *  relative to the process cwd. Boot throws SchemaDriftError on pending
      *  migrations or missing tables. `false` disables the gate for setups that

package/dist/run-prod-app.js

@@ -7,7 +7,7 @@
 //   - Hard schema-drift gate: checks kumiko/migrations against
 //     _kumiko_migrations and verifies every expected table with tableExists.
 //     Boot never runs CREATE TABLE automatically; migrations are applied by
-//     CI (`bun kumiko schema apply`) and boot only validates them. This avoids
+//     CI (`bun /app/kumiko.js schema apply`) and boot only validates them. This avoids
 //     races in multi-replica deployments and keeps schema state reviewable.
 //   - Idempotent seeds run only when the database is empty, using an
 //     `isDbEmpty` probe per seed. Reboots after the first seed are no-ops.
@@ -132,7 +132,7 @@ async function bootProdApp(options, registerAbortCleanup) {
         registry,
         cacheSync: connections.cacheSync,
     });
-    await assertProdSchemaCurrent(connections.db, options.migrations, log);
+    await assertProdSchemaCurrent(connections.db, options.migrations, log, features);
     await assertRowLevelSecurityBootState(connections.db, config.rowLevelSecurity, knownTablesOf(features));
     warnIfRowLevelSecurityOff(config.rowLevelSecurity, log);
     const requestContext = await buildProdRequestContext(options, config, composed, connections);

package/dist/run-worker-app.d.ts

@@ -16,6 +16,7 @@ import type { FileStorageBootOption } from "./boot-options/file-storage-option.t
 import type { KmsMode } from "./boot-options/kms-mode.ts";
 import type { MailBootOption } from "./boot-options/mail-option.ts";
 import { type SystemWireDeps } from "./extra-routes-deps.ts";
+import type { UnsubscribeOption } from "./resolve-unsubscribe-wiring.ts";
 import type { ConfigOverridesInput } from "./run-prod-app-boot-context.ts";
 export type WorkerContextOption = Record<string, unknown> | ((deps: WorkerDeps) => Record<string, unknown>);
 export type WorkerDeps = {
@@ -112,6 +113,10 @@ export type RunWorkerAppOptions = {
     readonly billing?: BillingBootOption;
     /** Same as RunProdAppOptions["featureToggles"]: mounts feature-toggles and layers the operator switches over the tier resolver. */
     readonly featureToggles?: boolean;
+    /** Signs the unsubscribe links of `unsubscribe: true` mails that jobs in this process trigger, as
+     *  RunProdAppOptions["unsubscribe"] does. The unsubscribe routes stay in the API process; `secret`
+     *  must be the same there. The public URL comes from `APP_BASE_URL`. */
+    readonly unsubscribe?: UnsubscribeOption;
     /** Composed env schema (see RunProdAppOptions["envSchema"]). With it the worker validates its env,
      *  derives the KMS slots from it (`kmsSlots` is ignored) and understands every `KUMIKO_DRY_RUN_ENV`
      *  mode. Without it only `KUMIKO_DRY_RUN_ENV=boot` is available. */

package/dist/run-worker-app.js

@@ -23,6 +23,7 @@ import { runEnvGate } from "./boot/env-gate.js";
 import { startPiiEventBackfillOnBoot } from "./boot/pii-event-backfill-on-boot.js";
 import { recordAppStartedOnBoot } from "./boot/record-app-started-on-boot.js";
 import { startSearchReindexOnBoot } from "./boot/search-reindex-on-boot.js";
+import { withEnvDefaults } from "./boot/shared-boot-steps.js";
 import { runStreamTenantBackfillOnBoot, } from "./boot/stream-tenant-backfill-on-boot.js";
 import { bootWorkerProcess, resolveWorkerEnvSource, } from "./boot/worker-boot-core.js";
 import { startWorkerMetricsServer, } from "./boot/worker-metrics-server.js";
@@ -77,9 +78,7 @@ export async function runWorkerApp(options) {
     log.info("booting Kumiko worker");
     assertWorkerStackRequirements(options);
     const wiring = await resolveBootOptionWiring(options, resolvedEnvSource);
-    const envSource = Object.keys(wiring.envDefaults).length > 0
-        ? { ...wiring.envDefaults, ...resolvedEnvSource }
-        : resolvedEnvSource;
+    const envSource = withEnvDefaults(wiring.envDefaults, resolvedEnvSource);
     let boot;
     try {
         boot = await bootWorkerProcess({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.413.1",
+  "version": "0.415.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold tooling.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -82,6 +82,10 @@
       "types": "./dist/try-hono-first.d.ts",
       "default": "./dist/try-hono-first.js"
     },
+    "./pwa": {
+      "types": "./dist/pwa.d.ts",
+      "default": "./dist/pwa.js"
+    },
     "./request-bound-system-query": {
       "types": "./dist/request-bound-system-query.d.ts",
       "default": "./dist/request-bound-system-query.js"
@@ -96,11 +100,11 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.413.1",
-    "@cosmicdrift/kumiko-framework": "0.413.1",
-    "@cosmicdrift/kumiko-renderer": "0.413.1",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.413.1",
-    "@cosmicdrift/kumiko-types": "0.413.1",
+    "@cosmicdrift/kumiko-bundled-features": "0.415.0",
+    "@cosmicdrift/kumiko-framework": "0.415.0",
+    "@cosmicdrift/kumiko-renderer": "0.415.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.415.0",
+    "@cosmicdrift/kumiko-types": "0.415.0",
     "ioredis": "^5.11.1",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.6.7"
@@ -109,7 +113,7 @@
     "bun-types": "^1.4.4"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.413.1",
+    "@cosmicdrift/kumiko-testing": "0.415.0",
     "bun-types": "^1.4.4"
   },
   "publishConfig": {
@@ -180,6 +184,10 @@
         "types": "./dist/try-hono-first.d.ts",
         "default": "./dist/try-hono-first.js"
       },
+      "./pwa": {
+        "types": "./dist/pwa.d.ts",
+        "default": "./dist/pwa.js"
+      },
       "./request-bound-system-query": {
         "types": "./dist/request-bound-system-query.d.ts",
         "default": "./dist/request-bound-system-query.js"

package/src/changes.json

@@ -1,4 +1,34 @@
 [
+  {
+    "version": "0.415.0",
+    "type": "fix",
+    "title": "PWA update removes the precache of the unscoped cache name format",
+    "detail": "Caches named kumiko-pwa-<16hex> from before the per-scope prefix were never deleted after an update. The service worker now drops them once, and keeps caches of other scopes and foreign libraries."
+  },
+  {
+    "version": "0.415.0",
+    "type": "improvement",
+    "title": "runWorkerApp accepts the unsubscribe option",
+    "detail": "Pass the same `unsubscribe: { secret }` to runWorkerApp as to runProdApp; a job in the worker (e.g. a cron digest) that sends an `unsubscribe: true` notification then gets a signed link from `APP_BASE_URL`. The unsubscribe routes stay in the API process, which must use the same secret. Before, such mails went out without a link."
+  },
+  {
+    "version": "0.414.0",
+    "type": "improvement",
+    "title": "The stripe boot option passes clientConfig",
+    "detail": "`billing: { stripe: { clientConfig } }` is handed to the subscription-stripe feature, so an app can set the Stripe client configuration (API version, retries, host) from the boot options."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "provider-wide billing webhookPath, shared worker boot steps, no leaked SSE broker",
+    "detail": "`billing.webhookPath` replaces `billing.stripe.webhookPath` (deprecated, still read as a fallback) and the error message names the new key. `runWorkerApp` applies env defaults through `withEnvDefaults` and `bootWorkerProcess` validates through the shared `validateBootAndWarnTz` step. If `createWorkerEntrypoint` throws, the Redis SSE broker opened before it is closed instead of keeping the process alive. The stream tenant backfill decides searchability with the shared `isEntitySearchable`."
+  },
+  {
+    "version": "0.414.0",
+    "type": "fix",
+    "title": "job drain leaves a tail reserve of the shutdown budget",
+    "detail": "The SIGTERM timer and the job drain in `stop()` used the same budget, so a job that ran the whole time ended the process with exit code 1 before the HTTP shutdown, the escape-hatch audit flush and the connection close ran. The job drain now gets the budget minus a 5 s reserve (at least 1 s). `KUMIKO_SHUTDOWN_DRAIN_TIMEOUT_MS` is the budget for both."
+  },
   {
     "version": "0.411.0",
     "type": "improvement",