@cosmicdrift/kumiko-framework 0.197.0 → 0.198.0

package/src/db/money.ts

@@ -3,10 +3,15 @@
 // Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
 //   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
 //   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
-//   Read-Form:   { amount, currency, amountMinor } — amount in MAJOR units again,
-//                amountMinor sits alongside as exact integer cents (fw#1830) for
-//                callers that need cent-exact comparisons (e.g. invoice sums)
-//                instead of round-tripping the float amount through /100·*100.
+//   Read-Form:   { amount, currency, amountScaled } — amount in MAJOR units again,
+//                amountScaled sits alongside as the exact integer value in
+//                MINOR_UNIT_SCALE units (fw#1830) for callers that need
+//                scale-exact comparisons (e.g. invoice sums) instead of
+//                round-tripping the float amount through /100·*100.
+//                `amountMinor` stays as a @deprecated alias of the same
+//                value until #1976/4 and #1976/5 migrate their remaining
+//                consumers (renderer-web/primitives/index.tsx,
+//                renderer/components/render-field.tsx) off the old name.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
 // "the integer minor unit" — this file used to just pass the API amount
@@ -40,8 +45,8 @@ export function toMinorUnits(amount: number): number {
   return Math.round(amount * MINOR_UNIT_SCALE);
 }
 
-function toMajorUnits(amountMinor: number): number {
-  return amountMinor / MINOR_UNIT_SCALE;
+function toMajorUnits(amountScaled: number): number {
+  return amountScaled / MINOR_UNIT_SCALE;
 }
 
 // One money field's write payload — `{ amount, currency }` or a bare number
@@ -123,11 +128,20 @@ export function flattenMoney(
 }
 
 /** Shape of a single rehydrated money field — {amount major, currency,
- *  amountMinor exact integer cents}. Exported so consumers type their own
- *  copy against this instead of re-declaring the shape by hand. */
+ *  amountScaled exact integer value in MINOR_UNIT_SCALE units}. Exported so
+ *  consumers type their own copy against this instead of re-declaring the
+ *  shape by hand. */
 export type MoneyRead = {
   readonly amount: number;
   readonly currency: string;
+  readonly amountScaled: number;
+  /**
+   * @deprecated Use `amountScaled` — this name implies ISO-4217 minor units
+   * (cents), which is wrong once a currency needing a different scale than
+   * the current flat MINOR_UNIT_SCALE=100 lands (e.g. JPY, 0 decimals).
+   * Alias of `amountScaled`, kept until #1976/4 and #1976/5 migrate their
+   * consumers off it.
+   */
   readonly amountMinor: number;
 };
 
@@ -159,18 +173,18 @@ export function rehydrateMoney(
       continue;
     }
 
-    let amountMinor: number;
+    let amountScaled: number;
     if (typeof amountRaw === "number") {
-      amountMinor = amountRaw;
+      amountScaled = amountRaw;
     } else if (typeof amountRaw === "bigint") {
-      amountMinor = Number(amountRaw);
-      if (!Number.isSafeInteger(amountMinor)) {
+      amountScaled = Number(amountRaw);
+      if (!Number.isSafeInteger(amountScaled)) {
         throw new Error(`rehydrateMoney: field "${name}" bigint amount is not a safe integer`);
       }
     } else if (typeof amountRaw === "string" && amountRaw !== "") {
       // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
-      amountMinor = Number(amountRaw);
-      if (!Number.isSafeInteger(amountMinor)) {
+      amountScaled = Number(amountRaw);
+      if (!Number.isSafeInteger(amountScaled)) {
         throw new Error(
           `rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`,
         );
@@ -184,7 +198,13 @@ export function rehydrateMoney(
     const currency =
       typeof currencyRaw === "string" && currencyRaw !== "" ? currencyRaw : fallbackCurrency;
 
-    result[name] = { amount: toMajorUnits(amountMinor), currency, amountMinor };
+    // amountMinor: deprecated alias, same value as amountScaled — see MoneyRead.
+    result[name] = {
+      amount: toMajorUnits(amountScaled),
+      currency,
+      amountScaled,
+      amountMinor: amountScaled,
+    };
   }
 
   return result;

package/src/db/table-builder.ts

@@ -25,6 +25,7 @@ import {
   moneyAmount,
   table as pgTable,
   plainDate,
+  SQL_EXPR_BRAND,
   type SqlExpression,
   serial,
   sql,
@@ -586,7 +587,12 @@ export function buildEntityTable<E extends EntityDefinition>(
                 .filter((c, i) => c !== def.columns[i])
                 .map((c) => `"${toSnakeCase(c)}" IS NOT NULL`)
                 .join(" AND ");
-              const partialWhere: SqlExpression = { kind: "sql-expr", text: whereText, params: [] };
+              const partialWhere: SqlExpression = {
+                kind: "sql-expr",
+                text: whereText,
+                params: [],
+                [SQL_EXPR_BRAND]: true,
+              };
               indexes[`${indexName}_bidx`] = uniqueIndex(`${indexName}_bidx`)
                 .on(...bidxCols)
                 .where(partialWhere);

package/src/derivatives/__tests__/derivatives-context.test.ts

@@ -171,4 +171,47 @@ describe("createDerivativesContext — variant()", () => {
     expect(provider.mimeTypeOf(result.storageKey)).toBe(result.mimeType);
     expect(result.mimeType).toBe("image/webp");
   });
+
+  // #2021 — a variant with no spec.format used to fall straight through to
+  // the source's mimeType, which is client-controlled (`file.type` off the
+  // upload). A field without `accept` plus a broad `image/*` renderer
+  // wildcard (like `setup()`'s here) let a client ride an active-content
+  // type like `image/svg+xml` all the way to the response Content-Type.
+  test("no spec.format + a non-allowlisted source mimeType does not take over that mimeType", async () => {
+    const { ctx, provider } = await setup("image/svg+xml");
+    const spec = {} as const;
+
+    const result = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(result.mimeType).not.toBe("image/svg+xml");
+    expect(result.mimeType).toBe("application/octet-stream");
+    expect(provider.mimeTypeOf(result.storageKey)).toBe("application/octet-stream");
+  });
+
+  test("no spec.format + a non-allowlisted source mimeType — a cache hit returns the same normalized value", async () => {
+    const { ctx } = await setup("image/svg+xml");
+    const spec = {} as const;
+
+    const first = await ctx.variant(FILE_REF_ID, spec, "thumb");
+    const second = await ctx.variant(FILE_REF_ID, spec, "thumb");
+
+    expect(first.mimeType).toBe("application/octet-stream");
+    expect(second.mimeType).toBe("application/octet-stream");
+  });
+
+  test("no spec.format keeps a known-safe source mimeType — resize-without-reformat stays intact", async () => {
+    const { ctx } = await setup("image/png");
+
+    const result = await ctx.variant(FILE_REF_ID, { maxEdge: 320 }, "thumb");
+
+    expect(result.mimeType).toBe("image/png");
+  });
+
+  test("no spec.format normalizes a `; charset=` suffix off the source mimeType instead of leaking it raw", async () => {
+    const { ctx } = await setup("image/jpeg; charset=binary");
+
+    const result = await ctx.variant(FILE_REF_ID, {}, "thumb");
+
+    expect(result.mimeType).toBe("image/jpeg");
+  });
 });

package/src/derivatives/__tests__/variant-route.integration.test.ts

@@ -27,7 +27,14 @@ const fakeRender: DerivativeRendererPlugin["render"] = async () => {
 const photoEntity = createEntity({
   table: "variant_route_photos",
   fields: {
-    avatar: createImageField({ variants: { thumb: { maxEdge: 100, format: "webp" } } }),
+    avatar: createImageField({
+      variants: {
+        thumb: { maxEdge: 100, format: "webp" },
+        // No format — resize-without-reformat, the legitimate reason
+        // spec.format can be omitted (see #2021).
+        raw: { maxEdge: 100 },
+      },
+    }),
   },
 });
 
@@ -207,4 +214,44 @@ describe("GET /api/files/:id/variant/:name", () => {
     expect(res.status).toBe(415);
     expect(await res.json()).toEqual({ error: "unsupported_media_type" });
   });
+
+  // #2021 — the "raw" variant has no `format`, so its mimeType comes from
+  // outputMimeType's fallback branch. `avatar` has no `accept`, so the
+  // source mimeType is exactly the client-controlled `file.type` from the
+  // upload — this proves the route no longer echoes it verbatim.
+  test("a variant with no spec.format never echoes a non-safe, client-controlled source mimeType", async () => {
+    const token = await stack.jwt.sign(user);
+    const fd = new FormData();
+    fd.append("file", new File([Buffer.from([1, 2, 3])], "avatar.svg", { type: "image/svg+xml" }));
+    fd.append("entityType", "photo");
+    fd.append("fieldName", "avatar");
+    const { body, contentType } = await buildMultipartBody(fd);
+    const uploadRes = await stack.app.request("/api/files", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": contentType },
+      body,
+    });
+    expect(uploadRes.status).toBe(201);
+    const { id: fileId } = (await uploadRes.json()) as { id: string };
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/raw`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).not.toBe("image/svg+xml");
+    expect(res.headers.get("Content-Type")).toBe("application/octet-stream");
+  });
+
+  test("a variant with no spec.format keeps a known-safe source mimeType through the full route (resize without reformat)", async () => {
+    const fileId = await uploadFile();
+    const token = await stack.jwt.sign(user);
+
+    const res = await stack.app.request(`/api/files/${fileId}/variant/raw`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Content-Type")).toBe("image/jpeg");
+  });
 });

package/src/derivatives/derivatives-context.ts

@@ -69,6 +69,23 @@ function isFileRefRow(row: Record<string, unknown>): row is FileRefRow {
   return typeof row["storageKey"] === "string" && typeof row["mimeType"] === "string";
 }
 
+// sourceMimeType is client-controlled (it's `file.type` off the upload — see
+// file-routes.ts's "a field without `accept` lets a client upload anything")
+// and, when spec.format is unset, a renderer is documented to preserve the
+// source's own format (DerivativeRendererPlugin's doc comment) — so the
+// bytes really are in this format, but the STRING itself must still be
+// allowlisted before it becomes a response Content-Type or storage-provider
+// metadata. Otherwise an app whose renderer wildcard is broad enough (e.g.
+// `image/*`) would let a client-declared `image/svg+xml` ride straight
+// through as an honestly-declared (non-sniffed) active-content type (#2021).
+const KNOWN_SAFE_VARIANT_MIME_TYPES: ReadonlySet<string> = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/avif",
+  "image/gif",
+]);
+
 // The spec — not the renderer — determines the output mimeType, so it's the
 // single source of truth for both what gets written to storage and what the
 // caller receives; a cache hit never runs the renderer, so there's nothing
@@ -81,11 +98,24 @@ function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
       return "image/avif";
     case "jpeg":
       return "image/jpeg";
-    default:
-      return sourceMimeType;
+    default: {
+      const normalized = normalizeMimeType(sourceMimeType);
+      return KNOWN_SAFE_VARIANT_MIME_TYPES.has(normalized)
+        ? normalized
+        : "application/octet-stream";
+    }
   }
 }
 
+// `deps.db` is whatever the caller passes through — in the write-handler
+// pipeline (dispatch-shared.ts) that's the handler's open DbTx. `variant()`
+// then holds that transaction open across a full render (decode/resize/
+// encode) plus the storage read+write, not just the fetchOne/exists checks.
+// On a later rollback in the same handler, a variant already written to
+// storage is orphaned there (row never committed, bytes never cleaned up).
+// Prefer this context from the job/MSP path, where `deps.db` isn't tied to
+// an in-flight write transaction; a synchronous write handler rendering a
+// large image should hand off to a job instead of calling `variant()` inline.
 export function createDerivativesContext(deps: DerivativesContextDeps): DerivativesContext {
   return {
     variant: async (fileRefId, spec, name) => {

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

@@ -71,6 +71,26 @@ describe("buildAppSchema", () => {
     });
   });
 
+  // kumiko-framework#2034: createKumikoApp's boot diagnostic reads
+  // `screens[].dormant` from the CLIENT schema, not from the registry —
+  // this pins that the flag actually survives the server→client projection
+  // instead of only living in the registry's verbatim `feature.screens`.
+  test("custom screen's `dormant` flag survives the buildAppSchema projection verbatim (#2034)", () => {
+    const dormantScreenFeature = defineFeature("privacy", (r) => {
+      r.screen({
+        id: "privacy-center",
+        type: "custom",
+        renderer: { react: { __component: "PrivacyCenterScreen" } },
+        dormant: true,
+      });
+    });
+
+    const app = buildAppSchema(createRegistry([dormantScreenFeature]));
+    const screen = app.features.find((f) => f.featureName === "privacy")?.screens[0];
+
+    expect(screen).toMatchObject({ id: "privacy-center", dormant: true });
+  });
+
   test("Feature ohne r.translations lässt das Feld weg (omit-undefined-Pattern)", () => {
     const f = defineFeature("bare", (r) => {
       r.nav({ id: "x", label: "X" });

package/src/engine/__tests__/nav.test.ts

@@ -38,7 +38,7 @@ describe("r.nav() — registration", () => {
       r.nav({
         id: "products",
         label: "shop:nav.products",
-        icon: "box",
+        icon: "package",
         order: 10,
         parent: "shop:nav:catalog",
         screen: "shop:screen:products",
@@ -47,7 +47,7 @@ describe("r.nav() — registration", () => {
     });
     const nav = feature.navs["products"];
     expect(nav).toMatchObject({
-      icon: "box",
+      icon: "package",
       order: 10,
       parent: "shop:nav:catalog",
       screen: "shop:screen:products",
@@ -78,6 +78,14 @@ describe("r.nav() — registration", () => {
       }),
     ).not.toThrow();
   });
+
+  test("@ts-expect-error: icon must be a registered NavIconKey, not any string", () => {
+    const feature = defineFeature("shop", (r) => {
+      // @ts-expect-error — "seting" is a typo of "settings", not a NavIconKey
+      r.nav({ id: "catalog", label: "x", icon: "seting" });
+    });
+    expect(feature.navs["catalog"]).toBeDefined();
+  });
 });
 
 describe("r.screen({ nav }) — inline nav sugar", () => {
@@ -89,13 +97,13 @@ describe("r.screen({ nav }) — inline nav sugar", () => {
         type: "entityList",
         entity: "product",
         columns: ["name"],
-        nav: { label: "shop:nav.products", icon: "box", order: 5 },
+        nav: { label: "shop:nav.products", icon: "package", order: 5 },
       });
     });
     expect(feature.navs["products"]).toMatchObject({
       id: "products",
       label: "shop:nav.products",
-      icon: "box",
+      icon: "package",
       order: 5,
       screen: "shop:screen:products",
     });

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-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/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 {