@cosmicdrift/kumiko-framework 0.307.0 → 0.309.0

package/src/stack/test-stack.ts

@@ -4,7 +4,6 @@ import type { JwtHelper } from "../api/jwt";
 import { buildServer } from "../api/server";
 import { createSseBroker, type SseBroker } from "../api/sse-broker";
 import type { PgClient } from "../db/connection";
-import { extractTableInfo } from "../db/query";
 import { validateOwnershipBoot } from "../engine/boot-validator/ownership";
 import { createRegistry } from "../engine/registry";
 import type { AppContext, FeatureDefinition, JobRunIn, Registry, TenantId } from "../engine/types";
@@ -181,6 +180,10 @@ export type TestStackOptions = {
    *  out (e.g. 60_000) so the polling timer can't land inside the
    *  assertion window and mask a dead subscription — see E.4 (#2042). */
   eventDispatcherPollIntervalMs?: number;
+  /** Opt out of auto-created r.entity() tables for callers that create/migrate
+   *  them themselves. Default true — false pushes only projection/MSP/
+   *  storeTable sources, same as before fw#3102. */
+  entityTables?: boolean;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -215,68 +218,72 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
     createTestRedis(),
   ]);
 
-  // Every ES-entity writes events via createEventStoreExecutor in the
-  // feature's write handlers. Auto-create the events table so every
-  // setupTestStack call is ready for writes without needing a manual
-  // createEventsTable().
-  await createEventsTable(testDb.db);
-  // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
-  // loadAggregate's default-skip. Idempotent, so production boot running
-  // the same call is fine.
-  await createArchivedStreamsTable(testDb.db);
+  // Any throw in this DDL region must still drop the just-created ephemeral
+  // DB/Redis — the caller never gets the stack object back to call
+  // cleanup() itself (same "leaked ephemeral DB" failure class as the later
+  // try/catch below, but for setup that runs before that try starts).
+  try {
+    // Every ES-entity writes events via createEventStoreExecutor in the
+    // feature's write handlers. Auto-create the events table so every
+    // setupTestStack call is ready for writes without needing a manual
+    // createEventsTable().
+    await createEventsTable(testDb.db);
+    // Archive-stream metadata — needed by ctx.appendEvent's archive guard and
+    // loadAggregate's default-skip. Idempotent, so production boot running
+    // the same call is fine.
+    await createArchivedStreamsTable(testDb.db);
 
-  // Framework state for projection rebuild/status + event-consumer cursors.
-  // Idempotent — production boot flows run the same calls.
-  const { createProjectionStateTable, createEventConsumerStateTable } = await import("../pipeline");
-  await createProjectionStateTable(testDb.db);
-  await createEventConsumerStateTable(testDb.db);
+    // Framework state for projection rebuild/status + event-consumer cursors.
+    // Idempotent — production boot flows run the same calls.
+    const { createProjectionStateTable, createEventConsumerStateTable } = await import(
+      "../pipeline"
+    );
+    await createProjectionStateTable(testDb.db);
+    await createEventConsumerStateTable(testDb.db);
 
-  // Files support: when a provider is registered, the fileRefs table must
-  // exist before the first upload. Skipped when no provider — the table
-  // stays off tenant test DBs that never touch files.
-  if (options.files) {
-    const { fileRefsTable } = await import("../files");
-    await unsafePushTables(testDb.db, { fileRefsTable });
-  }
-
-  // Projection-/MSP-/raw-tables: the executor (or async dispatcher) writes
-  // into them as soon as the first matching event flows, so the DDL must
-  // exist before setupTestStack returns. The source list is shared with
-  // collectTableMetas (`kumiko schema generate`) — divergence between the
-  // two was exactly the #255 prod-crash. Two registrations backed by the
-  // same physical table (e.g. an alternative apply-shape for the same
-  // read-model in a test feature) are deduped by table reference so we
-  // emit only one CREATE TABLE per physical table.
-  const { enumerateFeatureTableSources } = await import("../db/feature-table-sources");
-  const projectionTables: Record<string, unknown> = {};
-  // Dedup by NAME, matching collectTableMetas — by-reference alone let two
-  // distinct table objects with the same name slip through as a double
-  // CREATE TABLE while schema-generate emitted only one meta (silent
-  // test-vs-schema divergence).
-  const seenTableNames = new Set<string>();
-  for (const feature of options.features) {
-    for (const { table, origin } of enumerateFeatureTableSources(feature)) {
-      const name = extractTableInfo(table).name;
-      if (seenTableNames.has(name)) continue;
-      seenTableNames.add(name);
-      projectionTables[origin] = table;
+    // Files support: when a provider is registered, the fileRefs table must
+    // exist before the first upload. Skipped when no provider — the table
+    // stays off tenant test DBs that never touch files.
+    if (options.files) {
+      const { fileRefsTable } = await import("../files");
+      await unsafePushTables(testDb.db, { fileRefsTable });
     }
-  }
-  if (Object.keys(projectionTables).length > 0) {
-    // unsafePushTables emits raw CREATE TABLE — fine for ephemeral test DBs but
-    // collides on re-boot against a persistent DB whose projection tables
-    // were created during a previous run. Filter out the ones that already
-    // exist so the re-boot doesn't fail on duplicate CREATE TABLE.
+
+    // Same table list as `kumiko schema generate` (collectTableMetas) — divergence
+    // was the #255 prod-crash and the #3102 missing r.entity() tables.
+    const { collectTableMetas } = await import("../db/collect-table-metas");
     const { tableExists } = await import("../db/schema-inspection");
+    let metas = collectTableMetas(options.features);
+    if (options.entityTables === false) {
+      const { enumerateFeatureTableSources } = await import("../db/feature-table-sources");
+      const { extractTableInfo } = await import("../db/query");
+      const nonEntityNames = new Set(
+        options.features.flatMap((f) =>
+          enumerateFeatureTableSources(f).map((s) => extractTableInfo(s.table).name),
+        ),
+      );
+      metas = metas.filter((m) => nonEntityNames.has(m.tableName));
+    }
     const missing: Record<string, unknown> = {};
-    for (const [key, tbl] of Object.entries(projectionTables)) {
-      const physical = extractTableInfo(tbl).name;
-      if (await tableExists(testDb.db, `public.${physical}`)) continue;
-      missing[key] = tbl;
+    for (const meta of metas) {
+      if (await tableExists(testDb.db, `public.${meta.tableName}`)) continue;
+      missing[meta.tableName] = meta;
     }
     if (Object.keys(missing).length > 0) {
       await unsafePushTables(testDb.db, missing);
     }
+  } catch (error) {
+    try {
+      await testDb.cleanup();
+    } catch {
+      // ignore — `error` is the one that matters
+    }
+    try {
+      await testRedis.cleanup();
+    } catch {
+      // ignore — `error` is the one that matters
+    }
+    throw error;
   }
 
   const searchAdapter = createInMemorySearchAdapter();

package/src/testing/__tests__/e2e-generator.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { z } from "zod";
+import * as z from "zod";
 import {
   createBooleanField,
   createDateField,

package/src/testing/__tests__/real-providers.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { requireRealProviders } from "../real-providers";
+import { isRealProviderRun, REAL_PROVIDERS_ENV, requireRealProviders } from "../real-providers";
 
 const CI = "CI";
 const FLAG = "KUMIKO_REAL_PROVIDERS";
@@ -52,3 +52,11 @@ describe("requireRealProviders", () => {
     expect(() => requireRealProviders()).not.toThrow();
   });
 });
+
+describe("isRealProviderRun", () => {
+  test("reads the exported flag name from an explicit env map, defaulting to process.env", () => {
+    expect(isRealProviderRun({ [REAL_PROVIDERS_ENV]: "1" })).toBe(true);
+    expect(isRealProviderRun({ [REAL_PROVIDERS_ENV]: "true" })).toBe(false);
+    expect(isRealProviderRun({})).toBe(false);
+  });
+});

package/src/testing/e2e-generator.ts

@@ -24,7 +24,7 @@
 // "not supported yet" — wir füllen nach, wenn ein echter Caller es braucht.
 // Fake-komplexe-Werte würden nur False-Green-Tests produzieren.
 
-import type { z } from "zod";
+import type * as z from "zod";
 import {
   type EntityDefinition,
   type EntityEditScreenDefinition,

package/src/testing/index.ts

@@ -45,7 +45,7 @@ export {
   createRecordingProvider,
   type RecordingProvider,
 } from "./observability-recorder";
-export { requireRealProviders } from "./real-providers";
+export { isRealProviderRun, REAL_PROVIDERS_ENV, requireRealProviders } from "./real-providers";
 export { deleteRows, seedRow, seedRows, updateRows } from "./seed";
 export {
   sharedItemEntity,

package/src/testing/real-providers.ts

@@ -1,4 +1,4 @@
-const REAL_PROVIDERS_FLAG = "KUMIKO_REAL_PROVIDERS";
+export const REAL_PROVIDERS_ENV = "KUMIKO_REAL_PROVIDERS";
 const CI_FLAG = "CI";
 
 function isCi(): boolean {
@@ -6,15 +6,23 @@ function isCi(): boolean {
   return ci !== undefined && ci !== "" && ci !== "0" && ci.toLowerCase() !== "false";
 }
 
+// Apps and the e2e/bunfig templates gate real-provider runs on this same
+// check instead of re-reading KUMIKO_REAL_PROVIDERS themselves.
+export function isRealProviderRun(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  return env[REAL_PROVIDERS_ENV] === "1";
+}
+
 export function requireRealProviders(): void {
   if (isCi()) {
     throw new Error(
-      `Real-provider tests never run in CI (CI is set). Run them locally with ${REAL_PROVIDERS_FLAG}=1 via the test:real / e2e:real script.`,
+      `Real-provider tests never run in CI (CI is set). Run them locally with ${REAL_PROVIDERS_ENV}=1 via the test:real / e2e:real script.`,
     );
   }
-  if (process.env[REAL_PROVIDERS_FLAG] !== "1") {
+  if (!isRealProviderRun()) {
     throw new Error(
-      `Real-provider test needs ${REAL_PROVIDERS_FLAG}=1 (an API key alone never enables it). Run it via the test:real / e2e:real script.`,
+      `Real-provider test needs ${REAL_PROVIDERS_ENV}=1 (an API key alone never enables it). Run it via the test:real / e2e:real script.`,
     );
   }
 }