@cosmicdrift/kumiko-framework 0.14.0 → 0.16.0

package/src/engine/steps/unsafe-projection-upsert.ts

@@ -11,56 +11,88 @@
 // rejected by boot-validation — domain mutation MUST go through
 // r.step.aggregate.*.
 
-import { getTableColumns, type Table } from "drizzle-orm";
-import type { PgColumn } from "drizzle-orm/pg-core";
+import { executeRawQuery } from "../../db/queries/raw-sql";
 import { defineStep } from "../define-step";
 import type { PipelineCtx, StepInstance, StepResolver } from "../types/step";
-import { asQueryTarget } from "./_drizzle-boundary";
 import { resolveRequired } from "./_resolver-utils";
 
 type UnsafeProjectionUpsertArgs = {
-  readonly table: Table;
+  readonly table: unknown;
   readonly on: readonly string[];
   readonly row: StepResolver<Record<string, unknown>>;
 };
 
+// @cast-boundary drizzle-bridge — reads table name + column snake_case
+// names from drizzle Symbol-based metadata without importing drizzle-orm.
+const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
+
+function resolveTableName(table: unknown): string {
+  if (typeof table !== "object" || table === null) {
+    throw new Error("unsafeProjectionUpsert: table is not an object");
+  }
+  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  if (typeof name !== "string") {
+    throw new Error("unsafeProjectionUpsert: table has no kumiko:schema:Name symbol");
+  }
+  return name;
+}
+
+function resolveColumnName(table: unknown, field: string): string {
+  if (typeof table !== "object" || table === null) return field;
+  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
+  if (typeof cols !== "object" || cols === null) return field;
+  const col = (cols as Record<string, unknown>)[field];
+  if (typeof col === "object" && col !== null) {
+    const nameVal = (col as Record<string, unknown>)["name"];
+    if (typeof nameVal === "string") return nameVal;
+  }
+  return field;
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
 defineStep<UnsafeProjectionUpsertArgs, void>({
   kind: "unsafeProjectionUpsert",
   defaultFailureStrategy: "throw",
   run: async (args, ctx: PipelineCtx) => {
     const resolvedRow = resolveRequired(args.row, ctx);
 
-    const columns = getTableColumns(args.table) as Record<string, unknown>;
-    const conflictTargets = args.on.map((key) => {
-      const col = columns[key];
-      if (!col) {
-        throw new Error(`unsafeProjectionUpsert: column "${key}" not found on target table`);
+    // Validate conflict-key columns exist in the row.
+    for (const key of args.on) {
+      if (!(key in resolvedRow)) {
+        throw new Error(`unsafeProjectionUpsert: column "${key}" not found in row`);
       }
-      return col;
-    });
+    }
+
+    const tableName = resolveTableName(args.table);
+    const entries = Object.entries(resolvedRow);
+    const params: unknown[] = [];
 
-    // SET clause is the same row minus the conflict-key columns —
-    // updating a key to itself is harmless but verbose.
-    const updateSet: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(resolvedRow)) {
-      if (!args.on.includes(k)) updateSet[k] = v;
+    const colNames = entries.map(([k]) => quoteIdent(resolveColumnName(args.table, k)));
+    const placeholders = entries.map((_, i) => `$${i + 1}`);
+    for (const [, v] of entries) params.push(v);
+
+    const conflictCols = args.on
+      .map((k) => quoteIdent(resolveColumnName(args.table, k)))
+      .join(", ");
+
+    // SET clause excludes conflict-key columns.
+    const setClauses: string[] = [];
+    let paramIdx = entries.length + 1;
+    for (const [k, v] of entries) {
+      if (args.on.includes(k)) continue;
+      setClauses.push(`${quoteIdent(resolveColumnName(args.table, k))} = $${paramIdx++}`);
+      params.push(v);
     }
 
-    // @cast-boundary drizzle-bridge — The values + set + target casts
-    // cross the drizzle type-boundary for the same reason as
-    // asQueryTarget: resolvedRow is Record<string, unknown> by design
-    // (M.1 phantom-typing limit), drizzle's typed-builder expects
-    // table-specific shapes. Step-author owns shape correctness.
-    // `as never` (not `as any`) — never is contravariantly assignable to
-    // every drizzle Insert-shape; explicit "this bypass cannot be made
-    // type-safe without lifting <TTable extends Table>" marker.
-    await ctx.db
-      .insert(asQueryTarget(args.table))
-      .values(resolvedRow as never)
-      .onConflictDoUpdate({
-        target: conflictTargets as unknown as PgColumn[],
-        set: updateSet as never,
-      });
+    const sqlText =
+      `INSERT INTO ${quoteIdent(tableName)} (${colNames.join(", ")}) VALUES (${placeholders.join(", ")}) ` +
+      `ON CONFLICT (${conflictCols}) DO UPDATE SET ${setClauses.join(", ")}`;
+
+    await executeRawQuery(ctx.db.raw, sqlText, params);
   },
 });
 

package/src/engine/types/feature.ts

@@ -1,5 +1,11 @@
-import type { PgTable } from "drizzle-orm/pg-core";
 import type { ZodType, z } from "zod";
+import type { EntityTableMeta } from "../../db/entity-table-meta";
+
+// PgTable historically came from drizzle-orm/pg-core; the native dialect
+// no longer carries drizzle internal class types. Every caller really
+// needs "an opaque table-object with Symbol-based introspection".
+type PgTable = unknown;
+
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "../define-handler";
 import type {
   ConfigKeyDefinition,
@@ -143,6 +149,23 @@ export type RawTableDef = RawTableEntry & {
   readonly featureName: string;
 };
 
+// --- Unmanaged tables (declared by features via r.unmanagedTable()) ---
+
+/** Per-feature unmanaged-table registration. `meta` is the
+ *  `EntityTableMeta` (framework-native shape used by `migrate-runner`).
+ *  The `reason` justifies the bypass at the registration site — same
+ *  contract as `r.rawTable`. */
+export type UnmanagedTableEntry = {
+  readonly name: string;
+  readonly meta: EntityTableMeta;
+  readonly reason: string;
+};
+
+/** Registry-aggregated unmanaged-table — adds the owning feature name. */
+export type UnmanagedTableDef = UnmanagedTableEntry & {
+  readonly featureName: string;
+};
+
 // --- Feature Definition (output of defineFeature) ---
 
 export type FeatureDefinition = {
@@ -176,7 +199,7 @@ export type FeatureDefinition = {
   // F3 search-payload-extension — per-entity contributors that add flat fields
   // to the search-index payload during indexing. Keyed by entityName. Wrapped
   // in OwnedFn for feature-toggle filtering (consistent with postQuery-Hooks).
-  readonly searchPayloadExtensions: Readonly<
+  readonly searchPayloadExtensions?: Readonly<
     Record<string, readonly OwnedFn<SearchPayloadContributorFn>[]>
   >;
   readonly configKeys: Readonly<Record<string, ConfigKeyDefinition>>;
@@ -269,6 +292,12 @@ export type FeatureDefinition = {
   // system. Keyed by feature-local short name. The registry attaches
   // featureName on aggregation, lifting RawTableEntry → RawTableDef.
   readonly rawTables: Readonly<Record<string, RawTableEntry>>;
+  // Unmanaged tables declared via r.unmanagedTable() — `EntityTableMeta`
+  // shape (post-drizzle), keyed by feature-local table-name. Cousin of
+  // rawTables: same bypass-justification contract, different storage
+  // shape. `kumiko schema generate` aggregates these alongside
+  // r.entity()-derived metas to build the full schema.
+  readonly unmanagedTables: Readonly<Record<string, UnmanagedTableEntry>>;
   // Optional Zod-schema for env-vars this feature reads at runtime.
   // Declared via `r.envSchema(z.object({...}))`. `composeEnvSchema` reads
   // this to build one app-wide schema for boot-validation + dry-run
@@ -577,6 +606,22 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // declare data via `r.entity()` instead.
   rawTable(name: string, table: PgTable, options: RawTableOptions): void;
 
+  // Declare an "unmanaged" framework-native table (post-drizzle).
+  // EntityTableMeta carries the same column-shape that r.entity() builds,
+  // minus the audit-trail + base-columns scaffolding — used for read-side
+  // projections of event-streams (delivery-attempts, job-run-logs) where
+  // r.entity()'s aggregate-lifecycle assumptions don't fit.
+  //
+  // The `meta` argument is the result of `defineUnmanagedTable(...)` from
+  // `@cosmicdrift/kumiko-framework/db`. Reason-justification + audit-trail
+  // contract identical to `r.rawTable`.
+  //
+  // Why this exists separate from `r.rawTable`: rawTable carries a Drizzle
+  // `PgTable` (legacy), unmanagedTable carries the new `EntityTableMeta`
+  // shape that `migrate-runner` consumes. After the full drizzle-cut they
+  // will likely merge; for now they coexist.
+  unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void;
+
   // Register the tree-actions schema for this feature — a map of
   // action-name → action-definition (with optional typed args). At-most-
   // one call per feature.

package/src/engine/types/fields.ts

@@ -5,7 +5,6 @@
 // accepted at the type layer during migration: features that pass an
 // array are auto-normalized to { [role]: "all" } at registry build.
 // Long-term: string[] disappears.
-import type { SQL } from "drizzle-orm";
 import type { OwnershipMap } from "../ownership";
 
 export type FieldAccess = {
@@ -475,7 +474,7 @@ export function isFileField(field: FieldDefinition | undefined): field is AnyFil
 export type TransitionMap = Readonly<Record<string, readonly string[]>>;
 
 /** Composite-Index auf einer Entity. Spalten werden via field-Name
- *  referenziert (camelCase). buildDrizzleTable mapped sie auf snake_case-
+ *  referenziert (camelCase). buildEntityTable mapped sie auf snake_case-
  *  Spaltennamen und benennt den Index nach Convention:
  *
  *    <table>_<col1>_<col2>_idx          (non-unique)
@@ -484,7 +483,7 @@ export type TransitionMap = Readonly<Record<string, readonly string[]>>;
  *  Eine `name`-Override ist erlaubt — Convention-Bruch in Bestandscode
  *  vermeidet Migration-Churn beim Refactor.
  *
- *  Single-column indices über `tenantId` sind redundant (buildDrizzleTable
+ *  Single-column indices über `tenantId` sind redundant (buildEntityTable
  *  legt die immer automatisch an); die Boot-Validation warnt. */
 export type EntityIndexDef = {
   readonly columns: readonly [string, ...string[]];
@@ -503,7 +502,7 @@ export type EntityIndexDef = {
    * man z.B. fuer scharfe BTREE-Indexes nur auf einer Status-Teilmenge
    * statt voller Tabelle).
    */
-  readonly where?: SQL;
+  readonly where?: unknown;
 };
 
 export type FieldsMap = Readonly<Record<string, FieldDefinition>>;
@@ -517,7 +516,7 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
   /** Allowed state transitions per field. Boot validates against select options. */
   readonly transitions?: Readonly<Record<string, TransitionMap>>;
   /** Composite-Indices über mehrere Felder. Single-column FK-Indices und
-   *  der tenant_id-Index werden weiterhin automatisch von buildDrizzleTable
+   *  der tenant_id-Index werden weiterhin automatisch von buildEntityTable
    *  angelegt — diese Liste ist nur für Custom-Indices die der Author
    *  explizit deklariert (z.B. `{ unique: true, columns: ["key", "tenantId", "userId"] }`). */
   readonly indexes?: readonly EntityIndexDef[];

package/src/engine/types/index.ts

@@ -70,6 +70,8 @@ export type {
   SecretKeyDefinition,
   SecretKeyHandle,
   SecretOptions,
+  UnmanagedTableDef,
+  UnmanagedTableEntry,
 } from "./feature";
 export type {
   AnyFileFieldDef,

package/src/engine/types/step.ts

@@ -9,8 +9,8 @@
 // (see TS-typing notes in the design doc). M.1 uses unsafeAppendEvent
 // semantics under the hood for r.step.aggregate.appendEvent.
 
-import type { SQL, Table } from "drizzle-orm";
 import type { EventStoreExecutor } from "../../db/event-store-executor";
+import type { WhereObject } from "../../db/query";
 import type { KumikoEventTypeMap } from "./event-type-map";
 import type { HandlerContext, WriteEvent, WriteResult } from "./handlers";
 import type { SaveContext } from "./hooks";
@@ -200,31 +200,31 @@ export type StepNamespace = {
   // and NOT registered as an aggregate-table via r.entity. See
   // step-vocabulary.md "Was unsafeProjection.* überspringt".
   readonly unsafeProjectionUpsert: (args: {
-    readonly table: Table;
+    readonly table: unknown;
     readonly on: readonly string[];
     readonly row: StepResolver<Record<string, unknown>>;
   }) => StepInstance;
   // Sibling: delete row(s) from a read-side projection table. Same
   // boot-validation contract as unsafeProjectionUpsert.
   readonly unsafeProjectionDelete: (args: {
-    readonly table: Table;
-    readonly where: StepResolver<SQL>;
+    readonly table: unknown;
+    readonly where: StepResolver<WhereObject>;
   }) => StepInstance;
-  // Read sub-namespace — thin wrapper on ctx.db.select(). Caller-owned
-  // tenant-filter (does NOT auto-inject like ctx.queryProjection does).
+  // Read sub-namespace — thin wrapper on selectMany/fetchOne (bun-db).
+  // Caller-owned tenant-filter (does NOT auto-inject like ctx.queryProjection does).
   readonly read: {
     readonly findOne: (
       name: string,
       opts: {
-        readonly table: Table;
-        readonly where: StepResolver<SQL | undefined>;
+        readonly table: unknown;
+        readonly where: StepResolver<WhereObject | undefined>;
       },
     ) => StepInstance;
     readonly findMany: (
       name: string,
       opts: {
-        readonly table: Table;
-        readonly where?: StepResolver<SQL | undefined>;
+        readonly table: unknown;
+        readonly where?: StepResolver<WhereObject | undefined>;
         readonly limit?: number;
       },
     ) => StepInstance;

package/src/engine/validate-projection-allowlist.ts

@@ -23,7 +23,6 @@
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
 
-import { getTableName, type Table } from "drizzle-orm";
 import { getStep } from "./define-step";
 import { buildPipelineSteps } from "./pipeline";
 import type { FeatureDefinition, SessionUser, TenantId, WriteEvent } from "./types";
@@ -56,7 +55,28 @@ function* walkAllSteps(steps: readonly StepInstance[]): Generator<StepInstance,
   }
 }
 
-type UnsafeProjectionStepArgs = { readonly table: Table };
+// @cast-boundary drizzle-bridge — reads table name from drizzle Symbol
+// without importing drizzle-orm (bun-db pattern, see bun-db/query.ts).
+const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
+
+function resolveTableNameFromStep(table: unknown): string {
+  if (typeof table === "object" && table !== null) {
+    // EntityTableMeta discriminator
+    if (
+      "source" in table &&
+      "tableName" in table &&
+      typeof (table as Record<string, unknown>)["tableName"] === "string"
+    ) {
+      return (table as Record<string, unknown>)["tableName"] as string;
+    }
+    // drizzle pgTable
+    const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+    if (typeof name === "string") return name;
+  }
+  throw new Error(`validate-projection-allowlist: cannot resolve table name from ${String(table)}`);
+}
+
+type UnsafeProjectionStepArgs = { readonly table: unknown };
 
 const DUMMY_USER: SessionUser = {
   id: "00000000-0000-0000-0000-000000000000",
@@ -137,7 +157,7 @@ export function validateProjectionAllowlist(features: readonly FeatureDefinition
               `without a \`table\` argument.`,
           );
         }
-        const tableName = getTableName(stepArgs.table);
+        const tableName = resolveTableNameFromStep(stepArgs.table);
 
         const aggregateOwner = aggregateTables.get(tableName);
         if (aggregateOwner) {

package/src/entrypoint/__tests__/{entrypoint-job-wiring.integration.ts → entrypoint-job-wiring.integration.test.ts}

@@ -12,12 +12,13 @@
 // so a future refactor that drops the merge fails here instead of silently
 // regressing to the Welle-2.5 state.
 
-import { afterAll, beforeAll, describe, expect, test } from "vitest";
+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 { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
-import { createTestDb, createTestRedis, type TestDb, type TestRedis, TestUsers } from "../../stack";
+import { createTestRedis, type TestRedis, TestUsers } from "../../stack";
 import { waitFor } from "../../testing";
 import { createAllInOneEntrypoint } from "../index";
 
@@ -72,7 +73,7 @@ const mixedLaneFeature = defineFeature("mixed", (r) => {
 const JWT = "entrypoint-wiring-test-secret-must-be-32-chars!";
 const adminUser = TestUsers.admin;
 
-let testDb: TestDb;
+let testDb: BunTestDb;
 let testRedis: TestRedis;
 
 beforeAll(async () => {

package/src/entrypoint/__tests__/{split-deploy.integration.ts → split-deploy.integration.test.ts}

@@ -11,12 +11,13 @@
 //      guard — buildServer always wires an SSE consumer so this only
 //      fires with systemConsumers explicitly disabled).
 
-import { afterAll, beforeAll, describe, expect, test } from "vitest";
+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 { createRegistry, defineFeature } from "../../engine";
 import { createArchivedStreamsTable, createEventsTable } from "../../event-store";
 import { createEventConsumerStateTable } from "../../pipeline";
-import { createTestDb, createTestRedis, type TestDb, type TestRedis } from "../../stack";
+import { createTestRedis, type TestRedis } from "../../stack";
 import { createAllInOneEntrypoint, createApiEntrypoint, createWorkerEntrypoint } from "../index";
 
 const splitFeature = defineFeature("split", (r) => {
@@ -38,7 +39,7 @@ function uniquePrefix(label: string): string {
   return `${label}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
 
-let testDb: TestDb;
+let testDb: BunTestDb;
 let testRedis: TestRedis;
 
 beforeAll(async () => {

package/src/env/__tests__/compose-env-schema.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import { defineFeature } from "../../engine/define-feature";
 import { camelCase, composeEnvSchema, KumikoBootError, parseEnv, pulumiConfigKey } from "../index";

package/src/env/__tests__/dry-run.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import { defineFeature } from "../../engine/define-feature";
 import { renderDryRun } from "../dry-run";

package/src/errors/__tests__/classes.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import {
   AccessDeniedError,

package/src/errors/__tests__/error-helpers.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { NotFoundError } from "../classes";
+import { FrameworkReasons } from "../reasons";
+import { buildInvalidTransitionDetails } from "../transition-details";
+import { reraiseAsKumikoError, toWriteErrorInfo, writeFailure } from "../write-error-info";
+
+describe("writeFailure", () => {
+  test("wraps KumikoError into WriteFailure envelope", () => {
+    const failure = writeFailure(new NotFoundError("invoice", "inv-1"));
+    expect(failure.isSuccess).toBe(false);
+    expect(failure.error.code).toBe("not_found");
+    expect(failure.error.httpStatus).toBe(404);
+  });
+});
+
+describe("reraiseAsKumikoError", () => {
+  test("round-trips WriteErrorInfo through KumikoError", () => {
+    const info = toWriteErrorInfo(new NotFoundError("task", 7));
+    const err = reraiseAsKumikoError(info);
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+    expect(err.message).toContain("task");
+  });
+});
+
+describe("buildInvalidTransitionDetails", () => {
+  test("builds structured from/to/allowed + message", () => {
+    const details = buildInvalidTransitionDetails("draft", "paid", ["sent"]);
+    expect(details).toMatchObject({
+      from: "draft",
+      to: "paid",
+      allowed: ["sent"],
+    });
+    expect(details.message).toContain("draft");
+    expect(details.message).toContain("sent");
+  });
+});
+
+describe("FrameworkReasons", () => {
+  test("exposes stable snake_case reason codes", () => {
+    expect(FrameworkReasons.invalidTransition).toBe("invalid_transition");
+    expect(FrameworkReasons.staleState).toBe("stale_state");
+  });
+});

package/src/errors/__tests__/field-issue-compat.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import type { FieldIssue as FrameworkFieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import type { FieldIssue as HeadlessFieldIssue } from "@cosmicdrift/kumiko-headless";
+
+describe("FieldIssue cross-package contract", () => {
+  test("framework and headless FieldIssue shapes are assignable", () => {
+    const frameworkIssue: FrameworkFieldIssue = {
+      path: "title",
+      code: "too_small",
+      i18nKey: "errors.validation.too_small",
+      params: { minimum: 1 },
+    };
+    const headlessIssue: HeadlessFieldIssue = frameworkIssue;
+    expect(headlessIssue.path).toBe("title");
+  });
+});

package/src/errors/__tests__/write-failures.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "vitest";
+import { describe, expect, test } from "bun:test";
 import { failNotFound, failTransition, failUnprocessable } from "../write-error-info";
 
 describe("failNotFound", () => {

package/src/errors/classes.ts

@@ -1,16 +1,11 @@
+import { toSnakeCase } from "../utils/case";
+import type { FieldIssue } from "./field-issue";
 import { type ErrorOpts, KumikoError } from "./kumiko-error";
 
-// Per-field validation issue. Shared shape between Zod-derived and
-// hook-derived validation errors so the client sees one list.
-export type ValidationFieldIssue = {
-  readonly path: string;
-  readonly code: string;
-  readonly i18nKey: string;
-  readonly params?: Readonly<Record<string, unknown>>;
-};
+export type { FieldIssue, ValidationFieldIssue } from "./field-issue";
 
 export type ValidationDetails = {
-  readonly fields: readonly ValidationFieldIssue[];
+  readonly fields: readonly FieldIssue[];
 };
 
 export class ValidationError extends KumikoError {
@@ -89,7 +84,7 @@ export class NotFoundError extends KumikoError {
     // The reason string follows `<snake_entity>_not_found` — keeps a stable,
     // client-friendly tag that survives wire serialization even if the entity
     // name is later renamed for display purposes.
-    const reason = `${toSnake(entity)}_not_found`;
+    const reason = `${toSnakeCase(entity)}_not_found`;
     const details: NotFoundDetails & { reason: string } = { reason, entity, id: idStr };
     super({
       message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,
@@ -101,15 +96,6 @@ export class NotFoundError extends KumikoError {
   }
 }
 
-// Accepts camelCase OR kebab-case entity names and produces snake_case for
-// the reason tag. New code uses kebab; legacy camelCase still flows through.
-function toSnake(s: string): string {
-  return s
-    .replace(/-/g, "_")
-    .replace(/([a-z])([A-Z])/g, "$1_$2")
-    .toLowerCase();
-}
-
 // Generic 409. Features that need a narrower shape should subclass (see
 // VersionConflictError) — this way the HTTP layer stays uniform while callers
 // can still instanceof on the concrete subtype in handlers.

package/src/errors/field-issue.ts

@@ -0,0 +1,11 @@
+// Canonical per-field validation issue shape — shared between server-side
+// ValidationError, Zod-bridge, and client-side DispatcherError.details.fields.
+export type FieldIssue = {
+  readonly path: string;
+  readonly code: string;
+  readonly i18nKey: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+};
+
+/** @deprecated Use `FieldIssue` — kept for existing imports. */
+export type ValidationFieldIssue = FieldIssue;

package/src/errors/index.ts

@@ -1,5 +1,6 @@
 export type {
   FeatureDisabledDetails,
+  FieldIssue,
   NotFoundDetails,
   RateLimitDetails,
   UniqueViolationDetails,

package/src/errors/zod-bridge.ts

@@ -1,5 +1,6 @@
 import type { ZodError, ZodIssue } from "zod";
-import { ValidationError, type ValidationFieldIssue } from "./classes";
+import { ValidationError } from "./classes";
+import type { FieldIssue } from "./field-issue";
 
 // Zod issues carry a .code and sometimes issue-specific params (min, max, etc).
 // We surface those under `params` so the client can render "must be at least N"
@@ -24,7 +25,7 @@ const ISSUE_PARAM_KEYS = [
 ] as const;
 
 export function validationErrorFromZod(error: ZodError): ValidationError {
-  const fields = error.issues.map<ValidationFieldIssue>((issue) => {
+  const fields = error.issues.map<FieldIssue>((issue) => {
     const params = extractIssueParams(issue);
     return {
       path: issue.path.map(String).join(".") || "(root)",