@cosmicdrift/kumiko-framework 0.262.0 → 0.264.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.262.0",
+  "version": "0.264.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>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.262.0",
+    "@cosmicdrift/kumiko-types": "0.264.0",
     "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.262.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.264.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "version": "0.263.0",
+    "type": "breaking",
+    "title": "ctx.queryAs/ctx.writeAs with a SYSTEM identity only from r.systemScope(), jobs, or a handler/hook declaring escapeHatch (fw#2859).",
+    "detail": "Switching identity to SYSTEM (a SessionUser whose id is SYSTEM_USER_ID or whose roles contain SYSTEM_ROLE, e.g. `createSystemUser(...)`) through `HandlerContext.queryAs`/`writeAs` now throws `AccessDeniedError` (code `access_denied`, `details.reason` `system_identity_switch_denied`) unless the calling handler belongs to an `r.systemScope()` feature or declares `escapeHatch: { reason }`. The grant is looked up per handler type in the registry and never propagates: a handler reached through another handler's `writeAs(SYSTEM)` needs its own declaration for its own SYSTEM switches. `queryAs`/`writeAs` with a non-system user stays ungated and runs under that user's access. `JobContext.queryAs`/`writeAs` and top-level `dispatcher.write`/`query` (es-ops `systemWriteAs`, extraRoutes) stay ungated. Lifecycle hooks no longer inherit the grant of the handler they fire on: `r.hook(type, target, fn, { escapeHatch })` is the per-hook declaration; hooks contributed through `r.extendsRegistrar` are always denied; `r.authClaims` hooks' `queryAs` denies SYSTEM. `escapeHatch` is now also accepted on query handlers (`QueryHandlerDef`/`QueryHandlerDefinition`/`r.queryHandler` options); the boot validator rejects an empty reason there too, and `r.hook` throws at registration on an empty reason. Static boot-time detection of SYSTEM switches is not possible (handlers are closures), so enforcement is at runtime.",
+    "migration": "Find every `ctx.queryAs(...)`/`ctx.writeAs(...)` whose user is `createSystemUser(...)` or otherwise carries `SYSTEM_ROLE` (also indirectly through helpers that receive `ctx`). For each, add `escapeHatch: { reason: \"<which SYSTEM lookup/write and why the caller's own identity cannot do it>\" }` to the write or query handler definition that ends up calling it (`r.writeHandler`/`r.queryHandler` options, `defineWriteHandler`/`defineQueryHandler`), or move the logic into an `r.systemScope()` feature or a job when that is the correct owner. Handlers of `r.systemScope()` features need nothing. A lifecycle hook doing a SYSTEM switch through its runtime HandlerContext passes `{ escapeHatch: { reason } }` as `r.hook`'s options (postSave/postDelete: next to `phase`). `escapeHatch` on a write handler also permits `ctx.db.global()` writes. Consumer call sites to audit at release: solon 15, offlot-app 14, kumiko-enterprise 5 `queryAs`/`writeAs` sites."
+  },
+  {
+    "version": "0.263.0",
+    "type": "breaking",
+    "title": "Forms are prefilled from URL query parameters only for fields a declarative `navigate` action declares as `params` (fw#2852).",
+    "detail": "`buildAppSchema` now derives `urlPrefillFields` per actionForm/secretMint/entityEdit-create screen from every navigate `params` that targets it — entityList/projectionList rowActions, projectionDetail/entityEdit actions, relatedList rowActions, and projectionDetail metrics; a form nothing targets takes nothing from the URL. Previously any query parameter matching a field name was taken, so a crafted link could seed e.g. an IBAN or e-mail field. Declared params keep working. `sensitive` and `format: \"password\"` fields are still never prefilled — not from the URL, an allowlist, or a handoff.",
+    "migration": "Code that prefills a form via `nav.navigate` + `nav.setSearchParams` without a declared `params` (known: publicstatus `custom-field-list`, phronexsis `driver-map-node-panel`, kumiko-enterprise ai-agent `openForm` client tool / `agentPrefill=1`) must switch to a declared `navigate` action with `params`, or — for programmatic prefill — to `useNavigateWithInitialValues()` from `@cosmicdrift/kumiko-renderer`. No codemod."
+  },
+  {
+    "version": "0.263.0",
+    "type": "improvement",
+    "title": "New `useNavigateWithInitialValues()` hands a form screen initial values in memory instead of the query string (fw#2852).",
+    "detail": "`useNavigateWithInitialValues()`, exported from `@cosmicdrift/kumiko-renderer`, returns `(target: ScreenTarget, initialValues: Readonly<Record<string, unknown>>) => void`, which navigates to a form screen and carries the initial values in memory rather than as URL search params — for programmatic prefill outside a declared `navigate` `params` action. `sensitive` and `format: \"password\"` fields are still never prefilled, same as URL and allowlist prefill."
+  },
+  {
+    "version": "0.263.0",
+    "type": "fix",
+    "title": "`projectField`/`projectEntity` now forward field metadata the client schema previously dropped (fw#2852).",
+    "detail": "`projectField`/`projectEntity` (`packages/framework/src/engine/build-app-schema.ts`) now forward number `unit`, entity `defaultCurrency`, text `format`, timestamp `locatedBy`, file/image `accept`/`maxSize`/`variants`, decimal `scale` (incl. embedded sub-fields), and `sensitive` into the client schema; previously they were lost on the way, so the unit suffix did not render, money fields fell back to \"EUR\", password masking and the never-prefill-sensitive rule were inactive client-side."
+  },
   {
     "version": "0.262.0",
     "type": "improvement",

package/src/engine/__tests__/build-app-schema-url-prefill.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import { buildAppSchema } from "../build-app-schema";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import type { EntityDefinition } from "../types/fields";
+import type { ScreenDefinition } from "../types/screen";
+
+const leaseEntity = {
+  fields: { name: { type: "text" }, iban: { type: "text" } },
+} as unknown as EntityDefinition;
+const itemEntity = {
+  fields: { leaseId: { type: "text" }, note: { type: "text" } },
+} as unknown as EntityDefinition;
+
+const leasesFeature = defineFeature("leases", (r) => {
+  r.entity("lease", leaseEntity);
+  r.entity("item", itemEntity);
+  r.screen({
+    id: "lease-list",
+    type: "entityList",
+    entity: "lease",
+    columns: ["name"],
+    rowActions: [
+      {
+        kind: "navigate",
+        id: "add-item",
+        label: "add",
+        screen: "item-create",
+        params: { map: { leaseId: "id" } },
+      },
+      {
+        kind: "navigate",
+        id: "pay",
+        label: "pay",
+        screen: "record-payment",
+        params: { pick: ["name"] },
+      },
+      {
+        kind: "navigate",
+        id: "edit",
+        label: "edit",
+        screen: "lease-edit",
+        params: { pick: ["iban"] },
+      },
+      {
+        kind: "drawer",
+        id: "note",
+        label: "note",
+        screen: "drawer-only-form",
+        params: { pick: ["note"] },
+      },
+    ],
+  });
+  r.screen({
+    id: "lease-edit",
+    type: "entityEdit",
+    entity: "lease",
+    layout: { sections: [{ title: "x", fields: ["name", "iban"] }] },
+    actions: [
+      {
+        kind: "navigate",
+        id: "pay-party",
+        label: "pay",
+        screen: "record-payment",
+        params: { map: { partyId: "id" } },
+      },
+    ],
+  });
+  r.screen({
+    id: "lease-detail",
+    type: "projectionDetail",
+    query: "leases:query:lease:detail",
+    layout: { sections: [] },
+    metrics: [
+      {
+        field: "openItems",
+        label: "items",
+        navigate: { screen: "item-create", params: { map: { note: "summary" } } },
+      },
+    ],
+  });
+  r.screen({
+    id: "item-create",
+    type: "entityEdit",
+    entity: "item",
+    layout: { sections: [{ title: "x", fields: ["leaseId", "note"] }] },
+  });
+  r.screen({
+    id: "record-payment",
+    type: "actionForm",
+    handler: "leases:write:payment:record",
+    fields: { name: { type: "text" }, partyId: { type: "text" }, iban: { type: "text" } },
+    layout: { sections: [{ title: "x", fields: ["name", "partyId", "iban"] }] },
+    urlPrefillFields: ["iban"],
+  } as ScreenDefinition);
+  r.screen({
+    id: "drawer-only-form",
+    type: "actionForm",
+    handler: "leases:write:item:note",
+    fields: { note: { type: "text" } },
+    layout: { sections: [{ title: "x", fields: ["note"] }] },
+  });
+});
+
+const billingFeature = defineFeature("billing", (r) => {
+  r.entity("invoice", { fields: { payee: { type: "text" } } } as unknown as EntityDefinition);
+  r.screen({
+    id: "invoice-list",
+    type: "entityList",
+    entity: "invoice",
+    columns: ["payee"],
+    rowActions: [
+      {
+        kind: "navigate",
+        id: "pay",
+        label: "pay",
+        screen: "record-payment",
+        params: { map: { name: "payee" } },
+      },
+    ],
+  });
+});
+
+function urlPrefillFieldsOf(featureName: string, screenId: string): unknown {
+  const app = buildAppSchema(createRegistry([leasesFeature, billingFeature]));
+  const screen = app.features
+    .find((f) => f.featureName === featureName)
+    ?.screens.find((s) => s.id.endsWith(`:${screenId}`) || s.id === screenId);
+  if (screen === undefined) throw new Error(`screen ${featureName}/${screenId} not projected`);
+  return "urlPrefillFields" in screen ? screen.urlPrefillFields : undefined;
+}
+
+describe("buildAppSchema — urlPrefillFields derived from navigate params", () => {
+  test("a cross-entity entityEdit-create target gets exactly the declared params keys", () => {
+    expect(urlPrefillFieldsOf("leases", "item-create")).toEqual(["leaseId", "note"]);
+  });
+
+  test("keys from several sources and features are unioned; an authored value is overwritten", () => {
+    expect(urlPrefillFieldsOf("leases", "record-payment")).toEqual(["name", "partyId"]);
+  });
+
+  test("a form no navigate params targets gets an empty list — drawer params do not count", () => {
+    expect(urlPrefillFieldsOf("leases", "drawer-only-form")).toEqual([]);
+  });
+
+  test("a same-entity entityEdit target opens in update mode and gets no URL prefill", () => {
+    expect(urlPrefillFieldsOf("leases", "lease-edit")).toEqual([]);
+  });
+
+  test("non-form screens carry no urlPrefillFields", () => {
+    expect(urlPrefillFieldsOf("leases", "lease-list")).toBeUndefined();
+  });
+});

package/src/engine/__tests__/build-app-schema.test.ts

@@ -420,10 +420,10 @@ describe("buildAppSchema", () => {
       "default", // array-valued for multiSelect — projectField's
       // isJsonSafeValue() (fw#2497) now recurses into arrays/plain
       // objects instead of only string/number/boolean/null.
+      "sensitive", // write-response redaction server-side AND the renderer's prefill block
     ] as const;
 
     const SERVER_ONLY_KEYS = [
-      "sensitive", // controls write-response redaction, never rendered
       "access", // server-side authz check, not a renderer concern
       "pii", // PII classification, drives crypto/storage — not client-relevant
       "userOwned", // same: subject-key annotation, server/crypto-only
@@ -582,6 +582,95 @@ describe("buildAppSchema", () => {
     expect(fields["avatar"]?.["capture"]).toBeUndefined();
   });
 
+  test("number unit (static and sibling-field form) and entity defaultCurrency survive the projection", () => {
+    // Regression: the edit view-model reads `unit` and `entity.defaultCurrency`,
+    // but the client schema never carried them — the suffix never rendered and
+    // money fields always fell back to "EUR".
+    const entity = {
+      defaultCurrency: "USD",
+      fields: {
+        distance: { type: "number", unit: "mi" },
+        mileage: { type: "number", unit: { field: "mileageUnit" } },
+        mileageUnit: { type: "text" },
+        count: { type: "number" },
+        bogus: { type: "number", unit: { field: () => "km" } },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const projected = app.features[0]!.entities["thing"] as unknown as {
+      defaultCurrency?: string;
+      fields: Record<string, Record<string, unknown>>;
+    };
+
+    expect(projected.defaultCurrency).toBe("USD");
+    expect(projected.fields["distance"]?.["unit"]).toBe("mi");
+    expect(projected.fields["mileage"]?.["unit"]).toEqual({ field: "mileageUnit" });
+    expect(projected.fields["count"]?.["unit"]).toBeUndefined();
+    expect(projected.fields["bogus"]?.["unit"]).toBeUndefined();
+    expect(JSON.parse(JSON.stringify(projected))).toEqual(projected);
+  });
+
+  test("entity without defaultCurrency omits the key", () => {
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", { fields: { label: { type: "text" } } } as unknown as EntityDefinition);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    expect("defaultCurrency" in app.features[0]!.entities["thing"]!).toBe(false);
+  });
+
+  test("text format, timestamp locatedBy, file accept/maxSize, image variants and decimal scale survive the projection", () => {
+    // Regression: all of these are read by the edit view-model (password
+    // masking, wall-clock input, upload constraints, preview variant, derived
+    // embedded-cell rounding) but were missing from the client schema.
+    const entity = {
+      fields: {
+        secret: { type: "text", format: "password" },
+        pickupAt: { type: "timestamp", locatedBy: "pickupTz" },
+        pickupTz: { type: "tz" },
+        contract: { type: "file", accept: ["application/pdf"], maxSize: "5mb" },
+        photo: {
+          type: "image",
+          accept: ["image/*"],
+          maxSize: "10mb",
+          variants: { thumb: { fit: "cover", size: { width: 120, height: 120 } } },
+        },
+        positions: {
+          type: "embedded",
+          multiple: true,
+          schema: { price: { type: "decimal", scale: 2 } },
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    expect(fields["secret"]?.["format"]).toBe("password");
+    expect(fields["pickupAt"]?.["locatedBy"]).toBe("pickupTz");
+    expect(fields["contract"]?.["accept"]).toEqual(["application/pdf"]);
+    expect(fields["contract"]?.["maxSize"]).toBe("5mb");
+    expect(fields["photo"]?.["accept"]).toEqual(["image/*"]);
+    expect(fields["photo"]?.["variants"]).toEqual({
+      thumb: { fit: "cover", size: { width: 120, height: 120 } },
+    });
+    const positionsSchema = fields["positions"]?.["schema"] as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(positionsSchema["price"]?.["scale"]).toBe(2);
+  });
+
   test("embedded: minItems/maxItems/derived/totals/totalsMatch überleben die Projection (fw#2497)", () => {
     // Regression: `totals` carries "Renderer metadata: numeric sub-field
     // names to sum in a totals row" in its own doc-comment but was never

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

@@ -1,6 +1,26 @@
 import { describe, expect, mock, test } from "bun:test";
 import { z } from "zod";
-import { createEntity, createRegistry, createTextField, defineFeature } from "../index";
+import { AccessDeniedError } from "../../errors";
+import { createGatedIdentitySwitch, type QueryAsFn } from "../../pipeline/system-identity-switch";
+import {
+  createEntity,
+  createRegistry,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+} from "../index";
+import type { AppContext, SaveContext } from "../types";
+import type { TenantId } from "../types/identifiers";
+
+const TENANT = "00000000-0000-4000-8000-00000000ee01" as TenantId;
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "vehicle-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
 
 describe("extendsRegistrar", () => {
   test("r.useExtension records usage with name, entity, and options", () => {
@@ -132,7 +152,7 @@ describe("extendsRegistrar", () => {
     expect(hooks.length).toBeGreaterThan(0);
   });
 
-  test("extension preSave hooks fire for entity-scoped handlers", () => {
+  test("extension preSave hooks fire for entity-scoped handlers", async () => {
     const preSaveFn = mock(async (changes: Record<string, unknown>) => changes);
 
     const ext = defineFeature("audit", (r) => {
@@ -178,13 +198,19 @@ describe("extendsRegistrar", () => {
     const registry = createRegistry([ext, consumer]);
     const createHooks = registry.getPreSaveHooks("fleet:write:vehicle:create");
     expect(createHooks).toHaveLength(1);
-    expect(createHooks[0]).toBe(preSaveFn);
+    // Hook is wrapped for the SYSTEM gate (system-identity-switch.ts), so it's no longer reference-equal to preSaveFn.
+    const preSaveContext = { previous: {}, isNew: true } as AppContext & {
+      previous: Readonly<Record<string, unknown>>;
+      isNew: boolean;
+    };
+    await createHooks[0]?.({ name: "x" }, preSaveContext);
+    expect(preSaveFn).toHaveBeenCalledTimes(1);
 
     const updateHooks = registry.getPreSaveHooks("fleet:write:vehicle:update");
     expect(updateHooks).toHaveLength(1);
   });
 
-  test("extension postSave hooks are entity hooks", () => {
+  test("extension postSave hooks are entity hooks", async () => {
     const postSaveFn = mock(async () => {});
 
     const ext = defineFeature("audit", (r) => {
@@ -202,6 +228,51 @@ describe("extendsRegistrar", () => {
     const registry = createRegistry([ext, consumer]);
     const hooks = registry.getEntityPostSaveHooks("vehicle");
     expect(hooks).toHaveLength(1);
-    expect(hooks[0]).toBe(postSaveFn);
+    await hooks[0]?.(dummySaveContext, {} as AppContext);
+    expect(postSaveFn).toHaveBeenCalledTimes(1);
+  });
+
+  test("extension postSave hook cannot switch identity to SYSTEM — no declaration site to opt in with", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    // Simulates a handler whose OWN grant is allow=true (escapeHatch or
+    // systemScope) — the extension hook must not inherit this.
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "fleet:write:vehicle:create"',
+      true,
+      ungated,
+    );
+
+    let caught: unknown;
+    const ext = defineFeature("audit", (r) => {
+      r.extendsRegistrar("audited", {
+        hooks: {
+          postSave: async (_result, ctx) => {
+            const asContext = ctx as unknown as { queryAs: QueryAsFn };
+            try {
+              await asContext.queryAs(createSystemUser(TENANT), "whoami", {});
+            } catch (err) {
+              caught = err;
+            }
+          },
+        },
+      });
+    });
+    const consumer = defineFeature("fleet", (r) => {
+      r.entity("vehicle", createEntity({ table: "Vehicles", fields: {} }));
+      r.useExtension("audited", "vehicle");
+    });
+
+    const registry = createRegistry([ext, consumer]);
+    const hooks = registry.getEntityPostSaveHooks("vehicle");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    expect(ungatedQueryAs).not.toHaveBeenCalled();
   });
 });

package/src/engine/__tests__/hook-identity-switch-grant.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, mock, test } from "bun:test";
+import { AccessDeniedError } from "../../errors";
+import { createGatedIdentitySwitch, type QueryAsFn } from "../../pipeline/system-identity-switch";
+import { createEntity, createRegistry, createSystemUser, defineFeature } from "../index";
+import type { AppContext, PostSaveHookFn, SaveContext } from "../types";
+import type { TenantId } from "../types/identifiers";
+
+// fw#2859: r.hook({ allOf }, ...) must get the same identity-switch gate as the handler-keyed path.
+
+const TENANT = "00000000-0000-4000-8000-00000000cd01" as TenantId;
+const systemUser = createSystemUser(TENANT);
+
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "thing-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+
+describe("r.hook({ allOf }, ...) identity-switch gate", () => {
+  test("entity-wide hook WITHOUT escapeHatch does not inherit the handler's SYSTEM grant", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    // Simulates a handler whose OWN grant is allow=true (e.g. it declared
+    // escapeHatch or is systemScope) — the hook must not inherit this.
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "test:write:thing:create"',
+      true,
+      ungated,
+    );
+
+    let caught: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { queryAs: QueryAsFn };
+        try {
+          await asContext.queryAs(systemUser, "whoami", {});
+        } catch (err) {
+          caught = err;
+        }
+      };
+      r.hook("postSave", { allOf: thing }, hookFn);
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    expect(ungatedQueryAs).not.toHaveBeenCalled();
+  });
+
+  test("entity-wide hook WITH escapeHatch reaches SYSTEM even when the handler's own grant was false", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "test:write:thing:create"',
+      false,
+      ungated,
+    );
+
+    let queryAsResult: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { queryAs: QueryAsFn };
+        queryAsResult = await asContext.queryAs(systemUser, "whoami", {});
+      };
+      r.hook("postSave", { allOf: thing }, hookFn, {
+        escapeHatch: { reason: "test: allOf hook needs SYSTEM" },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(queryAsResult).toBe("ok");
+    expect(ungatedQueryAs).toHaveBeenCalledWith(systemUser, "whoami", {});
+  });
+
+  test("registering an { allOf } hook with an empty escapeHatch reason throws at registration", () => {
+    expect(() => {
+      defineFeature("test", (r) => {
+        const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+        r.hook("postSave", { allOf: thing }, async () => undefined, {
+          escapeHatch: { reason: "" },
+        });
+      });
+    }).toThrow(/non-empty string/);
+  });
+});

package/src/engine/__tests__/hook-phases.test.ts

@@ -1,7 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, defineFeature, HookPhases } from "../index";
-import type { PostSaveHookFn } from "../types";
+import type { AppContext, PostSaveHookFn, SaveContext } from "../types";
+
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "thing-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+const dummyAppContext = {} as AppContext;
 
 // These tests lock in the phase defaults + filtering so the invariants survive
 // refactors. Behavior under test:
@@ -72,9 +82,15 @@ describe("HookPhases defaults", () => {
 });
 
 describe("Registry phase filtering", () => {
-  test("getPostSaveHooks filters by phase when given", () => {
-    const inTxFn: PostSaveHookFn = async () => undefined;
-    const afterFn: PostSaveHookFn = async () => undefined;
+  test("getPostSaveHooks filters by phase when given", async () => {
+    const inTxCalls: SaveContext[] = [];
+    const afterCalls: SaveContext[] = [];
+    const inTxFn: PostSaveHookFn = async (result) => {
+      inTxCalls.push(result);
+    };
+    const afterFn: PostSaveHookFn = async (result) => {
+      afterCalls.push(result);
+    };
 
     const feature = defineFeature("test", (r) => {
       r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -92,10 +108,18 @@ describe("Registry phase filtering", () => {
     const afterOnly = registry.getPostSaveHooks(handlerQn, HookPhases.afterCommit);
     const all = registry.getPostSaveHooks(handlerQn);
 
+    // Hooks are wrapped for the SYSTEM identity-switch gate (system-identity-
+    // switch.ts), so the stored fn is no longer reference-equal to the
+    // original — prove behaviour (calling the original) instead.
     expect(inTxOnly).toHaveLength(1);
-    expect(inTxOnly[0]).toBe(inTxFn);
+    await inTxOnly[0]?.(dummySaveContext, dummyAppContext);
+    expect(inTxCalls).toEqual([dummySaveContext]);
+    expect(afterCalls).toEqual([]);
+
     expect(afterOnly).toHaveLength(1);
-    expect(afterOnly[0]).toBe(afterFn);
+    await afterOnly[0]?.(dummySaveContext, dummyAppContext);
+    expect(afterCalls).toEqual([dummySaveContext]);
+
     expect(all).toHaveLength(2);
   });
 
@@ -114,9 +138,15 @@ describe("Registry phase filtering", () => {
     );
   });
 
-  test("getEntityPostSaveHooks filters by phase", () => {
-    const inTxFn: PostSaveHookFn = async () => undefined;
-    const afterFn: PostSaveHookFn = async () => undefined;
+  test("getEntityPostSaveHooks filters by phase", async () => {
+    const inTxCalls: SaveContext[] = [];
+    const afterCalls: SaveContext[] = [];
+    const inTxFn: PostSaveHookFn = async (result) => {
+      inTxCalls.push(result);
+    };
+    const afterFn: PostSaveHookFn = async (result) => {
+      afterCalls.push(result);
+    };
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -125,8 +155,18 @@ describe("Registry phase filtering", () => {
     });
 
     const registry = createRegistry([feature]);
-    expect(registry.getEntityPostSaveHooks("thing", HookPhases.inTransaction)).toEqual([inTxFn]);
-    expect(registry.getEntityPostSaveHooks("thing", HookPhases.afterCommit)).toEqual([afterFn]);
+    const inTxHooks = registry.getEntityPostSaveHooks("thing", HookPhases.inTransaction);
+    const afterHooks = registry.getEntityPostSaveHooks("thing", HookPhases.afterCommit);
+
+    expect(inTxHooks).toHaveLength(1);
+    await inTxHooks[0]?.(dummySaveContext, dummyAppContext);
+    expect(inTxCalls).toEqual([dummySaveContext]);
+    expect(afterCalls).toEqual([]);
+
+    expect(afterHooks).toHaveLength(1);
+    await afterHooks[0]?.(dummySaveContext, dummyAppContext);
+    expect(afterCalls).toEqual([dummySaveContext]);
+
     expect(registry.getEntityPostSaveHooks("thing")).toHaveLength(2);
   });
 });