@cosmicdrift/kumiko-framework 0.40.1 → 0.41.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.40.1",
+  "version": "0.41.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.38.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.40.1",
     "@types/uuid": "^11.0.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"

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

@@ -1,7 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { asRawClient } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
-import { createEventsTable } from "../../event-store";
+import { append, createEventsTable } from "../../event-store";
 import {
   createTestDb,
   type TestDb,
@@ -246,3 +246,42 @@ describe("event-store-executor — sensitive fields", () => {
     expect(event.payload.previous.apiToken).toBeUndefined();
   });
 });
+
+describe("event-store-executor — detail liefert die Stream-Version", () => {
+  const crud = createEventStoreExecutor(table, entity, { entityName: "esExecUser" });
+
+  // Lifecycle-Writes (ctx.appendEvent) bumpen den Stream, ohne row.version
+  // anzufassen — gäbe detail die stale Row-Version heraus, liefe jedes
+  // darauf gebaute CRUD-Update (entityEdit nutzt detail.version als
+  // optimistic-lock-Basis) in ein garantiertes version_conflict.
+  // Prod-Repro: incident:open appended das Eröffnungs-Update → Stream v2,
+  // Row v1 → incident-edit konnte nie speichern.
+  test("nach ctx.appendEvent-artigem Stream-Bump: detail.version == Stream, Update damit erfolgreich", async () => {
+    const created = await crud.create({ email: "stream@test.de" }, adminUser, tdb);
+    expect(created.isSuccess).toBe(true);
+    if (!created.isSuccess) return;
+    const id = created.data.id;
+
+    // Hand-emittiertes Event auf demselben Aggregat (wie incident:post-update).
+    await append(testDb.db, {
+      aggregateId: String(id),
+      aggregateType: "esExecUser",
+      tenantId: adminUser.tenantId,
+      expectedVersion: 1,
+      type: "esExecUser.lifecycle-bumped",
+      payload: { note: "stream moved past the row" },
+      metadata: { userId: String(adminUser.id) },
+    });
+
+    const detail = await crud.detail({ id }, adminUser, tdb);
+    expect(detail).not.toBeNull();
+    expect(detail?.["version"]).toBe(2);
+
+    const updated = await crud.update(
+      { id, version: 2, changes: { firstName: "After" } },
+      adminUser,
+      tdb,
+    );
+    expect(updated.isSuccess).toBe(true);
+  });
+});

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

@@ -969,6 +969,19 @@ export function createEventStoreExecutor(
 
       const idWhere = idFilter(payload.id);
 
+      // Stream-version authoritative (same policy as update/Block 0):
+      // ctx.appendEvent (lifecycle-writes like incident:post-update) bumps
+      // the stream WITHOUT touching row.version — a detail-read that hands
+      // out the stale row.version dooms the next CRUD update built on it
+      // (entityEdit loads detail.version as its optimistic-lock base) to a
+      // guaranteed version_conflict.
+      const withStreamVersion = async (
+        row: Record<string, unknown>,
+      ): Promise<Record<string, unknown>> => {
+        const streamVersion = await getStreamVersion(db.raw, String(payload.id), user.tenantId);
+        return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+      };
+
       if (entityCache && entityName) {
         const cached = await entityCache.get(user.tenantId, entityName, payload.id);
         if (cached) {
@@ -978,7 +991,7 @@ export function createEventStoreExecutor(
             const checkRows = await loadWithOwnership(db, idWhere, ownership);
             if (checkRows.length === 0) return null;
           }
-          return cached;
+          return withStreamVersion(cached);
         }
       }
 
@@ -993,7 +1006,7 @@ export function createEventStoreExecutor(
         await entityCache.set(user.tenantId, entityName, payload.id, coerced);
       }
 
-      return coerced;
+      return withStreamVersion(coerced);
     },
   };
 }

package/src/db/queries/event-store-admin.ts

@@ -8,8 +8,11 @@ export type RawFirstEventInsertParams = {
   readonly newVersion: number;
   readonly type: string;
   readonly eventVersion: number;
-  readonly payloadJson: string;
-  readonly metadataJson: string;
+  // Plain objects — a JS string bound to ::jsonb double-encodes under
+  // Bun.SQL (jsonb string scalar instead of object), see
+  // db/queries/event-store.ts SubsequentEventInsertParams.
+  readonly payload: Record<string, unknown>;
+  readonly metadata: Record<string, unknown>;
   readonly createdAt: string;
   readonly createdBy: string;
 };
@@ -31,8 +34,8 @@ export async function insertRawFirstEvent(
       params.newVersion,
       params.type,
       params.eventVersion,
-      params.payloadJson,
-      params.metadataJson,
+      params.payload,
+      params.metadata,
       params.createdAt,
       params.createdBy,
     ],
@@ -67,8 +70,8 @@ export async function insertRawSubsequentEvent(
       params.newVersion,
       params.type,
       params.eventVersion,
-      params.payloadJson,
-      params.metadataJson,
+      params.payload,
+      params.metadata,
       params.createdAt,
       params.createdBy,
       params.expectedVersion,

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

@@ -13,8 +13,12 @@ export type SubsequentEventInsertParams = {
   readonly newVersion: number;
   readonly type: string;
   readonly eventVersion: number;
-  readonly payloadJson: string;
-  readonly metadataJson: string;
+  // Plain objects, NOT pre-stringified JSON: Bun.SQL encodes a JS string
+  // bound to ::jsonb as a JSON string scalar (double-encoding) — every
+  // version>1 event written between 2026-05-25 and this fix carried
+  // payload/metadata as jsonb strings instead of objects.
+  readonly payload: Record<string, unknown>;
+  readonly metadata: Record<string, unknown>;
   readonly createdBy: string;
   readonly expectedVersion: number;
 };
@@ -51,8 +55,8 @@ export async function insertSubsequentEventRow(
       params.newVersion,
       params.type,
       params.eventVersion,
-      params.payloadJson,
-      params.metadataJson,
+      params.payload,
+      params.metadata,
       params.createdBy,
       params.expectedVersion,
     ],
@@ -127,7 +131,9 @@ export type SaveSnapshotParams = {
   readonly tenantId: string;
   readonly aggregateType: string;
   readonly version: number;
-  readonly stateJson: string;
+  // Plain object — see SubsequentEventInsertParams on why pre-stringified
+  // JSON double-encodes under Bun.SQL's ::jsonb binding.
+  readonly state: Record<string, unknown>;
 };
 
 export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Promise<void> {
@@ -139,7 +145,7 @@ export async function upsertSnapshot(db: AnyDb, params: SaveSnapshotParams): Pro
        "state" = $5::jsonb,
        "aggregate_type" = $3,
        "created_at" = now()`,
-    [params.aggregateId, params.tenantId, params.aggregateType, params.version, params.stateJson],
+    [params.aggregateId, params.tenantId, params.aggregateType, params.version, params.state],
   );
 }
 

package/src/engine/types/screen.ts

@@ -333,6 +333,17 @@ export type EntityEditScreenDefinition = {
   readonly type: "entityEdit";
   readonly entity: string;
   readonly layout: EditLayout;
+  /** Default true. `false` für Entities deren Create über einen eigenen
+   *  Lifecycle-Write läuft (z.B. incident:open mit Event-Stream + Joins)
+   *  statt über `<entity>:create`: unterdrückt den automatischen
+   *  „+ Neu"-Button auf entityList-Screens dieser Entity und rendert den
+   *  Create-Branch (Aufruf ohne entityId) als Fehler statt eines Forms,
+   *  dessen Submit gegen einen nicht registrierten Handler liefe. */
+  readonly allowCreate?: boolean;
+  /** Default true. `false` wenn kein `<entity>:delete`-Handler existiert
+   *  (History-/Audit-Erhalt): unterdrückt den Löschen-Button im
+   *  Update-Form. */
+  readonly allowDelete?: boolean;
   readonly slots?: ScreenSlots;
   readonly access?: AccessRule;
 };

package/src/entrypoint/index.ts

@@ -96,6 +96,15 @@ export type ApiEntrypointOptions = BaseEntrypointOptions & {
   readonly jobs?: JobsBlock & {
     readonly runLocalJobs?: boolean;
   };
+  // Event-dispatcher inside the API process — the MSP analog to
+  // `jobs.runLocalJobs`. Single-container deployments (runProdApp) have no
+  // worker process; without `runLocal: true` their multiStreamProjections
+  // NEVER apply (the read-side silently stays empty — 2026-06-11 incident).
+  // processLane becomes "both" so worker-lane MSPs run here too.
+  // Deployments with a dedicated worker keep this unset.
+  readonly eventDispatcher?: ServerOptions["eventDispatcher"] & {
+    readonly runLocal?: boolean;
+  };
 };
 
 export type WorkerEntrypointOptions = BaseEntrypointOptions &
@@ -117,9 +126,13 @@ export type ApiEntrypoint = {
   // Command-dispatcher behind /api/* — for writes outside the HTTP
   // pipeline (provider-webhook routes, see KumikoServer.dispatcher).
   readonly dispatcher: Dispatcher;
+  // Set when `eventDispatcher.runLocal: true` built a local poller —
+  // single-container mode. Undefined for API-only processes.
+  readonly eventDispatcher?: EventDispatcher;
   readonly mode: "api";
-  // No-op on API mode — event-dispatcher isn't built, job-runner doesn't
-  // exist. Kept for a uniform call-site so `main.ts` doesn't branch on mode.
+  // Starts the local BullMQ worker (runLocalJobs) and the local
+  // event-dispatcher (eventDispatcher.runLocal) when configured;
+  // no-op otherwise. Uniform call-site so `main.ts` doesn't branch on mode.
   start(): Promise<void>;
   stop(): Promise<void>;
 };
@@ -322,9 +335,19 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
       )
     : undefined;
 
-  // `{disabled:true}` skips dispatcher creation entirely — an API process
-  // doesn't hold an idle poller.
-  const server = buildApiServer(options, lifecycle, { disabled: true }, apiJobRunner, "api");
+  // Without `runLocal` the dispatcher is skipped entirely (`{disabled:true}`)
+  // — an API process behind a dedicated worker doesn't hold an idle poller.
+  // WITH `runLocal` this process fills every role (single-container), so
+  // processLane is "both": worker-lane MSPs must run here or they'd never
+  // apply anywhere.
+  const { runLocal: runLocalDispatcher, ...dispatcherTunables } = options.eventDispatcher ?? {};
+  const server = buildApiServer(
+    options,
+    lifecycle,
+    runLocalDispatcher ? dispatcherTunables : { disabled: true },
+    apiJobRunner,
+    runLocalDispatcher ? "both" : "api",
+  );
 
   return {
     app: server.app,
@@ -333,12 +356,17 @@ export function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoin
     lifecycle,
     observability: server.observability,
     dispatcher: server.dispatcher,
+    ...(server.eventDispatcher && { eventDispatcher: server.eventDispatcher }),
     mode: "api",
     async start() {
       // Start the local BullMQ worker when runLocalJobs=true; enqueuer-only
       // runners have a no-op .start() by design (JobRunner skips worker
       // creation when consumerLane is undefined).
       if (apiJobRunner) await apiJobRunner.start();
+      // Local event-dispatcher (runLocal): begins the poll loop so MSPs
+      // apply in-process. stop() is already lifecycle-registered by
+      // buildServer.
+      if (server.eventDispatcher) await server.eventDispatcher.start();
     },
     async stop() {
       await lifecycle.drain();
@@ -410,11 +438,13 @@ export function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): Al
   // config instead of `{disabled:true}`, so buildServer wires the poller
   // alongside the HTTP app. processLane "both" disables MSP lane-filter
   // entirely: all-in-one is a single process that fills every role, so
-  // every MSP (api-only, worker-only, both) must run here.
+  // every MSP (api-only, worker-only, both) must run here. `runLocal` is
+  // the API-mode flag — all-in-one is always local, strip it.
+  const { runLocal: _runLocal, ...allInOneDispatcherTunables } = options.eventDispatcher ?? {};
   const server = buildApiServer(
     options,
     lifecycle,
-    options.eventDispatcher,
+    allInOneDispatcherTunables,
     workerJobRunner,
     "both",
   );

package/src/event-store/__tests__/event-store.integration.test.ts

@@ -584,3 +584,59 @@ describe("event-store: streamAllEventsByType (memory-bounded iteration)", () =>
     expect((thrown as Error).name).toBe("AbortError");
   });
 });
+
+describe("event-store: jsonb encoding of payload/metadata", () => {
+  // Regression für die Bun.SQL-Doppelkodierung (Prod-Incident 2026-06-11):
+  // insertSubsequentEventRow band stringifyJson(payload) an ::jsonb — Bun
+  // kodiert einen JS-String für jsonb erneut, das Ergebnis ist ein jsonb-
+  // STRING-Skalar statt einem Objekt. Der typed Read-Pfad parsed Strings
+  // beim Laden zurück (bun-db/query.ts), deshalb blieb das in allen
+  // loadAggregate-Tests unsichtbar — nur SQL-Konsumenten (payload->>'x',
+  // GDPR-Pipeline, MSP-Replays über raw rows) sahen kaputte Daten. Darum
+  // prüft dieser Test das Spalten-Encoding direkt in SQL.
+  test("first AND subsequent append store payload/metadata as jsonb objects", async () => {
+    const aggregateId = uuid();
+    const base = {
+      aggregateId,
+      aggregateType: "task",
+      tenantId: tenantA,
+      metadata: { userId: userA },
+    };
+
+    await append(testDb.db, {
+      ...base,
+      expectedVersion: 0,
+      type: "task.created",
+      payload: { title: "T" },
+    });
+    await append(testDb.db, {
+      ...base,
+      expectedVersion: 1,
+      type: "task.updated",
+      payload: { title: "T2", nested: { deep: true } },
+    });
+
+    const rows = (await asRawClient(testDb.db).unsafe(
+      `SELECT version,
+              jsonb_typeof(payload) AS payload_type,
+              jsonb_typeof(metadata) AS metadata_type,
+              payload->>'title' AS title
+       FROM kumiko_events WHERE aggregate_id = $1 ORDER BY version`,
+      [aggregateId],
+    )) as ReadonlyArray<{
+      version: number;
+      payload_type: string;
+      metadata_type: string;
+      title: string | null;
+    }>;
+
+    expect(rows).toHaveLength(2);
+    for (const row of rows) {
+      expect(row.payload_type).toBe("object");
+      expect(row.metadata_type).toBe("object");
+    }
+    // SQL-seitiger Feldzugriff funktioniert nur auf echten Objekten —
+    // genau der Pfad, der mit String-Skalaren null lieferte.
+    expect(rows[1]?.title).toBe("T2");
+  });
+});

package/src/event-store/admin-api.ts

@@ -17,7 +17,6 @@ import {
   insertRawSubsequentEvent,
 } from "../db/queries/event-store-admin";
 import type { TenantId } from "../engine/types";
-import { stringifyJson } from "../utils/safe-json";
 import { VersionConflictError } from "./errors";
 import type { EventMetadata } from "./event-store";
 
@@ -69,8 +68,8 @@ function rawEventParams(event: RawEventToAppend, newVersion: number, eventVersio
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: stringifyJson(event.payload),
-    metadataJson: stringifyJson(event.metadata),
+    payload: event.payload,
+    metadata: event.metadata,
     createdAt: event.createdAt.toString(),
     createdBy: event.createdBy,
   };
@@ -130,8 +129,8 @@ export async function appendRawBatch(
       newVersion,
       e.type,
       eventVersion,
-      stringifyJson(e.payload),
-      stringifyJson(e.metadata),
+      e.payload,
+      e.metadata,
       e.createdAt.toString(),
       e.createdBy,
     );

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

@@ -10,7 +10,6 @@ import {
 } from "../db/queries/event-store";
 import { insertOne, selectMany } from "../db/query";
 import type { TenantId } from "../engine/types";
-import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
@@ -176,8 +175,8 @@ async function insertSubsequentEvent(
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: stringifyJson(event.payload),
-    metadataJson: stringifyJson(event.metadata),
+    payload: event.payload,
+    metadata: event.metadata,
     createdBy: event.metadata.userId,
     expectedVersion: event.expectedVersion,
   });

package/src/event-store/snapshot.ts

@@ -17,7 +17,6 @@ import { selectMany } from "../db/query";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
-import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 
@@ -108,7 +107,7 @@ export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promis
     tenantId: args.tenantId,
     aggregateType: args.aggregateType,
     version: args.version,
-    stateJson: stringifyJson(args.state),
+    state: args.state,
   });
 }