@cosmicdrift/kumiko-framework 0.182.0 → 0.183.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.182.0",
+  "version": "0.183.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.182.0",
+    "@cosmicdrift/kumiko-types": "0.183.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.182.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.183.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/server.ts

@@ -236,8 +236,34 @@ export type KumikoServer = {
   // Echoed back so the caller has a single handle for both the app and the
   // lifecycle. Only set when the caller passed one in.
   lifecycle?: Lifecycle;
+  // The AppContext every handler on this server sees — options.context plus
+  // what buildServer wires onto it (_fileProviderResolver, rateLimit, the
+  // observability tracer/meter). Callers that build a second consumer of the
+  // same registry outside this server (a dev-server's job-runners) must pass
+  // THIS, not their own pre-buildServer literal, or that consumer reaches for
+  // fields only the request path has (#1232).
+  context: AppContext;
 };
 
+// The per-tenant file-provider resolver, built once for a registry+context so
+// a job-runner and the server it runs beside share one instance (and one
+// per-tenant provider cache). Mirrors buildServer's own resolution exactly —
+// including NOT inventing a resolver when no `file-provider-*` plugin is
+// mounted, which is what keeps buildServer's boot-guard below able to fire.
+export function withFileProviderResolver(registry: Registry, context: AppContext): AppContext {
+  if (context._fileProviderResolver !== undefined) return context;
+  if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0) return context;
+  return {
+    ...context,
+    _fileProviderResolver: makeFileProviderResolver({
+      registry,
+      _configAccessorFactory: context._configAccessorFactory,
+      secrets: context.secrets,
+      db: context.db,
+    }),
+  };
+}
+
 export function buildServer(options: ServerOptions): KumikoServer {
   // File-storage is resolved per-tenant through file-foundation: a mounted
   // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
@@ -336,16 +362,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
   // resolver once (when a provider plugin is mounted) — the dispatcher uses it
   // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
   // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
-  const fileProviderResolver =
-    options.context._fileProviderResolver ??
-    (hasFileProvider
-      ? makeFileProviderResolver({
-          registry: options.registry,
-          _configAccessorFactory: options.context._configAccessorFactory,
-          secrets: options.context.secrets,
-          db: options.context.db,
-        })
-      : undefined);
+  const contextWithFiles = withFileProviderResolver(options.registry, options.context);
+  const fileProviderResolver = contextWithFiles._fileProviderResolver;
   // Auto-wire the rate-limit resolver, but ONLY when at least one
   // handler actually declared a rateLimit option. Apps that don't use
   // L3 pay zero cost: no resolver instance, no Lua-script registration
@@ -363,9 +381,8 @@ export function buildServer(options: ServerOptions): KumikoServer {
     options.context.rateLimit ??
     (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
   const contextWithObservability: AppContext = {
-    ...options.context,
+    ...contextWithFiles,
     ...(wrappedRedis ? { redis: wrappedRedis } : {}),
-    ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
     ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
     // Propagate the feature-toggle resolver to the context so the event-
     // dispatcher (and any future context-reading consumer) sees the same
@@ -783,6 +800,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
     sseBroker,
     observability,
     dispatcher,
+    context: contextWithObservability,
     ...(eventDispatcher ? { eventDispatcher } : {}),
     ...(options.lifecycle ? { lifecycle: options.lifecycle } : {}),
   };

package/src/engine/__tests__/content-collection.test.ts

@@ -155,14 +155,14 @@ describe("r.contentCollection() — registration", () => {
         id: "prompts",
         kind: "ai-prompt",
         contentFormat: "plain",
-        variableSchema: { customerName: {}, orderId: {} },
+        variableSchema: { customerName: "Max Mustermann", orderId: "A-1042" },
         nav: { label: "mail:nav.prompts" },
       });
     });
 
     expect(feature.contentCollections?.["prompts"]?.variableSchema).toEqual({
-      customerName: {},
-      orderId: {},
+      customerName: "Max Mustermann",
+      orderId: "A-1042",
     });
   });
 
@@ -267,7 +267,7 @@ describe("buildAppSchema — content collections", () => {
           id: "prompts",
           kind: "ai-prompt",
           contentFormat: "plain",
-          variableSchema: { customerName: {} },
+          variableSchema: { customerName: "Max Mustermann" },
           nav: { label: "mail:nav.prompts" },
         });
       }),
@@ -275,7 +275,9 @@ describe("buildAppSchema — content collections", () => {
 
     const schema = buildAppSchema(registry);
     const mail = schema.features.find((f) => f.featureName === "mail");
-    expect(mail?.contentCollections?.[0]?.variableSchema).toEqual({ customerName: {} });
+    expect(mail?.contentCollections?.[0]?.variableSchema).toEqual({
+      customerName: "Max Mustermann",
+    });
     // buildAppSchema's JSON-safety check throws on undefined leaves — proves
     // the new field survives that check instead of only the toEqual above.
     expect(() =>
@@ -284,7 +286,7 @@ describe("buildAppSchema — content collections", () => {
           r.contentCollection({
             id: "prompts",
             kind: "ai-prompt",
-            variableSchema: { customerName: {} },
+            variableSchema: { customerName: "Max Mustermann" },
             nav: { label: "mail2:nav.prompts" },
           });
         }),

package/src/entrypoint/__tests__/split-deploy.integration.test.ts

@@ -63,6 +63,34 @@ const workerWriteFeature = defineFeature("workerWrite", (r) => {
   });
 });
 
+// The job-runner is built BEFORE the server, so it used to capture the raw
+// caller context — without the per-tenant file-provider resolver buildServer
+// wires onto it. An event-triggered job reaching for ctx.files then died in
+// the worker while the identical code worked on the request path.
+const jobSawFileResolver: string[] = [];
+
+const fileJobFeature = defineFeature("fileJob", (r) => {
+  const requested = r.defineEvent("bytes-requested", z.object({ storageKey: z.string() }), {
+    version: 1,
+  });
+  // Stands in for file-foundation, which this package cannot import.
+  r.extendsRegistrar("fileProvider", { onRegister: () => undefined });
+  r.useExtension("fileProvider", "spy", {
+    build: async () => {
+      throw new Error("no provider is built in this test — presence of the resolver is the point");
+    },
+  });
+  r.job(
+    "read-bytes",
+    { trigger: { on: requested.name }, runIn: "worker" },
+    async (_payload, ctx) => {
+      jobSawFileResolver.push(typeof ctx._fileProviderResolver);
+    },
+  );
+  // Worker mode refuses to boot without a consumer to drain.
+  r.multiStreamProjection({ name: "noop", apply: { [requested.name]: async () => {} } });
+});
+
 async function waitForCondition(check: () => boolean, timeoutMs = 5000): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (!check()) {
@@ -137,6 +165,32 @@ describe("entrypoint factories", () => {
     await worker.stop();
   });
 
+  test("Worker job-context carries the file-provider resolver, not just the request path", async () => {
+    const registry = createRegistry([fileJobFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const worker = createWorkerEntrypoint({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      jwtSecret: JWT,
+      redisUrl,
+      queueNamePrefix: uniquePrefix("split-filejob"),
+    });
+
+    jobSawFileResolver.length = 0;
+    await worker.start();
+    try {
+      await worker.jobRunner.handleEvent(
+        "file-job:event:bytes-requested",
+        { storageKey: "some/key.pdf" },
+        TestUsers.admin,
+      );
+      await waitForCondition(() => jobSawFileResolver.length > 0);
+      expect(jobSawFileResolver[0]).toBe("function");
+    } finally {
+      await worker.stop();
+    }
+  });
+
   // An app-wired component running in the worker (analysis service, IMAP
   // supervisor) has to persist its result, and persisting goes through the
   // write-path — JobContext has no write/query. The dispatcher is the only

package/src/entrypoint/index.ts

@@ -34,7 +34,7 @@ import type { Hono } from "hono";
 import type { AuthRoutesConfig } from "../api/auth-routes";
 import type { JwtHelper, JwtKeyring } from "../api/jwt";
 import type { KumikoServer, ServerOptions } from "../api/server";
-import { buildServer } from "../api/server";
+import { buildServer, withFileProviderResolver } from "../api/server";
 import type { SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
@@ -322,6 +322,7 @@ function requireDispatcher(server: KumikoServer, mode: string): EventDispatcher
 export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
   const observability = resolveObservability(options.observability);
+  const context = withFileProviderResolver(options.registry, options.context);
 
   // Boot-validation (Welle 2.6.c) — fail loud before traffic arrives:
   //   (a) Any jobs declared + no jobs-block → command-dispatcher would
@@ -356,7 +357,7 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
     ? buildJobRunnerWithHook(
         options.registry,
         contextWithObservability(
-          options.context,
+          context,
           observability,
           options.dispatcherOptions?.effectiveFeatures,
         ),
@@ -374,7 +375,7 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
   // apply anywhere.
   const { runLocal: runLocalDispatcher, ...dispatcherTunables } = options.eventDispatcher ?? {};
   const server = buildApiServer(
-    options,
+    { ...options, context },
     lifecycle,
     runLocalDispatcher ? dispatcherTunables : { disabled: true },
     apiJobRunner,
@@ -411,19 +412,16 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
 export function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
   const observability = resolveObservability(options.observability);
+  const context = withFileProviderResolver(options.registry, options.context);
   const jobRunner = buildJobRunnerWithHook(
     options.registry,
-    contextWithObservability(
-      options.context,
-      observability,
-      options.dispatcherOptions?.effectiveFeatures,
-    ),
+    contextWithObservability(context, observability, options.dispatcherOptions?.effectiveFeatures),
     options,
     "worker",
     lifecycle,
     "jobRunner",
   );
-  const server = buildWorkerServer(options, lifecycle, jobRunner);
+  const server = buildWorkerServer({ ...options, context }, lifecycle, jobRunner);
   const eventDispatcher = requireDispatcher(server, "worker");
 
   return {
@@ -448,8 +446,9 @@ export function createWorkerEntrypoint(options: WorkerEntrypointOptions): Worker
 export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint {
   const lifecycle = options.lifecycle ?? createLifecycle({ startReady: true });
   const observability = resolveObservability(options.observability);
+  const context = withFileProviderResolver(options.registry, options.context);
   const jobRunnerContext = contextWithObservability(
-    options.context,
+    context,
     observability,
     options.dispatcherOptions?.effectiveFeatures,
   );
@@ -486,7 +485,7 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   // the API-mode flag — all-in-one is always local, strip it.
   const { runLocal: _runLocal, ...allInOneDispatcherTunables } = options.eventDispatcher ?? {};
   const server = buildApiServer(
-    options,
+    { ...options, context },
     lifecycle,
     allInOneDispatcherTunables,
     workerJobRunner,

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -582,6 +582,9 @@ describe("concurrency: replace", () => {
         const queue = new Queue(`${queueNamePrefix}-worker`, {
           connection: { host: testRedis.redis.options.host, port: testRedis.redis.options.port },
         });
+        // A post-close 'error' here is otherwise unhandled and bun:test
+        // attributes it to whichever test runs next (fw#1805).
+        queue.on("error", () => {});
         try {
           const waiting = (await queue.getWaiting()).filter(
             (job) => job.name === "test:job:replace-job",

package/src/jobs/job-runner.ts

@@ -13,6 +13,7 @@ import {
   type TenantId,
 } from "../engine/types";
 import { createFileContext } from "../files/file-handle";
+import { createFallbackLogger } from "../logging";
 import type { Logger } from "../logging/types";
 import {
   emitJobQueueDepth,
@@ -197,6 +198,7 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   // Use the context's tracer when present (observability-provider injected at
   // boot); otherwise noop so dispatch/handleJob stay zero-cost without config.
   const tracer: Tracer = context.tracer ?? getFallbackTracer();
+  const errorLogger = createFallbackLogger("job-runner", context.log);
 
   const allJobs = registry.getAllJobs();
 
@@ -218,6 +220,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
   let sequentialLock: DistributedLock | null = null;
   if (hasSequential) {
     lockRedis = new Redis(redisOpts);
+    // Without a listener, a post-close 'error' (e.g. a teardown-race
+    // "Connection is closed") is unhandled and crashes the process — in
+    // bun:test it gets attributed to whichever test happens to run next
+    // (fw#1805).
+    lockRedis.on("error", (err) =>
+      errorLogger.error("lock redis connection error", { error: err.message }),
+    );
     const lockScope = consumerLane ?? "enqueue";
     sequentialLock = createDistributedLock(lockRedis, `${RedisKeys.lock}seq:${lockScope}:`);
   }
@@ -239,6 +248,13 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
     api: new Queue(queueNameFor(queueNamePrefix, "api"), { connection: redisOpts }),
     worker: new Queue(queueNameFor(queueNamePrefix, "worker"), { connection: redisOpts }),
   };
+  // Same unhandled-'error'-crash hazard as lockRedis above, just via
+  // BullMQ's internal ioredis client (fw#1805).
+  for (const queue of Object.values(queues)) {
+    queue.on("error", (err) =>
+      errorLogger.error("queue redis connection error", { error: err.message }),
+    );
+  }
   let worker: Worker | null = null;
   let queueDepthTimer: ReturnType<typeof setInterval> | null = null;
   // Forward reference to the runner's own API, exposed on the job-handler ctx
@@ -488,6 +504,17 @@ export function createJobRunner(options: JobRunnerOptions): JobRunner {
         connection: redisOpts,
         concurrency: 5,
       });
+      worker.on("error", (err) =>
+        errorLogger.error("worker redis connection error", { error: err.message }),
+      );
+      // A caller that calls stop() right after start() otherwise races the
+      // still-settling blocking connection: it rejects in-flight commands
+      // via ioredis's flushQueue() during close(), which isn't a listenable
+      // 'error' event — the only fix is to not return until both of the
+      // worker's connections (main + blocking) are ready (fw#1805). This
+      // mirrors the wait BullMQ already does internally for
+      // upsertJobScheduler()/add() below when the lane has a cron/boot job.
+      await worker.waitUntilReady();
 
       // Only schedule cron + boot for jobs that belong to this lane. Jobs
       // assigned to the other lane get their cron/boot wiring from the

package/src/stack/test-stack.ts

@@ -6,7 +6,7 @@ import { createSseBroker, type SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
 import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
-import type { FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
+import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
 import { createJobRunner, type JobRunner } from "../jobs";
 import type { Lifecycle } from "../lifecycle";
@@ -39,6 +39,12 @@ export type TestStack = {
   // Command-dispatcher behind the HTTP routes — for direct system-writes
   // in tests and dev-server extraRoutes (provider-webhook wiring).
   dispatcher: Dispatcher;
+  // The AppContext buildServer handed the request path, incl. the fields it
+  // wires itself (_fileProviderResolver). A dev-server that starts its own
+  // lane job-runners beside this stack must hand them THIS, not a
+  // `{ db, registry }` literal — that's the #1232 drift, and it makes an
+  // event-triggered job reaching for ctx.files die where the request path works.
+  context: AppContext;
   // Present whenever a system consumer (SSE, Search) or
   // r.multiStreamProjection is wired. Tests drain it via runOnce() for
   // deterministic assertion — no timer-induced flakiness.
@@ -441,6 +447,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       observability: server.observability,
       sseBroker,
       dispatcher: server.dispatcher,
+      context: server.context,
       ...(eventDispatcher ? { eventDispatcher } : {}),
       ...(server.lifecycle ? { lifecycle: server.lifecycle } : {}),
       ...(jobRunner ? { jobRunner } : {}),