@cosmicdrift/kumiko-types 0.378.0 → 0.380.0

package/dist/executor-brand.d.ts

@@ -1,8 +1,15 @@
-declare const EXECUTOR_ONLY: unique symbol;
-export interface ExecutorOnly {
-    readonly [EXECUTOR_ONLY]: true;
+import type { DbRunner } from "./db-connection.ts";
+import type { EntityTableMeta } from "./entity-table-meta-types.ts";
+import type { SchemaTable } from "./schema-table-types.ts";
+declare const WRITABLE: unique symbol;
+export interface Writable {
+    readonly [WRITABLE]: true;
 }
-export type NotExecutorOnly = {
-    readonly [EXECUTOR_ONLY]?: never;
-};
+export type WritableTable = EntityTableMeta & Writable;
+declare const EXECUTOR_MANAGED_WRITE: unique symbol;
+export interface ExecutorManagedWriteCapability {
+    readonly [EXECUTOR_MANAGED_WRITE]: true;
+}
+export type ExecutorManagedRunner = DbRunner & ExecutorManagedWriteCapability;
+export type WritableSchemaTable = SchemaTable & Writable;
 export {};

package/dist/fields.d.ts

@@ -493,6 +493,10 @@ export type EmbeddedDerivedCellDef = {
     readonly op: "multiply" | "sum" | "subtract" | "percent";
     readonly from: readonly string[];
 };
+export type EmbeddedTotalDef = string | {
+    readonly label: string;
+    readonly from: readonly string[];
+};
 export type EmbeddedFieldDef = {
     readonly type: "embedded";
     readonly description?: string;
@@ -519,9 +523,12 @@ export type EmbeddedFieldDef = {
      *  sub-fields of the same row, rounded to that sub-field's declared
      *  precision. Only valid with `multiple: true`. */
     readonly derived?: Readonly<Record<string, EmbeddedDerivedCellDef>>;
-    /** Renderer metadata: numeric sub-field names to sum in a totals row. Only
-     *  valid with `multiple: true`. */
-    readonly totals?: readonly string[];
+    /** Renderer metadata: footer totals. A string is the sum of that numeric
+     *  sub-field under the column label; an object shows the sum of all `from`
+     *  sub-fields under its own i18n `label` (e.g. net, VAT, gross). Display
+     *  only; the server derivation is unchanged. Only valid with
+     *  `multiple: true`. */
+    readonly totals?: readonly EmbeddedTotalDef[];
     /** Maps an embedded-list subfield name to a sibling top-level money field
      *  name — the sum of that subfield across all rows must equal the sibling
      *  field's amount. Validated both client- and server-side (schema-builder
@@ -637,6 +644,10 @@ export type FilesFieldDef = {
     readonly maxSize?: string;
     readonly accept?: readonly string[];
     readonly maxCount?: number;
+    /** `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a
+     *  drag-and-drop zone with one status row per file, a remove action per file and the field's
+     *  `maxCount`/`accept`/`maxSize` as hints. The stored value is the same array of FileRef ids. */
+    readonly display?: "list" | "dropzone";
     readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
 export type ImagesFieldDef = {
@@ -645,6 +656,10 @@ export type ImagesFieldDef = {
     readonly maxSize?: string;
     readonly accept?: readonly string[];
     readonly maxCount?: number;
+    /** `"list"` (default) shows the picked files as a list with a file picker; `"dropzone"` shows a
+     *  drag-and-drop zone with one status row per file, a remove action per file and the field's
+     *  `maxCount`/`accept`/`maxSize` as hints. The stored value is the same array of FileRef ids. */
+    readonly display?: "list" | "dropzone";
     readonly variants?: Readonly<Record<string, VariantSpec>>;
     /** Forwarded to the file input's `capture` attribute so a phone opens the
      *  camera instead of the file picker. */

package/dist/handlers.d.ts

@@ -232,7 +232,7 @@ type SharedContextFields = {
     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. */
+    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in 0.390.0. */
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
@@ -297,15 +297,12 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
      * 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
+     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For atomic
+     * multi-statement writes outside the tx use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)`; `fn`
+     * must not touch rows the handler's own tx has locked. 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;
     /** Aktiver SessionUser des Handler-Aufrufs — Convenience-Alias zu
@@ -460,7 +457,7 @@ export type EventPiiSubject = {
 } | {
     readonly personal: "self";
 } | {
-    /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. */
+    /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. Removed in 0.390.0. */
     readonly subjectField: string;
 };
 export type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;

package/dist/projection.d.ts

@@ -1,12 +1,12 @@
 import type { RunIn } from "./config.ts";
-import type { DbRunner } from "./db-connection.ts";
 import type { StoredEvent } from "./event-store-types.ts";
+import type { ExecutorManagedRunner } from "./executor-brand.ts";
 import type { EntityDefinition } from "./fields.ts";
 import type { MultiStreamApplyContext } from "./multi-stream-apply-context-types.ts";
 import type { SchemaTable } from "./schema-table-types.ts";
 export type ProjectionTable = SchemaTable;
-export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, table: ProjectionTable) => Promise<void>;
-export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: DbRunner, ctx: MultiStreamApplyContext) => Promise<void>;
+export type SingleStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, table: ProjectionTable) => Promise<void>;
+export type MultiStreamApplyFn<TPayload = Record<string, unknown>> = (event: StoredEvent<TPayload>, tx: ExecutorManagedRunner, ctx: MultiStreamApplyContext) => Promise<void>;
 export type ProjectionRowIdOf = (source: Pick<StoredEvent, "tenantId" | "aggregateId">) => string;
 export type ProjectionDefinition = {
     readonly name: string;

package/dist/screen.d.ts

@@ -925,6 +925,15 @@ export type DashboardTextBlock = {
 } | {
     readonly kind: "hint";
     readonly text: string;
+} | {
+    readonly kind: "link";
+    /** Link label (i18n key). */
+    readonly text: string;
+    /** Same-feature short id or cross-feature QN `<feature>:screen:<id>`. */
+    readonly screen: string;
+    /** Show the link only to users holding one of these roles. Display
+     *  gate only: the target screen's own `access` stays the enforcement. */
+    readonly roles?: readonly string[];
 };
 export type DashboardTextPanel = DashboardPanelGate & {
     readonly kind: "text";
@@ -1703,6 +1712,11 @@ export type ActionFormLoad = {
     readonly query: string;
     /** Payload key carrying the record id (default "id"). */
     readonly idParam?: string;
+    /** The query picks the row from the caller's tenant/session context, so the
+     *  form loads without a record id and the query is called WITHOUT `idParam`
+     *  (same semantics as `ProjectionDetailScreenDefinition.singleton`). Boot
+     *  rejects declaring `idParam` alongside it. */
+    readonly singleton?: boolean;
 };
 /** One key figure of the success box, read from the handler's success payload. */
 export type ActionFormSuccessFact = {

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

@@ -1,12 +1,11 @@
 import type { AggregateRow, AggregateSpec } from "./aggregate-types.ts";
 import type { DbRunner } from "./db-connection.ts";
 import type { EntityTableMeta } from "./entity-table-meta-types.ts";
-import type { ExecutorOnly, NotExecutorOnly } from "./executor-brand.ts";
+import type { ExecutorManagedWriteCapability, Writable, WritableTable } from "./executor-brand.ts";
 import type { TenantId } from "./identifiers.ts";
 import type { SchemaTable } from "./schema-table-types.ts";
 import type { TenancyBrand } from "./tenancy-brand.ts";
 import type { SelectOptions, WhereObject } from "./where-clause-types.ts";
-type WritableTable = (SchemaTable | EntityTableMeta) & NotExecutorOnly;
 type GlobalReads = {
     selectMany<T = Record<string, unknown>>(where?: WhereObject, options?: SelectOptions): Promise<readonly T[]>;
     fetchOne<T = Record<string, unknown>>(where: WhereObject): Promise<T | undefined>;
@@ -16,7 +15,7 @@ type GlobalWrites = {
     updateMany<T = Record<string, unknown>>(set: Record<string, unknown>, where: WhereObject): Promise<readonly T[]>;
     deleteMany(where: WhereObject): Promise<void>;
 };
-export type GlobalTableDb<TTable> = GlobalReads & (TTable extends ExecutorOnly ? unknown : GlobalWrites);
+export type GlobalTableDb<TTable> = GlobalReads & (TTable extends Writable ? GlobalWrites : unknown);
 /**
  * TenantDb scope modes:
  *
@@ -30,7 +29,12 @@ export type GlobalTableDb<TTable> = GlobalReads & (TTable extends ExecutorOnly ?
  */
 export type TenantDbMode = "tenant" | "system";
 export type CrossTenantReads = Pick<TenantDb, "selectMany" | "fetchOne" | "count">;
-export type TenantDb = {
+export type TenantDbWrites<TTable> = {
+    insertOne<T = Record<string, unknown>>(table: TTable, values: Record<string, unknown>): Promise<T | undefined>;
+    updateMany<T = Record<string, unknown>>(table: TTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly T[]>;
+    deleteMany(table: TTable, where: WhereObject): Promise<number>;
+};
+type TenantDbNonWrites = {
     readonly tenantId: TenantId;
     readonly mode: TenantDbMode;
     /**
@@ -51,11 +55,12 @@ export type TenantDb = {
      * commit or rollback. Keys of different tenants never contend. Only serialises inside a transaction.
      */
     advisoryXactLock(namespace: number, key: string): Promise<void>;
+    /** Postgres `now()`; inside a transaction this is the transaction start. */
+    databaseNow(): Promise<Date>;
     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[]>;
-    deleteMany(table: WritableTable, where: WhereObject): Promise<number>;
 };
+export type TenantDb = TenantDbNonWrites & TenantDbWrites<WritableTable>;
+export type ExecutorManagedTenantDb = TenantDbNonWrites & TenantDbWrites<EntityTableMeta> & ExecutorManagedWriteCapability;
 export declare const SYSTEM_SCOPE_CHECK_BRAND: unique symbol;
 export type UncheckedSystemDb = {
     readonly [SYSTEM_SCOPE_CHECK_BRAND]: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.378.0",
+  "version": "0.380.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,11 @@
 [
+  {
+    "version": "0.379.0",
+    "type": "breaking",
+    "title": "HandlerContext.outsideTransaction removed",
+    "detail": "The deprecated outsideTransaction field no longer exists on HandlerContext. ctx.dbOutsideTransaction together with runInOwnTransaction replaces it.",
+    "migration": "Replace ctx.outsideTransaction(fn) with runInOwnTransaction(requireOutsideTransactionDb(ctx), fn); both are exported from @cosmicdrift/kumiko-framework/db and fn keeps its (db) => Promise signature."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",