@cosmicdrift/kumiko-types 0.382.0 → 0.383.0

package/dist/config.d.ts

@@ -3,7 +3,7 @@ import type { ConcurrencyMode } from "./concurrency-mode.ts";
 import type { ConfigScope } from "./config-scope.ts";
 import type { DbConnection } from "./db-connection.ts";
 import type { FieldDefinition, OptionsQueryPayload } from "./fields.ts";
-import type { EscapeHatchDeclaration, JobContext } from "./handlers.ts";
+import type { EscapeHatchDeclaration, JobContext, JobDeferral } from "./handlers.ts";
 import type { PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn } from "./hooks.ts";
 import type { TenantId } from "./identifiers.ts";
 import type { NavIconKey } from "./nav-icon.ts";
@@ -139,7 +139,7 @@ export type ConfigResolver = {
 };
 export type RunIn = "api" | "worker" | "both";
 export type JobRunIn = Exclude<RunIn, "both">;
-export type JobHandlerFn = (payload: Record<string, unknown>, context: JobContext) => Promise<void>;
+export type JobHandlerFn = (payload: Record<string, unknown>, context: JobContext) => Promise<void | JobDeferral>;
 export type JobTrigger = {
     readonly on: import("./handlers.ts").NameOrRef | readonly import("./handlers.ts").NameOrRef[];
     readonly where?: Readonly<Record<string, string | number | boolean>>;
@@ -166,6 +166,7 @@ export type JobDefinition = {
     readonly concurrency?: ConcurrencyMode | undefined;
     readonly maxPerTenant?: number | MaxPerTenantOptions | undefined;
     readonly debounceMs?: number | undefined;
+    readonly maxDefers?: number | undefined;
     readonly retries?: number | undefined;
     readonly backoff?: JobBackoff | undefined;
     readonly timeout?: number | undefined;

package/dist/fields.d.ts

@@ -120,8 +120,9 @@ export type TextFieldDef = {
      *  run that already read the compromised value. See irreversible-operation-gate. */
     readonly readAsInstruction?: boolean;
     /** "password" is a pure render hint (masked input) — no storage semantics.
-     *  "month" stores `YYYY-MM`: month picker in the form, format enforced on write. */
-    readonly format?: "email" | "url" | "phone" | "password" | "month";
+     *  "month" stores `YYYY-MM`: month picker in the form, format enforced on write.
+     *  "iban" is checked on write (shape plus mod-97); the value is stored as typed. */
+    readonly format?: "email" | "url" | "phone" | "password" | "month" | "iban";
     readonly default?: string;
     readonly access?: FieldAccess;
     /** Mehrzeiliger Text — DefaultInput rendert dann ein <textarea> statt

package/dist/handlers.d.ts

@@ -377,6 +377,10 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
     readonly queryAsMember: MemberReader;
 };
+export type JobDeferral = {
+    readonly kind: "job-deferral";
+    readonly delayMs: number;
+};
 export type JobContext = SharedContextFields & {
     readonly db: TenantDb;
     readonly registry: Registry;
@@ -390,6 +394,7 @@ export type JobContext = SharedContextFields & {
     } | null;
     readonly attempt: number;
     readonly finalAttempt: boolean;
+    readonly defer: (delayMs: number) => JobDeferral;
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
     readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;

package/dist/http-route.d.ts

@@ -60,7 +60,7 @@ export type HttpRouteDefinition = {
      *  Response (sync oder async). */
     readonly handler: HttpRouteHandler;
     /** Enforced before the route's guards through the server's rate-limit
-     *  resolver (fail-closed like the global L1 limiter: a limiter outage
-     *  answers 503 instead of letting the request through). */
+     *  resolver (fail-open like the global L1 limiter: a limiter outage
+     *  lets the request through, counted and logged). */
     readonly rateLimit?: HttpRouteRateLimit;
 };

package/dist/screen.d.ts

@@ -631,12 +631,11 @@ export type MetricNavigate = {
      *  instead of navigating away. */
     readonly tab?: string;
 };
-export type MetricSpec = string | {
+export type MetricSpec = {
     readonly field: string;
-    readonly label?: string;
+    readonly label: string;
     readonly navigate?: MetricNavigate;
 };
-export declare function metricField(metric: MetricSpec): string;
 export type ProjectionDetailScreenDefinition = {
     readonly id: string;
     readonly type: "projectionDetail";
@@ -682,8 +681,7 @@ export type ProjectionDetailScreenDefinition = {
     /** Record header above the layout — title/subtitle/status name columns
      *  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` (string shorthand) or the object form's own `label`.
+    /** Metric band above the layout — column names in the query row, each with its own i18n `label`.
      *  Rendered only when set. */
     readonly metrics?: readonly MetricSpec[];
     /** Parent list screen (kurze id) für eine "Zurück"-Navigation. */
@@ -1133,7 +1131,7 @@ export type EditFieldPrefill = {
     readonly property: "displayName" | "email" | "id";
 };
 export type EditSectionSpec = EditFieldsSection | EditExtensionSection | EditRelatedListSection | EditWriteFormSection;
-export type EditFieldsSection = {
+type EditFieldsSectionBase = {
     /** Kebab-case tab id, used as the `?tab=` value. Required by the
      *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */
     readonly id?: string;
@@ -1149,17 +1147,6 @@ export type EditFieldsSection = {
      *  (subtitle-only section). */
     readonly description?: string;
     readonly columns?: number;
-    /** Mutually exclusive with `groups` — pass `[]` when using `groups`; the
-     *  boot-validator rejects both non-empty or both empty. */
-    readonly fields: readonly EditFieldSpec[];
-    /** Splits the section into multiple titled cards instead of one flat grid.
-     *  Mutually exclusive with `fields`; fields named here still need to exist. */
-    readonly groups?: readonly {
-        readonly title: string;
-        readonly fields: readonly EditFieldSpec[];
-        /** Default 2. */
-        readonly columns?: number;
-    }[];
     /** Rendered left of the section title, `text-muted-foreground` — closed
      *  IconKey vocabulary into the ICONS registry (renderer/web), analogous
      *  to EditFieldSpec.icon. No title → no icon, and no heuristic derives
@@ -1180,6 +1167,21 @@ export type EditFieldsSection = {
      *  (declared or id-derived); the boot-validator rejects one that doesn't. */
     readonly actions?: readonly RowAction[];
 };
+export type EditFieldGroup = {
+    readonly title: string;
+    readonly fields: readonly EditFieldSpec[];
+    /** Default 2. */
+    readonly columns?: number;
+};
+/** Either a flat `fields` grid or titled `groups` cards, never both: the groups branch has no
+ *  `fields` key, so a raw `.fields` read on a section does not compile — use `sectionFieldSpecs`. */
+export type EditFieldsSection = EditFieldsSectionBase & ({
+    readonly fields: readonly EditFieldSpec[];
+} | {
+    /** Splits the section into multiple titled cards instead of one flat grid; fields named
+     *  here still need to exist. */
+    readonly groups: readonly EditFieldGroup[];
+});
 export type EditExtensionSection = {
     /** Kebab-case tab id, used as the `?tab=` value. Required by the
      *  boot-validator when the enclosing `EditLayout.mode` is "tabs". */

package/dist/screen.js

@@ -1,6 +1,3 @@
-export function metricField(metric) {
-    return typeof metric === "string" ? metric : metric.field;
-}
 // Query result contract: flat record; `valueField` points at the
 // value (string is display-ready, number is locale-formatted, DashboardI18nText
 // is translated), `subField` optionally at a sub line (string | DashboardI18nText), `toneField` optionally at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.382.0",
+  "version": "0.383.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,18 @@
 [
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "MetricSpec requires the object form with a label",
+    "detail": "The plain string shorthand for projectionDetail `metrics` is removed and `label` (an i18n key) is required, so a metric can no longer render as a bare column name. `metricField()` is removed from the screen exports because it is trivial now; read `metric.field`. The `metrics` entry without label check in the Screen-Conventions guard is dropped, the type enforces it.",
+    "migration": "Replace `metrics: [\"balance\"]` with `metrics: [{ field: \"balance\", label: \"<i18n key>\" }]`, reusing the key you had in `fieldLabels` for that column. Replace `metricField(metric)` with `metric.field`."
+  },
+  {
+    "version": "0.383.0",
+    "type": "breaking",
+    "title": "EditFieldsSection is either fields or groups",
+    "detail": "EditFieldsSection is now a union of a section with `fields` and a section with `groups`; the groups branch has no `fields` key, so a raw `section.fields` read on a section does not compile and `fields: []` next to `groups` is no longer needed. The boot validator rejects a section that declares both, including `fields: []`. FieldsOrGroupsSection now has optional `fields` and `groups`. Read a section's fields through `sectionFieldSpecs`, which the Section-Fields-Raw guard used to enforce.",
+    "migration": "Remove `fields: []` from every section that declares `groups`. Code that reads `section.fields` or `section.groups` of a fields section uses `sectionFieldSpecs(section)` or narrows with `\"groups\" in section`."
+  },
   {
     "version": "0.379.0",
     "type": "breaking",