@cosmicdrift/kumiko-types 0.350.0 → 0.352.0

package/dist/fields.d.ts

@@ -213,6 +213,14 @@ export type SelectFieldDef<TOptions extends readonly string[] = readonly string[
     /** Payload sent with every `optionsQuery` call. `{ field }` entries re-load the
      *  options when that sibling field changes. */
     readonly optionsQueryPayload?: OptionsQueryPayload;
+    /** Marks static options as unavailable per tenant (e.g. by tier). Contract:
+     *  `{ rows: { value: string; disabled?: boolean; hint?: string }[] }`. The renderer
+     *  loads it (with `optionsQueryPayload` resolved like for `optionsQuery`, `{}` when
+     *  absent) and merges it onto `options`: `disabled` disables the option, `hint` becomes
+     *  its description. The currently stored value always stays enabled; unknown values
+     *  are ignored. Static `options` stay authoritative, and the write path must enforce
+     *  the same rule (see `withTierOptionGate`), the renderer only mirrors it. */
+    readonly optionsAvailabilityQuery?: string;
 } & ResolvedPiiFlags;
 export type MultiSelectFieldDef<TOptions extends readonly string[] = readonly string[]> = {
     readonly type: "multiSelect";

package/dist/handlers.d.ts

@@ -2,7 +2,7 @@ import type { Redis } from "ioredis";
 import type { ZodType } from "zod";
 import type { CacheSyncBus } from "./cache-sync-types.js";
 import type { ConfigAccessor, ConfigAccessorFactory, ConfigResolver } from "./config.js";
-import type { DbConnection } from "./db-connection.js";
+import type { DbConnection, DbTx } from "./db-connection.js";
 import type { DerivativesContext } from "./derivatives-types.js";
 import type { EntityCache } from "./entity-cache.js";
 import type { EventMetadata, WriteOrigin } from "./event-store-types.js";
@@ -505,12 +505,24 @@ export type AgentExposure = {
 };
 /** Undoes a reservation made before the handler transaction. */
 export type ReservationRelease = () => Promise<void>;
-/** Runs in the dispatcher after access and schema checks but before the
- *  handler transaction opens, so it must commit its own short write instead
- *  of holding a second connection while the transaction is open. The returned
- *  release runs when the transaction does not commit (failure result, throw,
- *  rollback, failed commit). Throwing a KumikoError rejects the write. */
-export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | undefined>;
+/** The dispatcher's own open handler transaction: a reservation must settle on it, not on
+ *  HandlerContext, whose db is fail-closed for r.systemScope() handlers. */
+export type ReservationConfirmContext = {
+    readonly tx: DbTx;
+    readonly tenantId: TenantId;
+};
+/** A reservation that also settles inside the handler transaction. `confirmInTransaction` runs
+ *  after the handler succeeded and before COMMIT; a throw fails the write and rolls it back. */
+export type ReservationHandle = {
+    readonly release: ReservationRelease;
+    readonly confirmInTransaction: (confirm: ReservationConfirmContext) => Promise<void>;
+};
+/** Runs in the dispatcher after every pre-handler gate (feature, rate limit, access, schema,
+ *  validation, field roles) passed but before the handler transaction opens, so it must commit
+ *  its own short write instead of holding a second connection while the transaction is open.
+ *  The returned release (or handle.release) runs when the transaction does not commit (failure
+ *  result, throw, rollback, failed commit). Throwing a KumikoError rejects the write. */
+export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
 export type WriteHandlerDef = {
     readonly name: string;
     readonly schema: ZodType;

package/dist/rate-limit-types.d.ts

@@ -1,4 +1,4 @@
-import type { Temporal } from "temporal-polyfill";
+import type { Temporal } from "./temporal.js";
 export type RateLimitDecision = {
     readonly allowed: boolean;
     readonly limit: number;

package/dist/screen.d.ts

@@ -691,6 +691,9 @@ export type DashboardPanelQueryOptions = {
      *  `timeRange` still is. */
     readonly ignoreScreenFilter?: boolean;
 };
+export type DashboardPanelGate = {
+    readonly visibleWhen?: DashboardPanelVisibility;
+};
 export type DashboardPanelSpan = "half" | "full";
 export type DashboardPanelEmptyState = {
     readonly span?: DashboardPanelSpan;
@@ -698,11 +701,11 @@ export type DashboardPanelEmptyState = {
     /** Second line under `emptyLabel`. */
     readonly emptyHint?: string;
 };
-export type DashboardStatPanel = DashboardPanelQueryOptions & {
+export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate & {
     readonly kind: "stat";
     /** Stable id: kebab-case, unique within the panel set. */
     readonly id: string;
-    /** Anzeige-Text (i18n-Key). */
+    /** Display text (i18n key). */
     readonly label: string;
     readonly query: string;
     readonly valueField: string;
@@ -715,29 +718,49 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & {
     /** Record field holding `{ atMs, value | null }[]` (MetricResult.points),
      *  drawn as a sparkline next to the value. */
     readonly sparklineField?: string;
-    /** Optionaler Delta-Chip (z.B. "↓23 %") neben dem Label. Nur wenn BEIDE
-     *  Felder gesetzt sind UND der Query-Handler sie liefert, rendert der Chip
-     *  — sonst bleibt die Kachel wie ohne Delta. `deltaToneField` fällt auf
-     *  `toneField`/"default" zurück, wenn ungesetzt. */
+    /** Delta chip (e.g. "↓23 %") next to the label. It renders only when BOTH
+     *  fields are set AND the query handler returns them; otherwise the tile
+     *  looks as it does without a delta. `deltaToneField` falls back to
+     *  `toneField`/"default" when unset. */
     readonly deltaField?: string;
     readonly deltaDirectionField?: string;
     readonly deltaToneField?: string;
-    /** Statisches Icon neben dem Label — anders als value/sub/delta variiert
-     *  das Icon nicht pro Query-Result, sondern ist eine Author-Entscheidung
-     *  wie das Panel selbst. Aufgelöst über dieselbe extensionSectionComponents-
-     *  Registry wie custom-Panels; die registrierte Komponente ignoriert
-     *  typischerweise entityName/entityId/filterParams (kein Entity-Kontext
-     *  für ein reines Icon). */
+    /** Static icon next to the label. Unlike value/sub/delta it does not vary
+     *  per query result; it is an author decision like the panel itself.
+     *  Resolved through the same extensionSectionComponents registry as custom
+     *  panels; the registered component usually ignores
+     *  entityName/entityId/filterParams (a plain icon has no entity context). */
     readonly icon?: PlatformComponent;
-    /** Statischer CSS-Farbwert (z.B. "var(--color-debt)") für den Icon-Chip —
-     *  Passthrough an die Kachel, keine Registry, kein Lookup. Wirkt NUR wenn
-     *  `icon` gesetzt ist (StatCard rendert den Chip nur zusammen mit einem
-     *  Icon) — ohne icon wird der Wert still verworfen. */
+    /** Static CSS color value (e.g. "var(--color-debt)") for the icon chip,
+     *  passed straight to the tile without a registry lookup. Applies ONLY when
+     *  `icon` is set (StatCard renders the chip only together with an icon);
+     *  without an icon the value is silently dropped. Without `accentColor` the
+     *  chip follows the tone, including a `toneField` value delivered per result.
+     *  An accent that should change with the result (e.g. by sign) goes through
+     *  `toneField`; leave `accentColor` unset then. */
     readonly accentColor?: string;
 };
 export type DashboardChartKind = "timeseries" | "stacked-bars" | "segment-bars" | "stacked-area";
 export type DashboardChartTone = "positive" | "negative" | "active" | "neutral";
-export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
+/** Look of the markers whose `kind` matches: a dashed guide line through the
+ *  plot plus a colored pin. `color` (raw CSS color) wins over `tone`. */
+export type DashboardChartMarkerKind = {
+    readonly tone?: DashboardChartTone;
+    readonly color?: string;
+};
+/** One option of a stacked-area range switch. Without `months` the option
+ *  shows every bucket; with it, a window of that many months anchored at
+ *  `todayMs` (or the last bucket). `label` is an i18n key. */
+export type DashboardChartRangeOption = {
+    readonly value: string;
+    readonly label: string;
+    readonly months?: number;
+};
+export type DashboardChartRanges = {
+    readonly options: readonly DashboardChartRangeOption[];
+    readonly default: string;
+};
+export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "chart";
     readonly id: string;
     readonly label: string;
@@ -745,34 +768,47 @@ export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmp
     readonly query: string;
     /** i18n key under the title, e.g. "7 days, by creation day". */
     readonly subtitle?: string;
-    /** Series/segment key -> tone; unmapped keys fall back to a palette. */
+    /** Series/segment/line key -> tone; unmapped keys fall back to a palette. */
     readonly seriesTones?: Readonly<Record<string, DashboardChartTone>>;
+    /** Series/segment/line key -> raw CSS color (e.g. "var(--color-debt)"); wins over `seriesTones`. */
+    readonly seriesColors?: Readonly<Record<string, string>>;
     /** Formats values as currency (minor units): y ticks, legend totals and tooltips on
      *  stacked-bars/segment-bars/stacked-area, only the y ticks on timeseries. */
     readonly valueFormat?: DashboardValueFormat;
     /** Only for chart "stacked-area": fixed width per bucket, plot scrolls horizontally. */
     readonly scrollable?: boolean;
+    /** Only for chart "stacked-area": marker `kind` -> look. Markers without a
+     *  declared kind keep the neutral numbered pin. */
+    readonly markerKinds?: Readonly<Record<string, DashboardChartMarkerKind>>;
+    /** Only for chart "stacked-area": false hides the per-series sums in the
+     *  legend (they mean nothing for balances). Default true. */
+    readonly legendTotals?: boolean;
+    /** Only for chart "stacked-area": range switch in the panel header. */
+    readonly ranges?: DashboardChartRanges;
 };
-export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
+export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "list";
     readonly id: string;
     readonly label: string;
     readonly query: string;
     readonly columns: readonly ListColumnSpec[];
 };
-export type DashboardStatGroupPanel = {
+export type DashboardStatGroupPanel = DashboardPanelGate & {
     readonly kind: "stat-group";
     readonly id: string;
     readonly label?: string;
+    /** i18n key, a line under `label`; the boot validator requires `label`. */
+    readonly subtitle?: string;
+    readonly span?: DashboardPanelSpan;
     readonly stats: readonly DashboardStatPanel[];
 };
-export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
+export type DashboardFeedPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "feed";
     readonly id: string;
     readonly label: string;
     readonly query: string;
 };
-export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & {
+export type DashboardProgressListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "progress-list";
     readonly id: string;
     readonly label: string;

package/dist/secrets-types.d.ts

@@ -8,8 +8,9 @@ export declare function createSecret<T>(value: T): Secret<T>;
 export declare function isSecret(v: unknown): v is Secret<unknown>;
 type Primitive = string | number | boolean | bigint | symbol | null | undefined;
 type SafeLeaf = Date | RegExp | Temporal.Instant | Temporal.ZonedDateTime | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.PlainYearMonth | Temporal.PlainMonthDay | Temporal.Duration | Map<unknown, unknown> | Set<unknown>;
-export type ContainsSecret<T> = [T] extends [never] ? false : unknown extends T ? false : T extends Secret<unknown> ? true : T extends Primitive ? false : T extends SafeLeaf ? false : T extends readonly (infer U)[] ? ContainsSecret<U> : T extends object ? true extends {
-    [K in keyof T]-?: ContainsSecret<T[K]>;
+type MaxSecretDepth = 8;
+export type ContainsSecret<T, Depth extends readonly unknown[] = []> = [T] extends [never] ? false : unknown extends T ? false : Depth["length"] extends MaxSecretDepth ? false : T extends Secret<unknown> ? true : T extends Primitive ? false : T extends SafeLeaf ? false : T extends readonly (infer U)[] ? ContainsSecret<U, [...Depth, unknown]> : T extends object ? true extends {
+    [K in keyof T]-?: ContainsSecret<T[K], [...Depth, unknown]>;
 }[keyof T] ? true : false : false;
 export type SecretAuditContext = {
     readonly userId: string;

package/dist/temporal.d.ts

@@ -0,0 +1,49 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+export type TemporalApi = typeof globalThis.Temporal;
+export declare const Temporal: TemporalApi;
+export declare namespace Temporal {
+    type ComparisonResult = globalThis.Temporal.ComparisonResult;
+    type RoundingMode = globalThis.Temporal.RoundingMode;
+    type AssignmentOptions = globalThis.Temporal.AssignmentOptions;
+    type DurationOptions = globalThis.Temporal.DurationOptions;
+    type ToInstantOptions = globalThis.Temporal.ToInstantOptions;
+    type OffsetDisambiguationOptions = globalThis.Temporal.OffsetDisambiguationOptions;
+    type ZonedDateTimeAssignmentOptions = globalThis.Temporal.ZonedDateTimeAssignmentOptions;
+    type ArithmeticOptions = globalThis.Temporal.ArithmeticOptions;
+    type DateUnit = globalThis.Temporal.DateUnit;
+    type TimeUnit = globalThis.Temporal.TimeUnit;
+    type DateTimeUnit = globalThis.Temporal.DateTimeUnit;
+    type ToStringPrecisionOptions = globalThis.Temporal.ToStringPrecisionOptions;
+    type ShowCalendarOption = globalThis.Temporal.ShowCalendarOption;
+    type CalendarTypeToStringOptions = globalThis.Temporal.CalendarTypeToStringOptions;
+    type ZonedDateTimeToStringOptions = globalThis.Temporal.ZonedDateTimeToStringOptions;
+    type InstantToStringOptions = globalThis.Temporal.InstantToStringOptions;
+    type TransitionDirection = globalThis.Temporal.TransitionDirection;
+    type DurationLike = globalThis.Temporal.DurationLike;
+    type DurationFormatOptions = globalThis.Temporal.DurationFormatOptions;
+    type Duration = globalThis.Temporal.Duration;
+    type Instant = globalThis.Temporal.Instant;
+    type CalendarLike = globalThis.Temporal.CalendarLike;
+    type PlainDateLike = globalThis.Temporal.PlainDateLike;
+    type PlainDate = globalThis.Temporal.PlainDate;
+    type PlainDateTimeLike = globalThis.Temporal.PlainDateTimeLike;
+    type PlainDateTime = globalThis.Temporal.PlainDateTime;
+    type PlainMonthDayLike = globalThis.Temporal.PlainMonthDayLike;
+    type PlainMonthDay = globalThis.Temporal.PlainMonthDay;
+    type PlainTimeLike = globalThis.Temporal.PlainTimeLike;
+    type PlainTime = globalThis.Temporal.PlainTime;
+    type TimeZoneLike = globalThis.Temporal.TimeZoneLike;
+    type PlainYearMonthLike = globalThis.Temporal.PlainYearMonthLike;
+    type PlainYearMonth = globalThis.Temporal.PlainYearMonth;
+    type ZonedDateTimeLike = globalThis.Temporal.ZonedDateTimeLike;
+    type ZonedDateTime = globalThis.Temporal.ZonedDateTime;
+    type DurationArithmeticOptions = globalThis.Temporal.DurationArithmeticOptions;
+    type DurationRoundTo = globalThis.Temporal.DurationRoundTo;
+    type DurationTotalOf = globalThis.Temporal.DurationTotalOf;
+    type PluralUnit<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.PluralUnit<T>;
+    type LargestUnit<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.LargestUnit<T>;
+    type SmallestUnit<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.SmallestUnit<T>;
+    type TotalUnit<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.TotalUnit<T>;
+    type DifferenceOptions<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.DifferenceOptions<T>;
+    type RoundTo<T extends globalThis.Temporal.DateTimeUnit> = globalThis.Temporal.RoundTo<T>;
+}

package/dist/temporal.js

@@ -0,0 +1,12 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import { Temporal as TemporalPolyfill } from "temporal-polyfill";
+function resolveTemporal() {
+    // System boundary: same TC39 API, only the typings differ.
+    const native = globalThis.Temporal;
+    if (native !== undefined)
+        return native;
+    const polyfill = TemporalPolyfill;
+    Object.assign(globalThis, { Temporal: polyfill });
+    return polyfill;
+}
+export const Temporal = resolveTemporal();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.350.0",
+  "version": "0.352.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>",
@@ -261,6 +261,10 @@
     "./agent-exposure": {
       "types": "./dist/agent-exposure.d.ts",
       "default": "./dist/agent-exposure.js"
+    },
+    "./temporal": {
+      "types": "./dist/temporal.d.ts",
+      "default": "./dist/temporal.js"
     }
   },
   "devDependencies": {
@@ -524,6 +528,10 @@
       "./agent-exposure": {
         "types": "./dist/agent-exposure.d.ts",
         "default": "./dist/agent-exposure.js"
+      },
+      "./temporal": {
+        "types": "./dist/temporal.d.ts",
+        "default": "./dist/temporal.js"
       }
     }
   },

package/src/changes.json

@@ -1,4 +1,30 @@
 [
+  {
+    "version": "0.352.0",
+    "type": "improvement",
+    "title": "SelectFieldDef.optionsAvailabilityQuery marks static select options as unavailable per tenant",
+    "detail": "The query returns { rows: { value, disabled?, hint? }[] }; the renderer merges it onto options and keeps the stored value enabled."
+  },
+  {
+    "version": "0.352.0",
+    "type": "breaking",
+    "title": "Apps must import Temporal from @cosmicdrift/kumiko-types/temporal instead of temporal-polyfill (affects every app since 0.351.0)",
+    "detail": "Since 0.351.0 the native globalThis.Temporal wins over the polyfill. A Temporal imported from \"temporal-polyfill\" is a second implementation, so instanceof and z.instanceof(Temporal.Instant) reject values the framework creates. This applies whether you upgrade from before 0.351.0 or are already on it.",
+    "migration": "Replace every value import from \"temporal-polyfill\" in app code and tests, e.g. `import { Temporal } from \"temporal-polyfill\"`, with `import { Temporal } from \"@cosmicdrift/kumiko-types/temporal\"`, and drop side-effect imports of \"temporal-polyfill/global\" (importing @cosmicdrift/kumiko-types/temporal already installs the global when the runtime has none). `import type` and `/// <reference types=\"temporal-polyfill/global\" />` may stay. Then run `kumiko check`; the No-Temporal-Polyfill-Import guard lists anything left. Close the step with `kumiko-upgrade --resolve <id> --reason \"<what you changed>\"`, or add `--not-applicable` when the repo never imported temporal-polyfill."
+  },
+  {
+    "version": "0.351.0",
+    "type": "fix",
+    "title": "ContainsSecret no longer fails with TS2615 on recursive types such as DashboardI18nText",
+    "detail": "ContainsSecret works on recursive types\n`ContainsSecret<T>` stops after eight levels of nesting. Query handlers whose output contains `DashboardI18nText` (which refers to itself through `i18nParams`) no longer fail to compile with TS2615. A secret nested deeper than that is still caught by the runtime leak guard."
+  },
+  {
+    "version": "0.351.0",
+    "type": "improvement",
+    "title": "New @cosmicdrift/kumiko-types/temporal export resolves one Temporal (native first, polyfill as fallback) for framework and app code",
+    "detail": "One Temporal implementation: `@cosmicdrift/kumiko-types/temporal`\nThe new export returns the native `globalThis.Temporal` when the runtime has it (Bun 1.4, current browsers) and falls back to `temporal-polyfill` otherwise, installing it on `globalThis`. Framework, bundled features and renderers import from there, so values made by the framework pass `instanceof` and `z.instanceof(Temporal.Instant)` checks in app code. `ensureTemporalPolyfill()` puts the same instance on the global. Apps should import `Temporal` from `@cosmicdrift/kumiko-types/temporal` instead of `temporal-polyfill`.",
+    "migration": "Replace imports from \"temporal-polyfill\" with \"@cosmicdrift/kumiko-types/temporal\" so app code and framework share one set of Temporal classes."
+  },
   {
     "version": "0.340.0",
     "type": "improvement",