@cosmicdrift/kumiko-framework 0.235.0 → 0.235.1

package/package.json

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

package/src/db/__tests__/list-row-meta-drift.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
+import { rowMetaFieldNames } from "../table-builder";
+
+// Drift-Guard: LIST_ROW_META_COLUMNS (client-safe subpath, headless's
+// computeListViewModel) duplicates the base row-meta column names instead
+// of importing db/table-builder directly (that would pull drizzle into the
+// client bundle — see ui-types/list-row-meta.ts). This test is the only
+// place both sides meet, so a base-columns change here fails loud instead
+// of silently drifting the two representations apart.
+describe("LIST_ROW_META_COLUMNS ↔ rowMetaFieldNames(false)", () => {
+  test("key set matches the non-softDelete base row-meta columns exactly", () => {
+    expect(new Set(Object.keys(LIST_ROW_META_COLUMNS))).toEqual(new Set(rowMetaFieldNames(false)));
+  });
+});

package/src/engine/__tests__/boot-validator.test.ts

@@ -2,8 +2,11 @@ import { describe, expect, spyOn, test } from "bun:test";
 import { z } from "zod";
 import type { SchemaTable } from "../../db/dialect";
 import { table, text } from "../../db/dialect";
+import { rowMetaFieldNames } from "../../db/table-builder";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { validateBoot as validateBootRaw } from "../boot-validator";
+import { validateEntityListScreens } from "../boot-validator/entity-list-screens";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
   createDerivedField,
@@ -1953,6 +1956,117 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityList: row-meta columns (id/tenantId/version/...) ---
+  // Row-meta columns are real base-table columns, never declared entity
+  // fields — a SystemAdmin cross-tenant list exposes tenantId this way.
+  //
+  // Two separate boot-validators check entityList columns (validateScreens
+  // here, validateEntityListScreens in entity-list-screens.ts) — a #2601
+  // review found they'd drifted to accept different column sets, which
+  // would have let a softDelete column pass one gate and throw only in
+  // computeListViewModel at render time. Table-driven over
+  // LIST_ROW_META_COLUMNS (not one-off cases) so a future column added
+  // there is proven against BOTH validators automatically. Companion
+  // assertions: list.test.ts (headless renderer draws the same set) and
+  // list-row-meta-drift.test.ts (LIST_ROW_META_COLUMNS key-set drift guard).
+  describe("entityList row-meta column — accepted by both boot validators", () => {
+    function noteFeatureWithColumn(
+      columnName: string,
+      options?: { readonly softDelete?: boolean },
+    ) {
+      return defineFeature("notes", (r) => {
+        r.entity(
+          "note",
+          createEntity({ fields: { title: createTextField() }, softDelete: options?.softDelete }),
+        );
+        r.screen({
+          id: "note-list",
+          type: "entityList",
+          entity: "note",
+          columns: ["title", columnName],
+        });
+      });
+    }
+
+    for (const [columnName, columnType] of Object.entries(LIST_ROW_META_COLUMNS)) {
+      test(`"${columnName}" (${columnType}) on a non-softDelete entity → kein Throw`, () => {
+        const feature = noteFeatureWithColumn(columnName);
+        expect(() => validateBoot([feature])).not.toThrow();
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).not.toThrow();
+      });
+    }
+
+    // rowMetaFieldNames(true) also carries the softDelete-only columns
+    // (isDeleted/deletedAt/deletedById) — real base-table columns, but
+    // deliberately absent from LIST_ROW_META_COLUMNS because
+    // computeListViewModel can't render them. Both validators must reject
+    // them, or a softDelete column would pass boot and only throw at
+    // render-time.
+    const softDeleteOnlyColumns = [...rowMetaFieldNames(true)].filter(
+      (name) => LIST_ROW_META_COLUMNS[name] === undefined,
+    );
+    expect(softDeleteOnlyColumns.sort()).toEqual(["deletedAt", "deletedById", "isDeleted"]);
+
+    for (const columnName of softDeleteOnlyColumns) {
+      test(`"${columnName}" (softDelete-only, not renderable) → Throw on both validators`, () => {
+        const feature = noteFeatureWithColumn(columnName, { softDelete: true });
+        expect(() => validateBoot([feature])).toThrow(
+          new RegExp(`references field "${columnName}" which does not exist`),
+        );
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).toThrow(
+          new RegExp(`unknown column field "${columnName}"`),
+        );
+      });
+    }
+  });
+
+  // --- entityList: typo columns must still fail (row-meta acceptance is
+  // NOT a general gate-loosening) ---
+  //
+  // validateBoot only ever surfaces validateScreens' message here — it runs
+  // before validateEntityListScreens in the per-feature loop (see
+  // boot-validator/index.ts) and throws first. validateEntityListScreens'
+  // own "unknown column field" message is only reachable by calling it
+  // directly, which these tests also do.
+  describe("entityList typo column → Throw on both validators (not silently accepted)", () => {
+    const typoColumns = ["tenantID", "tenatId", "totallyMadeUp"];
+
+    for (const typo of typoColumns) {
+      test(`"${typo}" fails validateScreens (via validateBoot)`, () => {
+        const feature = defineFeature("notes", (r) => {
+          r.entity("note", createEntity({ fields: { title: createTextField() } }));
+          r.screen({
+            id: "note-list",
+            type: "entityList",
+            entity: "note",
+            columns: ["title", typo],
+          });
+        });
+        expect(() => validateBoot([feature])).toThrow(
+          new RegExp(`references field "${typo}" which does not exist`),
+        );
+      });
+
+      test(`"${typo}" fails validateEntityListScreens directly ("unknown column field")`, () => {
+        const feature = defineFeature("notes", (r) => {
+          r.entity("note", createEntity({ fields: { title: createTextField() } }));
+          r.screen({
+            id: "note-list",
+            type: "entityList",
+            entity: "note",
+            columns: ["title", typo],
+          });
+        });
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).toThrow(
+          new RegExp(`unknown column field "${typo}"`),
+        );
+      });
+    }
+  });
+
   // --- entityList: pagination + sort validation ---
   // Author-Fehler vor Production fangen, damit "Screen lädt nichts /
   // sortiert falsch / crasht beim Pager-Klick" nicht erst zur Laufzeit

package/src/engine/boot-validator/entity-list-screens.ts

@@ -1,9 +1,17 @@
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { normalizeListColumn } from "../screen-helpers";
 import type { EntityListScreenDefinition, FeatureDefinition } from "../types";
 
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
 export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
 
+// Same set computeListViewModel (headless) can actually render — NOT
+// db/table-builder's rowMetaFieldNames(softDelete), which also carries
+// isDeleted/deletedAt/deletedById. Accepting those here would let a
+// softDelete column pass the boot gate and then throw at render-time
+// because the renderer's LIST_ROW_META_COLUMNS doesn't know them.
+const LIST_ROW_META_COLUMN_NAMES = new Set(Object.keys(LIST_ROW_META_COLUMNS));
+
 function hasFilterableFields(feature: FeatureDefinition, entityName: string): boolean {
   const entities = feature.entities;
   if (!entities) return false;
@@ -71,7 +79,11 @@ function validateOneEntityListScreen(
     if (normalized.label === undefined) {
       const entity = feature.entities?.[screen.entity];
       const isDerived = entity?.derivedFields?.[normalized.field] !== undefined;
-      if (!entity?.fields[normalized.field] && !isDerived) {
+      // Row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) is a
+      // real base-table column without being a declared entity field — e.g.
+      // a SystemAdmin cross-tenant list exposing tenantId.
+      const isRowMeta = LIST_ROW_META_COLUMN_NAMES.has(normalized.field);
+      if (!entity?.fields[normalized.field] && !isDerived && !isRowMeta) {
         throw new Error(`${prefix}: unknown column field "${normalized.field}"`);
       }
     }

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

@@ -6,6 +6,7 @@
 
 import { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 import { rowMetaFieldNames } from "../../db/table-builder";
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
@@ -26,6 +27,15 @@ import type {
   ToolbarAction,
 } from "../types/screen";
 
+// entityList columns accept exactly the row-meta columns the renderer
+// (computeListViewModel) knows how to type — LIST_ROW_META_COLUMNS, NOT the
+// wider rowMetaFieldNames(softDelete) used below for rowAction payload/visible
+// field refs. Those two checks guard different things: a screen column must
+// be renderable, a payload/visible field reference only needs to exist on the
+// row. Using the wider set here would let a softDelete column like
+// "deletedAt" pass the boot gate and then throw at render-time instead.
+const LIST_ROW_META_COLUMN_NAMES = new Set(Object.keys(LIST_ROW_META_COLUMNS));
+
 // entityList and projectionList both allow a rowAction to double as the
 // row-body click target (rowClick: true, fw#1708/#2164) — at most one per
 // screen, or the renderer can't tell which one should fire.
@@ -1036,14 +1046,23 @@ export function validateScreens(
       }
       for (const col of screen.columns) {
         const normalized = normalizeListColumn(col);
+        // A row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) is a
+        // real DB column without being a declared entity field — e.g. a
+        // SystemAdmin cross-tenant list exposing tenantId. Accept it like a
+        // regular field name — but only the columns computeListViewModel can
+        // actually render (LIST_ROW_META_COLUMN_NAMES), not the wider
+        // softDelete-aware rowMeta set used below for payload/visible refs.
+        //
         // A virtual presentational column (drawn by a columnRenderer component
         // from the row, e.g. tag chips) needs BOTH a label AND a renderer —
         // renderer is what actually makes it "virtual" (label alone still
         // needs list.ts's virtual-branch to have something to draw; without
         // a renderer the column would render nothing). A column with neither
-        // matching a real field NOR a renderer is a typo worth failing the boot.
+        // matching a real field/row-meta column NOR a renderer is a typo worth
+        // failing the boot.
         if (
           !columnFieldNames.has(normalized.field) &&
+          !LIST_ROW_META_COLUMN_NAMES.has(normalized.field) &&
           !(normalized.label !== undefined && normalized.renderer !== undefined)
         ) {
           throw new Error(

package/src/pipeline/multi-stream-apply-context.ts

@@ -11,10 +11,10 @@ export type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-st
 
 export type MultiStreamApplyContextDeps = {
   readonly registry: Registry;
-  // TX-scoped DbRunner — the same `tx` the applyFn receives as the 2nd
-  // arg. ctx.appendEvent + inline-projections run inside this tx so a
-  // throw rolls the whole hop back (consumer retries the triggering
-  // event on the next pass).
+  // Same DbRunner the applyFn receives as its 2nd arg. In the server's MSP
+  // consumer wiring (api/server.ts) that's the unbound pool, not the
+  // dispatcher's cursor tx — a throw does NOT roll back appends/inline
+  // projections already made; apply must be idempotent for the retry.
   readonly db: DbRunner;
   // tenantId + userId of the TRIGGERING event. appendEvent stamps these
   // onto the new event so the causal chain stays tenant-consistent and

package/src/ui-types/index.ts

@@ -107,3 +107,5 @@ export type {
   QualifiedContentCollection,
   WorkspaceSchema,
 } from "./app-schema";
+export type { ListRowMetaColumnType } from "./list-row-meta";
+export { LIST_ROW_META_COLUMNS } from "./list-row-meta";

package/src/ui-types/list-row-meta.ts

@@ -0,0 +1,25 @@
+// Base row-meta columns (id/tenantId/version/insertedAt/modifiedAt/
+// insertedById/modifiedById) exist on every entity table without being
+// declared entity fields (see rowMetaFieldNames in db/table-builder.ts).
+// computeListViewModel needs a type + sortable hint per column when a screen
+// picks one of these as a list column (e.g. a SystemAdmin cross-tenant view
+// exposing tenantId). This stays a plain string map instead of importing
+// db/table-builder directly, so headless (client bundle) doesn't pull
+// drizzle in through this type-only subpath. list-row-meta-drift.test.ts
+// guards the key set against drift from rowMetaFieldNames(false).
+//
+// Deliberately excludes the softDelete-only columns (isDeleted/deletedAt/
+// deletedById) — this is also the SAME set the boot-validator's entityList
+// column checks accept, so a softDelete column stays a boot-time error
+// instead of a renderer-side throw (see screens.ts / entity-list-screens.ts).
+export type ListRowMetaColumnType = "text" | "number" | "timestamp";
+
+export const LIST_ROW_META_COLUMNS: Readonly<Record<string, ListRowMetaColumnType>> = {
+  id: "text",
+  tenantId: "text",
+  version: "number",
+  insertedAt: "timestamp",
+  modifiedAt: "timestamp",
+  insertedById: "text",
+  modifiedById: "text",
+};