@cosmicdrift/kumiko-types 0.327.0 → 0.328.1

package/dist/fields.js

@@ -0,0 +1,50 @@
+// --- Field Types ---
+/** Qualified config key a `{ kind: "tenant" }` MoneyCurrencySource resolves
+ *  against — the tenant-settings bundle's per-tenant currency. Lives here
+ *  (client-safe) rather than framework/engine so renderer code can read it
+ *  without a runtime-only import (kumiko-framework#2937). */
+export const TENANT_CURRENCY_CONFIG_KEY = "tenant-settings:config:currency";
+// Exhaustive catalogue of `FieldDefinition["type"]` values, derived from a
+// `Record` so an added/removed union member fails to compile here instead of
+// silently drifting out of sync with the runtime validator that consults
+// this list (feature-ast's pattern-change-schema). Plain array, not a Set —
+// same rationale as NO_WIDGET_FIELD_TYPES (guard-types-class-free.test.ts).
+const FIELD_TYPE_NAME_FLAGS = {
+    text: true,
+    longText: true,
+    boolean: true,
+    select: true,
+    multiSelect: true,
+    number: true,
+    bigInt: true,
+    decimal: true,
+    money: true,
+    reference: true,
+    embedded: true,
+    jsonb: true,
+    date: true,
+    timestamp: true,
+    tz: true,
+    locatedTimestamp: true,
+    file: true,
+    image: true,
+    files: true,
+    images: true,
+};
+export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS);
+// Field types with no bound, editable widget on the auto-wired entityEdit
+// path (render-field.tsx renders a read-only banner instead) — shared by
+// the boot validator (packages/framework/src/engine/boot-validator/screens.ts)
+// and the client-side required-field check (packages/renderer/src/app/form-schema.ts).
+// Embedded LIST fields (`multiple: true`) are the one exception — they get
+// their own EmbeddedListField grid widget (#1838) — callers must check that
+// separately, this array alone doesn't distinguish plain embedded from embedded lists.
+// A plain array, not a Set: kumiko-types stays free of module-scope runtime
+// identity (guard-types-class-free.test.ts) since a consumer may resolve two
+// copies of this package.
+export const NO_WIDGET_FIELD_TYPES = [
+    "jsonb",
+    "embedded",
+    "files",
+    "images",
+];

package/dist/file-handle-types.d.ts

@@ -0,0 +1,12 @@
+export type FileHandle = {
+    readonly key: string;
+    read(): Promise<Uint8Array>;
+    write(data: Uint8Array, mimeType?: string): Promise<void>;
+    delete(): Promise<void>;
+    exists(): Promise<boolean>;
+    derive(suffix: string): FileHandle;
+};
+export type FileContext = {
+    ref(key: string): FileHandle;
+    list(prefix: string): Promise<readonly string[]>;
+};

package/dist/file-handle-types.js

@@ -0,0 +1 @@
+export {};

package/dist/file-provider-resolver-types.d.ts

@@ -0,0 +1,3 @@
+import type { FileStorageProvider } from "./file-storage-provider-types.js";
+import type { TenantId } from "./identifiers.js";
+export type FileProviderResolver = (tenantId: TenantId) => Promise<FileStorageProvider>;

package/dist/file-provider-resolver-types.js

@@ -0,0 +1 @@
+export {};

package/dist/file-storage-provider-types.d.ts

@@ -0,0 +1,17 @@
+export type SignedUrlOptions = {
+    readonly contentDisposition?: string;
+};
+export type WriteStreamOptions = {
+    readonly mimeType?: string;
+    readonly contentLength?: number;
+};
+export type FileStorageProvider = {
+    write(key: string, data: Uint8Array, mimeType?: string): Promise<void>;
+    writeStream(key: string, source: AsyncIterable<Uint8Array>, options?: WriteStreamOptions): Promise<void>;
+    read(key: string): Promise<Uint8Array>;
+    readStream(key: string): AsyncIterable<Uint8Array>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    list(prefix: string): Promise<readonly string[]>;
+    getSignedUrl?(key: string, expiresInSeconds: number, options?: SignedUrlOptions): Promise<string>;
+};

package/dist/file-storage-provider-types.js

@@ -0,0 +1 @@
+export {};

package/dist/geo-tz.d.ts

@@ -0,0 +1,17 @@
+export type GeoCoordinates = {
+    readonly latitude: number;
+    readonly longitude: number;
+};
+export type GeoAddress = {
+    readonly street?: string;
+    readonly city?: string;
+    readonly region?: string;
+    readonly postalCode?: string;
+    readonly country?: string;
+};
+export type GeoTzProvider = {
+    /** Geo-coordinates → IANA zone (offline lat/lng → tz). */
+    readonly fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>;
+    /** Optional: postal address → IANA zone (geocoding API provider). */
+    readonly fromAddress?: (address: GeoAddress) => string | Promise<string>;
+};

package/{src/geo-tz.ts → dist/geo-tz.js}

@@ -10,23 +10,4 @@
 // zone, online). This split keeps the interface compatible with both
 // provider classes instead of forcing an address shape the offline case
 // can't serve at all.
-
-export type GeoCoordinates = {
-  readonly latitude: number;
-  readonly longitude: number;
-};
-
-export type GeoAddress = {
-  readonly street?: string;
-  readonly city?: string;
-  readonly region?: string;
-  readonly postalCode?: string;
-  readonly country?: string;
-};
-
-export type GeoTzProvider = {
-  /** Geo-coordinates → IANA zone (offline lat/lng → tz). */
-  readonly fromCoordinates: (coords: GeoCoordinates) => string | Promise<string>;
-  /** Optional: postal address → IANA zone (geocoding API provider). */
-  readonly fromAddress?: (address: GeoAddress) => string | Promise<string>;
-};
+export {};

package/dist/handlers.d.ts

@@ -0,0 +1,493 @@
+import type { Redis } from "ioredis";
+import type { ZodType } from "zod";
+import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config.js";
+import type { DbConnection } from "./db-connection.js";
+import type { DerivativesContext } from "./derivatives-types.js";
+import type { EntityCache } from "./entity-cache.js";
+import type { EventMetadata, WriteOrigin } from "./event-store-types.js";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
+import type { FileContext } from "./file-handle-types.js";
+import type { FileProviderResolver } from "./file-provider-resolver-types.js";
+import type { GeoTzProvider } from "./geo-tz.js";
+import type { Logger } from "./logger.js";
+import type { Meter, MetricsHandle, Tracer } from "./observability/index.js";
+import type { SearchAdapter } from "./search-adapter.js";
+import type { TenantDb } from "./tenant-db-types.js";
+import type { TzContext } from "./tz-context.js";
+export type OpenToAllPersonalData = "tenant-members";
+export type OpenToAllDeclaration = {
+    readonly reason: string;
+    readonly personalData?: OpenToAllPersonalData;
+};
+export type OpenToAllAccessRule = {
+    readonly openToAll: OpenToAllDeclaration;
+};
+export type RoleAccessPersonalData = "public-intake";
+export type RoleAccessRule = {
+    readonly roles: readonly string[];
+    readonly personalData?: RoleAccessPersonalData;
+};
+export type AccessRule = RoleAccessRule | OpenToAllAccessRule;
+export type EscapeHatchDeclaration = {
+    readonly reason: string;
+};
+export declare function isOpenToAllGranted(rule: AccessRule): boolean;
+export declare function isUiAccessGranted(access: AccessRule | undefined, userRoles: readonly string[] | undefined): boolean;
+export type SessionUserOrigin = "member-resolution";
+export type SessionUser = {
+    readonly id: string;
+    readonly tenantId: TenantId;
+    readonly roles: readonly string[];
+    readonly timezone?: string;
+    readonly locale?: string;
+    readonly claims?: Readonly<Record<string, unknown>>;
+    readonly sid?: string;
+    readonly pat?: {
+        readonly tokenId: string;
+        readonly scopes: readonly string[];
+        readonly allowedQns: readonly string[];
+    };
+    readonly origin?: SessionUserOrigin;
+};
+export type ClaimKeyType = "string" | "number" | "boolean" | "string[]" | "object";
+export type ClaimKeyJsType<T extends ClaimKeyType> = T extends "string" ? string : T extends "number" ? number : T extends "boolean" ? boolean : T extends "string[]" ? readonly string[] : T extends "object" ? Readonly<Record<string, unknown>> : never;
+export type ClaimKeyDefinition = {
+    readonly shortName: string;
+    readonly qualifiedName: string;
+    readonly type: ClaimKeyType;
+};
+export type ClaimKeyHandle<T extends ClaimKeyType = ClaimKeyType> = {
+    readonly name: string;
+    readonly type: T;
+};
+export type AuthClaimsContext = {
+    readonly db: import("./tenant-db-types.js").TenantDb;
+    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+    readonly config?: ConfigAccessor;
+};
+export type AuthClaimsFn = (user: SessionUser, ctx: AuthClaimsContext) => Promise<Record<string, unknown>>;
+export type AuthClaimsHookDef = {
+    readonly featureName: string;
+    readonly fn: AuthClaimsFn;
+    readonly declaredKeys?: ReadonlySet<string>;
+};
+export type ActiveMembershipRejection = "not_a_member" | "principal_blocked" | "tenant_teardown";
+export type ActiveMembership = {
+    readonly tenantId: TenantId;
+    readonly roles: readonly string[];
+    readonly tenantName?: string;
+    readonly tenantKey?: string;
+};
+export type ActiveMembershipResult = {
+    readonly kind: "active";
+    readonly membership: ActiveMembership;
+} | {
+    readonly kind: "rejected";
+    readonly reason: ActiveMembershipRejection;
+};
+export type WriteEvent<TPayload = unknown> = {
+    readonly type: string;
+    readonly payload: TPayload;
+    readonly user: SessionUser;
+};
+export type QueryEvent<TPayload = unknown> = {
+    readonly type: string;
+    readonly payload: TPayload;
+    readonly user: SessionUser;
+};
+import type { WriteFailure } from "./write-error-info-types.js";
+export type WriteResult<TData = unknown> = {
+    readonly isSuccess: true;
+    readonly data: TData;
+} | WriteFailure;
+import type { Registry } from "./feature.js";
+import type { TenantId } from "./identifiers.js";
+import type { UncheckedSystemDb } from "./tenant-db-types.js";
+export type MemberReader = (userId: string, qn: string, payload: unknown) => Promise<unknown>;
+export type JobTriggerEvent = {
+    readonly id: string;
+    readonly headers: NonNullable<EventMetadata["headers"]>;
+};
+export type JobRunnerRef = {
+    handleEvent(eventName: string, payload: Record<string, unknown>, user?: SessionUser, triggerEvent?: JobTriggerEvent): Promise<void>;
+};
+export type DispatchWriteRef = {
+    readonly write: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<WriteResult>;
+    readonly queryAs: (user: SessionUser, qn: string, payload: unknown, inheritedOrigin?: WriteOrigin) => Promise<unknown>;
+    readonly createMemberReader: (tenantId: TenantId) => MemberReader;
+};
+export type NotifyPriority = "critical" | "normal" | "low";
+export type NotifyOptions = {
+    readonly to?: string | readonly string[] | {
+        readonly tenant: TenantId;
+    };
+    readonly route?: Readonly<Record<string, string>>;
+    readonly data?: Readonly<Record<string, unknown>>;
+    readonly priority?: NotifyPriority;
+    readonly idempotencyKey?: string;
+    readonly recipientId?: string;
+};
+export type NotifyFn = (notificationType: string, options: NotifyOptions) => Promise<void>;
+export type NotifyFactory = (user: SessionUser, tenantId: TenantId) => NotifyFn;
+export type EscapeHatchKind = "unsafe-raw" | "acknowledge-cross-tenant" | "global-write" | "identity-switch" | "unsafe-all-tenants";
+export type EscapeHatchTarget = {
+    readonly id: string;
+    readonly tenantId: TenantId;
+};
+export type EscapeHatchUseEvent = {
+    readonly handler: string;
+    readonly kind: EscapeHatchKind;
+    readonly reason: string;
+    readonly tenantId: TenantId;
+    readonly actor: string;
+    readonly target?: EscapeHatchTarget;
+};
+export type EscapeHatchAuditSink = (event: EscapeHatchUseEvent) => Promise<void>;
+export type EscapeHatchReporter = (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => void;
+type SharedContextFields = {
+    readonly redis?: Redis;
+    readonly jobRunner?: JobRunnerRef;
+    readonly configResolver?: ConfigResolver;
+    readonly config?: ConfigAccessor;
+    readonly _configAccessorFactory?: ConfigAccessorFactory;
+    readonly configEncryption?: import("./envelope-cipher-types.js").EnvelopeCipher;
+    readonly rateLimit?: import("./rate-limit-types.js").RateLimitResolver;
+    readonly searchAdapter?: SearchAdapter;
+    readonly files?: FileContext;
+    readonly derivatives?: DerivativesContext;
+    readonly _fileProviderResolver?: FileProviderResolver;
+    readonly entityCache?: EntityCache;
+    readonly notify?: NotifyFn;
+    readonly _notifyFactory?: NotifyFactory;
+    readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
+    readonly secrets?: import("./secrets-types.js").SecretsContext;
+    readonly masterKeyProvider?: import("./secrets-types.js").MasterKeyProvider;
+    readonly kms?: import("./kms-adapter-types.js").KmsAdapter;
+    readonly tracer?: Tracer;
+    readonly meter?: Meter;
+    readonly signal?: AbortSignal;
+    readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+    readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+    readonly queryAsMember?: MemberReader;
+};
+export type AppContext = SharedContextFields & {
+    readonly db?: DbConnection | TenantDb;
+    readonly systemDb?: UncheckedSystemDb;
+    readonly registry?: Registry;
+    readonly systemUser?: SessionUser;
+    readonly log?: Logger;
+    readonly triggeredBy?: {
+        readonly id: string;
+        readonly tenantId: TenantId;
+    } | null;
+    /** Bei Job-Handler-Aufrufen die aus einem Event-Trigger heraus laufen
+     *  (r.job mit `trigger: { on: ... }`): der Name des Handlers der das
+     *  Event ausgelöst hat. Bei Multi-Trigger-Jobs (`on: [...]`) ist das
+     *  die einzige Möglichkeit für den Handler zu wissen WELCHER Trigger
+     *  gefeuert hat. Cron- und manual-Jobs lassen das Feld undefined. */
+    readonly triggerName?: string;
+    readonly _userId?: string | undefined;
+    readonly _handlerType?: string | undefined;
+    /** Optionaler Geo→Zone-Adapter. Wenn gesetzt (via buildServer-context oder
+     *  runProdApp/runDevApp extraContext), reicht der Dispatcher ihn an
+     *  ctx.tz.fromCoordinates / fromAddress weiter. Ohne Provider werfen diese. */
+    readonly geoTzProvider?: GeoTzProvider;
+    /** Tenant des aktuellen Pipeline-Calls. Wird vom Dispatcher beim Bauen
+     *  des HandlerContext aus `user.tenantId` gespiegelt, damit lifecycle-
+     *  pipeline + system-hooks den Wert ohne Zugriff auf user-Object haben.
+     *  Sprint-8a Tier-Composition: `effectiveFeatures(ctx._tenantId)`-call
+     *  in den hook-filter-Stellen. */
+    readonly _tenantId?: TenantId;
+    /** Boot-configured default locale (BCP-47). Last fallback in ctx.locale's
+     *  Request-Locale → Boot-Default chain (dispatch-shared.ts) — used when
+     *  the request carries no X-Locale header and no usable Accept-Language.
+     *  Absent falls back to "en". */
+    readonly defaultLocale?: string;
+};
+export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
+    readonly db: TenantDb;
+    readonly dbOutsideTransaction: TenantDb | undefined;
+    readonly systemDb?: UncheckedSystemDb;
+    readonly registry: Registry;
+    /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
+     *  `event.user`. Existiert weil Handler intuitiv `ctx.user.tenantId`
+     *  schreiben (Context = "kennt seinen User") und der Pfad sonst nur
+     *  über `event.user` läuft, was typo-anfällig ist und stillschweigend
+     *  zu `internal_error` führt wenn der falsche Pfad gewählt wird.
+     *  Identisch zum event.user-Wert; Identity-Switches nutzen
+     *  weiterhin queryAs/writeAs. */
+    readonly user: SessionUser;
+    readonly systemUser?: SessionUser;
+    readonly log?: Logger;
+    readonly triggeredBy?: {
+        readonly id: string;
+        readonly tenantId: TenantId;
+    } | null;
+    readonly _userId?: string | undefined;
+    readonly _handlerType?: string | undefined;
+    readonly includeDeleted?: boolean;
+    readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
+    readonly query: (qn: string, payload: unknown) => Promise<unknown>;
+    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly hasFeature: (featureName: string) => Promise<boolean>;
+    readonly appendEvent: AppendEventFn<TMap>;
+    readonly unsafeAppendEvent: UnsafeAppendEventFn;
+    readonly tryAppendEvent: TryAppendEventFn;
+    readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
+    readonly loadAggregate: (aggregateId: string, options?: {
+        readonly asOf?: Temporal.Instant;
+    }) => Promise<readonly import("./event-store-types.js").StoredEvent[]>;
+    readonly archiveStream: (aggregateId: string, args: {
+        readonly aggregateType: string;
+        readonly reason?: string;
+    }) => Promise<void>;
+    readonly restoreStream: (aggregateId: string) => Promise<void>;
+    readonly isStreamArchived: (aggregateId: string) => Promise<boolean>;
+    readonly snapshotAggregate: (args: {
+        readonly aggregateId: string;
+        readonly aggregateType: string;
+        readonly version: number;
+        readonly state: Record<string, unknown>;
+        readonly snapshotVersion?: number;
+    }) => Promise<void>;
+    readonly loadAggregateWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: import("./snapshot-types.js").SnapshotReducer<TState>, initial: TState, options?: Omit<import("./snapshot-types.js").LoadAggregateWithSnapshotOptions, "upcastEvent">) => Promise<import("./snapshot-types.js").LoadAggregateWithSnapshotResult<TState>>;
+    readonly queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
+        readonly unsafeAllTenants?: boolean;
+    }) => Promise<readonly T[]>;
+    readonly metrics: MetricsHandle;
+    readonly metricsFor: (featureName: string) => MetricsHandle;
+    readonly tracer: Tracer;
+    readonly tz: TzContext;
+    readonly locale: string;
+    readonly resolveAuthClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
+    readonly resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
+    readonly queryAsMember: MemberReader;
+};
+export type JobContext = SharedContextFields & {
+    readonly db: TenantDb;
+    readonly registry: Registry;
+    readonly systemUser: SessionUser;
+    readonly log: Logger;
+    readonly triggeredBy: {
+        readonly id: string;
+        readonly tenantId: TenantId;
+    } | null;
+    readonly attempt: number;
+    readonly finalAttempt: boolean;
+    readonly systemDb?: UncheckedSystemDb;
+    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+    readonly queryAsMember: MemberReader;
+    readonly triggerName?: string;
+    readonly triggerEvent?: JobTriggerEvent;
+    readonly _tenantId?: TenantId;
+    readonly _userId?: string | undefined;
+};
+export type WriteHandlerFn<TPayload = unknown, TData = unknown> = (event: WriteEvent<TPayload>, context: HandlerContext) => Promise<WriteResult<TData>>;
+export type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
+export type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => AsyncGenerator<TChunk>;
+/**
+ * Compile-time mirror of `engine/qualified-name.ts:toKebab` for camelCase
+ * → kebab-case. Drives the literal-type of `EventDef.name`, so that
+ * `r.defineEvent("foo", schema)` inside `defineFeature("driverOrders")`
+ * carries `name: "driver-orders:event:foo"` as a literal — strict-mode
+ * for `ctx.appendEvent({ type: eventDef.name, ... })` lights up.
+ *
+ * Algorithm mirrors the runtime regex pipeline:
+ *   1. `.` → `-` (dot acts as word-boundary)
+ *   2. Insert `-` between `[A-Z]+` and `[A-Z][a-z]` (so `SSEFoo` →
+ *      `SSE-Foo`, splitting an uppercase run before a camel-hump)
+ *   3. Insert `-` between `[a-z0-9]` and `[A-Z]` (camelCase boundary,
+ *      so `ticketAssigned` → `ticket-Assigned`)
+ *   4. lowercase everything
+ *
+ * Implemented as a state machine with one-char lookahead. State:
+ *   - "start"        — at start of string, or right after a dot-boundary
+ *   - "upper"        — last emitted char came from an uppercase letter
+ *   - "post-letter"  — last emitted char was a lowercase letter or digit
+ *
+ * Sync vs runtime is verified by `engine/__tests__/camel-to-kebab.test-d.ts`
+ * — the type-tests cross-check identical inputs against `toKebab()`.
+ */
+export type CamelToKebab<S extends string> = CamelToKebabImpl<S, "start", "">;
+type CamelToKebabImpl<S extends string, Prev extends "start" | "upper" | "post-letter", Acc extends string> = S extends `${infer C}${infer Rest}` ? CharKind<C> extends "upper" ? Prev extends "start" ? CamelToKebabImpl<Rest, "upper", `${Acc}${Lowercase<C>}`> : Prev extends "post-letter" ? CamelToKebabImpl<Rest, "upper", `${Acc}-${Lowercase<C>}`> : Rest extends `${infer Next}${string}` ? CharKind<Next> extends "lower" ? CamelToKebabImpl<Rest, "upper", `${Acc}-${Lowercase<C>}`> : CamelToKebabImpl<Rest, "upper", `${Acc}${Lowercase<C>}`> : `${Acc}${Lowercase<C>}` : CharKind<C> extends "lower" ? CamelToKebabImpl<Rest, "post-letter", `${Acc}${C}`> : C extends "." ? CamelToKebabImpl<Rest, "start", `${Acc}-`> : CamelToKebabImpl<Rest, "post-letter", `${Acc}${C}`> : Acc;
+/**
+ * Three-way classification used by `CamelToKebab`:
+ *   - "lower"      — a lowercase letter (a-z and Unicode lowercase)
+ *   - "upper"      — an uppercase letter (A-Z and Unicode uppercase)
+ *   - "non-letter" — digit, dot, dash, etc. (Lowercase==Uppercase for them)
+ */
+type CharKind<C extends string> = C extends Lowercase<C> ? (C extends Uppercase<C> ? "non-letter" : "lower") : "upper";
+/**
+ * Builds the qualified event-name from feature + inner-name in the same
+ * shape the runtime emits via `qn(toKebab(feature), "event", toKebab(inner))`.
+ */
+export type QualifiedEventName<TFeature extends string, TInner extends string> = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`;
+export type EventPiiAbsentSubject = "plaintext" | "tenant";
+export type EventPiiSubject = {
+    readonly personal: {
+        readonly of: string;
+        readonly whenAbsent?: EventPiiAbsentSubject;
+    };
+} | {
+    readonly personal: "tenant";
+} | {
+    readonly personal: "self";
+} | {
+    /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. */
+    readonly subjectField: string;
+};
+export type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;
+export type NormalizedEventPiiSubject = {
+    readonly kind: "user";
+    readonly ownerField: string;
+    readonly whenAbsent: EventPiiAbsentSubject | undefined;
+} | {
+    readonly kind: "tenant";
+} | {
+    readonly kind: "self";
+};
+export declare function normalizeEventPiiSubject(spec: EventPiiSubject): NormalizedEventPiiSubject;
+export type EventPiiStance = EventPiiFields | "none";
+export type EventDef<TPayload = unknown, TName extends string = string> = {
+    readonly name: TName;
+    readonly schema: ZodType<TPayload>;
+    readonly version: number;
+    readonly piiFields?: EventPiiStance;
+};
+export type AppendEventArgs = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly headers?: Readonly<Record<string, string | number | boolean>>;
+};
+export type TypedAppendEventArgs<TMap extends object, K extends keyof TMap> = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly type: K;
+    readonly payload: TMap[K];
+    readonly headers?: Readonly<Record<string, string | number | boolean>>;
+};
+export type AppendEventFn<TMap extends object = KumikoEventTypeMap> = <K extends keyof TMap>(args: TypedAppendEventArgs<TMap, K>) => Promise<void>;
+export type UnsafeAppendEventFn = (args: AppendEventArgs) => Promise<void>;
+export type TryAppendEventResult = {
+    readonly ok: true;
+    readonly event: import("./event-store-types.js").StoredEvent;
+} | {
+    readonly ok: false;
+    readonly conflict: import("./event-store-types.js").VersionConflict;
+};
+export type TryAppendEventFn = (args: AppendEventArgs) => Promise<TryAppendEventResult>;
+export type FetchForWritingArgs = {
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly expectedVersion?: number;
+};
+export type AggregateStreamHandle = {
+    readonly events: readonly import("./event-store-types.js").StoredEvent[];
+    readonly version: number;
+    readonly appendOne: (args: {
+        readonly type: string;
+        readonly payload: unknown;
+    }) => Promise<void>;
+    readonly hasEvent: (type: string) => boolean;
+};
+export type EventUpcastCtx = {
+    readonly db: import("./db-connection.js").DbRunner;
+    readonly tenantId: import("./identifiers.js").TenantId;
+};
+export type EventUpcastFn = (payload: unknown, ctx: EventUpcastCtx) => unknown | Promise<unknown>;
+export type DeclarativeEventMigration = {
+    readonly rename?: Readonly<Record<string, string>>;
+    readonly default?: Readonly<Record<string, unknown>>;
+    readonly map?: Readonly<Record<string, (value: unknown) => unknown>>;
+};
+export type EventMigrationDef = {
+    readonly eventName: string;
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly transform: EventUpcastFn;
+};
+export type NameOrRef = string | {
+    readonly name: string;
+};
+export type EntityRef = {
+    readonly name: string;
+    readonly table: string;
+};
+export type HandlerRef = {
+    readonly name: string;
+};
+export type RateLimitPer = "user" | "tenant" | "ip" | "user+handler" | "tenant+handler" | "ip+handler";
+export type RateLimitOption = {
+    readonly per: RateLimitPer;
+    readonly limit: number;
+    readonly windowSeconds: number;
+    readonly cost?: number;
+};
+export type RateLimitDisabled = {
+    readonly disabled: true;
+    readonly reason: string;
+};
+export type RateLimitDeclaration = RateLimitOption | RateLimitDisabled;
+export declare function isRateLimitDisabled(v: RateLimitDeclaration | undefined): v is RateLimitDisabled;
+export type AgentRisk = "low" | "mid" | "high";
+/** Per-handler hints for the AI-agent manifest. `expose` overrides the
+ *  default derived from `description`; `risk` overrides the per-kind default. */
+export type AgentHandlerHints = {
+    readonly expose?: boolean;
+    readonly risk?: AgentRisk;
+};
+export type AgentExposure = {
+    readonly expose: boolean;
+    readonly risk: AgentRisk;
+};
+export type WriteHandlerDef = {
+    readonly name: string;
+    readonly schema: ZodType;
+    readonly handler: WriteHandlerFn;
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    readonly unsafeSkipTransitionGuard?: boolean;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly perform?: import("./step.js").PipelineDef;
+};
+export declare const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";
+export type QueryHandlerDef = {
+    readonly name: string;
+    readonly schema: ZodType;
+    readonly handler: QueryHandlerFn;
+    /** Set only by defineEntityQueryHandler, which wires the parent-ref
+     *  read-gate. The boot-validator requires it on a `parentRef` entity's
+     *  list/detail handler — see boot-validator/parent-ref.ts. */
+    readonly [ENTITY_CONVENTION_QUERY_BRAND]?: true;
+    readonly access: AccessRule;
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+    readonly rateLimit?: RateLimitDeclaration;
+    /** Zod schema of the handler's actual return value — the paged envelope
+     *  `{ rows, nextCursor, total? }` for a `definePagedQueryHandler`, or the
+     *  flat record (optionally `.nullable()`) for a plain query handler.
+     *  Optional and purely additive: absent on every existing handler, and
+     *  the boot-validator skips any column-reference check that would need
+     *  it (screens.ts projectionList/relatedList `columns`, projectionDetail
+     *  `header`/`metrics`, dashboard `valueField`/`subField`/etc.) rather
+     *  than requiring it retroactively. See fw#2493. */
+    readonly outputSchema?: ZodType;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+};
+export type StreamHandlerDef = {
+    readonly name: string;
+    readonly schema: ZodType;
+    readonly handler: StreamHandlerFn;
+    readonly access: AccessRule;
+    readonly rateLimit?: RateLimitDeclaration;
+    readonly escapeHatch?: EscapeHatchDeclaration;
+};
+export {};