@cosmicdrift/kumiko-types 0.289.0 → 0.291.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.289.0",
+  "version": "0.291.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.290.0",
+    "type": "improvement",
+    "title": "EventMetadata: feature + handler + UNATTRIBUTED_ORIGIN",
+    "detail": "EventMetadata traegt zwei neue optionale Felder (feature, handler) und exportiert die Sentinel-Konstante UNATTRIBUTED_ORIGIN fuer Appends ausserhalb eines attribuierten Ausfuehrungsscopes. Additiv, bestehende Zeilen bleiben ohne Backfill lesbar."
+  },
   {
     "version": "0.289.0",
     "type": "improvement",

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/event-store-types.ts

@@ -37,8 +37,21 @@ export type EventMetadata = {
   // app reads them when filtering/auditing. Keep values JSON-primitive
   // (string|number|boolean) so JSON serialization stays bulletproof.
   readonly headers?: Readonly<Record<string, string | number | boolean>>;
+  // Feature that owned the execution scope which wrote this event, and the
+  // qualified name of the handler/consumer/job inside it. Derived in
+  // event-store.append() from the ambient request scope, never passed in by
+  // the writer — attribution handed over can lie, attribution derived cannot.
+  // Optional so rows written before #3043 stay readable without a backfill;
+  // every new row carries both, falling back to UNATTRIBUTED_ORIGIN.
+  readonly feature?: string;
+  readonly handler?: string;
 };
 
+// Stamped when an append runs outside any attributed scope (seed scripts,
+// tests, direct event-store use). A distinct value, not an omission —
+// omitted would be indistinguishable from a pre-#3043 row.
+export const UNATTRIBUTED_ORIGIN = "unknown";
+
 // Generic over the payload shape. Default = Record<string, unknown> keeps
 // all existing consumers backwards-compatible; annotate `StoredEvent<MyEventPayload>`
 // where a typed payload read is needed.

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/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";
 
@@ -1180,8 +1180,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 +1275,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 +1317,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