@cosmicdrift/kumiko-types 0.388.0 → 0.389.0

package/dist/config.d.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";

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/feature-registrar.d.ts

@@ -0,0 +1,326 @@
+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, PreQueryHookFn, 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: "preQuery";
+    readonly target: RefOrRefs;
+    readonly handler: PreQueryHookFn;
+    readonly phase?: never;
+} & HookEscapeHatch) | ({
+    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.appendEvent({ 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 {};

package/dist/feature.d.ts

@@ -1,20 +1,16 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TemplateVariables, TranslationKeys, TranslationsDef } from "./config.ts";
-import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.ts";
-import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
+import type { ConfigKeyDefinition, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, NotificationDefinition, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys } from "./config.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 { EntityDefinition } from "./fields.ts";
-import type { AccessRule, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, QueryHandlerDef, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef } from "./handlers.ts";
-import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
+import type { AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, EventDef, EventMigrationDef, EventUpcastFn, QueryHandlerDef, StreamHandlerDef, WriteHandlerDef } from "./handlers.ts";
+import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn } 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 { EntityRelations, RelationDefinition } from "./relations.ts";
 import type { ScreenDefinition } from "./screen.ts";
-import type { TreeActionDef, TreeActionsHandle } from "./tree-node.ts";
+import type { TreeActionDef } from "./tree-node.ts";
 import type { WebSocketRouteDefinition } from "./websocket-route.ts";
 import type { WorkspaceDefinition } from "./workspace.ts";
 export type FeatureMetricType = "counter" | "histogram" | "gauge";
@@ -116,7 +112,7 @@ export type BootCheckContext = {
 };
 export type BootCheckFn = (ctx: BootCheckContext) => void;
 /** runProdApp options a stack can depend on; runProdApp checks the set at boot. */
-export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "demoMode" | "seeds" | "signals" | "rateLimit";
+export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "rateLimit";
 export type StackBootRequirement = {
     readonly stack: string;
     readonly options: readonly BootOptionName[];
@@ -133,6 +129,7 @@ export type FeatureDefinition = {
     readonly requiredProjections: ReadonlySet<string>;
     readonly requiredSteps: ReadonlySet<string>;
     readonly toggleableDefault?: boolean;
+    readonly adoptsBundledLists?: true;
     readonly uiHints?: UiHints;
     readonly entities?: Readonly<Record<string, EntityDefinition>>;
     readonly entityTables?: Readonly<Record<string, unknown>>;
@@ -198,310 +195,6 @@ export type FeatureDefinition = {
     readonly envSchema?: z.ZodObject<z.ZodRawShape>;
     readonly dedupeOptions?: Readonly<Record<string, unknown>>;
 };
-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: "preQuery";
-    readonly target: RefOrRefs;
-    readonly handler: PreQueryHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    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.appendEvent({ 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;
-    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 type Registry = {
     readonly features: ReadonlyMap<string, FeatureDefinition>;
     getFeature(name: string): FeatureDefinition | undefined;
@@ -595,4 +288,3 @@ export type Registry = {
     getDefaultWorkspace(): WorkspaceDefinition | undefined;
     getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
 };
-export {};

package/dist/handlers.d.ts

@@ -256,6 +256,7 @@ type SharedContextFields = {
     readonly signal?: AbortSignal;
     readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
     readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+    readonly scheduleAfterRollback?: (hook: () => Promise<void>) => void;
     readonly queryAsMember?: MemberReader;
 };
 export type AppContext = SharedContextFields & {
@@ -350,6 +351,10 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
     readonly loadAggregate: (aggregateId: string, options?: {
         readonly asOf?: Temporal.Instant;
+        readonly atVersion?: never;
+    } | {
+        readonly atVersion?: number;
+        readonly asOf?: never;
     }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
     readonly archiveStream: (aggregateId: string, args: {
         readonly aggregateType: string;
@@ -405,12 +410,6 @@ export type JobContext = SharedContextFields & {
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
 };
-/**
- * What a provider plugin (`build`, `capabilitiesFor`, ...) may read. Both write/query handlers
- * and jobs can produce one (`providerPluginContextFromHandler`, `providerPluginContextFromJob`),
- * so a plugin never depends on a request-bound field.
- */
-export type ProviderPluginContext = Pick<HandlerContext, "db" | "dbOutsideTransaction" | "systemDb" | "registry" | "user" | "log" | "triggeredBy" | "config" | "secrets">;
 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>;

package/dist/list-aggregate-types.d.ts

@@ -23,7 +23,12 @@ export type ListAggregatePayload = {
         readonly kind: ListAggregateMeasureKind;
     }[];
 };
-export type ListAggregateValue = number | string | null;
+export type ListAggregateCurrencyAmount = {
+    readonly currency: string;
+    readonly value: number;
+};
+export type ListAggregateValue = number | string | null | readonly ListAggregateCurrencyAmount[];
+export declare function isListAggregateCurrencyAmounts(value: ListAggregateValue | undefined): value is readonly ListAggregateCurrencyAmount[];
 export type ListAggregateGroup = {
     readonly key: AggregateKey;
     readonly label?: string | null;

package/dist/list-aggregate-types.js

@@ -9,6 +9,9 @@ export const listAggregatePayloadSchema = z.object({
         .max(MAX_LIST_AGGREGATE_MEASURES)
         .default([]),
 });
+export function isListAggregateCurrencyAmounts(value) {
+    return Array.isArray(value);
+}
 const LIST_AGGREGATE_RESULT_KEYS = ["groups", "truncated", "searchTruncated"];
 // Closed key set: a row that merely has a `groups` field (jsonb column) must not
 // be mistaken for an aggregate and skip the row-level read filter.

package/dist/screen-entity-edit.d.ts

@@ -6,6 +6,8 @@ import type { FieldRenderer, PlatformComponent, ScreenNavSugar, ScreenSlots } fr
 import type { ActionFormRedirect } from "./screen-action-form.ts";
 import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
 import type { ListColumnSpec, ListSortSpec, RelatedListToolbarAction, RowAction, RowActionMode, RowFieldExtractor } from "./screen-entity-list.ts";
+import type { ListBulkAction } from "./screen-list-bulk.ts";
+import type { ListTableGrouping, ListTableOptions } from "./screen-list-table.ts";
 import type { ListFacetSpec } from "./screen-projection.ts";
 export type EditFieldSpec = string | {
     readonly field: string;
@@ -168,25 +170,9 @@ export type EditExtensionSection = {
      *  (declared or id-derived); the boot-validator rejects one that doesn't. */
     readonly actions?: readonly RowAction[];
 };
-/** Rows are grouped by `field` in order of first appearance. Every group gets
- *  a collapsible header. */
-export type RelatedListGroupBy = {
-    readonly field: string;
-    /** Groups whose field value equals this start collapsed; the others start open. */
-    readonly collapsedWhen?: string | number | boolean | null;
-    /** i18n key of the group header. Placeholders: `{count}` rows in the group,
-     *  `{value}` the group's field value, `{lastDate}` the group's latest
-     *  `dateField` value as a locale date. A group with neither `label` nor an
-     *  entry in `labels` renders its rows without a header and never collapses. */
-    readonly label?: string;
-    /** Header i18n key per group value (as string), overriding `label`. */
-    readonly labels?: Readonly<Record<string, string>>;
-    /** Row field (ISO date or timestamp) behind `{lastDate}`. */
-    readonly dateField?: string;
-};
-/** Group key of a field value; `collapsedWhen` and row values both go through it. */
+/** Group key of a field value; `collapsedWhen` and server group keys both go through it. */
 export declare function relatedListGroupKey(value: unknown): string;
-export declare function relatedListGroupHeaderLabel(groupBy: RelatedListGroupBy, groupKey: string): string | undefined;
+export declare function relatedListGroupHeaderLabel(grouping: Pick<ListTableGrouping, "label" | "labels">, groupKey: string): string | undefined;
 /** Row tint rule: rows where the `FieldCondition` (`{ field, eq }`, `{ field,
  *  in }` …) holds get the tone. `bad` renders red. */
 export type RelatedListRowTone = Exclude<FieldCondition, boolean> & {
@@ -240,6 +226,8 @@ export type EditRelatedListSection = {
      *  "3 Positionen"). Omitted: generic "entries" wording. */
     readonly itemNoun?: string;
     readonly pageSize?: number;
+    /** Opt-in table behaviour: remembered state, reset, column picker, density. */
+    readonly table?: ListTableOptions;
     /** Initial sort on mount, applied client-side over the already-loaded rows
      *  (this section has no pager; if the fetch is truncated, `nextCursor !== null`,
      *  the section shows a hint banner that the sort covers only the loaded rows).
@@ -278,8 +266,8 @@ export type EditRelatedListSection = {
     readonly rowActions?: readonly RowAction[];
     /** Layout of the row-action column — see `RowActionMode`. */
     readonly rowActionMode?: RowActionMode;
-    /** Groups rows by the value of a field under collapsible group headers. */
-    readonly groupBy?: RelatedListGroupBy;
+    /** Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action. Adds a checkbox column and a selection bar; without it the list has no checkboxes. */
+    readonly bulkActions?: readonly ListBulkAction[];
     /** Tints rows whose field matches — a declarative rule, not a function, so
      *  the screen definition stays serializable. */
     readonly rowTone?: RelatedListRowTone;

package/dist/screen-entity-edit.js

@@ -1,8 +1,10 @@
-/** Group key of a field value; `collapsedWhen` and row values both go through it. */
+/** Group key of a field value; `collapsedWhen` and server group keys both go through it. */
 export function relatedListGroupKey(value) {
     return value === undefined || value === null ? "" : String(value);
 }
-export function relatedListGroupHeaderLabel(groupBy, groupKey) {
-    const labels = groupBy.labels;
-    return labels !== undefined && Object.hasOwn(labels, groupKey) ? labels[groupKey] : groupBy.label;
+export function relatedListGroupHeaderLabel(grouping, groupKey) {
+    const labels = grouping.labels;
+    return labels !== undefined && Object.hasOwn(labels, groupKey)
+        ? labels[groupKey]
+        : grouping.label;
 }

package/dist/screen-entity-list.d.ts

@@ -4,7 +4,10 @@ import type { IconKey } from "./nav-icon.ts";
 import type { FieldRenderer, PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts";
 import type { ActionFormRedirect } from "./screen-action-form.ts";
 import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
-import type { EditRelatedListSection, ListEmptyStateSpec } from "./screen-entity-edit.ts";
+import type { ListEmptyStateSpec } from "./screen-entity-edit.ts";
+import type { EntityListExpandableRow } from "./screen-expandable-row.ts";
+import type { ListBulkAction } from "./screen-list-bulk.ts";
+import type { ListColumnPin, ListTableOptions } from "./screen-list-table.ts";
 export type ListColumnSpec = string | {
     readonly field: string;
     readonly renderer?: FieldRenderer;
@@ -49,6 +52,16 @@ export type ListColumnSpec = string | {
      *  `md` breakpoint (tables keep it). For columns that only make sense
      *  next to the others, like a sort key. */
     readonly hideOnNarrow?: boolean;
+    /** Start state for the column picker: the column begins hidden and the
+     *  user can show it. Only valid together with `table.columnPicker`. */
+    readonly hidden?: boolean;
+    /** Start pin for the column: it sticks to this edge while the table scrolls
+     *  horizontally. Only valid together with `table.pinning`. */
+    readonly pinned?: ListColumnPin;
+    /** Start width in px. Only valid together with `table.resizing`. */
+    readonly width?: number;
+    /** Smallest width in px the user can resize to. Only valid together with `table.resizing`. */
+    readonly minWidth?: number;
     /** Dashboard list panels only. "bar": field holds a 0..1 fraction, drawn
      *  as bar + percent. "badge": field holds a label, drawn as a pill whose
      *  tone comes from `badgeToneField`. "datetime": field holds an ISO string or
@@ -321,11 +334,6 @@ export type RelatedListToolbarAction = (Extract<ToolbarAction, {
 }> & {
     readonly visible?: FieldCondition;
 });
-/** Expandable area of an `entityList` row: a relatedList of the row's record.
- *  `id` (tab id) and `countField` (tab badge) have no meaning outside a tabs
- *  layout and are therefore omitted. `kind` stays the discriminator so further
- *  expansion kinds can be added without a breaking change. */
-export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField">;
 /** An extra choice on a facet next to the field's own options: a named
  *  bundle of values ("Running" = several statuses) or "no filter" (`values:
  *  []`, e.g. "All"). Chips only. */
@@ -340,8 +348,9 @@ export type EntityListFacetExtraOption = {
 };
 export type EntityListFacetConfig = {
     /** `"select"` (default): dropdown with checkboxes. `"chips"`: one toggle
-     *  chip per option, single choice. */
-    readonly display?: "select" | "chips";
+     *  chip per option, single choice. `"range"`: "from" and "to" inputs on a
+     *  number, decimal, money or bigInt field, sent as `gte`/`lte`. */
+    readonly display?: "select" | "chips" | "range";
     /** Chips show how many rows each option matches (other facets and the
      *  search apply). Counts come from the list query itself, one `limit: 1`
      *  count request per chip. */
@@ -387,6 +396,8 @@ export type EntityListScreenDefinition = {
     readonly rowActions?: readonly RowAction[];
     /** Layout of the row-action column — see `RowActionMode`. */
     readonly rowActionMode?: RowActionMode;
+    /** Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action. Adds a checkbox column and a selection bar; without it the list has no checkboxes. */
+    readonly bulkActions?: readonly ListBulkAction[];
     /** Toolbar actions (list header). "Open Incident", "Schedule Maintenance"
      *  etc. — next to "+ New" if present. Array order = UI order,
      *  primary-style links. */
@@ -403,6 +414,8 @@ export type EntityListScreenDefinition = {
     readonly filter?: ScreenFilter;
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
+    /** Opt-in table behaviour: remembered state, reset, column picker, density. */
+    readonly table?: ListTableOptions;
     readonly defaultSort?: ListSortSpec;
     /** Initial facet selection, per filterable field: option values (string
      *  facets) or a boolean. Applies only while the URL carries no value for

package/dist/screen-expandable-row.d.ts

@@ -0,0 +1,16 @@
+import type { EditRelatedListSection } from "./screen-entity-edit.ts";
+import type { ListTableGrouping } from "./screen-list-table.ts";
+/** Server-side grouping of an expandable row's sub-list: a fixed `field`, no "Group by" choice. */
+export type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoice" | "fields"> & {
+    readonly field: string;
+};
+/** Expandable area of an `entityList` row: a relatedList of the row's record.
+ *  `id` (tab id) and `countField` (tab badge) have no meaning outside a tabs
+ *  layout and are therefore omitted. `kind` stays the discriminator so further
+ *  expansion kinds can be added without a breaking change. `table` takes only
+ *  `grouping`; the other table options belong on the entityList itself. */
+export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "table" | "bulkActions"> & {
+    readonly table?: {
+        readonly grouping?: ExpandableRowGrouping;
+    };
+};

package/dist/screen-expandable-row.js

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

package/dist/screen-list-bulk.d.ts

@@ -0,0 +1,12 @@
+export declare const LIST_BULK_ACTION_KEYS: readonly ["id", "rowAction", "confirm"];
+/** Most rows one selection can hold; the loaded page caps it further. */
+export declare const MAX_BULK_SELECTION = 100;
+/** An action that runs a writeHandler row action once per checkbox-selected row. One `/api/write` per row, so access, validation and audit stay per row. */
+export type ListBulkAction = {
+    /** Stable id, kebab-case, unique among the screen's bulk actions. */
+    readonly id: string;
+    /** Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`. Rows the action's `visible` hides are skipped. */
+    readonly rowAction: string;
+    /** i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`. Without it a `confirm` or `style: "danger"` on the row action still asks once with the default text. */
+    readonly confirm?: string;
+};

package/dist/screen-list-bulk.js

@@ -0,0 +1,3 @@
+export const LIST_BULK_ACTION_KEYS = ["id", "rowAction", "confirm"];
+/** Most rows one selection can hold; the loaded page caps it further. */
+export const MAX_BULK_SELECTION = 100;

package/dist/screen-list-table.d.ts

@@ -0,0 +1,70 @@
+import type { ListAggregateMeasureKind } from "./list-aggregate-types.ts";
+export declare const LIST_TABLE_DENSITIES: readonly ["comfortable", "compact"];
+export type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
+export declare const LIST_COLUMN_PINS: readonly ["left", "right"];
+export type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
+export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals"];
+export declare const LIST_TABLE_GROUPING_KEYS: readonly ["field", "label", "labels", "collapsedWhen", "userChoice", "fields"];
+export declare const LIST_TABLE_TOTAL_KEYS: readonly ["field", "kind"];
+export declare const LIST_TABLE_EXPORT_KEYS: readonly ["xlsx", "maxRows"];
+export declare const DEFAULT_EXPORT_MAX_ROWS = 10000;
+/** Hard cap: the server builds the whole workbook in memory. */
+export declare const MAX_EXPORT_MAX_ROWS = 100000;
+export declare const LIST_TABLE_DENSITY_KEYS: readonly ["default", "userChoice"];
+/** Opt-in table behaviour of a list. Without the block a list renders and behaves exactly as before. */
+export type ListTableOptions = {
+    /** Keeps search, sort, page size, facets and date range for the browser session and restores them when the screen is opened without list parameters in the URL. A link with parameters always wins. */
+    readonly rememberState?: boolean;
+    /** Replaces the facet reset with one button that resets search, sort, page size, facets and date range, and drops the remembered list parameters (column and density choices stay). */
+    readonly resetAll?: boolean;
+    /** Lets the user hide and reorder columns in the view menu. Columns marked `hidden` start hidden. */
+    readonly columnPicker?: boolean;
+    /** Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`. Pinned columns stay sticky while scrolling horizontally. No effect in the card layout below `md`. */
+    readonly pinning?: boolean;
+    /** Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize. `width` and `minWidth` on a column are start values; widths are remembered per session. No effect in the card layout. */
+    readonly resizing?: boolean;
+    /** Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click. Space stays reserved for selection. */
+    readonly keyboardNavigation?: boolean;
+    readonly density?: {
+        /** Row density on first visit. Default "comfortable". */
+        readonly default?: ListTableDensity;
+        /** Shows the density choice in the view menu and remembers it per session. */
+        readonly userChoice?: boolean;
+    };
+    /** Shows an export button; the server reads the whole filtered list (not just the visible page). */
+    readonly export?: ListTableExportOptions;
+    /** Server-side grouping: group headers with count and the `totals` measures over all matching rows; each open group loads its own rows. */
+    readonly grouping?: ListTableGrouping;
+    /** Footer row under the rows, computed by the server over all rows matching the current filters and search. In grouped mode the same measures show in each group header. */
+    readonly totals?: readonly ListTableTotal[];
+};
+export type ListTableGrouping = {
+    /** Start grouping. Without it the list starts ungrouped and the user picks from `fields`. */
+    readonly field?: string;
+    /** Groups whose key equals this start collapsed and load no rows until opened. */
+    readonly collapsedWhen?: string | number | boolean | null;
+    /** i18n key of the group header. Placeholders: `{count}` rows in the group, `{value}` the group's value. Default: the value itself. */
+    readonly label?: string;
+    /** Header i18n key per group key (as string), overriding `label`. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Shows "Group by" in the view menu (needs `fields` or `field`) and remembers the choice per session. */
+    readonly userChoice?: boolean;
+    /** Fields offered under "Group by"; `field` is always offered. */
+    readonly fields?: readonly string[];
+};
+export type ListTableTotal = {
+    readonly field: string;
+    /** sum and avg on number, decimal, money and bigInt; min and max also on date and timestamp. Money is shown per currency, never added across currencies. */
+    readonly kind: ListAggregateMeasureKind;
+};
+export type ListTableExportOptions = {
+    readonly xlsx: true;
+    /** Export is refused above this many rows. Default 10000, hard cap 100000. Encrypted, sensitive and virtual columns are never written. */
+    readonly maxRows?: number;
+};
+/** One `table` block for every entityList, projectionList and relatedList of the bundled features. A screen's own `table` keys win per key. `grouping` and `totals` are not accepted here. */
+export type BundledListsOptions = {
+    readonly table: ListTableOptions;
+    /** Pins the first column left on every bundled list where no column is pinned. Needs `table.pinning: true`. */
+    readonly pinFirstColumn?: boolean;
+};

package/dist/screen-list-table.js

@@ -0,0 +1,28 @@
+export const LIST_TABLE_DENSITIES = ["comfortable", "compact"];
+export const LIST_COLUMN_PINS = ["left", "right"];
+export const LIST_TABLE_OPTION_KEYS = [
+    "rememberState",
+    "resetAll",
+    "columnPicker",
+    "density",
+    "pinning",
+    "resizing",
+    "keyboardNavigation",
+    "export",
+    "grouping",
+    "totals",
+];
+export const LIST_TABLE_GROUPING_KEYS = [
+    "field",
+    "label",
+    "labels",
+    "collapsedWhen",
+    "userChoice",
+    "fields",
+];
+export const LIST_TABLE_TOTAL_KEYS = ["field", "kind"];
+export const LIST_TABLE_EXPORT_KEYS = ["xlsx", "maxRows"];
+export const DEFAULT_EXPORT_MAX_ROWS = 10000;
+/** Hard cap: the server builds the whole workbook in memory. */
+export const MAX_EXPORT_MAX_ROWS = 100000;
+export const LIST_TABLE_DENSITY_KEYS = ["default", "userChoice"];

package/dist/screen-projection.d.ts

@@ -4,6 +4,8 @@ import type { PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts
 import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
 import type { EditLayout, ListEmptyStateSpec } from "./screen-entity-edit.ts";
 import type { ListColumnSpec, ListPaginationMode, ListSortSpec, RowAction, RowActionMode, RowFieldExtractor, ScreenFilter, ToolbarAction } from "./screen-entity-list.ts";
+import type { ListBulkAction } from "./screen-list-bulk.ts";
+import type { ListTableOptions } from "./screen-list-table.ts";
 export type ListFacetSpec = {
     readonly field: string;
     readonly type: "select";
@@ -71,9 +73,13 @@ export type ProjectionListScreenDefinition = {
     readonly rowActions?: readonly RowAction[];
     /** Layout of the row-action column — see `RowActionMode`. */
     readonly rowActionMode?: RowActionMode;
+    /** Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action. Adds a checkbox column and a selection bar; without it the list has no checkboxes. */
+    readonly bulkActions?: readonly ListBulkAction[];
     readonly toolbarActions?: readonly ToolbarAction[];
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
+    /** Opt-in table behaviour: remembered state, reset, column picker, density. */
+    readonly table?: ListTableOptions;
     readonly defaultSort?: ListSortSpec;
     /** Replaces the default empty-list title/hint; the create button stays when the list can create. */
     readonly emptyState?: ListEmptyStateSpec;

package/dist/screen.d.ts

@@ -72,8 +72,11 @@ export interface FieldFormatRegistry {
     };
     /** FileRef id (or id array) as a download link with the file name. On a
      *  read-only detail field it renders a file list with download links and an
-     *  inline preview for PDFs; elsewhere the raw value is shown. */
-    file: object;
+     *  inline preview for PDFs; elsewhere the raw value is shown.
+     *  `previewOpenByDefault` opens the first file's PDF preview initially. */
+    file: {
+        readonly previewOpenByDefault?: boolean;
+    };
 }
 export type FormatSpec = {
     [K in keyof FieldFormatRegistry]: {
@@ -111,7 +114,12 @@ export type { ActionFormFooterAction, ActionFormLoad, ActionFormRedirect, Action
 export type { ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, SecretsEditScreenDefinition, SecretsEditSection, } from "./screen-custom-config.ts";
 export type { DashboardChartKind, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardChartTone, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelGate, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardStatTone, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardTimeRangeDefinition, DashboardValueFormat, } from "./screen-dashboard.ts";
 export { DASHBOARD_MIN_REFRESH_SECONDS, DASHBOARD_STAT_TONES } from "./screen-dashboard.ts";
-export type { EditExtensionSection, EditFieldGroup, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityWriteExcludedFields, FieldAffix, FieldFillAction, FormWidth, ListEmptyStateSpec, RelatedListGroupBy, RelatedListRowTone, } from "./screen-entity-edit.ts";
+export type { EditExtensionSection, EditFieldGroup, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityWriteExcludedFields, FieldAffix, FieldFillAction, FormWidth, ListEmptyStateSpec, RelatedListRowTone, } from "./screen-entity-edit.ts";
 export { relatedListGroupHeaderLabel, relatedListGroupKey } from "./screen-entity-edit.ts";
-export type { EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListPaginationMode, ListSortDir, ListSortSpec, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenFilter, ScreenFilterOp, ToolbarAction, } from "./screen-entity-list.ts";
+export type { EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListPaginationMode, ListSortDir, ListSortSpec, RelatedListToolbarAction, RowAction, RowActionClientAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenFilter, ScreenFilterOp, ToolbarAction, } from "./screen-entity-list.ts";
+export type { EntityListExpandableRow, ExpandableRowGrouping } from "./screen-expandable-row.ts";
+export type { ListBulkAction } from "./screen-list-bulk.ts";
+export { LIST_BULK_ACTION_KEYS, MAX_BULK_SELECTION } from "./screen-list-bulk.ts";
+export type { BundledListsOptions, ListColumnPin, ListTableDensity, ListTableExportOptions, ListTableGrouping, ListTableOptions, ListTableTotal, } from "./screen-list-table.ts";
+export { DEFAULT_EXPORT_MAX_ROWS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_EXPORT_MAX_ROWS, } from "./screen-list-table.ts";
 export type { ListFacetSpec, MetricNavigate, MetricSpec, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, } from "./screen-projection.ts";

package/dist/screen.js

@@ -1,2 +1,4 @@
 export { DASHBOARD_MIN_REFRESH_SECONDS, DASHBOARD_STAT_TONES } from "./screen-dashboard.js";
 export { relatedListGroupHeaderLabel, relatedListGroupKey } from "./screen-entity-edit.js";
+export { LIST_BULK_ACTION_KEYS, MAX_BULK_SELECTION } from "./screen-list-bulk.js";
+export { DEFAULT_EXPORT_MAX_ROWS, LIST_COLUMN_PINS, LIST_TABLE_DENSITIES, LIST_TABLE_DENSITY_KEYS, LIST_TABLE_EXPORT_KEYS, LIST_TABLE_GROUPING_KEYS, LIST_TABLE_OPTION_KEYS, LIST_TABLE_TOTAL_KEYS, MAX_EXPORT_MAX_ROWS, } from "./screen-list-table.js";

package/dist/tenant-db-types.d.ts

@@ -58,6 +58,11 @@ type TenantDbNonWrites = {
     /** Postgres `now()`; inside a transaction this is the transaction start. */
     databaseNow(): Promise<Date>;
     aggregate(table: SchemaTable | EntityTableMeta, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
+    upsert<T = Record<string, unknown>>(table: WritableTable, values: Record<string, unknown>, options: TenantDbUpsertOptions): Promise<T | undefined>;
+};
+export type TenantDbUpsertOptions = {
+    readonly conflictTarget: readonly string[];
+    readonly update?: Record<string, unknown>;
 };
 export type TenantDb = TenantDbNonWrites & TenantDbWrites<WritableTable>;
 export type ExecutorManagedTenantDb = TenantDbNonWrites & TenantDbWrites<EntityTableMeta> & ExecutorManagedWriteCapability;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.388.0",
+  "version": "0.389.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -178,6 +178,10 @@
       "types": "./dist/feature.d.ts",
       "default": "./dist/feature.js"
     },
+    "./feature-registrar": {
+      "types": "./dist/feature-registrar.d.ts",
+      "default": "./dist/feature-registrar.js"
+    },
     "./fields": {
       "types": "./dist/fields.d.ts",
       "default": "./dist/fields.js"
@@ -284,18 +288,18 @@
     }
   },
   "devDependencies": {
+    "bun-types": "^1.4.4",
     "hono": "^4.13.1",
-    "postgres": "npm:@bender0oo0/postgres@3.4.9-kumiko.2",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3",
     "ioredis": "^5.10.1"
   },
   "peerDependencies": {
     "hono": "^4.13.1",
-    "postgres": "^3.4.9-0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3",
-    "ioredis": "^5.10.1"
+    "ioredis": "^5.10.1",
+    "bun-types": "^1.4.4"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -461,6 +465,10 @@
         "types": "./dist/feature.d.ts",
         "default": "./dist/feature.js"
       },
+      "./feature-registrar": {
+        "types": "./dist/feature-registrar.d.ts",
+        "default": "./dist/feature-registrar.js"
+      },
       "./fields": {
         "types": "./dist/fields.d.ts",
         "default": "./dist/fields.js"

package/src/changes.json

@@ -1,4 +1,17 @@
 [
+  {
+    "version": "0.389.0",
+    "type": "breaking",
+    "title": "DbConnection, DbTx and PgClient are Bun.SQL types and postgres is no longer a peer dependency",
+    "detail": "DbConnection is SQL | RawDbClient, DbTx is TransactionSQL | RawDbClient and PgClient is SQL from the bun module, so the package type-checks against bun-types instead of postgres. The postgres peer dependency is removed.",
+    "migration": "Remove postgres from your dependencies unless your own code imports it. Annotations that named postgres.Sql or postgres.TransactionSql for framework handles become SQL and TransactionSQL from \"bun\", or the DbConnection and DbTx aliases. Manual migration, there is no codemod."
+  },
+  {
+    "version": "0.389.0",
+    "type": "improvement",
+    "title": "Config validators can read a key's cascade",
+    "detail": "ConfigValidateContext gains readCascade(qualifiedKey), which returns the full cascade of any registered key from the writing tenant and user. Unknown keys throw."
+  },
   {
     "version": "0.386.0",
     "type": "improvement",