@cosmicdrift/kumiko-framework 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.37.0",
+  "version": "0.38.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.35.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.37.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

package/src/api/routes.ts

@@ -1,11 +1,10 @@
 import { type Context, Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import {
-  InternalError,
-  isKumikoError,
   type KumikoError,
   reraiseAsKumikoError,
   serializeError,
+  toKumikoError,
   ValidationError,
 } from "../errors";
 import type { Dispatcher } from "../pipeline/dispatcher";
@@ -115,11 +114,7 @@ function jsonResponse(c: Context, body: unknown, status: ContentfulStatusCode =
   return c.body(stringifyJson(body), status, { "Content-Type": "application/json" });
 }
 
-function toKumiko(e: unknown): KumikoError {
-  if (isKumikoError(e)) return e;
-  if (e instanceof Error) return new InternalError({ cause: e });
-  return new InternalError({ message: String(e) });
-}
+const toKumiko = toKumikoError;
 
 // For /write + /batch: keep the isSuccess flag so clients can flip on a single
 // boolean (mirrors the success shape). The actual error body is the

package/src/api/server.ts

@@ -635,7 +635,7 @@ export function buildServer(options: ServerOptions): KumikoServer {
 // the yes/no answer for the boot check.
 function registryDeclaresFileFields(registry: Registry): boolean {
   for (const feature of registry.features.values()) {
-    for (const entity of Object.values(feature.entities)) {
+    for (const entity of Object.values(feature.entities ?? {})) {
       for (const field of Object.values(entity.fields)) {
         if (isFileField(field)) return true;
       }

package/src/bun-db/connection.ts

@@ -66,6 +66,7 @@ export function createBunDbConnection(
   };
 }
 
+// guard:dup-ok — ENV-Reader für BunDB (gibt { db, listenClient } zurück), nicht verwandt mit redisClientOptionsFromEnv
 export function bunDbConnectionOptionsFromEnv(
   env: Readonly<Record<string, string | undefined>> = process.env,
 ): BunDbConnectionOptions {

package/src/bun-db/index.ts

@@ -11,7 +11,6 @@ export type {
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection";
 export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query";
 export {
-  asEntityTableMeta,
   asRawClient,
   countWhere,
   type DeleteManyBatchedOptions,

package/src/db/__tests__/schema-migration.integration.test.ts

@@ -40,7 +40,7 @@ afterAll(async () => {
 async function applySchema(features: readonly FeatureDefinition[]): Promise<void> {
   const tables: Record<string, unknown> = {};
   for (const feature of features) {
-    for (const [entityName, entity] of Object.entries(feature.entities)) {
+    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
       tables[entityName] = buildEntityTable(entityName, entity);
     }
   }

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
-import { asEntityTableMeta } from "../../bun-db/query";
 import { createEntity } from "../../engine/factories";
+import { sql } from "../dialect";
 import type { ColumnMeta, IndexMeta } from "../entity-table-meta";
 import { buildEntityTableMeta } from "../entity-table-meta";
+import { asEntityTableMeta } from "../query";
 import { buildEntityTable } from "../table-builder";
 
 // Lock-step-Guard: buildEntityTable (Runtime-/Test-Stack-Pfad, Meta am
@@ -60,3 +61,43 @@ describe("buildEntityTable ↔ buildEntityTableMeta lock-step", () => {
     expect(cols.get("active")?.defaultSql).toBe("true");
   });
 });
+
+// Zweite Probe: softDelete + explizite Indexes (unique, partial, multi-col).
+// Diese Pfade generieren zusätzliche Spalten (deleted_at/_by) bzw. Index-
+// Metas — Drift hier blieb von der defaults-Probe oben unentdeckt.
+const entityWithSoftDeleteAndIndexes = createEntity({
+  table: "read_lockstep_probe_sd",
+  fields: {
+    title: { type: "text", required: true },
+    ownerId: { type: "text", required: true },
+    status: { type: "select", options: ["open", "done"], required: true, default: "open" },
+  },
+  softDelete: true,
+  indexes: [
+    { columns: ["ownerId"] },
+    { columns: ["ownerId", "status"], unique: true },
+    { columns: ["title"], unique: true, where: sql`status = 'open'`, name: "open_title_unique" },
+  ],
+});
+
+describe("lock-step — softDelete + explizite Indexes", () => {
+  const fromBuilder = asEntityTableMeta(
+    buildEntityTable("lockstepProbeSd", entityWithSoftDeleteAndIndexes),
+  );
+  const fromMeta = buildEntityTableMeta("lockstepProbeSd", entityWithSoftDeleteAndIndexes);
+
+  test("identical columns inkl. softDelete-Spalten", () => {
+    expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
+      byName<ColumnMeta>(fromMeta.columns),
+    );
+    const names = (fromBuilder?.columns ?? []).map((c) => c.name);
+    expect(names).toContain("deleted_at");
+  });
+
+  test("identical indexes inkl. unique/partial/multi-col", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+    expect((fromBuilder?.indexes ?? []).length).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -79,3 +79,37 @@ describe("tenant-db WHERE merge — caller cannot override tenant scope", () =>
     expect(captured[0]?.values).toContain(own);
   });
 });
+
+describe("tenant-db WHERE merge — narrowing within the enforced scope", () => {
+  const SYSTEM = "00000000-0000-4000-8000-000000000000";
+
+  test("where.tenantId = own narrows to own only (excludes SYSTEM reference rows)", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { tenantId: own });
+
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).not.toContain(SYSTEM);
+  });
+
+  test("where.tenantId = [own, SYSTEM] keeps both", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { tenantId: [own, SYSTEM] });
+
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).toContain(SYSTEM);
+  });
+
+  test("mixed [own, foreign] drops the foreign id, keeps own", async () => {
+    const captured: Captured[] = [];
+    const tdb = createTenantDb(recordingDb(captured), own);
+
+    await tdb.selectMany(table, { tenantId: [own, foreign] });
+
+    expect(captured[0]?.values).toContain(own);
+    expect(captured[0]?.values).not.toContain(foreign);
+  });
+});

package/src/db/collect-table-metas.ts

@@ -6,10 +6,10 @@
 // read_subscriptions) nie in Migrations landeten und der erste Prod-Write
 // crashte (#255).
 
-import { asEntityTableMeta } from "../bun-db/query";
 import type { FeatureDefinition } from "../engine/types";
 import { buildEntityTableMeta, type EntityTableMeta } from "./entity-table-meta";
 import { enumerateFeatureTableSources } from "./feature-table-sources";
+import { asEntityTableMeta } from "./query";
 
 function canonicalColumnsKey(meta: EntityTableMeta): string {
   // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
@@ -34,7 +34,7 @@ export function collectTableMetas(
   // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
   // Verhalten (gleiche Reihenfolge, gleiche buildEntityTableMeta-Optionen).
   for (const feature of features) {
-    for (const [name, ent] of Object.entries(feature.entities)) {
+    for (const [name, ent] of Object.entries(feature.entities ?? {})) {
       const meta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
       metas.push(meta);
       byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });

package/src/db/connection.ts

@@ -17,6 +17,7 @@ export type PgClient = ReturnType<typeof postgres>;
 export type PgListenClient = ReturnType<typeof postgres>;
 
 // Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
+// guard:dup-ok — andere Layer als createPgConnection (gibt DbConnection zurück, nicht postgres-Instanz)
 export function createDbConnection(
   url: string,
   options: import("./api").DbConnectionOptions = {},

package/src/db/dialect.ts

@@ -272,9 +272,9 @@ export function instant(
 }
 
 // moneyAmount kept as a customType-style API but produces a bigint column.
-// bigintJsMode "bigint" — money cents must round-trip as JS bigint (lock-step
-// with entity-table-meta's money rendering; without it bun-db reads the
-// column as number and loses precision past 2^53).
+// bigintJsMode "bigint" — entity-table-meta renders money as bigint, and the
+// table-builder↔meta lockstep guard fails on a number-mode column. (Precision
+// past 2^53 is the underlying motivation, not the immediate breakage.)
 export const moneyAmount = (name: string): ColumnBuilder<number> =>
   buildColumn(name, "bigint", { bigintJsMode: "bigint" }) as ColumnBuilder<number>;
 
@@ -482,6 +482,19 @@ export function table<TCols extends ColumnMap>(
   return out;
 }
 
+/** Reads the `kumiko:schema:Name` symbol from a table object.
+ *  Throws with `context` in the message so callers don't have to duplicate the guard. */
+export function extractTableName(table: unknown, context = "extractTableName"): string {
+  if (typeof table !== "object" || table === null) {
+    throw new Error(`${context}: table is not an object`);
+  }
+  const name = (table as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  if (typeof name !== "string") {
+    throw new Error(`${context}: table missing kumiko:schema:Name symbol`);
+  }
+  return name;
+}
+
 // Helper used by `instantToDriver` callers in legacy code — kept identical
 // to the previous behaviour. The native dialect handles parse/serialize
 // implicitly via the Bun driver; this function is a defensive coerce at

package/src/db/event-store-executor.ts

@@ -16,6 +16,7 @@ import type {
   FieldDefinition,
   SaveContext,
   SessionUser,
+  TenantId,
   WriteResult,
 } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers";
@@ -29,10 +30,12 @@ import {
   writeFailure,
 } from "../errors";
 import {
+  ArchivedStreamError,
   append,
   type EventMetadata,
   VersionConflictError as EventStoreVersionConflict,
   getStreamVersion,
+  isStreamArchived,
 } from "../event-store";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
@@ -291,6 +294,26 @@ export function createEventStoreExecutor(
     return rehydrateCompoundTypes(row as DbRow, entity);
   }
 
+  // Archive guard for the CRUD write paths. Archived streams are read-only —
+  // ctx.appendEvent (append-event-core) already enforces this, but the
+  // executor appends directly via append() and getStreamVersion() ignores
+  // the archive flag, so without this check a PATCH/DELETE on an archived
+  // entity would silently land an event and break the read-only contract
+  // (loadAggregate returns [] for the same stream). Throws ArchivedStreamError
+  // to mirror the appendEvent path exactly — same 500 + rolled-back tx.
+  // Creates skip this: a fresh UUID can't be archived, and a deterministic-id
+  // re-create onto an archived stream collides on the unique index →
+  // version_conflict, which already blocks the write.
+  async function assertStreamWritable(
+    db: TenantDb,
+    id: EntityId,
+    tenantId: TenantId,
+  ): Promise<void> {
+    if (await isStreamArchived(db.raw, tenantId, String(id))) {
+      throw new ArchivedStreamError(tenantId, String(id));
+    }
+  }
+
   // SELECT a row by id with the ownership clause applied at the DB layer.
   // Detail() uses this both on cold path and as a cache-revalidation probe.
   async function loadWithOwnership(
@@ -521,6 +544,8 @@ export function createEventStoreExecutor(
         );
       }
 
+      await assertStreamWritable(db, payload.id, user.tenantId);
+
       // Stream-version is authoritative, not row.version. `ctx.appendEvent`
       // can bump the stream between CRUD writes (domain event on the same
       // aggregate); a stale row.version here would make the next CRUD write
@@ -655,6 +680,8 @@ export function createEventStoreExecutor(
         );
       }
 
+      await assertStreamWritable(db, payload.id, user.tenantId);
+
       // Stream-version authoritative (see update() for rationale).
       const currentVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
 
@@ -730,6 +757,8 @@ export function createEventStoreExecutor(
         );
       }
 
+      await assertStreamWritable(db, payload.id, user.tenantId);
+
       // Stream-version authoritative (see update() for rationale).
       const currentVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
       // Restore carries the soft-deleted snapshot as `previous` — mirror of

package/src/db/index.ts

@@ -11,6 +11,7 @@ export {
   bigint,
   bigserial,
   boolean,
+  extractTableName,
   index,
   instant,
   instantToDriver,

package/src/db/query.ts

@@ -2,6 +2,7 @@
 // Alle Consumer importieren von hier, nicht direkt aus bun-db/.
 export {
   type AnyDb,
+  asEntityTableMeta,
   asRawClient,
   coerceRow,
   countWhere,

package/src/db/tenant-db.ts

@@ -133,12 +133,22 @@ export function createTenantDb(
 
   // Reads see own-tenant rows + reference data (tenantId === SYSTEM_TENANT_ID).
   // Writes never touch reference rows — those are system-mode only.
-  // The tenant filter is spread LAST so a caller-supplied `where.tenantId`
-  // cannot override the enforced scope — overriding it would be a
-  // tenant-isolation bypass.
+  // A caller-supplied `where.tenantId` may only NARROW the enforced scope
+  // (e.g. exclude SYSTEM reference rows at the DB instead of post-filtering
+  // after a limit). Values outside the scope are dropped; if nothing valid
+  // remains, the full enforced scope applies — widening is never possible.
   function readWhere(table: Table, where?: WhereObject): WhereObject | undefined {
     if (!hasTenantColumn(table) || mode === "system") return where;
-    const tenantFilter: WhereObject = { tenantId: [tenantId, SYSTEM_TENANT_ID] };
+    const allowed = [tenantId, SYSTEM_TENANT_ID];
+    const requested = where?.["tenantId"];
+    if (requested !== undefined) {
+      const requestedList = Array.isArray(requested) ? requested : [requested];
+      const narrowed = requestedList.filter(
+        (t): t is string => typeof t === "string" && allowed.includes(t),
+      );
+      return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
+    }
+    const tenantFilter: WhereObject = { tenantId: allowed };
     return where ? { ...where, ...tenantFilter } : tenantFilter;
   }
 

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

@@ -8,7 +8,7 @@
 //      im Browser-Bundle.
 
 import { describe, expect, test } from "bun:test";
-import { buildAppSchema } from "../build-app-schema";
+import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
 import type { EntityDefinition } from "../types/fields";
@@ -207,8 +207,9 @@ describe("buildAppSchema", () => {
     const app = buildAppSchema(createRegistry([f]));
     const roundTripped = JSON.parse(JSON.stringify(app));
 
-    // Vollständige deep-equality — kein Silent-Drop durch JSON.stringify
-    expect(roundTripped).toEqual(app);
+    // toStrictEqual: toEqual ignoriert undefined-Props und würde einen
+    // Silent-Drop durch JSON.stringify genau NICHT fangen.
+    expect(roundTripped).toStrictEqual(app);
 
     // Explizit: FormatSpec-Felder landen unverändert an
     const screen = roundTripped.features[0]?.screens[0];
@@ -234,3 +235,30 @@ describe("buildAppSchema", () => {
     expect(actions?.find((a) => a.id === "always")?.visible).toBe(true);
   });
 });
+
+describe("findNonJsonSafePath", () => {
+  test("findet eine Funktion ausserhalb von PlatformComponent-Slots mit Pfad", () => {
+    const schema = { features: [{ label: () => "nope" }] };
+    expect(findNonJsonSafePath(schema, "schema")).toBe("schema.features[0].label");
+  });
+
+  test("PlatformComponent-Slots ({ react, native }) sind opak — Komponenten-Funktionen erlaubt", () => {
+    const schema = {
+      features: [{ screens: [{ id: "s1", component: { react: () => null } }] }],
+    };
+    expect(findNonJsonSafePath(schema, "schema")).toBeNull();
+  });
+
+  test("faengt undefined, bigint und Klassen-Instanzen", () => {
+    expect(findNonJsonSafePath({ a: undefined }, "schema")).toBe("schema.a");
+    expect(findNonJsonSafePath({ a: 1n }, "schema")).toBe("schema.a");
+    expect(findNonJsonSafePath({ a: new Map() }, "schema")).toBe("schema.a");
+    expect(findNonJsonSafePath({ a: Number.NaN }, "schema")).toBe("schema.a");
+  });
+
+  test("normales JSON-Schema passiert ohne Befund", () => {
+    expect(
+      findNonJsonSafePath({ features: [{ name: "x", count: 3, on: true, opt: null }] }, "schema"),
+    ).toBeNull();
+  });
+});

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

@@ -65,9 +65,9 @@ describe("defineFeature", () => {
       );
     });
 
-    expect(feature.entities["user"]).toBeDefined();
-    expect(feature.entities["user"]?.table).toBe("Users");
-    expect(feature.entities["user"]?.fields["email"]?.type).toBe("text");
+    expect(feature.entities?.["user"]).toBeDefined();
+    expect(feature.entities?.["user"]?.table).toBe("Users");
+    expect(feature.entities?.["user"]?.fields["email"]?.type).toBe("text");
   });
 
   test("collects write handlers with inferred types", () => {

package/src/engine/__tests__/hook-phases.test.ts

@@ -22,7 +22,7 @@ describe("HookPhases defaults", () => {
       r.hook("postSave", "thing:create", noopSave);
     });
 
-    const entry = feature.hooks.postSave["thing:create"];
+    const entry = feature.hooks?.postSave?.["thing:create"];
     expect(entry).toHaveLength(1);
     expect(entry?.[0]?.phase).toBe(HookPhases.afterCommit);
   });
@@ -36,7 +36,7 @@ describe("HookPhases defaults", () => {
       r.hook("postSave", "thing:create", noopSave, { phase: HookPhases.inTransaction });
     });
 
-    const entry = feature.hooks.postSave["thing:create"];
+    const entry = feature.hooks?.postSave?.["thing:create"];
     expect(entry?.[0]?.phase).toBe(HookPhases.inTransaction);
   });
 
@@ -55,7 +55,7 @@ describe("HookPhases defaults", () => {
       r.hook("preDelete", "thing:delete", async () => undefined);
     });
 
-    const entry = feature.hooks.preDelete["thing:delete"];
+    const entry = feature.hooks?.preDelete?.["thing:delete"];
     expect(entry?.[0]?.phase).toBe(HookPhases.inTransaction);
   });
 
@@ -66,8 +66,8 @@ describe("HookPhases defaults", () => {
       r.entityHook("preDelete", thing, async () => undefined);
     });
 
-    expect(feature.entityHooks.postSave["thing"]?.[0]?.phase).toBe(HookPhases.afterCommit);
-    expect(feature.entityHooks.preDelete["thing"]?.[0]?.phase).toBe(HookPhases.inTransaction);
+    expect(feature.entityHooks?.postSave?.["thing"]?.[0]?.phase).toBe(HookPhases.afterCommit);
+    expect(feature.entityHooks?.preDelete?.["thing"]?.[0]?.phase).toBe(HookPhases.inTransaction);
   });
 });
 

package/src/engine/__tests__/lifecycle-hooks.test.ts

@@ -15,7 +15,7 @@ describe("lifecycle hook registration", () => {
       });
     });
 
-    expect(Object.keys(feature.hooks.preSave)).toContain("user");
+    expect(Object.keys(feature.hooks?.preSave ?? {})).toContain("user");
   });
 
   test("postSave hooks are registered", () => {
@@ -23,7 +23,7 @@ describe("lifecycle hook registration", () => {
       r.hook("postSave", "user", async () => {});
     });
 
-    expect(Object.keys(feature.hooks.postSave)).toContain("user");
+    expect(Object.keys(feature.hooks?.postSave ?? {})).toContain("user");
   });
 
   test("preDelete hooks are registered", () => {
@@ -31,7 +31,7 @@ describe("lifecycle hook registration", () => {
       r.hook("preDelete", "user", async () => {});
     });
 
-    expect(Object.keys(feature.hooks.preDelete)).toContain("user");
+    expect(Object.keys(feature.hooks?.preDelete ?? {})).toContain("user");
   });
 
   test("postDelete hooks are registered", () => {
@@ -39,7 +39,7 @@ describe("lifecycle hook registration", () => {
       r.hook("postDelete", "user", async () => {});
     });
 
-    expect(Object.keys(feature.hooks.postDelete)).toContain("user");
+    expect(Object.keys(feature.hooks?.postDelete ?? {})).toContain("user");
   });
 
   test("multiple hooks on same entity are collected in order", () => {
@@ -48,7 +48,7 @@ describe("lifecycle hook registration", () => {
       r.hook("preSave", "user", async (changes) => changes);
     });
 
-    const hooks = feature.hooks.preSave["user"];
+    const hooks = feature.hooks?.preSave?.["user"];
     expect(hooks).toHaveLength(2);
   });
 
@@ -59,9 +59,9 @@ describe("lifecycle hook registration", () => {
       r.hook("postSave", "user", async () => {});
     });
 
-    expect(feature.hooks.validation["userForm"]).toBeDefined();
-    expect(feature.hooks.preSave["user"]).toHaveLength(1);
-    expect(feature.hooks.postSave["user"]).toHaveLength(1);
+    expect(feature.hooks?.validation?.["userForm"]).toBeDefined();
+    expect(feature.hooks?.preSave?.["user"]).toHaveLength(1);
+    expect(feature.hooks?.postSave?.["user"]).toHaveLength(1);
   });
 });
 

package/src/engine/__tests__/post-query-hook.test.ts

@@ -30,7 +30,7 @@ describe("postQuery hook registration", () => {
 
     // feature.hooks.postQuery is keyed by raw handler-name (qualification
     // happens at registry-merge time).
-    const entry = feature.hooks.postQuery["thing:list"];
+    const entry = feature.hooks?.postQuery?.["thing:list"];
     expect(entry).toHaveLength(1);
     expect(entry?.[0]?.featureName).toBe("test");
   });
@@ -41,7 +41,7 @@ describe("postQuery hook registration", () => {
       r.entityHook("postQuery", thing, noop);
     });
 
-    const entry = feature.entityHooks.postQuery["thing"];
+    const entry = feature.entityHooks?.postQuery?.["thing"];
     expect(entry).toHaveLength(1);
     expect(entry?.[0]?.featureName).toBe("test");
   });
@@ -56,7 +56,7 @@ describe("postQuery hook registration", () => {
       r.entityHook("postQuery", thing, hookB);
     });
 
-    expect(feature.entityHooks.postQuery["thing"]).toHaveLength(2);
+    expect(feature.entityHooks?.postQuery?.["thing"]).toHaveLength(2);
   });
 });
 

package/src/engine/__tests__/validation-hooks.test.ts

@@ -14,8 +14,8 @@ describe("validation hooks", () => {
       });
     });
 
-    expect(feature.hooks["validation"]).toBeDefined();
-    expect(feature.hooks["validation"]?.["user:create"]).toBeDefined();
+    expect(feature.hooks?.["validation"]).toBeDefined();
+    expect(feature.hooks?.["validation"]?.["user:create"]).toBeDefined();
   });
 
   test("runValidation returns null when valid", () => {

package/src/engine/boot-validator/entity-handler.ts

@@ -145,7 +145,7 @@ export function validateMultiStreamProjections(feature: FeatureDefinition): void
 // ohne das `fooTz`-Feld zu deklarieren. Der `locatedTimestamp(name)` Helper
 // macht das Pair atomar — wer ihn nutzt, fliegt nicht durch diesen Validator.
 export function validateLocatedTimestamps(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     const fields = entity.fields;
     for (const [fieldName, field] of Object.entries(fields)) {
       if (field.type !== "timestamp" || field.locatedBy === undefined) continue;
@@ -182,7 +182,7 @@ export function validateLocatedTimestamps(feature: FeatureDefinition): void {
 // (`["tenantId", "key"]` ist sinnvoll), nur die rein-tenantId-Single-
 // column-Form blockieren wir.
 export function validateEntityIndexes(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     if (!entity.indexes) continue;
     const fieldNames = new Set(Object.keys(entity.fields));
     for (const [idx, def] of entity.indexes.entries()) {
@@ -242,7 +242,7 @@ export function validateEntityIndexes(feature: FeatureDefinition): void {
 
 export function validateEncryptedFields(feature: FeatureDefinition): boolean {
   let found = false;
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       // Beide string-typed fields können encrypted sein. Die
       // searchable/sortable-Konflikt-Checks gelten nur für `text`
@@ -271,7 +271,7 @@ export function validateEncryptedFields(feature: FeatureDefinition): boolean {
 // --- File field detection ---
 
 export function validateFileFields(feature: FeatureDefinition): boolean {
-  for (const entity of Object.values(feature.entities)) {
+  for (const entity of Object.values(feature.entities ?? {})) {
     for (const field of Object.values(entity.fields)) {
       if (FILE_FIELD_TYPES.has(field.type)) return true;
     }
@@ -296,7 +296,7 @@ export function validateReferenceFields(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
 ): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type !== "reference") continue;
 
@@ -310,9 +310,12 @@ export function validateReferenceFields(
             `Known features: ${knownFeatures}.`,
         );
       }
-      const targetEntity = targetFeature.entities[target.entityName];
+      const targetEntity = targetFeature.entities?.[target.entityName];
       if (!targetEntity) {
-        const known = Object.keys(targetFeature.entities).sort().join(", ") || "(none)";
+        const known =
+          Object.keys(targetFeature.entities ?? {})
+            .sort()
+            .join(", ") || "(none)";
         const where =
           target.featureName === feature.name
             ? `in this feature`
@@ -354,7 +357,7 @@ export function validateReferenceFields(
 }
 
 export function validateEmbeddedFields(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type !== "embedded") continue;
 
@@ -382,7 +385,7 @@ export function validateEmbeddedFields(feature: FeatureDefinition): void {
 // auch im Zod-Schema bei runtime fehlschlagen, der Boot-Catch ist nur
 // die früheste Stelle für klare Fehlermeldungen.
 export function validateMultiSelectFields(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     for (const [fieldName, field] of Object.entries(entity.fields)) {
       if (field.type !== "multiSelect") continue;
 
@@ -409,7 +412,7 @@ export function validateMultiSelectFields(feature: FeatureDefinition): void {
 // --- Transition validation ---
 
 export function validateTransitions(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     if (!entity.transitions) continue;
 
     for (const [fieldName, transitionMap] of Object.entries(entity.transitions)) {
@@ -451,7 +454,7 @@ export function validateTransitions(feature: FeatureDefinition): void {
 // --- extendSchema column collision detection ---
 
 export function validateExtendSchemaCollisions(feature: FeatureDefinition): void {
-  for (const [entityName, entity] of Object.entries(feature.entities)) {
+  for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     const existingFields = new Set(Object.keys(entity.fields));
 
     // Check if any registered extension would collide with existing fields