@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/define-handler.ts

@@ -0,0 +1,78 @@
+import type { ZodType, z } from "zod";
+import type {
+  AccessRule,
+  HandlerContext,
+  KumikoEventTypeMap,
+  QueryEvent,
+  RateLimitOption,
+  WriteEvent,
+  WriteResult,
+} from "./types";
+
+// --- Write Handler Definition ---
+//
+// TMap propagates the strict event-type-map through the handler's
+// HandlerContext. CRITICAL: TMap is declared as a generic parameter on the
+// FUNCTION (defineWriteHandler), not just on the type. Generic-functions
+// substitute TMap at the USE-site (the caller's compile context, where
+// the augmentation is visible); generic-type-aliases substitute at the
+// definition-site (framework's compile, where the augmentation isn't
+// visible) and collapse `keyof TMap` to `never`. See the spike-findings
+// memory for the empirical proof.
+
+export type WriteHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TData = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly skipTransitionGuard?: boolean;
+  readonly rateLimit?: RateLimitOption;
+  readonly handler: (
+    event: WriteEvent<z.infer<TSchema>>,
+    context: HandlerContext<TMap>,
+  ) => Promise<WriteResult<TData>>;
+};
+
+export function defineWriteHandler<
+  const TName extends string,
+  TSchema extends ZodType,
+  TData = unknown,
+  TMap extends object = KumikoEventTypeMap,
+>(
+  def: WriteHandlerDefinition<TName, TSchema, TData, TMap>,
+): WriteHandlerDefinition<TName, TSchema, TData, TMap> {
+  return def;
+}
+
+// --- Query Handler Definition ---
+
+export type QueryHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TResult = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
+  readonly handler: (
+    query: QueryEvent<z.infer<TSchema>>,
+    context: HandlerContext<TMap>,
+  ) => Promise<TResult>;
+};
+
+export function defineQueryHandler<
+  const TName extends string,
+  TSchema extends ZodType,
+  TResult = unknown,
+  TMap extends object = KumikoEventTypeMap,
+>(
+  def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>,
+): QueryHandlerDefinition<TName, TSchema, TResult, TMap> {
+  return def;
+}

package/src/engine/define-roles.ts

@@ -0,0 +1,19 @@
+// Identity function for type-safe role definitions.
+// App defines roles once, all features reference them via the typed object.
+//
+// Usage:
+//   const roles = defineRoles(["Admin", "SystemAdmin", "Driver"] as const);
+//   roles.Admin     // "Admin" — autocomplete + type-checked
+//   roles.Admni     // TS error
+
+type RoleMap<T extends readonly string[]> = {
+  readonly [K in T[number]]: K;
+};
+
+export function defineRoles<const T extends readonly string[]>(roles: T): RoleMap<T> {
+  const map = {} as Record<string, string>;
+  for (const role of roles) {
+    map[role] = role;
+  }
+  return map as RoleMap<T>;
+}

package/src/engine/effective-features.ts

@@ -0,0 +1,87 @@
+import type { Registry } from "./types";
+
+// Callback that returns the current global-toggle override for a feature.
+// `true`  = explicit global row says enabled.
+// `false` = explicit global row says disabled.
+// `undefined` = no row — fall back to the feature's declared toggleableDefault.
+//
+// The feature-toggles bundled feature provides this reader; tests can inject
+// a map-backed stub. The reader is called once per feature during compute;
+// callers that fetch toggles from a DB should batch-load upfront and expose
+// a Map lookup to keep compute() allocation-light.
+export type ToggleReader = (featureName: string) => boolean | undefined;
+
+// Compute the set of effectively-enabled features for the current call.
+//
+// Rules (AND-combined, any false wins):
+//   1. Always-on: feature without r.toggleable() → enabled, ignores overrides.
+//   2. Toggleable: enabled = (globalOverride ?? toggleableDefault).
+//   3. Cascade: a feature is only effectively enabled if ALL its r.requires()
+//      targets are effectively enabled. Applied transitively.
+//
+// Cascade semantics note: a NON-toggleable feature A that requires a
+// toggleable feature B becomes effectively disabled when B is off. This is
+// intentional — running A's handlers/hooks without its declared dependency
+// would be a worse failure mode than gating A. Ops documentation must call
+// this out so disabling "leaf" features doesn't surprise anyone.
+//
+// The result is a plain Set for O(1) `has(name)` checks in the dispatcher
+// gate, hook filter, and MSP runner. Cycle-safety is delegated to the
+// registry's existing boot-validation (cycles are rejected there).
+export function computeEffectiveFeatures(
+  registry: Registry,
+  readToggle: ToggleReader,
+): ReadonlySet<string> {
+  // Raw enablement, before cascade.
+  const raw = new Map<string, boolean>();
+  for (const feature of registry.features.values()) {
+    if (feature.toggleableDefault === undefined) {
+      raw.set(feature.name, true);
+      continue;
+    }
+    const override = readToggle(feature.name);
+    raw.set(feature.name, override ?? feature.toggleableDefault);
+  }
+
+  // Transitive cascade via DFS with memoization. Cycles are already rejected
+  // at boot, so no cycle-breaking is needed here.
+  const effective = new Map<string, boolean>();
+
+  function resolve(name: string): boolean {
+    const cached = effective.get(name);
+    if (cached !== undefined) return cached;
+
+    const rawEnabled = raw.get(name) ?? true;
+    if (!rawEnabled) {
+      effective.set(name, false);
+      return false;
+    }
+
+    const feature = registry.getFeature(name);
+    // Feature referenced by requires() but not loaded — registry boot should
+    // have caught this, but be defensive: treat missing deps as disabled
+    // (surfaces the same behaviour as "dep is off", not a silent pass).
+    if (!feature) {
+      effective.set(name, false);
+      return false;
+    }
+
+    for (const dep of feature.requires) {
+      if (!resolve(dep)) {
+        effective.set(name, false);
+        return false;
+      }
+    }
+
+    effective.set(name, true);
+    return true;
+  }
+
+  for (const feature of registry.features.values()) resolve(feature.name);
+
+  const result = new Set<string>();
+  for (const [name, enabled] of effective) {
+    if (enabled) result.add(name);
+  }
+  return result;
+}

package/src/engine/entity-handlers.ts

@@ -0,0 +1,364 @@
+import { type ZodType, z } from "zod";
+import type { DbRow } from "../db/connection";
+import type { TableColumns } from "../db/dialect";
+import {
+  collectReferenceFields,
+  enrichRowWithReferences,
+  enrichWithReferences,
+} from "../db/eagerload";
+import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
+import { buildDrizzleTable } from "../db/table-builder";
+import { assertUnreachable } from "../utils";
+import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
+import type { AccessRule, EntityDefinition, QueryHandlerDef, WriteHandlerDef } from "./types";
+
+// Convention-based handler factories for event-sourced aggregates.
+//
+// You register one handler per call (no auto-generation of a whole CRUD set),
+// but the Schema and the executor body are inferred from the entity + verb.
+// Pick the verbs you need — leave out the ones you don't.
+//
+// Two API shapes — pick one per project, don't mix:
+//
+//   PREFERRED — one function per verb, type-safe, no magic strings:
+//     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
+//     r.writeHandler(defineEntityUpdateHandler("note", noteEntity, { access }))
+//     r.writeHandler(defineEntityDeleteHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityListHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }))
+//
+//   LEGACY — single function with verb in the name-string. Kept for
+//   backwards-compat; existing apps work as before. New code should use
+//   the verb-specific factories above:
+//     r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access }))
+//     r.queryHandler(defineEntityDetailHandler("note", noteEntity, { access }))
+//
+// For custom logic (default values, business rules, side effects, custom
+// executors with ctx.searchAdapter, ...) write the handler explicitly with
+// r.writeHandler / r.queryHandler — these helpers cover the standard path only.
+//
+// Note on the `as` casts in the handler bodies: WriteHandlerDef.handler's
+// payload type is `unknown` because the dispatcher hands the parsed payload
+// through a runtime-only boundary. Each verb knows its post-parse shape (the
+// schema we just built two lines up enforces it), so the casts are a
+// localised re-declaration of that shape rather than a narrowing escape.
+
+const WRITE_VERBS = ["create", "update", "delete", "restore"] as const;
+const QUERY_VERBS = ["list", "detail"] as const;
+
+type UpdatePayload = { id: string; version: number; changes: Record<string, unknown> };
+type IdPayload = { id: string };
+type ListPayload = {
+  cursor?: string;
+  limit?: number;
+  search?: string;
+  sort?: string;
+  sortDirection?: "asc" | "desc";
+  // Page-based Pagination: offset 0-basiert, mit limit zusammen statt
+  // cursor genutzt. Cursor ist für infinite-scroll / live-tailing
+  // präziser; offset ist für klassische Pager (← 1 2 ... N →) wo der
+  // User direkt zu "page 7" springen will. Nur EINE Variante pro
+  // Request — wenn beide gesetzt sind, gewinnt cursor (DB-stabil).
+  offset?: number;
+  // Wenn true, liefert der executor zusätzlich eine `total`-Zahl im
+  // Response. Extra-Roundtrip auf der DB (COUNT(*)), nur dann sinnvoll
+  // wenn der Pager "Page X of Y" rendern muss. Infinite-Scroll oder
+  // unbedingte Lists lassen das weg um die COUNT-Kosten zu sparen.
+  totalCount?: boolean;
+  // Screen-Level Filter (Tier 2.7c) — Author-deklarierter, server-side
+  // applizierter WHERE-Clause. Drei Buckets der selben Entity ohne
+  // Custom-Pages: jedes Screen hat sein eigenes filter, alle nutzen
+  // den gleichen Query-Handler.
+  filter?: {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+    readonly value: unknown;
+  };
+};
+
+const idSchema = z.object({ id: z.uuid() });
+const listSchema = z.object({
+  cursor: z.string().optional(),
+  limit: z.number().optional(),
+  search: z.string().optional(),
+  sort: z.string().optional(),
+  sortDirection: z.enum(["asc", "desc"]).optional(),
+  offset: z.number().int().nonnegative().optional(),
+  totalCount: z.boolean().optional(),
+  filter: z
+    .object({
+      field: z.string(),
+      op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+      // Value ist `unknown` zur Compile-Zeit; Server-Side prüft beim
+      // Build der WHERE-Clause ob der Type zum Field passt. z.unknown()
+      // lässt alles durch; Type-Check kommt im executor.list.
+      value: z.unknown(),
+    })
+    .optional(),
+});
+
+function parseHandlerName<TVerb extends string>(
+  name: string,
+  validVerbs: readonly TVerb[],
+): { entityName: string; verb: TVerb } {
+  const colonIdx = name.indexOf(":");
+  if (colonIdx < 0) {
+    throw new Error(
+      `Handler name "${name}" must use the "<entity>:<verb>" pattern (e.g. "note:create").`,
+    );
+  }
+  const entityName = name.slice(0, colonIdx);
+  const verbCandidate = name.slice(colonIdx + 1);
+  if (!entityName) {
+    throw new Error(`Handler name "${name}" is missing the entity part before the colon.`);
+  }
+  // @cast-boundary engine-bridge — verbCandidate validated against validVerbs union
+  if (!(validVerbs as readonly string[]).includes(verbCandidate)) {
+    throw new Error(
+      `Unknown verb "${verbCandidate}" in handler name "${name}". Standard verbs: ${validVerbs.join("/")}. For custom verbs use the explicit r.writeHandler / r.queryHandler form.`,
+    );
+  }
+  return { entityName, verb: verbCandidate as TVerb }; // @cast-boundary engine-bridge
+}
+
+export function defineEntityWriteHandler(
+  name: string,
+  entity: EntityDefinition,
+  options?: { access?: AccessRule },
+): WriteHandlerDef {
+  const { entityName, verb } = parseHandlerName(name, WRITE_VERBS);
+  if (verb === "restore" && !entity.softDelete) {
+    throw new Error(
+      `"${name}": restore is only valid for entities declared with softDelete: true.`,
+    );
+  }
+
+  const table = buildDrizzleTable(entityName, entity);
+  const executor = createEventStoreExecutor(table, entity, { entityName });
+
+  let schema: ZodType;
+  let handler: WriteHandlerDef["handler"];
+
+  switch (verb) {
+    case "create":
+      schema = buildInsertSchema(entity);
+      handler = async (event, ctx) => executor.create(event.payload as DbRow, event.user, ctx.db);
+      break;
+    case "update":
+      schema = z.object({
+        id: z.uuid(),
+        version: z.number(),
+        changes: buildUpdateSchema(entity),
+      });
+      handler = async (event, ctx) =>
+        executor.update(event.payload as UpdatePayload, event.user, ctx.db);
+      break;
+    case "delete":
+      schema = idSchema;
+      handler = async (event, ctx) =>
+        executor.delete(event.payload as IdPayload, event.user, ctx.db);
+      break;
+    case "restore":
+      schema = idSchema;
+      handler = async (event, ctx) =>
+        executor.restore(event.payload as IdPayload, event.user, ctx.db);
+      break;
+    default:
+      assertUnreachable(verb, "write verb");
+  }
+
+  return {
+    name,
+    schema,
+    handler,
+    ...(options?.access && { access: options.access }),
+  };
+}
+
+export function defineEntityQueryHandler(
+  name: string,
+  entity: EntityDefinition,
+  options?: { access?: AccessRule },
+): QueryHandlerDef {
+  const { entityName, verb } = parseHandlerName(name, QUERY_VERBS);
+
+  const table = buildDrizzleTable(entityName, entity);
+  const executor = createEventStoreExecutor(table, entity, { entityName });
+
+  let schema: ZodType;
+  let handler: QueryHandlerDef["handler"];
+
+  // Tier 2.7e Server-Eagerload: wenn die entity reference-Felder hat,
+  // resolved der handler nach dem Haupt-Query die UUIDs gegen die
+  // referenced entities. Das `_refs`-Property landet auf jeder Row;
+  // Renderer-Side useReferenceLookup bleibt als Fallback bestehen
+  // (für Apps die manuell Custom-Handler schreiben ohne diesen
+  // Wrapper zu nutzen).
+  const hasRefFields = collectReferenceFields(entity).length > 0;
+
+  switch (verb) {
+    case "list":
+      schema = listSchema;
+      handler = async (query, ctx) => {
+        // Tier 2.7e Audit-Fix: SearchAdapter aus ctx durchreichen,
+        // damit payload.search zur Laufzeit gegen Meilisearch/InMem
+        // läuft (Remote-Combobox-Search). Der executor wird beim
+        // Definition-Time gebaut, kennt den Adapter also nicht —
+        // Runtime-Override holt das.
+        const result = await executor.list(query.payload as ListPayload, query.user, ctx.db, {
+          ...(ctx.searchAdapter !== undefined && { searchAdapter: ctx.searchAdapter }),
+        });
+        if (!hasRefFields) return result;
+        const enrichedRows = await enrichWithReferences(
+          result.rows,
+          entity,
+          (name) => ctx.registry.getEntity(name),
+          ctx.db,
+        );
+        return { ...result, rows: enrichedRows };
+      };
+      break;
+    case "detail":
+      schema = idSchema;
+      handler = async (query, ctx) => {
+        const row = await executor.detail(query.payload as IdPayload, query.user, ctx.db);
+        if (row === null || !hasRefFields) return row;
+        return enrichRowWithReferences(row, entity, (name) => ctx.registry.getEntity(name), ctx.db);
+      };
+      break;
+    default:
+      assertUnreachable(verb, "query verb");
+  }
+
+  return {
+    name,
+    schema,
+    handler,
+    ...(options?.access && { access: options.access }),
+  };
+}
+
+// ─── Verb-specific factories (preferred) ──────────────────────────────
+//
+// One function per verb — verb is the function name, no magic-string
+// parsing. Each delegates to the legacy `defineEntityWriteHandler` /
+// `defineEntityQueryHandler` with a fixed verb-suffix; the schema +
+// handler-body logic is unchanged. Migration from the legacy API is a
+// 1:1 rename — same arguments minus the verb-prefix in the name-string.
+//
+// Why prefer these over the legacy form:
+//   - Verb is checked at compile-time (no runtime "Unknown verb" throw)
+//   - IDE auto-completes the four/two verbs after typing `defineEntity`
+//   - Function name is self-documenting; no comment needed to explain
+//   - Entity-name appears once (used to be doubled: once in the string,
+//     once as the entity-arg)
+//
+// Restore-specific note: defineEntityRestoreHandler still validates at
+// runtime that entity.softDelete === true. A compile-time-only check
+// would need a Branded-EntityDefinition with `softDelete: true` literal
+// — feasible but not yet wired; the runtime guard catches misuse.
+
+type EntityHandlerOptions = { readonly access?: AccessRule };
+
+export function defineEntityCreateHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): WriteHandlerDef {
+  return defineEntityWriteHandler(`${entityName}:create`, entity, options);
+}
+
+export function defineEntityUpdateHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): WriteHandlerDef {
+  return defineEntityWriteHandler(`${entityName}:update`, entity, options);
+}
+
+export function defineEntityDeleteHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): WriteHandlerDef {
+  return defineEntityWriteHandler(`${entityName}:delete`, entity, options);
+}
+
+export function defineEntityRestoreHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): WriteHandlerDef {
+  return defineEntityWriteHandler(`${entityName}:restore`, entity, options);
+}
+
+export function defineEntityListHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): QueryHandlerDef {
+  return defineEntityQueryHandler(`${entityName}:list`, entity, options);
+}
+
+export function defineEntityDetailHandler(
+  entityName: string,
+  entity: EntityDefinition,
+  options?: EntityHandlerOptions,
+): QueryHandlerDef {
+  return defineEntityQueryHandler(`${entityName}:detail`, entity, options);
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic table — erased on purpose, same as db/event-store-executor.ts does.
+type AnyTable = TableColumns<any>;
+
+// Bundle the two calls every custom write-handler opens with: build the
+// Drizzle table from the entity, then wire an event-store executor onto it.
+// The pair is identical in every sample that hand-writes handlers, so the
+// helper collapses 3-4 lines + the { entityName } bookkeeping into one.
+//
+//   const { table, executor } = createEntityExecutor("counter", counterEntity);
+//
+// Keep using the explicit buildDrizzleTable / createEventStoreExecutor duo
+// when you need search-adapter / entity-cache options on the executor — this
+// helper covers the zero-config case.
+export function createEntityExecutor(
+  entityName: string,
+  entity: EntityDefinition,
+): { readonly table: AnyTable; readonly executor: EventStoreExecutor } {
+  const table = buildDrizzleTable(entityName, entity);
+  const executor = createEventStoreExecutor(table, entity, { entityName });
+  return { table, executor };
+}
+
+// Wrap a projection read into a zero-argument query handler. Use when the
+// read is "give me all rows from projection X, tenant-scoped" — the common
+// shape for list-views backed by an MSP/projection table.
+//
+//   r.queryHandler(
+//     defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue", {
+//       access: { openToAll: true },
+//     }),
+//   );
+//
+// For anything more involved (filters, joins, custom shaping), write the
+// query-handler explicitly with ctx.queryProjection or a raw select.
+export function defineProjectionQueryHandler(
+  name: string,
+  projectionQualifiedName: string,
+  options?: { access?: AccessRule; allTenants?: boolean },
+): QueryHandlerDef {
+  return {
+    name,
+    schema: z.object({}),
+    // Returns the raw row array — matches ctx.queryProjection's shape so the
+    // helper is a drop-in for the inline `async (_q, ctx) => ctx.queryProjection(...)`
+    // handler. Wrap the result in the caller's handler when you need
+    // pagination envelopes or added metadata.
+    handler: async (_query, ctx) =>
+      ctx.queryProjection(
+        projectionQualifiedName,
+        options?.allTenants ? { allTenants: true } : undefined,
+      ),
+    ...(options?.access && { access: options.access }),
+  };
+}

package/src/engine/event-helpers.ts

@@ -0,0 +1,73 @@
+import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers";
+
+// The ctx-surface emitEvent needs. Accepting the narrow shape lets tests or
+// MultiStreamApplyContext-style callers pass their own appendEvent without
+// a full HandlerContext. Real handlers just pass `ctx`.
+//
+// Uses appendEventUnsafe internally because EventDef's TPayload comes from
+// a runtime-defined zod-schema — emitEvent does the type-check itself via
+// the EventDef generic, so it doesn't need the strict KumikoEventTypeMap
+// path. The strict appendEvent is for direct in-handler callsites.
+export type EmitCtx = Pick<HandlerContext, "appendEventUnsafe">;
+
+// Typed wrapper around ctx.appendEvent. Two wins over the raw call:
+//
+//   1. The payload is checked against the EventDef's inferred TPayload,
+//      so a Zod-schema mismatch becomes a compile error at the emit site
+//      rather than a runtime reject from the event-store append.
+//   2. The event name is carried by the def — no hand-typed
+//      "<feature>:event:<short>" string, no typos.
+//
+//   await emitEvent(ctx, orderPlaced, {
+//     aggregateId: String(result.data.id),
+//     aggregateType: "pubsub-order",
+//     payload: { id, customer, product },
+//   });
+//
+// aggregateType stays explicit on purpose — the EventDef doesn't know which
+// aggregate owns an event (cross-feature reuse is legal). Use the raw
+// ctx.appendEvent when the event name is computed at runtime.
+export async function emitEvent<TPayload>(
+  ctx: EmitCtx,
+  eventDef: EventDef<TPayload>,
+  args: {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly payload: TPayload;
+  },
+): Promise<void> {
+  const appendArgs: AppendEventArgs = {
+    aggregateId: args.aggregateId,
+    aggregateType: args.aggregateType,
+    type: eventDef.name,
+    payload: args.payload,
+  };
+  await ctx.appendEventUnsafe(appendArgs);
+}
+
+// Read-side counterpart: narrow a StoredEvent's `payload` (declared as
+// `Record<string, unknown>` because a stream carries many event types) to
+// the EventDef's inferred TPayload. Replaces the scattered
+// `event.payload as { ... }` casts inside projection-apply handlers and
+// reducers — the cast is named, the shape comes from a single source
+// (the defineEvent() schema), and a mismatched event-type throws loudly.
+//
+//   const p = typedPayload(event, approved);
+//   // p is typed as { amountCents: number; approvedBy: string }
+//
+// The runtime type-check guards against projection-apply maps that hand-
+// build their key → handler mapping and accidentally route events to the
+// wrong typedPayload call. No Zod-parse — validation happened at
+// appendEvent time; this is a read-path helper.
+export function typedPayload<TPayload>(
+  event: { readonly type: string; readonly payload: Record<string, unknown> },
+  eventDef: EventDef<TPayload>,
+): TPayload {
+  if (event.type !== eventDef.name) {
+    throw new Error(
+      `[Kumiko] typedPayload: event type "${event.type}" does not match EventDef "${eventDef.name}". ` +
+        `Check the projection-apply / reducer mapping — the event was routed to the wrong handler.`,
+    );
+  }
+  return event.payload as TPayload;
+}