@cosmicdrift/kumiko-types 0.159.1 → 0.161.0

package/src/hook-phase.ts

@@ -0,0 +1,2 @@
+// Keep in sync with HookPhases in packages/framework/src/engine/hook-helpers.ts.
+export type HookPhase = "inTransaction" | "afterCommit";

package/src/hooks.ts

@@ -0,0 +1,170 @@
+import type { StoredEvent } from "./event-store-types";
+import type { AppContext } from "./handlers";
+import type { HookPhase } from "./hook-phase";
+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>>;
+
+// postQuery — fires after query-handler-execute, before field-access-read-filter.
+// Hook receives normalized rows + entityName + can mutate rows (e.g., merge
+// custom-fields, add computed-counts, attach related-data). Mutation result
+// replaces original rows. Hook is responsible for its own field-access-logic
+// on added fields (field-access-filter only knows entity's stammfields).
+export type PostQueryHookFn = (
+  result: {
+    // undefined for standalone queries (no-colon handler names like
+    // "ns:dashboard") — those have no backing entity, but handler-keyed
+    // postQuery hooks still fire on them.
+    readonly entityName: string | undefined;
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+  },
+  context: AppContext,
+) => Promise<{ rows: ReadonlyArray<Record<string, unknown>> }>;
+
+export type LifecycleHookFn =
+  | PreSaveHookFn
+  | PostSaveHookFn
+  | PreDeleteHookFn
+  | PostDeleteHookFn
+  | PreQueryHookFn
+  | PostQueryHookFn;
+
+export type { HookPhase } from "./hook-phase";
+
+// 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 ---
+
+// Slots are optional: defineFeature materializes every slot, but hand-built
+// FeatureDefinitions at system boundaries (test fixtures, partial boots —
+// see registry.test.ts "slot robustness") legitimately omit them, and the
+// registry merge paths tolerate undefined. The type mirrors that contract.
+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>[]>>;
+  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
+};
+
+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>[]>>;
+  readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
+};
+
+// Search-Payload-Extension (F3) — contributor function that adds flat
+// fields to an entity's search-document. Fires synchronously during
+// buildSearchDocument (in `system-hooks.ts`), receives current entity
+// state, returns extra fields to merge into the search-index payload.
+//
+// Use-cases: custom-fields-bundle (merge customFields-jsonb-keys flat
+// into index), tags-bundle (project tags-array as searchable), computed-
+// fields (denormalize related-counts).
+//
+// IMPORTANT: contributor must be deterministic per (entityName, entityId,
+// state). Async-allowed for future-proofing but discouraged — the
+// indexing path runs once per entity-write, sync extension is
+// near-zero-cost.
+export type SearchPayloadContributorFn = (args: {
+  readonly entityName: string;
+  readonly entityId: EntityId;
+  readonly state: Record<string, unknown>;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;

package/src/kms-adapter-types.ts

@@ -0,0 +1,118 @@
+import type { TenantId } from "./identifiers";
+
+// The subject a DEK belongs to. User data is shredded on user-forget,
+// tenant data on tenant-destroy — two erase triggers, two subject kinds.
+export type SubjectId =
+  | { readonly kind: "user"; readonly userId: string }
+  | { readonly kind: "tenant"; readonly tenantId: TenantId };
+
+// Compact storage key ("user:<uuid>" / "tenant:<uuid>") — primary key in
+// adapter backends and cache key in the request-level DEK cache.
+export type SubjectKey = string;
+
+export function subjectKeyForUser(userId: string): SubjectKey {
+  return `user:${userId}`;
+}
+
+export function subjectKeyForTenant(tenantId: TenantId): SubjectKey {
+  return `tenant:${tenantId}`;
+}
+
+export function subjectIdToKey(subject: SubjectId): SubjectKey {
+  return subject.kind === "user"
+    ? subjectKeyForUser(subject.userId)
+    : subjectKeyForTenant(subject.tenantId);
+}
+
+export function subjectIdFromKey(key: SubjectKey): SubjectId {
+  if (key.startsWith("user:")) return { kind: "user", userId: key.slice("user:".length) };
+  if (key.startsWith("tenant:")) {
+    return { kind: "tenant", tenantId: key.slice("tenant:".length) as TenantId }; // @cast-boundary parse of a key this module minted
+  }
+  throw new Error(`Invalid subject key: ${key}`);
+}
+
+export interface KmsContext {
+  readonly tenantId?: TenantId;
+  readonly requestId: string;
+  readonly userId?: string;
+  readonly eraseReason?: string;
+}
+
+export interface KmsHealth {
+  readonly ok: boolean;
+  readonly latencyMs: number;
+  readonly details?: Record<string, unknown>;
+}
+
+// 32-byte AES-256 data-encryption key, unwrapped and ready for local use.
+export type SubjectDek = Buffer;
+
+interface KmsAdapterBase {
+  /**
+   * Creates a fresh subject key. Throws KeyAlreadyExistsError when the
+   * subject already has one — including an erased tombstone: a shredded
+   * subject must never get a new key, or forget could be undone by
+   * re-encrypting under it.
+   */
+  createKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+
+  /**
+   * Erases the key material immediately; the tombstone row stays for the
+   * audit trail. Idempotent — repeat calls and unknown subjects are no-ops.
+   */
+  eraseKey(subject: SubjectId, ctx: KmsContext): Promise<void>;
+
+  /** Probe for boot + readiness. Throws when the backend is unreachable. */
+  health(): Promise<KmsHealth>;
+}
+
+// Backends that hand out the plaintext DEK (Pg, InMemory). Encrypt/decrypt
+// happens locally; DEKs are cacheable per request.
+export interface LocalKeyKmsAdapter extends KmsAdapterBase {
+  readonly capabilities: { readonly mode: "local-key" };
+
+  /**
+   * Throws KeyErasedError after eraseKey (callers render "[[erased]]"),
+   * KeyNotFoundError when the subject never had a key (typically a bug).
+   */
+  getKey(subject: SubjectId, ctx: KmsContext): Promise<SubjectDek>;
+}
+
+// Backends that never release key material (Vault transit, cloud KMS).
+// Every encrypt/decrypt is a round-trip; nothing is cacheable.
+export interface RemoteCryptoKmsAdapter extends KmsAdapterBase {
+  readonly capabilities: { readonly mode: "remote-crypto" };
+
+  encrypt(subject: SubjectId, plaintext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+
+  /** Same error contract as LocalKeyKmsAdapter.getKey. */
+  decrypt(subject: SubjectId, ciphertext: Uint8Array, ctx: KmsContext): Promise<Uint8Array>;
+}
+
+export type KmsAdapter = LocalKeyKmsAdapter | RemoteCryptoKmsAdapter;
+
+export function isLocalKeyKmsAdapter(adapter: KmsAdapter): adapter is LocalKeyKmsAdapter {
+  return adapter.capabilities.mode === "local-key";
+}
+
+export class KeyErasedError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key erased: ${subjectIdToKey(subject)}`);
+    this.name = "KeyErasedError";
+  }
+}
+
+export class KeyNotFoundError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key not found: ${subjectIdToKey(subject)}`);
+    this.name = "KeyNotFoundError";
+  }
+}
+
+export class KeyAlreadyExistsError extends Error {
+  constructor(public readonly subject: SubjectId) {
+    super(`Subject key already exists: ${subjectIdToKey(subject)}`);
+    this.name = "KeyAlreadyExistsError";
+  }
+}

package/src/multi-stream-apply-context-types.ts

@@ -0,0 +1,38 @@
+import type { StoredEvent } from "./event-store-types";
+import type { KumikoEventTypeMap } from "./event-type-map";
+import type { FileContext } from "./file-handle-types";
+import type { AppendEventFn, UnsafeAppendEventFn } from "./handlers";
+
+// Minimal, read+write surface handed to a MultiStreamProjection's apply()
+// when it needs to produce follow-up events (saga / process-manager
+// pattern). Keeps the MSP feature-decoupled: applies don't reach into
+// handler-bridge (no query/write/writeAs), they just read the aggregate
+// stream and append new events — Marten's session scope for projections.
+//
+// TMap propagates the strict event-type-map (see HandlerContext). Default
+// matches the global KumikoEventTypeMap; runtime-pluggable callers route
+// through unsafeAppendEvent.
+export type MultiStreamApplyContext<TMap extends object = KumikoEventTypeMap> = {
+  // Append a domain event onto an aggregate stream in the CURRENT tx.
+  // Schema-validated, archive-guarded, stream-version derived. Metadata
+  // inherits from the triggering event (correlationId) + requestContext
+  // (causationId is already set to the triggering event.id by the
+  // dispatcher wrap). Strict against KumikoEventTypeMap — same contract
+  // as HandlerContext.appendEvent (compile-time-validated payload).
+  readonly appendEvent: AppendEventFn<TMap>;
+  // Escape hatch for runtime-pluggable events without compile-time
+  // augmentation. Same runtime semantics; type-surface is `payload: unknown`.
+  readonly unsafeAppendEvent: UnsafeAppendEventFn;
+  // Read an aggregate stream — useful when a saga needs to inspect the
+  // current state of a different aggregate before deciding what to emit.
+  readonly loadAggregate: (
+    aggregateId: string,
+    options?: { readonly asOf?: Temporal.Instant },
+  ) => Promise<readonly StoredEvent[]>;
+  // Binary storage handle factory, mirrors AppContext.files. Present when
+  // the app booted with `files.storageProvider`; undefined otherwise.
+  // Post-processing MSPs (resize, EXIF-strip, virus-scan) read bytes via
+  // `ctx.files.ref(payload.storageKey).read()` and write derivates via
+  // `.derive("thumb").write(...)` — binaries never ride through events.
+  readonly files?: FileContext;
+};

package/src/nav.ts

@@ -0,0 +1,67 @@
+import type { AccessRule } from "./handlers";
+import type { TargetRef } from "./target-ref";
+import type { TreeAction } from "./tree-node";
+
+// 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;
+  // Polymorphes Klick-Ziel (öffnet die EditorPanel-Maske via Target-
+  // Resolver) — Alternative zu `screen`. Ein Knoten trägt screen XOR
+  // target; der Renderer dispatcht das target statt einen Route-Link zu
+  // rendern. Gespiegelt aus dem alten Visual-Tree (TreeNode.target).
+  readonly target?: TargetRef;
+  // Hover-Actions rechts in der Zeile (VS-Code-Pattern) — erst bei Hover
+  // sichtbar. Reihenfolge wie deklariert.
+  readonly actions?: readonly TreeAction[];
+  // „+"-Affordance am Knoten. Klick dispatcht createAction.target; der
+  // Provider weiß was „leer befüllen" für ihn heißt (neuer Page-Slug etc.).
+  readonly createAction?: TreeAction;
+  // Children kommen zur Laufzeit aus einem registrierten nav-provider
+  // (lazy beim Ausklappen, SSE-live via treeEntities), keyed auf diese
+  // Nav-QN. Macht den Knoten expandable auch ohne statische children.
+  readonly provider?: boolean;
+  // 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
+  // membership decided solely by the workspace's nav list (or both empty
+  // → entry belongs to no workspace).
+  readonly workspaces?: readonly string[];
+};

package/src/ownership.ts

@@ -0,0 +1,83 @@
+// --- Ownership ---
+// Pure types for the declarative Claims → Access bridge. Runtime (from(),
+// matchesRule(), buildOwnershipClause()) stays in engine/ownership.ts, which
+// re-exports these for backwards compatibility.
+
+import type { SessionUser } from "./handlers";
+
+// Parameterised SQL fragment — produced by buildOwnershipClause + by the
+// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
+// renumbering placeholders if needed (shiftParams in engine/ownership.ts).
+export type SqlFragment = {
+  readonly sqlText: string;
+  readonly params: readonly unknown[];
+};
+
+// Reference spec supported by `from()`:
+//   "user:id"                  → user.id
+//   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
+//   "claim:<featureName>:<key>" → user.claims["<featureName>:<key>"]
+//
+// The string form is keyed so the framework can look up the referenced
+// Registry entry at boot (Claim-QN exists? Column type compatible?). A typed
+// object form would force features to import each other's handles — the
+// whole point of H.2's unified path is string-based references, no imports.
+export type OwnershipRef = string;
+
+// Resolved during `from()` — the parser eagerly splits the prefix so the
+// runtime evaluator avoids string-parsing on every row. `kind` drives the
+// evaluator branch; the rest is the resolved metadata.
+export type FromRuleKind = "user" | "claim";
+
+export type FromRule = {
+  readonly kind: "from";
+  readonly refKind: FromRuleKind;
+  // For "user:id" → "id"; for "user:tenantId" → "tenantId".
+  // For "claim:<featureName>:<key>" → "<featureName>:<key>" (the full QN,
+  // which is exactly the key under which the JWT stores the value).
+  readonly refPath: string;
+  // Row-column to match against. For claim rules defaults to the claim's
+  // shortName (second segment of the claim QN). For user-rules the column
+  // is always explicit.
+  readonly column: string;
+};
+
+// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
+// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
+// concatenates the fragment into the larger query.
+export type WhereRuleContext<TTable = unknown> = {
+  readonly table: TTable;
+  readonly tableName: string;
+  readonly paramStart: number;
+};
+
+export type WhereRule<TTable = unknown> = {
+  readonly kind: "where";
+  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
+};
+
+// "all" collapses to a primitive so map authors can write `Admin: "all"`
+// without importing a helper.
+export type OwnershipRule = "all" | FromRule | WhereRule;
+
+// Per-role map: every key is a role name, value is the rule that role
+// satisfies to pass the access check.
+export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+
+// Result of buildOwnershipClause. The discriminant lets the caller handle
+// the three outcomes without inspecting SQL internals:
+//
+//   "pass"  → user is unrestricted. Run the query as-is.
+//   "empty" → user has a role mapped but no rule accepts any row (missing
+//             claim, empty array, role not in map). Skip the DB call entirely
+//             — returning [] is equivalent and avoids a pointless roundtrip.
+//   "sql"   → apply the parameterised fragment as an AND on the query.
+//             Caller is responsible for renumbering placeholders when
+//             concatenating with other fragments (see `shiftParams`).
+//
+// "empty" vs. "pass" is the critical distinction for a safe default:
+// undefined/pass = allow, empty = deny-by-construction.
+export type OwnershipClause =
+  | { readonly kind: "pass" }
+  | { readonly kind: "empty" }
+  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };

package/src/projection.ts

@@ -0,0 +1,164 @@
+import type { RunIn } from "./config";
+import type { DbRunner } from "./db-connection";
+import type { StoredEvent } from "./event-store-types";
+import type { EntityDefinition } from "./fields";
+import type { MultiStreamApplyContext } from "./multi-stream-apply-context-types";
+import type { SchemaTable } from "./schema-table-types";
+
+// 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 the native dialect's `SchemaTable`
+// (drizzle-compat surface) keeps typing honest: 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.
+export type ProjectionTable = SchemaTable;
+
+// Single-stream projection apply: runs inline in the write-TX of the event
+// it projects. Gets the event, the TX-scoped DbRunner, and the projection's
+// own `table` (already erased to ProjectionTable). Write through THAT table —
+// it is the only ES-blessed write into a managed projection outside the
+// executor, and it is reachable only here (an arbitrary handler has no such
+// arg), so the write-brand cannot be bypassed by closing over the branded
+// table constant. 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. Der
+// `table`-Param ist additiv — 2-arg-Applies (event, tx) bleiben gültig.
+export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (
+  event: StoredEvent<TPayload>,
+  tx: DbRunner,
+  table: ProjectionTable,
+) => 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[];
+  // Additional aggregate-types whose events the rebuild replay must include
+  // beyond `source`. Fed by r.extendEntityProjection — an extension can react
+  // to events on foreign streams (e.g. "field-definition") while `source`
+  // keeps meaning "the owning entity" for consumers like soft-delete-cleanup.
+  readonly extraSources?: readonly string[];
+  // Drizzle-table the projection materializes into. User owns the schema —
+  // framework just guarantees the TX and event delivery.
+  readonly table: ProjectionTable;
+  // Optional: the EntityDefinition the table was built from, for projections
+  // without an r.entity registration — lets boot-time GDPR guards see
+  // pii/tenantOwned fields that feature.entities (r.entity-only) would miss.
+  readonly entity?: EntityDefinition;
+  // 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;
+};
+
+// Extension merged into an entity's implicit projection at registry build.
+// Lets a bundled feature that writes into the HOST entity's table via events
+// (custom-fields pattern) hook those event types into the entity's rebuild
+// replay — without it, a rebuild resets everything the extension wrote.
+// Live delivery stays with the extension's own MSP: implicit projections are
+// skipped by the inline runner, so the apply here runs ONLY during rebuild.
+export type EntityProjectionExtension = {
+  // Aggregate-types beyond the entity's own stream whose events the rebuild
+  // must scan (e.g. "field-definition"). Omit when all extension events are
+  // appended on the host entity's stream.
+  readonly sources?: readonly string[];
+  // Keyed by fully-qualified event type. Must not collide with the entity's
+  // built-in lifecycle applies (<entity>.created/updated/...) or another
+  // extension — collisions fail at boot.
+  readonly apply: Readonly<Record<string, SingleStreamApplyFn>>;
+};
+
+// 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";
+};