@cosmicdrift/kumiko-framework 0.15.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.15.0",
+  "version": "0.16.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>",

package/src/api/auth-routes.ts

@@ -6,6 +6,7 @@ import { createSystemUser } from "../engine/system-user";
 import { type SessionUser, SYSTEM_TENANT_ID, type TenantId } from "../engine/types";
 import { NotFoundError } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { parseStringArrayJson } from "../utils/parse-string-array-json";
 import { Routes } from "./api-constants";
 import {
   AUTH_COOKIE_NAME,
@@ -819,11 +820,7 @@ export function createAuthRoutes(
         )) as { roles?: string | null } | null;
         const raw = userRow?.roles;
         if (typeof raw === "string" && raw.length > 0) {
-          // @cast-boundary db-row — userTable.roles is JSON-encoded string[] per AuthUserRow contract
-          const parsed = JSON.parse(raw) as unknown;
-          if (Array.isArray(parsed) && parsed.every((r) => typeof r === "string")) {
-            globalRoles = parsed;
-          }
+          globalRoles = parseStringArrayJson(raw);
         }
       } catch (e) {
         // Non-fatal: globale Rollen kann nicht aufgelöst werden → switch

package/src/bun-db/query.ts

@@ -22,6 +22,7 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
+import { parseJsonSafe } from "../utils/safe-json";
 
 // Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
 // (designed for SHOUT_CASE input) — for already-camelCase keys (mock rows
@@ -276,11 +277,7 @@ export function coerceRow<T extends Record<string, unknown>>(row: T, info: Table
       const t = instantFromDriver(value);
       if (t !== null) coerced = t;
     } else if (pgType === "jsonb" && typeof value === "string") {
-      try {
-        coerced = JSON.parse(value);
-      } catch {
-        // leave as string on parse error — caller decides
-      }
+      coerced = parseJsonSafe(value, value);
     } else if ((pgType === "bigint" || pgType === "bigserial") && typeof value === "string") {
       // postgres-js returns BIGINT as string to avoid JS-Number precision
       // loss past 2^53. Framework contract: bigint columns surface as

package/src/compliance/profiles.ts

@@ -33,6 +33,7 @@
 //
 // Siehe docs/plans/datenschutz/compliance-profiles.md.
 
+import { isPlainObject } from "../utils/is-plain-object";
 import type { BundleTier } from "./sub-processors";
 
 // --- Profile-Schema ---
@@ -302,10 +303,6 @@ export type ComplianceProfileOverride = DeepReadonly<DeepPartial<ComplianceProfi
 
 type DeepPartial<T> = T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
 
-function isPlainObject(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-
 // Pfade die als ganzes Atom ersetzt werden (NICHT rekursiv gemergt).
 // Notwendig fuer Diskriminierte-Union-Types wo das Patch ein Schwester-
 // Property statt einer Override sein kann — z.B. retention von

package/src/db/__tests__/cursor.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { decodeCursor, encodeCursor } from "../cursor";
+
+describe("encodeCursor / decodeCursor", () => {
+  test("round-trips string ids", () => {
+    const id = "0194a1b2-c3d4-7890-abcd-ef1234567890";
+    expect(decodeCursor(encodeCursor(id))).toBe(id);
+  });
+
+  test("round-trips numeric ids", () => {
+    expect(decodeCursor(encodeCursor(42))).toBe("42");
+  });
+
+  test("decodeCursor throws on empty payload", () => {
+    expect(() => decodeCursor(encodeCursor(""))).toThrow(/Invalid cursor/);
+  });
+});

package/src/db/__tests__/migrate-generator.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, test } from "bun:test";
+import type { EntityTableMeta } from "../entity-table-meta";
+import {
+  diffSnapshots,
+  generateMigration,
+  renderMigrationSql,
+  snapshotFromMetas,
+} from "../migrate-generator";
+
+function meta(
+  tableName: string,
+  extraColumn?: EntityTableMeta["columns"][number],
+): EntityTableMeta {
+  return {
+    tableName,
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
+      ...(extraColumn ? [extraColumn] : []),
+    ],
+  };
+}
+
+describe("snapshotFromMetas", () => {
+  test("sorts tables by name for stable snapshots", () => {
+    const snap = snapshotFromMetas([meta("zebras"), meta("apples")]);
+    expect(snap.tables.map((t) => t.tableName)).toEqual(["apples", "zebras"]);
+    expect(snap.version).toBe(1);
+  });
+});
+
+describe("diffSnapshots", () => {
+  test("null prev → all tables are new", () => {
+    const next = snapshotFromMetas([meta("tasks")]);
+    const diff = diffSnapshots(null, next);
+    expect(diff.newTables.map((t) => t.tableName)).toEqual(["tasks"]);
+    expect(diff.droppedTables).toEqual([]);
+  });
+
+  test("detects dropped table and new column", () => {
+    const prev = snapshotFromMetas([meta("tasks"), meta("legacy")]);
+    const next = snapshotFromMetas([
+      meta("tasks", { name: "title", pgType: "text", notNull: true }),
+    ]);
+    const diff = diffSnapshots(prev, next);
+    expect(diff.droppedTables).toEqual(["legacy"]);
+    expect(diff.changedTables[0]?.newColumns.map((c) => c.name)).toEqual(["title"]);
+  });
+});
+
+describe("renderMigrationSql / generateMigration", () => {
+  test("emits CREATE TABLE for new tables", () => {
+    const diff = diffSnapshots(null, snapshotFromMetas([meta("tasks")]));
+    const sql = renderMigrationSql(diff, { name: "init", sequenceNumber: 1 });
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "tasks"');
+    expect(sql).toContain("Migration 0001_init");
+  });
+
+  test("generateMigration bundles snapshot + sql", () => {
+    const out = generateMigration({
+      metas: [meta("tasks")],
+      prevSnapshot: null,
+      name: "init",
+      sequenceNumber: 1,
+    });
+    expect(out.snapshot.tables).toHaveLength(1);
+    expect(out.sqlContent).toContain("0001_init");
+    expect(out.filename).toBe("0001_init.sql");
+  });
+});

package/src/db/__tests__/migrate-runner.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import { splitSqlStatements } from "../migrate-runner";
+
+describe("splitSqlStatements", () => {
+  test("splits on semicolons and strips line comments", () => {
+    const sql = `
+      CREATE TABLE "a" (id uuid); -- inline comment
+      CREATE TABLE "b" (id uuid);
+    `;
+    expect(splitSqlStatements(sql)).toEqual([
+      'CREATE TABLE "a" (id uuid);',
+      'CREATE TABLE "b" (id uuid);',
+    ]);
+  });
+
+  test("filters empty segments", () => {
+    expect(splitSqlStatements("-- only comments\n; ;")).toEqual([]);
+  });
+});

package/src/db/__tests__/pg-error.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation } from "../pg-error";
+
+describe("extractPgError", () => {
+  test("reads code from top-level postgres-js error", () => {
+    const info = extractPgError({ code: "23505", constraint_name: "users_email_uq" });
+    expect(info).toEqual({ code: "23505", constraint_name: "users_email_uq" });
+  });
+
+  test("unwraps DrizzleQueryError.cause", () => {
+    const info = extractPgError({
+      message: "wrapper",
+      cause: { code: "23505", constraint_name: "uq" },
+    });
+    expect(info?.code).toBe("23505");
+  });
+
+  test("returns null for non-objects", () => {
+    expect(extractPgError("nope")).toBeNull();
+  });
+});
+
+describe("isUniqueViolation", () => {
+  test("true for SQLSTATE 23505", () => {
+    expect(isUniqueViolation({ code: "23505" })).toBe(true);
+  });
+
+  test("false otherwise", () => {
+    expect(isUniqueViolation({ code: "23503" })).toBe(false);
+  });
+});
+
+describe("isTableAlreadyExists", () => {
+  test("true for SQLSTATE 42P07", () => {
+    expect(isTableAlreadyExists({ code: "42P07" })).toBe(true);
+  });
+});
+
+describe("constraintOf", () => {
+  test("returns constraint_name when present", () => {
+    expect(constraintOf({ constraint_name: "users_email_uq" })).toBe("users_email_uq");
+  });
+});

package/src/db/table-builder.ts

@@ -5,6 +5,10 @@ import type {
   FieldsMap,
 } from "../engine/types";
 import { assertUnreachable } from "../utils";
+import { toSnakeCase } from "../utils/case";
+
+export { toSnakeCase } from "../utils/case";
+
 import {
   bigint,
   boolean,
@@ -192,12 +196,8 @@ function fieldToColumns(
 }
 
 // Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
-// entity / field names. Kebab is the canonical form for new multi-word entity
-// types (consistent across r.entity, event-types, table names) — camelCase is
-// kept working for already-shipped code.
-export function toSnakeCase(str: string): string {
-  return str.replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-}
+// entity / field names. Implementation lives in utils/case — re-exported here
+// for backwards-compatible imports from db/table-builder.
 
 /**
  * Derives a table name from an entity name:

package/src/engine/__tests__/duration-utils.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { addDuration } from "../steps/_duration-utils";
+
+describe("addDuration", () => {
+  test("adds ISO duration to base instant", () => {
+    const base = "2024-01-01T00:00:00Z";
+    const result = addDuration(base, "PT1H");
+    expect(result).toBe(Temporal.Instant.from(base).add({ hours: 1 }).toString());
+  });
+
+  test("throws on invalid duration", () => {
+    expect(() => addDuration("2024-01-01T00:00:00Z", "not-a-duration")).toThrow(
+      /Invalid ISO-8601 duration/,
+    );
+  });
+});

package/src/engine/__tests__/field-access.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { checkWriteFieldRoles, filterReadFields } from "../field-access";
+import type { EntityDefinition } from "../types";
+
+const entity: EntityDefinition = {
+  fields: {
+    title: { type: "text", access: { read: { editor: "all" }, write: { editor: "all" } } },
+    secret: { type: "text", access: { read: { admin: "all" }, write: { admin: "all" } } },
+  },
+};
+
+const editor = { id: "u1", tenantId: "t1", roles: ["editor"] as const };
+const admin = { id: "u2", tenantId: "t1", roles: ["admin"] as const };
+
+describe("filterReadFields", () => {
+  test("strips fields the user cannot read", () => {
+    const row = { id: 1, title: "Hello", secret: "hidden" };
+    const filtered = filterReadFields(entity, row, editor);
+    expect(filtered["title"]).toBe("Hello");
+    expect(filtered["secret"]).toBeUndefined();
+  });
+
+  test("keeps restricted fields for allowed roles", () => {
+    const row = { id: 1, title: "Hello", secret: "visible" };
+    const filtered = filterReadFields(entity, row, admin);
+    expect(filtered["secret"]).toBe("visible");
+  });
+});
+
+describe("checkWriteFieldRoles", () => {
+  test("returns denied field name when role missing", () => {
+    expect(checkWriteFieldRoles(entity, { secret: "x" }, editor)).toBe("secret");
+  });
+
+  test("returns null when all changed fields are allowed", () => {
+    expect(checkWriteFieldRoles(entity, { title: "x" }, editor)).toBeNull();
+  });
+});

package/src/engine/__tests__/no-return-guard.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { validateNoReturnSteps } from "../steps/_no-return-guard";
+import type { StepInstance } from "../types/step";
+
+describe("validateNoReturnSteps", () => {
+  test("passes when no return steps present", () => {
+    const steps = [{ kind: "noop" }] as unknown as readonly StepInstance[];
+    expect(() => validateNoReturnSteps(steps, "r.step.branch.onTrue")).not.toThrow();
+  });
+
+  test("throws when return step is nested", () => {
+    const steps = [{ kind: "return" }] as unknown as readonly StepInstance[];
+    expect(() => validateNoReturnSteps(steps, "r.step.forEach.do")).toThrow(
+      /not allowed inside r\.step\.forEach\.do/,
+    );
+  });
+});

package/src/engine/__tests__/unmanaged-table.test.ts

@@ -0,0 +1,98 @@
+// Unit tests for r.unmanagedTable() — the EntityTableMeta cousin of
+// r.rawTable. Same audit-trail contract, different storage shape (post-
+// drizzle migrate-runner). See define-feature.ts / DX-4.
+
+import { describe, expect, test } from "bun:test";
+import { defineUnmanagedTable } from "../../db/entity-table-meta";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+
+const probeMeta = defineUnmanagedTable({
+  tableName: "ut_probe",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+const probeMetaTwo = defineUnmanagedTable({
+  tableName: "ut_probe_two",
+  columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
+});
+
+describe("r.unmanagedTable — declaration", () => {
+  test("rejects duplicate registrations within one feature", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "test" });
+        r.unmanagedTable(probeMeta, { reason: "test" });
+      }),
+    ).toThrow(/already registered/);
+  });
+
+  test("rejects empty reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "" });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("rejects whitespace-only reason", () => {
+    expect(() =>
+      defineFeature("probe", (r) => {
+        r.unmanagedTable(probeMeta, { reason: "   " });
+      }),
+    ).toThrow(/options\.reason must be a non-empty string/);
+  });
+
+  test("accepts valid registration and stores meta + reason", () => {
+    const feature = defineFeature("probe", (r) => {
+      r.unmanagedTable(probeMeta, {
+        reason: "read-side projection of an event-stream",
+      });
+    });
+    expect(feature.unmanagedTables).toHaveProperty("ut_probe");
+    expect(feature.unmanagedTables["ut_probe"]?.reason).toBe(
+      "read-side projection of an event-stream",
+    );
+    expect(feature.unmanagedTables["ut_probe"]?.meta).toBe(probeMeta);
+  });
+
+  test("two unmanaged tables on one feature register under their tableName", () => {
+    const feature = defineFeature("dual", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "one" });
+      r.unmanagedTable(probeMetaTwo, { reason: "two" });
+    });
+    expect(Object.keys(feature.unmanagedTables).sort()).toEqual(["ut_probe", "ut_probe_two"]);
+  });
+
+  test("absent unmanagedTables on a feature is ok", () => {
+    const feat = defineFeature("plain", () => {
+      // no r.unmanagedTable calls
+    });
+    expect(feat.unmanagedTables).toEqual({});
+  });
+});
+
+describe("createRegistry — unmanagedTable aggregation", () => {
+  test("rejects cross-feature tableName collisions at boot", () => {
+    // Two features can't share the same physical tableName — migrate-runner
+    // would race two CREATE TABLE statements. Boot-validator catches it.
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).toThrow(
+      /Unmanaged-table "ut_probe" registered by both feature "a" and "b"/,
+    );
+  });
+
+  test("two features with distinct tableNames register cleanly", () => {
+    const featA = defineFeature("a", (r) => {
+      r.unmanagedTable(probeMeta, { reason: "first" });
+    });
+    const featB = defineFeature("b", (r) => {
+      r.unmanagedTable(probeMetaTwo, { reason: "second" });
+    });
+    expect(() => createRegistry([featA, featB])).not.toThrow();
+  });
+});

package/src/engine/define-feature.ts

@@ -1,4 +1,5 @@
 import type { ZodType, z } from "zod";
+import type { EntityTableMeta } from "../db/entity-table-meta";
 import { toTableName } from "../db/table-builder";
 import { LifecycleHookTypes } from "./constants";
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-handler";
@@ -61,6 +62,7 @@ import type {
   TreeActionDef,
   TreeActionsHandle,
   TreeChildrenSubscribe,
+  UnmanagedTableEntry,
   ValidationHookFn,
   WriteHandlerDef,
   WriteHandlerFn,
@@ -136,6 +138,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const projections: Record<string, ProjectionDefinition> = {};
   const multiStreamProjections: Record<string, MultiStreamProjectionDefinition> = {};
   const rawTables: Record<string, RawTableEntry> = {};
+  const unmanagedTables: Record<string, UnmanagedTableEntry> = {};
   const authClaimsHooks: AuthClaimsFn[] = [];
   const claimKeys: Record<string, ClaimKeyDefinition> = {};
   const screens: Record<string, ScreenDefinition> = {};
@@ -791,6 +794,38 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
     },
 
+    unmanagedTable(meta: EntityTableMeta, options: RawTableOptions): void {
+      // Name comes from the meta itself — apps already give the table a
+      // name when calling defineUnmanagedTable, no need to repeat it.
+      const tableName = meta.tableName;
+      if (!isKebabSegment(tableName.replace(/_/g, "-"))) {
+        // EntityTableMeta uses snake_case for tableName (matches Postgres
+        // convention); we just guard against truly broken input.
+        throw new Error(
+          `[Feature ${name}] Unmanaged-table name "${tableName}" must be a ` +
+            `valid identifier (lowercase letters, digits, underscores; start with a letter).`,
+        );
+      }
+      if (unmanagedTables[tableName]) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}") already registered. ` +
+            `Unmanaged-table names must be unique per feature.`,
+        );
+      }
+      if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+        throw new Error(
+          `[Feature ${name}] r.unmanagedTable("${tableName}"): options.reason must be a ` +
+            `non-empty string. The reason justifies the audit-trail bypass — ` +
+            `if you can't write one, declare data via r.entity() instead.`,
+        );
+      }
+      unmanagedTables[tableName] = {
+        name: tableName,
+        meta,
+        reason: options.reason,
+      };
+    },
+
     claimKey<T extends ClaimKeyType>(
       shortName: string,
       options: { readonly type: T },
@@ -905,6 +940,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     workspaces,
     httpRoutes,
     rawTables,
+    unmanagedTables,
     ...(treeActions !== undefined && { treeActions }),
     ...(treeProvider !== undefined && { treeProvider }),
     ...(envSchema !== undefined && { envSchema }),

package/src/engine/feature-ast/extractors/shared.ts

@@ -1,5 +1,6 @@
 import type { CallExpression, Node } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
+import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
 
 export type ExtractOutput<TPattern> =
@@ -107,9 +108,7 @@ export function readDataLiteralNode(node: Node): unknown {
   }
 }
 
-export function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+export { isPlainObject } from "../../../utils/is-plain-object";
 
 export function readPropertyKey(propAssign: import("ts-morph").PropertyAssignment): string {
   const nameNode = propAssign.getNameNode();

package/src/engine/registry.ts

@@ -40,6 +40,7 @@ import type {
   TranslationKeys,
   TreeActionDef,
   TreeChildrenSubscribe,
+  UnmanagedTableDef,
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "./types";
@@ -169,6 +170,10 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
   // enforced at ingest below (collisions would race two CREATE TABLE
   // statements at the same physical name and break boot).
   const rawTableMap = new Map<string, RawTableDef>();
+  // Unmanaged tables — declared via r.unmanagedTable() (EntityTableMeta).
+  // Cousin of rawTables: same uniqueness-by-tableName invariant, different
+  // storage shape (post-drizzle migrate-runner consumes EntityTableMeta).
+  const unmanagedTableMap = new Map<string, UnmanagedTableDef>();
   // Auth-claims hooks — tagged with featureName so the login resolver can
   // auto-prefix each hook's returned keys with "<feature>:".
   const authClaimsHooks: AuthClaimsHookDef[] = [];
@@ -543,6 +548,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
       rawTableMap.set(rawName, { ...rawDef, featureName: feature.name });
     }
 
+    // Unmanaged tables — same cross-feature uniqueness invariant as rawTables.
+    // Two features registering the same physical tableName would race two
+    // CREATE TABLE statements via migrate-runner.
+    for (const [umName, umDef] of Object.entries(feature.unmanagedTables ?? {})) {
+      const existing = unmanagedTableMap.get(umName);
+      if (existing) {
+        throw new Error(
+          `Unmanaged-table "${umName}" registered by both feature "${existing.featureName}" and ` +
+            `"${feature.name}". Pick a feature-prefixed tableName to disambiguate.`,
+        );
+      }
+      unmanagedTableMap.set(umName, { ...umDef, featureName: feature.name });
+    }
+
     // Claim keys: aggregated by qualified name. Two features cannot collide
     // here (qualified by feature name), but we still guard for explicit
     // correctness — the only way to hit this is a hand-built FeatureDefinition

package/src/engine/types/feature.ts

@@ -1,4 +1,5 @@
 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
@@ -148,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 = {
@@ -274,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
@@ -582,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/index.ts

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

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/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)",

package/src/es-ops/context.ts

@@ -15,6 +15,7 @@ import {
 } from "../db/queries/seed-context";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { parseStringArrayJson } from "../utils/parse-string-array-json";
 import type { SeedMembershipRow, SeedMigrationContext, SeedTenantRow } from "./types";
 
 export type CreateSeedMigrationContextArgs = {
@@ -75,7 +76,7 @@ export function createSeedMigrationContext(
           userId: r.user_id,
           tenantId: r.tenant_id,
           streamTenantId: r.stream_tenant_id,
-          roles: safeParseRolesJson(r.roles),
+          roles: parseStringArrayJson(r.roles),
         }),
       );
     },
@@ -89,17 +90,5 @@ export function createSeedMigrationContext(
   };
 }
 
-function safeParseRolesJson(raw: string): readonly string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
-      return parsed;
-    }
-  } catch {
-    // Fallthrough — return empty rather than throwing in a seed context.
-  }
-  return [];
-}
-
 // Re-export für Caller-Convenience.
 export type { SeedMigrationContext } from "./types";

package/src/pipeline/__tests__/dispatcher-utils.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "bun:test";
+import { createSystemUser } from "../../engine/system-user";
+import { InternalError } from "../../errors";
+import {
+  describeShape,
+  dispatcherSpanAttributes,
+  extractNestedSpecs,
+  isFailedWriteResult,
+  isLifecycleResult,
+  isWriteResultShape,
+  prefixValidationPath,
+  resolveType,
+  wrapToKumiko,
+} from "../dispatcher-utils";
+
+describe("isFailedWriteResult", () => {
+  test("narrows failed write results", () => {
+    const result = { isSuccess: false as const, error: { code: "validation_error" } };
+    expect(isFailedWriteResult(result)).toBe(true);
+    expect(isFailedWriteResult({ isSuccess: true, data: {} })).toBe(false);
+  });
+});
+
+describe("isWriteResultShape / isLifecycleResult", () => {
+  test("detects write-result envelope", () => {
+    expect(isWriteResultShape({ isSuccess: true, data: 1 })).toBe(true);
+    expect(isWriteResultShape({ kind: "created" })).toBe(false);
+  });
+
+  test("detects lifecycle results", () => {
+    expect(isLifecycleResult({ kind: "deleted" })).toBe(true);
+    expect(isLifecycleResult(null)).toBe(false);
+  });
+});
+
+describe("describeShape", () => {
+  test("summarizes unknown values", () => {
+    expect(describeShape(null)).toBe("null");
+    expect(describeShape("x")).toBe("string");
+    expect(describeShape({ a: 1, b: 2 })).toContain("object with keys");
+  });
+});
+
+describe("dispatcherSpanAttributes", () => {
+  test("includes handler, operation, user, tenant, optional feature", () => {
+    const user = createSystemUser("tenant-1");
+    const attrs = dispatcherSpanAttributes("feat:query:task:list", "query", user, "feat");
+    expect(attrs).toMatchObject({
+      "kumiko.handler": "feat:query:task:list",
+      "kumiko.operation": "query",
+      "kumiko.feature": "feat",
+    });
+  });
+});
+
+describe("prefixValidationPath", () => {
+  test("prefixes validation field paths", () => {
+    const info = {
+      code: "validation_error",
+      httpStatus: 400,
+      i18nKey: "errors.validation.failed",
+      message: "Validation failed",
+      details: {
+        fields: [{ path: "title", code: "too_small", i18nKey: "errors.validation.too_small" }],
+      },
+    };
+    const prefixed = prefixValidationPath(info, "tasks.0");
+    const fields = (prefixed.details as { fields: { path: string }[] }).fields;
+    expect(fields[0]?.path).toBe("tasks.0.title");
+  });
+
+  test("leaves non-validation errors unchanged", () => {
+    const info = {
+      code: "not_found",
+      httpStatus: 404,
+      i18nKey: "errors.notFound",
+      message: "missing",
+    };
+    expect(prefixValidationPath(info, "x")).toBe(info);
+  });
+});
+
+describe("resolveType", () => {
+  test("unwraps HandlerRef objects", () => {
+    expect(resolveType({ name: "feat:write:task:create" })).toBe("feat:write:task:create");
+    expect(resolveType("feat:query:task:list")).toBe("feat:query:task:list");
+  });
+});
+
+describe("wrapToKumiko", () => {
+  test("passes through KumikoError instances", () => {
+    const err = new InternalError();
+    expect(wrapToKumiko(err)).toBe(err);
+  });
+
+  test("wraps generic Error as InternalError", () => {
+    const wrapped = wrapToKumiko(new TypeError("boom"));
+    expect(wrapped.code).toBe("internal_error");
+    expect(wrapped.cause).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("extractNestedSpecs", () => {
+  test("returns null for non-create handlers", () => {
+    expect(extractNestedSpecs("feat:write:task:update", { tasks: [] }, {} as never)).toBeNull();
+  });
+});

package/src/pipeline/__tests__/redis-keys.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { RedisKeys } from "../redis-keys";
+
+describe("RedisKeys", () => {
+  test("uses unique kumiko-prefixed namespaces", () => {
+    const values = Object.values(RedisKeys);
+    expect(new Set(values).size).toBe(values.length);
+    for (const key of values) {
+      expect(key.startsWith("kumiko:")).toBe(true);
+    }
+  });
+});

package/src/pipeline/dispatcher-utils.ts

@@ -6,7 +6,13 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
-import { InternalError, isKumikoError, type KumikoError, type WriteErrorInfo } from "../errors";
+import {
+  type FieldIssue,
+  InternalError,
+  isKumikoError,
+  type KumikoError,
+  type WriteErrorInfo,
+} from "../errors";
 
 export type FailedWriteResult = Extract<WriteResult, { isSuccess: false }>;
 
@@ -146,12 +152,7 @@ export function prefixValidationPath(info: WriteErrorInfo, prefix: string): Writ
   if (info.code !== "validation_error") return info;
   const details = info.details as // @cast-boundary error-details
     | {
-        fields?: readonly {
-          path: string;
-          code: string;
-          i18nKey: string;
-          params?: Readonly<Record<string, unknown>>;
-        }[];
+        fields?: readonly FieldIssue[];
       }
     | undefined;
   const fields = details?.fields;

package/src/stack/test-stack.ts

@@ -4,6 +4,7 @@ import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
 import { createSseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
+import { extractTableInfo } from "../db/query";
 import { createRegistry } from "../engine/registry";
 import type { FeatureDefinition, Registry, TenantId } from "../engine/types";
 import { createArchivedStreamsTable, createEventsTable } from "../event-store";
@@ -207,10 +208,9 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     // exist; drizzle-kit's diff machinery would otherwise emit CREATE for
     // them again.
     const { tableExists } = await import("../db/schema-inspection");
-    const { getTableName } = await import("drizzle-orm");
     const missing: Record<string, unknown> = {};
     for (const [key, tbl] of Object.entries(projectionTables)) {
-      const physical = getTableName(tbl as Parameters<typeof getTableName>[0]); // @cast-boundary drizzle-bridge
+      const physical = extractTableInfo(tbl).name;
       if (await tableExists(testDb.db, `public.${physical}`)) continue;
       missing[key] = tbl;
     }

package/src/utils/__tests__/case.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { toSnakeCase } from "../case";
+
+describe("toSnakeCase", () => {
+  test("camelCase → snake_case", () => {
+    expect(toSnakeCase("tenantMembership")).toBe("tenant_membership");
+  });
+
+  test("kebab-case → snake_case", () => {
+    expect(toSnakeCase("billing-period")).toBe("billing_period");
+  });
+
+  test("single segment unchanged", () => {
+    expect(toSnakeCase("users")).toBe("users");
+  });
+});

package/src/utils/__tests__/is-plain-object.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { isPlainObject } from "../is-plain-object";
+
+describe("isPlainObject", () => {
+  test("accepts plain objects", () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1 })).toBe(true);
+  });
+
+  test("rejects null, arrays, and primitives", () => {
+    expect(isPlainObject(null)).toBe(false);
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject("x")).toBe(false);
+    expect(isPlainObject(42)).toBe(false);
+  });
+});

package/src/utils/__tests__/parse-string-array-json.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import { parseStringArrayJson } from "../parse-string-array-json";
+
+describe("parseStringArrayJson", () => {
+  test("parses string array", () => {
+    expect(parseStringArrayJson('["admin","editor"]')).toEqual(["admin", "editor"]);
+  });
+
+  test("returns fallback on invalid JSON", () => {
+    expect(parseStringArrayJson("{bad", ["guest"])).toEqual(["guest"]);
+  });
+
+  test("returns fallback when JSON is not a string array", () => {
+    expect(parseStringArrayJson("[1,2]", [])).toEqual([]);
+  });
+});

package/src/utils/__tests__/safe-json.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { parseJsonOrThrow, parseJsonSafe } from "../safe-json";
+
+describe("parseJsonSafe", () => {
+  test("parses valid JSON", () => {
+    expect(parseJsonSafe<{ a: number } | null>('{"a":1}', null)).toEqual({ a: 1 });
+  });
+
+  test("returns fallback on invalid JSON", () => {
+    expect(parseJsonSafe("{bad", { ok: false })).toEqual({ ok: false });
+  });
+});
+
+describe("parseJsonOrThrow", () => {
+  test("parses valid JSON", () => {
+    expect(parseJsonOrThrow<number[]>("[1,2]", "test")).toEqual([1, 2]);
+  });
+
+  test("throws with context on invalid JSON", () => {
+    expect(() => parseJsonOrThrow("{", "roles column")).toThrow(/Invalid JSON in roles column/);
+  });
+});

package/src/utils/case.ts

@@ -0,0 +1,6 @@
+// Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
+// names. Kebab is canonical for new multi-word identifiers; camelCase remains
+// supported for shipped code.
+export function toSnakeCase(str: string): string {
+  return str.replace(/-/g, "_").replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}

package/src/utils/index.ts

@@ -1,5 +1,8 @@
 export { assertUnreachable } from "./assert";
+export { toSnakeCase } from "./case";
 export { readPositiveIntEnv } from "./env-parse";
 export { generateId } from "./ids";
+export { isPlainObject } from "./is-plain-object";
+export { parseStringArrayJson } from "./parse-string-array-json";
 export { parseJsonOrThrow, parseJsonSafe } from "./safe-json";
 export { parseRoles } from "./serialization";

package/src/utils/is-plain-object.ts

@@ -0,0 +1,4 @@
+/** Non-null object that is not an array — shared guard for deep-merge and AST extractors. */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/utils/parse-string-array-json.ts

@@ -0,0 +1,14 @@
+import { parseJsonSafe } from "./safe-json";
+
+/** Parses a JSON-encoded string array from DB/cache columns; returns fallback on invalid input. */
+export function parseStringArrayJson(
+  raw: string,
+  fallback: readonly string[] = [],
+): readonly string[] {
+  const parsed = parseJsonSafe<unknown>(raw, null);
+  if (parsed === null) return fallback;
+  if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
+    return parsed;
+  }
+  return fallback;
+}