@cosmicdrift/kumiko-framework 0.159.1 → 0.161.0

package/src/engine/types/step.ts

@@ -1,334 +1,2 @@
-// Step-Vocabulary Types — see docs/plans/architecture/intern/step-vocabulary.md
-//
-// M.1 minimal scope:
-//   - Steps execute against the existing HandlerContext (no per-step subset).
-//   - steps-accumulator is Record<string, unknown> (no tuple-reduce typing).
-//   - Resolvers receive the full PipelineCtx as one argument.
-//
-// Strict typing on appendEvent inside steps is deferred to a later pass
-// (see TS-typing notes in the design doc). M.1 uses unsafeAppendEvent
-// semantics under the hood for r.step.aggregate.appendEvent.
-
-import type { EventStoreExecutor } from "../../db/event-store-executor";
-import type { WhereObject } from "../../db/query";
-import type { KumikoEventTypeMap } from "./event-type-map";
-import type { HandlerContext, WriteEvent, WriteResult } from "./handlers";
-import type { SaveContext } from "./hooks";
-import type { EntityId } from "./identifiers";
-
-/**
- * The kind discriminator for a step instance — matches the step's
- * registration name in the step-registry (e.g. "return", "compute",
- * "aggregate.create"). Steps register themselves at module-load time
- * via defineStep().
- */
-export type StepKind = string;
-
-/**
- * Pipeline-side context handed to step argument resolvers.
- *
- * Contains the full HandlerContext (no per-step subset in M.1) plus
- * the accumulated `steps` map of prior step results, and a `scope`
- * record for forEach/branch-local bindings.
- *
- * `scope` is `Record<string, unknown>` — sub-step builders (forEach,
- * branch) populate it once they land in later M.1 slices. M.1.1 ships
- * with `r.step.return` only, which reads `event` and ignores both
- * `steps` and `scope`.
- */
-export type PipelineCtx<
-  TPayload = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = HandlerContext<TMap> & {
-  readonly event: WriteEvent<TPayload>;
-  readonly steps: Readonly<Record<string, unknown>>;
-  readonly scope: Readonly<Record<string, unknown>>;
-  // Workflow-run context — present only when running inside defineWorkflow.
-  // Tier-3 steps use this to write suspension events onto the correct
-  // aggregate stream and for the Resume-Loop to re-hydrate state.
-  readonly workflow?: {
-    readonly runId: string;
-    readonly workflowName: string;
-    /** Current step index in the pipeline — set by the executor before each step. */
-    readonly stepIndex: number;
-    /**
-     * Retry attempt counter for the current workflow.retry step.
-     * Set by the workflow-engine resume-loop on re-entry; starts at 1.
-     * Absent (undefined) means first attempt.
-     */
-    readonly retryAttempt?: number;
-    /**
-     * Q7 Snapshot-at-Start fingerprint of the workflow definition that
-     * started this run. Propagated into every suspension event payload so
-     * the resume-loop can detect library-upgrades that changed the closure
-     * source and surface them as a typed failure instead of running a
-     * stale-vs-new mix of steps. Optional only for legacy callers; the
-     * workflow-runner sets it on every newly-started run.
-     */
-    readonly definitionFingerprint?: string;
-  };
-};
-
-/**
- * A resolver is either a static value or a function that derives the
- * value from the pipeline-context. M.1 keeps the resolver signature
- * uniform — every step accepts both forms via a normalise helper.
- */
-export type StepResolver<T, TPayload = unknown> = T | ((ctx: PipelineCtx<TPayload>) => T);
-
-/**
- * Per-step error strategy. M.1.1 only supports "throw" — the type is
- * deliberately narrowed so callers cannot pass an unsupported strategy
- * past the type-checker. The doc lists "return" / "skip" / fallback as
- * future strategies; each lands together with its own runtime support
- * + integration test in a later slice (no untested type expansion).
- */
-export type StepFailureStrategy = "throw";
-
-export type StepDef<TArgs = unknown, TResult = unknown> = {
-  readonly kind: StepKind;
-  readonly defaultFailureStrategy: StepFailureStrategy;
-  // Returns the result-key for this step instance, or undefined when the
-  // step doesn't surface a result. The first-position name on the call
-  // (e.g. r.step.compute("startedAt", fn) → "startedAt") becomes the key.
-  readonly resultKey?: (args: TArgs) => string | undefined;
-  // Sub-pipeline arg-paths — names of `args.<path>` entries that hold a
-  // readonly StepInstance[] (e.g. branch's `["onTrue", "onFalse"]`, forEach's
-  // `["do"]`). The boot-validator reads these at registration time so it
-  // can recurse into nested pipelines without a hardcoded kind-list. Steps
-  // that don't carry sub-pipelines omit the field. Followup #15 self-
-  // registration: prevents future sub-step-builders from silently bypassing
-  // the unsafeProjection allowlist by forgetting to update a central map.
-  readonly subPaths?: readonly string[];
-  // Step-vocabulary tier (Q9). Tier-1 implicit, Tier-2+ requires
-  // r.requires.step("<kind>") in the owning feature. Default 1 (implicit).
-  // Tier-3 is only available inside defineWorkflow.
-  readonly tier?: 1 | 2 | 3;
-  // Runtime: resolve the args against the ctx, perform the work, return
-  // the value to land in steps.{resultKey}. Thrown errors propagate to
-  // the dispatcher's catch (M.1.1 supports "throw"-strategy only).
-  readonly run: (args: TArgs, ctx: PipelineCtx) => Promise<TResult> | TResult;
-};
-
-/**
- * An instance of a step in a pipeline — what users build via the
- * step-builder (`r.step.compute(...)`). Carries the kind + resolved-or-
- * resolver args + the user-chosen onFailure override.
- *
- * `args` is `unknown` at this layer — the registered StepDef knows the
- * concrete shape and casts at run() time. Cross-step type-safety lives
- * in the per-step builder factories, not in this central type.
- */
-export type StepInstance = {
-  readonly kind: StepKind;
-  readonly args: unknown;
-  readonly onFailure?: StepFailureStrategy;
-};
-
-/**
- * What `stepsPipeline(closure)` returns. Carries the closure (instead of an
- * eagerly-built array) so each handler-call sees a fresh event ref and
- * the `r` step-builder is resolved at runtime, not at module-load time.
- *
- * `__kind: "pipeline"` lets defineWriteHandler distinguish a pipeline-
- * form `perform` from accidental other shapes.
- *
- * `_TData` is a phantom type-parameter — held in constraint position
- * only, never referenced in the type body. defineWriteHandler binds it
- * via `def.perform: PipelineDef<…, TData>` (the call-site uses TData
- * without underscore — phantom-prefix is purely a Biome
- * `noUnusedVariables` marker, not user-facing). _TData is NOT inferred
- * from the closure body (r.step.return has its own per-call TData), so
- * callers must spell it explicitly:
- *   `stepsPipeline<{ greeting: string }, { echoed: string }>(...)`
- * Better DX is a known follow-up — see step-vocabulary.md M.1-Followups.
- */
-export type PipelineDef<TPayload = unknown, _TData = unknown> = {
-  readonly __kind: "pipeline";
-  readonly build: (ctx: PipelineBuildCtx<TPayload>) => readonly StepInstance[];
-};
-
-/**
- * Argument bundle passed to the closure inside `stepsPipeline(closure)`.
- * Build-time only — no `steps`, no `scope`, no `db`: at build time no
- * step has run yet.
- *
- * The closure is invoked ONCE per handler-call and returns the immutable
- * list of step instances. Values inside the closure that depend on prior
- * step results MUST go through resolvers (functions) — those receive the
- * resolver-side PipelineCtx which carries `steps` + `scope`.
- *
- * **Closure-body contract:** the closure must produce a deterministic
- * step-list that doesn't depend on `event.payload` — branching on payload
- * fields belongs inside resolvers (where they fire per-call), not in the
- * outer closure body. Boot-validation runs the closure once with a dummy
- * empty payload to scan unsafeProjection-* step targets; a closure that
- * conditionally builds different step-lists per payload would silently
- * skip validation. See validate-projection-allowlist.ts for the
- * boot-side mechanics.
- */
-export type PipelineBuildCtx<TPayload = unknown> = {
-  readonly event: WriteEvent<TPayload>;
-  readonly r: StepBuilder;
-};
-
-/**
- * Step-builder namespace handed to the pipeline closure. The fields
- * grow as M.1 adds more steps. Each is a thin factory that returns a
- * StepInstance — the runtime resolution happens later in run().
- *
- * Why nested under `step`: matches the doc-API surface and leaves room
- * for future sibling namespaces (`r.trigger`, `r.transform`) without
- * crowding the top-level r.
- */
-export type StepBuilder = {
-  readonly step: StepNamespace;
-};
-
-/**
- * The collection of step factory functions. Grown incrementally —
- * landed: return (M.1.1), compute (M.1.2), unsafeProjectionUpsert
- * (M.1.3), aggregate.create (M.1.4). Pending: branch, forEach,
- * read.*, aggregate.update, aggregate.appendEvent,
- * unsafeProjectionDelete.
- */
-export type StepNamespace = {
-  readonly return: <TData>(resolver: StepResolver<WriteResult<TData>>) => StepInstance;
-  readonly compute: <TResult>(name: string, fn: (ctx: PipelineCtx) => TResult) => StepInstance;
-  // Inline read-side projection write. Boot-validation enforces the
-  // table is in the owning feature's r.requires.projection allowlist
-  // and NOT registered as an aggregate-table via r.entity. See
-  // step-vocabulary.md "Was unsafeProjection.* überspringt".
-  readonly unsafeProjectionUpsert: (args: {
-    readonly table: unknown;
-    readonly on: readonly string[];
-    readonly row: StepResolver<Record<string, unknown>>;
-  }) => StepInstance;
-  // Sibling: delete row(s) from a read-side projection table. Same
-  // boot-validation contract as unsafeProjectionUpsert.
-  readonly unsafeProjectionDelete: (args: {
-    readonly table: unknown;
-    readonly where: StepResolver<WhereObject>;
-  }) => StepInstance;
-  // Read sub-namespace — thin wrapper on selectMany/fetchOne (bun-db).
-  // Caller-owned tenant-filter (does NOT auto-inject like ctx.queryProjection does).
-  readonly read: {
-    readonly findOne: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where: StepResolver<WhereObject | undefined>;
-      },
-    ) => StepInstance;
-    readonly findMany: (
-      name: string,
-      opts: {
-        readonly table: unknown;
-        readonly where?: StepResolver<WhereObject | undefined>;
-        readonly limit?: number;
-      },
-    ) => StepInstance;
-  };
-  // Aggregate-mutation sub-namespace — wraps the existing event-store-
-  // executor surface. Every method goes through the full ES pipeline
-  // (events + projections + lifecycle hooks + audit). The default and
-  // intended path for domain mutation; contrast with unsafeProjection.*.
-  readonly aggregate: {
-    readonly create: (
-      name: string,
-      opts: {
-        readonly executor: EventStoreExecutor;
-        readonly data: StepResolver<Record<string, unknown>>;
-      },
-    ) => StepInstance;
-    readonly update: (
-      name: string,
-      opts: {
-        readonly executor: EventStoreExecutor;
-        readonly id: StepResolver<EntityId>;
-        readonly changes: StepResolver<Record<string, unknown>>;
-        readonly version?: StepResolver<number | undefined>;
-        readonly skipOptimisticLock?: boolean;
-      },
-    ) => StepInstance;
-    readonly appendEvent: (args: {
-      readonly aggregateId: StepResolver<string>;
-      readonly aggregateType: string;
-      readonly type: string;
-      readonly payload: StepResolver<unknown>;
-      readonly headers?: StepResolver<Readonly<Record<string, string | number | boolean>>>;
-    }) => StepInstance;
-  };
-  // Conditional sub-pipeline. `onTrue` (required) and `onFalse`
-  // (optional) are static StepInstance arrays; `r` for sub-step builders
-  // is captured from the outer pipeline closure. Naming-Q14: `onTrue`/
-  // `onFalse` over `then`/`else` because Biome's noThenProperty lint
-  // flags `then` as a thenable-trap. Q12: r.step.return inside
-  // onTrue/onFalse is rejected at build time (would trigger
-  // discriminated-union TData trap). Q13: no resultKey — branch is
-  // side-effect-only.
-  readonly branch: (args: {
-    readonly if: StepResolver<boolean>;
-    readonly onTrue: readonly StepInstance[];
-    readonly onFalse?: readonly StepInstance[];
-  }) => StepInstance;
-  // Iterate a sub-pipeline over an array. `as` is required (Q15);
-  // current item lands under `scope[as]` for resolvers in `do`.
-  // Sequential only in M.1.6; concurrency is Followup #12.
-  readonly forEach: <TItem = unknown>(args: {
-    readonly over: StepResolver<readonly TItem[]>;
-    readonly as: string;
-    readonly do: readonly StepInstance[];
-    readonly concurrency?: 1;
-  }) => StepInstance;
-  // Tier-2 namespace. Each builder requires r.requires.step("<kind>")
-  // in the owning feature; boot-validation enforces.
-  readonly webhook: {
-    readonly send: (args: {
-      readonly url: StepResolver<string>;
-      readonly method?: "POST" | "PUT" | "PATCH";
-      readonly headers?: StepResolver<Readonly<Record<string, string>>>;
-      readonly body?: StepResolver<unknown>;
-      readonly auth?:
-        | { readonly kind: "bearer"; readonly secretRef: string }
-        | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
-      readonly mode: "deferred";
-      readonly retry?: { readonly times: number; readonly backoff: "exponential" | "linear" };
-    }) => StepInstance;
-  };
-  readonly mail: {
-    readonly send: (args: {
-      readonly to: StepResolver<string | readonly string[]>;
-      readonly subject: StepResolver<string>;
-      readonly body: StepResolver<string>;
-      readonly from?: StepResolver<string>;
-      readonly mode: "deferred";
-    }) => StepInstance;
-  };
-  readonly callFeature: (
-    name: string,
-    opts: {
-      readonly handler: string;
-      readonly payload: StepResolver<unknown>;
-      readonly as?: import("./handlers").SessionUser;
-    },
-  ) => StepInstance;
-  // --- Tier-3 / Workflow-only steps ---
-  // Only available inside defineWorkflow ({ steps: stepsPipeline(...) }).
-  // Runtime guard: throws when used inside sync defineWriteHandler.
-  readonly wait: (args: { readonly for: StepResolver<string> }) => StepInstance;
-  readonly waitForEvent: (args: {
-    readonly event: string;
-    readonly match?: StepResolver<(payload: unknown) => boolean>;
-    readonly timeout: StepResolver<string>;
-  }) => StepInstance;
-  readonly retry: (args: {
-    readonly times: number;
-    readonly backoff: "exponential" | "linear";
-    readonly do: readonly StepInstance[];
-  }) => StepInstance;
-};
-
-// SaveContext is the result-type of aggregate.create / aggregate.update;
-// re-exported for step authors who want to type their resolver bindings.
-export type AggregateStepResult = SaveContext;
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/step";

package/src/engine/types/workspace.ts

@@ -1,42 +1,2 @@
-import type { AccessRule } from "./handlers";
-
-// Workspace declaration. A workspace is a persona-/role-scoped UI surface:
-// pure UI composition with no backend, DB or auth impact. The engine stores
-// these verbatim and the active web shell (shellWorkspaces) renders the
-// switcher and filters the nav tree by membership + access.
-//
-// Membership is computed from two sources, merged at boot:
-//   1. r.workspace({ nav: [...] }) — explicit list of nav QNs
-//   2. r.nav({ workspaces: [...] }) — nav entry self-assigns to workspaces
-// A nav entry that appears in neither source belongs to no workspace and
-// only shows up when no workspace is active (legacy / non-workspace apps).
-//
-// Cross-feature references are allowed: `nav` may point at any registered
-// nav QN. The boot validator checks references exist and that workspace
-// IDs referenced from r.nav are real.
-export type WorkspaceDefinition = {
-  // Feature author writes the short id ("disposition"); the registry
-  // overwrites `id` with the qualified name ("bmc:workspace:disposition")
-  // in its stored copy. Same pattern as NavDefinition / ScreenDefinition.
-  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 (mirrors NavDefinition.icon).
-  readonly icon?: string;
-  // Sort weight in the workspace switcher (lower = earlier). Ties broken
-  // by registration order — features registered later appear lower.
-  readonly order?: number;
-  // Role / openToAll gate. Only users matching this rule see the workspace
-  // in their switcher. Mirrors NavDefinition.access — same semantics across
-  // the UI surface, so a default-deny app can do `{ roles: [] }`.
-  readonly access?: AccessRule;
-  // Explicit nav QNs that belong to this workspace. Merged with any nav
-  // entries that self-assign via r.nav({ workspaces: [...] }).
-  readonly nav?: readonly string[];
-  // Default workspace at login when the user has access to multiple. Boot
-  // validator rejects more than one default per app.
-  readonly default?: boolean;
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/workspace";

package/src/errors/write-error-info.ts

@@ -1,30 +1,14 @@
+import type {
+  WriteErrorInfo,
+  WriteFailure,
+} from "@cosmicdrift/kumiko-types/write-error-info-types";
 import { NotFoundError, UnprocessableError } from "./classes";
 import { KumikoError } from "./kumiko-error";
 import { FrameworkReasons } from "./reasons";
 import { buildInvalidTransitionDetails } from "./transition-details";
 
-// Plain, JSON-serializable snapshot of a KumikoError for use on the write-path
-// (WriteResult.error, BatchResult.error). The dispatcher stores results under
-// an idempotency key — a KumikoError instance wouldn't round-trip through
-// JSON, so we keep structural data only and rebuild the instance on demand
-// via reraiseAsKumikoError when we need to throw upstream again.
-export type WriteErrorInfo = {
-  readonly code: string;
-  readonly httpStatus: number;
-  readonly i18nKey: string;
-  readonly i18nParams?: Readonly<Record<string, unknown>>;
-  readonly message: string;
-  readonly details?: unknown;
-};
-
-// The failure half of WriteResult — `{ isSuccess: false } + error`. Named
-// so the three write-failure factories below and WriteResult share one
-// shape instead of restating it. Not generic: the error carries zero data,
-// so there's nothing for the caller to narrow.
-export type WriteFailure = {
-  readonly isSuccess: false;
-  readonly error: WriteErrorInfo;
-};
+// Legacy types — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/write-error-info-types";
 
 // Convenience for call sites that return a failed WriteResult. Keeps the
 // pattern `return writeFailure(new NotFoundError(...))` compact so handlers

package/src/event-store/errors.ts

@@ -1,35 +1,2 @@
-// Failure modes of the event-store's append() path. Surfaced as typed
-// errors so the executor layer can map them to the framework's
-// WriteResult error contract (version_conflict).
-
-export class VersionConflictError extends Error {
-  public readonly aggregateId: string;
-  public readonly expectedVersion: number;
-  constructor(aggregateId: string, expectedVersion: number) {
-    super(
-      `Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`,
-    );
-    this.name = "VersionConflictError";
-    this.aggregateId = aggregateId;
-    this.expectedVersion = expectedVersion;
-  }
-}
-
-// Thrown when ctx.appendEvent targets an archived stream. Archived aggregates
-// are read-only — restoreStream() makes them writable again. The archive
-// state is not carried on the events themselves; it lives on the sparse
-// kumiko_archived_streams table. Handlers that need to branch on archive
-// state should call ctx.isStreamArchived(id) first.
-export class ArchivedStreamError extends Error {
-  public readonly tenantId: string;
-  public readonly aggregateId: string;
-  constructor(tenantId: string, aggregateId: string) {
-    super(
-      `Aggregate ${aggregateId} on tenant ${tenantId} is archived — appendEvent is blocked. ` +
-        `Call restoreStream() to re-open the stream before writing.`,
-    );
-    this.name = "ArchivedStreamError";
-    this.tenantId = tenantId;
-    this.aggregateId = aggregateId;
-  }
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/event-store-errors";

package/src/event-store/event-store.ts

@@ -1,3 +1,4 @@
+import type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 import { encryptEventPayloadPii } from "../crypto/event-pii";
 import type { DbRunner } from "../db";
 import { isUniqueViolation } from "../db/pg-error";
@@ -15,9 +16,8 @@ import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
 import { toStoredEvent } from "./row-to-stored-event";
-import type { EventMetadata } from "./types";
 
-export type { EventMetadata } from "./types";
+export type { EventMetadata, StoredEvent } from "@cosmicdrift/kumiko-types/event-store-types";
 
 export type EventToAppend = {
   readonly aggregateId: string;
@@ -31,25 +31,6 @@ export type EventToAppend = {
   readonly metadata: EventMetadata;
 };
 
-// Generic über payload-shape. Default = Record<string, unknown> macht
-// alle existierenden Konsumenten backwards-compatible. Konkrete Apply-
-// Handler / Tests können `StoredEvent<MyEventPayload>` annotieren um
-// payload typed zu lesen. Type-Propagation kommt durch r.defineEvent +
-// SingleStreamApplyFn<T> in apply-Maps.
-export type StoredEvent<TPayload = Record<string, unknown>> = {
-  readonly id: string;
-  readonly aggregateId: string;
-  readonly aggregateType: string;
-  readonly tenantId: TenantId;
-  readonly version: number;
-  readonly type: string;
-  readonly eventVersion: number;
-  readonly payload: TPayload;
-  readonly metadata: EventMetadata;
-  readonly createdAt: Temporal.Instant;
-  readonly createdBy: string;
-};
-
 type SelectedEvent = {
   readonly id: bigint;
   readonly aggregateId: string;

package/src/event-store/snapshot.ts

@@ -1,5 +1,10 @@
 // sql now comes from native dialect
 
+import type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 import type { DbConnection, DbRunner } from "../db/connection";
 import {
   index,
@@ -18,7 +23,7 @@ import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
 import { isStreamArchived } from "./archive";
-import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
+import { loadEventsAfterVersion } from "./event-store";
 
 // Marten-aligned snapshot store. A snapshot is a point-in-time materialised
 // state of an aggregate at a specific version, cached so rehydrating the
@@ -157,40 +162,11 @@ export async function loadLatestSnapshot<
   };
 }
 
-// Reducer used to fold events onto a state. Kept narrow and pure — the
-// caller supplies the shape and update rules. Mirrors the reducer shape
-// feature authors already write for r.projection.apply.
-export type SnapshotReducer<TState extends Record<string, unknown>> = (
-  state: TState,
-  event: StoredEvent,
-) => TState;
-
-export type LoadAggregateWithSnapshotResult<TState extends Record<string, unknown>> = {
-  readonly state: TState;
-  readonly version: number;
-  readonly snapshotHit: boolean;
-};
-
-export type LoadAggregateWithSnapshotOptions = {
-  // Opt-in: include archived streams in the rehydrate. Default false — same
-  // semantics as loadAggregate / loadAggregateAsOf. Archive check is a
-  // single indexed lookup, so the cost stays negligible on the hot path.
-  readonly includeArchived?: boolean;
-  // Optional upcaster step: every delta event goes through this transform
-  // BEFORE the reducer sees it. The dispatcher wires this up with
-  // r.eventMigration so feature code always sees current-version payloads.
-  // Async to support Marten-style AsyncOnlyEventUpcaster (DB lookups).
-  readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
-  // Auto-snapshot policy: when the fold applied at least this many delta
-  // events, persist a fresh snapshot at the folded version (best-effort —
-  // a failed save never fails the load). Omit to keep snapshotting manual.
-  readonly snapshotEvery?: number;
-  // Reducer-shape generation stamped onto saved snapshots (default 1). A
-  // stored snapshot with a different generation is ignored — full replay
-  // through the upcaster chain — and restamped on the next auto-save. Bump
-  // whenever the reducer's state shape changes.
-  readonly snapshotVersion?: number;
-};
+export type {
+  LoadAggregateWithSnapshotOptions,
+  LoadAggregateWithSnapshotResult,
+  SnapshotReducer,
+} from "@cosmicdrift/kumiko-types/snapshot-types";
 
 // Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
 // events strictly newer than snapshot.version, and returns the fold.

package/src/event-store/types.ts

@@ -1,22 +1,2 @@
-export type EventMetadata = {
-  readonly userId: string;
-  readonly requestId?: string;
-  // End-to-end business-operation id. Root HTTP requests get it from the
-  // x-correlation-id header (default: requestId). MSP-applies inherit it
-  // from the triggering event. Lets you trace "which user click caused
-  // this email 3 streams later?".
-  readonly correlationId?: string;
-  // Stored event id that triggered this write. Null for root commands;
-  // set to event.id when an MSP-apply runs ctx.appendEvent. Together with
-  // correlationId forms a causation DAG across aggregate streams.
-  readonly causationId?: string;
-  // Marten-conform free key/value space for app-specific metadata that
-  // doesn't deserve its own EventMetadata field. Examples: A/B-test bucket,
-  // feature-flag snapshot, geo-region, client SDK version. Persisted into
-  // events.metadata jsonb (no schema change — it's already a free-form
-  // jsonb column), survives upcasters untouched, available on every
-  // StoredEvent.metadata.headers. Framework does not interpret values; the
-  // app reads them when filtering/auditing. Keep values JSON-primitive
-  // (string|number|boolean) so JSON serialization stays bulletproof.
-  readonly headers?: Readonly<Record<string, string | number | boolean>>;
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/event-store-types";

package/src/files/provider-resolver.ts

@@ -12,11 +12,12 @@
 // file-foundation re-exports `createFileProviderForTenant` + the plugin types
 // (moved here from there) so existing imports keep working.
 
+import type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 import type { DbConnection } from "../db/connection";
 import type { TenantDb } from "../db/tenant-db";
 import { EXT_FILE_PROVIDER, FILE_PROVIDER_CONFIG_KEY } from "../engine/extension-names";
 import { SYSTEM_USER_ID } from "../engine/system-user";
-import type { ConfigAccessor, ConfigAccessorFactory, Registry, TenantId } from "../engine/types";
+import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/types";
 import type { SecretsContext } from "../secrets";
 import type { FileStorageProvider } from "./types";
 
@@ -120,10 +121,7 @@ export async function createFileProviderForTenant(
   return usage.options.build(ctx, tenantId);
 }
 
-// A bound, per-tenant provider resolver. One instance serves all tenants
-// (tenantId is the call argument) — the single spine shared by upload routes,
-// ctx.files and the GDPR jobs.
-export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;
+export type { FileProviderResolver } from "@cosmicdrift/kumiko-types/file-provider-resolver-types";
 
 export type FileProviderResolverDeps = {
   readonly registry?: Registry;