@cosmicdrift/kumiko-framework 0.63.0 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.63.0",
+  "version": "0.65.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.57.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.65.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/reference-data.integration.test.ts

@@ -1,9 +1,10 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
-import { integer, table as pgTable, serial, text } from "../db/dialect";
+import { integer, table as pgTable, serial, text, timestamp } from "../db/dialect";
 import { selectMany } from "../db/query";
 import { seedReferenceData } from "../db/reference-data";
 import type { ReferenceDataDef } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types";
 import { unsafePushTables } from "../stack";
 import { ensureTemporalPolyfill } from "../time/polyfill";
 
@@ -22,6 +23,14 @@ const statusTable = pgTable("ref_statuses", {
   sortOrder: integer("sort_order").default(0),
 });
 
+const scopedTable = pgTable("ref_scoped", {
+  key: text("key").primaryKey(),
+  label: text("label").notNull(),
+  tenantId: text("tenant_id"),
+  version: integer("version"),
+  insertedAt: timestamp("inserted_at"),
+});
+
 // --- Test state ---
 
 let testDb: BunTestDb;
@@ -29,7 +38,7 @@ let testDb: BunTestDb;
 beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
-  await unsafePushTables(testDb.db, { countryTable, statusTable });
+  await unsafePushTables(testDb.db, { countryTable, statusTable, scopedTable });
 });
 
 afterAll(async () => {
@@ -48,9 +57,10 @@ async function readStatuses() {
 }
 
 describe("seedReferenceData", () => {
-  const tables = new Map<string, typeof countryTable | typeof statusTable>([
+  const tables = new Map<string, typeof countryTable | typeof statusTable | typeof scopedTable>([
     ["country", countryTable],
     ["status", statusTable],
+    ["scoped", scopedTable],
   ]);
 
   test("inserts initial reference data", async () => {
@@ -197,6 +207,28 @@ describe("seedReferenceData", () => {
     expect(result).toEqual({ inserted: 0, updated: 0 });
   });
 
+  test("stamps framework columns (tenantId/version/insertedAt) on insert when the table has them", async () => {
+    const defs: ReferenceDataDef[] = [
+      {
+        entityName: "scoped",
+        data: [{ key: "k1", label: "One" }],
+      },
+    ];
+
+    const result = await seedReferenceData(defs, tables, testDb.db);
+    expect(result).toEqual({ inserted: 1, updated: 0 });
+
+    const rows = await selectMany(testDb.db, scopedTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      key: "k1",
+      label: "One",
+      tenantId: SYSTEM_TENANT_ID,
+      version: 1,
+    });
+    expect(rows[0]?.insertedAt).toBeTruthy();
+  });
+
   test("skips empty data arrays", async () => {
     const defs: ReferenceDataDef[] = [
       {

package/src/__tests__/schema-cli-rebuild.integration.test.ts

@@ -0,0 +1,176 @@
+// `schema apply` rebuilds the projections a freshly applied migration touched —
+// the projection-rebuild step the per-app bin/kumiko.ts files duplicate today,
+// folded into runSchemaCli behind the optional `features` option.
+//
+// Honest wiring test: seed one event, apply a migration carrying a hand-written
+// .rebuild.json marker, assert the projection was actually replayed (the row
+// reconstructed from the event log — not just a log line).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeRebuildMarker } from "../db";
+import { integer, table as pgTable, uuid } from "../db/dialect";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { asRawClient, selectMany } from "../db/query";
+import { buildEntityTable } from "../db/table-builder";
+import { createTenantDb, type TenantDb } from "../db/tenant-db";
+import { createEntity, createTextField, defineApply, defineFeature } from "../engine";
+import type { ProjectionDefinition } from "../engine/types";
+import { createEventsTable } from "../event-store";
+import { createProjectionStateTable } from "../pipeline";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../stack";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const itemEntity = createEntity({
+  table: "read_apply_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+  softDelete: true,
+});
+const itemTable = buildEntityTable("apply-item", itemEntity);
+
+const COUNTER_TABLE = "read_apply_items_per_group";
+const counterTable = pgTable(COUNTER_TABLE, {
+  groupId: uuid("group_id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  itemCount: integer("item_count").notNull().default(0),
+});
+
+type ItemCreated = { groupId: string };
+const counterProjection: ProjectionDefinition = {
+  name: "items-per-group",
+  source: "apply-item",
+  table: counterTable,
+  apply: {
+    "apply-item.created": defineApply<ItemCreated>(async (event, tx) => {
+      await asRawClient(tx).unsafe(
+        `INSERT INTO "${COUNTER_TABLE}" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1) ON CONFLICT (group_id) DO UPDATE SET item_count = ${COUNTER_TABLE}.item_count + 1`,
+        [event.payload.groupId, event.tenantId],
+      );
+    }),
+  },
+};
+
+const feature = defineFeature("applyrebuildtest", (r) => {
+  r.entity("apply-item", itemEntity);
+  r.projection(counterProjection);
+});
+
+const admin = TestUsers.admin;
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "apply-item" });
+
+function captureOut(): { out: SchemaCliOut; log: string[]; err: string[] } {
+  const log: string[] = [];
+  const err: string[] = [];
+  return { out: { log: (l) => log.push(l), err: (l) => err.push(l) }, log, err };
+}
+
+// Writes an app workspace with a single trivial migration + an optional
+// hand-written rebuild marker, bypassing the generate→managed-diff machinery
+// (tested elsewhere) to exercise only the apply→marker→rebuild wiring.
+function writeMigration(migrationId: string, rebuildTables: readonly string[] | null): string {
+  const appCwd = join(
+    tmpdir(),
+    `kumiko-apply-rebuild-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  const migrationsDir = join(appCwd, "kumiko/migrations");
+  mkdirSync(migrationsDir, { recursive: true });
+  writeFileSync(join(migrationsDir, `${migrationId}.sql`), "SELECT 1;\n");
+  if (rebuildTables) {
+    writeRebuildMarker(migrationsDir, `${migrationId}.sql`, rebuildTables);
+  }
+  return appCwd;
+}
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, itemEntity, "apply-item");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  await unsafePushTables(testDb.db, { applyItemsPerGroup: counterTable });
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+  prevDbUrl = process.env["DATABASE_URL"];
+  const baseUrl =
+    process.env["TEST_DATABASE_URL"] ??
+    process.env["DATABASE_URL"] ??
+    "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+  process.env["DATABASE_URL"] = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+});
+
+afterAll(async () => {
+  if (prevDbUrl !== undefined) process.env["DATABASE_URL"] = prevDbUrl;
+  else delete process.env["DATABASE_URL"];
+  await testDb?.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_apply_items, ${COUNTER_TABLE}, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function counterFor(groupId: string): Promise<number | undefined> {
+  const [row] = await selectMany(testDb.db, counterTable, { groupId });
+  return row?.itemCount;
+}
+
+describe("runSchemaCli apply — projection rebuild", () => {
+  const group = "00000000-0000-4000-8000-0000000000a1";
+
+  test("with features: applied migration's marker triggers a real rebuild", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+    // Pipeline not wired on this append → projection is empty until rebuild.
+    expect(await counterFor(group)).toBeUndefined();
+
+    const appCwd = writeMigration("0001_touch_counter", [COUNTER_TABLE]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Rebuild 1 Projection");
+    expect(cap.log.join("\n")).toContain("(1 events");
+    // The row was reconstructed from the seeded event — not a no-op loop.
+    expect(await counterFor(group)).toBe(1);
+  });
+
+  test("without features: marker present but no rebuild (dev path)", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0002_touch_counter", [COUNTER_TABLE]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out);
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    // No rebuild ran → projection stays empty.
+    expect(await counterFor(group)).toBeUndefined();
+  });
+
+  test("with features but no marker: apply succeeds, no rebuild", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0003_no_marker", null);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    expect(await counterFor(group)).toBeUndefined();
+  });
+});

package/src/__tests__/schema-cli.integration.test.ts

@@ -147,6 +147,65 @@ describe("runSchemaCli — no-DB paths", () => {
   });
 });
 
+describe("runSchemaCli — validate (static CI gate, no DB)", () => {
+  let appCwd: string;
+  beforeEach(() => {
+    appCwd = freshAppCwd();
+  });
+
+  test("missing schema.ts exits 1", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("kumiko/schema.ts");
+  });
+
+  test("entity with no generated migration → schema drift, exit 1 (the tags-class bug)", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("schema drift");
+    expect(cap.err.join("\n")).toContain("read_widgets");
+    expect(cap.err.join("\n")).toContain("kumiko-schema generate");
+  });
+
+  test("after generate (in sync) → exit 0, reports migrations match", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("migrations match");
+  });
+
+  test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("boot: skipped");
+  });
+
+  test("FEATURES present (empty) → validateBoot runs and passes", async () => {
+    writeFileSync(
+      join(appCwd, "kumiko/schema.ts"),
+      `export const ENTITY_METAS = [
+  { tableName: "read_widgets", source: "unmanaged", indexes: [],
+    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }] },
+];
+export const FEATURES = [];
+`,
+    );
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("feature configuration is valid");
+  });
+});
+
 describe("runSchemaCli — DB-backed paths", () => {
   let testDb: BunTestDb;
   let dbUrl: string;

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

@@ -259,6 +259,10 @@ describe("auth-routes cookieDomain", () => {
     });
     expect(res.status).toBe(200);
     expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
+    // Das CSRF-Cookie wird via denselben common-Optionen rotiert wie das Auth-
+    // Cookie. Ohne Domain-Attribut bliebe es host-only neben dem Domain-Auth-
+    // Cookie → der Double-Submit-Check läse umgebungsabhängig das falsche.
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
   });
 
   test("logout löscht beide Varianten: mit Domain UND host-only", async () => {

package/src/db/__tests__/assert-exists-in.integration.test.ts

@@ -0,0 +1,104 @@
+// Coverage-Lücke (9% u+i, 0 Tests): assertExistsIn ist der referenzielle
+// Existenz-Check (FK-Ersatz im ES-Modell), den Write-Handler vor dem Schreiben
+// nutzen. Gibt er faelschlich null (= existiert) zurueck, schreibt der Handler
+// eine dangling/cross-tenant Reference. Schwerpunkt: Tenant-Isolation.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertMany } from "../../bun-db";
+import { createEntity, createTextField } from "../../engine";
+import { NotFoundError } from "../../errors";
+import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
+import { assertExistsIn } from "../assert-exists-in";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const orderEntity = createEntity({
+  table: "ax_orders",
+  fields: { name: createTextField({ required: true }) },
+});
+const orderTable = buildEntityTable("order", orderEntity);
+
+const tenantA = testTenantId(71);
+const tenantB = testTenantId(72);
+const ID_A = "11111111-1111-4111-8111-1111110000a1";
+const ID_B = "22222222-2222-4222-8222-2222220000b2";
+const MISSING = "99999999-9999-4999-8999-999999990000";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+  await insertMany(stack.db, orderTable, [
+    { id: ID_A, tenantId: tenantA, name: "A-Order" },
+    { id: ID_B, tenantId: tenantB, name: "B-Order" },
+  ]);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("assertExistsIn — DbConnection + explizite tenantId", () => {
+  test("existierende Row → null", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+    });
+    expect(r).toBeNull();
+  });
+
+  test("fehlende Row → NotFoundError", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: MISSING,
+      tenantId: tenantA,
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+
+  test("ISOLATION: fremder Tenant → NotFoundError (existiert, aber nicht im Scope)", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_B, // gehört tenantB
+      tenantId: tenantA,
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});
+
+describe("assertExistsIn — TenantDb auto-filter", () => {
+  test("eigene Row → null", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    expect(await assertExistsIn(dbA, orderTable, { field: "id", value: ID_A })).toBeNull();
+  });
+
+  test("ISOLATION: fremde Row via TenantDb → NotFoundError", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    const r = await assertExistsIn(dbA, orderTable, { field: "id", value: ID_B });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});
+
+describe("assertExistsIn — Fehler-Benennung + where", () => {
+  test("expliziter entityName override gewinnt", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: MISSING,
+      tenantId: tenantA,
+      entityName: "Bestellung",
+    });
+    expect(r?.message).toContain("Bestellung");
+  });
+
+  test("zusätzliches where narrowt → existierende id + falscher name = NotFound", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+      where: { name: "nope" },
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});

package/src/db/__tests__/eagerload.integration.test.ts

@@ -0,0 +1,148 @@
+// Coverage-Lücke (0 Test, 12% u+i): Server-Side-Eagerload für Reference-Felder.
+// Schwerpunkt: Tenant-Isolation — ein Cross-Tenant-Ref darf NIE aufgelöst
+// werden (TenantDb filtert), sonst leakt eagerload fremde Rows nach _refs.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertMany } from "../../bun-db";
+import { createEntity, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
+import {
+  collectReferenceFields,
+  type EagerloadedRow,
+  enrichRowWithReferences,
+  enrichWithReferences,
+} from "../eagerload";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const authorEntity = createEntity({
+  table: "el_authors",
+  fields: { name: createTextField({ required: true }) },
+});
+const postEntity = createEntity({
+  table: "el_posts",
+  fields: {
+    title: createTextField({ required: true }),
+    author: { type: "reference", entity: "author" },
+    tags: { type: "reference", entity: "author", multiple: true },
+  },
+});
+const authorTable = buildEntityTable("author", authorEntity);
+
+const resolve = (name: string): EntityDefinition | undefined =>
+  name === "author" ? authorEntity : undefined;
+
+const tenantA = testTenantId(91);
+const tenantB = testTenantId(92);
+
+const A1 = "11111111-1111-4111-8111-111111111111";
+const A2 = "22222222-2222-4222-8222-222222222222";
+const BX = "33333333-3333-4333-8333-333333333333";
+const NOPE = "55555555-5555-4555-8555-555555555555";
+
+// _refs-Werte sind dynamisch gekeyt → bracket-access; Helper kapseln den Cast.
+const single = (r: EagerloadedRow | undefined, f: string) =>
+  r?._refs?.[f] as Record<string, unknown> | undefined;
+const many = (r: EagerloadedRow | undefined, f: string) =>
+  r?._refs?.[f] as ReadonlyArray<Record<string, unknown>> | undefined;
+
+let stack: TestStack;
+let dbA: ReturnType<typeof createTenantDb>;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, authorEntity);
+  await unsafeCreateEntityTable(stack.db, postEntity);
+  dbA = createTenantDb(stack.db, tenantA, "tenant");
+
+  await insertMany(stack.db, authorTable, [
+    { id: A1, tenantId: tenantA, name: "Ada" },
+    { id: A2, tenantId: tenantA, name: "Linus" },
+    { id: BX, tenantId: tenantB, name: "Foreign" },
+  ]);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function enrichA(row: Record<string, unknown>): Promise<EagerloadedRow | undefined> {
+  const [out] = (await enrichWithReferences([row], postEntity, resolve, dbA)) as EagerloadedRow[];
+  return out;
+}
+
+describe("collectReferenceFields", () => {
+  test("extrahiert reference-Felder, parst cross-feature-Prefix, flaggt multiple", () => {
+    const e = createEntity({
+      table: "x",
+      fields: {
+        title: createTextField(),
+        author: { type: "reference", entity: "users:user" },
+        tags: { type: "reference", entity: "tag", multiple: true },
+      },
+    });
+    expect(collectReferenceFields(e)).toEqual([
+      { fieldName: "author", refEntityName: "user", multiple: false },
+      { fieldName: "tags", refEntityName: "tag", multiple: true },
+    ]);
+  });
+
+  test("keine reference-Felder → leer", () => {
+    expect(collectReferenceFields(authorEntity)).toEqual([]);
+  });
+});
+
+describe("enrichWithReferences", () => {
+  test("löst single-ref zur Row auf", async () => {
+    const row = await enrichA({ id: "p1", author: A1 });
+    expect(single(row, "author")?.["name"]).toBe("Ada");
+  });
+
+  test("löst multiple-ref zu einem Array in Reihenfolge auf", async () => {
+    const row = await enrichA({ id: "p1", tags: [A2, A1] });
+    expect(many(row, "tags")?.map((t) => t["name"])).toEqual(["Linus", "Ada"]);
+  });
+
+  test("null/leerer ref-Wert → _refs[field] undefined", async () => {
+    const row = await enrichA({ id: "p1", author: null });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("TENANT-ISOLATION: cross-tenant-ref wird NICHT aufgelöst", async () => {
+    // bx gehört tenantB; dbA ist auf tenantA gescoped → der Lookup filtert
+    // ihn raus, _refs bleibt undefined (Renderer fällt auf die UUID zurück).
+    const row = await enrichA({ id: "p1", author: BX });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("dangling UUID (kein Row) → undefined, kein Crash", async () => {
+    const row = await enrichA({ id: "p1", author: NOPE });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("unbekannte ref-Entity (resolve→undefined) → undefined, kein Crash", async () => {
+    const [row] = (await enrichWithReferences(
+      [{ id: "p1", author: A1 }],
+      postEntity,
+      () => undefined,
+      dbA,
+    )) as EagerloadedRow[];
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("keine reference-Felder → flache Kopie ohne Lookup", async () => {
+    const out = await enrichWithReferences([{ id: "x1", name: "n" }], authorEntity, resolve, dbA);
+    expect(out).toEqual([{ id: "x1", name: "n" }]);
+  });
+
+  test("enrichRowWithReferences (single-row-Variante) stempelt _refs", async () => {
+    const row = (await enrichRowWithReferences(
+      { id: "p1", author: A1 },
+      postEntity,
+      resolve,
+      dbA,
+    )) as EagerloadedRow;
+    expect(single(row, "author")?.["name"]).toBe("Ada");
+  });
+});

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

@@ -930,12 +930,8 @@ export function createEventStoreExecutor(
       const tableInfo = extractTableInfo(table);
       const rows = rawRows.map((r) => coerceRow(rehydrateCompoundTypes(r, entity), tableInfo));
 
-      // list rows (and their cache entries) carry the READ-ROW version, not the
-      // authoritative stream version detail() applies. That is intentional —
-      // it's display-only and must never be used as an optimistic-lock base;
-      // edit flows reload via detail(), which reconciles the stream version.
-      // Sourcing a lock base from a list row would reintroduce the #336
-      // version_conflict. (#336)
+      // list rows carry the READ-ROW version (display-only), never an optimistic-lock
+      // base — edit flows reload via detail(), which reconciles the stream version.
       if (entityCache && entityName && rows.length > 0) {
         await entityCache.mset(
           user.tenantId,

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

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { validateBoot } from "../boot-validator";
 import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE } from "../build-config-feature-schema";
@@ -199,3 +199,51 @@ describe("buildAppSchema — Settings-Hub inline placement", () => {
     expect(() => validateBoot([typo])).toThrow(/references nav "config:nav:audience-systemm"/);
   });
 });
+
+describe("buildAppSchema — dangling audience-ref dev-warning (#408/3)", () => {
+  // billing registriert nur system+tenant-Keys → audience-user wird NIE
+  // generiert. Eine Workspace, die config:nav:audience-user referenziert, boot't
+  // (Boot-Validator exempt't die Audience-QNs), aber der Eintrag rendert
+  // unsichtbar — der Dev muss eine Warnung sehen, nicht still nichts.
+  function warnsFor(scopes: string[]): string[] {
+    const prevEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildAppSchema(createRegistry([placingShell(...scopes), billing]));
+      return warn.mock.calls.map((c) => String(c[0]));
+    } finally {
+      warn.mockRestore();
+      if (prevEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = prevEnv;
+      }
+    }
+  }
+
+  test("referencing a never-generated audience warns (dangling-ref)", () => {
+    const messages = warnsFor(["user"]);
+    expect(
+      messages.some((m) => m.includes("config:nav:audience-user") && m.includes("nie generiert")),
+    ).toBe(true);
+  });
+
+  test("referencing a generated audience does NOT trigger the dangling warning", () => {
+    // audience-tenant IS generated (billing has tenant keys) → kein dangling.
+    const messages = warnsFor(["tenant"]);
+    expect(messages.some((m) => m.includes("nie generiert"))).toBe(false);
+  });
+
+  test("authoring warnings are suppressed under NODE_ENV=test — no CI-log noise (#408/1)", () => {
+    // bun:test setzt NODE_ENV=test; eine un-platzierte Audience (tenant bleibt
+    // bei placingShell("system") übrig) darf KEIN console.warn ins Log spülen.
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildAppSchema(createRegistry([placingShell("system"), billing]));
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});