@cosmicdrift/kumiko-types 0.327.0 → 0.328.0

package/src/define-handler.ts

@@ -1,138 +0,0 @@
-import type * as z from "zod";
-import type { ZodType } from "zod";
-import type { KumikoEventTypeMap } from "./event-type-map";
-import type {
-  AccessRule,
-  AgentHandlerHints,
-  EscapeHatchDeclaration,
-  HandlerContext,
-  QueryEvent,
-  RateLimitDeclaration,
-  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 description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitDeclaration;
-  readonly escapeHatch?: EscapeHatchDeclaration;
-  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 description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitDeclaration;
-  readonly escapeHatch?: EscapeHatchDeclaration;
-} & (
-  | {
-      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 description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitDeclaration;
-  readonly escapeHatch?: EscapeHatchDeclaration;
-  readonly handler: (
-    query: QueryEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => Promise<TResult>;
-  /** Zod schema of `handler`'s actual return value — see QueryHandlerDef's
-   *  doc (handlers.ts) for the boot-validator checks this unlocks. Not
-   *  inferred from `TResult`: TResult is a compile-time-only type param
-   *  (this function never receives a runtime schema for it), so callers
-   *  that want boot-time column checks declare `outputSchema` explicitly,
-   *  same as `schema` for the input side. */
-  readonly outputSchema?: ZodType;
-};
-
-// --- 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?: RateLimitDeclaration;
-  // Stream handlers can't reach db.global() (that gate is write-only), but
-  // they can still switch identity to SYSTEM via ctx.queryAs — this opts
-  // in, same contract as WriteHandlerDefinition.escapeHatch.
-  readonly escapeHatch?: EscapeHatchDeclaration;
-  readonly handler: (
-    query: QueryEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => AsyncGenerator<TChunk>;
-};

package/src/derivatives-types.ts

@@ -1,106 +0,0 @@
-// Derived-file-variants (thumbnails, resized/reformatted images, …) — pure
-// types, no runtime logic. Client-visible package: no `node:*` imports.
-
-export type VariantFit = "cover" | "inside" | "contain";
-export type VariantFormat = "webp" | "avif" | "jpeg";
-
-// Rectangle in relative coordinates (0…1 of width/height) so it survives a
-// resize. Burning blur into plates/faces needs coordinates that only exist at
-// runtime (detection + user correction), so they ride in the spec instead of a
-// field declaration — the spec hash keys the cache, so corrected regions
-// automatically yield a fresh URL.
-export type BlurRegion = {
-  readonly x: number;
-  readonly y: number;
-  readonly width: number;
-  readonly height: number;
-};
-
-export type OverlayGravity = "north-west" | "north-east" | "south-west" | "south-east" | "center";
-
-// Placement is relative to the OUTPUT box (after resize), so one declaration
-// covers every aspect ratio the same source is rendered into.
-type OverlayPlacement = {
-  // Layer width as a fraction (0…1) of the output width; height follows the
-  // layer's own aspect ratio.
-  readonly widthPct: number;
-  readonly gravity: OverlayGravity;
-  // Inset from the edges, fraction of output width. Ignored for "center".
-  readonly marginPct?: number;
-};
-
-export type OverlayLayer =
-  // `dataToken` is NOT the QR payload — it names a value an
-  // EXT_DERIVATIVE_OVERLAY_RESOLVER registration resolves per FileRef. A
-  // literal payload is deliberately not expressible: the public variant route
-  // is anonymous, so a caller-supplied target would make it an open image
-  // generator for arbitrary URLs.
-  | ({ readonly kind: "qr"; readonly dataToken: string } & OverlayPlacement)
-  // Caller-supplied raster (watermark/badge), base64 in the declaration.
-  // Swapping the image changes the spec hash and invalidates every derivative
-  // that used it — no extra bookkeeping.
-  | ({ readonly kind: "image"; readonly imageBase64: string } & OverlayPlacement);
-
-// Renderer-facing counterpart of OverlayLayer once derivatives-context has
-// resolved every `dataToken` — a `qr` layer carries the actual value to
-// encode instead of a name a resolver still has to look up. Keeping this a
-// distinct type (not a value-replacement on OverlayLayer itself) means a
-// renderer's input type structurally cannot hold an unresolved token.
-export type ResolvedOverlayLayer =
-  | ({ readonly kind: "qr"; readonly data: string } & OverlayPlacement)
-  | Extract<OverlayLayer, { kind: "image" }>;
-
-export type VariantSpec = {
-  // Default "inside" when omitted (renderer-side default, Schnitt 2).
-  readonly fit?: VariantFit;
-  readonly size?: { readonly width: number; readonly height: number };
-  // Alternative to `size` — longest edge in pixels, aspect preserved.
-  readonly maxEdge?: number;
-  readonly format?: VariantFormat;
-  readonly quality?: number;
-  // Whole-image blur radius.
-  readonly blur?: number;
-  readonly blurRegions?: readonly BlurRegion[];
-  // Composited AFTER resize, in array order (last layer on top).
-  readonly overlays?: readonly OverlayLayer[];
-  // Framework-internal: derivatives-context.ts fills this in from `overlays`
-  // once every dataToken is resolved. A renderer reads only this field, so a
-  // token can never reach it, even by accident.
-  readonly resolvedOverlays?: readonly ResolvedOverlayLayer[];
-};
-
-// A renderer turns the original bytes + a spec into the derived bytes for one
-// variant. Registered per MIME-type (exact or `<type>/*` wildcard) via the
-// `derivativeRenderer` extension point — see EXT_DERIVATIVE_RENDERER.
-//
-// The renderer must produce `spec.format` when set, and the source's own
-// format otherwise. It never reports back what it produced: the caller
-// derives the output mimeType from the spec plus the source FileRef's
-// mimeType (see outputMimeType in derivatives-context.ts), because a cache
-// hit has no renderer run to read a mimeType off. When `spec.format` is
-// unset, the source mimeType is client-controlled, so outputMimeType
-// allowlists it against known-safe raster types instead of passing it
-// through verbatim (#2021).
-export type DerivativeRendererPlugin = {
-  readonly render: (
-    input: Uint8Array,
-    spec: VariantSpec,
-    sourceMimeType: string,
-  ) => Promise<Uint8Array>;
-};
-
-export type VariantResult = {
-  readonly storageKey: string;
-  readonly mimeType: string;
-  // true = rendered during this call, false = an existing derivative was
-  // found and returned unchanged.
-  readonly rendered: boolean;
-};
-
-// The `ctx.derivatives` service — derive-on-first-use variants of a tracked
-// FileRef. `name` feeds only the readable key-prefix; `spec` determines the
-// content hash, so a spec change always produces a fresh URL instead of
-// silently overwriting what's cached under the old pixels.
-export type DerivativesContext = {
-  readonly variant: (fileRefId: string, spec: VariantSpec, name: string) => Promise<VariantResult>;
-};

package/src/entity-cache.ts

@@ -1,35 +0,0 @@
-import type { EntityId, TenantId } from "./identifiers";
-
-export type EntityCache = {
-  /** Get a single cached entity. Returns null on miss. */
-  get(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-  ): Promise<Record<string, unknown> | null>;
-
-  /** Get multiple cached entities. Returns a Map of id → data (misses are absent). */
-  mget(
-    tenantId: TenantId,
-    entityName: string,
-    ids: readonly EntityId[],
-  ): Promise<Map<EntityId, Record<string, unknown>>>;
-
-  /** Cache a single entity. */
-  set(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-    data: Record<string, unknown>,
-  ): Promise<void>;
-
-  /** Cache multiple entities at once. */
-  mset(
-    tenantId: TenantId,
-    entityName: string,
-    entries: ReadonlyArray<{ id: EntityId; data: Record<string, unknown> }>,
-  ): Promise<void>;
-
-  /** Invalidate a single cached entity. */
-  del(tenantId: TenantId, entityName: string, id: EntityId): Promise<void>;
-};

package/src/entity-handlers.ts

@@ -1,68 +0,0 @@
-import type { EntityDefinition } from "./fields";
-import type {
-  AccessRule,
-  AgentHandlerHints,
-  EscapeHatchDeclaration,
-  QueryHandlerDef,
-  WriteHandlerDef,
-} from "./handlers";
-
-export type EntityHandlerOptions = {
-  readonly access: AccessRule;
-  readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  /** Lifts row filtering for this ONE handler across every tenant instead of
-   *  the caller's own — for a SystemAdmin-only operator handler over an
-   *  otherwise tenant-scoped entity. Every use reports an
-   *  `acknowledge-cross-tenant` escape-hatch audit event. On write handlers
-   *  update/delete/restore address the target row's own tenant stream.
-   *  `access` stays the only caller gate. Unlike `escapeHatch` on a
-   *  hand-written handler this does NOT grant `ctx.db.unsafeRaw`,
-   *  `db.global()` writes or identity switches. */
-  readonly escapeHatch?: EscapeHatchDeclaration;
-  /** @deprecated Use `escapeHatch: { reason }` — removed in a future release;
-   *  run `scripts/codemod/migrate-cross-tenant.ts`. */
-  readonly crossTenant?: boolean;
-};
-
-/** Options for the generic create/update handlers. */
-export type EntityWriteHandlerOptions = EntityHandlerOptions & {
-  /** Fields this handler never writes. They leave the payload schema as
-   *  "must be absent": a payload that still carries one fails validation
-   *  instead of being stripped silently. create rejects a required field
-   *  without default here, since the row could never be created. */
-  readonly excludeFields?: readonly string[];
-};
-
-export type EntityQueryHandlerOptions = EntityHandlerOptions;
-
-export type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
-
-// `access` stays optional here — registerEntityCrud resolves it per-verb from `verbAccess`, falling back to this default.
-export type EntityCrudHandlerDefaults = Omit<EntityHandlerOptions, "access"> & {
-  readonly access?: AccessRule;
-};
-
-export type RegisterEntityCrudOptions = {
-  readonly write?: EntityCrudHandlerDefaults;
-  readonly read?: EntityCrudHandlerDefaults;
-  readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
-  /** Per-verb access override — falls back to `write.access`/`read.access` when unset for a verb. */
-  readonly verbAccess?: Partial<Record<EntityCrudVerb, AccessRule>>;
-  /** Per-verb `description` — the author writes one sentence per verb; the AI-agent
-   *  manifest exposes only the verbs described here (fail-closed, same rule as
-   *  hand-written handlers). Falls back to `write.description`/`read.description`. */
-  readonly descriptions?: Partial<Record<EntityCrudVerb, string>>;
-  /** Per-verb `excludeFields` for the generic create/update handlers — see
-   *  EntityWriteHandlerOptions. */
-  readonly excludeFields?: Partial<Record<"create" | "update", readonly string[]>>;
-  /** 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

@@ -1,101 +0,0 @@
-// Plain-data types for EntityTableMeta — split from the runtime
-// (deriveEntityTableMeta, 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";
-import type { EntityTenancy } from "./tenancy-brand";
-
-// 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)"
-  // Calendar day, no time-of-day/timezone component — Temporal.PlainDate.
-  // Distinct from timestamptz: a `date` field is a pure calendar concept
-  // (invoice date, lease term) and must never round-trip through an Instant.
-  | "date"
-  // 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
-  // deriveEntityTableMeta so the registry can reject r.storeTable stores
-  // whose direct writes would skip the executor's encryption (#820).
-  readonly piiSubjectFields?: readonly string[];
-  // Only present for "global" tables — absent means "tenant" so existing
-  // schema snapshots don't drift. See EntityDefinition.tenancy.
-  readonly tenancy?: "global";
-};
-
-export type BuildEntityTableMetaOptions = {
-  readonly featureName?: string;
-  readonly relations?: EntityRelations;
-  readonly source?: EntityTableMeta["source"];
-};
-
-export type UnmanagedTableInput = {
-  readonly tableName: string;
-  readonly columns: readonly ColumnMeta[];
-  readonly indexes?: readonly IndexMeta[];
-  readonly compositePrimaryKey?: CompositePrimaryKeyMeta;
-  readonly tenancy?: EntityTenancy;
-};

package/src/envelope-cipher-types.ts

@@ -1,6 +0,0 @@
-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-executor-types.ts

@@ -1,163 +0,0 @@
-import type { CursorResult } from "./cursor-types";
-import type { EntityDefinition } from "./fields";
-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";
-
-// Read-time gate for join-row entities (EntityDefinition.parentRef): the
-// registered-entity map the SQL clause checks host candidates against.
-// Lives here (not in db/parent-ref-clause.ts) because the Registry only
-// exists at request time — the same extension-point shape as
-// referenceSearch/referenceSort below (fw#2660/fw#2741).
-export type ParentVisibilityOption = {
-  readonly entities: ReadonlyMap<string, EntityDefinition>;
-};
-
-// Runs the caller's preSave hooks against changes not yet persisted, for
-// the executor's create()/update() only — restore/delete/forget have no
-// `changes` to shape. See HandlerContext.runPreSave for how this gets bound
-// to a specific handler name + AppContext.
-export type PreSaveRunner = (
-  changes: Record<string, unknown>,
-  previous: Readonly<Record<string, unknown>>,
-  isNew: boolean,
-) => Promise<Record<string, unknown>>;
-
-export type EventStoreExecutor = {
-  create: (
-    payload: Record<string, unknown>,
-    user: SessionUser,
-    db: TenantDb,
-    options?: { preSave?: PreSaveRunner },
-  ) => Promise<WriteResult<SaveContext>>;
-
-  update: (
-    payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown> },
-    user: SessionUser,
-    db: TenantDb,
-    options?: {
-      skipOptimisticLock?: boolean;
-      skipUnchanged?: boolean;
-      preSave?: PreSaveRunner;
-      // Declarative precondition for a "genau einmal"-transition (kumiko-
-      // framework#3024): field/value pairs the row must still hold at write
-      // time — a `null` expected value matches a null field. Re-read fresh,
-      // atomically with the write's stream version (not the payload's stale
-      // `previous`), so a concurrent writer that already moved the row on is
-      // caught even when it doesn't collide with the stream-version check.
-      // Mismatch fails the whole update with PreconditionFailedError instead
-      // of applying it.
-      // Scalars only (string/number/boolean/null) — the check is `!==`, so an
-      // object/Date/Instant value would compare by reference and silently
-      // never match; a timestamp precondition needs its own scalar mirror
-      // field to check against, not the compound value itself. Also plain
-      // columns only: the check reads raw column values (no decrypt pass),
-      // so a pii/encrypted field can't be used here.
-      expect?: Readonly<Record<string, string | number | boolean | null>>;
-    },
-  ) => 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" | "lte" | "gte" | "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" | "lte" | "gte" | "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;
-      // fw#2660 — a text search also matches `searchable: true` reference
-      // fields (and the implicit tenantId→tenant.name row-meta reference) by
-      // their target row's labelField, not just the raw FK column. Only
-      // available at request time (registry access), so it rides the same
-      // runtime-override extension point as searchAdapter. `fields` and
-      // `resolveEntity` travel together — one without the other silently
-      // no-ops, so they're grouped instead of two independent optionals.
-      readonly referenceSearch?: {
-        readonly fields: ReadonlyArray<{
-          readonly fieldName: string;
-          readonly targetEntityName: string;
-          readonly labelField: string;
-        }>;
-        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-      };
-      // fw#2741 — `sortable: true` reference fields order by the target row's
-      // labelField instead of the raw FK column. Same request-time registry
-      // dependency (and the same fields/resolveEntity pairing) as referenceSearch.
-      readonly referenceSort?: {
-        readonly fields: ReadonlyArray<{
-          readonly fieldName: string;
-          readonly targetEntityName: string;
-          readonly labelField: string;
-        }>;
-        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-      };
-      // Join-row read-gate (EntityDefinition.parentRef) — same request-time
-      // registry dependency as referenceSearch/referenceSort above.
-      readonly parentVisibility?: ParentVisibilityOption;
-    },
-  ) => Promise<CursorResult<Record<string, unknown>>>;
-
-  detail: (
-    payload: { id: EntityId },
-    user: SessionUser,
-    db: TenantDb,
-    options?: { readonly parentVisibility?: ParentVisibilityOption },
-  ) => Promise<Record<string, unknown> | null>;
-};