@cosmicdrift/kumiko-framework 0.168.0 → 0.170.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.168.0",
+  "version": "0.170.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.168.0",
+    "@cosmicdrift/kumiko-types": "0.170.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.168.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.170.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -67,14 +67,19 @@ export function createWriteVerbs(
   } = ctx;
 
   return {
-    async create(payload, user, db) {
+    async create(payload, user, db, options) {
       // Respect an explicit id in the payload (seed pattern, SCIM import). Without
       // one the framework mints a fresh UUIDv7 via generateId. Strip it out of the
       // event payload so defaults + downstream consumers don't see a redundant id field.
       const explicitId = typeof payload["id"] === "string" ? (payload["id"] as string) : undefined; // @cast-boundary engine-payload
       const aggregateId = explicitId ?? generateId();
       const { id: _id, ...payloadWithoutId } = payload;
-      const data = applyDefaults(payloadWithoutId);
+      // preSave runs before ownership checks: authorization must evaluate the
+      // row as it will actually be persisted, including hook-derived fields
+      // (kumiko-framework#1672).
+      const data = options?.preSave
+        ? await options.preSave(applyDefaults(payloadWithoutId), {}, true)
+        : applyDefaults(payloadWithoutId);
 
       // H.2 — entity-level write-ownership on create. No oldRow exists, so
       // only the new row is checked. No Straddle concern for creates.
@@ -221,12 +226,19 @@ export function createWriteVerbs(
       const previous = await loadById(payload.id, db);
       if (!previous) return writeFailure(new NotFoundError(entityName, payload.id));
 
+      // preSave runs before ownership checks: authorization must evaluate the
+      // row as it will actually be persisted, including hook-derived fields
+      // (kumiko-framework#1672).
+      const changes = updateOptions?.preSave
+        ? await updateOptions.preSave(payload.changes, previous, false)
+        : payload.changes;
+
       // H.2 — entity-level write-ownership on update. Load old row (already
       // done above), build post-change row via shallow merge. Straddle-safe
       // multi-role check: at least one role must accept BOTH old and new —
       // prevents the attack where role A passes old, role B passes new and
       // aggregation would wrongly allow a row-grab.
-      const mergedNew: Record<string, unknown> = { ...previous, ...payload.changes };
+      const mergedNew: Record<string, unknown> = { ...previous, ...changes };
       if (!userCanWriteFieldRow(user, entity.access?.write, previous, mergedNew)) {
         return writeFailure(
           new UnprocessableError("ownership_denied", {
@@ -247,7 +259,7 @@ export function createWriteVerbs(
       // `previous`, we can run the ownership rules per field against both
       // sides and reject individual fields the user isn't entitled to
       // touch on this specific row.
-      const fieldDeniedUpdate = checkWriteFieldOwnership(entity, payload.changes, user, previous);
+      const fieldDeniedUpdate = checkWriteFieldOwnership(entity, changes, user, previous);
       if (fieldDeniedUpdate) {
         return writeFailure(
           new UnprocessableError("ownership_denied", {
@@ -303,11 +315,11 @@ export function createWriteVerbs(
         // ownerField — the merged row still names the subject.
         const submittedChanges = updateOptions?.skipUnchanged
           ? Object.fromEntries(
-              Object.entries(payload.changes).filter(
+              Object.entries(changes).filter(
                 ([key, value]) => !isUnchangedValue(value, previous[key]),
               ),
             )
-          : payload.changes;
+          : changes;
         const flatChangesPlain = flattenCompoundTypes(submittedChanges, entity);
         const flatChanges = await encryptForStorage(flatChangesPlain, user, {
           onlyKeys: Object.keys(submittedChanges),
@@ -368,7 +380,7 @@ export function createWriteVerbs(
             kind: "save",
             id: data["id"] as EntityId, // @cast-boundary engine-payload
             data,
-            changes: payload.changes,
+            changes,
             previous,
             isNew: false,
             entityName,

package/src/engine/__tests__/entity-presave-wiring.integration.test.ts

@@ -0,0 +1,97 @@
+// Regression coverage for kumiko-framework#1672 — preSave hooks were
+// registered and boot-validated but never invoked by the dispatch path,
+// making `r.hook("preSave", ...)` a silent no-op. This exercises the real
+// HTTP dispatcher (not a hand-fed handler context) so the fix is proven at
+// the layer app authors actually depend on.
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { asRawClient } from "../../db/query";
+import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+const contactEntity = createEntity({
+  table: "presave_wiring_contacts",
+  fields: {
+    firstName: createTextField({ required: true }),
+    lastName: createTextField({ required: true }),
+    displayName: createTextField(),
+  },
+});
+
+const seenIsNew: boolean[] = [];
+
+const deriveDisplayName: import("../types").PreSaveHookFn = async (changes, ctx) => {
+  seenIsNew.push(ctx.isNew);
+  const first =
+    (changes["firstName"] as string | undefined) ??
+    (ctx.previous["firstName"] as string | undefined);
+  const last =
+    (changes["lastName"] as string | undefined) ?? (ctx.previous["lastName"] as string | undefined);
+  return { ...changes, displayName: `${first ?? ""} ${last ?? ""}`.trim() };
+};
+
+const contactFeature = defineFeature("presave-wiring", (r) => {
+  r.crud("contact", contactEntity, {
+    write: { access: { roles: ["User"] } },
+    read: { access: { openToAll: true } },
+  });
+
+  // preSave has no entity-wide `{ allOf }` shorthand (unlike postSave/
+  // preDelete/postDelete) — r.crud registers separate create/update
+  // handlers, so both need their own target.
+  r.hook("preSave", "contact:create", deriveDisplayName);
+  r.hook("preSave", "contact:update", deriveDisplayName);
+});
+
+const CREATE = "presave-wiring:write:contact:create";
+const UPDATE = "presave-wiring:write:contact:update";
+
+describe("preSave hooks — real dispatcher path (#1672)", () => {
+  let stack: TestStack;
+
+  beforeAll(async () => {
+    stack = await setupTestStack({ features: [contactFeature] });
+    await unsafeCreateEntityTable(stack.db, contactEntity);
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+  });
+
+  beforeEach(async () => {
+    seenIsNew.length = 0;
+    await asRawClient(stack.db).unsafe("DELETE FROM kumiko_events");
+    await asRawClient(stack.db).unsafe('DELETE FROM "presave_wiring_contacts"');
+  });
+
+  test("create: preSave hook derives displayName before persistence", async () => {
+    const res = await stack.http.write(
+      CREATE,
+      { firstName: "Marc", lastName: "Ristone" },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const { data } = (await res.json()) as { data: { data: { displayName: string } } };
+    expect(data.data.displayName).toBe("Marc Ristone");
+    expect(seenIsNew).toEqual([true]);
+  });
+
+  test("update: preSave hook sees previous row and re-derives displayName", async () => {
+    const created = await stack.http.write(
+      CREATE,
+      { firstName: "Marc", lastName: "Ristone" },
+      TestUsers.user,
+    );
+    const { data } = (await created.json()) as { data: { data: { id: string; version: number } } };
+
+    const res = await stack.http.write(
+      UPDATE,
+      { id: data.data.id, version: data.data.version, changes: { lastName: "Kumiko" } },
+      TestUsers.user,
+    );
+    expect(res.status).toBe(200);
+    const { data: updated } = (await res.json()) as { data: { data: { displayName: string } } };
+    expect(updated.data.displayName).toBe("Marc Kumiko");
+    expect(seenIsNew).toEqual([true, false]);
+  });
+});

package/src/engine/entity-handlers.ts

@@ -182,7 +182,14 @@ export function defineEntityWriteHandler(
   switch (verb) {
     case "create":
       schema = buildInsertSchema(entity);
-      handler = async (event, ctx) => executor.create(event.payload as DbRow, event.user, ctx.db);
+      handler = async (event, ctx) => {
+        const { runPreSave } = ctx;
+        return executor.create(event.payload as DbRow, event.user, ctx.db, {
+          preSave:
+            runPreSave &&
+            ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
+        });
+      };
       break;
     case "update":
       schema = z.object({
@@ -190,16 +197,21 @@ export function defineEntityWriteHandler(
         version: z.number(),
         changes: buildUpdateSchema(entity),
       });
-      handler = async (event, ctx) =>
+      handler = async (event, ctx) => {
+        const { runPreSave } = ctx;
         // skipUnchanged (#464): API-driven updates diff against the stored
         // row so a resubmitted-but-identical field doesn't force a fresh
         // pii/encrypted ciphertext. Direct executor.update() callers (e.g.
         // KEK-rotation, the user-data-rights #494 backfill) don't go through
         // this handler and keep today's always-re-encrypt behavior, which
         // they rely on to intentionally force a fresh event/ciphertext.
-        executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
+        return executor.update(event.payload as UpdatePayload, event.user, ctx.db, {
           skipUnchanged: true,
+          preSave:
+            runPreSave &&
+            ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
         }); // @cast-boundary engine-payload
+      };
       break;
     case "delete":
       schema = idSchema;

package/src/pipeline/dispatch-shared.ts

@@ -154,7 +154,7 @@ export async function buildHandlerContext(
   afterCommitHooks?: AfterCommitHook[],
   includeDeleted?: boolean,
 ): Promise<HandlerContext> {
-  const { registry, appContext: context, effectiveFeatures, jobRunner } = ctx;
+  const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
   const isSystem = registry.isHandlerSystemScoped(type);
   // The outer dispatcher receives a DbConnection from the server/stack;
   // AppContext's `db` union also allows TenantDb (for downstream hook calls),
@@ -537,6 +537,18 @@ export async function buildHandlerContext(
     notify,
     ...(config && { config }),
     ...(files && { files }),
+    // preSave hooks need `changes`/`previous`/`isNew`, which only exist once
+    // a handler actually starts building its write — bound here so entity
+    // CRUD handlers (entity-handlers.ts) can forward it to the executor
+    // (kumiko-framework#1672).
+    ...(lifecycle && {
+      runPreSave: (
+        handlerName: string,
+        changes: Record<string, unknown>,
+        previous: Readonly<Record<string, unknown>>,
+        isNew: boolean,
+      ) => lifecycle.runPreSave(handlerName, changes, previous, isNew, context),
+    }),
     tracer,
     metrics,
     tz,