@cosmicdrift/kumiko-framework 0.1.0

package/src/engine/types/hooks.ts

@@ -0,0 +1,142 @@
+import type { StoredEvent } from "../../event-store/event-store";
+import type { AppContext } from "./handlers";
+import type { EntityId } from "./identifiers";
+
+// --- Validation ---
+
+export type ValidationError = {
+  readonly field: string;
+  readonly error: string;
+};
+
+export type ValidationHookFn = (
+  data: Readonly<Record<string, unknown>>,
+) => readonly ValidationError[] | null;
+
+// --- Save/Delete Context (what hooks receive) ---
+
+export type SaveContext = {
+  readonly kind: "save";
+  readonly id: EntityId;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly changes: Readonly<Record<string, unknown>>;
+  readonly previous: Readonly<Record<string, unknown>>;
+  readonly isNew: boolean;
+  readonly entityName?: string | undefined;
+  // The event that produced this save. Populated by the event-store-executor;
+  // the pipeline uses it to drive projections inside the same transaction.
+  // Optional because hand-crafted SaveContexts (tests, custom executors) may
+  // not have an event — projections just skip in that case.
+  readonly event?: StoredEvent | undefined;
+};
+
+export type DeleteContext = {
+  readonly kind: "delete";
+  readonly id: EntityId;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly entityName?: string | undefined;
+  // See SaveContext.event — same semantics.
+  readonly event?: StoredEvent | undefined;
+};
+
+export type LifecycleResult = SaveContext | DeleteContext;
+
+// --- Lifecycle Hooks ---
+
+export type PreSaveHookFn = (
+  changes: Record<string, unknown>,
+  context: AppContext & {
+    readonly previous: Readonly<Record<string, unknown>>;
+    readonly isNew: boolean;
+  },
+) => Promise<Record<string, unknown>>;
+
+export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
+
+// Batch-variant: called once at the end of a dispatcher batch with every
+// successful SaveContext. The per-save PostSaveHookFn still fires for
+// side-effects that need per-entity semantics (SSE); PostSaveBatch exists
+// for adapters that can amortise work across the whole batch (e.g. search
+// index batch-writes, bulk webhook fanout).
+export type PostSaveBatchHookFn = (
+  results: readonly SaveContext[],
+  context: AppContext,
+) => Promise<void>;
+
+export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
+
+export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
+
+export type PostDeleteBatchHookFn = (
+  payloads: readonly DeleteContext[],
+  context: AppContext,
+) => Promise<void>;
+
+export type PreQueryHookFn = (
+  payload: Record<string, unknown>,
+  context: AppContext,
+) => Promise<Record<string, unknown>>;
+
+export type LifecycleHookFn =
+  | PreSaveHookFn
+  | PostSaveHookFn
+  | PreDeleteHookFn
+  | PostDeleteHookFn
+  | PreQueryHookFn;
+
+// --- Hook Phases ---
+//
+// inTransaction: Hook runs inside the DB transaction. Failures roll back
+//   the entire write. Use for: DB-based side-effects (counter updates,
+//   dependent entity writes).
+//
+// afterCommit (default): Hook runs after the transaction commits. Failures
+//   are logged but don't affect the write. Use for: external systems
+//   (SSE broadcast, search index, email, webhooks).
+
+export const HookPhases = {
+  inTransaction: "inTransaction",
+  afterCommit: "afterCommit",
+} as const;
+
+export type HookPhase = (typeof HookPhases)[keyof typeof HookPhases];
+
+// Owner-tag shared across every hook structure. The lifecycle pipeline uses
+// it to skip hooks whose owning feature is globally disabled:
+//   - A concrete feature name like "orders" → subject to the feature-toggle
+//     filter (skipped when "orders" is disabled).
+//   - "*" (star) → invariant plumbing, never filtered. Reserved for
+//     extension-provided hooks and framework-internal hooks that belong to
+//     the pipeline itself, not a feature.
+//   - Omitted (undefined) → treated as "*". Supports tests that hand-build
+//     HookMap objects without caring about ownership.
+export type HookOwner = { readonly featureName?: string };
+
+export type PhasedHook<TFn> = {
+  readonly fn: TFn;
+  readonly phase: HookPhase;
+} & HookOwner;
+
+// Flat (non-phased) hook — preSave, preQuery. Same owner contract, no
+// phase semantics because these hooks run exactly once per handler pass
+// before/around the DB transaction.
+export type OwnedFn<TFn> = {
+  readonly fn: TFn;
+} & HookOwner;
+
+// --- Hook Maps ---
+
+export type HookMap = {
+  readonly validation: Readonly<Record<string, ValidationHookFn>>;
+  readonly preSave: Readonly<Record<string, readonly OwnedFn<PreSaveHookFn>[]>>;
+  readonly postSave: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
+  readonly preDelete: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
+  readonly postDelete: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
+  readonly preQuery: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
+};
+
+export type EntityHookMap = {
+  readonly postSave: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
+  readonly preDelete: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
+  readonly postDelete: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
+};

package/src/engine/types/http-route.ts

@@ -0,0 +1,54 @@
+// HTTP-Route-Definition — feature-deklarierte HTTP-Endpoints außerhalb
+// der /api/write|query|batch-Pipeline. Use-Case: RSS/Atom-Feeds, OpenAPI-
+// Specs, OG-Image-Generators, Webhook-Receiver — alles wo der Feature-
+// Author das Wire-Format selbst kontrolliert.
+//
+// Pattern symmetrisch zu r.queryHandler / r.writeHandler: Definition als
+// Teil des Features (nicht des App-Bootstrapping). Phase-3 Multi-Tenant
+// wird trivial weil tenant-context via host-resolution greift.
+//
+// Escape-hatch bleibt: runProdApp.extraRoutes für hand-rolled Routes die
+// nichts mit einem Feature zu tun haben (z.B. plattform-spezifische
+// Static-Serving-Logic).
+
+import type { Context } from "hono";
+
+/** Subset von HTTP-Methoden den wir aktiv unterstützen. Hono spricht
+ *  alle, aber das hier sind die einzigen die ein Feature-Author
+ *  realistisch deklariert. */
+export type HttpRouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+/** Dependencies die der Handler vom Framework bekommt. App-Author kann
+ *  die App selbst aufrufen (`deps.app.fetch(...)` für intern-call) oder
+ *  direkt per dispatcher Daten ziehen. Db/Redis sind die rohen Connections
+ *  — wer Tenant-Scope braucht muss durch dispatcher.query gehen.
+ *
+ *  Hono-typing: `Context<any, any>` weil das Hono-Type-Param-Setup nur
+ *  intern relevant ist. Concrete Hono-app wird im Boot-Path zugewiesen. */
+export type HttpRouteHandlerDeps = {
+  /** Die Hono-app — Handler kann via app.fetch(...) interne Routes
+   *  ansprechen (z.B. /api/query mit der vollen Auth-/Anonymous-Chain). */
+  // biome-ignore lint/suspicious/noExplicitAny: Hono's generic-Param ist im Framework-Boundary unsichtbar
+  readonly app: import("hono").Hono<any, any>;
+};
+
+export type HttpRouteHandler = (
+  // biome-ignore lint/suspicious/noExplicitAny: Hono Context-Generics sind im Framework-Boundary unsichtbar
+  c: Context<any, any>,
+  deps: HttpRouteHandlerDeps,
+) => Response | Promise<Response>;
+
+export type HttpRouteDefinition = {
+  /** HTTP-Methode — bei Hono-Mount via app.{get,post,...}(path). */
+  readonly method: HttpRouteMethod;
+  /** URL-Pfad (Hono-Pattern, z.B. "/feed.xml" oder "/og/:tenantId.png"). */
+  readonly path: string;
+  /** Wenn true, bypasses die /api/*-Auth-Middleware. Default false —
+   *  Routes liegen außerhalb /api/* und sehen die Auth-Middleware
+   *  ohnehin nicht; das Flag ist semantisch (= "diese Route ist
+   *  bewusst öffentlich") für Boot-Validator + Doku. */
+  readonly anonymous?: boolean;
+  /** Hono-Handler. Bekommt Hono-Context + Framework-Deps; returnt
+   *  Response (sync oder async). */
+  readonly handler: HttpRouteHandler;
+};

package/src/engine/types/identifiers.ts

@@ -0,0 +1,47 @@
+// Domain-identifier type aliases. Used everywhere a tenantId/userId/aggregateId
+// travels through the framework. One declaration per concept so future
+// representation changes (branded types, UUID validation, opaque wrappers)
+// land in a single place.
+
+// Tenant identifier — UUID string today. May become branded/opaque later
+// without touching call sites.
+export type TenantId = string;
+
+// Lowercase UUID (any RFC-4122 variant). Strict enough to keep client-
+// supplied junk (e.g. SQL fragments, path-traversal probes) out of the
+// pipeline; loose enough that v4 / v7 / nil all match. Any caller that
+// already holds a TenantId from a trusted source (JWT payload, server
+// config) skips this — the helper is for **untrusted input** crossing
+// the system boundary.
+const TENANT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+// Validates a candidate string against the tenantId format and returns it
+// as a TenantId, or `null` when it doesn't match. Use at every system
+// boundary that admits untrusted input (HTTP headers, cookies, query
+// params). Returning null instead of throwing keeps the caller in charge
+// of the rejection shape — middleware returns 400, batch jobs may filter
+// + log, and unit tests don't need a try/catch.
+export function parseTenantId(value: unknown): TenantId | null {
+  if (typeof value !== "string") return null;
+  if (!TENANT_ID_REGEX.test(value)) return null;
+  return value;
+}
+
+// "System-scope" tenant marker: handlers carry this tenantId when the event
+// doesn't belong to any particular tenant (reference data, cross-tenant
+// jobs, global config). The concrete UUID is a valid v4 (not all-zeroes —
+// Postgres' UUID type rejects invalid variants), chosen to be easy to
+// eyeball in logs. Central constant so call sites don't re-type the string
+// and the isSystemTenant() check stays in sync.
+export const SYSTEM_TENANT_ID: TenantId = "00000000-0000-4000-8000-000000000000";
+
+export function isSystemTenant(tenantId: TenantId | null | undefined): boolean {
+  return !tenantId || tenantId === SYSTEM_TENANT_ID;
+}
+
+// Primary-key identifier for any entity row. Two shapes coexist because of
+// the entity-def `idType` switch: classic CRUD entities keep `serial` (number),
+// while tenant + ES aggregates run on `uuid` (string). Call sites that pass
+// the id through to the DB layer stay agnostic; only code that formats ids
+// for URLs, logs, or cache keys needs `String(id)` — JS coerces both safely.
+export type EntityId = number | string;

package/src/engine/types/index.ts

@@ -0,0 +1,208 @@
+// Barrel: re-exports all types from logical modules
+// Duplicate types (OnDeleteStrategy, ConfigScope, ConcurrencyMode, LifecycleHookType)
+// are defined ONLY in constants.ts — re-exported here for backwards compatibility.
+
+// Re-export types that were duplicated in types.ts but are canonical in constants.ts
+export type {
+  ConcurrencyMode,
+  ConfigScope,
+  LifecycleHookType,
+  OnDeleteStrategy,
+} from "../constants";
+export type {
+  ConfigAccessor,
+  ConfigAccessorFactory,
+  ConfigBounds,
+  ConfigComputedContext,
+  ConfigComputedFn,
+  ConfigDefinition,
+  ConfigKeyAccess,
+  ConfigKeyDefinition,
+  ConfigKeyHandle,
+  ConfigKeyType,
+  ConfigResolver,
+  ConfigStoredRow,
+  ConfigValue,
+  ConfigValueSource,
+  ConfigValueWithSource,
+  JobDefinition,
+  JobHandlerFn,
+  JobRunIn,
+  JobTrigger,
+  NotificationDataFn,
+  NotificationDefinition,
+  NotificationRecipientFn,
+  NotificationTemplateFn,
+  ReferenceDataDef,
+  RegistrarExtensionDef,
+  RegistrarExtensionHooks,
+  RegistrarExtensionRegistration,
+  RunIn,
+  TranslationEntry,
+  TranslationKeys,
+  TranslationsDef,
+  UiExtensionDef,
+} from "./config";
+// Cross-Feature Compile-Time-Type-Map — features extend per declare-module.
+export type {
+  KumikoEntityTypeMap,
+  KumikoEventTypeMap,
+  KumikoHandlerPayloadMap,
+  KumikoHandlerResultMap,
+} from "./event-type-map";
+export type {
+  FeatureDefinition,
+  FeatureMetricDef,
+  FeatureMetricType,
+  FeatureRegistrar,
+  MetricOptions,
+  Registry,
+  SecretKeyDefinition,
+  SecretKeyHandle,
+  SecretOptions,
+} from "./feature";
+export type {
+  AnyFileFieldDef,
+  BooleanFieldDef,
+  DateFieldDef,
+  DefaultCurrency,
+  EmbeddedFieldDef,
+  EmbeddedSubFieldDef,
+  EntityDefinition,
+  EntityIndexDef,
+  FieldAccess,
+  FieldDefinition,
+  FieldsMap,
+  FileFieldDef,
+  FilesFieldDef,
+  ImageFieldDef,
+  ImagesFieldDef,
+  LocatedTimestampFieldDef,
+  LongTextFieldDef,
+  MoneyFieldDef,
+  MultiSelectFieldDef,
+  NumberFieldDef,
+  ReferenceFieldDef,
+  SelectFieldDef,
+  TextFieldDef,
+  TimestampFieldDef,
+  TransitionMap,
+  TzFieldDef,
+} from "./fields";
+export { DEFAULT_CURRENCIES, isFileField } from "./fields";
+export type {
+  AccessRule,
+  AggregateStreamHandle,
+  AppContext,
+  AppendEventArgs,
+  AppendEventFn,
+  AppendEventUnsafeFn,
+  AuthClaimsContext,
+  AuthClaimsFn,
+  AuthClaimsHookDef,
+  CamelToKebab,
+  ClaimKeyDefinition,
+  ClaimKeyHandle,
+  ClaimKeyJsType,
+  ClaimKeyType,
+  EntityRef,
+  EventDef,
+  EventMigrationDef,
+  EventUpcastCtx,
+  EventUpcastFn,
+  FetchForWritingArgs,
+  HandlerContext,
+  HandlerRef,
+  JobContext,
+  JobRunnerRef,
+  NameOrRef,
+  NotifyFactory,
+  NotifyFn,
+  NotifyOptions,
+  NotifyPriority,
+  QualifiedEventName,
+  QueryEvent,
+  QueryHandlerDef,
+  QueryHandlerFn,
+  RateLimitOption,
+  RateLimitPer,
+  SessionUser,
+  WriteEvent,
+  WriteHandlerDef,
+  WriteHandlerFn,
+  WriteResult,
+} from "./handlers";
+export { resolveName, withResponseData } from "./handlers";
+export type {
+  DeleteContext,
+  EntityHookMap,
+  HookMap,
+  HookOwner,
+  HookPhase,
+  LifecycleHookFn,
+  LifecycleResult,
+  OwnedFn,
+  PhasedHook,
+  PostDeleteBatchHookFn,
+  PostDeleteHookFn,
+  PostSaveBatchHookFn,
+  PostSaveHookFn,
+  PreDeleteHookFn,
+  PreQueryHookFn,
+  PreSaveHookFn,
+  SaveContext,
+  ValidationError,
+  ValidationHookFn,
+} from "./hooks";
+export { HookPhases } from "./hooks";
+export type {
+  HttpRouteDefinition,
+  HttpRouteHandler,
+  HttpRouteHandlerDeps,
+  HttpRouteMethod,
+} from "./http-route";
+// Domain-identifier type aliases — see identifiers.ts for rationale.
+export type { EntityId, TenantId } from "./identifiers";
+export { isSystemTenant, SYSTEM_TENANT_ID } from "./identifiers";
+export type { NavDefinition } from "./nav";
+export type {
+  MspErrorMode,
+  MspErrorPolicy,
+  MultiStreamApplyFn,
+  MultiStreamProjectionDefinition,
+  ProjectionDefinition,
+  ProjectionTable,
+  SingleStreamApplyFn,
+} from "./projection";
+export type {
+  BelongsToRelation,
+  EntityRelations,
+  HasManyRelation,
+  ManyToManyRelation,
+  RelationDefinition,
+} from "./relations";
+export type {
+  ActionFormScreenDefinition,
+  ConfigEditScreenDefinition,
+  CustomScreenDefinition,
+  CustomScreenRoute,
+  EditFieldSpec,
+  EditLayout,
+  EditSectionSpec,
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+  FieldCondition,
+  FieldRenderer,
+  ListColumnSpec,
+  PlatformComponent,
+  RowAction,
+  RowActionNavigate,
+  RowActionWriteHandler,
+  ScreenDefinition,
+  ScreenFilter,
+  ScreenFilterOp,
+  ScreenSlots,
+  ToolbarAction,
+} from "./screen";
+export { normalizeEditField, normalizeListColumn } from "./screen";
+export type { WorkspaceDefinition } from "./workspace";

package/src/engine/types/nav.ts

@@ -0,0 +1,46 @@
+import type { AccessRule } from "./handlers";
+
+// Nav entry declaration. Every feature that wants to appear in the app's
+// navigation tree registers one or more entries via r.nav(). The engine
+// keeps the list flat — ui-core's resolveNavigation assembles the parent/
+// child tree at render time, so changes (toggles, access-gating) don't
+// require re-indexing a tree shape server-side.
+//
+// Cross-feature references are allowed: `screen` may point at any
+// registered screen QN, `parent` at any registered nav QN. The boot
+// validator checks both references exist + rejects parent cycles.
+export type NavDefinition = {
+  // Feature author writes the feature-local short id ("catalog"); the
+  // registry overwrites `id` with the qualified name ("shop:nav:catalog")
+  // in its stored copy. Callers of `registry.getNav(qn)` /
+  // `getTopLevelNavs()` / `getNavsByParent(...)` always see the qualified
+  // id — no parallel reverse index needed. `feature.navs[shortId]` on the
+  // unregistered FeatureDefinition keeps the short form.
+  readonly id: string;
+  // i18n translation key. Resolved at render time by the renderer's
+  // useTranslation hook; engine keeps it opaque.
+  readonly label: string;
+  // Icon key — whatever the icon registry of the active renderer understands.
+  // Engine doesn't validate; unknown icons surface as a missing icon on screen,
+  // not a boot failure.
+  readonly icon?: string;
+  // Qualified name of a parent nav entry ("<feature>:nav:<id>"). Omit for
+  // top-level entries. Boot-validator rejects cycles + dangling refs.
+  readonly parent?: string;
+  // Sort weight within the parent's children (lower = earlier). Ties are
+  // broken by registration order — features registered later appear lower.
+  readonly order?: number;
+  // Qualified name of the screen this entry navigates to
+  // ("<feature>:screen:<id>"). Omit for pure grouping entries (a parent-only
+  // nav node that renders a sub-tree but has no target screen itself).
+  readonly screen?: string;
+  // 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: [] }).
+  readonly access?: AccessRule;
+  // Workspace QNs this entry self-assigns to. Merged at boot with any
+  // r.workspace({ nav: [...] }) explicit lists. Omit to leave workspace
+  // membership decided solely by the workspace's nav list (or both empty
+  // → entry belongs to no workspace).
+  readonly workspaces?: readonly string[];
+};

package/src/engine/types/projection.ts

@@ -0,0 +1,132 @@
+import type { DbRunner } from "../../db/connection";
+import type { TableColumns } from "../../db/dialect";
+import type { StoredEvent } from "../../event-store/event-store";
+import type { MultiStreamApplyContext } from "../../pipeline/multi-stream-apply-context";
+import type { RunIn } from "./config";
+
+// Drizzle pgTable shape — projections hand their table through to apply() so
+// user code writes upserts/updates directly instead of going through a
+// framework-managed state reducer. Using Drizzle's own `PgTableWithColumns<any>`
+// (re-exported as TableColumns) keeps typing honest: drizzle's typed paths work
+// inside apply(), but the column union is erased so framework code doesn't need
+// to know the schema shape of every user table.
+// biome-ignore lint/suspicious/noExplicitAny: Drizzle's PgTable generic needs a concrete row shape; we erase it on purpose because the framework does not know user-defined column types.
+export type ProjectionTable = TableColumns<any>;
+
+// Single-stream projection apply: runs inline in the write-TX of the event
+// it projects. Gets the event + TX-scoped DbRunner — that's it. Inline
+// projections must not spawn further events (no ctx) because they run
+// inside the command's transaction and the framework guarantees a single
+// commit boundary per command.
+//
+// Generic über payload-shape. Default = Record<string, unknown> behält
+// rückwärtskompatibles Verhalten; Konkrete Apply-Handler annotieren
+// `SingleStreamApplyFn<MyPayload>` für typed event.payload-Access.
+export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (
+  event: StoredEvent<TPayload>,
+  tx: DbRunner,
+) => Promise<void>;
+
+// Multi-stream projection apply: runs asynchronously via the event-dispatcher
+// with its own cursor. Gets the event, tx, and a ctx surface for emitting
+// follow-up events (saga / process-manager pattern). ctx.appendEvent +
+// ctx.loadAggregate are the Marten-equivalent of IProjectionSession — write
+// cross-aggregate reactions here, not in single-stream projections.
+export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (
+  event: StoredEvent<TPayload>,
+  tx: DbRunner,
+  ctx: MultiStreamApplyContext,
+) => Promise<void>;
+
+export type ProjectionDefinition = {
+  readonly name: string;
+  // One or more entity names whose events feed this projection. Event-types
+  // are matched in `apply` (e.g. "unit.created") — `source` is only used to
+  // index projections so the executor doesn't scan all projections on every
+  // write.
+  readonly source: string | readonly string[];
+  // Drizzle-table the projection materializes into. User owns the schema —
+  // framework just guarantees the TX and event delivery.
+  readonly table: ProjectionTable;
+  // Keyed by fully-qualified event type ("<aggregate>.<verb>", e.g. "unit.created").
+  // Missing keys are silently skipped — a projection declares only the events it
+  // cares about.
+  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+  // Auto-registered projection (one per r.entity) that exists ONLY to
+  // make rebuildProjection work for entity-tables. Live writes go through
+  // the EventStoreExecutor directly — firing the implicit apply inline
+  // would double-write into the same table. The inline-projection-runner
+  // skips entries with this flag; rebuildProjection treats them
+  // identically to explicit projections.
+  readonly isImplicit?: boolean;
+};
+
+// Per-lifecycle error policy for a MultiStreamProjection. Mirrors Marten's
+// Projections.Errors / Projections.RebuildErrors split — a projection can
+// be lenient during steady-state delivery but strict during rebuild (or
+// vice versa).
+export type MspErrorPolicy = {
+  // When the apply handler throws: log the error, advance the cursor past
+  // the offending event, and keep delivering. Default false — current
+  // strict behaviour: retry up to maxAttempts, then mark the consumer
+  // status="dead" and pause delivery. Use for best-effort sinks
+  // (notifications, webhooks) where a single bad event should not stall
+  // the whole consumer.
+  readonly skipApplyErrors?: boolean;
+};
+
+export type MspErrorMode = {
+  // Applied during steady-state dispatcher delivery.
+  readonly continuous?: MspErrorPolicy;
+  // Applied during rebuildProjection() / backfill passes. When omitted,
+  // rebuild inherits continuous — explicit override common for "strict
+  // during rebuild, lenient in production" patterns.
+  readonly rebuild?: MspErrorPolicy;
+};
+
+// Marten-style MultiStreamProjection: aggregates events from many streams
+// into one cross-cutting read-model. Unlike ProjectionDefinition (single-
+// source, inline in the write-TX), an MSP is ASYNC — the event-dispatcher
+// picks events off the log via its own cursor. Handlers MUST be idempotent
+// because the dispatcher guarantees at-least-once delivery.
+//
+// Use for Sagas / process managers, customer-centric views that span
+// multiple aggregate types, cross-feature aggregations, audit logs. With
+// `table` omitted, the MSP becomes a pure side-effect consumer — sending
+// notifications, posting webhooks, updating an external system. Marten's
+// equivalent of a subscription / event listener, without a separate API.
+export type MultiStreamProjectionDefinition = {
+  readonly name: string;
+  // Optional: omit for side-effect-only handlers (notifications, external
+  // system sync). When present, setupTestStack auto-pushes the table.
+  readonly table?: ProjectionTable;
+  // Keyed by fully-qualified event type. Unlike a single-stream projection,
+  // there is no source-entity hint — the MSP declares the event types it
+  // cares about directly. Extract the identity/grouping key inside the
+  // apply handler from the event payload.
+  readonly apply: Readonly<Record<string, MultiStreamApplyFn>>;
+  // How the dispatcher handles apply-throws. Default strict (retry + dead).
+  readonly errorMode?: MspErrorMode;
+  // Which deploy-lane runs this MSP's dispatcher. Default "worker". MSPs
+  // share a single consumer-row per MSP name with SKIP LOCKED, so "both"
+  // is safe semantically (API + Worker race for each event; exactly one
+  // wins). Use "api" for MSPs that need in-process state on the API
+  // (rare); use "both" only when genuinely load-balancing is helpful.
+  readonly runIn?: RunIn;
+  // Delivery semantics across multi-instance deploys:
+  //   "shared"       (default) — one cursor across all dispatcher instances,
+  //                   SKIP LOCKED serialises; each event delivered exactly
+  //                   once globally. The right choice for side-effects with
+  //                   any downstream state: notifications, external APIs,
+  //                   projection tables, audit rows.
+  //   "per-instance" — one cursor PER dispatcher instance, so every process
+  //                   delivers every event. Required for push-to-local-
+  //                   subscribers (SSE, in-memory caches): a split-deploy
+  //                   where API instance B emits an event that API instance
+  //                   A's clients also need to see. Handler MUST be
+  //                   side-effect-free relative to the DB — it only reaches
+  //                   in-process structures — otherwise each instance
+  //                   writes duplicate rows. Misuse = duplicated side
+  //                   effects, not a safety property.
+  readonly delivery?: "shared" | "per-instance";
+};

package/src/engine/types/relations.ts

@@ -0,0 +1,51 @@
+import type { OnDeleteStrategy } from "../constants";
+
+// --- Relations ---
+
+export type BelongsToRelation = {
+  readonly type: "belongsTo";
+  readonly target: string;
+  readonly foreignKey: string;
+  readonly searchInclude?: readonly string[];
+  // onDelete is declared on the parent-side (hasMany / manyToMany) because
+  // that's where the "what happens to my children?" decision lives. A
+  // belongsTo node just points at a parent — the parent's onDelete drives
+  // the cleanup.
+};
+
+export type HasManyRelation = {
+  readonly type: "hasMany";
+  readonly target: string;
+  readonly foreignKey: string;
+  readonly onDelete?: OnDeleteStrategy;
+  // When true, a nested payload under this relation's key (e.g.
+  // `{ tasks: [{ ... }] }` on a `project:create` write) is auto-expanded
+  // into child writes: parent first, then one child-write per entry with
+  // the foreign key set to the parent's new id — all in the same TX.
+  // Opt-in (default false) so legacy hasMany relations that were declared
+  // purely for cascade-delete or UI-nav semantics don't silently gain a
+  // client-writable path. Children are never inferred from payload-shape
+  // alone; only relations with this flag unlock nested-write.
+  //
+  // Scope v1: depth=1, create-only, hasMany-only. Update-nested,
+  // delete-nested, and belongsTo/m2m auto-expansion are explicit future
+  // work — when they arrive, they'll take the same flag so the opt-in
+  // stays a single, consistent surface.
+  readonly nestedWrite?: boolean;
+};
+
+export type ManyToManyRelation = {
+  readonly type: "manyToMany";
+  readonly target: string;
+  readonly through: {
+    readonly table: string;
+    readonly sourceKey: string;
+    readonly targetKey: string;
+  };
+  readonly searchInclude?: readonly string[];
+  readonly onDelete?: OnDeleteStrategy;
+};
+
+export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
+
+export type EntityRelations = Readonly<Record<string, RelationDefinition>>;