@cosmicdrift/kumiko-framework 0.75.0 → 0.76.0

package/package.json

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

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

@@ -53,7 +53,6 @@ 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, [

package/src/db/__tests__/event-store-system-stream.integration.test.ts

@@ -0,0 +1,96 @@
+// #497 guard: an entity declared `systemStream: true` (tenant-independent, e.g.
+// user) gets its event stream on SYSTEM_TENANT_ID for EVERY op; a normal entity
+// stays on the caller's tenant (byte-identical to the old hardcoded user.tenantId).
+// Routing is per-entity (createEntity flag), NOT inherited from r.systemScope().
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { SYSTEM_TENANT_ID } from "../../engine/types/identifiers";
+import { eventsTable } from "../../event-store";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { createEventStoreExecutor } from "../event-store-executor";
+import { selectMany } from "../query";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const systemEntity = createEntity({
+  table: "sstream_sys",
+  systemStream: true,
+  fields: { name: createTextField({ required: true }) },
+});
+const tenantOwnedEntity = createEntity({
+  table: "sstream_tn",
+  fields: { name: createTextField({ required: true }) },
+});
+
+const systemTable = buildEntityTable("sstreamSys", systemEntity);
+const tenantTable = buildEntityTable("sstreamTn", tenantOwnedEntity);
+const systemExec = createEventStoreExecutor(systemTable, systemEntity, {
+  entityName: "sstreamSys",
+});
+const tenantExec = createEventStoreExecutor(tenantTable, tenantOwnedEntity, {
+  entityName: "sstreamTn",
+});
+
+const user = TestUsers.admin; // tenantId === testTenantId(1)
+
+let testDb: TestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, systemEntity, "sstreamSys");
+  await unsafeCreateEntityTable(testDb.db, tenantOwnedEntity, "sstreamTn");
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+async function eventTenantIds(aggregateId: string): Promise<string[]> {
+  const rows = await selectMany(testDb.db, eventsTable, { aggregateId });
+  return rows.map((r) => r!["tenantId"] as string);
+}
+
+describe("systemStream stream-tenant routing (#497)", () => {
+  test("systemStream entity: created event lands on SYSTEM_TENANT_ID", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    const res = await systemExec.create({ name: "a" }, user, db);
+    expect(res.isSuccess).toBe(true);
+    if (!res.isSuccess) throw new Error("create failed");
+
+    expect(await eventTenantIds(String(res.data.id))).toEqual([SYSTEM_TENANT_ID]);
+  });
+
+  test("systemStream entity: update addresses the SYSTEM stream (every op routes)", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    const created = await systemExec.create({ name: "a" }, user, db);
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = String(created.data.id);
+
+    // If update addressed user.tenantId instead of SYSTEM, getStreamVersion
+    // would read 0 and the append would version-conflict. Success proves the
+    // whole addressing path (not just create) routes to SYSTEM.
+    const updated = await systemExec.update({ id, changes: { name: "b" } }, user, db, {
+      skipOptimisticLock: true,
+    });
+    expect(updated.isSuccess).toBe(true);
+    expect(await eventTenantIds(id)).toEqual([SYSTEM_TENANT_ID, SYSTEM_TENANT_ID]);
+  });
+
+  test("normal entity: created event lands on the caller's tenant (unchanged)", async () => {
+    const db = createTenantDb(testDb.db, user.tenantId);
+    const res = await tenantExec.create({ name: "a" }, user, db);
+    expect(res.isSuccess).toBe(true);
+    if (!res.isSuccess) throw new Error("create failed");
+
+    const ids = await eventTenantIds(String(res.data.id));
+    expect(ids).toEqual([testTenantId(1)]);
+    expect(ids).not.toContain(SYSTEM_TENANT_ID);
+  });
+});

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

@@ -243,6 +243,13 @@ export function createEventStoreExecutor(
   const { searchAdapter, entityName, entityCache } = options;
   const softDelete = entity.softDelete ?? false;
 
+  // Stream-tenant choke-point. A systemStream entity (tenant-independent, e.g.
+  // user) lives on SYSTEM_TENANT_ID deterministically — every op addresses it
+  // there. Everything else stays on the caller's tenant (byte-identical to the
+  // old hardcoded user.tenantId). Single source of truth for the stream key.
+  const streamTenantFor = (user: SessionUser): TenantId =>
+    entity.systemStream ? SYSTEM_TENANT_ID : user.tenantId;
+
   // idType default (undefined) is now "uuid" — the ES-pivot made UUID the
   // only valid aggregate-id type. Explicit `idType: "serial"` is the only
   // shape that's incompatible with the event-store and still rejected.
@@ -433,7 +440,7 @@ export function createEventStoreExecutor(
         event = await append(db.raw, {
           aggregateId,
           aggregateType: entityName,
-          tenantId: user.tenantId,
+          tenantId: streamTenantFor(user),
           expectedVersion: 0,
           type: entityEventName(entityName, "created"),
           payload: stripSensitive(flatData),
@@ -451,7 +458,7 @@ export function createEventStoreExecutor(
           // is recoverable client-side via a fresh detail-query if needed.
           let currentVersion = -1;
           try {
-            currentVersion = await getStreamVersion(db.raw, aggregateId, user.tenantId);
+            currentVersion = await getStreamVersion(db.raw, aggregateId, streamTenantFor(user));
           } catch {
             // Aborted TX or any lookup failure — keep the sentinel.
           }
@@ -560,14 +567,18 @@ export function createEventStoreExecutor(
         );
       }
 
-      await assertStreamWritable(db, payload.id, user.tenantId);
+      await assertStreamWritable(db, payload.id, streamTenantFor(user));
 
       // 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
       // trip `events_aggregate_version_uq` (tenant_id, aggregate_id, version)
       // with version_conflict.
-      const currentVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
+      const currentVersion = await getStreamVersion(
+        db.raw,
+        String(payload.id),
+        streamTenantFor(user),
+      );
       if (!updateOptions?.skipOptimisticLock) {
         if (payload.version === undefined) {
           return writeFailure(
@@ -603,7 +614,7 @@ export function createEventStoreExecutor(
         const event = await append(db.raw, {
           aggregateId: String(payload.id),
           aggregateType: entityName,
-          tenantId: user.tenantId,
+          tenantId: streamTenantFor(user),
           expectedVersion: currentVersion,
           type: entityEventName(entityName, "updated"),
           payload: {
@@ -696,10 +707,14 @@ export function createEventStoreExecutor(
         );
       }
 
-      await assertStreamWritable(db, payload.id, user.tenantId);
+      await assertStreamWritable(db, payload.id, streamTenantFor(user));
 
       // Stream-version authoritative (see update() for rationale).
-      const currentVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
+      const currentVersion = await getStreamVersion(
+        db.raw,
+        String(payload.id),
+        streamTenantFor(user),
+      );
 
       // Deletes carry the full pre-delete row as `previous`. That's what
       // projections and downstream consumers need to reverse any aggregates —
@@ -708,7 +723,7 @@ export function createEventStoreExecutor(
       const event = await append(db.raw, {
         aggregateId: String(payload.id),
         aggregateType: entityName,
-        tenantId: user.tenantId,
+        tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "deleted"),
         payload: { previous: stripSensitive(existing) },
@@ -773,10 +788,14 @@ export function createEventStoreExecutor(
         );
       }
 
-      await assertStreamWritable(db, payload.id, user.tenantId);
+      await assertStreamWritable(db, payload.id, streamTenantFor(user));
 
       // Stream-version authoritative (see update() for rationale).
-      const currentVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
+      const currentVersion = await getStreamVersion(
+        db.raw,
+        String(payload.id),
+        streamTenantFor(user),
+      );
       // Restore carries the soft-deleted snapshot as `previous` — mirror of
       // delete for symmetry. Projections that decremented on delete use
       // `previous` to re-increment on restore without re-querying the entity
@@ -784,7 +803,7 @@ export function createEventStoreExecutor(
       const event = await append(db.raw, {
         aggregateId: String(payload.id),
         aggregateType: entityName,
-        tenantId: user.tenantId,
+        tenantId: streamTenantFor(user),
         expectedVersion: currentVersion,
         type: entityEventName(entityName, "restored"),
         payload: { previous: stripSensitive(data) },
@@ -1000,7 +1019,11 @@ export function createEventStoreExecutor(
       const withStreamVersion = async (
         row: Record<string, unknown>,
       ): Promise<Record<string, unknown>> => {
-        const streamVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
+        const streamVersion = await getStreamVersion(
+          db.raw,
+          String(payload.id),
+          streamTenantFor(user),
+        );
         return streamVersion > 0 ? { ...row, version: streamVersion } : row;
       };
 

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

@@ -236,8 +236,8 @@ describe("buildAppSchema — dangling audience-ref dev-warning (#408/3)", () =>
   });
 
   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.
+    // bun:test sets NODE_ENV=test; an unplaced audience (tenant left over by
+    // placingShell("system")) must NOT emit a console.warn into CI logs.
     const warn = spyOn(console, "warn").mockImplementation(() => {});
     try {
       buildAppSchema(createRegistry([placingShell("system"), billing]));

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -202,10 +202,10 @@ describe("buildConfigFeatureSchema — per-role cascade (system > tenant > user)
 });
 
 describe("buildConfigFeatureSchema — machine-role does not leak into screen access (#406/2)", () => {
-  // Ein gemischter write-Set (machine "system" + human "SystemAdmin") entsteht
-  // nur über ein explizites write:-Override (kein Preset erzeugt den Mix). Der
-  // Screen darf trotzdem NUR die Human-Rolle gaten — "system" trägt kein User,
-  // ein Leak macht das Gate inkonsistent zum Hardening-Ziel.
+  // A mixed write-set (machine "system" + human "SystemAdmin") only arises via
+  // an explicit write:-override (no preset produces the mix). The screen must
+  // gate on the human role only — "system" is not carried by a real user and
+  // leaking it makes the gate inconsistent with the hardening goal.
   const mixedWrite = defineFeature("mixed", (r) => {
     r.config({
       keys: {

package/src/engine/factories.ts

@@ -363,6 +363,9 @@ export function createEntity<F>(def: {
   readonly table?: string;
   readonly fields: F;
   readonly softDelete?: boolean;
+  /** Event stream lives on SYSTEM_TENANT_ID (tenant-independent aggregate, e.g.
+   *  user) instead of the creator's tenant. See EntityDefinition.systemStream. */
+  readonly systemStream?: boolean;
   readonly searchWeight?: number;
   readonly defaultCurrency?: string;
   readonly transitions?: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;

package/src/engine/types/fields.ts

@@ -561,6 +561,11 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap> = {
   readonly table?: string;
   readonly fields: F;
   readonly softDelete?: boolean;
+  /** This aggregate's event stream lives on SYSTEM_TENANT_ID rather than the
+   *  creator's tenant. Opt-in per entity (NOT inherited from r.systemScope()):
+   *  only for genuinely tenant-independent aggregates like `user`. The first
+   *  event (create) is what's routed; updates resolve the stream tenant upstream. */
+  readonly systemStream?: boolean;
   readonly searchWeight?: number;
   readonly defaultCurrency?: string;
   /** Allowed state transitions per field. Boot validates against select options. */