@cosmicdrift/kumiko-framework 0.28.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.28.0",
+  "version": "0.31.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/api/auth-routes.ts

@@ -115,6 +115,10 @@ type MembershipRow = {
   userId: string;
   tenantId: TenantId;
   roles: string[];
+  /** Display-Name des Tenants — liefert die membershipQuery seit dem
+   *  tenant-switcher-Fix mit; optional für ältere App-eigene Queries. */
+  tenantName?: string;
+  tenantKey?: string;
 };
 
 // Guest identity used for unauthenticated calls (e.g. login). The "all" role
@@ -754,6 +758,8 @@ export function createAuthRoutes(
         tenants: memberships.map((m) => ({
           tenantId: m.tenantId,
           roles: m.roles,
+          ...(m.tenantName !== undefined && { name: m.tenantName }),
+          ...(m.tenantKey !== undefined && { key: m.tenantKey }),
         })),
         activeTenantId: user.tenantId,
       });

package/src/bun-db/index.ts

@@ -9,14 +9,16 @@ export type {
   PgListenClient,
 } from "./connection";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection";
-export type { SelectOptions, WhereObject, WhereOperator, WhereValue } from "./query";
+export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query";
 export {
+  asEntityTableMeta,
   asRawClient,
   countWhere,
   type DeleteManyBatchedOptions,
   type DeleteManyBatchedResult,
   deleteMany,
   deleteManyBatched,
+  extractTableInfo,
   fetchOne,
   type IncrementCounterOptions,
   incrementCounter,

package/src/bun-db/query.ts

@@ -60,7 +60,7 @@ function isEntityTableMeta(v: unknown): v is EntityTableMeta {
 //    to a column-handle shadowing a meta key.
 //  - buildEntityTableMeta / defineUnmanagedTable return a plain meta with no
 //    handle-spread, so its structural shape is itself unshadowable.
-function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
+export function asEntityTableMeta(table: unknown): EntityTableMeta | undefined {
   if (table === null || typeof table !== "object") return undefined;
   const fromSymbol = (table as Record<symbol, unknown>)[KUMIKO_META_SYMBOL];
   if (isEntityTableMeta(fromSymbol)) return fromSymbol;

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

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../../engine/define-feature";
+import { createEntity, createTextField } from "../../engine/factories";
+import { collectTableMetas } from "../collect-table-metas";
+import { integer, type SchemaTable, table, text, uuid } from "../dialect";
+import { defineUnmanagedTable } from "../entity-table-meta";
+import { buildEntityTable } from "../table-builder";
+
+function exampleEntity() {
+  return createEntity({
+    table: "read_units",
+    fields: { name: createTextField() },
+  });
+}
+
+const counterTable = table("read_unit_counters", {
+  id: uuid("id").primaryKey(),
+  count: integer("count").notNull().default(0),
+}) as unknown as SchemaTable;
+
+describe("collectTableMetas (#255)", () => {
+  test("collects entity, projection, MSP and rawTable tables — same sources as the test-stack auto-push", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "unit-counters",
+        source: "unit",
+        table: counterTable,
+        apply: {},
+      });
+      r.multiStreamProjection({
+        name: "unit-audit",
+        table: table("read_unit_audit", {
+          id: uuid("id").primaryKey(),
+          detail: text("detail"),
+        }) as unknown as SchemaTable,
+        apply: { "unit.created": async () => {} },
+      });
+      // side-effect-only MSP — no table, must be skipped without throwing
+      r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
+      r.rawTable(
+        "cache",
+        table("unit_cache", {
+          id: uuid("id").primaryKey(),
+        }) as unknown as SchemaTable,
+        { reason: "test fixture" },
+      );
+      r.unmanagedTable(
+        defineUnmanagedTable({
+          tableName: "read_unit_log",
+          columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
+        }),
+        { reason: "test fixture" },
+      );
+    });
+
+    const names = collectTableMetas([feature]).map((m) => m.tableName);
+    expect(names).toContain("read_units"); // entity
+    expect(names).toContain("read_unit_counters"); // r.projection
+    expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
+    expect(names).toContain("unit_cache"); // r.rawTable
+    expect(names).toContain("read_unit_log"); // r.unmanagedTable
+    expect(names).toHaveLength(5);
+  });
+
+  test("dedupes a projection that materializes into an entity table — entity meta wins", () => {
+    const entity = exampleEntity();
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", entity);
+      r.projection({
+        name: "unit-alt",
+        source: "unit",
+        table: buildEntityTable("unit", entity) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    const metas = collectTableMetas([feature]);
+    expect(metas.filter((m) => m.tableName === "read_units")).toHaveLength(1);
+  });
+
+  test("throws when two table-bearing registrations declare the same table with diverging columns", () => {
+    const a = defineFeature("feat-a", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "conflict-a",
+        source: "unit",
+        table: table("read_conflict", {
+          id: uuid("id").primaryKey(),
+          count: integer("count").notNull(),
+        }) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+    const b = defineFeature("feat-b", (r) => {
+      r.entity("thing", exampleEntity());
+      r.projection({
+        name: "conflict-b",
+        source: "thing",
+        table: table("read_conflict", {
+          id: uuid("id").primaryKey(),
+          label: text("label").notNull(),
+        }) as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    expect(() => collectTableMetas([a, b])).toThrow(/read_conflict.*diverging/);
+  });
+
+  test("throws when a projection table carries no EntityTableMeta", () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("unit", exampleEntity());
+      r.projection({
+        name: "broken",
+        source: "unit",
+        // System-Grenze: absichtlich kaputtes table-Objekt — der Cast
+        // simuliert eine fremd-konstruierte Tabelle ohne kumiko-Meta.
+        table: { tableName: "read_broken" } as unknown as SchemaTable,
+        apply: {},
+      });
+    });
+
+    expect(() => collectTableMetas([feature])).toThrow(/no EntityTableMeta/);
+  });
+});

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

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import { asEntityTableMeta } from "../../bun-db/query";
+import { createEntity } from "../../engine/factories";
+import type { ColumnMeta, IndexMeta } from "../entity-table-meta";
+import { buildEntityTableMeta } from "../entity-table-meta";
+import { buildEntityTable } from "../table-builder";
+
+// Lock-step-Guard: buildEntityTable (Runtime-/Test-Stack-Pfad, Meta am
+// KUMIKO_META_SYMBOL) und buildEntityTableMeta (Migrations-Pfad) müssen
+// für dieselbe EntityDefinition identische Spalten + Indexes produzieren.
+// Drift hier = Migration und Prod-Tabelle (bzw. collectTableMetas-Output)
+// gehen auseinander — gefunden als #255-Follow-up: select/number/bigInt
+// verloren ihre deklarierten defaults auf dem Builder-Pfad.
+
+const entityWithDefaults = createEntity({
+  table: "read_lockstep_probe",
+  fields: {
+    title: { type: "text", required: true, default: "untitled" },
+    active: { type: "boolean", default: true },
+    status: { type: "select", options: ["open", "done"], required: true, default: "open" },
+    tags: { type: "multiSelect", options: ["a", "b"] },
+    attempt: { type: "number", required: true, default: 1 },
+    bytes: { type: "bigInt", default: 0 },
+    price: { type: "money" },
+    meta: { type: "embedded", fields: {} },
+    startedAt: { type: "timestamp", required: true },
+  },
+});
+
+function byName<T extends { name: string }>(items: readonly T[]): readonly T[] {
+  return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+describe("buildEntityTable ↔ buildEntityTableMeta lock-step", () => {
+  const fromBuilder = asEntityTableMeta(buildEntityTable("lockstepProbe", entityWithDefaults));
+  const fromMeta = buildEntityTableMeta("lockstepProbe", entityWithDefaults);
+
+  test("builder table carries an EntityTableMeta", () => {
+    expect(fromBuilder).toBeDefined();
+  });
+
+  test("identical columns (incl. declared defaults)", () => {
+    expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
+      byName<ColumnMeta>(fromMeta.columns),
+    );
+  });
+
+  test("identical indexes", () => {
+    expect(byName<IndexMeta>(fromBuilder?.indexes ?? [])).toEqual(
+      byName<IndexMeta>(fromMeta.indexes),
+    );
+  });
+
+  test("declared defaults survive the builder path", () => {
+    const cols = new Map((fromBuilder?.columns ?? []).map((c) => [c.name, c]));
+    expect(cols.get("status")?.defaultSql).toBe("'open'");
+    expect(cols.get("attempt")?.defaultSql).toBe("1");
+    expect(cols.get("bytes")?.defaultSql).toBe("0");
+    expect(cols.get("title")?.defaultSql).toBe("'untitled'");
+    expect(cols.get("active")?.defaultSql).toBe("true");
+  });
+});

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

@@ -0,0 +1,81 @@
+// collectTableMetas — kanonische ENTITY_METAS-Quelle für `kumiko schema
+// generate`. Erfasst dieselben Tabellen-Quellen wie der setupTestStack-
+// auto-push (entities, unmanagedTables, projections, multiStreamProjections,
+// rawTables) — die frühere Template-Variante sammelte nur entities +
+// unmanagedTables, wodurch projection-only-Tabellen (z.B. billing-foundation
+// 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";
+
+function canonicalColumnsKey(meta: EntityTableMeta): string {
+  // Spalten-Identität unabhängig von Deklarations-Reihenfolge und
+  // Objekt-Key-Order. Indexes bleiben außen vor: eine Projection-Table
+  // (buildEntityTable ohne relations) trägt legitim weniger FK-Indexes
+  // als das Entity-Meta derselben Tabelle.
+  return [...meta.columns]
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(
+      (c) =>
+        `${c.name}|${c.pgType}|${c.notNull}|${c.defaultSql ?? ""}|${c.primaryKey ?? false}|${c.identity ?? false}|${c.bigintJsMode ?? ""}`,
+    )
+    .join("\n");
+}
+
+export function collectTableMetas(
+  features: readonly FeatureDefinition[],
+): readonly EntityTableMeta[] {
+  const metas: EntityTableMeta[] = [];
+  const byName = new Map<string, { meta: EntityTableMeta; origin: string }>();
+
+  // 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)) {
+      const meta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      metas.push(meta);
+      byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
+    }
+    for (const entry of Object.values(feature.unmanagedTables)) {
+      metas.push(entry.meta);
+      byName.set(entry.meta.tableName, {
+        meta: entry.meta,
+        origin: `unmanagedTable "${entry.name}" (${feature.name})`,
+      });
+    }
+  }
+
+  // Pass 2: table-tragende Registrierungen. Zwei Pässe, damit eine Entity-
+  // Tabelle aus Feature B gegen eine gleichnamige Projection-Table aus
+  // Feature A gewinnt — Entity-Metas sind die reichere Quelle (FK-Indexes
+  // aus relations).
+  for (const feature of features) {
+    for (const { table, origin } of enumerateFeatureTableSources(feature)) {
+      const meta = asEntityTableMeta(table);
+      if (!meta) {
+        throw new Error(
+          `collectTableMetas: ${origin} carries no EntityTableMeta — ` +
+            "build the table via table() / buildEntityTable / defineUnmanagedTable.",
+        );
+      }
+      const existing = byName.get(meta.tableName);
+      if (existing) {
+        if (canonicalColumnsKey(existing.meta) !== canonicalColumnsKey(meta)) {
+          throw new Error(
+            `collectTableMetas: table "${meta.tableName}" is declared with diverging ` +
+              `columns by ${origin} and ${existing.origin}. Align the column ` +
+              "definitions or rename one of the tables.",
+          );
+        }
+        continue;
+      }
+      metas.push(meta);
+      byName.set(meta.tableName, { meta, origin });
+    }
+  }
+
+  return metas;
+}

package/src/db/dialect.ts

@@ -272,8 +272,11 @@ 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).
 export const moneyAmount = (name: string): ColumnBuilder<number> =>
-  buildColumn(name, "bigint") as ColumnBuilder<number>;
+  buildColumn(name, "bigint", { bigintJsMode: "bigint" }) as ColumnBuilder<number>;
 
 // ---- Index + primaryKey helpers ----
 

package/src/db/feature-table-sources.ts

@@ -0,0 +1,35 @@
+// Single enumeration of every table-bearing registration on a feature
+// (r.projection, r.multiStreamProjection with table, r.rawTable). Consumed
+// by BOTH the setupTestStack auto-push and collectTableMetas — one list, so
+// test-DB-push and `kumiko schema generate` cannot drift apart again (#255).
+// A new table-bearing registrar must be added HERE, not in the consumers.
+
+import type { FeatureDefinition } from "../engine/types";
+
+export type FeatureTableSource = {
+  readonly table: unknown;
+  // Stable human-readable label, unique across features — used as push-key
+  // and in error messages.
+  readonly origin: string;
+};
+
+export function enumerateFeatureTableSources(
+  feature: FeatureDefinition,
+): readonly FeatureTableSource[] {
+  const sources: FeatureTableSource[] = [];
+  for (const [name, proj] of Object.entries(feature.projections)) {
+    sources.push({ table: proj.table, origin: `projection "${name}" (${feature.name})` });
+  }
+  for (const [name, msp] of Object.entries(feature.multiStreamProjections)) {
+    // table omitted = side-effect-only MSP, materialises nothing.
+    if (!msp.table) continue;
+    sources.push({
+      table: msp.table,
+      origin: `multiStreamProjection "${name}" (${feature.name})`,
+    });
+  }
+  for (const [name, raw] of Object.entries(feature.rawTables)) {
+    sources.push({ table: raw.table, origin: `rawTable "${name}" (${feature.name})` });
+  }
+  return sources;
+}

package/src/db/index.ts

@@ -1,4 +1,5 @@
 export { assertExistsIn } from "./assert-exists-in";
+export { collectTableMetas } from "./collect-table-metas";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 export { seedConfigValues } from "./config-seed";
 export type { DbConnection, DbConnectionOptions, DbRow, DbRunner, DbTx } from "./connection";
@@ -50,6 +51,10 @@ export type {
   EventStoreExecutorOptions,
 } from "./event-store-executor";
 export { createEventStoreExecutor, entityEventName } from "./event-store-executor";
+export {
+  enumerateFeatureTableSources,
+  type FeatureTableSource,
+} from "./feature-table-sources";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp";
 export {
   diffSnapshots,

package/src/db/table-builder.ts

@@ -80,7 +80,12 @@ function fieldToColumns(
               : boolean(snakeName),
       };
     case "select": {
-      const col = text(snakeName);
+      // default() durchreichen — entity-table-meta rendert deklarierte
+      // defaults, dieser Builder MUSS lock-step bleiben (sonst trägt das
+      // Meta am buildEntityTable-Objekt eine andere Spalte als die
+      // Migration, #255-Follow-up-Befund).
+      const base = text(snakeName);
+      const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }
     case "multiSelect":
@@ -95,7 +100,8 @@ function fieldToColumns(
       // multi-select.
       return { [name]: jsonb(snakeName).default([]).notNull() };
     case "number": {
-      const col = integer(snakeName);
+      const base = integer(snakeName);
+      const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }
     case "bigInt": {
@@ -104,7 +110,8 @@ function fieldToColumns(
       // JS-`bigint` — JSON-serialisierbar, Frontend-tauglich. Wer >2^53
       // braucht (Astronomie-Astronomie), nutzt einen Text-Field mit
       // eigenem Codec.
-      const col = bigint(snakeName, { mode: "number" });
+      const base = bigint(snakeName, { mode: "number" });
+      const col = field.default !== undefined ? base.default(field.default) : base;
       return { [name]: field.required ? col.notNull() : col };
     }
     case "reference":

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

@@ -1,4 +1,6 @@
 import { describe, expect, test } from "bun:test";
+import { createTenantConfig } from "../config-helpers";
+import { defineFeature } from "../define-feature";
 import { createRegistry } from "../registry";
 import type { FeatureDefinition } from "../types/feature";
 
@@ -56,3 +58,76 @@ describe("createRegistry slot robustness", () => {
     ).not.toThrow();
   });
 });
+
+describe("extensionSelector boot-validation", () => {
+  function foundationFeature() {
+    return defineFeature("probe-foundation", (r) => {
+      r.extendsRegistrar("probeTransport", { onRegister: () => undefined });
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("probeTransport", configKeys.provider);
+      return { configKeys };
+    });
+  }
+
+  test("valid declaration lands in getAllExtensionSelectors", () => {
+    const registry = createRegistry([foundationFeature()]);
+    expect(registry.getAllExtensionSelectors().get("probeTransport")).toBe(
+      "probe-foundation:config:provider",
+    );
+  });
+
+  test("usages carry the owning featureName after merge", () => {
+    const provider = defineFeature("probe-smtp", (r) => {
+      r.useExtension("probeTransport", "smtp");
+    });
+    const registry = createRegistry([foundationFeature(), provider]);
+    const usage = registry.getExtensionUsages("probeTransport")[0];
+    expect(usage?.featureName).toBe("probe-smtp");
+  });
+
+  test("duplicate selector across features fails the boot", () => {
+    const rival = defineFeature("probe-rival", (r) => {
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("probeTransport", configKeys.provider);
+      return { configKeys };
+    });
+    expect(() => createRegistry([foundationFeature(), rival])).toThrow(
+      /Duplicate extension selector/,
+    );
+  });
+
+  test("selector for an undeclared extension fails the boot", () => {
+    const orphan = defineFeature("probe-orphan", (r) => {
+      const configKeys = r.config({
+        keys: { provider: createTenantConfig("text", { default: "" }) },
+      });
+      r.extensionSelector("ghostTransport", configKeys.provider);
+      return { configKeys };
+    });
+    expect(() => createRegistry([orphan])).toThrow(/no feature registers that extension/);
+  });
+
+  test("selector pointing at an unknown config key fails the boot", () => {
+    const typo = defineFeature("probe-typo", (r) => {
+      r.extendsRegistrar("probeTransport", { onRegister: () => undefined });
+      r.extensionSelector("probeTransport", "probe-typo:config:does-not-exist");
+    });
+    expect(() => createRegistry([typo])).toThrow(/unknown config key/);
+  });
+
+  test("declaring the selector twice in one feature fails at define-time", () => {
+    expect(() =>
+      defineFeature("probe-double", (r) => {
+        const configKeys = r.config({
+          keys: { provider: createTenantConfig("text", { default: "" }) },
+        });
+        r.extensionSelector("probeTransport", configKeys.provider);
+        r.extensionSelector("probeTransport", configKeys.provider);
+      }),
+    ).toThrow(/declared twice/);
+  });
+});

package/src/engine/config-helpers.ts

@@ -49,6 +49,7 @@ type ConfigKeyOptions<T extends ConfigKeyType> = {
   bounds?: T extends "number" ? ConfigBounds : never;
   computed?: ConfigComputedFn<T>;
   allowPerRequest?: T extends "text" ? never : boolean;
+  required?: boolean;
 };
 
 // --- Scope Defaults ---
@@ -80,6 +81,7 @@ function createConfigKey<T extends ConfigKeyType>(
     bounds: opts.bounds as ConfigBounds | undefined, // @cast-boundary schema-walk
     computed: opts.computed,
     ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
+    ...(opts.required === true ? { required: true } : {}),
   };
 }
 

package/src/engine/define-feature.ts

@@ -19,6 +19,7 @@ import type {
   EventDef,
   EventMigrationDef,
   EventUpcastFn,
+  ExtensionSelectorDef,
   FeatureDefinition,
   FeatureMetricDef,
   FeatureRegistrar,
@@ -129,6 +130,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   const notifications: Record<string, NotificationDefinition> = {};
   const registrarExtensions: Record<string, RegistrarExtensionDef> = {};
   const extensionUsages: RegistrarExtensionRegistration[] = [];
+  const extensionSelectors: ExtensionSelectorDef[] = [];
   const exposedApis: Set<string> = new Set();
   const usedApis: Set<string> = new Set();
   const referenceData: ReferenceDataDef[] = [];
@@ -565,6 +567,17 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       extensionUsages.push({ extensionName, entityName: resolveName(entityRef), options });
     },
 
+    extensionSelector(extensionName: string, key: { readonly name: string } | string): void {
+      if (extensionSelectors.some((s) => s.extensionName === extensionName)) {
+        throw new Error(
+          `[Feature ${name}] extensionSelector("${extensionName}") declared twice — ` +
+            `one selector key per extension point.`,
+        );
+      }
+      const qualifiedKey = typeof key === "string" ? key : key.name;
+      extensionSelectors.push({ extensionName, qualifiedKey });
+    },
+
     /**
      * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
      * unter dem genannten Namen bereit. Die eigentliche Implementation
@@ -936,6 +949,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     notifications,
     registrarExtensions,
     extensionUsages,
+    extensionSelectors,
     exposedApis,
     usedApis,
     referenceData,