@cosmicdrift/kumiko-framework 0.40.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.40.0",
+  "version": "0.41.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.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/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/__tests__/boot-validator.test.ts

@@ -1890,6 +1890,56 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- rowAction payload-Extractor Feld-Referenzen (Tier 2.7e-3) ---
+  // Row-Meta (id, version) ist auf jeder Entity-Row vorhanden ohne ein
+  // Entity-Field zu sein — pick ["id", "version"] ist das Standard-Payload
+  // für optimistic-lock-Lifecycle-Writes und darf den Boot nicht killen
+  // (Prod-Incident publicstatus 2026-06-11: 0.40-Validator lehnte
+  // maintenance-start/cancel/complete ab, CrashLoopBackOff).
+  describe("entityList rowAction payload pick (Tier 2.7e-3)", () => {
+    function makeFeature(pick: readonly string[]) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            {
+              id: "archive",
+              label: "actions.archive",
+              handler: "shop:write:archive",
+              payload: { pick: [...pick] },
+            },
+          ],
+        });
+        r.writeHandler(
+          "archive",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+      });
+    }
+
+    test("pick mit Row-Meta id + version → kein Throw (optimistic-lock-Standard)", () => {
+      expect(() => validateBoot([makeFeature(["id", "version"])])).not.toThrow();
+    });
+
+    test("pick mit Entity-Field → kein Throw", () => {
+      expect(() => validateBoot([makeFeature(["id", "name"])])).not.toThrow();
+    });
+
+    test("pick mit unknown Field → Throw mit klarer Message", () => {
+      expect(() => validateBoot([makeFeature(["id", "ghost"])])).toThrow(
+        /rowAction "archive" payload references unknown field "ghost"/,
+      );
+    });
+  });
+
   // --- toolbarAction navigate + writeHandler Validierung (Tier 2.7e-2) ---
   describe("entityList toolbarAction navigate (Tier 2.7e-2)", () => {
     function makeFeature(targetScreen: string, withTarget: boolean) {

package/src/engine/boot-validator/screens-nav.ts

@@ -48,7 +48,9 @@ function validateActionFieldRefs(
     }
     const sources = "pick" in extractor ? extractor.pick : Object.values(extractor.map);
     for (const source of sources) {
-      if (source === "id") continue; // row.id ist immer da (Aggregat-Id)
+      // Row-Meta ist immer da, ohne Entity-Field zu sein: id (Aggregat-Id)
+      // und version (optimistic lock — Standard-pick für Lifecycle-Writes).
+      if (source === "id" || source === "version") continue;
       if (!fieldNames.has(source)) {
         throw new Error(
           `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +

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,
   });
 }