@cosmicdrift/kumiko-types 0.374.0 → 0.378.0

package/dist/config.d.ts

@@ -219,7 +219,10 @@ export type TemplateListVariableDef = TemplateVariableCommon & {
     readonly item: Readonly<Record<string, TemplateScalarVariableDef>>;
     readonly example?: readonly Readonly<Record<string, unknown>>[];
 };
-export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef;
+export type TemplateImagesVariableDef = TemplateVariableCommon & {
+    readonly type: "images";
+};
+export type TemplateVariableDef = TemplateScalarVariableDef | TemplateListVariableDef | TemplateImagesVariableDef;
 export type TemplateVariables = Readonly<Record<string, TemplateVariableDef>>;
 export type NotificationTemplateMeta = {
     readonly subject: string;

package/dist/feature.d.ts

@@ -116,10 +116,12 @@ 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" | "demoMode" | "seeds" | "signals" | "rateLimit";
+export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "demoMode" | "seeds" | "signals" | "rateLimit";
 export type StackBootRequirement = {
     readonly stack: string;
     readonly options: readonly BootOptionName[];
+    /** `"warn"`: a missing option logs a boot warning instead of aborting. Default `"error"`. */
+    readonly severity?: "error" | "warn";
 };
 export type FeatureDefinition = {
     readonly name: string;

package/dist/fields.d.ts

@@ -119,8 +119,9 @@ export type TextFieldDef = {
      *  "high" on the directly-dispatched entry handler; a revert doesn't undo a
      *  run that already read the compromised value. See irreversible-operation-gate. */
     readonly readAsInstruction?: boolean;
-    /** "password" is a pure render hint (masked input) — no storage semantics. */
-    readonly format?: "email" | "url" | "phone" | "password";
+    /** "password" is a pure render hint (masked input) — no storage semantics.
+     *  "month" stores `YYYY-MM`: month picker in the form, format enforced on write. */
+    readonly format?: "email" | "url" | "phone" | "password" | "month";
     readonly default?: string;
     readonly access?: FieldAccess;
     /** Mehrzeiliger Text — DefaultInput rendert dann ein <textarea> statt
@@ -488,7 +489,8 @@ export type EmbeddedSubFieldDef = (EmbeddedSubFieldBase & {
  *  precision its target sub-field in `schema` declares (money → integer,
  *  decimal → `scale`) before it's validated. */
 export type EmbeddedDerivedCellDef = {
-    readonly op: "multiply" | "sum" | "subtract";
+    /** `percent` = `from[0] * from[1] / 100` (exactly two sources, e.g. amount and rate). */
+    readonly op: "multiply" | "sum" | "subtract" | "percent";
     readonly from: readonly string[];
 };
 export type EmbeddedFieldDef = {

package/dist/handlers.d.ts

@@ -230,6 +230,9 @@ type SharedContextFields = {
      * absent for r.systemScope() handlers and without a db.
      */
     readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
+    /** Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value. */
+    readonly configAccessorFactory?: ConfigAccessorFactory;
+    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in the next major. */
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
@@ -290,7 +293,18 @@ export type AppContext = SharedContextFields & {
 };
 export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
     readonly db: TenantDb;
+    /**
+     * Same tenant scoping as `db`, but never bound to the handler's tx: writes through it survive
+     * a rollback. `undefined` only in the denial phases (member-resolution, before-transaction)
+     * and in platform-metering tenant mode; narrow with `hasOutsideTransactionDb(ctx)` or take it
+     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For
+     * r.systemScope() handlers it is a fail-closed Proxy; use `systemDb.outsideTransaction`.
+     */
     readonly dbOutsideTransaction: TenantDb | undefined;
+    /**
+     * @deprecated Use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)` from
+     * `@cosmicdrift/kumiko-framework/db`; removed in the next major.
+     */
     readonly outsideTransaction?: <T>(fn: (db: TenantDb) => Promise<T>) => Promise<T>;
     readonly systemDb?: UncheckedSystemDb;
     readonly registry: Registry;
@@ -320,8 +334,21 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
     readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
     readonly hasFeature: (featureName: string) => Promise<boolean>;
+    /**
+     * Default append: a typed domain event on one aggregate stream in the current tx. The runtime
+     * bumps the stream version and fires matching projections in the same transaction. A version
+     * conflict throws and poisons the transaction.
+     */
     readonly appendEvent: AppendEventFn<TMap>;
+    /**
+     * Untyped append (`payload: unknown`) with the same runtime as `appendEvent`. Only for
+     * migrations and upcasters, where the event type is not knowable at compile time.
+     */
     readonly unsafeAppendEvent: UnsafeAppendEventFn;
+    /**
+     * Optimistic append: runs in a savepoint and returns a version conflict as a result instead of
+     * throwing, so the handler can continue after losing a race on the same aggregate stream.
+     */
     readonly tryAppendEvent: TryAppendEventFn;
     readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
     readonly loadAggregate: (aggregateId: string, options?: {
@@ -375,8 +402,13 @@ export type JobContext = SharedContextFields & {
     readonly triggerName?: string;
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
-    readonly _userId?: string | undefined;
 };
+/**
+ * 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/nav-icon.js

@@ -4,7 +4,7 @@
 // r.nav()/r.screen()/config-mask/button call site instead of a silent
 // missing-icon at runtime.
 //
-// The renderer-web NAV_ICONS map (packages/renderer-web/src/icons.tsx) is
+// The renderer/web NAV_ICONS map (packages/renderer/src/web/icons.tsx) is
 // checked against this same union via `satisfies`, so the two can't drift —
 // add a key here only together with its lucide-react entry there, and vice
 // versa.

package/dist/screen.d.ts

@@ -63,8 +63,9 @@ export interface FieldFormatRegistry {
     image: {
         readonly variant?: string;
     };
-    /** List cell: FileRef id (or id array) as a download link with the file name.
-     *  Outside list cells the raw value is shown. */
+    /** 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;
 }
 export type FormatSpec = {
@@ -200,7 +201,7 @@ export type RowActionWriteHandler = {
     readonly style?: "primary" | "secondary" | "danger";
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -244,7 +245,7 @@ export type RowActionNavigateBase = {
     readonly rowClick?: boolean;
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -282,7 +283,7 @@ export type RowActionDrawer = {
     readonly style?: "primary" | "secondary" | "danger";
     /** Overrides the id-based default icon (see ACTION_ICON_BY_ID in
      *  kumiko-renderer) — closed IconKey vocabulary into the ICONS registry
-     *  (renderer-web), analogous to EditFieldSpec.icon. */
+     *  (renderer/web), analogous to EditFieldSpec.icon. */
     readonly icon?: IconKey;
     /** Inline render form in the row-action column — see `RowActionDisplay`. */
     readonly display?: RowActionDisplay;
@@ -1056,7 +1057,7 @@ export type EditFieldSpec = string | {
      *  rendering are unchanged. */
     readonly submit?: false;
     /** Prefix icon on the input — closed FieldIconKey vocabulary into
-     *  the FIELD_ICONS registry (renderer-web), analogous to
+     *  the FIELD_ICONS registry (renderer/web), analogous to
      *  `ScreenNavSugar.icon` / NavIconKey. Only takes effect for
      *  single-line `type: "text"` and `"number"` — a `text` field with
      *  `multiline` routes to a textarea (no icon slot), and other input
@@ -1151,7 +1152,7 @@ export type EditFieldsSection = {
         readonly columns?: number;
     }[];
     /** Rendered left of the section title, `text-muted-foreground` — closed
-     *  IconKey vocabulary into the ICONS registry (renderer-web), analogous
+     *  IconKey vocabulary into the ICONS registry (renderer/web), analogous
      *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
      *  one from the title (titles are free i18n strings). */
     readonly icon?: IconKey;
@@ -1522,6 +1523,21 @@ export type EntityEditActionPlacement = "inline" | "menu";
 export type EntityEditAction = RowAction & {
     readonly placement?: EntityEditActionPlacement;
 };
+/** A form field computed from other fields of the same form. `listSum` adds one
+ *  numeric cell over all rows of an embedded list field; its `whenEmpty`
+ *  fallback applies while the list has no rows (it must not be a `listSum`). */
+export type FormFieldDerivation = {
+    readonly op: "sum" | "subtract" | "multiply" | "percent";
+    readonly from: readonly string[];
+} | {
+    readonly op: "listSum";
+    readonly list: string;
+    readonly cell: string;
+    readonly whenEmpty?: FormFieldDerivationWithoutList;
+};
+export type FormFieldDerivationWithoutList = Extract<FormFieldDerivation, {
+    from: unknown;
+}>;
 export type ActionFormScreenDefinition = {
     readonly id: string;
     readonly type: "actionForm";
@@ -1560,6 +1576,13 @@ export type ActionFormScreenDefinition = {
      *  A `money` field here must name its own currency source: this screen
      *  has no entity whose `defaultCurrency` it could inherit (fw#2839). */
     readonly fields: Readonly<Record<string, FormFieldDefinition>>;
+    /** Fields computed from other fields, shown read-only and recomputed on every
+     *  change. A `listSum` over an empty list without `whenEmpty` leaves the field
+     *  a normal input, and then the client value counts. Otherwise the client value
+     *  is never trusted: the handler must wrap its schema with
+     *  `withFormDerivations(schema, screen)`, which the boot validator enforces.
+     *  A field read only as `whenEmpty` operand is read-only while every such list has rows. */
+    readonly derive?: Readonly<Record<string, FormFieldDerivation>>;
     /** Layout analog zu EntityEditScreen: sections mit fields aus dem
      *  fields-Map oben. */
     readonly layout: EditLayout;
@@ -1612,6 +1635,10 @@ export type ActionFormScreenDefinition = {
      *  handler's success payload); a link without a string id is hidden.
      *  Mutually exclusive with `redirect`. */
     readonly successLinks?: readonly ActionFormSuccessLink[];
+    /** Key figures from the handler's success payload, shown in the success box
+     *  while the screen stays put (e.g. charged/skipped/failed of a batch run).
+     *  Mutually exclusive with `redirect`. */
+    readonly successFacts?: readonly ActionFormSuccessFact[];
     /** Reset the form to its initial values after a successful submit (prefill
      *  kept, typed values cleared). Only applies while the screen stays put,
      *  i.e. without `redirect`. */
@@ -1677,6 +1704,15 @@ export type ActionFormLoad = {
     /** Payload key carrying the record id (default "id"). */
     readonly idParam?: string;
 };
+/** One key figure of the success box, read from the handler's success payload. */
+export type ActionFormSuccessFact = {
+    /** Flat field name in the handler's success payload. A number or string is
+     *  shown as one value, an array a comma-separated list (numbers, strings and
+     *  `{ label }` objects). A missing field hides the fact. */
+    readonly field: string;
+    /** Label (i18n key). */
+    readonly label: string;
+};
 /** A redirect target rendered as a link in the success box. */
 export type ActionFormSuccessLink = Omit<ActionFormRedirect, "idFrom"> & {
     /** Success-payload field carrying the navigation id. Required for a record

package/dist/target-ref.js

@@ -1,5 +1,5 @@
 // TargetRef — runtime-Repräsentation eines typed buildTarget-Outputs.
-// Wird vom Visual-Tree-Component (renderer-web) an einen Target-Resolver
+// Wird vom Visual-Tree-Component (renderer/web) an einen Target-Resolver
 // dispatcht; der Resolver findet die Editor-Maske via featureId.
 //
 // **Compile-time-Safety:** TargetRef wird niemals hand-getippt. Stattdessen

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

@@ -46,6 +46,11 @@ export type TenantDb = {
     selectMany<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where?: WhereObject, options?: SelectOptions): Promise<readonly T[]>;
     fetchOne<T = Record<string, unknown>>(table: SchemaTable | EntityTableMeta, where: WhereObject): Promise<T | undefined>;
     count(table: SchemaTable | EntityTableMeta, where?: WhereObject): Promise<number>;
+    /**
+     * Transaction-scoped advisory lock keyed on (namespace, this handle's tenantId + key); released at
+     * commit or rollback. Keys of different tenants never contend. Only serialises inside a transaction.
+     */
+    advisoryXactLock(namespace: number, key: string): Promise<void>;
     aggregate(table: SchemaTable | EntityTableMeta, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
     insertOne<T = Record<string, unknown>>(table: WritableTable, values: Record<string, unknown>): Promise<T | undefined>;
     updateMany<T = Record<string, unknown>>(table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly T[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.374.0",
+  "version": "0.378.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,24 @@
 [
+  {
+    "version": "0.377.0",
+    "type": "improvement",
+    "title": "outsideTransaction deprecated, ProviderPluginContext added",
+    "detail": "HandlerContext.outsideTransaction is marked deprecated; use runInOwnTransaction(ctx.dbOutsideTransaction, fn). ProviderPluginContext is a Pick of HandlerContext for provider plugins. SharedContextFields gains configAccessorFactory; _configAccessorFactory stays as a deprecated alias. dbOutsideTransaction stays TenantDb | undefined (undefined only in the member-resolution and before-transaction denial phases and in platform-metering tenant mode); hasOutsideTransactionDb(ctx) narrows it and requireOutsideTransactionDb(ctx) throws when it is missing.",
+    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(ctx.dbOutsideTransaction, fn). Read configAccessorFactory instead of _configAccessorFactory."
+  },
+  {
+    "version": "0.377.0",
+    "type": "breaking",
+    "title": "JobContext._userId removed",
+    "detail": "The job runner never set JobContext._userId; only user-data-rights read it, falling back to SYSTEM_USER_ID. Hand-built JobContext objects that still set it fail to type-check, and code that read it must use SYSTEM_USER_ID or the job's system user.",
+    "migration": "Drop _userId from hand-built JobContext objects (tests, job helpers) and replace reads of ctx._userId with SYSTEM_USER_ID. Known hits - money-horse data-export integration test, offlot-app channel-text generate-texts.job.ts."
+  },
+  {
+    "version": "0.376.0",
+    "type": "improvement",
+    "title": "StackBootRequirement severity and the featureToggles option name",
+    "detail": "StackBootRequirement takes severity \"warn\" for requirements that only log, and BootOptionName lists featureToggles."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",