@cosmicdrift/kumiko-framework 0.56.1 → 0.57.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.56.1",
+  "version": "0.57.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>",

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

@@ -2,6 +2,7 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { asRawClient } from "../../db/query";
 import { createBooleanField, createEntity, createTextField } from "../../engine";
 import { append, createEventsTable } from "../../event-store";
+import type { EntityCache } from "../../pipeline/entity-cache";
 import {
   createTestDb,
   type TestDb,
@@ -285,3 +286,48 @@ describe("event-store-executor — detail liefert die Stream-Version", () => {
     expect(updated.isSuccess).toBe(true);
   });
 });
+
+describe("event-store-executor — entity cache read-through", () => {
+  // In-memory stand-in for EntityCache — no Redis needed.
+  const store = new Map<string, Record<string, unknown>>();
+  const entityCache: EntityCache = {
+    get: async (tenantId, name, id) => store.get(`${tenantId}:${name}:${id}`) ?? null,
+    mget: async () => new Map(),
+    set: async (tenantId, name, id, data) => {
+      store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    mset: async (tenantId, name, entries) => {
+      for (const { id, data } of entries) store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    del: async (tenantId, name, id) => {
+      store.delete(`${tenantId}:${name}:${id}`);
+    },
+  };
+  const cachedCrud = createEventStoreExecutor(table, entity, {
+    entityName: "esExecUser",
+    entityCache,
+  });
+
+  beforeEach(() => store.clear());
+
+  test("first detail populates cache; second detail is served from cache", async () => {
+    const created = await cachedCrud.create({ email: "cache@test.de" }, adminUser, tdb);
+    if (!created.isSuccess) throw new Error("create failed");
+    const id = created.data.id;
+    const storeKey = `${adminUser.tenantId}:esExecUser:${id}`;
+
+    // create() calls del() — cache must be empty after create.
+    expect(store.has(storeKey)).toBe(false);
+
+    // First detail: miss → DB → populates cache.
+    const first = await cachedCrud.detail({ id }, adminUser, tdb);
+    expect(first).not.toBeNull();
+    expect(store.has(storeKey)).toBe(true);
+
+    // Poison the cache entry — proves the second detail reads from cache, not DB.
+    store.set(storeKey, { ...store.get(storeKey)!, email: "from-cache@test.de" });
+
+    const second = await cachedCrud.detail({ id }, adminUser, tdb);
+    expect(second?.["email"]).toBe("from-cache@test.de");
+  });
+});

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

@@ -361,6 +361,54 @@ describe("boot-validator", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
+  // --- Write-handler entity-mapping (smart tryMapEntity + extension preSave) ---
+
+  test("accepts bare CRUD write handler when feature name matches entity", () => {
+    const features = [
+      defineFeature("credit", (r) => {
+        r.entity("credit", createEntity({ table: "Credits", fields: { name: createTextField() } }));
+        r.writeHandler(
+          "create",
+          z.object({ name: z.string() }),
+          async () => ({
+            isSuccess: true as const,
+            data: { id: "1" },
+          }),
+          { access: { openToAll: true } },
+        );
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+    expect(features[0]?.handlerEntityMappings["create"]).toBe("credit");
+  });
+
+  test("throws when extension preSave targets entity with no mapped write handlers", () => {
+    const ext = defineFeature("cap-ext", (r) => {
+      r.extendsRegistrar("credit-cap", {
+        hooks: {
+          preSave: async (changes) => changes,
+        },
+      });
+    });
+    const consumer = defineFeature("money-horse", (r) => {
+      r.requires("cap-ext");
+      r.entity("credit", createEntity({ table: "Credits", fields: { name: createTextField() } }));
+      r.writeHandler(
+        "doSomething",
+        z.object({}),
+        async () => ({
+          isSuccess: true as const,
+          data: {},
+        }),
+        { access: { openToAll: true } },
+      );
+      r.useExtension("credit-cap", "credit");
+    });
+    expect(() => validateBoot([ext, consumer])).toThrow(
+      /no write handler is entity-mapped to "credit"/i,
+    );
+  });
+
   // --- Handler access validation (default-deny) ---
 
   test("throws when a write handler has no access rule", () => {

package/src/engine/__tests__/engine.test.ts

@@ -404,7 +404,7 @@ describe("createRegistry", () => {
       });
     });
 
-    expect(() => createRegistry([feature])).toThrow(/hr:write:promote.*not mapped.*entity:action/i);
+    expect(() => createRegistry([feature])).toThrow(/hr:write:promote.*not mapped.*entity:verb/i);
   });
 
   test("allows unmapped write handlers when feature has no field-access rules", () => {

package/src/engine/__tests__/extends-registrar.test.ts

@@ -98,6 +98,29 @@ describe("extendsRegistrar", () => {
     expect(entity?.fields["customData"]?.type).toBe("text");
   });
 
+  test("extension preSave hooks fire for bare CRUD handler with smart entity map", () => {
+    const preSaveFn = mock(async (changes: Record<string, unknown>) => changes);
+
+    const ext = defineFeature("audit", (r) => {
+      r.extendsRegistrar("audited", {
+        hooks: { preSave: preSaveFn },
+      });
+    });
+    const consumer = defineFeature("credit", (r) => {
+      r.requires("audit");
+      r.entity("credit", createEntity({ table: "Credits", fields: { name: createTextField() } }));
+      r.writeHandler("create", z.object({ name: z.string() }), async () => ({
+        isSuccess: true as const,
+        data: { id: "c1" },
+      }));
+      r.useExtension("audited", "credit");
+    });
+
+    const registry = createRegistry([ext, consumer]);
+    const hooks = registry.getPreSaveHooks("credit:write:create");
+    expect(hooks.length).toBeGreaterThan(0);
+  });
+
   test("extension preSave hooks fire for entity-scoped handlers", () => {
     const preSaveFn = mock(async (changes: Record<string, unknown>) => changes);
 

package/src/engine/boot-validator/entity-handler.ts

@@ -53,6 +53,42 @@ export const PII_USER_OWNED_NAME_HINTS: ReadonlySet<string> = new Set([
   "notes",
 ]);
 
+// --- Extension preSave wiring validation ---
+
+/** Extensions with preSave must target an entity that has mapped write handlers. */
+export function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void {
+  const extensionsWithPreSave = new Set<string>();
+  for (const f of features) {
+    for (const [extName, def] of Object.entries(f.registrarExtensions ?? {})) {
+      if (def.hooks?.preSave) extensionsWithPreSave.add(extName);
+    }
+  }
+  // skip: no extensions declare preSave hooks — nothing to validate
+  if (extensionsWithPreSave.size === 0) return;
+
+  const entitiesWithMappedWrites = new Set<string>();
+  for (const f of features) {
+    for (const [handlerName, entityName] of Object.entries(f.handlerEntityMappings ?? {})) {
+      if (handlerName in (f.writeHandlers ?? {})) {
+        entitiesWithMappedWrites.add(entityName);
+      }
+    }
+  }
+
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (!extensionsWithPreSave.has(usage.extensionName)) continue;
+      if (!entitiesWithMappedWrites.has(usage.entityName)) {
+        throw new Error(
+          `Feature "${f.name}" uses extension "${usage.extensionName}" with preSave on entity "${usage.entityName}" ` +
+            `but no write handler is entity-mapped to "${usage.entityName}". ` +
+            `Use create/update/delete on a matching entity or name the handler "entity:verb".`,
+        );
+      }
+    }
+  }
+}
+
 // --- Handler access validation ---
 
 // Rate-limit modes that bucket per user.id. Anonymous endpoints would put

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

@@ -16,6 +16,7 @@ import {
   validateEncryptedFields,
   validateEntityIndexes,
   validateExtendSchemaCollisions,
+  validateExtensionPreSaveWiring,
   validateFileFields,
   validateHandlerAccess,
   validateLocatedTimestamps,
@@ -158,6 +159,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
 
   validateNavCycles(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
+  validateExtensionPreSaveWiring(features);
 
   if (hasEncryptedFields && !process.env["ENCRYPTION_KEY"]) {
     throw new Error("ENCRYPTION_KEY environment variable is required (encrypted fields in use)");

package/src/engine/config-helpers.ts

@@ -1,4 +1,5 @@
 import type { ConfigScope } from "./constants";
+import { SYSTEM_ROLE } from "./system-user";
 import type {
   ConfigBacking,
   ConfigBounds,
@@ -27,6 +28,13 @@ export const access = {
   authenticated: ["User", "Admin", "SystemAdmin"] as readonly string[], // @cast-boundary schema-walk
   anonymous: ["anonymous"] as readonly string[], // @cast-boundary schema-walk
   roles: (...roles: string[]): readonly string[] => roles,
+  // Tenant self-service roles PLUS the system actor — for tenant-scope keys a
+  // tenant edits itself (configEdit) but that provisioning/migration/jobs must
+  // also set via ctx.systemWriteAs (roles = [SYSTEM_ROLE]). Stays human-writable
+  // because checkWriteAccess only collapses to system-only when system is the
+  // SOLE writer (humanWriters empty). Composes any preset, so apps with custom
+  // roles get the same provisioning path (issue #396).
+  withSystem: (roles: readonly string[]): readonly string[] => [SYSTEM_ROLE, ...roles],
 } as const;
 
 // --- Config Key Options ---

package/src/engine/define-feature.ts

@@ -170,14 +170,30 @@ export function defineFeature<const TName extends string, TExports = undefined>(
   let envSchema: z.ZodObject<z.ZodRawShape> | undefined;
 
   // Map handler name to entity via colon convention.
-  // "task:create" → entity "task". No colon → standalone handler, no mapping.
+  // "task:create" → entity "task". Bare CRUD verbs (create/update/delete) map
+  // when feature name matches an entity or the feature owns exactly one entity.
+  const CRUD_VERBS = new Set(["create", "update", "delete"]);
+
   function tryMapEntity(handlerName: string): void {
     const colonIdx = handlerName.indexOf(":");
-    // skip: handler name is not entity-scoped (no colon), nothing to map
-    if (colonIdx < 0) return;
-    const candidate = handlerName.slice(0, colonIdx);
-    if (entities[candidate]) {
-      handlerEntityMappings[handlerName] = candidate;
+    if (colonIdx >= 0) {
+      const candidate = handlerName.slice(0, colonIdx);
+      if (entities[candidate]) {
+        handlerEntityMappings[handlerName] = candidate;
+      }
+      // skip: colon-prefixed handler processed (mapped or not), bare CRUD path not applicable
+      return;
+    }
+    if (CRUD_VERBS.has(handlerName)) {
+      if (entities[name]) {
+        handlerEntityMappings[handlerName] = name;
+        // skip: feature-name entity match is the preferred mapping
+        return;
+      }
+      const entityKeys = Object.keys(entities);
+      if (entityKeys.length === 1) {
+        handlerEntityMappings[handlerName] = entityKeys[0] as string;
+      }
     }
   }
 

package/src/engine/index.ts

@@ -6,6 +6,7 @@ export {
   validateAppCustomScreenWriteQns,
   validateBoot,
 } from "./boot-validator";
+export { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler";
 export { buildAppSchema } from "./build-app-schema";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema";
 export {

package/src/engine/registry.ts

@@ -980,23 +980,20 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
 
   // Validate: handlers in features with field-access rules must be entity-mapped.
   // Without entity mapping, field-level access checks are silently skipped (security gap).
-  // Convention: "entityName.action" = entity-bound (must resolve), "action" = standalone (no filter).
   for (const feature of features) {
     if (!hasFieldAccessRules(feature)) continue;
 
-    // Write handlers: ALL must be entity-mapped (security-critical, writes need field-access checks)
     for (const handlerName of Object.keys(feature.writeHandlers ?? {})) {
       const qualified = qualify(feature.name, "write", handlerName);
       if (!handlerEntityMap.has(qualified)) {
         throw new Error(
           `Write handler "${qualified}" is not mapped to any entity, but feature "${feature.name}" has field-level access rules. ` +
-            `Name must follow "entity:action" convention (e.g. "user:create") so field-access checks apply.`,
+            `Name must follow "entity:verb" convention (e.g. "user:create") or use create/update/delete on a matching entity.`,
         );
       }
     }
 
-    // Query handlers: only those with a dash must resolve (typo protection).
-    // No dash = standalone query (dashboard, stats) — intentionally not entity-bound.
+    // Query handlers: only those with a colon must resolve (typo protection).
     for (const handlerName of Object.keys(feature.queryHandlers ?? {})) {
       if (!handlerName.includes(":")) continue;
       const qualified = qualify(feature.name, "query", handlerName);
@@ -1009,6 +1006,27 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
     }
   }
 
+  // Extension preSave: useExtension on an entity must have at least one mapped write handler.
+  const extensionsWithPreSave = new Set<string>();
+  for (const f of features) {
+    for (const [extName, def] of Object.entries(f.registrarExtensions ?? {})) {
+      if (def.hooks?.preSave) extensionsWithPreSave.add(extName);
+    }
+  }
+  for (const usage of extensionUsages) {
+    if (!extensionsWithPreSave.has(usage.extensionName)) continue;
+    const hasMapped = [...writeHandlerMap.keys()].some(
+      (qn) => handlerEntityMap.get(qn) === usage.entityName,
+    );
+    if (!hasMapped) {
+      throw new Error(
+        `Feature "${usage.featureName}" uses extension "${usage.extensionName}" with preSave on entity "${usage.entityName}" ` +
+          `but no write handler is entity-mapped to "${usage.entityName}". ` +
+          `Use create/update/delete on a matching entity or name the handler "entity:verb".`,
+      );
+    }
+  }
+
   // Validate: all relation targets must reference existing entities
   for (const [entityName, rels] of relationMap) {
     for (const [relName, rel] of Object.entries(rels)) {