@cosmicdrift/kumiko-framework 0.194.0 → 0.196.0

package/package.json

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

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

@@ -8,7 +8,7 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
 import { z } from "zod";
 import { defineFeature, EXT_DERIVATIVE_RENDERER } from "../../engine";
-import { InternalError, writeFailure } from "../../errors";
+import { InternalError, NotFoundError, writeFailure } from "../../errors";
 import { createFilesFeature } from "../../files/feature";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createTestUser, setupTestStack, type TestStack, testTenantId } from "../../stack";
@@ -41,6 +41,37 @@ const derivativesTestFeature = defineFeature("derivativestest", (r) => {
     { access: { openToAll: true } },
   );
 
+  // Catches the error INSIDE the handler (not via HTTP serialization) so the
+  // test can assert `instanceof` on the concrete error class — the wire
+  // response only carries the serialized WireErrorInfo, which loses that.
+  r.writeHandler(
+    "probe-typed-error",
+    z.object({ fileRefId: z.string() }),
+    async (event, ctx) => {
+      if (!ctx.derivatives) {
+        return writeFailure(
+          new InternalError({ message: "no ctx.derivatives on write-handler ctx" }),
+        );
+      }
+      try {
+        await ctx.derivatives.variant(event.payload.fileRefId, { maxEdge: 100 }, "thumb");
+        return { isSuccess: true as const, data: { threw: false } };
+      } catch (err) {
+        return {
+          isSuccess: true as const,
+          data: {
+            threw: true,
+            isNotFoundError: err instanceof NotFoundError,
+            notFoundHttpStatus: err instanceof NotFoundError ? err.httpStatus : undefined,
+            isInternalError: err instanceof InternalError,
+            internalHttpStatus: err instanceof InternalError ? err.httpStatus : undefined,
+          },
+        };
+      }
+    },
+    { access: { openToAll: true } },
+  );
+
   r.job("record", { trigger: { manual: true }, runIn: "worker" }, async (payload, ctx) => {
     const fileRefId = (payload as { fileRefId: string }).fileRefId;
     if (!ctx.derivatives) {
@@ -70,10 +101,13 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-async function uploadFile(asUser = user): Promise<string> {
+async function uploadFile(
+  asUser = user,
+  file = new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }),
+): Promise<string> {
   const token = await stack.jwt.sign(asUser);
   const fd = new FormData();
-  fd.append("file", new File([Buffer.from([1, 2, 3])], "photo.jpg", { type: "image/jpeg" }));
+  fd.append("file", file);
   const { body, contentType } = await buildMultipartBody(fd);
   const res = await stack.app.request("/api/files", {
     method: "POST",
@@ -129,7 +163,7 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: "00000000-0000-4000-8000-999999999999" },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
   });
 
   test("a soft-deleted fileRef throws", async () => {
@@ -146,7 +180,7 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: fileId },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
   });
 
   test("a fileRef uploaded under a different tenant is not resolvable", async () => {
@@ -157,6 +191,39 @@ describe("ctx.derivatives — the mandatory id/tenant/isDeleted filters", () =>
       { fileRefId: foreignFileId },
       user,
     );
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(404);
+  });
+});
+
+describe("ctx.derivatives — typed errors from variant()", () => {
+  test("an unknown fileRefId throws NotFoundError with httpStatus 404", async () => {
+    const result = await stack.http.writeOk<{
+      threw: boolean;
+      isNotFoundError: boolean;
+      notFoundHttpStatus?: number;
+    }>(
+      "derivativestest:write:probe-typed-error",
+      { fileRefId: "00000000-0000-4000-8000-999999999999" },
+      user,
+    );
+    expect(result.threw).toBe(true);
+    expect(result.isNotFoundError).toBe(true);
+    expect(result.notFoundHttpStatus).toBe(404);
+  });
+
+  test("no renderer registered for the mimeType throws InternalError with httpStatus 500", async () => {
+    const fileId = await uploadFile(
+      user,
+      new File([Buffer.from([1, 2, 3])], "doc.pdf", { type: "application/pdf" }),
+    );
+
+    const result = await stack.http.writeOk<{
+      threw: boolean;
+      isInternalError: boolean;
+      internalHttpStatus?: number;
+    }>("derivativestest:write:probe-typed-error", { fileRefId: fileId }, user);
+    expect(result.threw).toBe(true);
+    expect(result.isInternalError).toBe(true);
+    expect(result.internalHttpStatus).toBe(500);
   });
 });

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

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { DerivativeRendererPlugin } from "@cosmicdrift/kumiko-types/derivatives-types";
 import type { Registry } from "../../engine/types";
+import { InternalError } from "../../errors";
 import { createFileContext } from "../../files/file-handle";
 import { createInMemoryFileProvider } from "../../files/in-memory-provider";
 import { createDerivativesContext, resolveRenderer } from "../derivatives-context";
@@ -133,7 +134,7 @@ describe("createDerivativesContext — variant()", () => {
     expect(second.storageKey).not.toBe(first.storageKey);
   });
 
-  test("no renderer registered for the mimeType throws, naming the known patterns", async () => {
+  test("no renderer registered for the mimeType throws InternalError, naming the known patterns in details", async () => {
     const provider = createInMemoryFileProvider();
     await provider.write("tenant/doc.pdf", new Uint8Array([1]));
     const files = createFileContext(() => Promise.resolve(provider));
@@ -141,7 +142,13 @@ describe("createDerivativesContext — variant()", () => {
     const db = fakeDbWithFileRef({ storageKey: "tenant/doc.pdf", mimeType: "application/pdf" });
     const ctx = createDerivativesContext({ files, registry, db, tenantId: TENANT_ID });
 
-    await expect(ctx.variant(FILE_REF_ID, {}, "thumb")).rejects.toThrow(/image\/\*/);
+    // The renderer list moved out of the client-visible `message` into
+    // `details` — InternalError's serialize() drops `details` from the wire
+    // response, so it must not be the only place a caller can find it.
+    const err = await ctx.variant(FILE_REF_ID, {}, "thumb").catch((e) => e);
+    expect(err).toBeInstanceOf(InternalError);
+    expect((err as InternalError).httpStatus).toBe(500);
+    expect((err as InternalError).details).toEqual({ knownRenderers: "image/*" });
   });
 
   test("mimeType is consistent across a fresh render and a cache hit for the same spec", async () => {

package/src/derivatives/derivatives-context.ts

@@ -6,6 +6,7 @@ import type {
 import { type AnyDb, fetchOne } from "../bun-db/query";
 import { EXT_DERIVATIVE_RENDERER } from "../engine/extension-names";
 import type { Registry, TenantId } from "../engine/types";
+import { InternalError, NotFoundError } from "../errors";
 import type { FileContext } from "../files/file-handle";
 import { fileRefsTable } from "../files/file-ref-table";
 import { assertSafeStorageKey } from "../files/types";
@@ -94,12 +95,10 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
         isDeleted: false,
       });
       if (!row) {
-        throw new Error(`derivatives.variant: no fileRef found for id "${fileRefId}"`);
+        throw new NotFoundError("fileRef", fileRefId);
       }
       if (!isFileRefRow(row)) {
-        throw new Error(
-          `derivatives.variant: fileRef "${fileRefId}" is missing storageKey/mimeType`,
-        );
+        throw new NotFoundError("fileRef", fileRefId);
       }
 
       const renderer = resolveRenderer(deps.registry, row.mimeType);
@@ -109,9 +108,10 @@ export function createDerivativesContext(deps: DerivativesContextDeps): Derivati
             .getExtensionUsages(EXT_DERIVATIVE_RENDERER)
             .map((u) => u.entityName)
             .join(", ") || "<none>";
-        throw new Error(
-          `derivatives.variant: no renderer registered for mimeType "${row.mimeType}". Known: ${known}.`,
-        );
+        throw new InternalError({
+          message: `derivatives.variant: no renderer registered for mimeType "${row.mimeType}".`,
+          details: { knownRenderers: known },
+        });
       }
 
       const src = deps.files.ref(row.storageKey);

package/src/engine/boot-validator/screens.ts

@@ -4,11 +4,12 @@
 // into validateColumnRendererForm, splitting them would create a
 // same-folder require cycle.
 
+import { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 import { rowMetaFieldNames } from "../../db/table-builder";
 import { isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
-import type { EntityDefinition, FeatureDefinition, FieldDefinition } from "../types";
+import type { EntityDefinition, FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
   DashboardFilterDefinition,
@@ -24,16 +25,6 @@ import type {
   ToolbarAction,
 } from "../types/screen";
 
-// Mirrors FIELD_TYPES_WITHOUT_WIDGET in packages/renderer/src/app/form-schema.ts.
-// Can't import it directly — renderer depends on framework, not the reverse.
-// Keep both lists in sync when a field type gains or loses an auto-wired widget.
-const NO_WIDGET_FIELD_TYPES: ReadonlySet<FieldDefinition["type"]> = new Set([
-  "jsonb",
-  "embedded",
-  "files",
-  "images",
-]);
-
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
 // entityEdit path (#1925) — a required field the user can never fill would
 // block every save. Only the statically-resolvable case is caught here: a
@@ -48,7 +39,7 @@ function validateNoWidgetRequiredField(
 ): void {
   const fieldDef = entityDef.fields[fieldSpec.field];
   // skip: field doesn't exist or its type already has a widget — nothing to validate.
-  if (fieldDef === undefined || !NO_WIDGET_FIELD_TYPES.has(fieldDef.type)) return;
+  if (fieldDef === undefined || !NO_WIDGET_FIELD_TYPES.includes(fieldDef.type)) return;
   // Embedded LIST fields (`multiple: true`) get their own EmbeddedListField
   // grid widget (#1838) — only plain (non-list) embedded has no widget.
   const isEmbeddedList = fieldDef.type === "embedded" && fieldDef.multiple === true;
@@ -124,7 +115,7 @@ function validateRowActionNavigateParams(
 function validateWizardLayout(
   featureName: string,
   screenId: string,
-  screenType: "entityEdit" | "actionForm",
+  screenType: "entityEdit" | "actionForm" | "configEdit",
   layout: EditLayout,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
@@ -458,6 +449,7 @@ export function validateScreens(
           }
         }
       }
+      validateWizardLayout(feature.name, screenId, "configEdit", screen.layout, featureMap);
       // configKeys: jeder fieldName muss einen Mapping-Eintrag haben,
       // jeder qualifizierte Key muss in der Registry existieren.
       for (const fname of fieldNames) {

package/src/observability/__tests__/metric-validator.test.ts

@@ -66,8 +66,16 @@ describe("buildMetricName", () => {
     expect(buildMetricName("orders", "created_total")).toBe("kumiko_orders_created_total");
   });
 
-  it("rejects non-snake_case feature name", () => {
-    expect(() => buildMetricName("Orders", "created_total")).toThrow(/snake_case/);
+  it("rejects a feature name that stays invalid after kebab-normalization", () => {
+    // A single leading capital ("Orders") now normalizes cleanly via toKebab
+    // — this must still reject a space, which toKebab doesn't touch.
+    expect(() => buildMetricName("orders team", "created_total")).toThrow(/snake_case/);
+  });
+
+  it("normalizes camelCase feature names the same as their kebab-case equivalent", () => {
+    expect(buildMetricName("aiFoundation", "created_total")).toBe(
+      buildMetricName("ai-foundation", "created_total"),
+    );
   });
 });
 

package/src/observability/metric-validator.ts

@@ -1,3 +1,4 @@
+import { toKebab } from "../engine/qualified-name";
 import { assertUnreachable } from "../utils";
 import type { MetricType } from "./types";
 
@@ -74,11 +75,11 @@ export function validateMetricName(name: string, type: MetricType): void {
 // path (registry-ingest.ts) and the read path (ctx.metrics / ctx.metricsFor),
 // instead of the kebab form being rejected outright (framework#1844).
 export function buildMetricName(featureName: string, shortName: string): string {
-  const normalizedFeatureName = featureName.replace(/-/g, "_");
+  const normalizedFeatureName = toKebab(featureName).replace(/-/g, "_");
   if (!SNAKE_CASE.test(normalizedFeatureName)) {
     throw new Error(
-      `[Kumiko Observability] Feature name "${featureName}" must be kebab-case or snake_case ` +
-        `(a-z, 0-9, "-" or "_").`,
+      `[Kumiko Observability] Feature name "${featureName}" must be kebab-case, camelCase, ` +
+        `or snake_case (a-z, 0-9, "-" or "_").`,
     );
   }
   return `kumiko_${normalizedFeatureName}_${shortName}`;

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -149,6 +149,39 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
     { access: { roles: ["Admin"] } },
   );
 
+  // Records whether ctx.db threw (should, once the request signal is
+  // aborted) and whether the ctx.dbOutsideTransaction insert still landed
+  // (should — durability writes must survive a client disconnect).
+  //
+  // The throwing side reads via ctx.db.selectMany, not the event-store
+  // executor's create() — the latter writes through db.raw (bypassing
+  // TenantDb's withDbSpan/signal check entirely), so it wouldn't exercise
+  // the signal wiring this test is meant to prove. insertOne isn't an
+  // option either: bagTable is executor-managed (WritableTable rejects its
+  // EXECUTOR_ONLY brand) — direct writes would drift it past its event
+  // stream. selectMany has no such restriction (reads keep the plain
+  // SchemaTable param) and still goes through the same signal check.
+  r.writeHandler(
+    "bag:create-signal-probe",
+    z.object({ label: z.string() }),
+    async (event, ctx) => {
+      const crud = createEventStoreExecutor(bagTable, bagEntity, { entityName: "bag" });
+      let dbThrewAbortError = false;
+      try {
+        await ctx.db?.selectMany(bagTable, {});
+      } catch (err) {
+        dbThrewAbortError = err instanceof Error && err.name === "AbortError";
+      }
+      const outsideTx = ctx.dbOutsideTransaction;
+      if (!outsideTx) {
+        throw new Error("bag:create-signal-probe requires ctx.dbOutsideTransaction");
+      }
+      await crud.create({ label: `${event.payload.label}-outside-tx` }, event.user, outsideTx);
+      return { isSuccess: true as const, data: { dbThrewAbortError } };
+    },
+    { access: { roles: ["Admin"] } },
+  );
+
   // afterCommit hook on bag — fires once per outer commit.
   r.hook("postSave", { allOf: bag }, async (result) => {
     afterCommitLog.push(`bag:${result.data["label"]}`);
@@ -266,4 +299,35 @@ describe("ctx.dbOutsideTransaction", () => {
     const labels = (bags as Array<Record<string, unknown>>).map((row) => row["label"]);
     expect(labels).toEqual(["probe-outside-tx"]);
   });
+
+  test("an already-aborted request signal fails ctx.db but not ctx.dbOutsideTransaction", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const token = await stack.jwt.sign(admin);
+
+    const res = await stack.app.request(
+      new Request("http://test.local/api/write", {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          type: "ctxbridge:write:bag:create-signal-probe",
+          payload: { label: "signal-probe" },
+        }),
+        signal: controller.signal,
+      }),
+    );
+
+    const body = (await res.json()) as {
+      isSuccess: boolean;
+      data?: { dbThrewAbortError: boolean };
+    };
+    expect(body.isSuccess).toBe(true);
+    expect(body.data?.dbThrewAbortError).toBe(true);
+
+    // Only the outside-tx insert landed — ctx.db's insert threw before it
+    // could write, and there was nothing to roll back for it.
+    const bags = await selectMany(stack.db, bagTable);
+    const labels = (bags as Array<Record<string, unknown>>).map((row) => row["label"]);
+    expect(labels).toEqual(["signal-probe-outside-tx"]);
+  });
 });

package/src/pipeline/dispatch-shared.ts

@@ -170,24 +170,27 @@ export async function buildHandlerContext(
   // but at this point we're the root of the pipeline — cast is safe.
   const dbSource = resolveDbSource(ctx, tx);
   const reqCtx = requestContext.get();
-  const buildTenantScopedDb = (source: DbConnection | DbTx) =>
+  const buildTenantScopedDb = (source: DbConnection | DbTx, signal: AbortSignal | undefined) =>
     createTenantDb(
       source,
       user.tenantId,
       isSystem ? "system" : "tenant",
       context.tracer,
       context.meter,
-      // Propagate the request's AbortSignal so every TenantDb query
-      // throws when the client has disconnected — handlers with many
-      // sequential queries skip the rest of the chain instead of
-      // burning DB-CPU for results no one reads.
-      reqCtx?.signal,
+      signal,
     );
-  const db = dbSource ? buildTenantScopedDb(dbSource) : undefined;
+  // Propagate the request's AbortSignal so every TenantDb query throws when
+  // the client has disconnected — handlers with many sequential queries skip
+  // the rest of the chain instead of burning DB-CPU for results no one reads.
+  const db = dbSource ? buildTenantScopedDb(dbSource, reqCtx?.signal) : undefined;
   // Unbound pool, tenant-scoped like `db` but never tx-bound — writes
-  // through it survive a rollback of the handler's own transaction.
+  // through it survive a rollback of the handler's own transaction. No
+  // AbortSignal here: a client disconnect must not abort a durability write
+  // that is meant to outlive the request.
   const outsideTxSource = resolveDbSource(ctx, undefined);
-  const dbOutsideTransaction = outsideTxSource ? buildTenantScopedDb(outsideTxSource) : undefined;
+  const dbOutsideTransaction = outsideTxSource
+    ? buildTenantScopedDb(outsideTxSource, undefined)
+    : undefined;
   const log = context.log?.child({
     handler: type,
     tenantId: user.tenantId,

package/src/ui-types/index.ts

@@ -20,6 +20,7 @@
 // When adding a symbol here, verify it's either a type or a pure
 // helper with no cross-module side-effects.
 
+export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export type { DerivedCellRoundingTarget } from "../engine/embedded-derived";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived";
 export type { ParsedRefTarget } from "../engine/parse-ref-target";