@cosmicdrift/kumiko-types 0.354.1 → 0.356.0

package/dist/define-handler.d.ts

@@ -9,6 +9,8 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly access: AccessRule;
     readonly description?: string;
     readonly agent?: AgentHandlerHints;
+    /** Set by the entity convention create/update handlers; see WriteHandlerDef.excludedFields. */
+    readonly excludedFields?: readonly string[];
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];

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

@@ -2,22 +2,25 @@ import type { CursorResult } from "./cursor-types.js";
 import type { EntityDefinition } from "./fields.js";
 import type { SessionUser, WriteResult } from "./handlers.js";
 import type { DeleteContext, SaveContext } from "./hooks.js";
-import type { EntityId } from "./identifiers.js";
+import type { EntityId, TenantId } from "./identifiers.js";
 import type { SearchAdapter } from "./search-adapter.js";
 import type { TenantDb } from "./tenant-db-types.js";
 export type ParentVisibilityOption = {
     readonly entities: ReadonlyMap<string, EntityDefinition>;
 };
 export type PreSaveRunner = (changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
+export type StreamTenantOption = {
+    readonly streamTenantId?: TenantId | undefined;
+};
 export type EventStoreExecutor = {
-    create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: {
+    create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         preSave?: PreSaveRunner;
     }) => Promise<WriteResult<SaveContext>>;
     update: (payload: {
         id: EntityId;
         version?: number | undefined;
         changes: Record<string, unknown>;
-    }, user: SessionUser, db: TenantDb, options?: {
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & {
         skipOptimisticLock?: boolean;
         skipUnchanged?: boolean;
         preSave?: PreSaveRunner;
@@ -25,13 +28,13 @@ export type EventStoreExecutor = {
     }) => Promise<WriteResult<SaveContext>>;
     delete: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<DeleteContext>>;
     forget: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<DeleteContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<DeleteContext>>;
     restore: (payload: {
         id: EntityId;
-    }, user: SessionUser, db: TenantDb) => Promise<WriteResult<SaveContext>>;
+    }, user: SessionUser, db: TenantDb, options?: StreamTenantOption) => Promise<WriteResult<SaveContext>>;
     list: (payload: {
         cursor?: string | undefined;
         limit?: number | undefined;

package/dist/fields.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
 import type { VariantSpec } from "./derivatives-types.js";
+import type { EventUpcastCtx } from "./handlers.js";
 import type { OwnershipMap } from "./ownership.js";
 import type { EntityTenancy } from "./tenancy-brand.js";
 export type FieldAccess = {
@@ -713,6 +714,11 @@ export type ParentRefDef = {
      *  registered entity is a candidate, which also widens the read-gate's SQL. */
     readonly allowedTypes?: readonly string[];
 };
+export type EntityEventMigration = {
+    readonly fromVersion: number;
+    readonly toVersion: number;
+    readonly transform: (fields: Readonly<Record<string, unknown>>, ctx: EventUpcastCtx) => Record<string, unknown> | Promise<Record<string, unknown>>;
+};
 export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTenancy = EntityTenancy> = {
     readonly table?: string;
     readonly fields: F;
@@ -725,6 +731,10 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
      *  only for genuinely tenant-independent aggregates like `user`. The first
      *  event (create) is what's routed; updates resolve the stream tenant upstream. */
     readonly systemStream?: boolean;
+    /** Schema version stamped on every lifecycle event (default 1, integer 1..999). Bump it together with a step in `eventMigrations`. */
+    readonly eventVersion?: number;
+    /** One step per version, fromVersion → fromVersion+1. Transforms run on row-shaped field records; the record may be partial, touch only keys that are present. */
+    readonly eventMigrations?: readonly EntityEventMigration[];
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;
     /** Allowed state transitions per field. Boot validates against select options. */

package/dist/handlers.d.ts

@@ -178,10 +178,15 @@ export type EscapeHatchUseEvent = {
     readonly reason: string;
     readonly tenantId: TenantId;
     readonly actor: string;
+    readonly caller?: string;
     readonly target?: EscapeHatchTarget;
 };
 export type EscapeHatchAuditSink = (event: EscapeHatchUseEvent) => Promise<void>;
 export type EscapeHatchReporter = (kind: EscapeHatchKind, reason: string, target?: EscapeHatchTarget) => void;
+export type TenantWriteTarget = {
+    readonly db: TenantDb;
+    readonly streamTenantId: TenantId | undefined;
+};
 type SharedContextFields = {
     readonly redis?: Redis;
     readonly cacheSync?: CacheSyncBus;
@@ -196,6 +201,15 @@ type SharedContextFields = {
      * the config feature wired its accessor factory.
      */
     readonly configFor?: (tenantId: TenantId) => ConfigAccessor;
+    /**
+     * Write target for ANOTHER tenant: a tenant-mode db bound to it plus the
+     * `streamTenantId` to hand the executor, so the event actor stays the
+     * operator. Cross-tenant calls throw AccessDeniedError unless the caller is
+     * SystemAdmin (the tenantIdOverride gate); the caller's own tenant needs no
+     * privilege and yields `streamTenantId: undefined`. Write handlers only;
+     * absent for r.systemScope() handlers and without a db.
+     */
+    readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.js").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.js").RateLimitResolver;
@@ -534,6 +548,9 @@ export type WriteHandlerDef = {
     readonly access: AccessRule;
     readonly description?: string;
     readonly agent?: AgentHandlerHints;
+    /** Fields a generic create/update handler never writes (`excludeFields`).
+     *  Set only when non-empty; the renderer and the agent manifest read it from here. */
+    readonly excludedFields?: readonly string[];
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     /** Per-payload-field limits, e.g. per recipient address. Complements

package/dist/screen.d.ts

@@ -1205,6 +1205,10 @@ export type EditLayout = {
         };
     };
 };
+export type EntityWriteExcludedFields = {
+    readonly create?: readonly string[];
+    readonly update?: readonly string[];
+};
 export type EntityEditScreenDefinition = {
     readonly id: string;
     readonly type: "entityEdit";
@@ -1228,6 +1232,10 @@ export type EntityEditScreenDefinition = {
      *  screen — the only URL query keys the create form prefills. An authored
      *  value is overwritten. */
     readonly urlPrefillFields?: readonly string[];
+    /** Derived by buildAppSchema from the entity's create/update write handlers
+     *  (`excludeFields`): create hides these fields, update shows them read-only.
+     *  An authored value is overwritten. */
+    readonly writeExcludedFields?: EntityWriteExcludedFields;
     readonly entity: string;
     /** Entity field whose value names the loaded record in the header breadcrumb (edit mode only). */
     readonly recordTitleField?: string;
@@ -1291,16 +1299,24 @@ export type EntityEditScreenDefinition = {
      *  das `mask.title`-Label des Config-Keys. Fehlt ein Eintrag, gilt die
      *  Konvention. */
     readonly fieldLabels?: Readonly<Record<string, string>>;
-    /** Header action buttons. Reuses `RowAction` — analogous to
+    /** Record actions. Reuses `RowAction` — analogous to
      *  `ProjectionDetailScreenDefinition.actions` (the loaded record stands
      *  in for the "row"). `rowClick` has no target here and is rejected by
      *  the boot-validator, same as on projectionDetail. Not rendered in
      *  create mode — every action targets an existing record, which the
-     *  create branch doesn't have yet. */
-    readonly actions?: readonly RowAction[];
+     *  create branch doesn't have yet. By default an action renders with the
+     *  secondary form actions (footer, next to copy-link/delete/cancel);
+     *  `placement: "menu"` moves it into the header "…" menu, ahead of
+     *  copy-link/delete. Without a header menu (drawer, card form, shell
+     *  without a header slot) a "menu" action falls back to inline. */
+    readonly actions?: readonly EntityEditAction[];
     readonly slots?: ScreenSlots;
     readonly access?: AccessRule;
 };
+export type EntityEditActionPlacement = "inline" | "menu";
+export type EntityEditAction = RowAction & {
+    readonly placement?: EntityEditActionPlacement;
+};
 export type ActionFormScreenDefinition = {
     readonly id: string;
     readonly type: "actionForm";

package/dist/snapshot-types.d.ts

@@ -10,4 +10,5 @@ export type LoadAggregateWithSnapshotOptions = {
     readonly upcastEvent?: (event: StoredEvent) => Promise<StoredEvent>;
     readonly snapshotEvery?: number;
     readonly snapshotVersion?: number;
+    readonly entityEventVersionOf?: (aggregateType: string) => number | undefined;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.354.1",
+  "version": "0.356.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",