@cosmicdrift/kumiko-types 0.249.0 → 0.250.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.249.0",
+  "version": "0.250.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/event-store-executor-types.ts

@@ -109,6 +109,17 @@ export type EventStoreExecutor = {
         }>;
         readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
       };
+      // fw#2741 — `sortable: true` reference fields order by the target row's
+      // labelField instead of the raw FK column. Same request-time registry
+      // dependency (and the same fields/resolveEntity pairing) as referenceSearch.
+      readonly referenceSort?: {
+        readonly fields: ReadonlyArray<{
+          readonly fieldName: string;
+          readonly targetEntityName: string;
+          readonly labelField: string;
+        }>;
+        readonly resolveEntity: (entityName: string) => EntityDefinition | undefined;
+      };
     },
   ) => Promise<CursorResult<Record<string, unknown>>>;
 

package/src/feature.ts

@@ -37,7 +37,7 @@ import type {
   EntityRef,
   EventDef,
   EventMigrationDef,
-  EventPiiFields,
+  EventPiiStance,
   EventUpcastFn,
   HandlerRef,
   NameOrRef,
@@ -580,15 +580,18 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // payload out) and run once per read, not once per event persisted, so
   // keep them cheap.
   //
-  // `options.piiFields` declares PII payload fields encrypted under the DEK
-  // of the user named by `subjectField` (crypto-shredding, #799). append()
-  // enforces the catalog on every write path.
+  // `options.piiFields` is a mandatory, explicit PII stance (fw#2558) —
+  // registration fails without one. Pass a map of payload fields to their
+  // owning `subjectField` for fields carrying personal data (encrypted
+  // under that user's DEK, crypto-shredding #799), or `"none"` to declare
+  // the payload holds no personal data. append() enforces the resulting
+  // catalog on every write path.
   defineEvent<const TInner extends string, TPayload>(
     name: TInner,
     schema: ZodType<TPayload>,
-    options?: {
+    options: {
       readonly version?: number;
-      readonly piiFields?: EventPiiFields;
+      readonly piiFields: EventPiiStance;
       readonly migrations?: readonly {
         readonly fromVersion: number;
         readonly toVersion: number;
@@ -888,6 +891,11 @@ export type Registry = {
     targetEntityName: string;
     labelField: string;
   }>;
+  getSortableReferences(entityName: string): ReadonlyArray<{
+    fieldName: string;
+    targetEntityName: string;
+    labelField: string;
+  }>;
   getIncomingRelations(entityName: string): ReadonlyArray<{
     sourceEntity: string;
     relationName: string;

package/src/fields.ts

@@ -483,6 +483,11 @@ export type ReferenceFieldDef = {
    *  validator rejects it otherwise, since the default "id" is a UUID column
    *  and ILIKE against it would crash at runtime. */
   readonly searchable?: true;
+  /** Order a list by the referenced entity's `labelField` instead of by the raw
+   *  UUID column (fw#2741). Requires an explicit, non-"id" `labelField` — the
+   *  boot validator rejects it otherwise, since ordering by a UUID produces a
+   *  sequence that looks meaningful to the user but is arbitrary. */
+  readonly sortable?: true;
 } & ResolvedPiiFlags;
 
 // --- Currency ---

package/src/handlers.ts

@@ -589,15 +589,29 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
 // Job execution: db + registry + systemUser + logging guaranteed, plus a
 // write path into the same dispatcher pipeline write-handlers use.
 //
-// write/queryAs throw until JobRunner.attachDispatcher() has run — a call
-// this early is a framework boot bug, not a job-author mistake.
+// write/writeAs/queryAs throw until JobRunner.attachDispatcher() has run — a
+// call this early is a framework boot bug, not a job-author mistake.
 //
-// Identity is implicit: write runs as the job's own systemUser, tenant-
-// scoped via the job's _tenantId (falls back to SYSTEM_TENANT_ID for jobs
-// with no tenant context, e.g. plain cron jobs). A job that writes without
-// fanning out per-tenant (`_perTenant:` trigger) silently writes into the
-// system tenant instead of each tenant it may have meant to reach — no
-// guard against this, only this warning.
+// `write` runs as the job's own systemUser, tenant-scoped via the job's
+// _tenantId (falls back to SYSTEM_TENANT_ID for jobs with no tenant context,
+// e.g. plain cron jobs). A job that writes without fanning out per-tenant
+// (`_perTenant:` trigger) silently writes into the system tenant instead of
+// each tenant it may have meant to reach — no guard against this, only this
+// warning.
+//
+// `writeAs` is the explicit-identity counterpart, symmetric with `queryAs`:
+// `hasAccess` has no system bypass, so a write handler whose `access` lists
+// concrete roles is unreachable through `write` — the job's systemUser only
+// carries SYSTEM_ROLE and the dispatch comes back `access_denied`
+// (kumiko-framework#2585). The job has to assemble a full SessionUser for it:
+// `triggeredBy` alone is not enough, it carries only id + tenantId and no
+// roles, so the roles have to come from the job's own lookup.
+//
+// The passed identity also decides the target tenant — `writeAs` hands
+// `user.tenantId` straight to the dispatcher with nothing cross-checking it
+// against the job's own tenant, exactly as `queryAs` and the raw `db` above
+// already do. Building an identity from job payload data is therefore a
+// cross-tenant write path; derive it from a trusted lookup instead.
 export type JobContext = SharedContextFields & {
   readonly db: DbConnection;
   readonly registry: Registry;
@@ -614,6 +628,7 @@ export type JobContext = SharedContextFields & {
   // pass it to code that trusts the connection to already be scoped.
   readonly systemDb?: UncheckedSystemDb;
   readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
+  readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
   readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
   // Multi-trigger jobs (`on: [...]`) use this to tell which trigger fired —
   // undefined for cron/manual jobs. Mirrors AppContext.triggerName.
@@ -722,6 +737,12 @@ export type QualifiedEventName<
 // no user key to shred for system-triggered events.
 export type EventPiiFields = Readonly<Record<string, { readonly subjectField: string }>>;
 
+// The full set of PII stances a defineEvent() call may declare. "none" is a
+// distinct value from `{}` — an empty object is indistinguishable from "the
+// author forgot to list fields", while "none" is an explicit assertion that
+// the payload carries no personal data.
+export type EventPiiStance = EventPiiFields | "none";
+
 export type EventDef<TPayload = unknown, TName extends string = string> = {
   readonly name: TName;
   readonly schema: ZodType<TPayload>;
@@ -730,7 +751,7 @@ export type EventDef<TPayload = unknown, TName extends string = string> = {
   // upcasts older stored events. Reads consult this to decide if upcasters
   // need to run before the payload hits consumer code.
   readonly version: number;
-  readonly piiFields?: EventPiiFields;
+  readonly piiFields?: EventPiiStance;
 };
 
 // Args for ctx.appendEvent — explicit aggregate target, Marten-style.

package/src/screen.ts

@@ -275,7 +275,9 @@ export type RowActionNavigateBase = {
   readonly params?: RowFieldExtractor;
   /** Conditional Visibility pro Row. */
   readonly visible?: FieldCondition;
-  readonly style?: "primary" | "secondary";
+  /** Visual style only — unlike the writeHandler variants, "danger" does not
+   *  force a confirm dialog here: the target form is the confirmation. */
+  readonly style?: "primary" | "secondary" | "danger";
   /** Wenn true, löst ein Klick auf die ganze Zeile (nicht nur das Aktionsmenü)
    *  diese navigate-Action aus. Max. eine pro Liste (Boot-Validator prüft). Nur
    *  auf navigate — ein Row-Klick darf keinen (evtl. destruktiven, unbestätigten)
@@ -320,7 +322,9 @@ export type RowActionDrawer = {
   readonly params?: RowFieldExtractor;
   /** Per-row conditional visibility. */
   readonly visible?: FieldCondition;
-  readonly style?: "primary" | "secondary";
+  /** Visual style only — unlike the writeHandler variants, "danger" does not
+   *  force a confirm dialog here: the target form is the confirmation. */
+  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. */
@@ -338,7 +342,10 @@ export type ToolbarAction =
       readonly label: string;
       /** Screen-id (kurz, unqualified) zu dem navigiert wird. */
       readonly screen: string;
-      readonly style?: "primary" | "secondary";
+      /** Visual style only — unlike the writeHandler variant, "danger" does
+       *  not force a confirm dialog here: the target form is the
+       *  confirmation. */
+      readonly style?: "primary" | "secondary" | "danger";
     }
   | {
       readonly kind: "writeHandler";
@@ -364,7 +371,10 @@ export type ToolbarAction =
        *  vs. drawer, not the form (see docs/plans/bundled-features-screen-
        *  standardisierung.md §2.6c). */
       readonly screen: string;
-      readonly style?: "primary" | "secondary";
+      /** Visual style only — unlike the writeHandler variant, "danger" does
+       *  not force a confirm dialog here: the target form is the
+       *  confirmation. */
+      readonly style?: "primary" | "secondary" | "danger";
     };
 
 export type EntityListScreenDefinition = {
@@ -1004,6 +1014,10 @@ export type ActionFormScreenDefinition = {
   /** i18n-key für den Submit-Button. Default: i18n-Default des
    *  Renderers (typischerweise "actions.submit"). */
   readonly submitLabel?: string;
+  /** Visual style of the submit button. "danger" renders it red — for a form
+   *  whose handler is destructive (terminate, revoke, delete), so the warning
+   *  isn't lost on the way from the calling screen to this one. Default "primary". */
+  readonly submitStyle?: "primary" | "danger";
   /** Navigate to this screen ID after a successful submit: either a short
    *  ID (e.g. "item-list" — same feature, the nav-router resolves to the
    *  full path) or a fully-qualified cross-feature QN