@cosmicdrift/kumiko-framework 0.181.0 → 0.182.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.181.0",
+  "version": "0.182.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>",
@@ -182,7 +182,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.181.0",
+    "@cosmicdrift/kumiko-types": "0.182.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.12.27",
@@ -198,7 +198,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.181.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.182.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/bun-db/query.ts

@@ -30,6 +30,7 @@ import type {
 import { Temporal } from "temporal-polyfill";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
+import { extractPgError } from "../db/pg-error";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
 import { camelCase as envCamelCase } from "../env";
 import { parseJsonSafe } from "../utils/safe-json";
@@ -135,6 +136,38 @@ export async function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promis
   return raw.savepoint(fn);
 }
 
+// Same error-confinement as runInSavepoint, but for call sites that don't
+// know whether `db` is a bare pool connection or an active transaction
+// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
+// against the pool by seeds/tests). A pool connection has no savepoint() —
+// and doesn't need one, since each statement there is its own auto-committed
+// unit and a failed statement can't poison anything downstream.
+//
+// `.savepoint` being present isn't proof the transaction is still open: an
+// afterCommit hook closure captures the same handlerContext (and therefore
+// the same TransactionSql-shaped db) that was live during the write, but by
+// the time the hook fires the outer tx has already committed — the object
+// still exposes `.savepoint`, calling it now fails with PG 25P01 ("no
+// active sql transaction") because there's no BEGIN left to nest into. That
+// SAVEPOINT command is the first thing the driver sends, before `fn` runs,
+// so catching 25P01 and retrying directly is safe — nothing from `fn` has
+// executed yet.
+export async function runInSavepointIfSupported<T>(
+  db: unknown,
+  fn: (sp: unknown) => Promise<T>,
+): Promise<T> {
+  const raw = asRawClient(db) as unknown as {
+    savepoint?: <TR>(cb: (sp: unknown) => Promise<TR>) => Promise<TR>;
+  };
+  if (typeof raw.savepoint !== "function") return fn(db);
+  try {
+    return await raw.savepoint(fn);
+  } catch (e) {
+    if (extractPgError(e)?.code === "25P01") return fn(db);
+    throw e;
+  }
+}
+
 /**
  * When handlers call `selectMany(ctx.db, …)` instead of `ctx.db.selectMany(…)`,
  * unwrap via asRawClient would bypass TenantDb scoping. Duck-type TenantDb and

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

@@ -5,7 +5,7 @@
 // verb entirely, and restore()'s two precondition failures.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { asRawClient } from "../../db/query";
+import { asRawClient, transaction } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import { from } from "../../engine/ownership";
 import { createEventsTable } from "../../event-store";
@@ -419,6 +419,38 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
     expect(healthCheck[0]?.ok).toBe(1);
   });
 
+  // kumiko-framework#1778 — a real write handler runs create() inside the
+  // dispatcher's transaction (sql.begin()), not on the bare pool like the
+  // race test above. postgres.js/Bun.SQL poison the WHOLE begin() block
+  // once any statement inside it errors, even if the JS layer already
+  // caught and classified that error — so without the runInSavepoint fix
+  // in event-store-executor-write.ts, the LOSER's transaction() call itself
+  // rejects with the raw PostgresError instead of resolving to the
+  // version_conflict writeFailure create() already produced.
+  test("two concurrent first-time creates of the same id inside a transaction → one succeeds, one converges to version_conflict", async () => {
+    const id = "11111111-1111-4111-8111-111111111111";
+
+    const [a, b] = await Promise.all([
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "a@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+      transaction(testDb.db, (tx) =>
+        crud.create({ id, email: "b@test.de" }, admin, createTenantDb(tx, admin.tenantId)),
+      ),
+    ]);
+
+    const results = [a, b];
+    expect(results.filter((r) => r.isSuccess)).toHaveLength(1);
+    expect(results.filter((r) => !r.isSuccess && r.error.code === "version_conflict")).toHaveLength(
+      1,
+    );
+
+    const healthCheck = (await asRawClient(testDb.db).unsafe(`SELECT 1 AS ok`)) as Array<{
+      ok: number;
+    }>;
+    expect(healthCheck[0]?.ok).toBe(1);
+  });
+
   test("forget with entityCache clears the cache entry", async () => {
     const created = await crud.create({ email: "cache-forget@test.de" }, admin, tdb);
     if (!created.isSuccess) throw new Error("setup failed");

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

@@ -18,7 +18,7 @@ import {
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
-import type { DbRow } from "./connection";
+import type { DbRow, DbRunner } from "./connection";
 import type { EventStoreExecutor } from "./event-store-executor";
 import {
   buildEventMetadata,
@@ -26,7 +26,7 @@ import {
   entityEventName,
   tryMapUniqueViolation,
 } from "./event-store-executor-context";
-import { selectMany } from "./query";
+import { runInSavepointIfSupported, selectMany } from "./query";
 
 // The five write verbs (create/update/delete/forget/restore) of the event-
 // store-executor. Split out of event-store-executor.ts (#1005, Welle 2) —
@@ -190,30 +190,34 @@ export function createWriteVerbs(
       //    selben catch (siehe line 493+).
       let event: Awaited<ReturnType<typeof append>>;
       try {
-        event = await append(db.raw, {
-          aggregateId,
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: 0,
-          type: entityEventName(entityName, "created"),
-          payload: flatData,
-          metadata: buildEventMetadata(user),
-        });
+        // Savepoint-scoped: postgres.js/Bun.SQL poison the WHOLE surrounding
+        // begin() once any statement inside it errors, even if the JS error
+        // is caught (kumiko-framework#1778) — a losing concurrent create's
+        // unique-violation would otherwise abort the caller's outer
+        // transaction and surface as internal_error at commit time instead
+        // of the version_conflict this catch classifies. runInSavepointIfSupported
+        // confines the failed INSERT to a nested scope that rolls back on
+        // its own (same pattern as ctx.tryAppendEvent), and falls back to a
+        // plain call when db.raw is a bare pool connection with no active
+        // transaction to poison (seeds/tests calling the executor directly).
+        event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId,
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: 0,
+            type: entityEventName(entityName, "created"),
+            payload: flatData,
+            metadata: buildEventMetadata(user),
+          }),
+        );
       } catch (e) {
         if (e instanceof EventStoreVersionConflict) {
-          // Try to look up the real stream-version for the diagnostic — but
-          // wrap defensively: when `append` raised the unique-violation, the
-          // current TX is already aborted, and a second query on the same
-          // runner would re-throw "current transaction is aborted". Update-
-          // path doesn't have this problem (it queries getStreamVersion
-          // BEFORE the try-block). Falling back to a sentinel keeps the
-          // version_conflict mapping reliable; the actual current version
-          // is recoverable client-side via a fresh detail-query if needed.
           let currentVersion = -1;
           try {
             currentVersion = await getStreamVersion(db.raw, aggregateId, streamTenantFor(user));
           } catch {
-            // Aborted TX or any lookup failure — keep the sentinel.
+            // Lookup failure — keep the sentinel.
           }
           return writeFailure(
             new FrameworkVersionConflict({
@@ -412,18 +416,24 @@ export function createWriteVerbs(
         // re-encrypt it before it's persisted so plaintext of pii/encrypted
         // fields doesn't land in the immutable log (flatChanges is already
         // ciphertext from encryptForStorage above).
-        const event = await append(db.raw, {
-          aggregateId: String(payload.id),
-          aggregateType: entityName,
-          tenantId: streamTenantFor(user),
-          expectedVersion: currentVersion,
-          type: entityEventName(entityName, "updated"),
-          payload: {
-            changes: flatChanges,
-            previous: await encryptForStorage(previous, user),
-          },
-          metadata: buildEventMetadata(user),
-        });
+        const encryptedPrevious = await encryptForStorage(previous, user);
+        // Savepoint-scoped — see the create() append() above for why:
+        // confines a losing writer's unique-violation to a nested scope
+        // instead of poisoning the whole outer transaction.
+        const event = await runInSavepointIfSupported(db.raw, (sp) =>
+          append(sp as DbRunner, {
+            aggregateId: String(payload.id),
+            aggregateType: entityName,
+            tenantId: streamTenantFor(user),
+            expectedVersion: currentVersion,
+            type: entityEventName(entityName, "updated"),
+            payload: {
+              changes: flatChanges,
+              previous: encryptedPrevious,
+            },
+            metadata: buildEventMetadata(user),
+          }),
+        );
 
         // Live==Rebuild via applyEntityEvent mit demselben StoredEvent —
         // apply liest nur `changes`, und die sind live wie im Replay

package/src/db/query.ts

@@ -18,6 +18,7 @@ export {
   insertOne,
   type OrderByClause,
   runInSavepoint,
+  runInSavepointIfSupported,
   type SelectOptions,
   selectMany,
   type TableInfo,

package/src/engine/__tests__/content-collection.test.ts

@@ -115,6 +115,65 @@ describe("r.contentCollection() — registration", () => {
     expect(feature.contentCollections?.["signatures"]?.ownership).toBe("user");
   });
 
+  test("records contentFormat so the client can resolve the right editor", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.contentFormat).toBe("plain");
+  });
+
+  test("contentFormat is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.contentFormat).toBeUndefined();
+  });
+
+  test("records contentFormat markdown as a third format alongside plain/rich", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "notes",
+        kind: "text-block",
+        contentFormat: "markdown",
+        nav: { label: "mail:nav.notes" },
+      });
+    });
+
+    expect(feature.contentCollections?.["notes"]?.contentFormat).toBe("markdown");
+  });
+
+  test("records variableSchema so the client can offer the right chips", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({
+        id: "prompts",
+        kind: "ai-prompt",
+        contentFormat: "plain",
+        variableSchema: { customerName: {}, orderId: {} },
+        nav: { label: "mail:nav.prompts" },
+      });
+    });
+
+    expect(feature.contentCollections?.["prompts"]?.variableSchema).toEqual({
+      customerName: {},
+      orderId: {},
+    });
+  });
+
+  test("variableSchema is optional — undefined when the app didn't declare one", () => {
+    const feature = defineFeature("mail", (r) => {
+      r.contentCollection({ id: "templates", kind: "mail-html", nav: { label: "a" } });
+    });
+
+    expect(feature.contentCollections?.["templates"]?.variableSchema).toBeUndefined();
+  });
+
   test("rejects a second collection with the same id", () => {
     expect(() =>
       defineFeature("mail", (r) => {
@@ -179,6 +238,7 @@ describe("buildAppSchema — content collections", () => {
         r.contentCollection({
           id: "templates",
           kind: "mail-html",
+          contentFormat: "rich",
           nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         });
       }),
@@ -190,6 +250,7 @@ describe("buildAppSchema — content collections", () => {
       {
         id: "templates",
         kind: "mail-html",
+        contentFormat: "rich",
         nav: { label: "mail:nav.templates", parent: "mail:nav:root" },
         navQn: "mail:nav:templates",
       },
@@ -199,6 +260,38 @@ describe("buildAppSchema — content collections", () => {
     expect(mail?.navs?.map((n) => n.id)).toContain("templates");
   });
 
+  test("projects variableSchema through to the client schema", () => {
+    const registry = createRegistry([
+      defineFeature("mail", (r) => {
+        r.contentCollection({
+          id: "prompts",
+          kind: "ai-prompt",
+          contentFormat: "plain",
+          variableSchema: { customerName: {} },
+          nav: { label: "mail:nav.prompts" },
+        });
+      }),
+    ]);
+
+    const schema = buildAppSchema(registry);
+    const mail = schema.features.find((f) => f.featureName === "mail");
+    expect(mail?.contentCollections?.[0]?.variableSchema).toEqual({ customerName: {} });
+    // buildAppSchema's JSON-safety check throws on undefined leaves — proves
+    // the new field survives that check instead of only the toEqual above.
+    expect(() =>
+      validateBoot([
+        defineFeature("mail2", (r) => {
+          r.contentCollection({
+            id: "prompts",
+            kind: "ai-prompt",
+            variableSchema: { customerName: {} },
+            nav: { label: "mail2:nav.prompts" },
+          });
+        }),
+      ]),
+    ).not.toThrow();
+  });
+
   test("omits the slot for features without collections", () => {
     const registry = createRegistry([
       defineFeature("shop", (r) => {

package/src/engine/__tests__/entity-handlers.test.ts

@@ -14,6 +14,9 @@ import {
   registerEntityCrud,
 } from "../entity-handlers";
 import { createEntity, createTextField } from "../factories";
+// Barrel import, not "../entity-handlers": covers that entityListSchema is
+// actually re-exported through engine/index.ts.
+import { entityListSchema } from "../index";
 import type { QueryHandlerDef, WriteHandlerDef } from "../types";
 
 const VALID_UUID = "00000000-0000-4000-8000-000000000001";
@@ -119,6 +122,19 @@ describe("defineEntityQueryHandler", () => {
     expect(def.schema.safeParse({ sortDirection: "wrong" }).success).toBe(false);
   });
 
+  test("list: schema is the exported entityListSchema, not a private copy", () => {
+    const def = defineEntityListHandler("note", noteEntity);
+    expect(def.schema).toBe(entityListSchema);
+    // money-horse#293: a consumer copy silently dropped these fields when it
+    // drifted from the handler's actual schema — assert they still round-trip.
+    expect(
+      def.schema.safeParse({
+        includeDeleted: true,
+        filters: [{ field: "title", op: "eq", value: "x" }],
+      }).success,
+    ).toBe(true);
+  });
+
   test("detail: schema requires id", () => {
     const def = defineEntityDetailHandler("note", noteEntity);
     expect(def.schema.safeParse({ id: VALID_UUID }).success).toBe(true);

package/src/engine/entity-handlers.ts

@@ -102,7 +102,7 @@ type ListPayload = {
 };
 
 const idSchema = z.object({ id: z.uuid() });
-const listSchema = z.object({
+export const entityListSchema = z.object({
   cursor: z.string().optional(),
   limit: z.number().optional(),
   search: z.string().optional(),
@@ -292,7 +292,7 @@ export function defineEntityQueryHandler(
 
   switch (verb) {
     case "list":
-      schema = listSchema;
+      schema = entityListSchema;
       handler = async (query, ctx) => {
         // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
         // damit payload.search zur Laufzeit gegen Meilisearch/InMem

package/src/engine/index.ts

@@ -69,6 +69,7 @@ export {
   defineEntityWriteHandler,
   defineProjectionQueryHandler,
   type EntityCrudRegistrar,
+  entityListSchema,
   type RegisterEntityCrudOptions,
   registerEntityCrud,
 } from "./entity-handlers";