@cosmicdrift/kumiko-framework 0.197.1 → 0.199.0

package/src/engine/__tests__/soft-delete-cleanup.test.ts

@@ -9,7 +9,7 @@ import {
   softDeleteCleanupJob,
   softDeleteCleanupSystemJob,
 } from "../soft-delete-cleanup";
-import type { AppContext } from "../types/handlers";
+import type { JobContext } from "../types/handlers";
 
 function featureWith(softDelete: boolean | undefined) {
   return defineFeature("probe-sd", (r) => {
@@ -53,7 +53,7 @@ describe("registry soft-delete auto-wiring", () => {
 
 type DeleteCall = { table: unknown; where: Record<string, unknown> };
 
-function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): AppContext {
+function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): JobContext {
   // Shaped to satisfy bun-db's tenantDbDelegate() probe so deleteMany() routes
   // to this recorder instead of trying to extract real table metadata.
   const fakeDb = {
@@ -96,7 +96,7 @@ function makeCtx(opts: { graceDays?: number; calls: DeleteCall[] }): AppContext
     ...(opts.graceDays !== undefined && {
       configResolver: { get: async () => opts.graceDays },
     }),
-  } as unknown as AppContext;
+  } as unknown as JobContext;
 }
 
 describe("softDeleteCleanupJob handler", () => {
@@ -134,7 +134,7 @@ describe("softDeleteCleanupJob handler", () => {
   });
 
   test("throws when the job context is missing db/registry", async () => {
-    await expect(softDeleteCleanupJob({}, {} as AppContext)).rejects.toThrow(
+    await expect(softDeleteCleanupJob({}, {} as JobContext)).rejects.toThrow(
       /ctx.db \+ ctx.registry/,
     );
   });
@@ -161,7 +161,7 @@ describe("softDeleteCleanupSystemJob handler", () => {
   });
 
   test("throws when the job context is missing db/registry", async () => {
-    await expect(softDeleteCleanupSystemJob({}, {} as AppContext)).rejects.toThrow(
+    await expect(softDeleteCleanupSystemJob({}, {} as JobContext)).rejects.toThrow(
       /ctx.db \+ ctx.registry/,
     );
   });

package/src/engine/build-app-schema.ts

@@ -40,6 +40,11 @@ export type BuildAppSchemaOptions = {
   /** Dev-server authoring hints (Settings-Hub placement). Default off — only
    *  `createKumikoServer` opts in; prod boot + unit tests stay silent. */
   readonly authoringWarnings?: boolean;
+  /** Forwarded onto every FeatureSchema.searchAdapterMissing. Set by the boot
+   *  entrypoint (createKumikoServer, runProdApp) from its own
+   *  context.searchAdapter presence check — buildAppSchema itself has no
+   *  context, only the registry. Omit/false when a SearchAdapter is wired. */
+  readonly searchAdapterMissing?: boolean;
 };
 
 export function buildAppSchema(registry: Registry, options: BuildAppSchemaOptions = {}): AppSchema {
@@ -67,6 +72,7 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
       ...(Object.keys(feature.translations ?? {}).length > 0 && {
         translations: feature.translations,
       }),
+      ...(options.searchAdapterMissing === true && { searchAdapterMissing: true }),
     };
     features.push(featureSchema);
   }

package/src/engine/build-config-feature-schema.ts

@@ -28,7 +28,7 @@ import type { ConfigKeyDefinition } from "./types/config";
 import type { Registry } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 import type { AccessRule } from "./types/handlers";
-import type { NavDefinition } from "./types/nav";
+import type { NavDefinition, NavIconKey } from "./types/nav";
 import type {
   ConfigEditScreenDefinition,
   EditFieldsSection,
@@ -57,7 +57,7 @@ export type ConfigFeatureSchema = {
 
 // Audience-Reihenfolge im Sidebar: Plattform vor Tenant vor Benutzer.
 const SCOPE_ORDER: Record<ConfigScope, number> = { system: 10, tenant: 20, user: 30 };
-const SCOPE_ICON: Record<ConfigScope, string> = {
+const SCOPE_ICON: Record<ConfigScope, NavIconKey> = {
   system: "shield",
   tenant: "building",
   user: "user",

package/src/engine/index.ts

@@ -353,6 +353,7 @@ export type {
   MultiStreamProjectionDefinition,
   NameOrRef,
   NavDefinition,
+  NavIconKey,
   NotificationDataFn,
   NotificationDefinition,
   NotificationRecipientFn,
@@ -412,7 +413,7 @@ export type {
   WriteResult,
 } from "./types";
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
-export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
+export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/registry-facade.ts

@@ -203,6 +203,12 @@ export function buildRegistryFacade(state: RegistryState): Registry {
       return state.featureMap.get(featureName)?.systemScope ?? false;
     },
 
+    isJobSystemScoped(qualifiedJobName: string): boolean {
+      const featureName = state.jobFeatureMap.get(qualifiedJobName);
+      if (!featureName) return false;
+      return state.featureMap.get(featureName)?.systemScope ?? false;
+    },
+
     getHandlerFeature(qualifiedHandler: string): string | undefined {
       return state.handlerFeatureMap.get(qualifiedHandler);
     },

package/src/engine/registry-ingest.ts

@@ -129,6 +129,7 @@ export function populateJobsAndNotifications(
       );
     }
     state.jobMap.set(qualifiedName, { ...jobDef, name: qualifiedName });
+    state.jobFeatureMap.set(qualifiedName, feature.name);
   }
 
   // Notifications: scope:notify:name

package/src/engine/registry-state.ts

@@ -180,6 +180,7 @@ export type RegistryState = {
   searchPayloadExtensions: Map<string, OwnedFn<SearchPayloadContributorFn>[]>;
   configKeyMap: Map<string, ConfigKeyDefinition>;
   jobMap: Map<string, JobDefinition>;
+  jobFeatureMap: Map<string, string>;
   notificationMap: Map<string, NotificationDefinition>;
   notificationFeatureMap: Map<string, string>;
   eventMap: Map<string, EventDef>;
@@ -248,6 +249,7 @@ export function createInitialState(): RegistryState {
     searchPayloadExtensions: new Map(),
     configKeyMap: new Map(),
     jobMap: new Map(),
+    jobFeatureMap: new Map(),
     notificationMap: new Map(),
     notificationFeatureMap: new Map(),
     eventMap: new Map(),

package/src/engine/types/index.ts

@@ -138,6 +138,7 @@ export type {
   ClaimKeyJsType,
   ClaimKeyType,
   DeclarativeEventMigration,
+  DispatchWriteRef,
   EntityRef,
   EventDef,
   EventMigrationDef,
@@ -204,10 +205,15 @@ export type {
 export type { EntityId, TenantId } from "@cosmicdrift/kumiko-types/identifiers";
 export {
   isSystemTenant,
+  isUuid,
   parseTenantId,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-types/identifiers";
-export type { ContentCollectionDefinition, NavDefinition } from "@cosmicdrift/kumiko-types/nav";
+export type {
+  ContentCollectionDefinition,
+  NavDefinition,
+  NavIconKey,
+} from "@cosmicdrift/kumiko-types/nav";
 export type {
   FromRule,
   FromRuleKind,

package/src/entrypoint/__tests__/entrypoint-attach-dispatcher.integration.test.ts

@@ -0,0 +1,138 @@
+// Regression test for framework#2044 — attachDispatcher() wiring.
+//
+// #2043 added JobContext.write/queryAs plus JobRunner.attachDispatcher(), but
+// left the entrypoint factories unwired: nothing ever called
+// attachDispatcher() on the JobRunners they build, so ctx.write inside a job
+// always hit the throwing stub in production too. This test proves the
+// wiring closes that gap (a job's ctx.write actually commits when run
+// through a real entrypoint) and that the gap is real (the same job, run
+// against a bare createJobRunner() with no attachDispatcher() call, still
+// throws the #2043 stub).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { asRawClient } from "../../db/query";
+import { createRegistry, defineFeature } from "../../engine";
+import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
+import { createJobRunner } from "../../jobs/job-runner";
+import { createEventConsumerStateTable } from "../../pipeline";
+import { createTestRedis, type TestRedis } from "../../stack";
+import { waitFor } from "../../testing";
+import { createWorkerEntrypoint } from "../index";
+
+const writeProbeResults: Array<{ isSuccess: boolean }> = [];
+const writeProbeFailures: string[] = [];
+
+const writeProbeFeature = defineFeature("writeProbe", (r) => {
+  const noted = r.defineEvent("noted", z.object({ note: z.string() }), { version: 1 });
+  r.writeHandler(
+    "note",
+    z.object({ note: z.string() }),
+    async (event, ctx) => {
+      await ctx.unsafeAppendEvent({
+        aggregateId: crypto.randomUUID(),
+        aggregateType: "write-probe-note",
+        type: noted.name,
+        payload: { note: event.payload.note },
+      });
+      return { isSuccess: true as const, data: { note: event.payload.note } };
+    },
+    { access: { openToAll: true } },
+  );
+  r.job("write-via-job", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
+    try {
+      const result = await ctx.write("write-probe:write:note", {
+        note: payload["note"] as string,
+      });
+      writeProbeResults.push({ isSuccess: result.isSuccess });
+    } catch (error) {
+      writeProbeFailures.push(error instanceof Error ? error.message : String(error));
+      throw error;
+    }
+  });
+});
+
+const JWT = "attach-dispatcher-test-secret-must-be-32-chars!";
+
+let testDb: BunTestDb;
+let testRedis: TestRedis;
+
+beforeAll(async () => {
+  [testDb, testRedis] = await Promise.all([createTestDb(), createTestRedis()]);
+  await createEventsTable(testDb.db);
+  await createArchivedStreamsTable(testDb.db);
+  await createEventConsumerStateTable(testDb.db);
+});
+
+afterAll(async () => {
+  await Promise.all([testDb.cleanup(), testRedis.cleanup()]);
+});
+
+function uniquePrefix(label: string): string {
+  return `${label}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+describe("createWorkerEntrypoint auto-wires attachDispatcher() (framework#2044)", () => {
+  test("ctx.write inside a job commits end-to-end through a real entrypoint", async () => {
+    writeProbeResults.length = 0;
+    const registry = createRegistry([writeProbeFeature]);
+    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("attach-dispatcher"),
+    });
+
+    await worker.start();
+    try {
+      await worker.jobRunner.dispatch("write-probe:job:write-via-job", {
+        note: "written from the job",
+      });
+
+      await waitFor(() => {
+        expect(writeProbeResults.length).toBe(1);
+        expect(writeProbeResults[0]?.isSuccess).toBe(true);
+      });
+
+      const rows = await asRawClient(testDb.db).unsafe(
+        `SELECT payload FROM kumiko_events WHERE type = 'write-probe:event:noted'`,
+      );
+      expect(rows).toHaveLength(1);
+      expect((rows[0] as { payload: { note: string } }).payload.note).toBe("written from the job");
+    } finally {
+      await worker.stop();
+    }
+  });
+});
+
+describe("createJobRunner without attachDispatcher() still hits the #2043 stub", () => {
+  test("ctx.write throws — proves the entrypoint's attachDispatcher() call is the thing that makes writes work", async () => {
+    writeProbeFailures.length = 0;
+    const registry = createRegistry([writeProbeFeature]);
+    const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+    const runner = createJobRunner({
+      registry,
+      context: { db: testDb.db, redis: testRedis.redis },
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix: uniquePrefix("attach-dispatcher-bare"),
+    });
+
+    await runner.start();
+    try {
+      await runner.dispatch("write-probe:job:write-via-job", { note: "should never land" });
+
+      await waitFor(() => {
+        expect(writeProbeFailures.length).toBe(1);
+      });
+      expect(writeProbeFailures[0]).toContain(
+        "JobContext.write called before dispatcher attached — call attachDispatcher() first",
+      );
+    } finally {
+      await runner.stop();
+    }
+  });
+});

package/src/entrypoint/index.ts

@@ -38,7 +38,7 @@ 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";
-import type { AppContext, JobRunIn, Registry, RunIn } from "../engine/types";
+import type { AppContext, DispatchWriteRef, JobRunIn, Registry, RunIn } from "../engine/types";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner";
 import { createJobRunner } from "../jobs/job-runner";
 import type { Lifecycle } from "../lifecycle";
@@ -142,8 +142,9 @@ export type WorkerEntrypoint = {
   readonly eventDispatcher: EventDispatcher;
   readonly jobRunner: JobRunner;
   readonly observability: ObservabilityProvider;
-  // Same dispatcher the API process exposes. Background components in the
-  // worker persist through the write-path — JobContext has no write/query.
+  // Same dispatcher the API process exposes. App-wired background
+  // components that need the dispatcher directly (not JobContext.write)
+  // still persist through it.
   readonly dispatcher: Dispatcher;
   readonly mode: "worker";
   // Starts event-dispatcher poll + BullMQ worker. SIGTERM triggers
@@ -205,6 +206,18 @@ function contextWithObservability(
   };
 }
 
+// Adapts the command-dispatcher's positional (type, payload, user) calls to
+// DispatchWriteRef's (user, qn, payload) shape — JobContext.write/queryAs
+// pass identity explicitly per call (boot-time singleton), while Dispatcher
+// takes it last (request-scoped closure caller). Same underlying pipeline,
+// different argument order.
+function dispatcherToWriteRef(dispatcher: Dispatcher): DispatchWriteRef {
+  return {
+    write: (user, qn, payload) => dispatcher.write(qn, payload, user),
+    queryAs: (user, qn, payload) => dispatcher.query(qn, payload, user),
+  };
+}
+
 // buildApiServer shapes ServerOptions from API-mode caller-options.
 // AllInOneEntrypointOptions extends ApiEntrypointOptions, so structural
 // subtyping makes the all-in-one path a valid caller without an explicit
@@ -381,6 +394,7 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
     apiJobRunner,
     runLocalDispatcher ? "both" : "api",
   );
+  apiJobRunner?.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
 
   return {
     app: server.app,
@@ -422,6 +436,7 @@ export function createWorkerEntrypoint(options: WorkerEntrypointOptions): Worker
     "jobRunner",
   );
   const server = buildWorkerServer({ ...options, context }, lifecycle, jobRunner);
+  jobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
   const eventDispatcher = requireDispatcher(server, "worker");
 
   return {
@@ -491,6 +506,8 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
     workerJobRunner,
     "both",
   );
+  workerJobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
+  apiJobRunner.attachDispatcher(dispatcherToWriteRef(server.dispatcher));
   const eventDispatcher = requireDispatcher(server, "all-in-one");
 
   return {

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

@@ -581,6 +581,22 @@ describe("error handling", () => {
     expect(res.status).toBe(404);
   });
 
+  // #1950: a malformed (non-UUID) id used to reach `selectMany` unchecked —
+  // Postgres rejects it with 22P02, which the pooled Bun.SQL connection
+  // treated as poisoned (see the NONEXISTENT_UUID comment above, added as a
+  // workaround before this guard existed). 404, same as a real-but-absent
+  // id, not the raw DB error.
+  test("download with a malformed (non-UUID) id returns 404, not a DB error", async () => {
+    const res = await getFile(adminUser, "not-a-uuid");
+    expect(res.status).toBe(404);
+  });
+
+  test("a malformed id doesn't poison the pooled connection for the next request", async () => {
+    await getFile(adminUser, "not-a-uuid");
+    const res = await getFile(adminUser, NONEXISTENT_UUID);
+    expect(res.status).toBe(404);
+  });
+
   test("upload wrong file type for entity field is rejected", async () => {
     const pdfContent = new TextEncoder().encode("fake-pdf-content");
     const res = await uploadFile(adminUser, "document.pdf", pdfContent, "application/pdf", {

package/src/files/file-routes.ts

@@ -5,7 +5,13 @@ import type { DbConnection } from "../db/connection";
 import { createEventStoreExecutor } from "../db/event-store-executor";
 import { createTenantDb } from "../db/tenant-db";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer } from "../derivatives";
-import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
+import {
+  isFileField,
+  isUuid,
+  type Registry,
+  type SessionUser,
+  type TenantId,
+} from "../engine/types";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
 import { createFileContext } from "./file-handle";
@@ -396,6 +402,11 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   });
 
   async function loadFileForTenant(id: string, tenantId: TenantId): Promise<FileRef | null> {
+    // fileRefsTable.id is a UUID column — a malformed id must fail here, not
+    // at Postgres (22P02 poisons the pooled Bun.SQL connection). 404, not
+    // 400: an authenticated caller sending a bad id must see the same
+    // response as a nonexistent one, no existence-oracle.
+    if (!isUuid(id)) return null;
     // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
     // never surface to reads/guards.
     const [row] = await selectMany(db, fileRefsTable, { id, tenantId, isDeleted: false });

package/src/jobs/__tests__/job-systemdb.integration.test.ts

@@ -0,0 +1,152 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { createRegistry, defineFeature, type Registry } from "../../engine";
+import { createTestRedis, type TestRedis, testTenantId } from "../../stack";
+import { waitFor } from "../../testing";
+import { createJobRunner, type JobRunner } from "../job-runner";
+
+// r.systemScope() is feature-level (define-feature.ts), not per-job — so two
+// features prove both sides, mirroring pipeline/__tests__/ctx-systemdb.integration.test.ts
+// (the handler-dispatch counterpart from framework#2069/PR#2091).
+
+type JobRunResult = {
+  readonly name: "system" | "tenant" | "system-per-tenant";
+  readonly present: boolean;
+  // assertTenantMatch() must return a TenantDb whose `.raw` is the SAME
+  // underlying DbConnection ctx.db carries — proves systemDb is bound to
+  // the job's own tenant-scoped db, not a separate instance.
+  readonly boundToRawDb: boolean | undefined;
+  // A foreign tenantId must throw fail-closed (AccessDeniedError), same as
+  // the HandlerContext.systemDb self-check.
+  readonly foreignTenantThrew: boolean | undefined;
+};
+
+const results: JobRunResult[] = [];
+const ownTenant = testTenantId(1);
+const foreignTenant = testTenantId(2);
+
+const systemScopedFeature = defineFeature("jobsystemdb-system", (r) => {
+  r.systemScope();
+
+  r.job("check", { trigger: { manual: true } }, async (_payload, ctx) => {
+    if (!ctx.systemDb) {
+      results.push({
+        name: "system",
+        present: false,
+        boundToRawDb: undefined,
+        foreignTenantThrew: undefined,
+      });
+      return;
+    }
+    const checked = ctx.systemDb.assertTenantMatch(ctx.systemUser.tenantId);
+    let foreignTenantThrew = false;
+    try {
+      ctx.systemDb.assertTenantMatch(foreignTenant);
+    } catch {
+      foreignTenantThrew = true;
+    }
+    results.push({
+      name: "system",
+      present: true,
+      boundToRawDb: checked.raw === ctx.db,
+      foreignTenantThrew,
+    });
+  });
+
+  // perTenant jobs go through a separate dispatch path (_perTenant: wrapper
+  // fans out into one child job per tenant, job-runner.ts ~331-352) that
+  // re-enqueues under the bare qualified name before handleJob rebuilds the
+  // context — proves isJobSystemScoped() sees the same jobName fan-out
+  // children get, not the "_perTenant:"-prefixed wrapper name.
+  r.job(
+    "check-per-tenant",
+    { trigger: { manual: true }, perTenant: true },
+    async (_payload, ctx) => {
+      results.push({
+        name: "system-per-tenant",
+        present: ctx.systemDb !== undefined,
+        boundToRawDb: undefined,
+        foreignTenantThrew: undefined,
+      });
+    },
+  );
+});
+
+const tenantScopedFeature = defineFeature("jobsystemdb-tenant", (r) => {
+  r.job("check", { trigger: { manual: true } }, async (_payload, ctx) => {
+    results.push({
+      name: "tenant",
+      present: ctx.systemDb !== undefined,
+      boundToRawDb: undefined,
+      foreignTenantThrew: undefined,
+    });
+  });
+});
+
+let testDb: BunTestDb;
+let testRedis: TestRedis;
+let registry: Registry;
+let jobRunner: JobRunner;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  testRedis = await createTestRedis();
+
+  registry = createRegistry([systemScopedFeature, tenantScopedFeature]);
+
+  const redisUrl = `redis://${testRedis.redis.options.host}:${testRedis.redis.options.port}/${testRedis.redis.options.db}`;
+
+  jobRunner = createJobRunner({
+    registry,
+    context: { db: testDb.db },
+    redisUrl,
+    consumerLane: "worker",
+    queueNamePrefix: `kumiko-job-systemdb-test-${Date.now()}`,
+    getActiveTenantIds: async () => [ownTenant],
+  });
+
+  await jobRunner.start();
+});
+
+afterAll(async () => {
+  await jobRunner.stop();
+  await testDb.cleanup();
+  await testRedis.cleanup();
+});
+
+describe("JobContext.systemDb", () => {
+  test("is present, tenant-bound and fail-closed for r.systemScope() jobs", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-system:job:check", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "system");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(true);
+      expect(result?.boundToRawDb).toBe(true);
+      expect(result?.foreignTenantThrew).toBe(true);
+    });
+  });
+
+  test("is absent for non-system-scoped jobs", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-tenant:job:check", { tenantId: ownTenant });
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "tenant");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(false);
+    });
+  });
+
+  test("is present on the per-tenant fan-out child, not just the direct dispatch path", async () => {
+    results.length = 0;
+    await jobRunner.dispatch("jobsystemdb-system:job:check-per-tenant", {});
+
+    await waitFor(() => {
+      const result = results.find((r) => r.name === "system-per-tenant");
+      expect(result).toBeDefined();
+      expect(result?.present).toBe(true);
+    });
+  });
+});

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

@@ -201,6 +201,13 @@ const testFeature = defineFeature("test", (r) => {
     const value = await ctx.config!("test:config:probe-key");
     jobLog.push({ name: "test:job:config-probe", payload: { value }, timestamp: Date.now() });
   });
+
+  // ctx.write/queryAs throw until JobRunner.attachDispatcher() has run —
+  // regression guard for framework#2043. No test runner here ever calls
+  // attachDispatcher(), so this always hits the stub.
+  r.job("writeProbe", { trigger: { manual: true }, retries: 0 }, async (_payload, ctx) => {
+    await ctx.write("test:write:probe", {});
+  });
 });
 
 beforeAll(async () => {
@@ -803,6 +810,27 @@ describe("error handling", () => {
     );
   });
 
+  test("ctx.write throws before attachDispatcher() has run (framework#2043)", async () => {
+    clearLog();
+    const failures: string[] = [];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:write-probe");
+        await waitFor(() => {
+          expect(failures.length).toBeGreaterThanOrEqual(1);
+        });
+        expect(failures[0]).toContain(
+          "JobContext.write called before dispatcher attached — call attachDispatcher() first",
+        );
+      },
+      {
+        onJobFailed: (jobName, _id, error) => {
+          if (jobName === "test:job:write-probe") failures.push(error);
+        },
+      },
+    );
+  });
+
   test("perTenant without getActiveTenantIds fails wrapper; worker stays alive", async () => {
     clearLog();
     await withRunner(async (runner) => {