@cosmicdrift/kumiko-framework 0.197.1 → 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/derivatives-context.ts

@@ -107,6 +107,15 @@ function outputMimeType(spec: VariantSpec, sourceMimeType: string): string {
   }
 }
 
+// `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 {

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__/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) => {