@cosmicdrift/kumiko-framework 0.154.1 → 0.155.0

package/src/engine/types/feature.ts

@@ -7,7 +7,6 @@ import type { EntityTableMeta } from "../../db/entity-table-meta";
 type PgTable = unknown;
 
 import type { QueryHandlerDefinition, WriteHandlerDefinition } from "../define-handler";
-import type { RegisterEntityCrudOptions } from "../entity-handlers";
 import type {
   ConfigKeyDefinition,
   ConfigKeyHandle,
@@ -381,6 +380,12 @@ export type FeatureDefinition = {
 // --- Feature Registrar (the "r" object in defineFeature) ---
 
 type RefOrRefs = NameOrRef | readonly NameOrRef[];
+// Entity-wide hook target — "all query/write handlers of this entity",
+// same reach r.entityHook() used to have. Only valid for postSave/
+// preDelete/postDelete/postQuery (the same 4 types entityHook covered);
+// hook() throws at registration time if used with validation/preSave/
+// preQuery.
+type HookTarget = RefOrRefs | { readonly allOf: NameOrRef };
 
 /**
  * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
@@ -399,11 +404,16 @@ type RefOrRefs = NameOrRef | readonly NameOrRef[];
  * steps are allowed to write via `r.step.unsafeProjectionUpsert`.
  * Hard-required for any unsafeProjection-* step usage (see Q10).
  */
-export type RequiresApi = ((...featureNames: string[]) => void) & {
-  readonly projection: (tableName: string) => void;
-  // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
-  readonly step: (stepKind: string) => void;
-};
+export type RequiresApi = ((...featureNames: string[]) => void) &
+  // Object-Form — the shape the feature-ast renderer (`render.ts`) emits
+  // for Designer/AI-generated code. A single object argument with named
+  // fields is easier to generate correctly than positional args whose
+  // count/order vary per registrar method.
+  ((options: { readonly features: readonly string[] }) => void) & {
+    readonly projection: (tableName: string) => void;
+    // Tier-2 step opt-in (Q9). Tier-1 implicit, Tier-2 must be declared.
+    readonly step: (stepKind: string) => void;
+  };
 
 export type FeatureRegistrar<TFeature extends string = string> = {
   systemScope(): void;
@@ -412,6 +422,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   describe(text: string): void;
   requires: RequiresApi;
   optionalRequires(...featureNames: string[]): void;
+  optionalRequires(options: { readonly features: readonly string[] }): void;
   // Declare the feature as operator-togglable. `default` is the effective
   // state when no global-toggle row exists. Must be called at most once per
   // feature; calling on an always-on feature (e.g. auth/tenant/user) is a
@@ -425,11 +436,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     definition: EntityDefinition,
     options?: { readonly table?: unknown },
   ): EntityRef;
-
-  // One-call CRUD for an event-sourced entity — delegates to registerEntityCrud():
-  // r.entity + create/update/delete/restore/list/detail handlers per verb flag.
-  // Access stays explicit — no openToAll default.
-  crud(name: string, definition: EntityDefinition, options?: RegisterEntityCrudOptions): EntityRef;
+  entity(definition: { readonly name: string } & EntityDefinition): EntityRef;
 
   writeHandler<TName extends string, TSchema extends ZodType>(
     def: WriteHandlerDefinition<TName, TSchema>,
@@ -452,45 +459,39 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): HandlerRef;
 
   relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
+  // TDef inferred from the literal — keeps the excess-property check
+  // resolved against the matching RelationDefinition union member instead
+  // of distributing across all three (which spuriously rejects valid
+  // combinations when checked directly against the raw union).
+  relation<TDef extends RelationDefinition>(
+    definition: { readonly entity: NameOrRef; readonly name: string } & TDef,
+  ): void;
 
   hook(type: "validation", target: RefOrRefs, fn: ValidationHookFn): void;
   hook(type: "preSave", target: RefOrRefs, fn: PreSaveHookFn): void;
+  // postSave/preDelete/postDelete/postQuery accept `{ allOf: entityRef }` —
+  // fires for every write/query handler of that entity, replacing the old
+  // r.entityHook(type, entity, fn). postQuery's entity-wide form fires for
+  // ALL query-handlers of the entity (e.g. customFields-bundle merging
+  // custom-fields-jsonb into every read); no phase semantics there
+  // (synchronous after handler-execute, before field-access-filter).
   hook(
     type: "postSave",
-    target: RefOrRefs,
+    target: HookTarget,
     fn: PostSaveHookFn,
     options?: { phase?: HookPhase },
   ): void;
   // preDelete always runs in-transaction (it guards the delete — there is no
   // meaningful "after" for a pre-hook). No phase option.
-  hook(type: "preDelete", target: RefOrRefs, fn: PreDeleteHookFn): void;
+  hook(type: "preDelete", target: HookTarget, fn: PreDeleteHookFn): void;
   hook(
     type: "postDelete",
-    target: RefOrRefs,
+    target: HookTarget,
     fn: PostDeleteHookFn,
     options?: { phase?: HookPhase },
   ): void;
   hook(type: "preQuery", target: RefOrRefs, fn: PreQueryHookFn): void;
-  hook(type: "postQuery", target: RefOrRefs, fn: PostQueryHookFn): void;
-
-  entityHook(
-    type: "postSave",
-    entity: NameOrRef,
-    fn: PostSaveHookFn,
-    options?: { phase?: HookPhase },
-  ): void;
-  entityHook(type: "preDelete", entity: NameOrRef, fn: PreDeleteHookFn): void;
-  entityHook(
-    type: "postDelete",
-    entity: NameOrRef,
-    fn: PostDeleteHookFn,
-    options?: { phase?: HookPhase },
-  ): void;
-  // postQuery-entityHook: fires for ALL query-handlers of this entity (e.g.,
-  // for customFields-bundle to merge custom-fields-jsonb into every read).
-  // No phase semantics (synchronous after handler-execute, before field-
-  // access-filter).
-  entityHook(type: "postQuery", entity: NameOrRef, fn: PostQueryHookFn): void;
+  hook(type: "postQuery", target: HookTarget, fn: PostQueryHookFn): void;
 
   // F3 — Search-Payload-Extension: contributor function adds flat fields to
   // an entity's search-index document. Fires synchronously during
@@ -514,6 +515,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   }): { readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]> };
 
   job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
+  job(definition: JobDefinition): void;
 
   notification(
     name: string,
@@ -524,6 +526,13 @@ export type FeatureRegistrar<TFeature extends string = string> = {
       readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
     },
   ): void;
+  notification(definition: {
+    readonly name: string;
+    readonly trigger: { readonly on: NameOrRef };
+    readonly recipient: NotificationRecipientFn;
+    readonly data: NotificationDataFn;
+    readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+  }): void;
 
   translations(def: TranslationsDef): void;
 
@@ -559,16 +568,25 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   ): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
 
   readsConfig(...qualifiedKeys: string[]): void;
+  readsConfig(options: { readonly keys: readonly string[] }): void;
 
   referenceData(
     entity: NameOrRef,
     data: readonly Record<string, unknown>[],
     options?: { upsertKey?: string },
   ): void;
+  referenceData(definition: {
+    readonly entity: NameOrRef;
+    readonly data: readonly Record<string, unknown>[];
+    readonly upsertKey?: string;
+  }): void;
 
   extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
 
   useExtension(extensionName: string, entity: NameOrRef, options?: Record<string, unknown>): void;
+  useExtension(
+    definition: { readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>,
+  ): void;
 
   /**
    * Declares which config key selects the active provider under an
@@ -621,12 +639,14 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // qualifies it on boot. Validation (snake_case + typ-suffix) runs at boot.
   // Usage at runtime: ctx.metrics.inc("created_total", { status: "new" }).
   metric(shortName: string, options: MetricOptions): void;
+  metric(definition: { readonly name: string } & MetricOptions): void;
 
   // Declare a secret key. Qualified name follows "<feature>:secret:<kebab>"
   // via the QN helper. Returns a typed handle so feature code can pass it
   // to ctx.secrets.get without retyping the qualified string — same
   // ergonomics as r.config's handle.
   secret(shortName: string, options: SecretOptions): SecretKeyHandle;
+  secret(definition: { readonly name: string } & SecretOptions): SecretKeyHandle;
 
   // Register a projection driven by events of one or more source entities.
   // The runtime fires projection.apply[event.type] inside the event-store's
@@ -680,6 +700,10 @@ export type FeatureRegistrar<TFeature extends string = string> = {
     shortName: string,
     options: { readonly type: T },
   ): ClaimKeyHandle<T>;
+  claimKey<T extends ClaimKeyType>(definition: {
+    readonly name: string;
+    readonly type: T;
+  }): ClaimKeyHandle<T>;
 
   // Register a screen. The id is the feature-local short name (kebab-case);
   // the registry qualifies to "<feature>:screen:<id>". Boot-validation checks

package/src/engine/types/nav.ts

@@ -54,6 +54,10 @@ export type NavDefinition = {
   // Role / openToAll gate. The nav resolver hides entries the user can't
   // reach; leave unset to always show (engine stays un-opinionated about
   // who sees what — apps that need default-deny can set { roles: [] }).
+  // If `screen` is set and `access` is left unset, the client-side nav
+  // builder (buildNavRegistrySliceForApp) fills this in from the target
+  // screen's own `access` — a nav entry never invites a role into a 403.
+  // An explicit `access` here always wins over the screen's.
   readonly access?: AccessRule;
   // Workspace QNs this entry self-assigns to. Merged at boot with any
   // r.workspace({ nav: [...] }) explicit lists. Omit to leave workspace

package/src/jobs/__tests__/jobs.integration.test.ts

@@ -4,7 +4,12 @@ import { createRegistry, defineFeature } from "../../engine";
 import type { AppContext, Registry } from "../../engine/types";
 import { createTestRedis, type TestRedis } from "../../stack";
 import { sleep, waitFor } from "../../testing";
-import { createJobRunner, type JobRunner } from "../job-runner";
+import {
+  createJobRunner,
+  type JobMeta,
+  type JobRunner,
+  type JobRunnerOptions,
+} from "../job-runner";
 
 // --- Shared state ---
 
@@ -104,6 +109,12 @@ const testFeature = defineFeature("test", (r) => {
     throw new Error("intentional failure");
   });
 
+  // perTenant fan-out — used to assert missing getActiveTenantIds fails
+  // the wrapper job without killing the worker.
+  r.job("perTenantFanout", { trigger: { manual: true }, perTenant: true }, async (payload) => {
+    jobLog.push({ name: "test:job:per-tenant-fanout", payload, timestamp: Date.now() });
+  });
+
   // Correlation propagation probe — records the requestContext it sees at
   // handler-time so tests can assert the scheduling request's correlationId
   // made it through BullMQ into the worker process.
@@ -133,6 +144,7 @@ afterAll(async () => {
 // Helper to create a runner, run tests, then stop
 async function withRunner(
   fn: (runner: JobRunner, registry: Registry) => Promise<void>,
+  opts?: Partial<JobRunnerOptions>,
 ): Promise<void> {
   const registry = createRegistry([testFeature]);
   const context: AppContext = {};
@@ -145,6 +157,7 @@ async function withRunner(
     redisUrl,
     consumerLane: "worker",
     queueNamePrefix,
+    ...opts,
   });
 
   try {
@@ -534,6 +547,58 @@ describe("error handling", () => {
       });
     });
   });
+
+  test("onJobFailed receives the handler error on each attempt", async () => {
+    clearLog();
+    const failures: Array<{ jobName: string; error: string }> = [];
+    const starts: JobMeta[] = [];
+    await withRunner(
+      async (runner) => {
+        await runner.dispatch("test:job:failing-job");
+        // retries: 1 → attempts = 2 (initial + one retry)
+        await waitFor(() => {
+          expect(failures.length).toBeGreaterThanOrEqual(2);
+        });
+        expect(failures.every((f) => f.jobName === "test:job:failing-job")).toBe(true);
+        expect(failures.every((f) => f.error === "intentional failure")).toBe(true);
+        expect(starts.map((s) => s.attempt)).toEqual([1, 2]);
+
+        // Worker still alive after exhausted retries
+        await runner.dispatch("test:job:manual-report", { after: "retries" });
+        await waitFor(() => {
+          expect(
+            jobLog.some(
+              (e) => e.name === "test:job:manual-report" && e.payload["after"] === "retries",
+            ),
+          ).toBe(true);
+        });
+      },
+      {
+        onJobStart: (name, _id, meta) => {
+          if (name === "test:job:failing-job") starts.push(meta);
+        },
+        onJobFailed: (jobName, _id, error) => {
+          if (jobName === "test:job:failing-job") failures.push({ jobName, error });
+        },
+      },
+    );
+  });
+
+  test("perTenant without getActiveTenantIds fails wrapper; worker stays alive", async () => {
+    clearLog();
+    await withRunner(async (runner) => {
+      await runner.dispatch("test:job:per-tenant-fanout", { n: 1 });
+      // Wrapper throws before fan-out (and before onJobFailed) — settle, then
+      // prove the worker still consumes.
+      await sleep(300);
+      expect(jobLog.filter((e) => e.name === "test:job:per-tenant-fanout")).toHaveLength(0);
+
+      await runner.dispatch("test:job:manual-report", { after: "perTenant-miss" });
+      await waitFor(() => {
+        expect(jobLog.some((e) => e.name === "test:job:manual-report")).toBe(true);
+      });
+    });
+  });
 });
 
 // --- Registry ---

package/src/pipeline/__tests__/ctx-bridge.integration.test.ts

@@ -131,14 +131,14 @@ const bridgeFeature = defineFeature("ctxbridge", (r) => {
   );
 
   // afterCommit hook on bag — fires once per outer commit.
-  r.entityHook("postSave", bag, async (result) => {
+  r.hook("postSave", { allOf: bag }, async (result) => {
     afterCommitLog.push(`bag:${result.data["label"]}`);
   });
 
   // afterCommit hook on secret — the entity targeted by the nested writeAs.
   // Proves: (a) hook fires exactly once per successful writeAs, (b) hook
   // does NOT fire when the outer transaction rolls back.
-  r.entityHook("postSave", secret, async (result) => {
+  r.hook("postSave", { allOf: secret }, async (result) => {
     afterCommitLog.push(`secret:${result.data["owner"]}`);
   });
 });

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -424,7 +424,7 @@ describe("Sprint 8a: per-tenant entity-hook filter", () => {
     });
 
     const featureB = defineFeature("feat-b", (r) => {
-      r.entityHook("postSave", "widget", async (_result, ctx) => {
+      r.hook("postSave", { allOf: "widget" }, async (_result, ctx) => {
         calls.push({ tenant: ctx._tenantId ?? "no-tenant" });
       });
     });

package/src/pipeline/__tests__/post-query-hook.integration.test.ts

@@ -65,7 +65,7 @@ const postQueryFeature = defineFeature("postquerytest", (r) => {
   r.hook("postQuery", "widget:list", handlerKeyedHook);
 
   // Entity-keyed: fires for ALL query-handlers of widget-entity
-  r.entityHook("postQuery", widget, entityKeyedHook);
+  r.hook("postQuery", { allOf: widget }, entityKeyedHook);
 });
 
 // --- Single-object-result invariant fixtures ---
@@ -93,13 +93,13 @@ const singleObjectFeature = defineFeature("singleobjtest", (r) => {
   r.queryHandler("gadget:get", z.object({}), async () => ({ id: "g1", name: "Gadget" }), {
     access: { openToAll: true },
   });
-  r.entityHook("postQuery", gadget, dropRowHook);
+  r.hook("postQuery", { allOf: gadget }, dropRowHook);
 
   const gizmo = r.entity("gizmo", gizmoEntity);
   r.queryHandler("gizmo:get", z.object({}), async () => ({ id: "z1", name: "Gizmo" }), {
     access: { openToAll: true },
   });
-  r.entityHook("postQuery", gizmo, duplicateRowHook);
+  r.hook("postQuery", { allOf: gizmo }, duplicateRowHook);
 });
 
 // --- Test stack ---