@cosmicdrift/kumiko-types 0.388.0 → 0.390.0

package/dist/config.d.ts

@@ -4,7 +4,7 @@ import type { ConfigScope } from "./config-scope.ts";
 import type { DbConnection } from "./db-connection.ts";
 import type { EntityFieldDefinition, OptionsQueryPayload } from "./fields.ts";
 import type { EscapeHatchDeclaration, JobContext, JobDeferral } from "./handlers.ts";
-import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.ts";
+import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn } from "./hooks.ts";
 import type { TenantId } from "./identifiers.ts";
 import type { NavIconKey } from "./nav-icon.ts";
 import type { DashboardCustomPanel, DashboardScreenPanel } from "./screen.ts";
@@ -31,6 +31,7 @@ export type ConfigValidateContext = {
     readonly tenantId: TenantId;
     readonly userId: string | null;
     readonly db: TenantDb;
+    readonly readCascade: (qualifiedKey: string) => Promise<ConfigCascade>;
 };
 export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
@@ -282,7 +283,6 @@ export type RegistrarExtensionHooks = {
     readonly postSave?: PostSaveHookFn;
     readonly preDelete?: PreDeleteHookFn;
     readonly postDelete?: PostDeleteHookFn;
-    readonly preQuery?: PreQueryHookFn;
 };
 export type UiExtensionDef = {
     readonly editSection?: string;

package/dist/db-connection.d.ts

@@ -1,4 +1,4 @@
-import type postgres from "postgres";
+import type { SQL, TransactionSQL } from "bun";
 export type RawDbClient = {
     unsafe: (sql: string, params?: readonly unknown[]) => PromiseLike<readonly unknown[]>;
     begin: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
@@ -6,11 +6,11 @@ export type RawDbClient = {
         timeout?: number;
     }) => Promise<void>;
 };
-export type DbConnection = ReturnType<typeof postgres> | RawDbClient;
-export type DbTx = postgres.TransactionSql<Record<string, unknown>> | RawDbClient;
+export type DbConnection = SQL | RawDbClient;
+export type DbTx = TransactionSQL | RawDbClient;
 export type DbRunner = DbConnection | DbTx;
 export type DbRow = Record<string, unknown>;
-export type PgClient = ReturnType<typeof postgres>;
+export type PgClient = SQL;
 export type PgListenSubscription = {
     unlisten(): Promise<void>;
 };

package/dist/event-store-executor-types.d.ts

@@ -100,7 +100,7 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
     /** 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.
+     *  one from ctx.services.searchAdapter here at runtime.
      *  options.searchAdapter (build-time) wins — the runtime override
      *  is the fallback for the default wrapper. */
     runtimeOptions?: ListRuntimeOptions) => Promise<CursorResult<Row>>;

package/dist/event-type-map.js

@@ -1,6 +1,6 @@
 // Cross-Feature Compile-Time Type Map.
 //
-// Purpose: check ctx.appendEvent / ctx.queryProjection / dispatcher.write against a
+// Purpose: check ctx.events.append / ctx.dispatch.queryProjection / dispatcher.write against a
 // statically known schema image instead of failing only at boot or runtime
 // (zod-validate). The Designer/AI layer benefits immediately: autocomplete knows all
 // event types from all loaded features, and payload-shape mismatches appear in the

package/dist/feature-registrar.d.ts

@@ -0,0 +1,321 @@
+import type * as z from "zod";
+import type { ZodType } from "zod";
+import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, RegistrarExtensionDef, TemplateVariables, TranslationsDef } from "./config.ts";
+import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.ts";
+import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
+import type { EntityTableMeta } from "./entity-table-meta-types.ts";
+import type { KumikoEventTypeMap } from "./event-type-map.ts";
+import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.ts";
+import type { BootCheckFn, MetricOptions, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableOptions, UiHints } from "./feature.ts";
+import type { EntityDefinition } from "./fields.ts";
+import type { AccessRule, AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, RateLimitDeclaration, StreamHandlerFn } from "./handlers.ts";
+import type { HookPhase, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
+import type { HttpRouteDefinition } from "./http-route.ts";
+import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
+import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
+import type { RelationDefinition } from "./relations.ts";
+import type { ScreenDefinition } from "./screen.ts";
+import type { TreeActionDef, TreeActionsHandle } from "./tree-node.ts";
+import type { WebSocketRouteDefinition } from "./websocket-route.ts";
+import type { WorkspaceDefinition } from "./workspace.ts";
+type RefOrRefs = NameOrRef | readonly NameOrRef[];
+type HookTarget = RefOrRefs | {
+    readonly allOf: NameOrRef;
+};
+export type EntityObjectDefinition = {
+    readonly name: string;
+    readonly backingTable?: unknown;
+} & EntityDefinition;
+type HookEscapeHatch = {
+    readonly escapeHatch?: EscapeHatchDeclaration;
+};
+type HookPhaseOption = {
+    readonly phase?: HookPhase;
+};
+export type HookDefinition = {
+    readonly type: "validation";
+    readonly target: RefOrRefs;
+    readonly handler: ValidationHookFn;
+    readonly escapeHatch?: never;
+    readonly phase?: never;
+} | ({
+    readonly type: "preSave";
+    readonly target: RefOrRefs;
+    readonly handler: PreSaveHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    readonly type: "postSave";
+    readonly target: HookTarget;
+    readonly handler: PostSaveHookFn;
+} & HookEscapeHatch & HookPhaseOption) | ({
+    readonly type: "preDelete";
+    readonly target: HookTarget;
+    readonly handler: PreDeleteHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    readonly type: "postDelete";
+    readonly target: HookTarget;
+    readonly handler: PostDeleteHookFn;
+} & HookEscapeHatch & HookPhaseOption) | ({
+    readonly type: "postQuery";
+    readonly target: HookTarget;
+    readonly handler: PostQueryHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch);
+/**
+ * `r.requires({ features })` declares the features this one depends on; the
+ * `.projection` extension declares read-side projection tables that this
+ * feature's pipeline steps are allowed to write via
+ * `r.step.unsafeProjectionUpsert` (hard-required for any unsafeProjection-*
+ * step usage, see Q10).
+ *
+ * @example r.requires({ features: ["auth", "tenant"] });
+ */
+export type RequiresApi = ((options: {
+    readonly features: readonly string[];
+}) => void) & {
+    readonly projection: (tableName: string) => void;
+    readonly step: (stepKind: string) => void;
+};
+/**
+ * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
+ * default-`string` keeps every existing usage zero-config. Strict-typed
+ * features (apps that opt into the literal-name flavour) get propagated
+ * through to `defineEvent` so the returned `EventDef.name` is a literal
+ * `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`. That literal
+ * threads through `ctx.events.append({ type: eventDef.name, ... })`,
+ * keeping strict-mode alive even when handlers route via `eventDef.name`
+ * instead of hand-typed string literals.
+ */
+export type FeatureRegistrar<TFeature extends string = string> = {
+    systemScope(): void;
+    describe(text: string): void;
+    requires: RequiresApi;
+    optionalRequires(...featureNames: string[]): void;
+    optionalRequires(options: {
+        readonly features: readonly string[];
+    }): void;
+    toggleable(options: {
+        default: boolean;
+    }): void;
+    adoptsBundledLists(): void;
+    uiHints(hints: UiHints): void;
+    /**
+     * @example r.entity({ name: "note", fields: { title: createTextField({ required: true }) } });
+     */
+    entity(definition: EntityObjectDefinition): EntityRef;
+    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
+    /**
+     * @example r.writeHandler({ name: "note:archive", schema, handler, access: { roles: ["User"] } });
+     */
+    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
+    /**
+     * @example r.queryHandler({ name: "note:list", schema, handler, access: { roles: ["User"] } });
+     */
+    queryHandler<TName extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName, TSchema>): HandlerRef;
+    streamHandler<TName extends string, TSchema extends ZodType>(def: StreamHandlerDefinition<TName, TSchema>): HandlerRef;
+    streamHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: StreamHandlerFn<z.infer<TSchema>>, options: {
+        access: AccessRule;
+        rateLimit?: RateLimitDeclaration;
+        escapeHatch?: EscapeHatchDeclaration;
+    }): HandlerRef;
+    relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
+    relation<TDef extends RelationDefinition>(definition: {
+        readonly entity: NameOrRef;
+        readonly name: string;
+    } & TDef): void;
+    /**
+     * @example r.hook({ type: "postSave", target: { allOf: noteRef }, handler: notifyOwner });
+     */
+    hook(definition: HookDefinition): void;
+    searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
+    config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
+    config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
+        readonly keys: TKeys;
+        readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
+    }): {
+        readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
+    };
+    job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
+    job(definition: JobDefinition): void;
+    notification(name: string, definition: {
+        readonly trigger?: {
+            readonly on: NameOrRef;
+        };
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
+        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
+    }): void;
+    notification(definition: {
+        readonly name: string;
+        readonly trigger?: {
+            readonly on: NameOrRef;
+        };
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
+        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
+        readonly renamedFrom?: readonly string[];
+        readonly systemOnly?: boolean;
+        readonly unsubscribe?: boolean;
+        readonly tenantTransport?: boolean;
+    }): void;
+    translations(def: TranslationsDef): void;
+    defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {
+        readonly version?: number;
+        readonly piiFields: EventPiiStance;
+        readonly migrations?: readonly {
+            readonly fromVersion: number;
+            readonly toVersion: number;
+            readonly transform: EventUpcastFn | DeclarativeEventMigration;
+        }[];
+    }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
+    readsConfig(...qualifiedKeys: string[]): void;
+    readsConfig(options: {
+        readonly keys: readonly string[];
+    }): void;
+    referenceData(entity: NameOrRef, data: readonly Record<string, unknown>[], options?: {
+        upsertKey?: string;
+    }): void;
+    referenceData(definition: {
+        readonly entity: NameOrRef;
+        readonly data: readonly Record<string, unknown>[];
+        readonly upsertKey?: string;
+    }): void;
+    extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
+    useExtension<N extends string>(extensionName: N, entity: NameOrRef, ...options: ExtensionOptionsArgs<N>): void;
+    useExtension<N extends string>(definition: {
+        readonly name: N;
+        readonly entity: NameOrRef;
+    } & ExtensionOptionsFor<N>): void;
+    /**
+     * Declares which config key selects the active provider under an
+     * extension point — called by the point-owning foundation (e.g.
+     * `r.extensionSelector("mailTransport", configKeys.provider)`).
+     * Readiness gating counts a provider-feature's `required` keys and
+     * secrets only while that provider is the selected one. Registry-build
+     * fails on duplicate declarations per extension and on selector keys
+     * that no mounted feature declares. A masked tenant selector key makes the
+     * Settings-Hub render one tenant dashboard for the owner: the selector as a
+     * select of the mounted plugin ids, the selected plugin's config and secrets
+     * as panels, and plugin features lose their own tenant nav. `config:write:set`
+     * rejects unknown plugin ids (`""` clears). `options.panels` adds the owner's own
+     * `custom`/`screen` panels to that dashboard, after the selection and before the
+     * plugin panels (a short `screen` id means a screen of the declaring feature).
+     */
+    extensionSelector(extensionName: string, key: {
+        readonly name: string;
+    } | string, options?: {
+        readonly panels?: readonly ExtensionSelectorPanel[];
+    }): void;
+    /**
+     * Marker declaration: this feature provides a cross-feature API under the
+     * given name. The implementation is registered separately as a query or
+     * write handler under the QN pattern; `r.exposesApi` is only a boot-check
+     * surface.
+     *
+     * The boot validator checks that every `r.usesApi(name)` finds a matching
+     * exposer, that the exposer feature is listed in requires/optionalRequires,
+     * and that no API name is exposed more than once.
+     *
+     * ```ts
+     * defineFeature("compliance-profiles", (r) => {
+     *   r.exposesApi("compliance.forTenant");
+     *   r.queryHandler({
+     *     name: "compliance:query:for-tenant",
+     *     // ... actual implementation
+     *   });
+     * });
+     * ```
+     */
+    exposesApi(apiName: string): void;
+    /**
+     * Declares that this feature calls a cross-feature API. The boot validator
+     * checks that another feature provides `r.exposesApi(apiName)` and that
+     * this feature lists it in `r.requires/optionalRequires`.
+     *
+     * ```ts
+     * defineFeature("user-data-rights", (r) => {
+     *   r.requires({ features: ["compliance-profiles"] });
+     *   r.usesApi("compliance.forTenant");
+     * });
+     * ```
+     */
+    usesApi(apiName: string): void;
+    /**
+     * Declares a boot-time mount-invariant for this feature. `fn` runs once
+     * at boot with a ctx exposing every mounted feature — throw to fail the
+     * boot with a clear message. Multiple calls per feature are allowed.
+     *
+     * Use for cross-feature invariants that `r.requires` can't express
+     * because they're conditional (only fail when the feature has a
+     * specific shape), e.g. "if this feature has PII entities, some
+     * user-data-hook feature must be mounted" (the prompt-store trap —
+     * a UserData feature was written but never mounted, and nothing caught
+     * it at boot):
+     *
+     * ```ts
+     * defineFeature("prompt-store", (r) => {
+     *   const promptFields = { text: createTextField({ personal: "self", find: "none" }) };
+     *   r.entity({ name: "prompt", fields: promptFields });
+     *   r.bootCheck(({ features }) => {
+     *     // Conditional on this feature's own shape (has a pii field) —
+     *     // r.requires({ features: ["user-data-hook"] }) can't express that, it would fail
+     *     // even for a prompt-store variant with no PII fields at all.
+     *     const hasPiiField = Object.values(promptFields).some((f) => f.pii);
+     *     const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
+     *     if (hasPiiField && !hasUserDataHook) {
+     *       throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
+     *     }
+     *   });
+     * });
+     * ```
+     */
+    bootCheck(fn: BootCheckFn): void;
+    metric(shortName: string, options: MetricOptions): void;
+    metric(definition: {
+        readonly name: string;
+    } & MetricOptions): void;
+    secret(shortName: string, options: SecretOptions): SecretKeyHandle;
+    secret(definition: {
+        readonly name: string;
+    } & SecretOptions): SecretKeyHandle;
+    secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
+    secretNamespace(definition: {
+        readonly name: string;
+    } & SecretNamespaceOptions): SecretNamespaceHandle;
+    projection(definition: ProjectionDefinition): void;
+    multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
+    extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
+    authClaims(fn: AuthClaimsFn): void;
+    claimKey<T extends ClaimKeyType>(shortName: string, options: {
+        readonly type: T;
+    }): ClaimKeyHandle<T>;
+    claimKey<T extends ClaimKeyType>(definition: {
+        readonly name: string;
+        readonly type: T;
+    }): ClaimKeyHandle<T>;
+    screen(definition: ScreenDefinition): void;
+    nav(definition: NavDefinition): void;
+    contentCollection(definition: ContentCollectionDefinition): string;
+    workspace(definition: WorkspaceDefinition): void;
+    httpRoute(definition: HttpRouteDefinition): void;
+    webSocketRoute(definition: WebSocketRouteDefinition): void;
+    storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
+    treeActions<const TActions extends Record<string, TreeActionDef>>(actions: TActions): TreeActionsHandle<TFeature, TActions>;
+    envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
+};
+export {};

package/dist/feature-registrar.js

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