@cosmicdrift/kumiko-types 0.159.1 → 0.161.0

package/src/define-handler.ts

@@ -0,0 +1,115 @@
+import type { ZodType, z } from "zod";
+import type { KumikoEventTypeMap } from "./event-type-map";
+import type {
+  AccessRule,
+  HandlerContext,
+  QueryEvent,
+  RateLimitOption,
+  WriteEvent,
+  WriteResult,
+} from "./handlers";
+import type { PipelineDef } from "./step";
+
+// --- Write Handler Definition ---
+//
+// TMap propagates the strict event-type-map through the handler's
+// HandlerContext. CRITICAL: TMap is declared as a generic parameter on the
+// FUNCTION (defineWriteHandler), not just on the type. Generic-functions
+// substitute TMap at the USE-site (the caller's compile context, where
+// the augmentation is visible); generic-type-aliases substitute at the
+// definition-site (framework's compile, where the augmentation isn't
+// visible) and collapse `keyof TMap` to `never`. See the spike-findings
+// memory for the empirical proof.
+//
+// Two authoring forms — `handler` (free-form) or `perform: stepsPipeline(...)`
+// (step-pipeline). A `perform` is compiled to a handler-function at
+// definition time; the dispatcher only ever sees `handler`.
+
+export type WriteHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TData = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly unsafeSkipTransitionGuard?: boolean;
+  readonly rateLimit?: RateLimitOption;
+  readonly handler: (
+    event: WriteEvent<z.infer<TSchema>>,
+    context: HandlerContext<TMap>,
+  ) => Promise<WriteResult<TData>>;
+  // Preserved when the author wrote a `perform` block — the original
+  // PipelineDef. Designer/AI/AST tools read this when present; the
+  // dispatcher ignores it and just calls `handler`. Absent on free-form
+  // handlers.
+  readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
+};
+
+// Author-facing input — accepts either the free-form `handler` or the
+// pipeline-form `perform`. defineWriteHandler narrows them to the
+// canonical WriteHandlerDefinition shape.
+export type WriteHandlerInput<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TData = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly unsafeSkipTransitionGuard?: boolean;
+  readonly rateLimit?: RateLimitOption;
+} & (
+  | {
+      readonly handler: (
+        event: WriteEvent<z.infer<TSchema>>,
+        context: HandlerContext<TMap>,
+      ) => Promise<WriteResult<TData>>;
+      readonly perform?: never;
+    }
+  | {
+      readonly perform: PipelineDef<z.infer<TSchema>, TData>;
+      readonly handler?: never;
+    }
+);
+
+// --- Query Handler Definition ---
+
+export type QueryHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TResult = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
+  readonly handler: (
+    query: QueryEvent<z.infer<TSchema>>,
+    context: HandlerContext<TMap>,
+  ) => Promise<TResult>;
+};
+
+// --- Stream Handler Definition ---
+//
+// Scaffolding only (#1376) — access/rateLimit read by the boot-validator
+// (#1377), dispatch-time consumption (async-generator, SSE) lands in #1378.
+
+export type StreamHandlerDefinition<
+  TName extends string = string,
+  TSchema extends ZodType = ZodType,
+  TChunk = unknown,
+  TMap extends object = KumikoEventTypeMap,
+> = {
+  readonly name: TName;
+  readonly schema: TSchema;
+  readonly access?: AccessRule;
+  readonly rateLimit?: RateLimitOption;
+  readonly handler: (
+    query: QueryEvent<z.infer<TSchema>>,
+    context: HandlerContext<TMap>,
+  ) => AsyncGenerator<TChunk>;
+};

package/src/entity-handlers.ts

@@ -0,0 +1,30 @@
+import type { EntityDefinition } from "./fields";
+import type { AccessRule, QueryHandlerDef, WriteHandlerDef } from "./handlers";
+
+export type EntityHandlerOptions = { readonly access?: AccessRule };
+
+export type EntityQueryHandlerOptions = EntityHandlerOptions & {
+  /** Reads across every tenant instead of the caller's own — for a
+   *  SystemAdmin-only operator inspector over an otherwise tenant-scoped
+   *  entity. Scope this to the ONE handler that needs it rather than making
+   *  the whole feature r.systemScope(), which would drop tenant isolation
+   *  from every other handler the feature registers too. */
+  readonly crossTenant?: boolean;
+};
+
+export type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
+
+export type RegisterEntityCrudOptions = {
+  readonly write?: EntityHandlerOptions;
+  readonly read?: EntityQueryHandlerOptions;
+  readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
+  /** Default true. Set false when the entity was already registered (e.g. before r.relation). */
+  readonly registerEntity?: boolean;
+};
+
+/** Minimal registrar surface — keeps entity-handlers free of define-feature imports. */
+export type EntityCrudRegistrar = {
+  entity(name: string, definition: EntityDefinition): unknown;
+  writeHandler(def: WriteHandlerDef): unknown;
+  queryHandler(def: QueryHandlerDef): unknown;
+};

package/src/entity-table-meta-types.ts

@@ -0,0 +1,92 @@
+// Plain-data types for EntityTableMeta — split from the runtime
+// (buildEntityTableMeta, resolveTableName, defineUnmanagedTable) in
+// entity-table-meta.ts. Prep step for the types-only package extraction
+// (#1283) — this file must have ONLY `import type`, no value imports
+// (crypto/DB deps).
+
+import type { EntityRelations } from "./relations";
+
+// PG type repertoire the read-model tables need. Deliberately narrow — no
+// vendor-specific types (TSVECTOR, HSTORE, etc.). An app-author who needs
+// those reaches into the reviewed SQL migration by hand, not the generator.
+export type PgType =
+  | "uuid"
+  | "text"
+  | "boolean"
+  | "integer"
+  | "double precision"
+  | "bigint"
+  | "serial"
+  | "bigserial"
+  | "jsonb"
+  | "timestamptz"
+  | "timestamptz(3)"
+  // Exact decimal — precision/scale are encoded in the type string so the
+  // DDL renderer and read-coercion need no side-channel metadata.
+  | `numeric(${number},${number})`;
+
+export type ColumnMeta = {
+  readonly name: string; // snake_case PG column name
+  readonly pgType: PgType;
+  readonly notNull: boolean;
+  // Raw SQL-default-expression (e.g. `now()`, `gen_random_uuid()`,
+  // `'[]'::jsonb`). undefined = no DEFAULT clause.
+  readonly defaultSql?: string;
+  readonly primaryKey?: boolean;
+  readonly identity?: boolean;
+  // bigint/bigserial only: JS round-trip mode. `number` = createBigIntField /
+  // drizzle mode:"number" (safe ≤2^53). `bigint` = money cents, raw unmanaged.
+  readonly bigintJsMode?: "number" | "bigint";
+};
+
+export type IndexMeta = {
+  readonly name: string;
+  readonly columns: readonly string[]; // snake_case PG column names
+  readonly unique?: boolean;
+  // Raw SQL-where-expression for partial indexes. Caller is responsible
+  // for safety — emitted verbatim.
+  readonly whereSql?: string;
+  // Set when the EntityDefinition has a partial index (def.where as a
+  // drizzle SQL AST) the generator can't reliably render. The renderer
+  // emits the statement COMMENTED OUT with a warning hint — the app-author
+  // has to add the WHERE manually in the generated SQL.
+  readonly needsManualWhere?: boolean;
+};
+
+export type CompositePrimaryKeyMeta = {
+  readonly name: string;
+  readonly columns: readonly string[];
+};
+
+export type EntityTableMeta = {
+  readonly tableName: string;
+  readonly columns: readonly ColumnMeta[];
+  readonly indexes: readonly IndexMeta[];
+  // For tables with composite PK (no single id column, e.g. snapshots
+  // keyed by aggregate_id+version). When set, no column should have
+  // primaryKey:true; the constraint is emitted at table-level.
+  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+  // Source hint for diagnostics/tests — not used functionally.
+  // "managed" = from EntityDefinition (with base-columns + audit trail).
+  // "unmanaged" = via defineUnmanagedTable — no standard audit, the app
+  // carries the responsibility. Migration-generator + tooling can use the
+  // discriminator to render warnings ("X tables are unmanaged").
+  readonly source: "managed" | "unmanaged";
+  // PII-subject-annotated field names (pii/userOwned/tenantOwned). Set by
+  // buildEntityTableMeta so the registry can reject r.storeTable stores
+  // whose direct writes would skip the executor's encryption (#820).
+  readonly piiSubjectFields?: readonly string[];
+};
+
+export type BuildEntityTableMetaOptions = {
+  readonly featureName?: string;
+  readonly relations?: EntityRelations;
+  readonly source?: "managed" | "unmanaged";
+};
+
+export type UnmanagedTableInput = {
+  readonly tableName: string;
+  readonly columns: readonly ColumnMeta[];
+  readonly indexes?: readonly IndexMeta[];
+  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
+};

package/src/envelope-cipher-types.ts

@@ -0,0 +1,6 @@
+import type { KeyScope } from "./secrets-types";
+
+export type EnvelopeCipher = {
+  encrypt(plaintext: string, scope?: KeyScope): Promise<string>;
+  decrypt(stored: string, scope?: KeyScope): Promise<string>;
+};

package/src/event-store-errors.ts

@@ -0,0 +1,35 @@
+// 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;
+  }
+}

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

@@ -0,0 +1,93 @@
+import type { CursorResult } from "./cursor-types";
+import type { SessionUser, WriteResult } from "./handlers";
+import type { DeleteContext, SaveContext } from "./hooks";
+import type { EntityId } from "./identifiers";
+import type { SearchAdapter } from "./search-adapter";
+import type { TenantDb } from "./tenant-db-types";
+
+export type EventStoreExecutor = {
+  create: (
+    payload: Record<string, unknown>,
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<WriteResult<SaveContext>>;
+
+  update: (
+    payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown> },
+    user: SessionUser,
+    db: TenantDb,
+    options?: { skipOptimisticLock?: boolean; skipUnchanged?: boolean },
+  ) => Promise<WriteResult<SaveContext>>;
+
+  delete: (
+    payload: { id: EntityId },
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<WriteResult<DeleteContext>>;
+
+  // Hard-purge (Art. 17 erasure). Like delete, but emits `<entity>.forgotten`
+  // which hard-deletes the row even for softDelete entities — and, being an
+  // auto-verb replayed by the implicit projection, the erasure survives a
+  // rebuild (created → forgotten → row gone). Reaches soft-deleted rows too.
+  forget: (
+    payload: { id: EntityId },
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<WriteResult<DeleteContext>>;
+
+  restore: (
+    payload: { id: EntityId },
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<WriteResult<SaveContext>>;
+
+  list: (
+    payload: {
+      cursor?: string | undefined;
+      limit?: number | undefined;
+      search?: string | undefined;
+      sort?: string | undefined;
+      sortDirection?: "asc" | "desc" | undefined;
+      offset?: number | undefined;
+      totalCount?: boolean | undefined;
+      filter?:
+        | {
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+            readonly value: unknown;
+          }
+        | undefined;
+      // User-chosen faceted filters (dynamic, additive to the static
+      // `filter`). All combined with AND.
+      filters?:
+        | ReadonlyArray<{
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+            readonly value: unknown;
+          }>
+        | undefined;
+    },
+    user: SessionUser,
+    db: TenantDb,
+    /** Tier 2.7e audit fix: per-call SearchAdapter override. When the
+     *  executor didn't get a SearchAdapter via Options at build time
+     *  (defaultEntityQueryHandler path), the caller (handler) can pass
+     *  one from ctx.searchAdapter here at runtime.
+     *  options.searchAdapter (build-time) wins — the runtime override
+     *  is the fallback for the default wrapper. */
+    runtimeOptions?: {
+      readonly searchAdapter?: SearchAdapter;
+      // Trash query: skip the implicit `isDeleted = FALSE` filter so soft-
+      // deleted rows are returned too. Tenant + ownership clauses still apply
+      // — includeDeleted only relaxes the soft-delete predicate, never the
+      // visibility ones, so it can ride untrusted query input safely.
+      readonly includeDeleted?: boolean;
+    },
+  ) => Promise<CursorResult<Record<string, unknown>>>;
+
+  detail: (
+    payload: { id: EntityId },
+    user: SessionUser,
+    db: TenantDb,
+  ) => Promise<Record<string, unknown> | null>;
+};

package/src/event-store-types.ts

@@ -0,0 +1,41 @@
+import type { TenantId } from "./identifiers";
+
+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>>;
+};
+
+// 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

@@ -0,0 +1,19 @@
+// 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;
+};