@cosmicdrift/kumiko-types 0.386.0 → 0.388.0

package/LICENSE

@@ -1,57 +1,21 @@
-Business Source License 1.1
-
-Parameters
-
-Licensor:             Marc Frost
-
-Licensed Work:        @cosmicdrift/kumiko-types
-                      The Licensed Work is © 2026 Marc Frost.
-
-Additional Use Grant: 
-You may use the Licensed Work in production for any purpose, including 
-commercially, EXCEPT for the Restricted Use. 
-
-"Restricted Use" is defined as using the Licensed Work to provide a platform 
-or service to third parties that allows them to host, deploy, or run their 
-own applications built with the Licensed Work. This includes, but is not 
-limited to: managed hosting services, software-as-a-service (SaaS) platforms, 
-platform-as-a-service (PaaS), developer platforms, or any multi-tenant 
-managed offering of the Licensed Work.
-
-This restriction does not apply to the Licensor, any entity controlled by, 
-controlling, or under common control with the Licensor ("Affiliates"), or 
-contractors acting on their behalf. The Licensor remains free to use the 
-Licensed Work for any purpose, including for the operation of kumiko.rocks.
-
-Change Date:          2030-05-05
-Change License:       Apache License, Version 2.0
-
-
-Terms
-
-The Licensor hereby grants you the right to copy, modify, create derivative works, 
-redistribute, and make non-production use of the Licensed Work. The Licensor may 
-make an Additional Use Grant, above, permitting limited production use.
-
-Effective on the Change Date, or the fourth anniversary of the first publicly 
-available distribution of the Licensed Work under this License, whichever comes 
-first, this License will convert to the Change License.
-
-This Business Source License governs use of the Licensed Work in all cases, except 
-as to any use that is explicitly granted in the Additional Use Grant above or 
-under the Change License after the Change Date.
-
-If your use of the Licensed Work does not comply with the requirements of this 
-License, you must cease use of the Licensed Work immediately.
-
-All copies of the Licensed Work, and all derivative works thereof, must include 
-this License.
-
-This License does not grant you any right, title, or interest in any trademark, 
-logo, or branding of the Licensor, except as required to comply with this License.
-
-TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN 
-“AS IS” BASIS. LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 
-WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, 
-TITLE, AND NON-INFRINGEMENT. IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES 
-ARISING OUT OF OR RELATED TO THIS LICENSE OR THE USE OF THE LICENSED WORK.
+MIT License
+
+Copyright (c) 2026 Marc Frost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @cosmicdrift/kumiko-types
 
-[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](../../LICENSE)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 
 Framework type definitions for Kumiko — `FeatureDefinition`, boot-check types,

package/dist/config.d.ts

@@ -50,7 +50,7 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
      *  encrypted under the DEK of the scope actually written to (tenant-row
      *  → tenant subject, user-row → user subject). Only on `type: "text"`,
      *  `scope !== "system"` (no subject there), and mutually exclusive with
-     *  `encrypted` (kumiko-platform#231/#459). */
+     *  `encrypted`. */
     readonly piiEncrypted?: boolean;
     readonly options?: readonly string[];
     /** Only on `type: "select"`: loads the options from this query (QN), contract
@@ -231,6 +231,8 @@ export type NotificationTemplateMeta = {
     readonly layoutSlug?: string;
     readonly category?: "transactional" | "marketing";
     readonly sender?: string;
+    readonly senderName?: string;
+    readonly replyTo?: string;
 };
 export type NotificationTemplateBody = {
     readonly body: string;

package/dist/define-handler.d.ts

@@ -14,6 +14,9 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
@@ -31,6 +34,9 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
+    readonly rateLimitCost?: (payload: z.infer<TSchema>) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;

package/dist/entity-table-meta-types.js

@@ -2,6 +2,6 @@
 // Plain-data types for EntityTableMeta — split from the runtime
 // (deriveEntityTableMeta, resolveTableName, defineUnmanagedTable) in
 // entity-table-meta.ts. Prep step for the types-only package extraction
-// (#1283) — this file must have ONLY `import type`, no value imports
+// — this file must have ONLY `import type`, no value imports
 // (crypto/DB deps).
 export {};

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

@@ -3,6 +3,7 @@ import type { EntityDefinition } from "./fields.ts";
 import type { SessionUser, WriteResult } from "./handlers.ts";
 import type { DeleteContext, SaveContext } from "./hooks.ts";
 import type { EntityId, TenantId } from "./identifiers.ts";
+import type { ListAggregatePayload, ListAggregateResult } from "./list-aggregate-types.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { TenantDb } from "./tenant-db-types.ts";
 export type ParentVisibilityOption = {
@@ -21,6 +22,38 @@ export type LockGuardOption = {
     readonly unsafeSkipLockGuard?: boolean;
     readonly writePurpose?: WritePurpose;
 };
+export type ListRuntimeOptions = {
+    readonly searchAdapter?: SearchAdapter;
+    readonly includeDeleted?: boolean;
+    readonly referenceSearch?: {
+        readonly fields: ReadonlyArray<{
+            readonly fieldName: string;
+            readonly targetEntityName: string;
+            readonly labelField: string;
+        }>;
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+    };
+    readonly referenceSort?: {
+        readonly fields: ReadonlyArray<{
+            readonly fieldName: string;
+            readonly targetEntityName: string;
+            readonly labelField: string;
+        }>;
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+    };
+    readonly parentVisibility?: ParentVisibilityOption;
+};
+type ListFilterOption = {
+    readonly field: string;
+    readonly op: "eq" | "ne" | "lt" | "gt" | "lte" | "gte" | "in";
+    readonly value: unknown;
+};
+export type ListAggregateRequest = {
+    readonly search?: string | undefined;
+    readonly filter?: ListFilterOption | undefined;
+    readonly filters?: readonly ListFilterOption[] | undefined;
+    readonly aggregate: ListAggregatePayload;
+};
 export type EventStoreExecutor<Row extends Record<string, unknown> = Record<string, unknown>> = {
     create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         preSave?: PreSaveRunner;
@@ -64,36 +97,19 @@ export type EventStoreExecutor<Row extends Record<string, unknown> = Record<stri
             readonly value: unknown;
         }> | undefined;
     }, user: SessionUser, db: TenantDb, 
-    /** Tier 2.7e audit fix: per-call SearchAdapter override. When the
+    /** Per-call SearchAdapter override. When the
      *  executor didn't get a SearchAdapter via Options at build time
      *  (defaultEntityQueryHandler path), the caller (handler) can pass
      *  one from ctx.searchAdapter here at runtime.
      *  options.searchAdapter (build-time) wins — the runtime override
      *  is the fallback for the default wrapper. */
-    runtimeOptions?: {
-        readonly searchAdapter?: SearchAdapter;
-        readonly includeDeleted?: boolean;
-        readonly referenceSearch?: {
-            readonly fields: ReadonlyArray<{
-                readonly fieldName: string;
-                readonly targetEntityName: string;
-                readonly labelField: string;
-            }>;
-            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-        };
-        readonly referenceSort?: {
-            readonly fields: ReadonlyArray<{
-                readonly fieldName: string;
-                readonly targetEntityName: string;
-                readonly labelField: string;
-            }>;
-            readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
-        };
-        readonly parentVisibility?: ParentVisibilityOption;
-    }) => Promise<CursorResult<Row>>;
+    runtimeOptions?: ListRuntimeOptions) => Promise<CursorResult<Row>>;
+    /** Groups and measures over the same WHERE as `list` (filters, search, ownership, field-read gates); paging and sort are ignored. */
+    aggregate: (payload: ListAggregateRequest, user: SessionUser, db: TenantDb, runtimeOptions?: ListRuntimeOptions) => Promise<ListAggregateResult>;
     detail: (payload: {
         id: EntityId;
     }, user: SessionUser, db: TenantDb, options?: {
         readonly parentVisibility?: ParentVisibilityOption;
     }) => Promise<Row | null>;
 };
+export {};

package/dist/event-store-types.js

@@ -3,5 +3,5 @@ export function isPersonalDataGated(origin) {
 }
 // Stamped when an append runs outside any attributed scope (seed scripts,
 // tests, direct event-store use). A distinct value, not an omission —
-// omitted would be indistinguishable from a pre-#3043 row.
+// omitted would be indistinguishable from an earlier row.
 export const UNATTRIBUTED_ORIGIN = "unknown";

package/dist/event-type-map.js

@@ -1,18 +1,18 @@
-// Cross-Feature Compile-Time-Type-Map.
+// Cross-Feature Compile-Time Type Map.
 //
-// Zweck: ctx.appendEvent / ctx.queryProjection / dispatcher.write gegen ein
-// statisch bekanntes Schema-Bild prüfen, statt erst zur Boot- oder Runtime
-// (zod-validate) zu scheitern. Designer/AI-Layer profitiert dadurch sofort:
-// Autocomplete kennt alle Event-Typen aller geladenen Features, payload-
-// Shape-Mismatches werden im Editor angezeigt, nicht erst beim Boot.
+// Purpose: check ctx.appendEvent / ctx.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
+// editor rather than only at boot.
 //
-// Befüllung erfolgt per Feature über `declare module "@cosmicdrift/kumiko-framework/engine"`
-// — entweder hand-geschrieben (für stabile Frameworks-Internals) oder vom
-// Codegen-Skript erzeugt (für apps/bundled-features). Empty defaults sind
-// kein Bug: ein Feature ohne Augmentation ist runtime-pluggable und nutzt
-// die Fallback-Overload mit `unknown` payload.
+// Each feature populates the map through `declare module "@cosmicdrift/kumiko-framework/engine"`
+// — either manually (for stable framework internals) or through the code-generation
+// script (for apps/bundled-features). Empty defaults are not a bug: a feature without
+// augmentation is runtime-pluggable and uses the fallback overload with `unknown`
+// payload.
 //
-// Pattern für hand-geschriebene Augmentation am File-Top:
+// Pattern for a manually written augmentation at the top of the file:
 //
 //   declare module "@cosmicdrift/kumiko-framework/engine" {
 //     interface KumikoEventTypeMap {

package/dist/feature.d.ts

@@ -79,7 +79,7 @@ export type StoreTableOptions = {
     /** Direct-write stores skip the executor, so the executor's PII
      *  encryption never runs for them — a feature whose meta carries
      *  piiSubjectFields must encrypt those fields itself before every
-     *  insert/update and declare that here, or boot fails (#820). */
+     *  insert/update and declare that here, or boot fails. */
     readonly piiEncryptedOnWrite?: true;
 };
 /** Per-feature store-table registration. `meta` is the `EntityTableMeta`
@@ -152,17 +152,17 @@ export type FeatureDefinition = {
     readonly extensionSelectors: readonly ExtensionSelectorDef[];
     /**
      * Cross-feature API names this feature exposes via `r.exposesApi(name)`.
-     * Pure Marker-Deklaration — die echte Implementation wird als
-     * Query-/Write-Handler unter dem QN-Pattern registriert (z.B.
-     * `compliance-profiles:query:effective-profile`). Boot-Validator prüft
-     * dass jedes `r.usesApi(name)` einen passenden Exposer hier findet —
-     * Tippfehler oder Drop-Refactorings werden zu Boot-Fail statt Runtime-Crash.
+     * Pure marker declaration — the implementation is registered separately as
+     * a query or write handler under the QN pattern (for example,
+     * `compliance-profiles:query:effective-profile`). The boot validator checks
+     * that every `r.usesApi(name)` finds a matching exposer, so typos or dropped
+     * refactors fail at boot instead of causing a runtime crash.
      */
     readonly exposedApis: ReadonlySet<string>;
     /**
-     * Cross-feature API names this feature calls. Pflicht-Boot-Check:
-     * jeder Eintrag muss in `exposedApis` irgendeines Features auftauchen
-     * UND das Provider-Feature muss in requires/optionalRequires sein.
+     * Cross-feature API names this feature calls. The boot check requires every
+     * entry to appear in some feature's `exposedApis` and the provider feature
+     * to be listed in requires/optionalRequires.
      */
     readonly usedApis: ReadonlySet<string>;
     /**
@@ -406,30 +406,30 @@ export type FeatureRegistrar<TFeature extends string = string> = {
         readonly panels?: readonly ExtensionSelectorPanel[];
     }): void;
     /**
-     * Marker-Deklaration: dieses Feature stellt eine Cross-Feature-API
-     * unter dem genannten Namen bereit. Die eigentliche Implementation
-     * wird separat als Query- oder Write-Handler unter dem QN-Pattern
-     * registriert; `r.exposesApi` ist reine Boot-Check-Surface.
+     * 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.
      *
-     * Boot-Validator prüft, dass jedes `r.usesApi(name)` einen passenden
-     * Exposer findet, dass das Exposer-Feature in requires/optionalRequires
-     * gelisted ist und dass kein API-Name doppelt exposed wird.
+     * 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",
-     *     // ... echte Implementation
+     *     // ... actual implementation
      *   });
      * });
      * ```
      */
     exposesApi(apiName: string): void;
     /**
-     * Declares that this feature calls a cross-feature API. Boot-Validator
-     * checkt dass irgendein anderes Feature `r.exposesApi(apiName)` macht
-     * und dass dieses Feature `r.requires/optionalRequires` darauf hat.
+     * 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) => {
@@ -447,9 +447,9 @@ export type FeatureRegistrar<TFeature extends string = string> = {
      * 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,
-     * kumiko-enterprise#229 — a UserData feature was written but never
-     * mounted, and nothing caught it at boot):
+     * 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) => {