@cosmicdrift/kumiko-types 0.326.1 → 0.328.0

package/src/event-store-types.ts

@@ -1,85 +0,0 @@
-import type { TenantId } from "./identifiers";
-
-// Structural shape of kumiko-framework's VersionConflictError. The class
-// itself cannot live here (#1629) — this package must stay free of
-// identity-sensitive runtime values so it can be a plain dependency.
-export interface VersionConflict extends Error {
-  readonly aggregateId: string;
-  readonly expectedVersion: number;
-}
-
-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;
-  // Opt-in second line of defense against duplicate appends when the
-  // Redis-backed HTTP idempotency guard (pipeline/idempotency.ts) misses a
-  // retry window (Redis unreachable, TTL race). Callers that want a hard
-  // per-event uniqueness guarantee set a stable key derived from the
-  // triggering request; the event-store enforces it via a tenant-scoped
-  // partial unique index and throws IdempotentAppendConflictError on a
-  // repeat. Unset by default — no uniqueness constraint applies.
-  readonly idempotencyKey?: 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>>;
-  // Feature that owned the execution scope which wrote this event, and the
-  // qualified name of the handler/consumer/job inside it. Derived in
-  // event-store.append() from the ambient request scope, never passed in by
-  // the writer — attribution handed over can lie, attribution derived cannot.
-  // Optional so rows written before #3043 stay readable without a backfill;
-  // every new row carries both, falling back to UNATTRIBUTED_ORIGIN.
-  readonly feature?: string;
-  readonly handler?: string;
-  // Only set under an anonymous root without public-intake, so event-triggered
-  // jobs keep the personal-data gate.
-  readonly writeOrigin?: WriteOrigin;
-};
-
-export type WriteOrigin = {
-  readonly rootHandler: string;
-  readonly anonymousRoot: boolean;
-  // Only a write-handler root can declare public-intake; a query/stream root never does.
-  readonly publicIntake: boolean;
-  readonly viaJob?: string;
-};
-
-export function isPersonalDataGated(origin: WriteOrigin): boolean {
-  return origin.anonymousRoot && !origin.publicIntake;
-}
-
-// Stamped when an append runs outside any attributed scope (seed scripts,
-// tests, direct event-store use). A distinct value, not an omission —
-// omitted would be indistinguishable from a pre-#3043 row.
-export const UNATTRIBUTED_ORIGIN = "unknown";
-
-// Generic over the payload shape. Default = Record<string, unknown> keeps
-// all existing consumers backwards-compatible; annotate `StoredEvent<MyEventPayload>`
-// where a typed payload read is needed.
-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;
-};

package/src/executor-brand.ts

@@ -1,19 +0,0 @@
-// A managed projection is only writable through the executor (event →
-// rebuild-safe). To make a direct write a *compile* error rather than a
-// convention, EntityTable carries a phantom `unique symbol` prop; the public
-// write helpers reject anything that has it (see NotExecutorOnly + query.ts).
-// The symbol key dodges SchemaTable's `[field: string]: unknown` index
-// signature (string index sigs don't cover symbol keys), so the brand
-// survives the type-erasure that would swallow a plain marker prop — and the
-// executor seam (applyEntityEvent) erases `table` to TableColumns<any>, which
-// carries no such prop, so the one legitimate writer stays green.
-declare const EXECUTOR_ONLY: unique symbol;
-export interface ExecutorOnly {
-  readonly [EXECUTOR_ONLY]: true;
-}
-// Negative brand for write-helper params: a branded EntityTable is NOT
-// assignable (its `true` clashes with `never`), while unmanaged EntityTableMeta
-// and erased SchemaTable pass (they lack the prop, so `?: never` is satisfied).
-export type NotExecutorOnly = {
-  readonly [EXECUTOR_ONLY]?: never;
-};

package/src/extension-options-map.ts

@@ -1,21 +0,0 @@
-// Cross-Feature Compile-Time-Type-Map for `r.useExtension(name, entity, options)`.
-// Augmented per extension point via `declare module "@cosmicdrift/kumiko-framework/engine"`,
-// mirroring event-type-map.ts; names without augmentation stay untyped.
-
-import type { EscapeHatchDeclaration } from "./handlers";
-
-// MUST be `interface` (not `type`): only interfaces support TS declaration-
-// merging. See event-type-map.ts for the same constraint.
-
-// biome-ignore lint/suspicious/noEmptyInterface: declaration-merging marker — augmented per extension point
-export interface KumikoExtensionOptionsMap {}
-
-/** Options shape for an extension name: the augmented hook shape plus `escapeHatch`, or an untyped bag if unaugmented. */
-export type ExtensionOptionsFor<N extends string> = N extends keyof KumikoExtensionOptionsMap
-  ? KumikoExtensionOptionsMap[N] & { readonly escapeHatch?: EscapeHatchDeclaration }
-  : Record<string, unknown>;
-
-/** Rest-tuple for useExtension's positional options arg: required for an augmented name, optional otherwise. */
-export type ExtensionOptionsArgs<N extends string> = N extends keyof KumikoExtensionOptionsMap
-  ? [options: ExtensionOptionsFor<N>]
-  : [options?: Record<string, unknown>];