@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/dist/engine/config-helpers.d.ts

@@ -0,0 +1,42 @@
+import type { ConfigBacking, ConfigBounds, ConfigComputedFn, ConfigKeyDefinition, ConfigKeyType, ConfigMask, ConfigSeedDef, ConfigValue, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions } from "./types/index.js";
+export declare function isEncryptedAtRest(def: Pick<ConfigKeyDefinition, "encrypted" | "backing">): boolean;
+export declare const access: {
+    readonly all: readonly string[];
+    readonly admin: readonly string[];
+    readonly systemAdmin: readonly string[];
+    readonly system: readonly string[];
+    readonly privileged: readonly string[];
+    readonly authenticated: readonly string[];
+    readonly anonymous: readonly string[];
+    readonly roles: (...roles: string[]) => readonly string[];
+    readonly withSystem: (roles: readonly string[]) => readonly string[];
+};
+type ConfigKeyOptions<T extends ConfigKeyType> = {
+    write?: readonly string[];
+    read?: readonly string[];
+    default?: ConfigValue<T>;
+    encrypted?: boolean;
+    piiEncrypted?: T extends "text" ? boolean : never;
+    options?: readonly string[];
+    bounds?: T extends "number" ? ConfigBounds : never;
+    pattern?: T extends "text" ? {
+        regex: string;
+        flags?: string;
+    } : never;
+    computed?: ConfigComputedFn<T>;
+    allowPerRequest?: T extends "text" ? never : boolean;
+    required?: boolean;
+    env?: string;
+    inheritedToTenant?: boolean;
+    backing?: ConfigBacking;
+    mask?: ConfigMask;
+    group?: string;
+};
+export declare function createTenantConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+export declare function createSystemConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+export declare function createUserConfig<T extends ConfigKeyType>(type: T, opts?: ConfigKeyOptions<T>): ConfigKeyDefinition<T>;
+export declare function createSeed(opts: CreateSeedOptions): ConfigSeedDef;
+export declare function createSystemSeed(opts: CreateSeedOptions): ConfigSeedDef;
+export declare function createTenantSeed(opts: CreateSeedOptions, options?: CreateTenantSeedOptions): ConfigSeedDef;
+export declare function createUserSeed(opts: CreateSeedOptions, options: CreateUserSeedOptions): ConfigSeedDef;
+export {};

package/dist/engine/config-helpers.js

@@ -0,0 +1,115 @@
+import { SYSTEM_ROLE } from "./system-user.js";
+// A key backed by "secrets" is at-rest encrypted by the secrets store itself
+// (MasterKeyProvider), even without an explicit `encrypted: true` — callers
+// that gate on encryption (boot-validator mutual-exclusion checks, config
+// query redaction) must treat the two as equivalent or a secrets-backed key
+// silently skips the encrypted-only guard.
+export function isEncryptedAtRest(def) {
+    return def.encrypted === true || def.backing === "secrets";
+}
+// --- Access Presets ---
+export const access = {
+    all: ["all"], // @cast-boundary schema-walk
+    // TenantAdmin zusätzlich: bundled-features vergeben "TenantAdmin",
+    // App-Repos historisch "Admin" — das Preset deckt beide ab, sonst
+    // driftet die writeRole-Spalte der Feature-Reference (Manifest 243/2).
+    admin: ["TenantAdmin", "Admin", "SystemAdmin"], // @cast-boundary schema-walk
+    systemAdmin: ["SystemAdmin"], // @cast-boundary schema-walk
+    system: ["system"], // @cast-boundary schema-walk
+    privileged: ["system", "SystemAdmin"], // @cast-boundary schema-walk
+    authenticated: ["User", "Admin", "SystemAdmin"], // @cast-boundary schema-walk
+    anonymous: ["anonymous"], // @cast-boundary schema-walk
+    roles: (...roles) => roles,
+    // Tenant self-service roles PLUS the system actor — for tenant-scope keys a
+    // tenant edits itself (configEdit) but that provisioning/migration/jobs must
+    // also set via ctx.systemWriteAs (roles = [SYSTEM_ROLE]). Stays human-writable
+    // because checkWriteAccess only collapses to system-only when system is the
+    // SOLE writer (humanWriters empty). Composes any preset, so apps with custom
+    // roles get the same provisioning path (issue #396).
+    withSystem: (roles) => [SYSTEM_ROLE, ...roles],
+};
+// --- Scope Defaults ---
+const SCOPE_DEFAULTS = {
+    tenant: { write: access.admin, read: access.all },
+    system: { write: access.system, read: access.admin },
+    user: { write: access.all, read: access.all },
+};
+// --- Factory ---
+function createConfigKey(scope, type, opts = {}) {
+    const defaults = SCOPE_DEFAULTS[scope];
+    return {
+        type,
+        scope,
+        access: {
+            write: opts.write ?? defaults.write,
+            read: opts.read ?? defaults.read,
+        },
+        default: opts.default,
+        ...(opts.encrypted ? { encrypted: true } : {}),
+        ...(opts.piiEncrypted ? { piiEncrypted: true } : {}),
+        ...(opts.options ? { options: opts.options } : {}),
+        bounds: opts.bounds, // @cast-boundary schema-walk
+        ...(opts.pattern ? { pattern: opts.pattern } : {}),
+        computed: opts.computed,
+        ...(opts.allowPerRequest === true ? { allowPerRequest: true } : {}),
+        ...(opts.required === true ? { required: true } : {}),
+        ...(opts.env ? { env: opts.env } : {}),
+        ...(opts.inheritedToTenant === false ? { inheritedToTenant: false } : {}),
+        ...(opts.backing === "secrets" ? { backing: "secrets" } : {}),
+        ...(opts.mask ? { mask: opts.mask } : {}),
+        ...(opts.group ? { group: opts.group } : {}),
+    };
+}
+// --- Public API ---
+// Generic on the type-tag so `r.config({keys})` can propagate it into the
+// returned `ConfigKeyHandle<T>` — that's what narrows `ctx.config(handle)`.
+// @wrapper-known semantic-alias
+export function createTenantConfig(type, opts) {
+    return createConfigKey("tenant", type, opts);
+}
+// @wrapper-known semantic-alias
+export function createSystemConfig(type, opts) {
+    return createConfigKey("system", type, opts);
+}
+// @wrapper-known semantic-alias
+export function createUserConfig(type, opts) {
+    return createConfigKey("user", type, opts);
+}
+// --- Seed Factories ---
+//
+// `key` is set to "" here — define-feature.ts fills in the qualified name
+// from the seeds-record-key during r.config() processing.
+// Scope-agnostic seed. The scope is derived from the matching keyDef in
+// define-feature.ts (via `seed.scope ?? keyDef.scope`). NOT usable for
+// user-scope keys — those need an explicit tenantId+userId, use
+// `createUserSeed` instead.
+export function createSeed(opts) {
+    return { value: opts.value, key: "" };
+}
+// System-scope seed. Always writes under SYSTEM_TENANT_ID.
+export function createSystemSeed(opts) {
+    return { value: opts.value, scope: "system", key: "" };
+}
+// Tenant-scope seed. `tenantId` omitted → fallback row under
+// SYSTEM_TENANT_ID (visible to all tenants via the resolver cascade).
+// Explicit `tenantId` → seed targets that one tenant only.
+export function createTenantSeed(opts, options) {
+    return {
+        value: opts.value,
+        scope: "tenant",
+        key: "",
+        tenantId: options?.tenantId,
+    };
+}
+// User-scope seed. Both tenantId AND userId are required — the resolver
+// matches against the user's actual tenantId, so a seed under
+// SYSTEM_TENANT_ID would never resolve.
+export function createUserSeed(opts, options) {
+    return {
+        value: opts.value,
+        scope: "user",
+        key: "",
+        tenantId: options.tenantId,
+        userId: options.userId,
+    };
+}

package/dist/engine/constants.d.ts

@@ -0,0 +1,52 @@
+import type { ConcurrencyMode } from "@cosmicdrift/kumiko-types/concurrency-mode";
+import type { ConfigScope } from "@cosmicdrift/kumiko-types/config-scope";
+import type { OnDeleteStrategy as OnDeleteStrategyType } from "@cosmicdrift/kumiko-types/relations";
+import type { TenantId } from "./types/identifiers.js";
+export declare const SystemHookNames: {
+    readonly cascadeDelete: "system:hook:cascade-delete";
+};
+export type SystemHookName = (typeof SystemHookNames)[keyof typeof SystemHookNames];
+export declare const SystemHookPriorities: {
+    readonly cascadeDelete: 500;
+};
+export declare const MessageKind: {
+    readonly write: "write";
+    readonly query: "query";
+    readonly command: "command";
+    readonly shared: "shared";
+    readonly broadcast: "broadcast";
+};
+export type MessageKind = (typeof MessageKind)[keyof typeof MessageKind];
+export declare const LifecycleHookTypes: {
+    readonly preSave: "preSave";
+    readonly postSave: "postSave";
+    readonly preDelete: "preDelete";
+    readonly postDelete: "postDelete";
+    readonly preQuery: "preQuery";
+    readonly postQuery: "postQuery";
+};
+export type LifecycleHookType = (typeof LifecycleHookTypes)[keyof typeof LifecycleHookTypes];
+export declare const ConfigScopes: {
+    readonly system: "system";
+    readonly tenant: "tenant";
+    readonly user: "user";
+};
+export type { ConfigScope };
+export declare const OnDeleteStrategies: {
+    readonly cascade: "cascade";
+    readonly restrict: "restrict";
+    readonly setNull: "setNull";
+    readonly nothing: "nothing";
+};
+export type OnDeleteStrategy = OnDeleteStrategyType;
+export declare const ConcurrencyModes: {
+    readonly parallel: "parallel";
+    readonly skip: "skip";
+    readonly replace: "replace";
+    readonly sequential: "sequential";
+    readonly debounce: "debounce";
+};
+export type { ConcurrencyMode };
+export { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
+export declare function tenantChannel(tenantId: TenantId): string;
+export declare function userAccessChannel(userId: string): string;

package/dist/engine/constants.js

@@ -0,0 +1,79 @@
+// All framework constants as `as const` objects with inferred union types.
+// No enums — only const objects + typeof inference.
+// Error codes — the canonical list lives on the KumikoError subclasses in
+// `errors/classes.ts`. Features that need to surface a feature-specific reason
+// attach it under `details.reason` on the relevant Kumiko error class.
+// --- System Hook Names ---
+export const SystemHookNames = {
+    cascadeDelete: "system:hook:cascade-delete",
+};
+// --- System Hook Priorities ---
+export const SystemHookPriorities = {
+    cascadeDelete: 500,
+};
+// --- Message Kinds ---
+export const MessageKind = {
+    write: "write",
+    query: "query",
+    command: "command",
+    shared: "shared",
+    broadcast: "broadcast",
+};
+// --- Lifecycle Hook Types ---
+export const LifecycleHookTypes = {
+    preSave: "preSave",
+    postSave: "postSave",
+    preDelete: "preDelete",
+    postDelete: "postDelete",
+    preQuery: "preQuery",
+    postQuery: "postQuery",
+};
+// --- Config Scopes ---
+// Value object satisfies the canonical ConfigScope union from kumiko-types —
+// a scope added here without a matching kumiko-types member is now a
+// compile error instead of silent drift (#1423/#1439).
+export const ConfigScopes = {
+    system: "system",
+    tenant: "tenant",
+    user: "user",
+};
+// Reverse direction: a member added only to kumiko-types' ConfigScope
+// (not to ConfigScopes above) would otherwise pass the `satisfies` check
+// above unnoticed — this line forces exhaustiveness the other way too.
+const _configScopeExhaustive = ConfigScopes;
+void _configScopeExhaustive;
+// --- On Delete Strategies ---
+export const OnDeleteStrategies = {
+    cascade: "cascade",
+    restrict: "restrict",
+    setNull: "setNull",
+    nothing: "nothing",
+};
+// --- Concurrency Modes ---
+// Value object satisfies the canonical ConcurrencyMode union from
+// kumiko-types — same drift-guard as ConfigScopes above.
+export const ConcurrencyModes = {
+    parallel: "parallel",
+    skip: "skip",
+    replace: "replace",
+    sequential: "sequential",
+    debounce: "debounce",
+};
+// Reverse-direction exhaustiveness guard — see the ConfigScope one above.
+const _concurrencyModeExhaustive = ConcurrencyModes;
+void _concurrencyModeExhaustive;
+// --- Money Currency Sources ---
+// Canonical definition lives in kumiko-types/fields (client-safe, next to
+// MoneyCurrencySource) so renderer code can import it without pulling in
+// runtime-only engine code (fw#2937). Re-exported here for server callers
+// already importing framework/engine (bundled-features/src/tenant-settings/
+// constants.ts TenantSettingsConfig.currency reuses this same constant, so
+// the two stay in sync by construction).
+export { TENANT_CURRENCY_CONFIG_KEY } from "@cosmicdrift/kumiko-types/fields";
+// --- SSE Channels ---
+export function tenantChannel(tenantId) {
+    return `tenant:${tenantId}`;
+}
+export function userAccessChannel(userId) {
+    return `user:${userId}:access`;
+}

package/dist/engine/create-app.d.ts

@@ -0,0 +1,17 @@
+import { type ValidateBootOptions } from "./boot-validator.js";
+import type { FeatureDefinition, Registry } from "./types/index.js";
+export type AppConfig = {
+    roles: readonly string[];
+    features: readonly FeatureDefinition[];
+    softDelete?: boolean;
+    currencies?: readonly string[];
+    /** Opt-in boot-validator warnings — see ValidateBootOptions. */
+    validateBootOptions?: ValidateBootOptions;
+};
+export type App = {
+    registry: Registry;
+    roles: readonly string[];
+    softDeleteDefault: boolean;
+    currencies: readonly string[];
+};
+export declare function createApp(config: AppConfig): App;

package/dist/engine/create-app.js

@@ -0,0 +1,119 @@
+import { validateBoot } from "./boot-validator.js";
+import { dedupeFeatures } from "./dedupe-features.js";
+import { createRegistry } from "./registry.js";
+import { DEFAULT_CURRENCIES } from "./types/index.js";
+// Every field map an entity-less inline form screen renders: actionForm's and
+// secretMint's own fields, plus a secretMint's separate `confirm` step.
+function inlineFormFieldMaps(screen) {
+    if (screen.type === "actionForm")
+        return [screen.fields];
+    if (screen.type !== "secretMint")
+        return [];
+    return screen.confirm !== undefined ? [screen.fields, screen.confirm.fields] : [screen.fields];
+}
+// `currency: { kind: "literal", code }` (fw#2839) is only meaningful for a
+// code the app knows — a typo would otherwise render and submit amounts in a
+// currency no formatter or rate table covers.
+function validateLiteralCurrencyCode(where, field, currencies) {
+    // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
+    const shape = field;
+    if (shape.type === "money" && shape.currency?.kind === "literal") {
+        const code = shape.currency.code;
+        if (typeof code !== "string" || !currencies.includes(code)) {
+            throw new Error(`${where} declares currency: { kind: "literal", code: ${JSON.stringify(code)} } which is ` +
+                `not in the currencies list. Available: ${currencies.join(", ")}`);
+        }
+    }
+}
+export function createApp(config) {
+    const features = dedupeFeatures(config.features);
+    const validRoles = new Set(config.roles);
+    // "system" is reserved for SYSTEM_USER — cannot be used as an app role
+    if (validRoles.has("system")) {
+        throw new Error('Role "system" is reserved for SYSTEM_USER and cannot be used as an app role');
+    }
+    // Special roles that don't need to be in the app's role list
+    const systemRoles = new Set(["all", "system"]);
+    // Validate all roles referenced by features exist in app-defined roles.
+    // openToAll access has no role list — nothing to validate there.
+    for (const feature of features) {
+        for (const handler of Object.values(feature.writeHandlers)) {
+            if (handler.access && "roles" in handler.access) {
+                for (const role of handler.access.roles) {
+                    if (!validRoles.has(role)) {
+                        throw new Error(`Unknown role "${role}" in write handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`);
+                    }
+                }
+            }
+        }
+        for (const handler of Object.values(feature.queryHandlers)) {
+            if (handler.access && "roles" in handler.access) {
+                for (const role of handler.access.roles) {
+                    if (!validRoles.has(role)) {
+                        throw new Error(`Unknown role "${role}" in query handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`);
+                    }
+                }
+            }
+        }
+        for (const handler of Object.values(feature.streamHandlers)) {
+            if (handler.access && "roles" in handler.access) {
+                for (const role of handler.access.roles) {
+                    if (!validRoles.has(role)) {
+                        throw new Error(`Unknown role "${role}" in stream handler "${handler.name}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`);
+                    }
+                }
+            }
+        }
+        for (const [key, keyDef] of Object.entries(feature.configKeys)) {
+            for (const role of [...keyDef.access.read, ...keyDef.access.write]) {
+                if (!systemRoles.has(role) && !validRoles.has(role)) {
+                    throw new Error(`Unknown role "${role}" in config key "${feature.name}.${key}" of feature "${feature.name}". Valid roles: ${config.roles.join(", ")}`);
+                }
+            }
+        }
+    }
+    const softDeleteDefault = config.softDelete ?? true;
+    // Merge default + custom currencies, deduplicate
+    const currencies = [...new Set([...DEFAULT_CURRENCIES, ...(config.currencies ?? [])])];
+    // Validate defaultCurrency on entities that have money fields
+    for (const feature of features) {
+        for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+            // A top-level money field isn't the only way an entity can hold money —
+            // an embedded-list's sub-schema (e.g. invoice lines) can carry a money
+            // cell with no top-level money field at all. Without this, that entity
+            // slips past the defaultCurrency check and its cells/totals render in
+            // the entity.defaultCurrency ?? "EUR" fallback regardless of the app's
+            // actual currency.
+            const hasMoneyField = Object.values(entity.fields).some((f) => f.type === "money" ||
+                (f.type === "embedded" && Object.values(f.schema).some((s) => s.type === "money")));
+            if (entity.defaultCurrency && !currencies.includes(entity.defaultCurrency)) {
+                throw new Error(`Entity "${entityName}" in feature "${feature.name}" has defaultCurrency "${entity.defaultCurrency}" which is not in the currencies list. Available: ${currencies.join(", ")}`);
+            }
+            if (hasMoneyField && !entity.defaultCurrency) {
+                throw new Error(`Entity "${entityName}" in feature "${feature.name}" has money fields but no defaultCurrency. Set defaultCurrency on the entity definition.`);
+            }
+            for (const [fieldName, field] of Object.entries(entity.fields)) {
+                validateLiteralCurrencyCode(`Entity "${entityName}" in feature "${feature.name}", money field "${fieldName}"`, field, currencies);
+            }
+        }
+        // A money field on an entity-less form screen names its own currency
+        // source (fw#2839) — a literal code has to be one the app actually knows,
+        // same rule the entity `defaultCurrency` check above applies.
+        for (const [screenId, screen] of Object.entries(feature.screens ?? {})) {
+            const inlineFields = inlineFormFieldMaps(screen);
+            for (const fields of inlineFields) {
+                for (const [fieldName, field] of Object.entries(fields)) {
+                    validateLiteralCurrencyCode(`Screen "${screenId}" in feature "${feature.name}", money field "${fieldName}"`, field, currencies);
+                }
+            }
+        }
+    }
+    // Run boot-time validation before creating registry
+    validateBoot(features, config.validateBootOptions);
+    return {
+        registry: createRegistry(features),
+        roles: config.roles,
+        softDeleteDefault,
+        currencies,
+    };
+}

package/dist/engine/cross-tenant.d.ts

@@ -0,0 +1,3 @@
+import { AccessDeniedError } from "../errors/index.js";
+import type { SessionUser } from "./types/index.js";
+export declare function crossTenantOverrideDenied(user: SessionUser, tenantIdOverride: string | undefined, i18nKey: string): AccessDeniedError | undefined;

package/dist/engine/cross-tenant.js

@@ -0,0 +1,18 @@
+import { AccessDeniedError } from "../errors/index.js";
+// A payload-supplied target tenant (tenantIdOverride) on a TenantAdmin-reachable
+// handler is the cross-tenant escape hatch: hasAccess passes the handler for any
+// TenantAdmin, so without a SystemAdmin gate a TenantAdmin could act on another
+// tenant. Centralizes the check the override handlers used to inline. Returns
+// the denial to `throw` (queries) or wrap in `writeFailure` (writes), or
+// undefined when allowed. The i18nKey stays per-feature so existing
+// translations keep resolving.
+export function crossTenantOverrideDenied(user, tenantIdOverride, i18nKey) {
+    if (tenantIdOverride === undefined)
+        return undefined;
+    if (user.roles.includes("SystemAdmin"))
+        return undefined;
+    return new AccessDeniedError({
+        i18nKey,
+        details: { reason: "tenant_override_requires_system_admin" },
+    });
+}

package/dist/engine/dedupe-features.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "./types/index.js";
+export declare function dedupeFeatures(features: readonly FeatureDefinition[]): FeatureDefinition[];

package/dist/engine/dedupe-features.js

@@ -0,0 +1,36 @@
+function dedupeOptionsShallowEqual(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        if (!Object.is(a[key], b[key]))
+            return false;
+    }
+    return true;
+}
+function isInterchangeable(existing, next) {
+    if (existing === next)
+        return true;
+    if (existing.dedupeOptions !== undefined && next.dedupeOptions !== undefined) {
+        return dedupeOptionsShallowEqual(existing.dedupeOptions, next.dedupeOptions);
+    }
+    return false;
+}
+// First occurrence wins: runtimes late-bind closure state (sessions' autoRevoke) on the kept instance.
+export function dedupeFeatures(features) {
+    const byName = new Map();
+    const result = [];
+    for (const feature of features) {
+        const existing = byName.get(feature.name);
+        if (existing === undefined) {
+            byName.set(feature.name, feature);
+            result.push(feature);
+            continue;
+        }
+        if (isInterchangeable(existing, feature))
+            continue;
+        if (existing.dedupeOptions !== undefined && feature.dedupeOptions !== undefined) {
+            throw new Error(`Duplicate feature: "${feature.name}" mounted twice with different options — mount it once or pass identical options`);
+        }
+        throw new Error(`Duplicate feature: "${feature.name}" mounted twice as distinct instances — mount it once`);
+    }
+    return result;
+}

package/dist/engine/define-feature.d.ts

@@ -0,0 +1,7 @@
+import type { FeatureDefinition, FeatureRegistrar } from "./types/index.js";
+export type DefineFeatureSettings = {
+    readonly dedupeOptions?: Readonly<Record<string, unknown>>;
+};
+export declare function defineFeature<const TName extends string, TExports = undefined>(name: TName, setup: (r: FeatureRegistrar<TName>) => TExports, settings?: DefineFeatureSettings): FeatureDefinition & {
+    readonly exports: TExports;
+};

package/dist/engine/define-feature.js

@@ -0,0 +1,143 @@
+import { createInitialFeatureBuilderState } from "./feature-builder-state.js";
+import { buildConfigEventsJobsMethods } from "./feature-config-events-jobs.js";
+import { buildEntityHandlerMethods } from "./feature-entity-handlers.js";
+import { buildUiExtensionsMethods } from "./feature-ui-extensions.js";
+import { unwrapArrayForm } from "./object-form.js";
+// `TExports` lets the setup callback hand back a typed object that
+// downstream features can import (e.g. `tenantFeature.exports.config`). The
+// runtime always packs whatever setup returns into `featureDef.exports` —
+// `void` returns become `undefined` and stay invisible at the call site.
+//
+// `TName` (with `const` inference) captures the literal feature-name from
+// the call-site (`defineFeature("driverOrders", ...)` → TName="driverOrders").
+// The literal threads into the FeatureRegistrar so r.defineEvent's return
+// carries `name: "driver-orders:event:foo"` as a literal — strict-mode
+// for `ctx.appendEvent({ type: eventDef.name, ... })` lights up. Apps
+// that don't care can keep the default-string and use the wrapper-based
+// strict-mode (string-literal types per call-site) like before.
+// requires/optionalRequires accept either variadic strings (hand-written
+// call sites) or a single `{ features }` object (the feature-ast renderer's
+// canonical Object-Form for Designer/AI-generated code) — see the matching
+// overloads on RequiresApi / FeatureRegistrar['optionalRequires'].
+function resolveFeatureNamesArgs(args) {
+    return unwrapArrayForm(args, "features");
+}
+export function defineFeature(name, setup, settings) {
+    const state = createInitialFeatureBuilderState();
+    const registrar = {
+        systemScope() {
+            state.isSystemScoped = true;
+        },
+        describe(text) {
+            if (state.description !== undefined) {
+                throw new Error(`[Feature ${name}] r.describe() called twice — a feature's description is declared once`);
+            }
+            if (typeof text !== "string" || text.trim().length === 0) {
+                throw new Error(`[Feature ${name}] r.describe(): text must be a non-empty string`);
+            }
+            state.description = text.trim();
+        },
+        requires: (() => {
+            const fn = (...args) => {
+                state.requires.push(...resolveFeatureNamesArgs(args));
+            };
+            fn.projection = (tableName) => {
+                state.requiredProjections.add(tableName);
+            };
+            fn.step = (stepKind) => {
+                state.requiredSteps.add(stepKind);
+            };
+            return fn;
+        })(),
+        optionalRequires(...args) {
+            state.optionalRequires.push(...resolveFeatureNamesArgs(args));
+        },
+        toggleable(options) {
+            if (state.toggleableDefault !== undefined) {
+                throw new Error(`[Feature ${name}] r.toggleable() called twice — a feature's toggleable status is declared once`);
+            }
+            state.toggleableDefault = options.default;
+        },
+        uiHints(hints) {
+            if (state.uiHints !== undefined) {
+                throw new Error(`[Feature ${name}] r.uiHints() called twice — UI hints are declared once`);
+            }
+            state.uiHints = hints;
+        },
+        ...buildEntityHandlerMethods(state, name),
+        ...buildConfigEventsJobsMethods(state, name),
+        ...buildUiExtensionsMethods(state, name),
+    };
+    const exports = setup(registrar); // @cast-boundary engine-bridge
+    return {
+        name,
+        ...(state.description !== undefined && { description: state.description }),
+        systemScope: state.isSystemScoped,
+        exports,
+        requires: state.requires,
+        optionalRequires: state.optionalRequires,
+        requiredProjections: state.requiredProjections,
+        requiredSteps: state.requiredSteps,
+        ...(state.toggleableDefault !== undefined && { toggleableDefault: state.toggleableDefault }),
+        ...(state.uiHints !== undefined && { uiHints: state.uiHints }),
+        entities: state.entities,
+        entityTables: state.entityTables,
+        relations: state.relations,
+        writeHandlers: state.writeHandlers,
+        queryHandlers: state.queryHandlers,
+        streamHandlers: state.streamHandlers,
+        translations: state.translations,
+        hooks: {
+            validation: state.validationHooks,
+            preSave: state.lifecycleHooks["preSave"] ?? {},
+            postSave: state.phasedLifecycleHooks.postSave,
+            preDelete: state.phasedLifecycleHooks.preDelete,
+            postDelete: state.phasedLifecycleHooks.postDelete,
+            preQuery: state.lifecycleHooks["preQuery"] ?? {},
+            postQuery: state.lifecycleHooks["postQuery"] ?? {},
+            // @cast-boundary engine-bridge — die Hook-Registrierung erased die
+            // per-Slot-Signaturen zu LifecycleHookFn (Union, s. Cast in
+            // addLifecycleHook); die Branches dort sind die einzigen Producer und
+            // schreiben pro Slot typrichtig.
+        },
+        entityHooks: {
+            postSave: state.entityPostSave,
+            preDelete: state.entityPreDelete,
+            postDelete: state.entityPostDelete,
+            postQuery: state.entityPostQuery,
+        },
+        searchPayloadExtensions: state.searchPayloadExtensions,
+        configKeys: state.configKeys,
+        configSeeds: state.configSeeds,
+        jobs: state.jobs,
+        notifications: state.notifications,
+        registrarExtensions: state.registrarExtensions,
+        extensionUsages: state.extensionUsages,
+        extensionSelectors: state.extensionSelectors,
+        exposedApis: state.exposedApis,
+        usedApis: state.usedApis,
+        bootChecks: state.bootChecks,
+        referenceData: state.referenceData,
+        events: state.events,
+        eventMigrations: state.eventMigrations,
+        configReads: state.configReads,
+        handlerEntityMappings: state.handlerEntityMappings,
+        metrics: state.metrics,
+        secretKeys: state.secretKeys,
+        projections: state.projections,
+        entityProjectionExtensions: state.entityProjectionExtensions,
+        multiStreamProjections: state.multiStreamProjections,
+        authClaimsHooks: state.authClaimsHooks,
+        claimKeys: state.claimKeys,
+        screens: state.screens,
+        navs: state.navs,
+        contentCollections: state.contentCollections,
+        workspaces: state.workspaces,
+        httpRoutes: state.httpRoutes,
+        webSocketRoutes: state.webSocketRoutes,
+        storeTables: state.storeTables,
+        ...(state.treeActions !== undefined && { treeActions: state.treeActions }),
+        ...(state.envSchema !== undefined && { envSchema: state.envSchema }),
+        ...(settings?.dedupeOptions !== undefined && { dedupeOptions: settings.dedupeOptions }),
+    };
+}