@cosmicdrift/kumiko-framework 0.154.1 → 0.154.2

package/package.json

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

package/src/__tests__/full-stack.integration.test.ts

@@ -182,7 +182,7 @@ const userFeature = defineFeature("users", (r) => {
     { access: { openToAll: true } },
   );
 
-  r.entityHook("postSave", user, async (result) => {
+  r.hook("postSave", { allOf: user }, async (result) => {
     featurePostSaveLog.push(result);
   });
 

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

@@ -81,9 +81,9 @@ const itemFeature = defineFeature("batch", (r) => {
   );
 
   // Entity hook: inTransaction — records in memory
-  r.entityHook(
+  r.hook(
     "postSave",
-    item,
+    { allOf: item },
     async (result: SaveContext) => {
       inTxHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
     },
@@ -92,9 +92,9 @@ const itemFeature = defineFeature("batch", (r) => {
 
   // Entity hook: inTransaction — writes to DB via ctx.db (the tx-scoped TenantDb).
   // Proves that hook DB writes roll back with the main transaction on failure.
-  r.entityHook(
+  r.hook(
     "postSave",
-    item,
+    { allOf: item },
     async (result, ctx) => {
       if (!ctx.db) return;
       await ctx.db.insertOne(auditTable, { action: "item_saved", itemId: result.id });
@@ -103,32 +103,32 @@ const itemFeature = defineFeature("batch", (r) => {
   );
 
   // Entity hook: afterCommit — records in memory (default phase)
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     afterCommitHookLog.push({ id: result.id, name: (result.data["name"] as string) ?? "" });
   });
 
   // Entity hook: afterCommit — may throw, used to verify error isolation
-  r.entityHook("postSave", item, async () => {
+  r.hook("postSave", { allOf: item }, async () => {
     if (afterCommitShouldThrow) throw new Error("afterCommit_boom");
   });
 
   // Entity hook: afterCommit — runs AFTER the throwing one. Used to prove the
   // next hooks still fire despite the earlier failure.
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     afterCommitThirdHookRan.push((result.data["name"] as string) ?? "");
   });
 
   // Two hooks used by the parallelism test. Each records its start+end
   // timestamps so the assertion can compare intervals rather than elapsed
   // wall-clock time (which is timing-flaky on loaded CI boxes).
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     const name = result.data["name"] as string;
     if (!name?.startsWith("slowness-")) return;
     parallelismWindows.push({ hook: "A", start: Date.now() });
     await new Promise((r) => setTimeout(r, 80));
     parallelismWindows.push({ hook: "A", end: Date.now() });
   });
-  r.entityHook("postSave", item, async (result: SaveContext) => {
+  r.hook("postSave", { allOf: item }, async (result: SaveContext) => {
     const name = result.data["name"] as string;
     if (!name?.startsWith("slowness-")) return;
     parallelismWindows.push({ hook: "B", start: Date.now() });

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

@@ -439,6 +439,22 @@ describe("createRegistry", () => {
     expect(all["profile:nav.title"]).toEqual({ de: "Profil", en: "Profile" });
   });
 
+  // #1105: a feature that already qualifies its own translation keys (nav
+  // labels referencing "featureName:..." verbatim, see cap-counter) must not
+  // be double-prefixed — else server-side t() can never resolve them.
+  test("does not double-prefix translation keys that already carry the feature's own namespace", () => {
+    const f = defineFeature("cap-counter", (r) => {
+      r.translations({
+        keys: { "cap-counter:nav.cap-list": { de: "Limits", en: "Caps" } },
+      });
+    });
+
+    const registry = createRegistry([f]);
+    const all = registry.getAllTranslations();
+    expect(all["cap-counter:nav.cap-list"]).toEqual({ de: "Limits", en: "Caps" });
+    expect(all["cap-counter:cap-counter:nav.cap-list"]).toBeUndefined();
+  });
+
   test("throws when write handler is not entity-mapped in feature with field-access", () => {
     const feature = defineFeature("hr", (r) => {
       r.entity(

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

@@ -59,11 +59,11 @@ describe("HookPhases defaults", () => {
     expect(entry?.[0]?.phase).toBe(HookPhases.inTransaction);
   });
 
-  test("entityHook postSave defaults to afterCommit, preDelete is forced inTransaction", () => {
+  test("hook({allOf}) postSave defaults to afterCommit, preDelete is forced inTransaction", () => {
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postSave", thing, noopSave);
-      r.entityHook("preDelete", thing, async () => undefined);
+      r.hook("postSave", { allOf: thing }, noopSave);
+      r.hook("preDelete", { allOf: thing }, async () => undefined);
     });
 
     expect(feature.entityHooks?.postSave?.["thing"]?.[0]?.phase).toBe(HookPhases.afterCommit);
@@ -120,8 +120,8 @@ describe("Registry phase filtering", () => {
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postSave", thing, inTxFn, { phase: HookPhases.inTransaction });
-      r.entityHook("postSave", thing, afterFn);
+      r.hook("postSave", { allOf: thing }, inTxFn, { phase: HookPhases.inTransaction });
+      r.hook("postSave", { allOf: thing }, afterFn);
     });
 
     const registry = createRegistry([feature]);

package/src/engine/__tests__/post-query-hook.test.ts

@@ -10,7 +10,7 @@ const stubContext = {} as unknown as AppContext;
 // postQuery-Hook (F1) — feuert nach Query-Handler-Execute, vor Field-Access-
 // Read-Filter. Zwei Registrierungs-Pfade:
 //   - r.hook("postQuery", "ns:query:list", fn) — handler-keyed
-//   - r.entityHook("postQuery", "thing", fn)   — entity-keyed (alle Queries)
+//   - r.hook("postQuery", { allOf: "thing" }, fn)   — entity-keyed (alle Queries)
 //
 // Diese Tests pinnen die Invarianten:
 //   1. Beide Registrierungs-Pfade landen in unabhängigen Maps
@@ -35,10 +35,10 @@ describe("postQuery hook registration", () => {
     expect(entry?.[0]?.featureName).toBe("test");
   });
 
-  test("r.entityHook('postQuery', entity, fn) lands in entity-keyed entityHooks map", () => {
+  test("r.hook('postQuery', { allOf: entity }, fn) lands in entity-keyed entityHooks map", () => {
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postQuery", thing, noop);
+      r.hook("postQuery", { allOf: thing }, noop);
     });
 
     const entry = feature.entityHooks?.postQuery?.["thing"];
@@ -52,8 +52,8 @@ describe("postQuery hook registration", () => {
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postQuery", thing, hookA);
-      r.entityHook("postQuery", thing, hookB);
+      r.hook("postQuery", { allOf: thing }, hookA);
+      r.hook("postQuery", { allOf: thing }, hookB);
     });
 
     expect(feature.entityHooks?.postQuery?.["thing"]).toHaveLength(2);
@@ -81,7 +81,7 @@ describe("Registry getters", () => {
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postQuery", thing, fn);
+      r.hook("postQuery", { allOf: thing }, fn);
     });
 
     const registry = createRegistry([feature]);
@@ -109,7 +109,7 @@ describe("Hook function semantics", () => {
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
-      r.entityHook("postQuery", thing, enrich);
+      r.hook("postQuery", { allOf: thing }, enrich);
     });
 
     const registry = createRegistry([feature]);

package/src/engine/__tests__/registrar-object-form.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "bun:test";
+import { defineFeature } from "../index";
+
+// Object-Form is the shape the feature-ast renderer emits for Designer/
+// AI-generated code (`r.entity({ name: "item", ... })` instead of
+// `r.entity("item", { ... })`) — see kumiko-framework#1113. The compile
+// checks in feature-ast/__tests__/render-roundtrip.test.ts prove the TYPES
+// line up; they never execute the runtime dispatch that unpacks Object-Form
+// back into the same state mutations as the positional form. These tests
+// cover that: one per distinct dispatch shape, asserting object-form and
+// positional-form produce identical FeatureDefinition state.
+
+describe("registrar Object-Form — runtime parity with positional form", () => {
+  test("requires: array-unwrap ({ features }) matches variadic-string form", () => {
+    const positional = defineFeature("a", (r) => {
+      r.requires("auth", "tenant");
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.requires({ features: ["auth", "tenant"] });
+    });
+    expect(objectForm.requires).toEqual(positional.requires);
+  });
+
+  test("optionalRequires: array-unwrap matches variadic-string form", () => {
+    const positional = defineFeature("a", (r) => {
+      r.optionalRequires("promotions");
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.optionalRequires({ features: ["promotions"] });
+    });
+    expect(objectForm.optionalRequires).toEqual(positional.optionalRequires);
+  });
+
+  test("readsConfig: array-unwrap ({ keys }) matches variadic-string form", () => {
+    const positional = defineFeature("a", (r) => {
+      r.readsConfig("auth.smtpHost");
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.readsConfig({ keys: ["auth.smtpHost"] });
+    });
+    expect(objectForm.configReads).toEqual(positional.configReads);
+  });
+
+  test("entity: split-name ({ name, ...fields }) matches (name, definition) form", () => {
+    const definition = { fields: { title: { type: "text" as const, required: true } } };
+    const positional = defineFeature("a", (r) => {
+      r.entity("item", definition);
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.entity({ name: "item", ...definition });
+    });
+    expect(objectForm.entities).toEqual(positional.entities);
+  });
+
+  test("metric: split-name matches (shortName, options) form", () => {
+    const positional = defineFeature("a", (r) => {
+      r.metric("created", { type: "counter" });
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.metric({ name: "created", type: "counter" });
+    });
+    expect(objectForm.metrics).toEqual(positional.metrics);
+  });
+
+  test("secret: split-name matches (shortName, options) form (same feature name for qualifiedName parity)", () => {
+    const positional = defineFeature("stripe", (r) => {
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    const objectForm = defineFeature("stripe", (r) => {
+      r.secret({ name: "apiKey", label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    expect(objectForm.secretKeys).toEqual(positional.secretKeys);
+  });
+
+  test("relation: two-field ({ entity, name, ...def }) matches (entity, name, definition) form", () => {
+    const definition = { type: "belongsTo" as const, target: "user", foreignKey: "supplierId" };
+    const positional = defineFeature("a", (r) => {
+      r.entity("item", { fields: {} });
+      r.relation("item", "supplier", definition);
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.entity("item", { fields: {} });
+      r.relation({ entity: "item", name: "supplier", ...definition });
+    });
+    expect(objectForm.relations).toEqual(positional.relations);
+  });
+
+  test("referenceData: two-field ({ entity, data, ...opts }) matches (entity, data, options) form", () => {
+    const data = [{ id: "a", label: "A" }];
+    const positional = defineFeature("a", (r) => {
+      r.referenceData("category", data, { upsertKey: "id" });
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.referenceData({ entity: "category", data, upsertKey: "id" });
+    });
+    expect(objectForm.referenceData).toEqual(positional.referenceData);
+  });
+
+  test("useExtension: two-field ({ name, entity, ...opts }) matches (extensionName, entity, options) form", () => {
+    const positional = defineFeature("a", (r) => {
+      r.useExtension("audit-log", "item", { verbose: true });
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.useExtension({ name: "audit-log", entity: "item", verbose: true });
+    });
+    expect(objectForm.extensionUsages).toEqual(positional.extensionUsages);
+  });
+
+  test("claimKey: generic split-name matches (shortName, options) form", () => {
+    const positional = defineFeature("drivers", (r) => {
+      r.claimKey("teamId", { type: "string" });
+    });
+    const objectForm = defineFeature("drivers", (r) => {
+      r.claimKey({ name: "teamId", type: "string" });
+    });
+    expect(objectForm.claimKeys).toEqual(positional.claimKeys);
+  });
+
+  test("job: full-definition object matches (name, options, handler) form", () => {
+    const handler = async () => {};
+    const positional = defineFeature("a", (r) => {
+      r.job("reconcile", { trigger: { manual: true } }, handler);
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.job({ name: "reconcile", trigger: { manual: true }, handler });
+    });
+    expect(objectForm.jobs).toEqual(positional.jobs);
+  });
+
+  test("notification: split-name matches (name, definition) form", () => {
+    const recipient = () => null;
+    const data = () => ({});
+    const positional = defineFeature("a", (r) => {
+      r.notification("itemLowStock", { trigger: { on: "item:lowStock" }, recipient, data });
+    });
+    const objectForm = defineFeature("b", (r) => {
+      r.notification({ name: "itemLowStock", trigger: { on: "item:lowStock" }, recipient, data });
+    });
+    expect(objectForm.notifications).toEqual(positional.notifications);
+  });
+});

package/src/engine/define-feature.ts

@@ -18,6 +18,20 @@ import type { RequiresApi } from "./types/feature";
 // that don't care can keep the default-string and use the wrapper-based
 // strict-mode (string-literal types per call-site) like before.
 
+// requires/optionalRequires accept either variadic strings (hand-written
+// call sites) or a single `{ features }` object (the feature-ast renderer's
+// canonical Object-Form for Designer/AI-generated code) — see the matching
+// overloads on RequiresApi / FeatureRegistrar['optionalRequires'].
+function resolveFeatureNamesArgs(
+  args: readonly [{ readonly features: readonly string[] }] | readonly string[],
+): readonly string[] {
+  const [first] = args;
+  if (typeof first === "object" && first !== null && "features" in first) {
+    return first.features;
+  }
+  return args as readonly string[];
+}
+
 export function defineFeature<const TName extends string, TExports = undefined>(
   name: TName,
   setup: (r: FeatureRegistrar<TName>) => TExports,
@@ -40,8 +54,10 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       state.description = text.trim();
     },
     requires: (() => {
-      const fn = (...featureNames: string[]) => {
-        state.requires.push(...featureNames);
+      const fn = (
+        ...args: readonly [{ readonly features: readonly string[] }] | readonly string[]
+      ) => {
+        state.requires.push(...resolveFeatureNamesArgs(args));
       };
       fn.projection = (tableName: string) => {
         state.requiredProjections.add(tableName);
@@ -51,8 +67,10 @@ export function defineFeature<const TName extends string, TExports = undefined>(
       };
       return fn as RequiresApi;
     })(),
-    optionalRequires(...featureNames: string[]): void {
-      state.optionalRequires.push(...featureNames);
+    optionalRequires(
+      ...args: readonly [{ readonly features: readonly string[] }] | readonly string[]
+    ): void {
+      state.optionalRequires.push(...resolveFeatureNamesArgs(args));
     },
     toggleable(options: { default: boolean }): void {
       if (state.toggleableDefault !== undefined) {

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -86,9 +86,9 @@ defineFeature("todoList", (r) => {
     },
   });
 
-  r.entityHook({
+  r.hook({
     type: "postDelete",
-    entity: "task",
+    target: { allOf: "task" },
     handler: async (event, ctx) => {
       console.log("task deleted");
     },
@@ -220,7 +220,6 @@ describe("Canonical Object-Form — parser akzeptiert + extrahiert", () => {
       "writeHandler",
       "queryHandler",
       "hook",
-      "entityHook",
       "job",
       "notification",
       "authClaims",
@@ -260,12 +259,14 @@ describe("Canonical Object-Form — parser akzeptiert + extrahiert", () => {
     });
   });
 
-  test("entityHook Pattern: type + entity aus Object-Form", () => {
-    const entityHook = result.patterns.find((p) => p.kind === "entityHook");
+  test("hook Pattern: entity-wide { allOf } target aus Object-Form", () => {
+    const entityHook = result.patterns.find(
+      (p) => p.kind === "hook" && p.hookType === "postDelete",
+    );
     expect(entityHook).toMatchObject({
-      kind: "entityHook",
+      kind: "hook",
       hookType: "postDelete",
-      entityName: "task",
+      target: { allOf: "task" },
     });
   });
 

package/src/engine/feature-ast/__tests__/parse-happy-path.test.ts

@@ -71,7 +71,7 @@ defineFeature("todoList", (r) => {
     console.log("task saved");
   });
 
-  r.entityHook("postDelete", "task", async (event, ctx) => {
+  r.hook("postDelete", { allOf: "task" }, async (event, ctx) => {
     console.log("task deleted");
   });
 
@@ -136,7 +136,6 @@ describe("parseSourceFile against a complete inline-form feature", () => {
       "writeHandler",
       "queryHandler",
       "hook",
-      "entityHook",
       "metric",
       "secret",
       "claimKey",

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -68,7 +68,7 @@ const FEATURES: readonly RealFeature[] = [
   {
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
-    recognisedKinds: ["entityHook", "writeHandler", "queryHandler"],
+    recognisedKinds: ["hook", "writeHandler", "queryHandler"],
     errorMethodNames: ["unmanagedTable", "job"],
   },
   {

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -784,29 +784,43 @@ defineFeature("f", (r) => {
   });
 });
 
-describe("extractEntityHook", () => {
-  test("captures hookType, entity and the function body", () => {
+describe("extractHook — entity-wide { allOf } target", () => {
+  test("captures hookType and the allOf entity from positional form", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.entityHook("postSave", "task", (event, ctx) => {});
+  r.hook("postSave", { allOf: "task" }, (event, ctx) => {});
 });
 `);
 
     expect(result.patterns[0]).toMatchObject({
-      kind: "entityHook",
+      kind: "hook",
       hookType: "postSave",
-      entityName: "task",
+      target: { allOf: "task" },
     });
   });
 
-  test("rejects validation as entity-hook type (only postSave/preDelete/postDelete allowed)", () => {
+  test("captures hookType and the allOf entity from object form", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
-  r.entityHook("validation", "task", () => {});
+  r.hook({ type: "postDelete", target: { allOf: "task" }, handler: () => {} });
 });
 `);
 
-    expect(result.errors[0]?.methodName).toBe("entityHook");
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      hookType: "postDelete",
+      target: { allOf: "task" },
+    });
+  });
+
+  test("rejects a malformed allOf value (not a string/ref)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", { allOf: 123 }, () => {});
+});
+`);
+
+    expect(result.errors[0]?.methodName).toBe("hook");
   });
 });
 

package/src/engine/feature-ast/__tests__/patcher.test.ts

@@ -157,18 +157,18 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
     });
   });
 
-  test("addEntityHook routes type + entity correctly", () => {
+  test("addHook routes entity-wide { allOf } target correctly", () => {
     const sf = makeSourceFile(STARTER);
-    createFeaturePatcher(sf).addEntityHook({
+    createFeaturePatcher(sf).addHook({
       type: "postDelete",
-      entity: "task",
+      target: { allOf: "task" },
       handlerSource: "async (event, ctx) => { /* cleanup */ }",
     });
     const result = parseSourceFile(sf);
     expect(result.patterns[0]).toMatchObject({
-      kind: "entityHook",
+      kind: "hook",
       hookType: "postDelete",
-      entityName: "task",
+      target: { allOf: "task" },
     });
   });
 
@@ -442,9 +442,9 @@ defineFeature("tasks", (r) => {
       handlerSource: "async (q, ctx) => []",
       access: { openToAll: true },
     });
-    p.addEntityHook({
+    p.addHook({
       type: "postDelete",
-      entity: "task",
+      target: { allOf: "task" },
       handlerSource: "async (event, ctx) => { /* cascade-clean */ }",
     });
     const result = parseSourceFile(sf);
@@ -453,7 +453,7 @@ defineFeature("tasks", (r) => {
       "entity",
       "writeHandler",
       "queryHandler",
-      "entityHook",
+      "hook",
     ]);
   });
 });