@cosmicdrift/kumiko-framework 0.156.2 → 0.157.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.156.2",
+  "version": "0.157.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>",
@@ -193,7 +193,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.156.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.157.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/{raw-table.integration.test.ts → store-table.integration.test.ts}

@@ -1,5 +1,5 @@
-// Integration test for r.rawTable() — proves the full boot path:
-// defineFeature declares a raw table → setupTestStack auto-pushes it →
+// Integration test for r.storeTable() — proves the full boot path:
+// defineFeature declares a store table → setupTestStack auto-pushes it →
 // INSERT/SELECT against the real DB roundtrip. Plan reference:
 // kumiko-platform/docs/plans/architecture/table-ddl-guard.md (Stufe 3).
 
@@ -9,7 +9,7 @@ import { asRawClient, insertOne, selectMany } from "../db/query";
 import { defineFeature } from "../engine";
 import { setupTestStack, type TestStack, unsafePushTables } from "../stack";
 
-// External-system payload cache — the textbook r.rawTable() use case:
+// External-system payload cache — the textbook r.storeTable() use case:
 // write-only by an integration handler, read-only by a query, never
 // event-sourced (the data isn't a domain fact, it's a side-effect
 // snapshot).
@@ -23,7 +23,7 @@ const stripeWebhookCacheMeta = defineUnmanagedTable({
 });
 
 const webhookCacheFeature = defineFeature("webhook-cache", (r) => {
-  r.rawTable(stripeWebhookCacheMeta, {
+  r.storeTable(stripeWebhookCacheMeta, {
     reason: "external Stripe webhook payload cache — write-only by webhook handler",
   });
 });
@@ -38,7 +38,7 @@ afterAll(async () => {
   await stack.cleanup();
 });
 
-describe("r.rawTable — DB roundtrip via setupTestStack", () => {
+describe("r.storeTable — DB roundtrip via setupTestStack", () => {
   test("table is auto-pushed and accepts INSERT + SELECT", async () => {
     const eventId = "evt_test_123";
     const payload = JSON.stringify({ type: "invoice.paid", amount: 4200 });
@@ -52,8 +52,8 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     expect(rows[0]?.receivedAt).toBeInstanceOf(Temporal.Instant);
   });
 
-  test("registry exposes the raw table with its reason and featureName", () => {
-    const all = stack.registry.getAllRawTables();
+  test("registry exposes the store table with its reason and featureName", () => {
+    const all = stack.registry.getAllStoreTables();
     const entry = all.get("rt_int_stripe_webhook_cache");
     expect(entry).toBeDefined();
     expect(entry?.featureName).toBe("webhook-cache");
@@ -62,9 +62,9 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
   });
 
   test("INSERT bypasses the event store — no kumiko_events row produced", async () => {
-    // Proves that the rawTable lives outside the event-sourcing graph:
+    // Proves that the storeTable lives outside the event-sourcing graph:
     // a write to it shouldn't append anything to kumiko_events. If a
-    // future regression accidentally routed raw-table writes through
+    // future regression accidentally routed store-table writes through
     // the executor, a row would show up here.
     const before = await asRawClient(stack.db).unsafe<{ count: string }>(
       `SELECT COUNT(*)::text AS count FROM kumiko_events`,
@@ -84,7 +84,7 @@ describe("r.rawTable — DB roundtrip via setupTestStack", () => {
     expect(afterCount).toBe(beforeCount);
   });
 
-  test("a second push on the same rawTable is idempotent — CREATE IF NOT EXISTS", async () => {
+  test("a second push on the same storeTable is idempotent — CREATE IF NOT EXISTS", async () => {
     // unsafePushTables uses CREATE TABLE IF NOT EXISTS — idempotent by design.
     await expect(
       unsafePushTables(stack.db, { idem: stripeWebhookCacheMeta }),

package/src/api/__tests__/batch.integration.test.ts

@@ -15,6 +15,7 @@ import {
   type SaveContext,
 } from "../../engine";
 import { UnprocessableError, writeFailure } from "../../errors";
+import { RedisKeys } from "../../pipeline/redis-keys";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
 
 // Entity: a simple "item" with name + counter
@@ -370,6 +371,73 @@ describe("POST /api/batch", () => {
     expect(inTxHookLog).toHaveLength(1);
     expect(afterCommitHookLog).toHaveLength(1);
   });
+
+  test("idempotency: failed batch is cached — retry returns same error without re-exec", async () => {
+    const requestId = "batch-rid-fail-cache";
+    const commands = [
+      { type: "batch:write:item:create", payload: { name: "should-rollback" } },
+      { type: "batch:write:item:fail", payload: { name: "stop" } },
+    ];
+
+    const first = await stack.http.batch(commands, admin, requestId);
+    const firstBody = await first.json();
+    expect(first.status).toBe(422);
+    expect(firstBody.isSuccess).toBe(false);
+    expect(firstBody.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["should-rollback"]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+
+    inTxHookLog.length = 0;
+    afterCommitHookLog.length = 0;
+
+    const second = await stack.http.batch(commands, admin, requestId);
+    const secondBody = await second.json();
+    expect(second.status).toBe(422);
+    expect(secondBody.isSuccess).toBe(false);
+    expect(secondBody.failedIndex).toBe(firstBody.failedIndex);
+    // HTTP re-serializes the cached failure with a fresh requestId/timestamp —
+    // pin the stable business fields, not the transport envelope.
+    expect(secondBody.error.code).toBe(firstBody.error.code);
+    expect(secondBody.error.details).toEqual(firstBody.error.details);
+    // Cached path must not re-run commands (hooks stay empty, DB empty)
+    expect(inTxHookLog).toHaveLength(0);
+    expect(afterCommitHookLog).toHaveLength(0);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+  });
+
+  test("idempotency: corrupted cache entry is treated as miss and re-runs", async () => {
+    const requestId = "batch-rid-corrupt";
+    await stack.redis.redis.set(`${RedisKeys.idempotency}${requestId}`, "{not-json", "EX", 60);
+
+    const res = await stack.http.batch(
+      [{ type: "batch:write:item:create", payload: { name: "after-corrupt" } }],
+      admin,
+      requestId,
+    );
+    const body = await res.json();
+    expect(res.status).toBe(200);
+    expect(body.isSuccess).toBe(true);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["after-corrupt"]);
+  });
+
+  test("mid-batch handler throw: rolls back prior writes, afterCommit does not fire", async () => {
+    const res = await stack.http.batch(
+      [
+        { type: "batch:write:item:create", payload: { name: "before-throw" } },
+        { type: "batch:write:item:throw", payload: { name: "boom" } },
+        { type: "batch:write:item:create", payload: { name: "never" } },
+      ],
+      admin,
+    );
+    const body = await res.json();
+    expect(body.isSuccess).toBe(false);
+    expect(body.failedIndex).toBe(1);
+    expect(inTxHookLog.map((h) => h.name)).toEqual(["before-throw"]);
+    expect(afterCommitHookLog).toEqual([]);
+    expect(await selectMany(stack.db, itemTable)).toHaveLength(0);
+    expect(await selectMany(stack.db, auditTable)).toHaveLength(0);
+  });
 });
 
 describe("POST /api/write (single write runs in its own transaction)", () => {

package/src/db/__tests__/collect-table-metas.test.ts

@@ -20,7 +20,7 @@ const counterTable = table("read_unit_counters", {
 }) as unknown as SchemaTable;
 
 describe("collectTableMetas (#255)", () => {
-  test("collects entity, projection, MSP and rawTable tables — same sources as the test-stack auto-push", () => {
+  test("collects entity, projection, MSP and storeTable tables — same sources as the test-stack auto-push", () => {
     const feature = defineFeature("test", (r) => {
       r.entity("unit", exampleEntity());
       r.projection({
@@ -39,16 +39,16 @@ describe("collectTableMetas (#255)", () => {
       });
       // side-effect-only MSP — no table, must be skipped without throwing
       r.multiStreamProjection({ name: "unit-notify", apply: { "unit.created": async () => {} } });
-      r.rawTable(
+      r.storeTable(
         defineUnmanagedTable({
           tableName: "unit_cache",
           columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true }],
         }),
         { reason: "test fixture" },
       );
-      r.rawTable(
+      r.storeTable(
         defineUnmanagedTable({
-          tableName: "read_unit_log",
+          tableName: "store_unit_log",
           columns: [{ name: "id", pgType: "serial", notNull: true, primaryKey: true }],
         }),
         { reason: "test fixture" },
@@ -59,8 +59,8 @@ describe("collectTableMetas (#255)", () => {
     expect(names).toContain("read_units"); // entity
     expect(names).toContain("read_unit_counters"); // r.projection
     expect(names).toContain("read_unit_audit"); // r.multiStreamProjection
-    expect(names).toContain("unit_cache"); // r.rawTable
-    expect(names).toContain("read_unit_log"); // r.rawTable (second registration)
+    expect(names).toContain("unit_cache"); // r.storeTable
+    expect(names).toContain("store_unit_log"); // r.storeTable (second registration)
     expect(names).toHaveLength(5);
   });
 

package/src/db/__tests__/entity-table-meta-source.test.ts

@@ -0,0 +1,50 @@
+// #1210: buildEntityTableMeta() hardcoded source: "managed", so unmanaged
+// direct-write stores (store_user_sessions, store_api_tokens, mail sync/seen
+// cursors) were misclassified as rebuildable event-sourced projections — a
+// destructive column change would DROP+rebuild-from-events tables that have
+// no events, wiping live data. The options.source escape hatch must produce
+// a byte-identical column/piiSubjectFields shape (only source differs), so
+// the migration diff for an existing table stays empty when flipping it.
+
+import { describe, expect, test } from "bun:test";
+import { createEntity, createTextField } from "../../engine";
+import { buildEntityTableMeta } from "../entity-table-meta";
+import { diffSnapshots, snapshotFromMetas } from "../migrate-generator";
+
+const entity = createEntity({
+  table: "source-probe",
+  fields: {
+    userId: createTextField({ required: true }),
+    ip: createTextField({ userOwned: { ownerField: "userId" } }),
+  },
+});
+
+describe("buildEntityTableMeta — options.source (#1210)", () => {
+  test("defaults to managed when omitted", () => {
+    expect(buildEntityTableMeta("source-probe", entity).source).toBe("managed");
+  });
+
+  test("options.source: 'unmanaged' changes only source, columns + piiSubjectFields stay identical", () => {
+    const managed = buildEntityTableMeta("source-probe", entity);
+    const unmanaged = buildEntityTableMeta("source-probe", entity, { source: "unmanaged" });
+
+    expect(managed.source).toBe("managed");
+    expect(unmanaged.source).toBe("unmanaged");
+    expect(unmanaged.columns).toEqual(managed.columns);
+    expect(unmanaged.indexes).toEqual(managed.indexes);
+    expect(unmanaged.piiSubjectFields).toEqual(managed.piiSubjectFields);
+    expect(unmanaged.piiSubjectFields).toEqual(["ip"]);
+  });
+
+  test("flipping an existing table's meta to unmanaged produces an empty migration diff", () => {
+    const prevSnapshot = snapshotFromMetas([buildEntityTableMeta("source-probe", entity)]);
+    const nextSnapshot = snapshotFromMetas([
+      buildEntityTableMeta("source-probe", entity, { source: "unmanaged" }),
+    ]);
+
+    const diff = diffSnapshots(prevSnapshot, nextSnapshot);
+    expect(diff.newTables).toEqual([]);
+    expect(diff.droppedTables).toEqual([]);
+    expect(diff.changedTables).toEqual([]);
+  });
+});

package/src/db/__tests__/feature-table-sources.test.ts

@@ -1,10 +1,10 @@
-// Regression test for #255-class drift: rawTables must appear in
+// Regression test for #255-class drift: storeTables must appear in
 // enumerateFeatureTableSources so setupTestStack's auto-push and
 // collectTableMetas see the exact same table set. Before this fix,
 // unmanaged tables were only handled by collectTableMetas directly, so any
 // app relying on setupTestStack's ephemeral DB (Playwright/e2e) never got
-// its raw tables created — e.g. the bundled "sessions" feature's
-// read_user_sessions, breaking every login in an ephemeral test stack.
+// its store tables created — e.g. the bundled "sessions" feature's
+// store_user_sessions, breaking every login in an ephemeral test stack.
 
 import { describe, expect, test } from "bun:test";
 import { defineFeature } from "../../engine/define-feature";
@@ -16,10 +16,10 @@ const probeMeta = defineUnmanagedTable({
   columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
 });
 
-describe("enumerateFeatureTableSources — rawTables", () => {
-  test("includes a feature's rawTable as a table source", () => {
+describe("enumerateFeatureTableSources — storeTables", () => {
+  test("includes a feature's storeTable as a table source", () => {
     const feature = defineFeature("probe", (r) => {
-      r.rawTable(probeMeta, { reason: "direct-write store" });
+      r.storeTable(probeMeta, { reason: "direct-write store" });
     });
     const sources = enumerateFeatureTableSources(feature);
     const entry = sources.find((s) => s.origin.includes("ftst_probe"));
@@ -27,7 +27,7 @@ describe("enumerateFeatureTableSources — rawTables", () => {
     expect(entry?.table).toBe(probeMeta);
   });
 
-  test("a feature with no rawTable contributes nothing extra", () => {
+  test("a feature with no storeTable contributes nothing extra", () => {
     const feature = defineFeature("plain", () => {});
     expect(enumerateFeatureTableSources(feature)).toEqual([]);
   });

package/src/db/collect-table-metas.ts

@@ -1,7 +1,7 @@
 // collectTableMetas — kanonische ENTITY_METAS-Quelle für `kumiko schema
 // generate`. Erfasst dieselben Tabellen-Quellen wie der setupTestStack-
-// auto-push (entities, rawTables, projections, multiStreamProjections) —
-// die frühere Template-Variante sammelte nur entities + rawTables, wodurch
+// auto-push (entities, storeTables, projections, multiStreamProjections) —
+// die frühere Template-Variante sammelte nur entities + storeTables, wodurch
 // projection-only-Tabellen (z.B. billing-foundation read_subscriptions) nie
 // in Migrations landeten und der erste Prod-Write crashte (#255).
 
@@ -59,11 +59,11 @@ export function collectTableMetas(
       metas.push(meta);
       byName.set(meta.tableName, { meta, origin: `entity "${name}" (${feature.name})` });
     }
-    for (const entry of Object.values(feature.rawTables)) {
+    for (const entry of Object.values(feature.storeTables)) {
       metas.push(entry.meta);
       byName.set(entry.meta.tableName, {
         meta: entry.meta,
-        origin: `rawTable "${entry.name}" (${feature.name})`,
+        origin: `storeTable "${entry.name}" (${feature.name})`,
       });
     }
   }

package/src/db/entity-table-meta.ts

@@ -95,7 +95,7 @@ export type EntityTableMeta = {
   // discriminator nutzen um Warnungen zu rendern ("X tables are unmanaged").
   readonly source: "managed" | "unmanaged";
   // PII-Subject-annotated field names (pii/userOwned/tenantOwned). Set by
-  // buildEntityTableMeta so the registry can reject r.rawTable stores
+  // buildEntityTableMeta so the registry can reject r.storeTable stores
   // whose direct writes would skip the executor's encryption (#820).
   readonly piiSubjectFields?: readonly string[];
 };
@@ -296,6 +296,7 @@ export function resolveTableName(
 export type BuildEntityTableMetaOptions = {
   readonly featureName?: string;
   readonly relations?: EntityRelations;
+  readonly source?: "managed" | "unmanaged";
 };
 
 export function buildEntityTableMeta(
@@ -415,7 +416,7 @@ export function buildEntityTableMeta(
     tableName,
     columns,
     indexes,
-    source: "managed",
+    source: options?.source ?? "managed",
     ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }
@@ -431,8 +432,8 @@ export function buildEntityTableMeta(
 // jede neue defineUnmanagedTable-Stelle prüfen.
 //
 // Heutige use-cases im framework:
-//   - `read_delivery_attempts` — id kommt aus dem Aggregate-Stream
-//   - `read_job_run_logs` — child-table, serial PK, kein tenant-scope
+//   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
+//   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
 export type UnmanagedTableInput = {
   readonly tableName: string;
   readonly columns: readonly ColumnMeta[];

package/src/db/feature-table-sources.ts

@@ -1,5 +1,5 @@
 // Single enumeration of every table-bearing registration on a feature
-// (r.projection, r.multiStreamProjection with table, r.rawTable).
+// (r.projection, r.multiStreamProjection with table, r.storeTable).
 // Consumed by BOTH the setupTestStack auto-push and collectTableMetas —
 // one list, so test-DB-push and `kumiko schema generate` cannot drift
 // apart again (#255).
@@ -29,8 +29,8 @@ export function enumerateFeatureTableSources(
       origin: `multiStreamProjection "${name}" (${feature.name})`,
     });
   }
-  for (const [name, raw] of Object.entries(feature.rawTables)) {
-    sources.push({ table: raw.meta, origin: `rawTable "${name}" (${feature.name})` });
+  for (const [name, raw] of Object.entries(feature.storeTables)) {
+    sources.push({ table: raw.meta, origin: `storeTable "${name}" (${feature.name})` });
   }
   return sources;
 }

package/src/db/queries/shadow-swap.ts

@@ -207,7 +207,7 @@ export async function assertNoUnreachableLiveRows(
     `projection-rebuild "${projectionName}": ${countLabel} live rows in "${tableName}" have no ` +
       `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
       `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
-      `without emitting a .created event. Fix: register the table with r.rawTable(meta, ` +
+      `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
       `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
       `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`,
   );

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

@@ -1297,6 +1297,102 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- function-renderer check on the non-entityEdit/entityList screen
+  // types that share the same EditLayout/ListColumnSpec shapes
+  // (action-wiring.ts's validateEditLayoutNoFunctions/validateColumnsNoFunctions) ---
+  describe("function-renderer check on other EditLayout/columns screens", () => {
+    test("actionForm field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "restock",
+            type: "actionForm",
+            handler: "shop:write:restock",
+            fields: { qty: { type: "number" } } as never,
+            layout: {
+              sections: [
+                { fields: [{ field: "qty", renderer: (v: unknown) => String(v) }] as never },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(actionForm\) field "qty" renderer is a function/,
+      );
+    });
+
+    test("configEdit field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.config({
+            keys: { "site-name": createTenantConfig("text", { default: "" }) },
+          });
+          r.screen({
+            id: "settings",
+            type: "configEdit",
+            scope: "tenant",
+            configKeys: { siteName: "shop:config:site-name" },
+            fields: { siteName: { type: "text" } } as never,
+            layout: {
+              sections: [
+                {
+                  fields: [{ field: "siteName", renderer: (v: unknown) => String(v) }] as never,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(configEdit\) field "siteName" renderer is a function/,
+      );
+    });
+
+    test("projectionDetail field renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "order-detail",
+            type: "projectionDetail",
+            query: "shop:query:order-detail",
+            layout: {
+              sections: [
+                { fields: [{ field: "total", renderer: (v: unknown) => String(v) }] as never },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(projectionDetail\) field "total" renderer is a function/,
+      );
+    });
+
+    test("dashboard list-panel column renderer as a function → Throw", () => {
+      const features = [
+        defineFeature("shop", (r) => {
+          r.screen({
+            id: "overview",
+            type: "dashboard",
+            panels: [
+              {
+                kind: "list",
+                id: "recent-orders",
+                label: "Recent Orders",
+                query: "shop:query:recent-orders",
+                columns: [{ field: "total", renderer: (v: unknown) => String(v) }] as never,
+              },
+            ],
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /\(dashboard-list\) column "total" renderer is a function/,
+      );
+    });
+  });
+
   // --- entityList virtual (labeled) columns ---
   // A column whose `field` is not an entity field is allowed IF it carries a
   // `label` — a presentational column drawn by a columnRenderer component (e.g.