@cosmicdrift/kumiko-types 0.253.0 → 0.255.0

package/package.json

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

@@ -582,10 +582,11 @@ export type FeatureRegistrar<TFeature extends string = string> = {
   //
   // `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.
+  // owning subject via `{ personal: { of: "<ownerField>" } }` (the older
+  // `{ subjectField: "<ownerField>" }` form still works) 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>,

package/src/handlers.ts

@@ -732,10 +732,38 @@ export type QualifiedEventName<
 > = `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`;
 
 // PII payload fields on a custom event (#799): `field` is encrypted under
-// the DEK of the user named by the payload's `subjectField` (crypto-
-// shredding). A null subject field leaves the value plaintext — there is
-// no user key to shred for system-triggered events.
-export type EventPiiFields = Readonly<Record<string, { readonly subjectField: string }>>;
+// 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.
+//
+// `{ personal: { of: "<ownerField>" } }` is the canonical user-subject form,
+// matching the entity-field `personal` vocabulary (see fields.ts).
+// `personal: "tenant"` and `personal: "self"` declare the event's tenant
+// (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 step 2).
+export type EventPiiSubject =
+  | { readonly personal: { readonly of: string } }
+  | { readonly personal: "tenant" }
+  | { readonly personal: "self" }
+  | {
+      /** @deprecated use `{ personal: { of: "<ownerField>" } }` instead. */
+      readonly subjectField: string;
+    };
+
+export type EventPiiFields = Readonly<Record<string, EventPiiSubject>>;
+
+export type NormalizedEventPiiSubject =
+  | { readonly kind: "user"; readonly ownerField: string }
+  | { readonly kind: "tenant" }
+  | { readonly kind: "self" };
+
+export function normalizeEventPiiSubject(spec: EventPiiSubject): NormalizedEventPiiSubject {
+  if ("subjectField" in spec) return { kind: "user", ownerField: spec.subjectField };
+  if (spec.personal === "tenant") return { kind: "tenant" };
+  if (spec.personal === "self") return { kind: "self" };
+  return { kind: "user", ownerField: spec.personal.of };
+}
 
 // The full set of PII stances a defineEvent() call may declare. "none" is a
 // distinct value from `{}` — an empty object is indistinguishable from "the

package/src/kms-adapter-types.ts

@@ -20,10 +20,18 @@ export function subjectKeyForTenant(tenantId: TenantId): SubjectKey {
   return `tenant:${tenantId}`;
 }
 
+// Registry entity names are identifier-shaped; a free-form aggregate_type
+// (events-schema.ts is a plain text column) could otherwise mint a record
+// key that subjectIdSchema (forget-subject.write.ts) later refuses to
+// shred — enforced once here so minting and shredding can never disagree.
+export const RECORD_ENTITY_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
 export function subjectKeyForRecord(entity: string, id: string): SubjectKey {
-  // The key is parsed back on exactly one ":" — an entity containing ":" would break the round-trip.
-  if (entity === "" || entity.includes(":"))
-    throw new Error(`Invalid record entity for subject key: ${entity}`);
+  if (!RECORD_ENTITY_PATTERN.test(entity)) {
+    throw new Error(
+      `Invalid record entity for subject key: "${entity}" — must match ${RECORD_ENTITY_PATTERN}`,
+    );
+  }
   if (id === "") throw new Error("Invalid record id for subject key: empty");
   return `record:${entity}:${id}`;
 }

package/src/screen.ts

@@ -517,8 +517,36 @@ export type RecordHeaderSpec = {
   readonly title: string;
   readonly subtitle?: string;
   readonly status?: string;
+  /** Record field holding an absolute http(s) URL. When present and the
+   *  field's value is such a URL, the subtitle renders as an external link
+   *  (`target="_blank"`) instead of plain text. */
+  readonly subtitleHref?: string;
 };
 
+// Same shape as `RowActionNavigate`'s screen/entity choice, minus the fields
+// a metric click has no use for (id, confirm, style).
+export type MetricNavigate = {
+  readonly screen?: string;
+  readonly entity?: string;
+  readonly entityId?: string;
+  readonly params?: RowFieldExtractor;
+};
+
+// A metric can navigate on click, so the plain string shorthand (field name,
+// same as before) sits alongside an object form carrying an explicit i18n
+// `label` and a `navigate` target.
+export type MetricSpec =
+  | string
+  | {
+      readonly field: string;
+      readonly label?: string;
+      readonly navigate?: MetricNavigate;
+    };
+
+export function metricField(metric: MetricSpec): string {
+  return typeof metric === "string" ? metric : metric.field;
+}
+
 export type ProjectionDetailScreenDefinition = {
   readonly id: string;
   readonly type: "projectionDetail";
@@ -551,8 +579,9 @@ export type ProjectionDetailScreenDefinition = {
    *  in the query row (not literals). Rendered only when set. */
   readonly header?: RecordHeaderSpec;
   /** Metric band above the layout — column names in the query row, labeled
-   *  via `fieldLabels`. Rendered only when set. */
-  readonly metrics?: readonly string[];
+   *  via `fieldLabels` (string shorthand) or the object form's own `label`.
+   *  Rendered only when set. */
+  readonly metrics?: readonly MetricSpec[];
   /** Parent list screen (kurze id) für eine "Zurück"-Navigation. */
   readonly listScreenId?: string;
   readonly slots?: ScreenSlots;
@@ -790,6 +819,11 @@ export type EditFieldsSection = {
    *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
    *  one from the title (titles are free i18n strings). */
   readonly icon?: IconKey;
+  /** Record field rendered as a count badge in the tab label when the
+   *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+   *  Ignored outside tabs mode or when the field's value is not a finite
+   *  number. */
+  readonly countField?: string;
 };
 
 export type EditExtensionSection = {
@@ -811,6 +845,11 @@ export type EditExtensionSection = {
    *  like NotesSection filters/writes against the right domain entity. Takes
    *  precedence over the host value on every screen type. */
   readonly entityName?: string;
+  /** Record field rendered as a count badge in the tab label when the
+   *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+   *  Ignored outside tabs mode or when the field's value is not a finite
+   *  number. */
+  readonly countField?: string;
 };
 
 // Read-only list of related records, driven by its own query — for a
@@ -860,6 +899,11 @@ export type EditRelatedListSection = {
    *  writeHandler action re-runs this section's own query, same as a
    *  projectionList row action re-running its list query. */
   readonly rowActions?: readonly RowAction[];
+  /** Record field rendered as a count badge in the tab label when the
+   *  enclosing `EditLayout.mode` is "tabs" (e.g. an open-items counter).
+   *  Ignored outside tabs mode or when the field's value is not a finite
+   *  number. */
+  readonly countField?: string;
 };
 
 // A declarative, self-persisting form section for `projectionDetail`