@cosmicdrift/kumiko-types 0.290.0 → 0.292.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.290.0",
+  "version": "0.292.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/config.ts

@@ -394,6 +394,22 @@ export type JobDefinition = {
   readonly runIn?: JobRunIn | undefined;
   // Grants `ctx.db.unsafeRaw(reason)` for this job, audited as `unsafe-raw`.
   readonly escapeHatch?: EscapeHatchDeclaration | undefined;
+  // Opt in to a tenant-visible failure record (`jobs:query:failures`). Only a
+  // translation key ever reaches the tenant: a thrown KumikoError's `i18nKey`
+  // when it carries one, otherwise `messageKey`. The provider's own message
+  // stays in the run log. Only the last attempt records, and a later
+  // successful run of the same job and subject clears the record.
+  // `subjectFields` names payload fields that scope the record (e.g.
+  // `["campaignId", "language"]`); each must hold a primitive or the run
+  // throws. Omit it for one record per job and tenant. Their values are
+  // stored in clear, unlike the encrypted run payload — never name a PII
+  // field here.
+  readonly tenantVisibleFailure?:
+    | {
+        readonly messageKey: string;
+        readonly subjectFields?: readonly string[] | undefined;
+      }
+    | undefined;
 };
 
 // --- Notifications ---

package/src/feature.ts

@@ -617,6 +617,12 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   // 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.
+  //
+  // When the schema lets the owner field be null/undefined, the stance must
+  // also say what happens on those writes — `whenAbsent: "tenant"` encrypts
+  // under the envelope tenant key, `whenAbsent: "plaintext"` acknowledges an
+  // unshreddable value. Registration fails without one, and an owner that is
+  // empty at append time with no declared fallback aborts the write (fw#2776).
   defineEvent<const TInner extends string, TPayload>(
     name: TInner,
     schema: ZodType<TPayload>,

package/src/fields.ts

@@ -445,12 +445,16 @@ export type DecimalFieldDef = {
   readonly access?: FieldAccess;
 } & ResolvedPiiFlags;
 
-/** Where a money field's currency comes from, for the fields that opt in.
- *  Discriminated union so #2839 can add `{ kind: "literal", code }` and
- *  `{ kind: "field", of }` variants without a breaking change. `"tenant"` is
- *  the tenant-settings bundle's per-tenant currency (`tenant-settings:config:
- *  currency`) — see kumiko-framework#2933. */
-export type MoneyCurrencySource = { readonly kind: "tenant" };
+/** Where a money field's currency comes from. `"tenant"` is the
+ *  tenant-settings bundle's per-tenant currency (`tenant-settings:config:
+ *  currency`, kumiko-framework#2933); `"literal"` names a fixed ISO code and
+ *  is checked against the app's `currencies` list at boot
+ *  (kumiko-framework#2839). Discriminated union so a `{ kind: "field", of }`
+ *  variant (amount and currency-picker side by side) can still be added
+ *  without a breaking change, once a multi-currency form actually exists. */
+export type MoneyCurrencySource =
+  | { readonly kind: "tenant" }
+  | { readonly kind: "literal"; readonly code: string };
 
 /** Qualified config key a `{ kind: "tenant" }` MoneyCurrencySource resolves
  *  against — the tenant-settings bundle's per-tenant currency. Lives here
@@ -513,6 +517,25 @@ export type ReferenceFieldDef = {
    *  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;
+  /** Fill the picker from this query handler instead of the referenced
+   *  entity's own list handler (fw#2780) — for targets whose identity is
+   *  composed from joined rows, where no single column of the referenced
+   *  entity is a readable label. Fully-qualified QN
+   *  ("<feature>:query:<short>"), boot-validated against the registered
+   *  handlers; result contract `{ rows: { id, label }[] }`, called with
+   *  `{ limit, search? }` like the default list handler. `id` rather than the
+   *  `{ value, label }` of `DashboardFilterDefinition.optionsQuery`, because
+   *  the stored value here IS the referenced row's id.
+   *
+   *  Additive to `labelField`, which keeps serving the paths a query handler
+   *  cannot back: list cells, `searchable` and `sortable` all resolve to an
+   *  SQL column on the referenced table.
+   *
+   *  The handler must return the row for an id that is already stored, even
+   *  when it otherwise curates its result (say, to active records only) —
+   *  the read-only display resolves a stored value against these rows and
+   *  falls back to the raw id for one it does not find. */
+  readonly optionsQuery?: string;
 } & ResolvedPiiFlags;
 
 // --- Currency ---
@@ -568,6 +591,8 @@ export type EmbeddedSubFieldDef =
       readonly type: "reference";
       readonly entity: string;
       readonly labelField?: string;
+      /** Same contract as `ReferenceFieldDef.optionsQuery` (fw#2780). */
+      readonly optionsQuery?: string;
     });
 
 /** A cell computed from other cells of the same row. `from` names the
@@ -811,6 +836,16 @@ export type FieldDefinition =
   | FilesFieldDef
   | ImagesFieldDef;
 
+/** FieldDefinition as an entity-less inline form screen (actionForm,
+ *  secretMint) may declare it: a `money` field there has no entity to borrow
+ *  `defaultCurrency` from, so it must name its own currency source, or the
+ *  form seeds a bare `0` that the handler's zod schema then rejects
+ *  (kumiko-framework#2839). Entity fields keep the optional `currency` —
+ *  `entity.defaultCurrency` is already boot-enforced for them. */
+export type FormFieldDefinition =
+  | Exclude<FieldDefinition, MoneyFieldDef>
+  | (MoneyFieldDef & { readonly currency: MoneyCurrencySource });
+
 // Union of all field variants that represent uploaded files. They share
 // `maxSize` and `accept`, which is what upload validation cares about.
 export type AnyFileFieldDef = FileFieldDef | ImageFieldDef | FilesFieldDef | ImagesFieldDef;

package/src/handlers.ts

@@ -832,9 +832,7 @@ export type QualifiedEventName<
 > = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`;
 
 // PII payload fields on a custom event (#799): `field` is encrypted under
-// the DEK the subject spec names (crypto-shredding). A null owner-field
-// value leaves a `personal: { of }` field plaintext — there is no user key
-// to shred for system-triggered events.
+// the DEK the subject spec names (crypto-shredding).
 //
 // `{ personal: { of: "<ownerField>" } }` is the canonical user-subject form,
 // matching the entity-field `personal` vocabulary (see fields.ts).
@@ -842,8 +840,21 @@ export type QualifiedEventName<
 // (envelope.tenantId) or its own aggregate stream (envelope.aggregateType +
 // aggregateId) as the subject instead — resolved via `resolveEventSubject`
 // in `packages/framework/src/crypto/subject-resolver.ts` (fw#2801).
+//
+// `whenAbsent` decides what happens when the named owner field carries no
+// id (system- or cron-triggered writes): "tenant" re-targets the envelope
+// tenant key, "plaintext" is an explicit acknowledgement that the value
+// ships unencrypted and cannot be crypto-shredded. Undeclared is not a
+// third option — the append fails closed instead of leaking (fw#2776).
+export type EventPiiAbsentSubject = "plaintext" | "tenant";
+
 export type EventPiiSubject =
-  | { readonly personal: { readonly of: string } }
+  | {
+      readonly personal: {
+        readonly of: string;
+        readonly whenAbsent?: EventPiiAbsentSubject;
+      };
+    }
   | { readonly personal: "tenant" }
   | { readonly personal: "self" }
   | {
@@ -854,15 +865,21 @@ export type EventPiiSubject =
 export type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;
 
 export type NormalizedEventPiiSubject =
-  | { readonly kind: "user"; readonly ownerField: string }
+  | {
+      readonly kind: "user";
+      readonly ownerField: string;
+      readonly whenAbsent: EventPiiAbsentSubject | undefined;
+    }
   | { readonly kind: "tenant" }
   | { readonly kind: "self" };
 
 export function normalizeEventPiiSubject(spec: EventPiiSubject): NormalizedEventPiiSubject {
-  if ("subjectField" in spec) return { kind: "user", ownerField: spec.subjectField };
+  if ("subjectField" in spec) {
+    return { kind: "user", ownerField: spec.subjectField, whenAbsent: undefined };
+  }
   if (spec.personal === "tenant") return { kind: "tenant" };
   if (spec.personal === "self") return { kind: "self" };
-  return { kind: "user", ownerField: spec.personal.of };
+  return { kind: "user", ownerField: spec.personal.of, whenAbsent: spec.personal.whenAbsent };
 }
 
 // The full set of PII stances a defineEvent() call may declare. "none" is a

package/src/identifiers.ts

@@ -49,6 +49,12 @@ export function isSystemTenant(tenantId: TenantId | null | undefined): boolean {
   return !tenantId || tenantId === SYSTEM_TENANT_ID;
 }
 
+// "No human caller" marker on event-store `createdBy`. Stringified so it
+// round-trips through SessionUser.id; not a real UUID, and createdBy is text.
+// Lives here rather than next to createSystemUser() so client-side code (the
+// reference-label map) can read it without importing a runtime module.
+export const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
+
 // Primary-key identifier for any entity row. Two shapes coexist because of
 // the entity-def `idType` switch: classic CRUD entities keep `serial` (number),
 // while tenant + ES aggregates run on `uuid` (string). Call sites that pass

package/src/screen.ts

@@ -1,5 +1,5 @@
 import type { FieldIconKey } from "./field-icon";
-import type { FieldDefinition } from "./fields";
+import type { FieldDefinition, FormFieldDefinition } from "./fields";
 import type { AccessRule, AgentHandlerHints } from "./handlers";
 import type { IconKey, NavIconKey } from "./nav-icon";
 
@@ -473,6 +473,8 @@ export type EntityListScreenDefinition = {
 // `falseLabel`) are i18n keys resolved via `translate()` with passthrough
 // for unknown keys (fw#2373) — not raw display strings. Sent to the server
 // as `{field, op:"in", value}` in `payload.filters`, ANDed with `filter`.
+// Exception: "dateRange" sends its bounds as the two top-level payload keys
+// named in `params`, not as a `filters` entry.
 export type ListFacetSpec =
   | {
       readonly field: string;
@@ -497,6 +499,20 @@ export type ListFacetSpec =
       /** Row field on the referenced entity shown as the option label
        *  (default "id"). */
       readonly labelField?: string;
+    }
+  | {
+      /** Declarative only — the date field the range narrows. It is NOT sent
+       *  to the server (the bounds go under `params`); it namespaces the
+       *  facet's URL keys and tells a reading agent which column this list
+       *  is time-rangeable on. */
+      readonly field: string;
+      readonly type: "dateRange";
+      readonly label: string;
+      /** Query-payload keys the chosen bounds are sent under as ISO instants.
+       *  Explicit rather than a `from`/`to` convention — a query is free to
+       *  name its time bounds anything, and the boot-validator checks these
+       *  keys against the handler's Zod schema. */
+      readonly params: { readonly from: string; readonly to: string };
     };
 
 export type ProjectionListScreenDefinition = {
@@ -535,7 +551,9 @@ export type ProjectionListScreenDefinition = {
   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. */
+   *  `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[];
   readonly slots?: ScreenSlots;
   readonly access?: AccessRule;
@@ -1180,8 +1198,11 @@ export type ActionFormScreenDefinition = {
   readonly handler: string;
   /** Form-Shape: Field-Map pro Name. Nutzt dieselben FieldDefinitions
    *  wie Entity-Felder. Mindestens ein Feld erforderlich (Boot-
-   *  Validator). */
-  readonly fields: Readonly<Record<string, FieldDefinition>>;
+   *  Validator).
+   *
+   *  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>>;
   /** Layout analog zu EntityEditScreen: sections mit fields aus dem
    *  fields-Map oben. */
   readonly layout: EditLayout;
@@ -1272,7 +1293,7 @@ export type SecretRevealField = {
 export type SecretMintConfirmStep = {
   /** Write-handler QN dispatched when the confirm form is submitted. */
   readonly handler: string;
-  readonly fields: Readonly<Record<string, FieldDefinition>>;
+  readonly fields: Readonly<Record<string, FormFieldDefinition>>;
   readonly layout: EditLayout;
   /** Mint success-payload fields merged into the confirm payload (e.g. a
    *  short-lived setup token). Held in component state only — never rendered,
@@ -1314,7 +1335,7 @@ export type SecretMintScreenDefinition = {
   readonly urlPrefillFields?: readonly string[];
   /** Write-handler QN dispatched on submit. */
   readonly handler: string;
-  readonly fields: Readonly<Record<string, FieldDefinition>>;
+  readonly fields: Readonly<Record<string, FormFieldDefinition>>;
   readonly layout: EditLayout;
   /** Navigate here after the reveal is confirmed. Short id (same-feature) or
    *  a fully-qualified cross-feature screen QN — no result-id navigation