@cosmicdrift/kumiko-types 0.351.0 → 0.353.0

package/dist/agent-exposure.d.ts

@@ -1,4 +1,4 @@
-import type { AgentExposure, AgentHandlerHints } from "./handlers.js";
+import type { AgentExposure, AgentHandlerHints, AgentScreenHints } from "./handlers.js";
 /** Fail-closed: a handler without a `description` stays invisible to the agent
  *  unless it opts in explicitly. `kind` is a parameter because write and query
  *  handler definitions are structurally indistinguishable at runtime. */
@@ -11,5 +11,5 @@ export declare function resolveAgentExposure(def: {
  *  Reusing `resolveAgentExposure`'s fail-closed default here would silently
  *  drop every screen without a description from the agent's view. */
 export declare function isAgentVisibleScreen(screen: {
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
 }): boolean;

package/dist/entity-handlers.d.ts

@@ -43,6 +43,9 @@ export type RegisterEntityCrudOptions = {
      *  manifest exposes only the verbs described here (fail-closed, same rule as
      *  hand-written handlers). Falls back to `write.description`/`read.description`. */
     readonly descriptions?: Partial<Record<EntityCrudVerb, string>>;
+    /** Per-verb agent hints; win over `write.agent`/`read.agent`, so one irreversible
+     *  verb (e.g. a hard delete) can be `risk: "high"` without raising create/update. */
+    readonly agents?: Partial<Record<EntityCrudVerb, AgentHandlerHints>>;
     /** Per-verb `excludeFields` for the generic create/update handlers — see
      *  EntityWriteHandlerOptions. */
     readonly excludeFields?: Partial<Record<"create" | "update", readonly string[]>>;

package/dist/fields.d.ts

@@ -80,6 +80,9 @@ export type TextFieldDef = {
      *  the i18n label is what users see. */
     readonly description?: string;
     readonly maxLength?: number;
+    /** Lower bound enforced by the generated write schema, so short input is
+     *  rejected by validation instead of reaching the handler. */
+    readonly minLength?: number;
     readonly required?: boolean;
     readonly searchable?: boolean;
     readonly sortable?: boolean;
@@ -171,7 +174,8 @@ export type BooleanFieldDef = {
     readonly default?: boolean;
     readonly access?: FieldAccess;
 };
-export type SelectOptionTone = "ok" | "warn" | "bad" | "neutral";
+export declare const SELECT_OPTION_TONES: readonly ["ok", "warn", "bad", "neutral"];
+export type SelectOptionTone = (typeof SELECT_OPTION_TONES)[number];
 /** One `optionsQueryPayload` entry: a literal, or `{ field }` = the current value of
  *  a sibling field of the same form (config keys: another key of the owner feature). */
 export type OptionsQueryPayloadValue = string | number | boolean | {
@@ -213,6 +217,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/fields.js

@@ -1,4 +1,5 @@
 // --- Field Types ---
+export const SELECT_OPTION_TONES = ["ok", "warn", "bad", "neutral"];
 export function isOptionsQueryFieldRef(value) {
     return typeof value === "object" && value !== null;
 }

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";
@@ -404,7 +404,7 @@ export type EventDef<TPayload = unknown, TName extends string = string> = {
     readonly name: TName;
     readonly schema: ZodType<TPayload>;
     readonly version: number;
-    readonly piiFields?: EventPiiStance;
+    readonly piiFields: EventPiiStance;
 };
 export type AppendEventArgs = {
     readonly aggregateId: string;
@@ -499,18 +499,32 @@ export type AgentHandlerHints = {
     readonly expose?: boolean;
     readonly risk?: AgentRisk;
 };
+/** Screens only read `expose`; `risk` ranks handler tool calls, so it is not offered here. */
+export type AgentScreenHints = Pick<AgentHandlerHints, "expose">;
 export type AgentExposure = {
     readonly expose: boolean;
     readonly risk: AgentRisk;
 };
 /** 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/kms-adapter-types.d.ts

@@ -13,6 +13,7 @@ export type SubjectId = {
 export type SubjectKey = string;
 export declare function subjectKeyForUser(userId: string): SubjectKey;
 export declare function subjectKeyForTenant(tenantId: TenantId): SubjectKey;
+export declare const PII_ERASED_SENTINEL = "[[erased]]";
 export declare const RECORD_ENTITY_PATTERN: RegExp;
 export declare function subjectKeyForRecord(entity: string, id: string): SubjectKey;
 export declare function subjectIdToKey(subject: SubjectId): SubjectKey;

package/dist/kms-adapter-types.js

@@ -4,6 +4,9 @@ export function subjectKeyForUser(userId) {
 export function subjectKeyForTenant(tenantId) {
     return `tenant:${tenantId}`;
 }
+// Stands in for a PII value whose subject key was erased; clients map it to a
+// translated label instead of showing it.
+export const PII_ERASED_SENTINEL = "[[erased]]";
 // 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

package/dist/screen.d.ts

@@ -1,6 +1,6 @@
 import type { FieldIconKey } from "./field-icon.js";
 import type { FieldDefinition, FormFieldDefinition, SelectOptionTone } from "./fields.js";
-import type { AccessRule, AgentHandlerHints } from "./handlers.js";
+import type { AccessRule, AgentScreenHints } from "./handlers.js";
 import type { IconKey, NavIconKey } from "./nav-icon.js";
 export type { FieldIconKey } from "./field-icon.js";
 export type PlatformComponent = {
@@ -395,7 +395,7 @@ export type EntityListScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -504,7 +504,7 @@ export type ProjectionListScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -598,7 +598,7 @@ export type ProjectionDetailScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -734,7 +734,10 @@ export type DashboardStatPanel = DashboardPanelQueryOptions & DashboardPanelGate
     /** 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 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";
@@ -782,6 +785,8 @@ export type DashboardChartPanel = DashboardPanelQueryOptions & DashboardPanelEmp
     readonly legendTotals?: boolean;
     /** Only for chart "stacked-area": range switch in the panel header. */
     readonly ranges?: DashboardChartRanges;
+    /** Only for chart "stacked-area": scrubber under the plot to drag the visible window; starts at today. */
+    readonly brush?: boolean;
 };
 export type DashboardListPanel = DashboardPanelQueryOptions & DashboardPanelEmptyState & DashboardPanelGate & {
     readonly kind: "list";
@@ -796,6 +801,7 @@ export type DashboardStatGroupPanel = DashboardPanelGate & {
     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 & DashboardPanelGate & {
@@ -867,7 +873,7 @@ export type DashboardScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -1201,7 +1207,7 @@ export type EntityEditScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -1297,7 +1303,7 @@ export type ActionFormScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -1465,7 +1471,7 @@ export type SecretMintScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -1504,8 +1510,7 @@ export type CustomScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    /** Only `expose` is read for screens; `risk` ranks handler tool calls. */
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     readonly renderer: PlatformComponent;
     readonly routes?: readonly CustomScreenRoute[];
     /** Parent list screen for breadcrumb when this detail is not in nav. */
@@ -1536,7 +1541,7 @@ export type ConfigEditScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;
@@ -1586,7 +1591,7 @@ export type SecretsEditScreenDefinition = {
     readonly nav?: ScreenNavSugar;
     readonly detailFor?: string;
     readonly description?: string;
-    readonly agent?: AgentHandlerHints;
+    readonly agent?: AgentScreenHints;
     /** Screen has no nav entry by design (opened via link or navved by the
      *  app); exempts it from the nav-area boot check. */
     readonly dormant?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.351.0",
+  "version": "0.353.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,17 @@
 [
+  {
+    "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",