@cosmicdrift/kumiko-server-runtime 0.172.0 → 0.173.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.172.0",
+  "version": "0.173.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/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -30,6 +30,10 @@
       "types": "./src/run-prod-app.ts",
       "default": "./src/run-prod-app.ts"
     },
+    "./run-worker-app": {
+      "types": "./src/run-worker-app.ts",
+      "default": "./src/run-worker-app.ts"
+    },
     "./bun-serve-options": {
       "types": "./src/bun-serve-options.ts",
       "default": "./src/bun-serve-options.ts"
@@ -72,8 +76,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.172.0",
-    "@cosmicdrift/kumiko-framework": "0.172.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.173.0",
+    "@cosmicdrift/kumiko-framework": "0.173.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/run-worker-app-boot.test.ts

@@ -0,0 +1,99 @@
+// Boot-mode + KMS-gate tests for runWorkerApp — no real Postgres/Redis
+// needed (like run-prod-app-env-source.test.ts): KUMIKO_DRY_RUN_ENV=boot
+// exits BEFORE any connection, and the KMS health gate runs BEFORE
+// createDbConnection/new Redis(...) — so neither path needs real infra.
+
+import { describe, expect, test } from "bun:test";
+import type { KmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import { runWorkerApp } from "../run-worker-app";
+import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
+
+const probeFeature = makeProbeFeature({
+  name: "worker-boot-probe",
+  table: "worker_boot_probe",
+});
+
+const DUMMY_ENV = {
+  DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
+  REDIS_URL: "redis://127.0.0.1:1",
+  JWT_SECRET: "smokesmokesmokesmokesmokesmokesmokesmoke",
+} as const;
+
+describe("runWorkerApp boot-mode", () => {
+  withClearedBootEnv();
+
+  test("KUMIKO_DRY_RUN_ENV=boot returns an inert handle without opening DB/Redis", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    let handle: Awaited<ReturnType<typeof runWorkerApp>>;
+    try {
+      handle = await runWorkerApp({
+        features: [probeFeature],
+        migrations: false,
+        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
+      });
+    } finally {
+      console.log = originalLog;
+    }
+
+    expect(handle).toBeDefined();
+    expect(typeof handle.stop).toBe("function");
+    expect(logs.some((line) => line.includes("boot validation OK"))).toBe(true);
+    await handle.stop();
+  });
+
+  test("ensureTemporalPolyfill runs even in boot-mode — Temporal is defined right after boot validation", async () => {
+    // Regression pin for fw#1725: the bug that cost real time was a
+    // missing polyfill call. Boot-mode boots without running any job —
+    // this test only proves "the polyfill call happens"; the ordering-
+    // before-composeFeatures guarantee is covered by the integration
+    // test (run-worker-app.integration.test.ts) via a real job.
+    const originalLog = console.log;
+    console.log = () => {};
+    try {
+      const handle = await runWorkerApp({
+        features: [probeFeature],
+        migrations: false,
+        envSource: { ...DUMMY_ENV, KUMIKO_DRY_RUN_ENV: "boot" },
+      });
+      await handle.stop();
+    } finally {
+      console.log = originalLog;
+    }
+    expect(typeof (globalThis as { Temporal?: unknown }).Temporal).toBe("object");
+  });
+
+  test("unhealthy KMS aborts boot before any DB/Redis connection is opened", async () => {
+    let healthChecked = false;
+    const unhealthyKms: KmsAdapter = {
+      capabilities: { mode: "local-key" },
+      createKey: async () => {},
+      getKey: async () => {
+        throw new Error("unreachable");
+      },
+      eraseKey: async () => {},
+      health: async () => {
+        healthChecked = true;
+        return { ok: false, latencyMs: 3 };
+      },
+    };
+    const originalLog = console.log;
+    console.log = () => {};
+    try {
+      await expect(
+        runWorkerApp({
+          features: [probeFeature],
+          migrations: false,
+          kms: unhealthyKms,
+          envSource: { ...DUMMY_ENV },
+        }),
+      ).rejects.toThrow(/KMS health check failed/);
+    } finally {
+      console.log = originalLog;
+    }
+    expect(healthChecked).toBe(true);
+  });
+});

package/src/__tests__/run-worker-app.integration.test.ts

@@ -0,0 +1,214 @@
+// runWorkerApp integration: boots the dedicated worker process against
+// real Postgres + Redis. Proves:
+//   - ensureTemporalPolyfill ran BEFORE the job executed (fw#1725: the
+//     bug that cost real time — without the polyfill, every job in the
+//     worker fails with "Temporal is not defined")
+//   - event-triggered jobs run end-to-end (afterCommit → BullMQ → handler)
+//   - the schema-drift gate aborts the boot on pending migrations
+//   - wireComponents gets db/redis/registry/dispatchSystemWrite/lifecycle
+//     and can register its own shutdown hooks
+
+import { afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createDbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createArchivedStreamsTable,
+  createEventsTable,
+} from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createEventConsumerStateTable,
+  createProjectionStateTable,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+import { unsafeEnsureEntityTable } from "@cosmicdrift/kumiko-framework/stack";
+import postgres from "postgres";
+import { z } from "zod";
+import { makeDispatchSystemWrite } from "../extra-routes-deps";
+import { runWorkerApp, type WorkerAppHandle } from "../run-worker-app";
+
+const jobRuns: Array<{ note: string; temporalWasDefined: boolean }> = [];
+
+const workerProbeEntity = createEntity({
+  fields: { note: createTextField({ required: true }) },
+  table: "worker_probes",
+});
+
+const workerProbeFeature = defineFeature("worker-probe", (r) => {
+  r.entity("probe", workerProbeEntity);
+  r.writeHandler({
+    name: "ping",
+    schema: z.object({ note: z.string() }),
+    access: { roles: ["SystemAdmin"] },
+    handler: async (event) => ({
+      isSuccess: true as const,
+      data: { note: (event.payload as { note: string }).note },
+    }),
+  });
+  // The job's only purpose: prove Temporal is already defined by the time
+  // the handler runs. Before fw#1725 there was no framework-side boot
+  // path for this — apps had to rebuild the polyfill call by hand
+  // (solon#42) and forgot it.
+  r.job(
+    "record-ping",
+    { trigger: { on: "worker-probe:write:ping" }, runIn: "worker" },
+    async (payload) => {
+      const temporalWasDefined =
+        typeof (globalThis as { Temporal?: unknown }).Temporal === "object";
+      // Touches the global directly — throws "Temporal is not defined" if the
+      // polyfill never ran, which is the exact failure mode fw#1725 reports.
+      Temporal.Now.instant();
+      jobRuns.push({
+        note: (payload as { note: string }).note,
+        temporalWasDefined,
+      });
+    },
+  );
+});
+
+const TENANT_ID = "00000000-0000-4000-8000-000000000002";
+const TEST_DB = `kumiko_runworker_${Date.now().toString(36)}`;
+const ADMIN_URL = process.env["TEST_DATABASE_URL"] ?? "";
+
+const tempDirs: string[] = [];
+let handles: WorkerAppHandle[] = [];
+
+beforeAll(async () => {
+  if (!ADMIN_URL) throw new Error("TEST_DATABASE_URL must be set");
+  const adminClient = postgres(ADMIN_URL.replace(/\/[^/]+$/, "/postgres"));
+  try {
+    await adminClient.unsafe(`CREATE DATABASE "${TEST_DB}"`);
+  } finally {
+    await adminClient.end();
+  }
+  const url = ADMIN_URL.replace(/\/[^/]+$/, `/${TEST_DB}`);
+  const { db, close } = createDbConnection(url);
+  try {
+    await createEventsTable(db);
+    await createArchivedStreamsTable(db);
+    await createProjectionStateTable(db);
+    await createEventConsumerStateTable(db);
+    await unsafeEnsureEntityTable(db, workerProbeEntity, "probe");
+  } finally {
+    await close();
+  }
+});
+
+afterEach(async () => {
+  for (const handle of handles) {
+    await handle.stop();
+  }
+  handles = [];
+  for (const dir of tempDirs) {
+    await rm(dir, { recursive: true, force: true });
+  }
+  tempDirs.length = 0;
+  jobRuns.length = 0;
+});
+
+async function boot(extra?: Partial<Parameters<typeof runWorkerApp>[0]>): Promise<WorkerAppHandle> {
+  const originalDbUrl = process.env["DATABASE_URL"];
+  process.env["DATABASE_URL"] = ADMIN_URL.replace(/\/[^/]+$/, `/${TEST_DB}`);
+  process.env["REDIS_URL"] = process.env["REDIS_URL"] ?? "redis://localhost:16379";
+  process.env["JWT_SECRET"] = "test-runworker-secret-32-chars-min!!";
+  try {
+    const handle = await runWorkerApp({
+      features: [workerProbeFeature],
+      migrations: false,
+      jobs: { queueNamePrefix: `test-worker-${Date.now().toString(36)}` },
+      ...(extra ?? {}),
+    });
+    handles.push(handle);
+    return handle;
+  } finally {
+    if (originalDbUrl !== undefined) process.env["DATABASE_URL"] = originalDbUrl;
+    else delete process.env["DATABASE_URL"];
+  }
+}
+
+async function pollFor<T>(probe: () => T | undefined, timeoutMs = 8000): Promise<T> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const result = probe();
+    if (result !== undefined) return result;
+    if (Date.now() > deadline) throw new Error("pollFor: timeout");
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+describe("runWorkerApp", () => {
+  test("boots against real Postgres/Redis — mode is worker, dispatcher available", async () => {
+    const handle = await boot();
+    expect(handle.entrypoint.mode).toBe("worker");
+    expect(handle.entrypoint.dispatcher).toBeDefined();
+  });
+
+  test("event-triggered job runs end-to-end with Temporal already defined (fw#1725 regression)", async () => {
+    const handle = await boot();
+    const dispatchSystemWrite = makeDispatchSystemWrite(handle.entrypoint.dispatcher);
+
+    const result = await dispatchSystemWrite({
+      handlerQn: "worker-probe:write:ping",
+      payload: { note: "hello-from-worker" },
+      tenantId: TENANT_ID as import("@cosmicdrift/kumiko-framework/engine").TenantId,
+    });
+    expect(result.isSuccess).toBe(true);
+
+    const run = await pollFor(() => jobRuns.find((r) => r.note === "hello-from-worker"));
+    expect(run.temporalWasDefined).toBe(true);
+  });
+
+  test("wireComponents receives db/redis/registry/dispatchSystemWrite/lifecycle and can register a shutdown hook", async () => {
+    let seenDeps: {
+      db: boolean;
+      redis: boolean;
+      registry: boolean;
+      dispatchSystemWrite: boolean;
+    } | null = null;
+    let shutdownHookRan = false;
+
+    const handle = await boot({
+      wireComponents: async (deps) => {
+        seenDeps = {
+          db: deps.db !== undefined,
+          redis: deps.redis !== undefined,
+          registry: deps.registry.features.has("worker-probe"),
+          dispatchSystemWrite: typeof deps.dispatchSystemWrite === "function",
+        };
+        deps.lifecycle.registerShutdownHook("test-component", async () => {
+          shutdownHookRan = true;
+        });
+      },
+    });
+
+    expect(seenDeps!).toEqual({
+      db: true,
+      redis: true,
+      registry: true,
+      dispatchSystemWrite: true,
+    });
+
+    await handle.stop();
+    handles = handles.filter((h) => h !== handle);
+    expect(shutdownHookRan).toBe(true);
+  });
+
+  test("Schema-Drift-Gate: pending migration aborts the boot before anything else initializes", async () => {
+    const driftDir = await mkdtemp(join(tmpdir(), "kumiko-worker-drift-boot-"));
+    tempDirs.push(driftDir);
+    await writeFile(
+      join(driftDir, "0001_pending.sql"),
+      `CREATE TABLE "worker_never_created_table" ("id" uuid PRIMARY KEY);`,
+    );
+    await writeFile(
+      join(driftDir, ".snapshot.json"),
+      JSON.stringify({
+        version: 1,
+        tables: [{ tableName: "worker_never_created_table", columns: [] }],
+      }),
+    );
+
+    await expect(boot({ migrations: { dir: driftDir } })).rejects.toThrow(/Schema drift detected/);
+  });
+});

package/src/index.ts

@@ -15,4 +15,10 @@ export type {
   SignupSetup,
 } from "./run-prod-app";
 export { runProdApp } from "./run-prod-app";
+export type {
+  RunWorkerAppOptions,
+  WorkerAppHandle,
+  WorkerWireDeps,
+} from "./run-worker-app";
+export { runWorkerApp } from "./run-worker-app";
 export type { SecurityHeadersOption } from "./security-headers";

package/src/run-worker-app.ts

@@ -0,0 +1,336 @@
+// runWorkerApp — production-grade bootstrap wrapper for a dedicated
+// Kumiko worker process. Symmetric to runProdApp, but without HTTP: no
+// Hono app, no auth routes, no SSE broker, no seeds. Shares the boot core
+// with runProdApp (env fail-fast, Temporal polyfill, composeFeatures/
+// registry, PII invariants, KMS health gate, connections, schema-drift
+// gate, boot-crypto, extraContext) — see fw#1725: before this function,
+// every app deploying a worker rebuilt this boot by hand (solon#42), and
+// every deviation was silent: without `ensureTemporalPolyfill`, every job
+// in the worker fails with "Temporal is not defined" in a retry loop,
+// with no boot-time signal that anything is wrong.
+//
+// App-author writes:
+//   await runWorkerApp({ features, wireComponents: async (deps) => {...} });
+//
+// Container/Coolify sets the same env vars as runProdApp:
+//   DATABASE_URL, REDIS_URL, JWT_SECRET — PORT is not needed.
+
+import { loadJwtSecretOrKeyring, type ServerOptions } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configureBlindIndexKey,
+  configurePiiSubjectKms,
+  type KmsAdapter,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  configureEntityFieldEncryption,
+  createDbConnection,
+  type DbConnection,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createRegistry,
+  type EffectiveFeaturesResolver,
+  type FeatureDefinition,
+  findTierResolverUsage,
+  type Registry,
+  type TierResolverPlugin,
+  validateBoot,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createWorkerEntrypoint,
+  type WorkerEntrypoint,
+} from "@cosmicdrift/kumiko-framework/entrypoint";
+import {
+  assertKumikoSchemaCurrent,
+  SchemaDriftError,
+} from "@cosmicdrift/kumiko-framework/migrations";
+import type {
+  ObservabilityOptions,
+  ObservabilityProvider,
+} from "@cosmicdrift/kumiko-framework/observability";
+import {
+  createEntityCache,
+  createEventDedup,
+  createIdempotencyGuard,
+} from "@cosmicdrift/kumiko-framework/pipeline";
+import type { MasterKeyProvider } from "@cosmicdrift/kumiko-framework/secrets";
+import { warnIfNonUtcServerTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import Redis from "ioredis";
+import { resolveBootCrypto } from "./boot/boot-crypto";
+import { jobRunLoggerCallbacks } from "./boot/job-run-logger";
+import { composeFeatures } from "./compose-features";
+import { type ExtraRoutesSystemDeps, makeDispatchSystemWrite } from "./extra-routes-deps";
+import { assertPiiBootInvariants } from "./pii-boot-gate";
+import { requireEnv } from "./run-prod-app";
+import { addConfigAccessorFactory, buildBootExtraContext } from "./run-prod-app-boot-context";
+
+export type WorkerContextOption =
+  | Record<string, unknown>
+  | ((deps: WorkerDeps) => Record<string, unknown>);
+
+export type WorkerDeps = {
+  readonly db: DbConnection;
+  readonly redis: Redis;
+  readonly registry: Registry;
+};
+
+/** Deps for the `wireComponents` hook — app-wired co-running components
+ *  (an analysis runner, an IMAP supervisor, ...) that need the system-
+ *  write dispatcher and register their own shutdown hooks on the worker
+ *  lifecycle. Same deps shape as extraRoutes, plus `lifecycle` for
+ *  `registerShutdownHook`. */
+export type WorkerWireDeps = ExtraRoutesSystemDeps & {
+  readonly lifecycle: WorkerEntrypoint["lifecycle"];
+};
+
+export type RunWorkerAppOptions = {
+  /** App-specific features — same array as in the API/all-in-one process,
+   *  so the registry + schema stay identical across processes. */
+  readonly features: readonly FeatureDefinition[];
+  /** Mount the auto-mixed config/user/tenant/auth-email-password features —
+   *  MUST match the API process's `includeBundled` value, otherwise API
+   *  and worker run with a diverging registry topology. Also controls
+   *  whether buildBootExtraContext auto-wires `configResolver` (same
+   *  auth-mode gate as runProdApp). */
+  readonly includeBundled?: boolean;
+  /** Path to kumiko/migrations for the boot gate. See RunProdAppOptions
+   *  ["migrations"] — identical semantics. */
+  readonly migrations?: { readonly dir: string } | false;
+  /** Extra AppContext keys — same factory-union pattern as
+   *  RunProdAppOptions["extraContext"], without sseBroker (the worker
+   *  has none — see entrypoint/index.ts's documented SSE limitation). */
+  readonly extraContext?: WorkerContextOption;
+  /** MasterKeyProvider for ctx.secrets. Default: env-KEK (see
+   *  RunProdAppOptions["masterKey"]). */
+  readonly masterKey?: MasterKeyProvider;
+  /** Subject-key adapter for crypto-shredding — boot checks health()
+   *  before any connection (see RunProdAppOptions["kms"]). */
+  readonly kms?: KmsAdapter;
+  /** Blind-index key for lookupable fields (see
+   *  RunProdAppOptions["blindIndexKey"]). */
+  readonly blindIndexKey?: string;
+  /** Explicit opt-out from the PII boot gate (see
+   *  RunProdAppOptions["allowPlaintextPii"]). */
+  readonly allowPlaintextPii?: string;
+  readonly jobs?: {
+    readonly queueNamePrefix?: string;
+  };
+  /** Tuning knobs for the event-dispatcher loop (pollIntervalMs, pgClient
+   *  for LISTEN/NOTIFY). */
+  readonly eventDispatcher?: ServerOptions["eventDispatcher"];
+  /** Hook for app-wired co-running components that need the system-write
+   *  dispatcher (e.g. an analysis runner, an IMAP supervisor). Runs AFTER
+   *  `entrypoint.start()` — the hook itself is responsible for starting
+   *  its component and registering a shutdown hook on `lifecycle`. */
+  readonly wireComponents?: (deps: WorkerWireDeps) => Promise<void> | void;
+  /** Feature-toggle resolver (see RunProdAppOptions["effectiveFeatures"]). */
+  readonly effectiveFeatures?: EffectiveFeaturesResolver;
+  /** Override `process.env` for env-validation (see
+   *  RunProdAppOptions["envSource"]). */
+  readonly envSource?: Record<string, string | undefined>;
+  readonly observability?: ObservabilityProvider;
+  readonly observabilityOptions?: ObservabilityOptions;
+};
+
+export type WorkerAppHandle = {
+  /** In KUMIKO_DRY_RUN_ENV=boot mode with an injected envSource (test
+   *  path), no boot ran — this slot is an undefined-cast, do not access. */
+  readonly entrypoint: WorkerEntrypoint;
+  readonly stop: () => Promise<void>;
+};
+
+function makeBootModeHandle(): WorkerAppHandle {
+  return {
+    // @cast-boundary boot-mode: no entrypoint exists because no boot ran —
+    // callers on this path never read this slot.
+    entrypoint: undefined as unknown as WorkerEntrypoint,
+    stop: async () => {},
+  };
+}
+
+export async function runWorkerApp(options: RunWorkerAppOptions): Promise<WorkerAppHandle> {
+  const envSource = options.envSource ?? process.env;
+
+  // 1. Polyfill before anything else — exactly the bug fw#1725 reports:
+  //    without it, every job in the worker fails with "Temporal is not
+  //    defined" in a retry loop, with no boot-time signal.
+  const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
+  await ensureTemporalPolyfill();
+
+  // 2. Env vars: fail-fast, same requireEnv as runProdApp. JWT_SECRET is
+  //    validated by loadJwtSecretOrKeyring itself (throws when neither
+  //    JWT_SECRET nor JWT_SECRET_V<n> is set).
+  const databaseUrl = requireEnv("DATABASE_URL", envSource, "runWorkerApp");
+  const redisUrl = requireEnv("REDIS_URL", envSource, "runWorkerApp");
+  const jwtSecretOrKeyring = loadJwtSecretOrKeyring(envSource);
+
+  // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+  console.log("[runWorkerApp] booting Kumiko worker…");
+
+  // 3. Feature registry — identical to runProdApp, MUST be built with the
+  //    same `includeBundled` as the API process.
+  const features = composeFeatures(options.features, {
+    includeBundled: !!options.includeBundled,
+  });
+  validateBoot(features);
+  warnIfNonUtcServerTimeZone();
+  assertPiiBootInvariants(features, {
+    kms: options.kms,
+    blindIndexKey: options.blindIndexKey,
+    allowPlaintextPii: options.allowPlaintextPii,
+    mode: "prod",
+  });
+  const registry = createRegistry(features);
+
+  // Boot-mode exit (parity with runProdApp's C1): validators ran and the
+  // registry is built, no DB/Redis client was constructed. Makes the boot
+  // testable without real Postgres/Redis infra.
+  if (envSource["KUMIKO_DRY_RUN_ENV"] === "boot") {
+    // biome-ignore lint/suspicious/noConsole: boot-mode output IS the deliverable
+    console.log(
+      `[runWorkerApp] boot validation OK (${features.length} features, ${registry.features.size} registry entries)`,
+    );
+    if (options.envSource === undefined) {
+      process.exit(0);
+    }
+    return makeBootModeHandle();
+  }
+
+  // 4. KMS health gate — runs BEFORE the connections, so an abort leaks
+  //    nothing (identical to runProdApp).
+  if (options.kms) {
+    const kmsHealth = await options.kms.health();
+    if (!kmsHealth.ok) {
+      throw new Error(
+        `[runWorkerApp] BOOT ABORTED — KMS health check failed (latency ${kmsHealth.latencyMs}ms)`,
+      );
+    }
+  }
+
+  const { db, close: closeDb } = createDbConnection(databaseUrl);
+  const redis = new Redis(redisUrl, { maxRetriesPerRequest: null });
+
+  let resolvedEffectiveFeatures: EffectiveFeaturesResolver | undefined = options.effectiveFeatures;
+  if (resolvedEffectiveFeatures === undefined) {
+    const tierResolverUsage = findTierResolverUsage(features);
+    if (tierResolverUsage) {
+      const plugin = tierResolverUsage.options as TierResolverPlugin;
+      resolvedEffectiveFeatures = await plugin.build({ db, registry });
+    }
+  }
+
+  // 5. Schema-drift gate — identical to runProdApp.
+  if (options.migrations !== false) {
+    const migrationsDir = options.migrations?.dir ?? "./kumiko/migrations";
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint
+    console.log(`[runWorkerApp] checking schema drift (${migrationsDir})…`);
+    try {
+      await assertKumikoSchemaCurrent(db, migrationsDir);
+    } catch (err) {
+      if (err instanceof SchemaDriftError) {
+        // biome-ignore lint/suspicious/noConsole: terminal error message
+        console.error(`\n[runWorkerApp] BOOT ABORTED — ${err.message}\n`);
+      }
+      throw err;
+    }
+  }
+
+  // 6. Pipeline pieces — same defaults as runProdApp.
+  const idempotency = createIdempotencyGuard(redis, { ttlSeconds: 60 });
+  const eventDedup = createEventDedup(redis, { ttlSeconds: 60 });
+  const entityCache = createEntityCache(redis, { ttlSeconds: 60 });
+
+  // 7. Boot-crypto + extraContext — the core of fw#1725: KMS wiring,
+  //    blind-index, config-encryption must be wired in the worker exactly
+  //    like in the API, otherwise the worker writes rows the API can no
+  //    longer read (different cipher, missing blind index).
+  const deps: WorkerDeps = { db, redis, registry };
+  const resolvedExtraContext =
+    typeof options.extraContext === "function"
+      ? options.extraContext(deps)
+      : (options.extraContext ?? {});
+
+  const bootCrypto = resolveBootCrypto(envSource, options.masterKey);
+  configureEntityFieldEncryption(bootCrypto.entityFieldCipher);
+  configurePiiSubjectKms(options.kms);
+  configureBlindIndexKey(options.blindIndexKey);
+  const autoExtraContext = buildBootExtraContext({
+    db,
+    features,
+    envSource,
+    registry,
+    hasAuth: !!options.includeBundled,
+    crypto: bootCrypto,
+    ...(options.kms && { kms: options.kms }),
+  });
+  const extraContext = addConfigAccessorFactory(
+    { ...autoExtraContext, ...resolvedExtraContext },
+    registry,
+  );
+
+  const jobLogger = jobRunLoggerCallbacks(registry, db);
+  const entrypoint = createWorkerEntrypoint({
+    registry,
+    context: { db, redis, entityCache, registry, ...extraContext },
+    jwtSecret: jwtSecretOrKeyring,
+    dispatcherOptions: {
+      idempotency,
+      ...(resolvedEffectiveFeatures && { effectiveFeatures: resolvedEffectiveFeatures }),
+    },
+    eventDedup,
+    ...(options.observability && { observability: options.observability }),
+    ...(options.observabilityOptions && { observabilityOptions: options.observabilityOptions }),
+    redisUrl,
+    ...jobLogger,
+    ...(options.jobs?.queueNamePrefix !== undefined && {
+      queueNamePrefix: options.jobs.queueNamePrefix,
+    }),
+    ...(options.eventDispatcher && { eventDispatcher: options.eventDispatcher }),
+  });
+
+  const handle: WorkerAppHandle = {
+    entrypoint,
+    stop: async () => {
+      await entrypoint.stop();
+      await closeDb();
+      redis.disconnect();
+    },
+  };
+
+  await entrypoint.start();
+
+  if (options.wireComponents) {
+    await options.wireComponents({
+      db,
+      redis,
+      registry,
+      dispatchSystemWrite: makeDispatchSystemWrite(entrypoint.dispatcher),
+      lifecycle: entrypoint.lifecycle,
+    });
+  }
+
+  let shuttingDown = false;
+  const shutdown = async (signal: string) => {
+    // skip: shutdown already in progress, avoid double-drain
+    if (shuttingDown) return;
+    shuttingDown = true;
+    // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+    console.log(`[runWorkerApp] ${signal} received — draining…`);
+    try {
+      await handle.stop();
+      // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+      console.log("[runWorkerApp] graceful shutdown complete.");
+    } catch (e) {
+      // biome-ignore lint/suspicious/noConsole: shutdown-time error, only path is stderr
+      console.error("[runWorkerApp] error during shutdown:", e);
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+
+  // biome-ignore lint/suspicious/noConsole: boot-time progress hint, no logger configured this early
+  console.log("[runWorkerApp] ready — worker running.");
+
+  return handle;
+}