@cosmicdrift/kumiko-framework 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.37.0",
+  "version": "0.39.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.38.0",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -177,3 +177,82 @@ describe("auth-routes cookie behaviour on /auth/switch-tenant", () => {
     expect(newAuth?.value).not.toBe(validToken); // new jwt
   });
 });
+
+// cookieDomain — Bug-Bash-2 Wave I (Auth auf Marketing-Host): Login auf
+// dem Apex muss eine Session setzen die admin.<domain> mitliest. Ohne
+// Option bleibt das Cookie host-only (kein Domain-Attribut).
+describe("auth-routes cookieDomain", () => {
+  async function login(app: Hono): Promise<Response> {
+    return app.request("/api/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: "a@b.c", password: "pw" }),
+    });
+  }
+
+  test("ohne cookieDomain: kein Domain-Attribut auf den Cookies", async () => {
+    const { app } = await buildApp();
+    const res = await login(app);
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).not.toMatch(/Domain=/i);
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).not.toMatch(/Domain=/i);
+  });
+
+  test("login: cookieDomain setzt Domain auf BEIDEN Cookies", async () => {
+    const { app } = await buildApp({ cookieDomain: "example.eu" });
+    const res = await login(app);
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
+  });
+
+  test("switch-tenant: rotierte Cookies tragen das Domain-Attribut", async () => {
+    const otherTenant = TestUsers.otherTenant;
+    const dispatcher = createStubDispatcher({
+      async query(type: string, _payload: unknown, _user: SessionUser): Promise<unknown> {
+        if (type === "tenant:query:memberships") {
+          return [
+            {
+              userId: TestUsers.user.id,
+              tenantId: otherTenant.tenantId,
+              roles: otherTenant.roles,
+            },
+          ];
+        }
+        return [];
+      },
+    });
+    const { app, validToken } = await buildApp({ cookieDomain: "example.eu" }, dispatcher);
+    const res = await app.request("/api/auth/switch-tenant", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${validToken}`,
+      },
+      body: JSON.stringify({ tenantId: otherTenant.tenantId }),
+    });
+    expect(res.status).toBe(200);
+    expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
+  });
+
+  test("logout löscht beide Varianten: mit Domain UND host-only", async () => {
+    const { app, validToken } = await buildApp({ cookieDomain: "example.eu" });
+    const res = await app.request("/api/auth/logout", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${validToken}` },
+    });
+    expect(res.status).toBe(200);
+    const raw = res.headers.getSetCookie();
+    const authDeletes = raw.filter(
+      (c) => c.startsWith(`${AUTH_COOKIE_NAME}=`) && /Max-Age=0/i.test(c),
+    );
+    const csrfDeletes = raw.filter(
+      (c) => c.startsWith(`${CSRF_COOKIE_NAME}=`) && /Max-Age=0/i.test(c),
+    );
+    // Host-only-Bestand (vor cookieDomain gesetzt) + aktuelle Domain-
+    // Variante — beide müssen invalidiert werden, sonst wirkt der Logout
+    // auf dem alten Cookie nicht.
+    expect(authDeletes.some((c) => /Domain=example\.eu/i.test(c))).toBe(true);
+    expect(authDeletes.some((c) => !/Domain=/i.test(c))).toBe(true);
+    expect(csrfDeletes.some((c) => /Domain=example\.eu/i.test(c))).toBe(true);
+    expect(csrfDeletes.some((c) => !/Domain=/i.test(c))).toBe(true);
+  });
+});

package/src/api/auth-routes.ts

@@ -40,7 +40,12 @@ function cookieSecure(): boolean {
 // state that would trip the csrf-middleware on every retry.
 function setAuthCookies(
   c: Context,
-  opts: { token: string; csrfToken: string; sameSite: "lax" | "strict" },
+  opts: {
+    token: string;
+    csrfToken: string;
+    sameSite: "lax" | "strict";
+    domain?: string | undefined;
+  },
 ): void {
   const sameSite = opts.sameSite === "strict" ? "Strict" : "Lax";
   const common = {
@@ -48,6 +53,7 @@ function setAuthCookies(
     sameSite,
     path: "/",
     maxAge: JWT_TTL_SECONDS,
+    ...(opts.domain !== undefined && { domain: opts.domain }),
   } as const;
 
   setCookie(c, AUTH_COOKIE_NAME, opts.token, { ...common, httpOnly: true });
@@ -56,9 +62,17 @@ function setAuthCookies(
   setCookie(c, CSRF_COOKIE_NAME, opts.csrfToken, { ...common, httpOnly: false });
 }
 
-function clearAuthCookies(c: Context): void {
+function clearAuthCookies(c: Context, domain?: string): void {
+  // Beide Varianten löschen: mit Domain (aktuelle Cookies) UND host-only
+  // (Bestand aus der Zeit vor cookieDomain) — sonst bleibt nach einem
+  // Deploy mit neu gesetztem cookieDomain der alte Cookie liegen und der
+  // Logout wirkt nur scheinbar.
   deleteCookie(c, AUTH_COOKIE_NAME, { path: "/" });
   deleteCookie(c, CSRF_COOKIE_NAME, { path: "/" });
+  if (domain !== undefined) {
+    deleteCookie(c, AUTH_COOKIE_NAME, { path: "/", domain });
+    deleteCookie(c, CSRF_COOKIE_NAME, { path: "/", domain });
+  }
 }
 
 // Body schema for POST /auth/login. Enforced BEFORE rate-limit so that a
@@ -237,6 +251,14 @@ export type AuthRoutesConfig = {
   // The framework always pairs the cookie with a Double-Submit CSRF token
   // (see csrf-middleware), so "lax" is defense-in-depth, not defense-alone.
   cookieSameSite?: "lax" | "strict";
+  // Domain attribute for both auth cookies. Unset (default) = host-only
+  // cookie, scoped to the exact host that served the response. Set it to
+  // the registrable parent domain (e.g. "example.eu") when login and app
+  // live on DIFFERENT subdomains (login on apex, app on admin.) — the
+  // browser then sends the session to every subdomain. Careful: that
+  // includes ALL subdomains (tenant pages, previews); widen the scope
+  // only when the cross-subdomain session is actually required.
+  cookieDomain?: string;
 };
 
 export type PasswordResetConfig = {
@@ -402,6 +424,7 @@ export function createAuthRoutes(
   // "lax" keeps email deep-links (invite, magic-link, notification click)
   // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
   const cookieSameSite = config.cookieSameSite ?? "lax";
+  const cookieDomain = config.cookieDomain;
 
   // POST /auth/login — public endpoint (bypasses auth middleware via PUBLIC_API_PATHS).
   // The configured login handler authenticates and returns a SessionUser;
@@ -481,7 +504,7 @@ export function createAuthRoutes(
       // ignores Set-Cookie keeps working without any server-side knowledge
       // of which transport this client will use next.
       const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite });
+      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
 
       return c.json({
         isSuccess: true,
@@ -588,7 +611,7 @@ export function createAuthRoutes(
 
       const token = await jwt.sign(sessionForJwt);
       const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite });
+      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
 
       return c.json({
         isSuccess: true,
@@ -671,7 +694,7 @@ export function createAuthRoutes(
       }
       const token = await jwt.sign(sessionForJwt);
       const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite });
+      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
       return c.json({
         isSuccess: true,
         token,
@@ -711,7 +734,7 @@ export function createAuthRoutes(
       }
       const token = await jwt.sign(sessionForJwt);
       const csrfToken = generateToken();
-      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite });
+      setAuthCookies(c, { token, csrfToken, sameSite: cookieSameSite, domain: cookieDomain });
       return c.json({
         isSuccess: true,
         token,
@@ -737,7 +760,7 @@ export function createAuthRoutes(
     }
     // Clear cookies on the cookie-transport path. Idempotent — clearing a
     // missing cookie is a no-op, so bearer-only clients aren't affected.
-    clearAuthCookies(c);
+    clearAuthCookies(c, cookieDomain);
     return c.json({ isSuccess: true });
   });
 
@@ -876,7 +899,12 @@ export function createAuthRoutes(
     // the new token in the body below — their Set-Cookie is a no-op
     // because the browser never sent cookies.
     const csrfToken = generateToken();
-    setAuthCookies(c, { token: newToken, csrfToken, sameSite: cookieSameSite });
+    setAuthCookies(c, {
+      token: newToken,
+      csrfToken,
+      sameSite: cookieSameSite,
+      domain: cookieDomain,
+    });
 
     return c.json({ token: newToken, tenantId: targetTenantId, roles: mergedRoles });
   });

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", () => {