@cosmicdrift/kumiko-framework 0.159.1 → 0.160.0

package/src/bun-db/query.ts

@@ -19,6 +19,11 @@
 //     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
 //     reference, NICHT als runtime-API-call)
 
+import type {
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index";
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { type NotExecutorOnly, toSnakeCase } from "../db/table-builder";
@@ -183,19 +188,13 @@ function assertNotTenantScoped(db: unknown, fnName: string): void {
 
 export type AnyDb = BunDbRunner | unknown;
 
-// WhereValue: primitive für eq, array für IN, null für IS NULL, oder
-// operator-object für range/comparisons.
-export type WhereOperator = {
-  readonly gt?: unknown;
-  readonly gte?: unknown;
-  readonly lt?: unknown;
-  readonly lte?: unknown;
-  readonly ne?: unknown;
-  readonly in?: readonly unknown[];
-  readonly like?: string;
-};
-export type WhereValue = unknown | WhereOperator;
-export type WhereObject = Record<string, WhereValue>;
+export type {
+  OrderByClause,
+  SelectOptions,
+  WhereObject,
+  WhereOperator,
+  WhereValue,
+} from "@cosmicdrift/kumiko-types/where-clause-types";
 
 function isWhereOperator(v: unknown): v is WhereOperator {
   if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
@@ -206,18 +205,6 @@ function isWhereOperator(v: unknown): v is WhereOperator {
   const opKeys = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
   return keys.every((k) => opKeys.includes(k));
 }
-export type OrderByClause = {
-  readonly col: string;
-  readonly direction?: "asc" | "desc";
-};
-
-export type SelectOptions = {
-  readonly limit?: number;
-  // Single column or array for multi-column tie-breaks (e.g.
-  // [{col: "createdAt"}, {col: "id"}] for chronological-with-stable-id).
-  readonly orderBy?: OrderByClause | readonly OrderByClause[];
-};
-
 // Akzeptiert EITHER. Beide haben einen tableName und field→column-mapping.
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface
 type TableLike = EntityTableMeta | any;

package/src/crypto/kms-adapter.ts

@@ -1,118 +1,2 @@
-import type { TenantId } from "../engine/types/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";
-  }
-}
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/kms-adapter-types";

package/src/db/__tests__/build-filter-where.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { buildFilterWhere } from "../event-store-executor-context";
+
+describe("buildFilterWhere", () => {
+  test("eq: returns a direct field-equality WhereObject", () => {
+    expect(buildFilterWhere("status", "eq", "active")).toEqual({ status: "active" });
+  });
+
+  test("ne: wraps the value in a { ne } clause", () => {
+    expect(buildFilterWhere("status", "ne", "active")).toEqual({ status: { ne: "active" } });
+  });
+
+  test("lt: wraps the value in a { lt } clause", () => {
+    expect(buildFilterWhere("createdAt", "lt", 100)).toEqual({ createdAt: { lt: 100 } });
+  });
+
+  test("gt: wraps the value in a { gt } clause", () => {
+    expect(buildFilterWhere("createdAt", "gt", 100)).toEqual({ createdAt: { gt: 100 } });
+  });
+
+  test("in: non-empty array → direct array WhereObject", () => {
+    expect(buildFilterWhere("status", "in", ["active", "pending"])).toEqual({
+      status: ["active", "pending"],
+    });
+  });
+
+  test("in: empty array → null (no-match short-circuit)", () => {
+    expect(buildFilterWhere("status", "in", [])).toBeNull();
+  });
+
+  test("in: non-array value → null (no-match short-circuit)", () => {
+    expect(buildFilterWhere("status", "in", "not-an-array")).toBeNull();
+  });
+});

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -9,6 +9,7 @@ import { asRawClient } from "../../db/query";
 import { createEntity, createTextField } from "../../engine";
 import { from } from "../../engine/ownership";
 import { createEventsTable } from "../../event-store";
+import type { EntityCache } from "../../pipeline/entity-cache";
 import { createTestDb, type TestDb, TestUsers, unsafeCreateEntityTable } from "../../stack";
 import { createEventStoreExecutor } from "../event-store-executor";
 import { buildEntityTable } from "../table-builder";
@@ -303,3 +304,93 @@ async function unsafeCreateEntityTableFor(
 ): Promise<void> {
   await unsafeCreateEntityTable(testDb.db, entity, name);
 }
+
+// =============================================================================
+// Concurrent update race → EventStoreVersionConflict catch + entityCache.del
+// on forget/restore (create/update/delete already exercise cache in the
+// main suite; forget/restore del() stayed uncovered).
+// =============================================================================
+
+const raceEntity = createEntity({
+  table: "read_es_write_race",
+  fields: {
+    email: createTextField({ required: true }),
+  },
+  softDelete: true,
+});
+const raceTable = buildEntityTable("esWriteRace", raceEntity);
+
+describe("event-store-executor write-verbs — concurrent version race + cache", () => {
+  const store = new Map<string, Record<string, unknown>>();
+  const entityCache: EntityCache = {
+    get: async (tenantId, name, id) => store.get(`${tenantId}:${name}:${id}`) ?? null,
+    mget: async () => new Map(),
+    set: async (tenantId, name, id, data) => {
+      store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    mset: async (tenantId, name, entries) => {
+      for (const { id, data } of entries) store.set(`${tenantId}:${name}:${id}`, data);
+    },
+    del: async (tenantId, name, id) => {
+      store.delete(`${tenantId}:${name}:${id}`);
+    },
+  };
+  const crud = createEventStoreExecutor(raceTable, raceEntity, {
+    entityName: "esWriteRace",
+    entityCache,
+  });
+
+  beforeAll(async () => {
+    await unsafeCreateEntityTableFor(raceEntity, "esWriteRace");
+  });
+
+  beforeEach(async () => {
+    store.clear();
+    await asRawClient(testDb.db).unsafe(
+      `TRUNCATE kumiko_events, read_es_write_race RESTART IDENTITY CASCADE`,
+    );
+  });
+
+  test("two concurrent updates with the same version → one wins, one version_conflict", async () => {
+    const created = await crud.create({ email: "race@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    const id = created.data.id;
+
+    const [a, b] = await Promise.all([
+      crud.update({ id, version: 1, changes: { email: "a@test.de" } }, admin, tdb),
+      crud.update({ id, version: 1, changes: { email: "b@test.de" } }, admin, tdb),
+    ]);
+
+    const results = [a, b];
+    expect(results.filter((r) => r.isSuccess)).toHaveLength(1);
+    expect(results.filter((r) => !r.isSuccess && r.error.code === "version_conflict")).toHaveLength(
+      1,
+    );
+  });
+
+  test("forget with entityCache clears the cache entry", async () => {
+    const created = await crud.create({ email: "cache-forget@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    const id = created.data.id;
+    const key = `${admin.tenantId}:esWriteRace:${id}`;
+    store.set(key, { email: "poison" });
+
+    const result = await crud.forget({ id }, admin, tdb);
+    expect(result.isSuccess).toBe(true);
+    expect(store.has(key)).toBe(false);
+  });
+
+  test("restore with entityCache clears the cache entry", async () => {
+    const created = await crud.create({ email: "cache-restore@test.de" }, admin, tdb);
+    if (!created.isSuccess) throw new Error("setup failed");
+    const id = created.data.id;
+    await crud.delete({ id }, admin, tdb);
+
+    const key = `${admin.tenantId}:esWriteRace:${id}`;
+    store.set(key, { email: "poison" });
+
+    const result = await crud.restore({ id }, admin, tdb);
+    expect(result.isSuccess).toBe(true);
+    expect(store.has(key)).toBe(false);
+  });
+});

package/src/db/cursor.ts

@@ -1,21 +1,4 @@
-import type { EntityId, TenantId } from "../engine/types/identifiers";
-
-export type CursorQueryOptions = {
-  tenantId: TenantId;
-  cursor?: string;
-  limit?: number;
-  filterIds?: readonly EntityId[];
-  sort?: string;
-  sortDirection?: "asc" | "desc";
-};
-
-export type CursorResult<T> = {
-  rows: T[];
-  nextCursor: string | null;
-  /** Optional total row count — nur present wenn der Caller `totalCount: true`
-   *  in der Query setzt. */
-  total?: number;
-};
+export type { CursorQueryOptions, CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
 
 // String-basiert damit UUIDs (Default seit Sprint F) + Integer-Auto-Increment
 // durch denselben Cursor-Pfad laufen. UUIDv7 erfüllt die lex-Monotonie

package/src/db/dialect.ts

@@ -13,6 +13,12 @@
 // The framework no longer imports drizzle-orm at runtime — schema-files
 // use only this module.
 
+import {
+  type ColumnHandle,
+  KUMIKO_COLUMNS_SYMBOL,
+  KUMIKO_NAME_SYMBOL,
+  type SchemaTable,
+} from "@cosmicdrift/kumiko-types/schema-table-types";
 import type {
   ColumnMeta,
   CompositePrimaryKeyMeta,
@@ -21,6 +27,8 @@ import type {
   PgType,
 } from "./entity-table-meta";
 
+export type { ColumnHandle, SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+
 // Public type aliases — historical compat for callers that used to import
 // these from drizzle-orm/pg-core. SelectQuery is no longer a meaningful
 // shape (no chain builder); TableColumns is the new SchemaTable union.
@@ -29,31 +37,12 @@ export type TableColumns<_T = any> = SchemaTable;
 // biome-ignore lint/suspicious/noExplicitAny: legacy type — chain API is gone
 export type SelectQuery = any;
 
-// Column handle exposed on the SchemaTable. The `name` is the SQL column
-// name (snake_case); legacy code accesses `table.fieldName.name` to
-// produce raw SQL.
-export type ColumnHandle = {
-  readonly name: string;
-  readonly pgType: PgType;
-  readonly getSQLType: () => string;
-};
-
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
 // Shadow-proof handle on the EntityTableMeta. The column handles below are
 // spread as enumerable props, so an entity field named `source`/`columns`/
 // `tableName`/… would overwrite the matching meta key. extractTableInfo reads
 // the canonical meta from this symbol instead of the (shadowable) props.
 const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
-// SchemaTable — opaque shape with both EntityTableMeta + Symbol-based
-// introspection. Returned by `table(...)`.
-export type SchemaTable = EntityTableMeta & {
-  readonly [KUMIKO_NAME_SYMBOL]: string;
-  readonly [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
-  readonly [field: string]: unknown;
-};
-
 function isNumericPgType(t: PgType): t is `numeric(${number},${number})` {
   return t.startsWith("numeric(");
 }

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

@@ -1,92 +1,2 @@
-// 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 "../engine/types";
-
-// 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;
-};
+// Legacy path — re-exported for callers still importing this module directly.
+export * from "@cosmicdrift/kumiko-types/entity-table-meta-types";

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

@@ -1,19 +1,14 @@
+import type { EventStoreExecutor } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 import type { LocalKeyKmsAdapter } from "../crypto";
-import type {
-  DeleteContext,
-  EntityDefinition,
-  EntityId,
-  SaveContext,
-  SessionUser,
-  WriteResult,
-} from "../engine/types";
+import type { EntityDefinition } from "../engine/types";
 import type { EntityCache } from "../pipeline/entity-cache";
 import type { SearchAdapter } from "../search/types";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher";
 import { buildExecutorContext, type Table } from "./event-store-executor-context";
 import { createReadVerbs } from "./event-store-executor-read";
 import { createWriteVerbs } from "./event-store-executor-write";
-import type { CursorResult } from "./index";
+
+export type { EventStoreExecutor } from "@cosmicdrift/kumiko-types/event-store-executor-types";
 
 // The executor writes events + auto-projection (entity table) in one TX.
 // It no longer knows about user projections — those are driven by the
@@ -42,93 +37,6 @@ export type EventStoreExecutorOptions = {
   kms?: LocalKeyKmsAdapter;
 };
 
-export type EventStoreExecutor = {
-  create: (
-    payload: Record<string, unknown>,
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<SaveContext>>;
-
-  update: (
-    payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown> },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-    options?: { skipOptimisticLock?: boolean; skipUnchanged?: boolean },
-  ) => Promise<WriteResult<SaveContext>>;
-
-  delete: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-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: import("./tenant-db").TenantDb,
-  ) => Promise<WriteResult<DeleteContext>>;
-
-  restore: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: import("./tenant-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-gewählte Faceted-Filter (dynamisch, additiv zum statischen
-      // `filter`). Alle werden mit AND verknüpft.
-      filters?:
-        | ReadonlyArray<{
-            readonly field: string;
-            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
-            readonly value: unknown;
-          }>
-        | undefined;
-    },
-    user: SessionUser,
-    db: import("./tenant-db").TenantDb,
-    /** Tier 2.7e Audit-Fix: per-Call SearchAdapter Override. Wenn der
-     *  Executor beim Build keinen SearchAdapter via Options bekommen
-     *  hat (defaultEntityQueryHandler-Pfad), kann der Caller (Handler)
-     *  hier zur Runtime einen aus ctx.searchAdapter durchreichen.
-     *  options.searchAdapter (build-time) gewinnt — runtime-Override
-     *  ist Fallback für die 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: import("./tenant-db").TenantDb,
-  ) => Promise<Record<string, unknown> | null>;
-};
-
 export function createEventStoreExecutor(
   table: Table,
   entity: EntityDefinition,

package/src/db/table-builder.ts

@@ -1,3 +1,4 @@
+import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type {
   EntityDefinition,
   EntityRelations,
@@ -382,25 +383,7 @@ type SoftDeleteColumnsType = {
 };
 
 // ── ES-write brand ──────────────────────────────────────────────────────
-// 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;
-};
+export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 
 export type EntityTable<E extends EntityDefinition = EntityDefinition> =
   TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.