@cosmicdrift/kumiko-framework 0.181.0 → 0.182.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.181.0",
+  "version": "0.182.1",
   "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.181.0",
+    "@cosmicdrift/kumiko-types": "0.182.1",
     "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.181.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.182.1",
     "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/bun-db/query.ts

@@ -30,6 +30,7 @@ import type {
 import { Temporal } from "temporal-polyfill";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
+import { extractPgError } from "../db/pg-error";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
 import { parseJsonSafe } from "../utils/safe-json";
@@ -135,6 +136,38 @@ export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promis
   return raw.savepoint(fn);
 }
 
+// Same error-confinement as runInSavepoint, but for call sites that don't
+// know whether `db` is a bare pool connection or an active transaction
+// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
+// against the pool by seeds/tests). A pool connection has no savepoint() —
+// and doesn't need one, since each statement there is its own auto-committed
+// unit and a failed statement can't poison anything downstream.
+//
+// `.savepoint` being present isn't proof the transaction is still open: an
+// afterCommit hook closure captures the same handlerContext (and therefore
+// the same TransactionSql-shaped db) that was live during the write, but by
+// the time the hook fires the outer tx has already committed — the object
+// still exposes `.savepoint`, calling it now fails with PG 25P01 ("no
+// active sql transaction") because there's no BEGIN left to nest into. That
+// SAVEPOINT command is the first thing the driver sends, before `fn` runs,
+// so catching 25P01 and retrying directly is safe — nothing from `fn` has
+// executed yet.
+export async function runInSavepointIfSupported<T>(
+  db: unknown,
+  fn: (sp: unknown) => Promise<T>,
+): Promise<T> {
+  const raw = asRawClient(db) as unknown as {
+    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
+  };
+  if (typeof raw.savepoint !== "function") return fn(db);
+  try {
+    return await raw.savepoint(fn);
+  } catch (e) {
+    if (extractPgError(e)?.code === "25P01") return fn(db);
+    throw e;
+  }
+}
+
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -5,7 +5,7 @@
 // verb entirely, and restore()'s two precondition failures.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "../../db/query";
+import { asRawClient, transaction } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import { from } from "../../engine/ownership";
 import { createEventsTable } from "../../event-store";
@@ -419,6 +419,38 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
     expect(healthCheck[0]?.ok).toBe(1);
   });
 
+  // kumiko-framework#1778 — a real write handler runs create() inside the
+  // dispatcher's transaction (sql.begin()), not on the bare pool like the
+  // race test above. postgres.js/Bun.SQL poison the WHOLE begin() block
+  // once any statement inside it errors, even if the JS layer already
+  // caught and classified that error — so without the runInSavepoint fix
+  // in event-store-executor-write.ts, the LOSER's transaction() call itself
+  // rejects with the raw PostgresError instead of resolving to the
+  // version_conflict writeFailure create() already produced.
+  test("two concurrent first-time creates of the same id inside a transaction → one succeeds, one converges to version_conflict", async () => {
+    const id = "11111111-1111-4111-8111-111111111111";
+
+    const [a, b] = await Promise.all([
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "a@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "b@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+    ]);
+
+    const results = [a, b];
+    expect(results.filter((r) => r.isSuccess)).toHaveLength(1);
+    expect(results.filter((r) => !r.isSuccess && r.error.code === "version_conflict")).toHaveLength(
+      1,
+    );
+
+    const healthCheck = (await asRawClient(testDb.db).unsafe(`SELECT 1 AS ok`)) as Array<{
+      ok: number;
+    }>;
+    expect(healthCheck[0]?.ok).toBe(1);
+  });
+
   test("forget with entityCache clears the cache entry", async () => {
     const created = await crud.create({ email: "cache-forget@test.de" }, admin, tdb);
     if (!created.isSuccess) throw new Error("setup failed");

package/src/db/event-store-executor-write.ts

@@ -18,7 +18,7 @@ import {
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
-import type { DbRow } from "./connection";
+import type { DbRow, DbRunner } from "./connection";
 import type { EventStoreExecutor } from "./event-store-executor";
 import {
   buildEventMetadata,
@@ -26,7 +26,7 @@ import {
   entityEventName,
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
-import { selectMany } from "./query";
+import { runInSavepointIfSupported, selectMany } from "./query";
 
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
@@ -190,30 +190,34 @@ export function createWriteVerbs(
       //    selben catch (siehe line 493+).
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await append(db.raw, {
-          aggregateId,
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: 0,
-          type: entityEventName(entityName, "created"),
-          payload: flatData,
-          metadata: buildEventMetadata(user),
-        });
+        // Savepoint-scoped: postgres.js/Bun.SQL poison the WHOLE surrounding
+        // begin() once any statement inside it errors, even if the JS error
+        // is caught (kumiko-framework#1778) — a losing concurrent create's
+        // unique-violation would otherwise abort the caller's outer
+        // transaction and surface as internal_error at commit time instead
+        // of the version_conflict this catch classifies. runInSavepointIfSupported
+        // confines the failed INSERT to a nested scope that rolls back on
+        // its own (same pattern as ctx.tryAppendEvent), and falls back to a
+        // plain call when db.raw is a bare pool connection with no active
+        // transaction to poison (seeds/tests calling the executor directly).
+        event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId,
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: 0,
+            type: entityEventName(entityName, "created"),
+            payload: flatData,
+            metadata: buildEventMetadata(user),
+          }),
+        );
       } catch (e) {
         if (e instanceof EventStoreVersionConflict) {
-          // Try to look up the real stream-version for the diagnostic — but
-          // wrap defensively: when `append` raised the unique-violation, the
-          // current TX is already aborted, and a second query on the same
-          // runner would re-throw "current transaction is aborted". Update-
-          // path doesn't have this problem (it queries getStreamVersion
-          // BEFORE the try-block). Falling back to a sentinel keeps the
-          // version_conflict mapping reliable; the actual current version
-          // is recoverable client-side via a fresh detail-query if needed.
           let currentVersion = -1;
           try {
             currentVersion = await getStreamVersion(db.raw, aggregateId, streamTenantFor(user));
           } catch {
-            // Aborted TX or any lookup failure — keep the sentinel.
+            // Lookup failure — keep the sentinel.
           }
           return writeFailure(
             new FrameworkVersionConflict({
@@ -412,18 +416,24 @@ export function createWriteVerbs(
         // re-encrypt it before it's persisted so plaintext of pii/encrypted
         // fields doesn't land in the immutable log (flatChanges is already
         // ciphertext from encryptForStorage above).
-        const event = await append(db.raw, {
-          aggregateId: String(payload.id),
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: currentVersion,
-          type: entityEventName(entityName, "updated"),
-          payload: {
-            changes: flatChanges,
-            previous: await encryptForStorage(previous, user),
-          },
-          metadata: buildEventMetadata(user),
-        });
+        const encryptedPrevious = await encryptForStorage(previous, user);
+        // Savepoint-scoped — see the create() append() above for why:
+        // confines a losing writer's unique-violation to a nested scope
+        // instead of poisoning the whole outer transaction.
+        const event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "updated"),
+            payload: {
+              changes: flatChanges,
+              previous: encryptedPrevious,
+            },
+            metadata: buildEventMetadata(user),
+          }),
+        );
 
         // Live==Rebuild via applyEntityEvent mit demselben StoredEvent —
         // apply liest nur `changes`, und die sind live wie im Replay

package/src/db/query.ts

@@ -18,6 +18,7 @@ export {
   insertOne,
   type OrderByClause,
   runInSavepoint,
+  runInSavepointIfSupported,
   type SelectOptions,
   selectMany,
   type TableInfo,

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

@@ -115,6 +115,65 @@ describe("r.contentCollection() — registration", () => {
     expect(feature.contentCollections?.["signatures"]?.ownership).toBe("user");
   });
 
+  test("records contentFormat so the client can resolve the right editor", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.contentFormat).toBe("plain");
+  });
+
+  test("contentFormat is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.contentFormat).toBeUndefined();
+  });
+
+  test("records contentFormat markdown as a third format alongside plain/rich", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "notes",
+        kind: "text-block",
+        contentFormat: "markdown",
+        nav: { label: "mail:nav.notes" },
+      });
+    });
+
+    expect(feature.contentCollections?.["notes"]?.contentFormat).toBe("markdown");
+  });
+
+  test("records variableSchema so the client can offer the right chips", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        variableSchema: { customerName: "Max Mustermann", orderId: "A-1042" },
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.variableSchema).toEqual({
+      customerName: "Max Mustermann",
+      orderId: "A-1042",
+    });
+  });
+
+  test("variableSchema is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.variableSchema).toBeUndefined();
+  });
+
   test("rejects a second collection with the same id", () => {
     expect(() =>
       defineFeature("mail", (r) => {
@@ -179,6 +238,7 @@ describe("buildAppSchema — content collections", () => {
         r.contentCollection({
           id: "templates",
           kind: "mail-html",
+          contentFormat: "rich",
           nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         });
       }),
@@ -190,6 +250,7 @@ describe("buildAppSchema — content collections", () => {
       {
         id: "templates",
         kind: "mail-html",
+        contentFormat: "rich",
         nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         navQn: "mail:nav:templates",
       },
@@ -199,6 +260,40 @@ describe("buildAppSchema — content collections", () => {
     expect(mail?.navs?.map((n) => n.id)).toContain("templates");
   });
 
+  test("projects variableSchema through to the client schema", () => {
+    const registry = createRegistry([
+      defineFeature("mail", (r) => {
+        r.contentCollection({
+          id: "prompts",
+          kind: "ai-prompt",
+          contentFormat: "plain",
+          variableSchema: { customerName: "Max Mustermann" },
+          nav: { label: "mail:nav.prompts" },
+        });
+      }),
+    ]);
+
+    const schema = buildAppSchema(registry);
+    const mail = schema.features.find((f) => f.featureName === "mail");
+    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(() =>
+      validateBoot([
+        defineFeature("mail2", (r) => {
+          r.contentCollection({
+            id: "prompts",
+            kind: "ai-prompt",
+            variableSchema: { customerName: "Max Mustermann" },
+            nav: { label: "mail2:nav.prompts" },
+          });
+        }),
+      ]),
+    ).not.toThrow();
+  });
+
   test("omits the slot for features without collections", () => {
     const registry = createRegistry([
       defineFeature("shop", (r) => {

package/src/engine/__tests__/entity-handlers.test.ts

@@ -14,6 +14,9 @@ import {
   registerEntityCrud,
 } from "../entity-handlers";
 import { createEntity, createTextField } from "../factories";
+// Barrel import, not "../entity-handlers": covers that entityListSchema is
+// actually re-exported through engine/index.ts.
+import { entityListSchema } from "../index";
 import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
@@ -119,6 +122,19 @@ describe("defineEntityQueryHandler", () => {
     expect(def.schema.safeParse({ sortDirection: "wrong" }).success).toBe(false);
   });
 
+  test("list: schema is the exported entityListSchema, not a private copy", () => {
+    const def = defineEntityListHandler("note", noteEntity);
+    expect(def.schema).toBe(entityListSchema);
+    // money-horse#293: a consumer copy silently dropped these fields when it
+    // drifted from the handler's actual schema — assert they still round-trip.
+    expect(
+      def.schema.safeParse({
+        includeDeleted: true,
+        filters: [{ field: "title", op: "eq", value: "x" }],
+      }).success,
+    ).toBe(true);
+  });
+
   test("detail: schema requires id", () => {
     const def = defineEntityDetailHandler("note", noteEntity);
     expect(def.schema.safeParse({ id: VALID_UUID }).success).toBe(true);

package/src/engine/entity-handlers.ts

@@ -102,7 +102,7 @@ type ListPayload = {
 };
 
 const idSchema = z.object({ id: z.uuid() });
-const listSchema = z.object({
+export const entityListSchema = z.object({
   cursor: z.string().optional(),
   limit: z.number().optional(),
   search: z.string().optional(),
@@ -292,7 +292,7 @@ export function defineEntityQueryHandler(
 
   switch (verb) {
     case "list":
-      schema = listSchema;
+      schema = entityListSchema;
       handler = async (query, ctx) => {
         // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
         // damit payload.search zur Laufzeit gegen Meilisearch/InMem

package/src/engine/index.ts

@@ -69,6 +69,7 @@ export {
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
   type EntityCrudRegistrar,
+  entityListSchema,
   type RegisterEntityCrudOptions,
   registerEntityCrud,
 } from "./entity-handlers";

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/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 } : {}),