@cosmicdrift/kumiko-types 0.363.0 → 0.365.0

package/dist/cache-sync-types.d.ts

@@ -1,5 +1,8 @@
+export type CacheSyncPublishOptions = {
+    readonly remoteOnly?: boolean;
+};
 export type CacheSyncBus = {
-    publish(topic: string, message: unknown): void;
+    publish(topic: string, message: unknown, options?: CacheSyncPublishOptions): void;
     subscribe(topic: string, listener: (message: unknown) => void): () => void;
     onResync(listener: () => void): () => void;
 };

package/dist/config.d.ts

@@ -30,7 +30,7 @@ export type ConfigValidateContext = {
     readonly scope: ConfigScope;
     readonly tenantId: TenantId;
     readonly userId: string | null;
-    readonly db: DbConnection | TenantDb;
+    readonly db: TenantDb;
 };
 export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
@@ -193,6 +193,9 @@ export type TemplateScalarVariableDef = (TemplateVariableCommon & {
 }) | (TemplateVariableCommon & {
     readonly type: "link";
     readonly example?: string;
+}) | (TemplateVariableCommon & {
+    readonly type: "richText";
+    readonly example?: string;
 }) | (TemplateVariableCommon & {
     readonly type: "money";
     readonly example?: number | {

package/dist/db-connection.d.ts

@@ -11,4 +11,9 @@ export type DbTx = postgres.TransactionSql<Record<string, unknown>> | RawDbClien
 export type DbRunner = DbConnection | DbTx;
 export type DbRow = Record<string, unknown>;
 export type PgClient = ReturnType<typeof postgres>;
-export type PgListenClient = ReturnType<typeof postgres>;
+export type PgListenSubscription = {
+    unlisten(): Promise<void>;
+};
+export type PgListenClient = {
+    listen(channel: string, onnotify: (payload: string) => void, onlisten?: () => void): Promise<PgListenSubscription>;
+};

package/dist/define-handler.d.ts

@@ -1,9 +1,9 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
 import type { KumikoEventTypeMap } from "./event-type-map.js";
-import type { AccessRule, AgentHandlerHints, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, PreTransactionReservation, QueryEvent, RateLimitDeclaration, WriteEvent, WriteResult } from "./handlers.js";
+import type { AccessRule, AgentHandlerHints, BeforeTransactionPhase, EscapeHatchDeclaration, HandlerContext, PayloadRateLimitOption, PreparedWriteEvent, PreTransactionReservation, QueryEvent, RateLimitDeclaration, WriteHandlerTransactionMode, WriteResult } from "./handlers.js";
 import type { PipelineDef } from "./step.js";
-export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+export type WriteHandlerDefinition<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined> = {
     readonly name: TName;
     readonly schema: TSchema;
     readonly access: AccessRule;
@@ -16,11 +16,13 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
     readonly tenantlessAnonymous?: boolean;
-    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly transaction?: WriteHandlerTransactionMode;
+    readonly handler: (event: PreparedWriteEvent<z.infer<TSchema>, TPrepared>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
 };
-export type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap> = {
+export type WriteHandlerInput<TName extends string = string, TSchema extends ZodType = ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined> = {
     readonly name: TName;
     readonly schema: TSchema;
     readonly access: AccessRule;
@@ -31,9 +33,11 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
     readonly escapeHatch?: EscapeHatchDeclaration;
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    readonly beforeTransaction?: BeforeTransactionPhase<z.infer<TSchema>, TPrepared>;
     readonly tenantlessAnonymous?: boolean;
+    readonly transaction?: WriteHandlerTransactionMode;
 } & ({
-    readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
+    readonly handler: (event: PreparedWriteEvent<z.infer<TSchema>, TPrepared>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: never;
 } | {
     readonly perform: PipelineDef<z.infer<TSchema>, TData>;

package/dist/feature.d.ts

@@ -4,6 +4,7 @@ import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef
 import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { EntityTableMeta } from "./entity-table-meta-types.js";
+import type { KumikoEventTypeMap } from "./event-type-map.js";
 import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.js";
 import type { EntityDefinition } from "./fields.js";
 import type { AccessRule, AgentHandlerHints, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, PayloadRateLimitOption, QualifiedEventName, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef, WriteHandlerFn } from "./handlers.js";
@@ -234,7 +235,7 @@ export type FeatureRegistrar<TFeature extends string = string> = {
         readonly name: string;
     } & EntityDefinition): EntityRef;
     crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
-    writeHandler<TName extends string, TSchema extends ZodType>(def: WriteHandlerDefinition<TName, TSchema>): HandlerRef;
+    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
     writeHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: WriteHandlerFn<z.infer<TSchema>>, options: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;

package/dist/fields.d.ts

@@ -750,7 +750,8 @@ export type EntityDefinition<F extends FieldsMap = FieldsMap, T extends EntityTe
     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. */
+    /** 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.
+     *  `pii` and `encrypted` fields arrive as stored ciphertext bound to their field name (AAD): pass them through under the same key, never rename or derive from them, or the value can no longer be decrypted. */
     readonly eventMigrations?: readonly EntityEventMigration[];
     readonly searchWeight?: number;
     readonly defaultCurrency?: string;

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

@@ -8,5 +8,11 @@ export type FileHandle = {
 };
 export type FileContext = {
     ref(key: string): FileHandle;
+    refFromFileRef(row: {
+        readonly storageKey: string;
+    }): FileHandle;
+    listFromFileRef(row: {
+        readonly storageKey: string;
+    }): Promise<readonly string[]>;
     list(prefix: string): Promise<readonly string[]>;
 };

package/dist/handlers.d.ts

@@ -101,6 +101,12 @@ export type WriteEvent<TPayload = unknown> = {
     readonly payload: TPayload;
     readonly user: SessionUser;
 };
+/** What a handler sees when its `beforeTransaction` phase ran: the phase's `data` as `prepared`; absent for handlers without the phase. */
+export type PreparedWriteEvent<TPayload = unknown, TPrepared = unknown> = WriteEvent<TPayload> & ([TPrepared] extends [undefined] ? {
+    readonly prepared?: undefined;
+} : {
+    readonly prepared: TPrepared;
+});
 export type QueryEvent<TPayload = unknown> = {
     readonly type: string;
     readonly payload: TPayload;
@@ -232,6 +238,7 @@ type SharedContextFields = {
     readonly notify?: NotifyFn;
     readonly _notifyFactory?: NotifyFactory;
     readonly _notifyInTransactionFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
+    readonly _notifyAfterCommitFactory?: (user: SessionUser, tenantId: TenantId) => NotifyFn;
     readonly _escapeHatchAuditSink?: EscapeHatchAuditSink;
     readonly secrets?: import("./secrets-types.js").SecretsContext;
     readonly masterKeyProvider?: import("./secrets-types.js").MasterKeyProvider;
@@ -299,6 +306,11 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     } | null;
     readonly _userId?: string | undefined;
     readonly _handlerType?: string | undefined;
+    /** Keyed digest for handler-owned rate-limit keys, so Redis never holds a
+     *  plaintext or plainly hashed identifier. Scoped to the running handler:
+     *  the same input yields a different digest per handler and never matches a
+     *  dispatcher payload-bucket digest. Absent when the app wires no digest key. */
+    readonly rateLimitDigest?: (value: string) => string;
     readonly includeDeleted?: boolean;
     readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
     readonly query: (qn: string, payload: unknown) => Promise<unknown>;
@@ -344,6 +356,7 @@ export type JobContext = SharedContextFields & {
     readonly registry: Registry;
     readonly systemUser: SessionUser;
     readonly log: Logger;
+    readonly metricsFor: (featureName: string) => MetricsHandle;
     readonly triggeredBy: {
         readonly id: string;
         readonly tenantId: TenantId;
@@ -507,11 +520,13 @@ export type RateLimitOption = {
 export type RateLimitPayloadBucket = {
     readonly payloadField: string;
 };
+export type PayloadBucketNormalization = "email";
 export type PayloadRateLimitOption = {
     readonly per: RateLimitPayloadBucket;
     readonly limit: number;
     readonly windowSeconds: number;
     readonly cost?: number;
+    readonly normalize?: PayloadBucketNormalization;
 };
 export type RateLimitDisabled = {
     readonly disabled: true;
@@ -552,6 +567,15 @@ export type ReservationHandle = {
  *  The returned release (or handle.release) runs when the transaction does not commit (failure
  *  result, throw, rollback, failed commit). Throwing a KumikoError rejects the write. */
 export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
+/** Outcome of a write handler's pre-transaction phase. `release` runs when the handler transaction does not commit (failure result, throw, rollback, failed commit with unknown outcome), so it must itself tolerate a commit that actually happened. */
+export type BeforeTransactionResult<TPrepared = unknown> = {
+    readonly isSuccess: true;
+    readonly data: TPrepared;
+    readonly release?: ReservationRelease;
+} | WriteFailure;
+export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: HandlerContext) => Promise<BeforeTransactionResult<TPrepared>>;
+/** `perCommand`: the handler runs without a transaction of its own. */
+export type WriteHandlerTransactionMode = "perCommand";
 export type WriteHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;
@@ -571,6 +595,18 @@ export type WriteHandlerDef = {
     /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
     readonly reserveBeforeTransaction?: PreTransactionReservation;
+    /** Runs after all pre-handler gates (and after reserveBeforeTransaction) and before the
+     *  transaction opens: no transaction and no connection held, for external I/O and reads only.
+     *  Its `data` reaches the handler as `event.prepared`; a failure result or throw rejects the
+     *  write before anything is written. A handler with this phase cannot run as a nested ctx.write.
+     *  `ctx.forTenant` is available but read-only here: its db denies writes for the own and a
+     *  foreign tenant alike (a foreign tenant stays gated by the SystemAdmin check). */
+    readonly beforeTransaction?: BeforeTransactionPhase;
+    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.write/writeAs it
+     *  issues runs as its own top-level command with its own transaction and afterCommit hooks;
+     *  ctx.db writes and event appends throw. It cannot run as a nested write or inside a
+     *  multi-command batch, and cannot be combined with beforeTransaction/reserveBeforeTransaction. */
+    readonly transaction?: WriteHandlerTransactionMode;
     /** Lets an anonymous `POST /api/write` for this handler proceed under
      *  SYSTEM_TENANT_ID when the host resolves no tenant. Boot requires
      *  `access.roles: ["anonymous"]` and a real `rateLimit`. */

package/dist/hooks.d.ts

@@ -23,6 +23,7 @@ export type DeleteContext = {
     readonly data: Readonly<Record<string, unknown>>;
     readonly entityName?: string | undefined;
     readonly event?: StoredEvent | undefined;
+    readonly lockGuardBypassed?: boolean | undefined;
 };
 export type LifecycleResult = SaveContext | DeleteContext;
 export type PreSaveHookFn = (changes: Record<string, unknown>, context: AppContext & {

package/dist/screen.d.ts

@@ -554,8 +554,10 @@ export type ProjectionListScreenDefinition = {
      *  boot-validator only checks structure (`op:"in"` ⇒ array value). */
     readonly filter?: ScreenFilter;
     /** User-toggleable facet dropdowns — see `ListFacetSpec` doc. `field`
-     *  must be a declared column; the bound query handler must accept
-     *  `filters` in its Zod schema — the boot-validator checks both. A
+     *  must be a declared column, except for `type: "reference"`: it filters
+     *  by id through the bound query's `filters` and needs a registered
+     *  `entity` instead. The bound query handler must accept `filters` in its
+     *  Zod schema — the boot-validator checks both. A
      *  "dateRange" facet instead needs its two `params` keys in that schema;
      *  it sends no `filters` entry. */
     readonly facets?: readonly ListFacetSpec[];
@@ -721,6 +723,8 @@ export type DashboardPanelEmptyState = {
     /** Second line under `emptyLabel`. */
     readonly emptyHint?: string;
 };
+export declare const DASHBOARD_STAT_TONES: readonly ["default", "positive", "ok", "warn", "negative"];
+export type DashboardStatTone = (typeof DASHBOARD_STAT_TONES)[number];
 export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
     readonly kind: "stat";
     /** Stable id: kebab-case, unique within the panel set. */
@@ -734,7 +738,7 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     /** Formats a numeric value as currency (minor units); ignored for string values. The sparkline is not formatted. */
     readonly valueFormat?: DashboardValueFormat;
     /** Fixed tone when `toneField` is unset or yields none; not applied while the value is 0. */
-    readonly tone?: "default" | "positive" | "ok" | "warn" | "negative";
+    readonly tone?: DashboardStatTone;
     /** Record field holding `{ atMs, value | null }[]` (MetricResult.points),
      *  drawn as a sparkline next to the value. */
     readonly sparklineField?: string;
@@ -1144,7 +1148,9 @@ export type EditRelatedListSection = {
     readonly searchable?: boolean;
     /** User-toggleable facet dropdowns — same explicit-label `ListFacetSpec` as
      *  `projectionList.facets` (a relatedList has no entity to derive filterable
-     *  fields from). `field` must be a declared column and the bound query
+     *  fields from). `field` must be a declared column, except for
+     *  `type: "reference"`: it filters by id through the bound query's
+     *  `filters` and needs a registered `entity` instead. The bound query
      *  handler must accept `filters` in its Zod schema — the boot-validator
      *  checks both. Selected values ride along as `payload.filters`. */
     readonly facets?: readonly ListFacetSpec[];

package/dist/screen.js

@@ -1,6 +1,13 @@
 export function metricField(metric) {
     return typeof metric === "string" ? metric : metric.field;
 }
+// Query result contract: flat record; `valueField` points at the
+// value (string is display-ready, number is locale-formatted, DashboardI18nText
+// is translated), `subField` optionally at a sub line (string | DashboardI18nText), `toneField` optionally at
+// "default" | "positive" | "ok" | "warn" | "negative".
+// `visibleWhen` only on a top-level stat; the boot validator rejects it on a
+// stat-group child (gate the whole group instead).
+export const DASHBOARD_STAT_TONES = ["default", "positive", "ok", "warn", "negative"];
 /** Group key of a field value; `collapsedWhen` and row values both go through it. */
 export function relatedListGroupKey(value) {
     return value === undefined || value === null ? "" : String(value);

package/dist/secrets-types.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
+import type { DbRunner } from "./db-connection.js";
 import type { TenantId } from "./identifiers.js";
 declare const SecretBrand: unique symbol;
 export type Secret<T = string> = {
@@ -21,6 +22,7 @@ export type SecretKeyRef = string | {
     readonly name: string;
 };
 export interface SecretsContext {
+    withRunner(runner: DbRunner): SecretsContext;
     get(tenantId: TenantId, key: SecretKeyRef, auditCtx?: SecretAuditContext): Promise<Secret<string> | undefined>;
     has(tenantId: TenantId, key: SecretKeyRef): Promise<boolean>;
     set(tenantId: TenantId, key: SecretKeyRef, value: string, opts?: {

package/dist/write-error-info-types.d.ts

@@ -5,6 +5,7 @@ export type WriteErrorInfo = {
     readonly i18nParams?: Readonly<Record<string, unknown>>;
     readonly message: string;
     readonly details?: unknown;
+    readonly retryAfterSeconds?: number;
 };
 export type WriteFailure = {
     readonly isSuccess: false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.363.0",
+  "version": "0.365.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>",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.365.0",
+    "type": "improvement",
+    "title": "DASHBOARD_STAT_TONES is the single source for dashboard stat tones",
+    "detail": "screen.ts exports DASHBOARD_STAT_TONES and DashboardStatTone; DashboardStatPanel.tone derives from it, and the web renderer builds its runtime tone check and StatTone type from the same constant, so a new tone can no longer be silently dropped from toneField values."
+  },
   {
     "version": "0.362.0",
     "type": "improvement",