@cosmicdrift/kumiko-framework 0.157.2 → 0.159.1

package/src/engine/boot-validator/index.ts

@@ -3,6 +3,7 @@ import { QnTypes, qualifyEntityName } from "../qualified-name";
 import type { ClaimKeyDefinition, FeatureDefinition } from "../types";
 import { validateActionWiring, validateFieldWiring } from "./action-wiring";
 import { validateApiExposureMatching, validateExtensionUsages } from "./api-ext";
+import { validateFeatureBootChecks } from "./boot-check";
 import {
   validateCircularDeps,
   validateConfigKeyAllowPerRequest,
@@ -30,12 +31,7 @@ import {
   validateTransitions,
 } from "./entity-handler";
 import { validateEntityListScreens } from "./entity-list-screens";
-import {
-  validateGdprHookCompleteness,
-  validateGdprPiiHookCoverage,
-  validateGdprStoragePersistence,
-  validateTenantDataHookCoverage,
-} from "./gdpr-storage";
+import { validateGdprStoragePersistence } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import {
   collectKnownRoles,
@@ -198,9 +194,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateEntityListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
-  validateGdprHookCompleteness(features);
-  validateGdprPiiHookCoverage(features);
-  validateTenantDataHookCoverage(features);
+  validateFeatureBootChecks(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring

package/src/engine/boot-validator/screens.ts

@@ -7,6 +7,7 @@
 import { rowMetaFieldNames } from "../../db/table-builder";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
 import type { FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
@@ -20,7 +21,6 @@ import type {
   ScreenDefinition,
   ToolbarAction,
 } from "../types/screen";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
 //

package/src/engine/define-feature.ts

@@ -136,6 +136,7 @@ export function defineFeature<const TName extends string, TExports = undefined>(
     extensionSelectors: state.extensionSelectors,
     exposedApis: state.exposedApis,
     usedApis: state.usedApis,
+    bootChecks: state.bootChecks,
     referenceData: state.referenceData,
     events: state.events,
     eventMigrations: state.eventMigrations,

package/src/engine/define-handler.ts

@@ -1,81 +1,18 @@
 import type { ZodType, z } from "zod";
 import type { ContainsSecret } from "../secrets/types";
 import { runPipeline } from "./run-pipeline";
+import type { HandlerContext, KumikoEventTypeMap, WriteEvent, WriteResult } from "./types";
 import type {
-  AccessRule,
-  HandlerContext,
-  KumikoEventTypeMap,
-  QueryEvent,
-  RateLimitOption,
-  WriteEvent,
-  WriteResult,
-} from "./types";
-import type { PipelineDef } from "./types/step";
+  QueryHandlerDefinition,
+  WriteHandlerDefinition,
+  WriteHandlerInput,
+} from "./types/define-handler";
 
-// --- Write Handler Definition ---
-//
-// TMap propagates the strict event-type-map through the handler's
-// HandlerContext. CRITICAL: TMap is declared as a generic parameter on the
-// FUNCTION (defineWriteHandler), not just on the type. Generic-functions
-// substitute TMap at the USE-site (the caller's compile context, where
-// the augmentation is visible); generic-type-aliases substitute at the
-// definition-site (framework's compile, where the augmentation isn't
-// visible) and collapse `keyof TMap` to `never`. See the spike-findings
-// memory for the empirical proof.
-//
-// Two authoring forms — `handler` (free-form) or `perform: stepsPipeline(...)`
-// (step-pipeline). A `perform` is compiled to a handler-function at
-// definition time; the dispatcher only ever sees `handler`.
-
-export type WriteHandlerDefinition<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TData = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
-  readonly handler: (
-    event: WriteEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => Promise<WriteResult<TData>>;
-  // Preserved when the author wrote a `perform` block — the original
-  // PipelineDef. Designer/AI/AST tools read this when present; the
-  // dispatcher ignores it and just calls `handler`. Absent on free-form
-  // handlers.
-  readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
-};
-
-// Author-facing input — accepts either the free-form `handler` or the
-// pipeline-form `perform`. defineWriteHandler narrows them to the
-// canonical WriteHandlerDefinition shape.
-export type WriteHandlerInput<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TData = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly unsafeSkipTransitionGuard?: boolean;
-  readonly rateLimit?: RateLimitOption;
-} & (
-  | {
-      readonly handler: (
-        event: WriteEvent<z.infer<TSchema>>,
-        context: HandlerContext<TMap>,
-      ) => Promise<WriteResult<TData>>;
-      readonly perform?: never;
-    }
-  | {
-      readonly perform: PipelineDef<z.infer<TSchema>, TData>;
-      readonly handler?: never;
-    }
-);
+export type {
+  QueryHandlerDefinition,
+  WriteHandlerDefinition,
+  WriteHandlerInput,
+} from "./types/define-handler";
 
 export function defineWriteHandler<
   const TName extends string,
@@ -160,24 +97,6 @@ export function defineWriteHandler<
   return { ...base, handler: def.handler };
 }
 
-// --- Query Handler Definition ---
-
-export type QueryHandlerDefinition<
-  TName extends string = string,
-  TSchema extends ZodType = ZodType,
-  TResult = unknown,
-  TMap extends object = KumikoEventTypeMap,
-> = {
-  readonly name: TName;
-  readonly schema: TSchema;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
-  readonly handler: (
-    query: QueryEvent<z.infer<TSchema>>,
-    context: HandlerContext<TMap>,
-  ) => Promise<TResult>;
-};
-
 export function defineQueryHandler<
   const TName extends string,
   TSchema extends ZodType,

package/src/engine/entity-handlers.ts

@@ -18,6 +18,21 @@ import type {
   QueryHandlerDef,
   WriteHandlerDef,
 } from "./types";
+import type {
+  EntityCrudRegistrar,
+  EntityCrudVerb,
+  EntityHandlerOptions,
+  EntityQueryHandlerOptions,
+  RegisterEntityCrudOptions,
+} from "./types/entity-handlers";
+
+export type {
+  EntityCrudRegistrar,
+  EntityCrudVerb,
+  EntityHandlerOptions,
+  EntityQueryHandlerOptions,
+  RegisterEntityCrudOptions,
+} from "./types/entity-handlers";
 
 // Convention-based handler factories for event-sourced aggregates.
 //
@@ -330,16 +345,6 @@ export function defineEntityQueryHandler(
 // would need a Branded-EntityDefinition with `softDelete: true` literal
 // — feasible but not yet wired; the runtime guard catches misuse.
 
-type EntityHandlerOptions = { readonly access?: AccessRule };
-type EntityQueryHandlerOptions = EntityHandlerOptions & {
-  /** Reads across every tenant instead of the caller's own — for a
-   *  SystemAdmin-only operator inspector over an otherwise tenant-scoped
-   *  entity. Scope this to the ONE handler that needs it rather than making
-   *  the whole feature r.systemScope(), which would drop tenant isolation
-   *  from every other handler the feature registers too. */
-  readonly crossTenant?: boolean;
-};
-
 // @wrapper-known semantic-alias
 export function defineEntityCreateHandler(
   entityName: string,
@@ -446,23 +451,6 @@ export function defineProjectionQueryHandler(
   };
 }
 
-type EntityCrudVerb = "create" | "update" | "delete" | "restore" | "list" | "detail";
-
-export type RegisterEntityCrudOptions = {
-  readonly write?: EntityHandlerOptions;
-  readonly read?: EntityQueryHandlerOptions;
-  readonly verbs?: Partial<Record<EntityCrudVerb, boolean>>;
-  /** Default true. Set false when the entity was already registered (e.g. before r.relation). */
-  readonly registerEntity?: boolean;
-};
-
-/** Minimal registrar surface — keeps entity-handlers free of define-feature imports. */
-export type EntityCrudRegistrar = {
-  entity(name: string, definition: EntityDefinition): unknown;
-  writeHandler(def: WriteHandlerDef): unknown;
-  queryHandler(def: QueryHandlerDef): unknown;
-};
-
 function defaultCrudVerbs(entity: EntityDefinition): Record<EntityCrudVerb, boolean> {
   return {
     create: true,

package/src/engine/feature-builder-state.ts

@@ -2,6 +2,7 @@ import type { ZodType, z } from "zod";
 import { LifecycleHookTypes } from "./constants";
 import type {
   AuthClaimsFn,
+  BootCheckFn,
   ClaimKeyDefinition,
   ConfigKeyDefinition,
   ConfigSeedDef,
@@ -79,6 +80,7 @@ export type FeatureBuilderState = {
   extensionSelectors: ExtensionSelectorDef[];
   exposedApis: Set<string>;
   usedApis: Set<string>;
+  bootChecks: BootCheckFn[];
   referenceData: ReferenceDataDef[];
   handlerEntityMappings: Record<string, string>;
   metrics: Record<string, FeatureMetricDef>;
@@ -137,6 +139,7 @@ export function createInitialFeatureBuilderState(): FeatureBuilderState {
     extensionSelectors: [],
     exposedApis: new Set(),
     usedApis: new Set(),
+    bootChecks: [],
     referenceData: [],
     handlerEntityMappings: {},
     metrics: {},

package/src/engine/feature-config-events-jobs.ts

@@ -1,5 +1,6 @@
 import { ZodObject, type ZodType, type z } from "zod";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { resolveName } from "./handler-helpers";
 import { splitNamedDefinition, unwrapArrayForm } from "./object-form";
 import { QnTypes, qn, toKebab } from "./qualified-name";
 import type {
@@ -26,7 +27,6 @@ import type {
   SecretOptions,
   TranslationsDef,
 } from "./types";
-import { resolveName } from "./types/handlers";
 
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.
 export function buildConfigEventsJobsMethods<TName extends string>(

package/src/engine/feature-entity-handlers.ts

@@ -4,6 +4,7 @@ import type { QueryHandlerDefinition, WriteHandlerDefinition } from "./define-ha
 import type { RegisterEntityCrudOptions } from "./entity-handlers";
 import { registerEntityCrud } from "./entity-handlers";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { resolveName } from "./handler-helpers";
 import { splitNamedDefinition } from "./object-form";
 import type {
   AccessRule,
@@ -16,7 +17,6 @@ import type {
   RelationDefinition,
   WriteHandlerFn,
 } from "./types";
-import { resolveName } from "./types/handlers";
 import type { PipelineDef } from "./types/step";
 
 const CRUD_VERBS = new Set(["create", "update", "delete"]);

package/src/engine/feature-ui-extensions.ts

@@ -1,8 +1,10 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
 import { LifecycleHookTypes } from "./constants";
 import type { FeatureBuilderState } from "./feature-builder-state";
+import { resolveName } from "./handler-helpers";
 import { isKebabSegment, toKebab } from "./qualified-name";
 import type {
+  BootCheckFn,
   EntityProjectionExtension,
   HookPhase,
   LifecycleHookFn,
@@ -22,7 +24,6 @@ import type {
   ValidationHookFn,
 } from "./types";
 import { HookPhases } from "./types";
-import { resolveName } from "./types/handlers";
 import type { HttpRouteDefinition } from "./types/http-route";
 import type { NavDefinition } from "./types/nav";
 import type { ScreenDefinition } from "./types/screen";
@@ -255,6 +256,9 @@ export function buildUiExtensionsMethods<TName extends string>(
     usesApi(apiName: string): void {
       state.usedApis.add(apiName);
     },
+    bootCheck(fn: BootCheckFn): void {
+      state.bootChecks.push(fn);
+    },
     projection(definition: ProjectionDefinition): void {
       // Reject names that would blow up at registry-boot when we qualify them.
       // Catch it at the registration site so the stack trace points at the

package/src/engine/field-helpers.ts

@@ -0,0 +1,31 @@
+import type { AnyFileFieldDef, FieldDefinition } from "./types/fields";
+
+// --- Currency ---
+
+export const DEFAULT_CURRENCIES = [
+  "EUR",
+  "USD",
+  "GBP",
+  "CHF",
+  "JPY",
+  "SEK",
+  "NOK",
+  "DKK",
+  "PLN",
+  "CZK",
+  "CAD",
+  "AUD",
+  "NZD",
+  "CNY",
+  "INR",
+] as const;
+
+export function isFileField(field: FieldDefinition | undefined): field is AnyFileFieldDef {
+  if (!field) return false;
+  return (
+    field.type === "file" ||
+    field.type === "image" ||
+    field.type === "files" ||
+    field.type === "images"
+  );
+}

package/src/engine/handler-helpers.ts

@@ -0,0 +1,26 @@
+import type { NameOrRef, WriteResult } from "./types/handlers";
+
+/**
+ * Override the success-side `data` of a WriteResult while forwarding the
+ * failure half untouched. Useful for handlers that delegate to the
+ * event-store executor (which returns a SaveContext / DeleteContext
+ * envelope) but want to keep their own response shape — caller contract
+ * stays flat instead of leaking the executor's internals.
+ *
+ * ```ts
+ * const result = await executor.delete({ id }, user, db);
+ * return withResponseData(result, { userId, tenantId });
+ * ```
+ *
+ * On failure the same WriteFailure instance is returned — the error
+ * object round-trips without any wrapping, so the dispatcher / HTTP layer
+ * still read the original error code + httpStatus + i18nKey.
+ */
+export function withResponseData<T>(result: WriteResult<unknown>, data: T): WriteResult<T> {
+  if (!result.isSuccess) return result;
+  return { isSuccess: true, data };
+}
+
+export function resolveName(ref: NameOrRef): string {
+  return typeof ref === "string" ? ref : ref.name;
+}

package/src/engine/hook-helpers.ts

@@ -0,0 +1,14 @@
+// --- Hook Phases ---
+//
+// inTransaction: Hook runs inside the DB transaction. Failures roll back
+//   the entire write. Use for: DB-based side-effects (counter updates,
+//   dependent entity writes).
+//
+// afterCommit (default): Hook runs after the transaction commits. Failures
+//   are logged but don't affect the write. Use for: external systems
+//   (SSE broadcast, search index, email, webhooks).
+
+export const HookPhases = {
+  inTransaction: "inTransaction",
+  afterCommit: "afterCommit",
+} as const;

package/src/engine/index.ts

@@ -177,6 +177,7 @@ export {
   checkWriteFieldRoles,
   filterReadFields,
 } from "./field-access";
+export { resolveName, withResponseData } from "./handler-helpers";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/
 // stripForbiddenMembershipRoles/buildSessionRoles are Public API for host
 // apps that build their own membership handlers. FORBIDDEN_MEMBERSHIP_ROLES
@@ -203,6 +204,7 @@ export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
 export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen-helpers";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {
@@ -385,9 +387,7 @@ export type {
   WriteResult,
 } from "./types";
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
-export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
-export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./types/screen";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/ownership.ts

@@ -20,64 +20,28 @@
 import { toSnakeCase } from "../db/table-builder";
 import type { SessionUser } from "./types";
 
-// Parameterised SQL fragment — produced by buildOwnershipClause + by the
-// WhereRule escape-hatch. Caller weaves `sqlText` into a larger statement,
-// renumbering placeholders if needed (FragmentBuilder below).
-export type SqlFragment = {
-  readonly sqlText: string;
-  readonly params: readonly unknown[];
-};
-
-// Reference spec supported by `from()`:
-//   "user:id"                  → user.id
-//   "user:tenantId"            → user.tenantId (rarely needed — TenantDb scopes anyway)
-//   "claim:<featureName>:<key>" → user.claims["<featureName>:<key>"]
-//
-// The string form is keyed so the framework can look up the referenced
-// Registry entry at boot (Claim-QN exists? Column type compatible?). A typed
-// object form would force features to import each other's handles — the
-// whole point of H.2's unified path is string-based references, no imports.
-export type OwnershipRef = string;
-
-// Resolved during `from()` — the parser eagerly splits the prefix so the
-// runtime evaluator avoids string-parsing on every row. `kind` drives the
-// evaluator branch; the rest is the resolved metadata.
-export type FromRuleKind = "user" | "claim";
-
-export type FromRule = {
-  readonly kind: "from";
-  readonly refKind: FromRuleKind;
-  // For "user:id" → "id"; for "user:tenantId" → "tenantId".
-  // For "claim:<featureName>:<key>" → "<featureName>:<key>" (the full QN,
-  // which is exactly the key under which the JWT stores the value).
-  readonly refPath: string;
-  // Row-column to match against. For claim rules defaults to the claim's
-  // shortName (second segment of the claim QN). For user-rules the column
-  // is always explicit.
-  readonly column: string;
-};
-
-// Context passed to a WhereRule escape-hatch. The author returns a SqlFragment
-// whose placeholders start at `paramStart` ($N, $N+1, ...); the framework
-// concatenates the fragment into the larger query.
-export type WhereRuleContext<TTable = unknown> = {
-  readonly table: TTable;
-  readonly tableName: string;
-  readonly paramStart: number;
-};
-
-export type WhereRule<TTable = unknown> = {
-  readonly kind: "where";
-  readonly where: (user: SessionUser, ctx: WhereRuleContext<TTable>) => SqlFragment;
-};
-
-// "all" collapses to a primitive so map authors can write `Admin: "all"`
-// without importing a helper.
-export type OwnershipRule = "all" | FromRule | WhereRule;
-
-// Per-role map: every key is a role name, value is the rule that role
-// satisfies to pass the access check.
-export type OwnershipMap = Readonly<Record<string, OwnershipRule>>;
+// Types live in engine/types/ownership.ts (no runtime dependency); re-exported
+// here for backwards compatibility with existing importers of this file.
+export type {
+  FromRule,
+  FromRuleKind,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+  WhereRule,
+  WhereRuleContext,
+} from "./types/ownership";
+
+import type {
+  FromRule,
+  OwnershipClause,
+  OwnershipMap,
+  OwnershipRef,
+  OwnershipRule,
+  SqlFragment,
+} from "./types/ownership";
 
 // Parse an OwnershipRef into kind + resolved path + default column.
 // Throws on malformed input so the error surfaces at `from()`-call-site (in
@@ -254,24 +218,6 @@ export function userCanCreateFieldRow(
   return false;
 }
 
-// Result of buildOwnershipClause. The discriminant lets the caller handle
-// the three outcomes without inspecting SQL internals:
-//
-//   "pass"  → user is unrestricted. Run the query as-is.
-//   "empty" → user has a role mapped but no rule accepts any row (missing
-//             claim, empty array, role not in map). Skip the DB call entirely
-//             — returning [] is equivalent and avoids a pointless roundtrip.
-//   "sql"   → apply the parameterised fragment as an AND on the query.
-//             Caller is responsible for renumbering placeholders when
-//             concatenating with other fragments (see `shiftParams` below).
-//
-// "empty" vs. "pass" is the critical distinction for a safe default:
-// undefined/pass = allow, empty = deny-by-construction.
-export type OwnershipClause =
-  | { readonly kind: "pass" }
-  | { readonly kind: "empty" }
-  | { readonly kind: "sql"; readonly sqlText: string; readonly params: readonly unknown[] };
-
 const PASS_CLAUSE: OwnershipClause = { kind: "pass" };
 const EMPTY_CLAUSE: OwnershipClause = { kind: "empty" };
 

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { resolveName } from "./handler-helpers";
 import type { RegistryState } from "./registry-state";
 import { buildImplicitProjection, hasFieldAccessRules, qualify } from "./registry-state";
 import {
@@ -11,7 +12,6 @@ import {
 } from "./soft-delete-cleanup";
 import type { EventPiiFields, EventUpcastFn, FeatureDefinition } from "./types";
 import { HookPhases } from "./types";
-import { resolveName } from "./types/handlers";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
   return new Set([...state.writeHandlerMap.keys(), ...state.queryHandlerMap.keys()]);

package/src/engine/screen-helpers.ts

@@ -0,0 +1,54 @@
+import type {
+  EditExtensionSection,
+  EditFieldSpec,
+  EditSectionSpec,
+  FieldCondition,
+  FormatSpec,
+  ListColumnSpec,
+} from "./types/screen";
+
+export function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection {
+  return section.kind === "extension";
+}
+
+// Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
+// authors who branch on the three FieldRenderer variants without manual
+// "format" in renderer checks.
+export function isFormatSpec(r: unknown): r is FormatSpec {
+  return typeof r === "object" && r !== null && "format" in r && typeof r.format === "string";
+}
+
+// Collapse the string-shorthand into the object form. Both the boot-validator
+// and (later) ui-core's view-model builder iterate over fields/columns — the
+// helper keeps that loop from growing two branches everywhere.
+export function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec, string> {
+  const col = typeof c === "string" ? { field: c } : c;
+  if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV !== "production" &&
+    col.renderer !== undefined &&
+    typeof col.renderer === "function"
+  ) {
+    // biome-ignore lint/suspicious/noConsole: dev-only warning
+    console.warn(
+      `[kumiko] normalizeListColumn: Feld "${col.field}" hat einen Funktions-Renderer — dieser wird von JSON.stringify verworfen. Bitte auf FormatSpec ({ format: "..." }) migrieren.`,
+    );
+  }
+  return col;
+}
+
+/** Evaluates a declarative FieldCondition against the current row/form
+ *  values. THE single implementation — renderer (row-action visibility),
+ *  headless view-model (visible/readOnly/required) and render-edit
+ *  (form-condition closures) reuse it; three hand-rolled copies had
+ *  already drifted in shape. */
+export function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean {
+  if (typeof cond === "boolean") return cond;
+  const val = values[cond.field];
+  if ("eq" in cond) return val === cond.eq;
+  return val !== cond.ne;
+}
+
+export function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string> {
+  return typeof f === "string" ? { field: f } : f;
+}

package/src/engine/tier-resolver-extension.ts

@@ -48,8 +48,9 @@ export type EffectiveFeaturesResolver = ((tenantId: TenantId) => ReadonlySet<str
    * Signup-Datum des Tenants live (tenant.inserted_at) und returnt true wenn
    * der Tenant im Trial-Fenster ist UND das Feature zum Trial-Tier gehört.
    * Async + nicht im Boot-Cache, weil der Trial zeit-abgeleitet ist (ändert
-   * sich zwischen Requests). Nur die 2 Gate-Aufrufstellen awaiten ihn; der
-   * synchrone Hot-Path (ctx.hasFeature, Feature-Set) bleibt unberührt.
+   * sich zwischen Requests). Konsultiert an 3 Stellen: den 2 Dispatch-Gate-
+   * Aufrufstellen (checkFeatureEnabled) UND ctx.hasFeature im Handler-Body
+   * (fällt darauf zurück, wenn der synchrone Feature-Set-Check negativ ist).
    */
   readonly trialGate?: TrialGate;
 };