@cosmicdrift/kumiko-types 0.327.0 → 0.328.0

package/src/nav.ts

@@ -1,139 +0,0 @@
-import type { AccessRule } from "./handlers";
-import type { NavIconKey } from "./nav-icon";
-import type { TargetRef } from "./target-ref";
-import type { TreeAction } from "./tree-node";
-
-export type { IconKey, NavIconKey } from "./nav-icon";
-
-// 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 from the closed NavIconKey vocabulary (see nav-icon.ts). Every
-  // renderer's icon map is checked against the same union, so a typo'd key
-  // is a compile error here rather than a missing icon at runtime.
-  readonly icon?: NavIconKey;
-  // 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 on the node. Click navigates to createAction.screen or
-  // dispatches createAction.target; the provider knows what "create empty"
-  // means for it (new 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[];
-};
-
-// A feature's content collection — a set of template-resources of one `kind`,
-// mounted in the nav next to the feature it belongs to rather than under a
-// central "Content" section. Declared via r.contentCollection(), which
-// registers the nav entry (always `provider: true`, the tree children arrive
-// at runtime) and records the `kind` so the client can build the matching tree
-// provider without the app repeating it.
-//
-// `parent` may point at another feature's nav QN; the boot validator rejects
-// dangling refs, so a collection mounted under a feature that isn't mounted
-// fails boot instead of silently disappearing from the sidebar.
-/** Client editor format for r.contentCollection() — not template body storage formats. */
-export type ContentEditorFormat = "plain" | "rich" | "markdown";
-
-export type ContentCollectionDefinition = {
-  // Feature-local short id, kebab-case. Also becomes the nav entry's id, so
-  // it must not collide with an r.nav()/r.screen() id in the same feature.
-  // Handlers take this id, not a kind — a payload can therefore only ever
-  // address a declared collection, with the rules that were declared for it.
-  readonly id: string;
-  // Which template-resource kind this collection lists ("mail-html",
-  // "document-pdf", "text-block", ...). The engine keeps it opaque —
-  // bundled-features owns the kind vocabulary. Two collections may share a
-  // kind and still differ in access and ownership.
-  readonly kind: string;
-  // Who may read and write this collection's entries. Declared at mount time
-  // by the app, because a bundled feature cannot know the host's role
-  // vocabulary — same reasoning as the `access` option on tags/folders/ledger.
-  // Omitted means the mounting app didn't decide; the feature's own default
-  // applies.
-  readonly access?: AccessRule;
-  // "tenant": one set of entries shared by everyone in the tenant (reply
-  // snippets an admin curates). "user": every user keeps their own (mail
-  // signatures). Defaults to "tenant".
-  readonly ownership?: "tenant" | "user";
-  // Which editor the client renders for this collection's entries — not how
-  // the content is stored. "rich" still stores HTML, because mail and PDF
-  // rendering want HTML either way. "markdown" stores markdown text, not
-  // HTML. Defaults to "plain" (textarea).
-  readonly contentFormat?: ContentEditorFormat;
-  // Fixed variable names the collection's editor offers as insertable chips,
-  // mapped to an example value the Preview substitutes in for `{{name}}`
-  // (e.g. `{ customerName: "Max Mustermann", orderId: "A-1042" }` for an
-  // ai-prompt collection). Declared once per collection, not per entry — a
-  // collection-set write always persists an entry's own `variableSchema` as
-  // `{}` (collections never let a user redefine the variable set), so this
-  // is the only place the client can learn which variables exist and what
-  // their preview values are.
-  readonly variableSchema?: Readonly<Record<string, string>>;
-  readonly nav: {
-    readonly label: string;
-    readonly icon?: NavIconKey;
-    readonly parent?: string;
-    readonly order?: number;
-    // Visibility of the nav node. Leave unset — it then follows the
-    // collection's `access`, so the sidebar never offers a node whose
-    // contents the handler will refuse. Set it only to hide the node from
-    // someone who may still reach the data another way.
-    readonly access?: AccessRule;
-    readonly workspaces?: readonly string[];
-    // "+" affordance on the node and hover actions on the row — same meaning
-    // as on NavDefinition. Without a createAction a collection can only list
-    // what already exists; the target is usually the owning feature's
-    // r.treeActions create.
-    readonly createAction?: TreeAction;
-    readonly actions?: readonly TreeAction[];
-  };
-};

package/src/observability/index.ts

@@ -1,28 +0,0 @@
-// Barrel for observability types. Split into span/metric/provider so each module stays focused.
-
-export type {
-  Counter,
-  Gauge,
-  Histogram,
-  Meter,
-  MetricDefinition,
-  MetricLabels,
-  MetricsHandle,
-  MetricType,
-} from "./metric";
-export type {
-  ObservabilityOptions,
-  ObservabilityProvider,
-  SamplingConfig,
-  SensitiveFilterConfig,
-} from "./provider";
-export type {
-  SerializedTraceContext,
-  Span,
-  SpanAttributes,
-  SpanAttributeValue,
-  SpanKind,
-  SpanStatus,
-  StartSpanOptions,
-  Tracer,
-} from "./span";

package/src/observability/metric.ts

@@ -1,56 +0,0 @@
-// Metric + Meter contract. Feature code interacts through ctx.metrics
-// (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
-
-export type MetricLabels = Record<string, string | number | boolean>;
-
-export type MetricType = "counter" | "histogram" | "gauge";
-
-export type MetricDefinition = {
-  // Fully-qualified name (with kumiko_<feature>_ prefix already applied).
-  readonly name: string;
-  readonly type: MetricType;
-  readonly description?: string;
-  // Declared label keys. Inc/observe calls with unknown label keys throw.
-  readonly labels?: readonly string[];
-  // Buckets only for histogram. If omitted, provider-default is used.
-  readonly buckets?: readonly number[];
-  readonly unit?: string;
-  // If true, the framework auto-injects tenant_id from the active ctx.
-  // Default false — adding tenant_id multiplies cardinality by tenant count.
-  readonly tenantLabel?: boolean;
-};
-
-export interface Counter {
-  inc(value?: number, labels?: MetricLabels): void;
-}
-
-export interface Histogram {
-  observe(value: number, labels?: MetricLabels): void;
-}
-
-export interface Gauge {
-  set(value: number, labels?: MetricLabels): void;
-  inc(value?: number, labels?: MetricLabels): void;
-  dec(value?: number, labels?: MetricLabels): void;
-}
-
-export interface Meter {
-  // Called once per metric during boot. Duplicate names throw.
-  registerMetric(def: MetricDefinition): void;
-  // Lookup by fully-qualified name. Unknown names throw — typed access only.
-  counter(name: string): Counter;
-  histogram(name: string): Histogram;
-  gauge(name: string): Gauge;
-  // List of registered definitions — used by ctx.metrics to validate labels.
-  definitions(): ReadonlyMap<string, MetricDefinition>;
-}
-
-// Public handle for feature code — ctx.metrics.
-// Name resolution uses the fully-qualified name (kumiko_<feature>_<short>).
-// The registrar resolves the short name from the calling feature context
-// at boot time; at handler time the map is ready.
-export interface MetricsHandle {
-  inc(name: string, labels?: MetricLabels, value?: number): void;
-  observe(name: string, value: number, labels?: MetricLabels): void;
-  set(name: string, value: number, labels?: MetricLabels): void;
-}

package/src/observability/provider.ts

@@ -1,32 +0,0 @@
-// Observability provider contract — the "plug" that implementations (noop,
-// console, otlp, prometheus) fulfil. Configuration types that consumers
-// (buildServer, setupTestStack) hand in also live here.
-
-import type { Meter } from "./metric";
-import type { Tracer } from "./span";
-
-export type SamplingConfig = {
-  // Base sampling rate 0..1. Default 1 in v1 (sample everything).
-  readonly tracing?: number;
-  readonly alwaysOnError?: boolean;
-  readonly alwaysOnSlow?: { readonly thresholdMs: number };
-};
-
-export type SensitiveFilterConfig = {
-  readonly redactedHeaders: readonly string[];
-  readonly redactedQueryParams: readonly string[];
-  readonly redactedAttributeKeyPatterns: readonly RegExp[];
-};
-
-export type ObservabilityOptions = {
-  readonly sampling?: SamplingConfig;
-  readonly sensitiveFilter?: Partial<SensitiveFilterConfig>;
-};
-
-export interface ObservabilityProvider {
-  readonly name: string;
-  readonly tracer: Tracer;
-  readonly meter: Meter;
-  // Graceful flush. Called from framework lifecycle shutdown.
-  shutdown(): Promise<void>;
-}

package/src/observability/span.ts

@@ -1,58 +0,0 @@
-// Span + Tracer contract. Provider implementations (noop, recording → console/otlp)
-// all speak this — everything else (middleware, dispatcher, db, redis, jobs)
-// is provider-agnostic.
-
-export type SpanAttributeValue = string | number | boolean;
-export type SpanAttributes = Record<string, SpanAttributeValue>;
-
-export type SpanStatus = "unset" | "ok" | "error";
-
-export type SpanKind = "internal" | "server" | "client" | "producer" | "consumer";
-
-// Serialized form of a trace context — what we pass across process boundaries
-// (outbox row, BullMQ job payload). Matches W3C trace-context spec loosely,
-// but staying minimal — a full W3C parser is v2.
-export type SerializedTraceContext = {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly baggage?: Readonly<Record<string, string>>;
-};
-
-export type StartSpanOptions = {
-  // Either a live Span (normal in-process parent) or a serialized trace
-  // context (cross-process — outbox row, job payload). Both carry traceId
-  // and spanId, so the tracer reads them uniformly. Omitted → fall back to
-  // the AsyncLocalStorage active span.
-  readonly parent?: Span | SerializedTraceContext;
-  readonly attributes?: SpanAttributes;
-  readonly kind?: SpanKind;
-  readonly startTime?: number;
-};
-
-export interface Span {
-  readonly traceId: string;
-  readonly spanId: string;
-  readonly parentSpanId: string | undefined;
-  readonly name: string;
-  setAttribute(key: string, value: SpanAttributeValue): void;
-  setAttributes(attrs: SpanAttributes): void;
-  setStatus(status: SpanStatus, message?: string): void;
-  recordException(error: Error): void;
-  end(endTime?: number): void;
-  // Whether end() has been called. Idempotency guard for auto-wrappers.
-  readonly ended: boolean;
-}
-
-export interface Tracer {
-  startSpan(name: string, options?: StartSpanOptions): Span;
-  // Runs fn inside the span context (AsyncLocalStorage), ends the span
-  // automatically — including on thrown errors, where the error is recorded
-  // and status set to "error" before re-throwing.
-  withSpan<T>(
-    name: string,
-    optionsOrFn: StartSpanOptions | ((span: Span) => Promise<T>),
-    fn?: (span: Span) => Promise<T>,
-  ): Promise<T>;
-  // Current active span from AsyncLocalStorage, or undefined.
-  getActiveSpan(): Span | undefined;
-}

package/src/ownership.ts

@@ -1,83 +0,0 @@
-// --- 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

@@ -1,170 +0,0 @@
-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";
-  // Where the consumer's cursor starts on its FIRST registration. Default
-  // "beginning" replays the full log. "now" seeds the cursor at the current
-  // MAX(events.id) so mounting the MSP into an existing app does not
-  // retroactively fire side effects for historical events. Only affects the
-  // first registration — an existing cursor row is never clobbered.
-  readonly startFrom?: "beginning" | "now";
-};

package/src/rate-limit-types.ts

@@ -1,32 +0,0 @@
-import type { Temporal } from "temporal-polyfill";
-
-export type RateLimitDecision = {
-  readonly allowed: boolean;
-  readonly limit: number;
-  readonly remaining: number;
-  readonly retryAfterSeconds: number;
-  readonly windowSeconds: number;
-  readonly resetAt: Temporal.Instant;
-};
-
-export type RateLimitConfig = {
-  readonly limit: number;
-  readonly windowSeconds: number;
-  readonly cost?: number;
-};
-
-export type RateLimitResolver = {
-  // Atomic check + deduct. Returns the decision and current bucket state
-  // — caller decides whether to throw RateLimitError or proceed.
-  check(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Convenience: throws RateLimitError when blocked. Useful inside the
-  // dispatcher / middleware code-paths where the failure shape is fixed.
-  enforce(bucket: string, config: RateLimitConfig): Promise<RateLimitDecision>;
-
-  // Read-only inspection: returns the same shape as check() but never
-  // mutates the bucket — no token deduction, no refill-timestamp update.
-  // Use for ops/status queries (e.g. "kumiko rl status user:42") that
-  // must observe the bucket without disturbing it.
-  peek(bucket: string, config: Omit<RateLimitConfig, "cost">): Promise<RateLimitDecision>;
-};

package/src/relations.ts

@@ -1,52 +0,0 @@
-// Canonical definition — packages/framework/src/engine/constants.ts imports
-// this type and binds its OnDeleteStrategies runtime object to it via
-// `satisfies`, so a drift between the two fails to compile.
-export type OnDeleteStrategy = "cascade" | "restrict" | "setNull" | "nothing";
-
-// --- Relations ---
-
-export type BelongsToRelation = {
-  readonly type: "belongsTo";
-  readonly target: string;
-  readonly foreignKey: 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 onDelete?: OnDeleteStrategy;
-};
-
-export type RelationDefinition = BelongsToRelation | HasManyRelation | ManyToManyRelation;
-
-export type EntityRelations = Readonly<Record<string, RelationDefinition>>;